Placeholder

From The Smartest Wiki
Jump to: navigation, search

A placeholder is a space on a page where a file from the media library can be placed.

For instance, you may want some pages on your site to ave a banner image, but for the banner image to be different on each page, and changeable by the user, without touching any code. To achieve this, you would simply use an image placeholder in your template, and call it "banner_image" (names must be lowercase letters, numbers and underscores).

Adding a placeholder

<?sm:placeholder name="sample_placeholder":?>

If Smartest has not seen this placeholder before, it will notify you you in the page elements tree:

New placeholder.png

If you click "Enter it now," Smartest will ask you specify what type of files should go there, and give the new placeholder a label:

Add placeholder.png

Now, the user will be able to choose a different image for the banner_image placeholder.

If the placeholder contains the strings "image", "img", "banner", "text", "txt", "quote", "stylesheet", "javascript", Smartest will attempt to guess what type of file the placeholder is intended for:

Placeholder auto guess.png

Working with placeholders in templates

The resulting file chosen to define the placeholder will be passed to the template as an instance of a SmartestRenderableAsset object.

If you want to pre-specify the dimensions of a whichever file is chosen to appear in the placeholder, you can do so with a width and height parameter:

<?sm:placeholder name="banner_image" width="800" height="100":?>

Files selected via placeholders can also be accessed via the $this variable. This is particularly useful if you need to access the file a second time, or want to access some informational aspect of the file, instead of displaying it, e.g.:

$this.placeholders.banner_image.file

Conversely, if you simply want a button in the page preview to replace or edit the file that appears in the placeholder, or a node to appear in the page elements tree, but do not actually want the file to appear where the placeholder tag is placed in the template, you can add a display="false" parameter:

<?sm:placeholder name="banner_image" display="false":?>

This works quite week in conjunction with the $this.placeholders.banner_image construction if you want the control and the display of a file in a placeholder to be located separately.