Difference between revisions of "Template data"

From The Smartest Wiki
Jump to: navigation, search
(SmartestPage)
(Automatic offsets)
 
(14 intermediate revisions by the same user not shown)
Line 33: Line 33:
 
===SmartestArray===
 
===SmartestArray===
  
A SmartestArray is a wrapper for an ordinary PHP array, but with added offsets for convenient use in templates.
+
A SmartestArray is a wrapper for an ordinary [[PHP:array|PHP array]], but with added offsets for convenient use in templates.
  
 
See [[SmartestArray]] for full details and offsets.
 
See [[SmartestArray]] for full details and offsets.
Line 53: Line 53:
 
Stores a time stamp, in a resolution of seconds. Can be used to refer only to days, months or years.
 
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.
+
See [[Class:SmartestDateTime|SmartestDateTime]] for full details and offsets.
  
 
==SmartestDataObject==
 
==SmartestDataObject==
Line 61: Line 61:
 
===SmartestAsset & SmartestRenderableAsset===
 
===SmartestAsset & SmartestRenderableAsset===
  
All files stored in Smartest's media library are displayed and interacted with via this class, regardless of their [[asset type|type]]. [[SmartestAsset]] is sufficient for creation and modification, while [[SmartestRenderableAsset]] is used for display of the file.
+
All files stored in Smartest's media library are displayed and interacted with via this class, regardless of their [[asset type|type]]. [[Class:SmartestAsset]] is sufficient for creation and modification, while [[Class:SmartestRenderableAsset]] is used for display of the file.
  
See [[SmartestAsset]] and [[SmartestRenderableAsset]] for more details and offsets.
+
See [[Class:SmartestAsset]] and [[Class:SmartestRenderableAsset]] for more details and offsets.
  
 
===SmartestPage===
 
===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-page]]s, tag pages, search results and user profiles respectively.
+
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, [[Class:SmartestItemPage|SmartestItemPage]], [[Class:SmartestTagPage|SmartestTagPage]], [[Class:SmartestSearchPage|SmartestSearchPage]] and [[Class:SmartestUserPage|SmartestUserPage]] are used for [[meta-page]]s, tag pages, search results and user profiles respectively.
  
See [[Class:SmartestPage|SmartestPage]], [[Class:SmartestItemPage|SmartestItemPage]], [[Class:SmartestTagPage|SmartestTagPage]], [[Class:SmartestSearchPage|SmartestSearchPage]] and [[Class:SmartestUserPage|SmartestUserPage]] for more details.
+
''For more on these classes, See [[Class:SmartestPage|SmartestPage]], [[Class:SmartestItemPage|SmartestItemPage]], [[Class:SmartestTagPage|SmartestTagPage]], [[Class:SmartestSearchPage|SmartestSearchPage]] and [[Class:SmartestUserPage|SmartestUserPage]] for more details.''
  
 
===SmartestItem===
 
