Free, Open Source Software for Building
and Managing Websites

Forum

Docs > Site Development > Development Topics > First Steps

About Saurus API

Saurus API (SAPI) is a collection of plugins and variables to the Smarty template engine. Saurus adds specific plugins (functions, modifiers and filters) and variables to interact with CMS content objects that are documented in the SAPI reference. If you are unfamiliar with Smarty, we recommend you to read at least basic syntax before continuing.

Creating page template tutorial

This is a step-by-step tutorial which will give you an overview about creating a page template in Saurus 4. Page template usually defines the heading, footer and menu system of web pages. To follow the tutorial you must have an access to a Saurus CMS installation and a text editor.

Creating a template file

First let’s create a template file we are going to work with.

Go to your site administration view (also referred here as Admin) by adding /admin at the end of the site address.
Go to Templates > Page templates and click New.
A popup window will open. Fill in the template name with „My page template” for example.
The checkbox „Visible in section editor” defines whether content editor can choose this template when creating new sections. Just leave it checked.
Finally, type some text such as „asdf” to the text area where the HTML code with Saurus API tags normally would go. We will get to the code in a moment.
Click Save.

Setting the master template

Although you could create a new section in editor’s environment and choose this new template now, let’s make it a default page template so that all sections which do not have a local value set would use it.

Go to Admin > Sites > Sites and choose your new page template „My page template” for the site you are working on (English is default for new installations). Click Save. Note that you can set different templates for each site/language, also there is an option to define default content templates.
Go to site public view and refresh if needed. You should see the output of your template now. „Asdf” in our case.

Editing the template

You can continue editing the template code from Admin > Templates > Page templates, but the HTML area in that popup window is really not a best option for that. Once registered via this page, the template file can be modified from file system directly. We recommend to use text editors such as EditPlus or Notepad++ for working with templates.

So where is your template? All templates created via Admin > Templates are stored in the following folder in your site root:

/classes/smarty/templates

Find your file my_page_template.html (all special characters in the template name were replaced by underscores automatically) and open it in the text editor program. You can now save any changes and refresh your page in browser to see the output changing. If you do not have access to the file system, you can work with the popup window in site Admin to continue with the tutorial.

Basic HTML code

Let’s change the current „asdf” with some HTML. Copy-paste the following code to your template:

<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
<html>
<head>
    <title>{$title}</title> 
    <meta http-equiv="Content-Type" content="text/html; charset={$encoding}"> 
    <script language="javascript" type="text/javascript" src="{$wwwroot}/js/yld.js"></script> 
    <link rel="stylesheet" type="text/css" href="{$wwwroot}/styles.php">
</head>
<body> 
    <h1>Hello world!</h1>
</body>
</html>

Everything between brackets {} is treated as Smarty / Saurus API (SAPI) code in templates. $ refers to a variable. In our example you can see the following SAPI tags and functions:

{$title} returns the page HTML TITLE which can be set in Admin > Properties > Meta-info.
{$encoding} is the codepage of current site language set on Admin > Languages > Languages.
{$wwwroot} refers to site root folder and is wise to include in the code since you may want to move your site around for example from sitename.com/development to just sitename.com.

For other suitable variables for HTML HEAD such as meta-description and meta-keywords, check out the SAPI Global variables page.

The JavaScript /js/yld.js and dynamic CSS /styles.php calls are needed for the editor’s environment to work.

Creating a menu system

1st level menu

So we now have a basic HTML page which outputs „Hello world” and sets HTML TITLE and encoding but we need something more dynamic. Copy-paste the following code between the HTML BODY tags in your template and find out how it works in your site editor’s environment:

<ul>
{init_sections name="section_list_1" level="1"}
{foreach from=$section_list_1 item="section_1"}
    <li>{$section_1->buttons}<a href="{$section_1->href}">{$section_1->title}</a></li>
{foreachelse} 
    {if $in_editor}<li>{$section_list_1_newbutton}</li>{/if}
{/foreach}
</ul>

