Links

From The Smartest Wiki
Jump to: navigation, search

Rather than use an ordinary <a href=""></a> tag to link your pages together, Smartest offers you markup alternatives that are processed and turned into ordinary HTML links, but with enhanced and automated functionality.

The advantages of this are numerous. For a start, your links will be compatible with Smartest's live preview mode, meaning that if you click a link to page B from a preview of page A, you are then taken to a preview of page B. Also, since Smartest offers a considerable degree of flexibility with the URLs of your pages, a changed URL does not mean lots of broken links, as Smartest can simply update the linked URL on relevant pages when you change it. Other functionality, such as file downloads and obscured email addresses in mailto: links is also handled automatically.

Linking in text

External URLS

Link to an external URL:

[http://www.example.com]

Link to an external URL with alternative text:

[http://www.example.com Text of the link]

produces:

<a href="http://www.example.com" class="sm-link-external">Text of the link</a>

Link to an external URL with alternative text, in a new window:

[+http://www.example.com Text of the link] (note the plus sign)

produces:

<a href="http://www.example.com" class="sm-link-external" target="_blank">Text of the link</a>

Internal pages

Link to an internal static page:

[[page:page-slug]] (where 'page-slug' is the slug of a page)

Link to an internal static page with alternative text:

[[page:page-slug|Text of the link]] (where 'page-slug' is the slug of a page)

produces:

<a href="/url-of-the-page.html" class="sm-link-internal">Text of the link</a>

Link to an internal item, of a hypothetical model called 'Blog Article,' with alternative text:

[[blog_article:item-slug|Text of the link]] (where 'item-slug' is the slug of the article)

produces:

<a href="/url-of-the-item.html" class="sm-link-internal">Text of the link</a>


Linking in templates

Every link in Smartest templates is done with the <?sm:link:?> tag.

This tag must always have the to="" field defined. The definition can be of the following:

  • a string, in the form of a smartest page address, such as "page:home" or "article:november-2014-update" (in the case that you have a model called Article and a specific item of that model with the slug 'november-2014-update')
  • a page object (an instance of SmartestPage)
  • an item from one of your models (a SmartestCmsItem-descended object)
  • a tag object (of the SmartestTag class)
  • a user object (of the SmartestUser class)

Examples

All HTML links must have a destination that they link to, and content in the form of text or an image that forms the visible, clickable bit of the link.

The destination of the link

This code:

<?sm:link to="page:home":?>

Will produce a link to the homepage, the content being the title of the page:

<a href="/" class="sm-link-internal">Home</a>


You can link to items by using a version of the model's singular name, rendered as lowercase letters and underscores (we call this a varname).

For example, if you had a model called "News story", and one of your news stories was entitled "Superman makes shock appearance in amateur play," you could link to it like so, using the slug of the item:

<?sm:link to="news_story:superman-makes-shock-appearance-in-amateur-play":?>

Will produce a link to the item, if it has a meta-page, the content of the link being the name/title/headline of the item, in this case a news story:

<a href="/news/superman-makes-shock-appearance-in-amateur-play.html" class="sm-link-internal">Superman makes shock appearance in amateur play</a>

If no meta-page is set up for this model, the URL will simply be a #


If you already have the item you want to link to as an object, you can pass this object to the to="" attribute:

<?sm:link to=$item:?> (where $item is a SmartestCmsItem object)


Similarly, if you have a page object, you can pass this, and a link to the page will be created:

<?sm:link to=$page:?> (where $page is a SmartestPage object)


Smartest also gives you special pages for a tag view and an author view, and you can link using a SmartestTag object or "tag:tagname" page address, or SmartestUser object or "author:marcus" page address, respectively:

<?sm:link to=$tag:?> (where $tag is a SmartestTag object) OR <?sm:link to="tag:news":?> (where "news" is the slug of a tag)

<?sm:link to=$author:?> (where $author is a SmartestUser object) OR <?sm:link to="author:marcus":?> (where "marcus" is the username of a user)


In cases where you are linking to an item, and there is more than one meta-page item available for viewing items of that model, Smartest will choose the default meta-page for that item, which is set both and the model and can be overridden for each item on the Edit Item screen. If you would like your link to use a different meta-page, you can specify the slug of the alternative meta-page with the metapage="" attribute, e.g.:

<?sm:link to="news_story:superman-makes-shock-appearance-in-amateur-play" metapage="news-story-print-layout":?>

The content of the link

To set the content of the link to something else, use the with="" attribute:

<?sm:link to="page:home" with="Go home":?>

which produces

<a href="/" class="sm-link-internal">Go home</a>

Note: The class="sm-link-internal" is added automatically to all internal links (i.e. links between the pages of the same site) in case you want to style them differently to external links.


You can also vary the with="" attribute in several ways, besides a simple text value. Using the image: prefix, you can specify the name of an image file in Public/Resources/Images/:

<?sm:link to="page:home" with="image:logo.gif":?>

which produces

<a href="/" class="sm-link-internal"><img src="/Resources/Images/logo.gif" alt="" /></a>


You can also specify the alt="" attribute of the image with an alt="" or img_alt="" attribute on your link:

<?sm:link to="page:home" with="image:logo.gif" img_alt="Company logo":?>

which produces

<a href="/" class="sm-link-internal"><img src="/Resources/Images/logo.gif" alt="Company logo" /></a>

Alternatively you can simply pass the with="" attribute of the link a SmartestImage object, or a SmartestAsset object, if it is a JPEG, GIF of PNG image type, and the same functionality will occur:

<?sm:link to="page:home" with=$my_image_object alt="Company logo":?> (where $my_image_object is a SmartestImage object containing Public/Resources/Images/logo.gif):

which produces

<a href="/" class="sm-link-internal"><img src="/Resources/Images/logo.gif" alt="Company logo" /></a>

Since SmartestImage objects are chainable, you can pass modified versions of an image to the link tag:

<?sm:link to="page:home" with=$my_image_object.width_200 alt="Company logo":?>

For more on how to modify and chain images, see the SmartestImage page.