===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.
+
SmartestItem is the basic active record [[Class:SmartestDataObject|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.
+
See [[Class:SmartestItem|SmartestItem]] for details.
  
 
===SmartestUser===
 
===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.
+
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 [[Class:SmartestSystemUser|SmartestSystemUser]] object, which is a subclass of [[Class:SmartestUser|SmartestUser]], but with more functionalities related to the Smartest backend.
  
 
===SmartestTag===
 
===SmartestTag===
  
The [[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.
+
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 [[SmartestTag]] for more details.
+
''See [[Class:SmartestTag]] for more details.''
  
 
==SmartestCmsItem==
 
==SmartestCmsItem==
Line 135: Line 135:
 
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.
 
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
+
* <code>$item.name</code> - the name of the item. Will be preceded by an asterisk (*) on unpublished items.
* $item._model
+
* <code>$item._model</code> - the model that the item uses, a [[class:SmartestModel|SmartestModel object]]
* $item._description
+
* <code>$item._description</code>
* $item._draft_mode - indicates whether or not an item is in [[draft mode]].
+
* <code>$item._draft_mode</code> - indicates whether or not an item is in [[draft mode]].
  
 
==Other template data==
 
==Other template data==
Line 144: Line 144:
 
===The $this variable offsets===
 
===The $this variable offsets===
  
The variable <code>$this</code> 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.
+
The variable <code>$this</code> 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 [[Class:SmartestPageRenderingDataRequestHandler|SmartestPageRenderingDataRequestHandler]] class.
  
 
====$this.navigation====
 
====$this.navigation====
  
Provides lists of pages that help to build automatic navigation. Returns an instance of class [[SmartestPageNavigationDataRequestHandler]].
+
Provides lists of pages that help to build automatic navigation. Returns an instance of class [[Class:SmartestPageNavigationDataRequestHandler]].
  
 
====$this.page====
 
====$this.page====
  
Provides access to the current page being rendered as a [[SmartestPage]] object or one of its subclasses ([[SmartestItemPage]], [[SmartestTagPage]], [[SmartestSearchPage]], [[SmartestUserPage]]). From this, all that page's offsets become available, for example <code>$this.page.title</code> to access the current page's title.
+
Provides access to the current page being rendered as a [[Class:SmartestPage|SmartestPage]] object or one of its subclasses ( [[Class:SmartestItemPage|SmartestItemPage]], [[Class:SmartestTagPage|SmartestTagPage]], [[Class:SmartestSearchPage|SmartestSearchPage]] and [[Class:SmartestUserPage|SmartestUserPage]]). From this, all that page's offsets become available, for example <code>$this.page.title</code> to access the current page's title.
  
 
[[Field|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 types|data type]] that field is. The recommended way to access page fields is through <code>$this.fields.FIELDNAME</code>, however this can be useful when accessing information about other pages, such as <code>$this.page.parent.FIELDNAME</code>
 
[[Field|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 types|data type]] that field is. The recommended way to access page fields is through <code>$this.fields.FIELDNAME</code>, however this can be useful when accessing information about other pages, such as <code>$this.page.parent.FIELDNAME</code>
Line 158: Line 158:
 
====$this.site====
 
====$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, <code>$this.site.domain</code>.
+
This offset provides information about the site that the current page being rendered belongs to, as a [[Class:SmartestSite|SmartestSite]] object. For instance, to get the domain name of that site, <code>$this.site.domain</code>.
  
 
====$this.principal_item or $this.%MODELNAME%====
 
====$this.principal_item or $this.%MODELNAME%====
Line 188: Line 188:
 
====$this.tag====
 
====$this.tag====
  
This offset is only available when a tag page is being built. It contains a [[SmartestTag]] object. From that, you can get all the information about the tag via the normal offsets. For example:
+
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:
  
 
<pre>
 
<pre>
Line 198: Line 198:
 
This offset is only available when the page being built is a search page. It returns a [[SmartestParameterHolder]] object with the following offsets:
 
This offset is only available when the page being built is a search page. It returns a [[SmartestParameterHolder]] object with the following offsets:
  
* <code>$this.search.results</code> - an array of the actual results returned, which is a mixture of [[SmartestPage]] and [[SmartestCmsItem]] objects. Also available via <code>$this.search_results for legacy reasons.</code>
+
* <code>$this.search.results</code> - an array of the actual results returned, which is a mixture of [[Class:SmartestPage|SmartestPage]] and [[Class:SmartestCmsItem|SmartestCmsItem]] objects. Also available via <code>$this.search_results for legacy reasons.</code>
 
* <code>$this.search.num_results</code> - the number of results returned. Also available via <code>$this.num_search_results</code>
 
* <code>$this.search.num_results</code> - the number of results returned. Also available via <code>$this.num_search_results</code>
 
* <code>$this.search.query</code> - the query that has been searched for.
 
* <code>$this.search.query</code> - the query that has been searched for.
Line 204: Line 204:
 
====$this.user or $this.author====
 
====$this.user or $this.author====
  
This offset is only available when building the user profile page. It returns a [[SmartestUser]] object, which will of course give you most data about the user via further offsets. Password and password salt are not available.
+
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:
 
For example:

Latest revision as of 16:26, 21 December 2015

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.