You should be able to see and edit 1st level menu items of your website. Here’s how the code works:

{init_sections} is SAPI function which opens a query of sections from Saurus CMS database. The parameter name defines a variable where the query results are stored while parameter level filters out 1st level sections in our example.
{foreach}..{/foreach} is Smarty syntax for cycling through the array given by from parameter. Note that here we point to the variable $section_list_1 defined by {init_sections} in previous row. The item defines a new variable which points to each cycled item.
{$section_1->buttons} attribute displays the v-shaped hotspot buttons for current item. It only outputs buttons when the editor has logged in and has permissions to modify the section.
{$section_1->href} and {$section_1->title} refer to corresponding parameters for current item.
{foreachelse} is executed when {init_sections} did not return any values and there is nothing to loop. We display a v-button to add first section item with {$section_list_1_newbutton}. Note that since in this case we do not have a loop item we can not use the variable $section_1 but have to point to the query results itself by using $section_list_1 instead.

2nd level menu

Creating 2nd level menu goes the same way, you just have to use different variable names and open the {init_sections} with different level parameter. Here’s our next example, replace the previous code between HTML BODY tags with this:

<ul>
{init_sections name="section_list_1" level="1"}
{foreach from=$section_list_1 item="section_1"}
    <li>
    {$section_1->buttons}<a href="{$section_1->href}">{$section_1->title}</a>

    {if $section_1->is_selected} 
        <ul> 
        {init_sections name="section_list_2" level="2" parent=$section_1->id} 
        {foreach from=$section_list_2 item="section_2"} 
            <li>{$section_2->buttons}<a href="{$section_2->href}">{$section_2->title}</a></li> 
        {foreachelse} 
            {if $in_editor}<li>{$section_list_2_newbutton}</li>{/if}
        {/foreach} 
        </ul> 
    {/if}
    </li>
{foreachelse} 
    {if $in_editor}<li>{$section_list_1_newbutton}</li>{/if}
{/foreach}
</ul>

The new code compared to the previous example is:

{if}..{/if} is Smarty syntax and should be self explanatory. The $section_1->is_selected returns true value if the current 1st level section is active. This makes our 2nd level menu only appear when the 1st level menu is clicked.
We added parent parameter to second level {init_sections} tag to get only the sub-items of current 1st level section.

Adding links to menus

If you wish to add link objects to your menus, try adding the following parameter to {init_sections} tags: classes=”section,link”. When you click now on New button in site editor’s environment, you will be asked whether to add new section or link to menu.

Find out more parameters you can use to query sections from database and the attributes returned from SAPI Sections page.

Displaying content

Finally, to display the web content, add the following tag where you wish the content template’s output to be rendered:

{print_content}

In our example the suitable place would be just before the HTML ending /BODY tag.

Creating content template tutorial

This is a step-by-step tutorial which will give you an overview about creating a content template in Saurus 4. We assume that you have previously worked through the Creating page template tutorial.

Creating template file

This is pretty much the same procedure as with the page templates, although the content- and page templates are stored in different sections in site Admin:

Go to Admin > Templates > Content templates. Click New and name your template „My content articles” for example.

Editing the template

The content template file is stored in the same file system folder as the page templates:

/classes/smarty/templates

Find your file my_content_articles.html and open it in the text editor program. If you do not have access to the filesystem, you can work with the popup window in site Admin to continue with the tutorial.

Article listing

Copy-paste the following code to your content template:

{init_articles name="article_list"}
{foreach from=$article_list item="article"}

    <h1>{$article->buttons}<a href="{$article->href}">{$article->title}</a></h1> 

    {init_article name="article_details" id=$article->id} 
    {$article_details->body|truncate:60:".."}

{foreachelse} 
    {$article_list_newbutton}
{/foreach}

Here’s what it does:

