Getting started
Sections
Help

Layout components

From Snowfire Wiki

Jump to: navigation, search


Components are parts of the page that should be editable inside Snowfire Live edit.

Contents

Basics

Below is the syntax for a component.

<!-- Example component -->
{ com_componentname ( parameter:'value' ) }
 
<!-- Example component with two parameters -->
{ com_anothercomponent ( parameter1:'true', parameter2:'59' ) }
 
<!-- Component syntax can span multiple lines -->
{ com_thirdcomponent (
    parameter1: 'some text',
    parameter2: 'false',
    parameter3: 99
) }

Note that a parameter value must always be wrapped by single-quotes.

Parameters that are not recognized, are treated as HTML attributes. Each component needs to have a unique numeric id parameter. This makes it possible to edit the layout file when it is being used. The description parameter will be displayed until the user changes it's value.

HTML attributes

To set a HTML attribute on a HTML element generated by a component, use component parameters.

Example

{ com_singlerow ( id:'1', description:'text', style:'background:red' ) }

Output

<span style="background:red"></span>

Single row

Use to make a single row editable, recommended for headlines. Officially supports sync.

{ com_singlerow ( id:'1', description:'Add headline', value:'{ var_pageName }' ) }

Parameters

  • htmlElement - A singlerow must be wrapped inside an HTML element. If you don't provide this option, Live edit will wrap a <span> around the content. This tag will only exist inside Live edit.
  • recommendedMaxLength
  • removeHtmlElement - Output just the raw text, without a wrapping html element
  • capitalizeFirst - Convert the first letter to upper case and the other to lower case.
  • value - Set a default value for the component. Can be used with layout variables, see above example.

WYSIWYG (Formatable text)

Use to add larger block of content. Officially supports sync.

{ com_wysiwyg ( id:'1', description:'Add text' ) }

Parameters

  • recommendedMaxLength - Defaults to nothing.
  • enableH1 - Boolean, defaults to false.
  • enableLists - Boolean, defaults to false.
  • disableHeadings - Boolean, defaults to false.
  • stripTags - Array, defaults to nothing.
  • customBlockformats - Array, defaults to nothing. Every item can either be a single HTML element, or a combination of element title and HTML element joined by a pipe. Example: 'code,Pre formated text|pre'
  • value - Set a default value for the component. Can be used with layout variables.

Image

Use to add images. When linkable is used, it is possible to add HTML attributes to the <a> tag by prefixing them with "a-", e.g. "a-rel". All parameters are optional. Officially supports sync.

{ com_image ( 
    id:          '1', 
    description: 'My image', 
    maxHeight:   '50', 
    linkable:    'true',
    a-rel:       'rel value on a'
) }

Parameters

  • maxWidth
  • maxHeight
  • linkable - boolean.
  • crop - boolean.
  • altAsLinkTitle - boolean.
  • linkClass - class on <a> tag. Deprecated, use a-class instead.
  • canHaveEmptyLink - By default the <a> tag is stripped out if no link was selected by the user.
  • enableVideo - boolean.
  • autoLinkToFile - boolean. Will automatically link the image to the original image file. *Requires linkable:'true'*
  • placeholderHeight - Specific width/height for the place holder image
  • placeholderWidth - Specific width/height for the place holder image

Link

Makes a link.

{ com_link ( id:'1', description:'Add link' ) }
  • linkText - Specify a text that cannot be changed by the user.

Menu

Displays a menu from the menu module. All parameters are optional.

{ com_menu ( 
    id:'1',
    description:'Menu',
    itemHtml:'<li><a href="%link%" %class% id="menu-%nameSanitized%">%name%</a></li>' 
) }

Parameters

  • menuId - The ID of the menu. The component is not changeable from Live edit if this is specified.
  • parentId - Parent menu ID. Defaults to 0.
  • activeClass - HTML class of active elements. Defaults to active. %classValue% or %class% must be set.
  • firstClass - HTML class of first element. Defaults to nothing. %classValue% or %class% must be set.
  • lastClass - HTML class of last element. Defaults to nothing. %classValue% or %class% must be set.
  • hasChildrenClass - HTML class whether the item has children. Defaults to nothing. %classValue% or %class% must be set.
  • htmlElement - Specifies what html element should be used. Defaults to ul.
  • reverse - If the item order should be reversed. Defaults to false.
  • between - Html to insert between every item.
  • childrenLevels - How many levels (generations?) of children to display. Defaults to 0. Note: This must be set to something greater than 0 for child items to be displayed.
  • child* - To change options on children, prepend child to any option except menuId, parentId, childrenLevels, useRootParentPageChildren, noCreateButton and activeByPageStructure. For example, to set itemHtml, use childItemHtml.
  • useRootParentPageChildren - This will automatically create a menu from the root parent's children pages. Defaults to false.
  • noCreateButton - boolean. Set if no "Create new..." link in the menu is wanted.
  • activeByPageStructure - boolean. Instead of using menu structure to detect what item is active, use page structure.
  • itemHtml - HTML markup for an item. Defaults to <li><a %class% href="%link%">%name%</a></li>


