Template data

From The Smartest Wiki
Revision as of 14:47, 29 September 2013 by WikiAdmin (Talk | contribs) ($this.user or $this.author)

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

SmartestPage

SmartestUser

SmartestItem

SmartestCmsItem

For more information about items and the SmartestCmsItem class, see Item

Item properties

As you will have seen in chapter XX, the models you build 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
  • $item._model
  • $item._description
  • $item._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.

$this.navigation

$this.page

$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.

$this.tag

$this.search_results

$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.

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.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.