The {init_articles} SAPI tag works the same way as {init_sections} and retrieves articles from Saurus CMS database. We do not have many parameters in our example because by default this function returns child objects of section which ID is currently in the URL – the current section.
So we loop through the articles and print out v-buttons and clickable title.
{init_article} inside the loop cycle creates a new variable and retrieves current article’s detailed fields. We hold article’s basic information like title, ID, href separated from details such as lead and body. Note the plural form of {init_articles} and singular form of {init_article}.
truncate:60:”..” is a Smarty string modifier which cuts the text from first 60 chars and adds two dots if the actual text is longer.

Create a new section or modify existing to apply your content template and check out about how it works.

About object’s detail view

So your template creates a listing of articles within the current section. If you click on any of the article titles, an article’s detail view is displayed. For that, we use object template defined in Admin > Templates > Object templates. This template is used whenever you request the article by its ID in the URL, for example from search results.

Normally you would have an object template for each content object type but sometimes it would be wise to change the detail view regarding to the content template assigned to the section.

Which template is currently used?

Saurus CMS would use the following algorithm to find current content template:

If the URL holds an ID of any other object type than section, the object template defined in Admin > Templates > Object templates would be used.
If the URL holds an ID of section, the content template set in section’s properties is used. If the user has not set any content template for section, master content template defined in Admin > Templates > Master templates is used.

For page templates, if there is no local page template set in section’s properties, the template defined in Admin > Templates > Master templates is used regardless of which object type’s ID is in the URL.

Template parameters

You can override the template usage chosen by Saurus CMS by adding tpl and c_tpl parameters to the URL which change page and content template accordingly.

If you still have the my_page_template active for the site, you can try adding &tpl=1043 to your site URL. This should force the site to use the page template which shipped with the product installation. The value 1043 is identifier number of the template in the database and is not connected to the content object ID-s. You can find out the indetifiers of each template in Admin > Templates > Page Templates by moving the mouse cursor over template links and waching the browser status bar.

Creating detail view

Let’s see what we can do with this knowledge. Change the following row in your my_content_articles content template.

<h1>{$article->buttons}<a href="{$article->href}&amp;c_tpl={$c_tpl}">{$article->title}</a></h1>

We have added c_tpl parameter to the URL which points to article’s detail view and added {$c_tpl} SAPI variable to it which returns the current content template number. So we are forcing Saurus to use our current content template.

When you test the code about how it works you will find that instead of article details, a „new article” button is displayed. What happened is that your template tries to find articles which are sub-items to the object currently in URL. Since you clicked on article, you are now able to create sub articles to the article object. While we do not usually recommend it, you can create a structure like that in Saurus CMS. Our task here was to create a custom detail view so we need to check in our template which kind of object is in the URL.

Replace all your content template code with the following:

{if $current_class == 'section'}

    {init_articles name="article_list"} 
    {foreach from=$article_list item="article"} 

       <h1>{$article->buttons}<a href="{$article->href}&amp;c_tpl={$c_tpl}">{$article->title}</a></h1> 

        {init_article name="article_details" id=$article->id} 
        {$article_details->body|truncate:60:".."} 

    {foreachelse} 
        {$article_list_newbutton} 
    {/foreach}

{else} 

    {init_article name="article_details"} 

    <h1>{$article_details->buttons}{$article_details->title}</h1> 
    <p>{$article_details->date} by {$article_details->author}<p> 
    {if $article_details->lead}<p>{$article_details->lead}</p>{/if} 
    {if $article_details->body}<p>{$article_details->body}</p>{/if}

{/if}

What we did:

There is an {if $current_class ..} sentence which checks whether the object in URL is section. If yes, we use the same code as previously to display article listing.
If not, we assume that the object type is article and print out the details such as title, date and author.
Since the content editor can split the article contents between lead and body part we check whether one of these are defined and display them accordingly in HTML paragraph.

About Saurus API

Creating page template tutorial

Creating a template file

Setting the master template

Editing the template

Basic HTML code

Creating a menu system

Adding links to menus

Displaying content

Creating content template tutorial

Creating template file

Editing the template

Article listing

About object’s detail view

Which template is currently used?

Template parameters

Creating detail view

Downloads

Documentation

About