Variables available in itemHtml

  • %link% - Url
  • %class% - class="class1 class2". You must use either this or %classValue% for Live edit to work properly.
  • %name% - Link title
  • %nameSanitized% - Sanitized title
  • %classValue% - class1 class2. You must use either this or %class% for Live edit to work properly.

Example with subpages

{ com_menu (
	id: '1',
	description: 'Main menu',
	syncId: '1',
	childrenLevels:'3',
	hasChildrenClass:'has-children',
	childHasChildrenClass:'has-children',
	itemHtml:'<li %class%><a href="%link%">%name%</a></li>',
	childItemHtml:'<li %class%><a href="%link%">%name%</a></li>'
) }

This creates an <ul> menu with at most three levels of subpages. The example below is taken where home/subpage was the current page.

<ul>
	<li class="activeRoot has-children">
		<a href="./">Home</a>
		<ul>
			<li class="active activeRoot"><a href="home/subpage">Subpage</a></li>
		</ul>
	</li>
	<li ><a href="contact-us">Contact us</a></li>
</ul>

Form

Displays a form from the form application.

{ com_form ( id:'1', description:'Include a form' ) }
  • disableHeading - Removes the H1 heading
  • placeholder - What to display in Live edit when no form is selected. Values are default and description.

Keys

Keys are made for doing things such as blogs where you need to automatically link pages to a list. Keys are set on components with the parameter key. A key could be thought of as a name for that component.

In com_keys, either the user selects some pages, or they are set for them with parameters. From these pages keys are extracted, and used to present some form of list. This could be used to pull a headline (singlerow) and the lead paragraph (wysiwyg) to a blog post list.

Bloglist.tpl

This would be the page to where all blog posts are pulled. The html parameter is rendered for every page selected, and the pages are sorted by published date in descending order, in the example below.

Liquid syntax is used in the html parameter. Some variables set by Snowfire and the keys you have defined, are available. Variables set by Snowfire are in the page namespace, e.g. {{ page.url }}. Keys are in the keys namespace, e.g. {{ keys.myOwnKey }}.

In the example below {{ page.url }}, {{ page.name }} and {{ page.publishDate }} are Snowfire variables, while {{ keys.body }} is a key.

{ com_keys ( 
    id:'1', 
    description:'Bloglist',
    html:'<h1><a href="{{ page.url }}">{{ page.name }}</a></h1><h2>{{ page.publishDate }}</h2>{{ keys.body }}',
    sortBy:'publishedDate descending'
) }

Blogpost.tpl

In this example, this is the page layout from where the keys are pulled. Please note that keys cannot be used on components in repeaters.

{ com_wysiwyg ( 
    id:'1', 
    description:'Body',
    key:'body' 
) }

Make sure you open pages created with blogpost.tpl, click the Live edit component and hit Save after you've added the key parameter to an existing component, to generate the key.

Parameters

html

The HTML code to be rendered for every page pulled. Liquid syntax is used. If you want to know all available keys, write <pre>{{ keys }}</pre>.

Don't forget that Liquid allows for conditional statements etc:

{% if keys.image %}
	{{ keys.image }}
{% else %}
	No image available
{% endif %}
  • {{ page.url }} - Url to the current page from where the keys are pulled.
  • {{ page.name }} - Page name of the current page from where the keys are pulled.
  • {{ page.id }} - A unique identifier for the page.
  • {{ page.html }} - The page HTML. Must be enabled with the parameter enablePageHtml.
  • {{ page.publishDate }} - Publish date of the current page from where the keys are pulled. See the format function for formatting options.
    • Example with formatting: {{ page.publishDate | format:"%e %h %Y" }}
  • Any user-defined key. Keys are set on components with the key parameter. In the above example, the wysiwyg component in layout Blogpost.tpl has key body. To get this key, use {{ keys.body }}.

