Template data

From The Smartest Wiki
Jump to: navigation, search

Using a dot (.) allows you to access and display specific information about an object that hass been passed to the presentation layer.

The text after the dot is known as an offset. Different offsets after the dot correspond to different bits of information about that object.

Offsets are always lowercase and contain only lowercase letters, numbers, and underscores.

For example:

$page.title retrieves the title of the page, while $page.url retrieves its default URL and $page.id its unique numeric ID within the system.

Different classes of object have different offsets according to what information about them might be available or relevant.

Smartest Basic Types

The main page for this topic is: Basic types

Virtually all information in Smartest is "typed" which means that depending on what kind of information it is, it is treated, stored, retrieved and displayed differently.

The different types of information make use of a standard set of classes, so for example all dates and times are passed around as SmartestDateTime objects, and external URLs are similarly passed as a SmartestExternalUrl object. See Basic types for more. Each basic type has specific offsets that are designed to be useful for working with that type of data.

SmartestImage

Corresponds to an actual image file, usually stored in the Public/Resources/Images/ folder on the server. This is importantly distinct from a SmartestAsset object which corresponds to any file that has been imported into Smartest. A SmartestAsset object contains and uses a SmartestImage object when it refers to an image.

See SmartestImage for full details and offsets.

SmartestExternalUrl

Contains a URL to some web address, almost always to one on another website (note that internal links are handled differently).

See SmartestExternalUrl for full details and offsets.

SmartestArray

A SmartestArray is a wrapper for an ordinary PHP array, but with added offsets for convenient use in templates.

See SmartestArray for full details and offsets.

SmartestParameterHolder

A SmartestParameterHolder is similar to SmartestArray but is not iterable and does not have order. A bit like a plain javascript object or hash, it stores named parameters, which are accessible via offsets derived from the parameter names.

See SmartestParameterHolder for full details and offsets.

SmartestRgbColor

Stores a 24-bit RGB colour. Offsets can be used to format and represent the colour in a variety of ways.

See SmartestRgbColor for full details and offsets.

SmartestDateTime

Stores a time stamp, in a resolution of seconds. Can be used to refer only to days, months or years.

See SmartestDateTime for full details and offsets.

SmartestDataObject

The main page for this topic is: Data objects

SmartestAsset & SmartestRenderableAsset

All files stored in Smartest's media library are displayed and interacted with via this class, regardless of their type. Class:SmartestAsset is sufficient for creation and modification, while Class:SmartestRenderableAsset is used for display of the file.

See Class:SmartestAsset and Class:SmartestRenderableAsset for more details and offsets.

SmartestPage

SmartestPage is the main class for creating pages, and storing and retrieving information about pages. It is used for normal web pages and the 404 page, while four important subclasses, SmartestItemPage, SmartestTagPage, SmartestSearchPage and SmartestUserPage are used for meta-pages, tag pages, search results and user profiles respectively.

For more on these classes, See SmartestPage, SmartestItemPage, SmartestTagPage, SmartestSearchPage and SmartestUserPage for more details.

SmartestItem

SmartestItem is the basic active record SmartestDataObject subclass for basic operations on items when their actual properties and values as entered in the backend are not needed. Name, slug, ID, author and other information is most simply manipulated using this class.

See SmartestItem for details.

SmartestUser

This class is the ordinary class used to refer to users in Smartest. Note that when users are actually logged in to Smartest, they are stored in a SmartestSystemUser object, which is a subclass of SmartestUser, but with more functionalities related to the Smartest backend.

SmartestTag

The Class:SmartestTag class is used to refer to any tag in use anywhere throughout the Smartest system. Pages, as well as items, files, and image files, are available via offsets at the template level.

See Class:SmartestTag for more details.

SmartestCmsItem

For more information about items, see Item

For more information about the SmartestCmsItem class, see SmartestCmsItem

Item properties

The models you build in Smartest all have corresponding PHP classes, and items within those models are usually objects of those classes.

Each property you add to a model also creates a new read-only offset for accessing the value of that property.

For example, let's say we have a 'car' model, and that we add a 'color' property to it so that we can say what color the cars are.

You'll see that the property now appears with a color picker on the item edit screen for all 'car' items:

[screenshot of item edit screen showing car color property]

Next to the label of the property, in parentheses, is an all-lowercase version of the property name with any spaces or punctuation converted to underscores.

This is the value that can be used as an offset in order to access the value of that property within a template.

So in the template, in order to access the color of the car, we'd simply say:

$car.color

It doesn't stop there, because the value returned by the offset will usually be an object in its own right. Since item properties are typed, what type of object you get depends on the type of property it is.

In this example, since the property is an RGB Color property, the object returned will be a SmartestRgbColor object (see above). If for instance we wanted the hex value of that color, we could put this in the template:

$car.color.hex

which would produce:

#c32b1f;

If we wanted an RGB value, we could similarly put this in the template:

$car.color.rgb.

which would produce:

195,43,31

Automatic offsets

Quite aside from the properties you give each model, some offsets are available on SmartestCmsItem objects simply because that's what kind of object they are.

  • $item.name - the name of the item. Will be preceded by an asterisk (*) on unpublished items.
  • $item._model - the model that the item uses, a SmartestModel object
  • $item._description
  • $item._draft_mode - indicates whether or not an item is in draft mode.

Other template data

The $this variable offsets

The variable $this is not itself ever rendered, but it has a number of essential offsets that are used for dealing with the core function of the current page. It is an instance of the SmartestPageRenderingDataRequestHandler class.