sortBy

What order the pages should be rendered in.

  • pageName ascending/descending
  • createdDate ascending/descending
  • updatedDate ascending/descending
  • publishedDate ascending/descending

contentType

Set it to "page" to enable more flexible keys (specific pages or tags)

functions

Key data can be tampered with using functions. Don't forget that functions are chainable: {{ page.html | getHtmlById:"blog-post-content" | debug }}

Limit words
limitWords:[Number of words allowed]

Strips all HTML, remove words above the limit and appends ... if necessary.

Example

{{ keys.body | limitWords:10 }}

Limit words HTML
limitWordsHtml:[Number of words allowed]

Same as limitWords, but doesn't strip HTML.

Example

{{ keys.body | limitWordsHtml:10 }}

HTML attribute
attr:"[HTML attribute]"

Extract an HTML attribute.

Example

{{ keys.image | attr:"src" }}

Format date
format:"[Format string]"

Format a date (see Date format for syntax).

Example

{{ page.publishDate | format:"%e %B %Y" }}

Resize image
resize:[Width in pixels]x[Height in pixels], "[resize / crop]"

Resize an image. The first parameter can be either just width, height or both: 50, x50 or 50x50. The second parameter specifies the method: resize scales the image, crop crops it.

Example

{{ keys.image | resize:"50x50","crop" }}

Extract HTML element by ID
getHtmlById:"[Html ID]"

Extract the inner HTML of an HTML element, by it's ID.

Example

{{ page.html | getHtmlById:"blog-post-content" }}

Debug
debug

Escape HTML entities for debugging purposes. Can also be used to show all available variables.

Example

{{ page | debug }}

paginationHtml

Uses Liquid syntax.

Variables
  • totalPages - Total number of pages
  • pageNumber - The current page
  • perPage - How many items per page
  • count - Total number of items
  • previous - Object with url and page, if there is a previous page, otherwise set to null.
  • next - Object with url and page, if there is a next page, otherwise set to null.
Filters
  • pageNumberToUrl - Convert a page number to an URL.
Tags

Other parameters

  • htmlElement - Defaults to div. What HTML element to wrap the html parameter with, i.e. every page. Additionally, this element will get any HTML attributes specified. HTML class active will automatically be set if the a HTML snippet links to the current URL.
  • perPage - How many items to show per page. If this is set, paginationHtml must also be set.
  • limit - Limit without pagination
  • offset - Offset 1 if you don't want to show the first post.
  • childrenLevels - How many levels of child pages
  • useChildPages - Automatically use this page's child pages
  • createButton - Creates a child page, to the page with the com_keys. This parameter sets the text on the button.
  • useRootParentChildPages - Automatically use all this page's grandparent's children.
  • enablePageHtml - Enable {{ page.html }}.

Example with pagination

{ com_keys ( id:'2', description:'Keys', sortBy:'publishedDate descending', perPage:'2', paginationHtml:'
 
	{% if previous %}
		<a href="{{ previous.url }}">&larr; Go to page {{ previous.page }}</a>
	{% else %}
		[This is the first page]
	{% endif %}
 
	Page {{ pageNumber }} of {{ totalPages }}
 
	{% if next %}
		<a href="{{ next.url }}">Go to page {{ next.page }} &rarr;</a>
	{% else %}
		[This is the last page]
	{% endif %}
 
', html:'
 
	<pre>
 
Url: <a href="{{ page.url }}">{{ page.url }}</a>
 
{{ keys.heading }}
==================
 
{{ keys.body | limitWords:5 }}
{{ keys.body | limitWords:10 }}
{{ keys.body | limitWords:20 }}
{{ keys.body }}
----------------------------------
 
	</pre>
 
' ) }

Another paginationHtml example

{% if totalPages > 1 %}
<div id="pagination">
 
	<div class="pages">
		{% paginate page in pages current: pageNumber limit: 10 %}
			{% if page == pageNumber %}
				<span>{{ page }}</span>
			{% else %}
				<a href="{{ page | pageNumberToUrl }}">{{ page }}</a>
			{% endif %}
 
		{% endpaginate %}
	</div>
 
</div>
{% endif %}


Map

Display an embedded map. Parameter description is not required.

{ com_map (
	id: '1',
	width: '500',
	height: '500',
	language: 'sv',
	htmlId: 'map'
) }

Parameters

  • width - Required.
  • height - Required
  • language - Required. ISO 639-1 language code.
Views
Personal tools