$this.navigation

Provides lists of pages that help to build automatic navigation. Returns an instance of class Class:SmartestPageNavigationDataRequestHandler.

$this.page

Provides access to the current page being rendered as a SmartestPage object or one of its subclasses ( SmartestItemPage, SmartestTagPage, SmartestSearchPage and SmartestUserPage). From this, all that page's offsets become available, for example $this.page.title to access the current page's title.

Page field values are also available this way - i.e. $this.page.FIELDNAME will provide the value of the field FIELDNAME as an object (type depends on what data type that field is. The recommended way to access page fields is through $this.fields.FIELDNAME, however this can be useful when accessing information about other pages, such as $this.page.parent.FIELDNAME

$this.site

This offset provides information about the site that the current page being rendered belongs to, as a SmartestSite object. For instance, to get the domain name of that site, $this.site.domain.

$this.principal_item or $this.%MODELNAME%

When rendering a meta-page, the item being represented by the meta-page is accessible via $this.principal_item or via the name of the model, as lowercase with underscores. For example, where the model is called Press Release, the principal item on the meta page could be $this.press_release

$this.user_agent

(From revision 667 onwards)

$this.user_agent provides information in the template about the client-side software and hardware being used to browse the page.

  • $this.user_agent.name or $this.user_agent.appname: A plain string containing the name of the browser - for example, "Safari"
  • $this.user_agent.version: A plain string containing the version identifier - for example, "7.0.1"
  • $this.user_agent.version_integer or $this.user_agent.vi: An integer of the major version number above - for example, Safari 7.0.1 would be 7, Chrome 36.X.X.X is just 36.
  • $this.user_agent.engine: An attempted identification of the rendering engine used - not that this will not always be perfect. For example, For Chrome 28 and above, will return "Blink," and for Chrome 27 and down, will return "WebKit." Even identified MSIE 5 for Mac correctly as "Tasman"
  • $this.user_agent.platform: The category of OS - for example, "Windows," "Macintosh," "Android"
  • $this.user_agent.is_mobile: A boolean. Is the client using a mobile device? This includes tablets.
  • $this.user_agent.is_small_mobile or $this.user_agent.is_phoneA boolean. Is the client using a smaller handheld mobile device? This includes phones and iPod touches, but excludes tablets.
  • $this.user_agent.is_large_mobile or $this.user_agent.is_tabletA boolean. True if the client is using a tablet.
  • $this.user_agent.is_desktop or $this.user_agent.is_pcA boolean. True if the client is using a laptop or desktop PC. Does not distinguish between supported and unsupported browsers.
  • $this.user_agent.is_supported_browserA boolean. True if the client is using a laptop or desktop PC that has a supported browser. See System/Core/Types/old_browsers.yml for specifics.
  • $this.user_agent.is_unsupported_browserA boolean. True if the client is using a laptop or desktop PC that has an unsupported browser. See System/Core/Types/old_browsers.yml for specifics.

Note that you will need to enable Smartest's server-side responsive features before cached pages will reliably be able to use $this.user_agent.

$this variable offsets on special pages

$this.tag

This offset is only available when a tag page is being built. It contains a Class:SmartestTag object. From that, you can get all the information about the tag via the normal offsets. For example:

<h2>Content tagged with <?sm:$this.tag.label:?></h2>

$this.search

This offset is only available when the page being built is a search page. It returns a SmartestParameterHolder object with the following offsets:

  • $this.search.results - an array of the actual results returned, which is a mixture of SmartestPage and SmartestCmsItem objects. Also available via $this.search_results for legacy reasons.
  • $this.search.num_results - the number of results returned. Also available via $this.num_search_results
  • $this.search.query - the query that has been searched for.

$this.user or $this.author

This offset is only available when building the user profile page. It returns a Class:SmartestUser object, which will of course give you most data about the user via further offsets. Password and password salt are not available.

For example:

<?sm:$this.user.full_name:?>

This will display the user's name.

You can use the individual model plural names, with lowercase letters and underscores, as offsets of the object returned by this offset, to access the different items that the user has been credited with, by model.

So for example:

<ul>
<?sm:foreach from=$this.user.articles item="article":?>
<li><?sm:link to=$article:?></li>
<?sm:/foreach:?>
</ul>

$this.fields

This is a short-hand means of accessing page field values on the current page, and returns a SmartestParameterHolder object from which each field's value can then be retrieved by a further offset.

For example:

$this.fields.alternate_title

This will retrieve an object (probably a SmartestString, depending on the field's data type) containing the value of the field 'alternate_title'.

Page field values are also accessible via $this.page.fields.%FIELDNAME% and $this.page.%FIELDNAME%

$this.request

The $random variable

As of revision 458, all templates have access to the $random variable.

By default, when printed, this variable will appear to contain a different number between 0 and 1000 (inclusive) every time it is used.

It is actually an instance of a SmartestRandomNumberGenerator object, which returns a new random number as a SmartestNumeric object every time its __toString() method is called.

However, it is a bit cleverer than that. If you need the same number again, use $random.again.

You can also use an offset to specify the upper and lower bounds of the random number generated, so for example, $random.5_15 will give you a random number between 5 and 15 (inclusive). If you want that same number a second time, you can again use $random.again.

$sm_draft_mode

The $sm_draft_mode variable contains a true boolean value that tells you whether the current page is being built in draft mode or not. True for draft mode, false for live.