Cyclone3 Skin

Module template

From Cyclone3 Wiki

(Redirected from File types:Module template)
  • Extension: *.xsgn (see Naming conventions)
  • Extension: _mdl directory
  • Caching: may be cached (depends on master module's setup)

A functional module can produce output by itself, by filling in the output $XSGN{'TMP'}, but it is strongly recommended, that it uses the Cyclone3 built-in template system. This way, the web designers don't have to edit the functional module part to change the output, they only change the template that it uses.

Here is an example of an article list module template (direct link: 401-article_list.lite.default.xsgn):

# use UTF-8
<XML_DESIGN_DEFINITION>

<DEFINITION id="TMP">
  <div class="article-list">

    <div class="head">
       
    </div>

    <div class="content">

<#item#>

      <div class="paging">
<#previous#>
<#next#>
      </div>

      <div class="cf-both"> </div>
    </div>

    <div class="foot"> </div>
  </div>
</DEFINITION>

<DEFINITION id="TMP_failure_no-data">
  No articles
</DEFINITION>

<DEFINITION id="next">
  <a href="?|?|offset=<%offset%>">older »</a>
</DEFINITION>

<DEFINITION id="previous">
  <a href="?|?|offset=<%offset%>">« newer</a>
</DEFINITION>

<DEFINITION id="item">
  <div class="article">
    <div class="image">
      <a href="<%alias_url%>/article-<%db_ID_entity_article%>-<%db_name_url%>"><img src="<%out.img.1.src%>" align="left" width="110" height="62" alt="<%attr_alt%>" /></a><br />
    </div>
    <div class="text">
      <a href="<%alias_url%>/article-<%db_ID_entity_article%>-<%db_name_url%>"> <%db_name%></a> <br/>
      <span class="info"><%db_datetime_start.mday%>. <%db_datetime_start.month%>. <%db_datetime_start.year%> <%db_datetime_start.hour%>:<%db_datetime_start.min%> | Autor: <%author_firstname%> <%author_surname%> </span> <br/>
        <#@html2text><%abstract%></@html2text>
    </div>
    <div class="cf-both"> </div>
  </div>
<#item#>
</DEFINITION>

<DEFINITION id="item.1">
  <div class="article first">
    <div class="image">
      <img src="<%out.img.1.src%>" align="left" width="110" height="62" alt="<%attr_alt%>" /><br />
    </div>
    <div class="text">
      <a href="<%alias_url%>/article-<%db_ID_entity_article%>-<%db_name_url%>"> <%db_name%></a> <br/>
      <span class="info"><%db_datetime_start.mday%>. <%db_datetime_start.month%>. <%db_datetime_start.year%> <%db_datetime_start.hour%>:<%db_datetime_start.min%> | Autor: <%author_firstname%> <%author_surname%> </span> <br/>
      <#@html2text><%abstract%></@html2text>
    </div>
    <div class="cf-both"> </div>
  </div>
<#item#>
</DEFINITION>

</XML_DESIGN_DEFINITION>

You can see here 3 different template definitions. The first one - TMP, is the main output, being sent by the system out to the viewer. The next one is item, which is used for a single article (a single db row). The last one, item.1 is a list-specific design for the first item in the list. This way, you can customize the looks of the listing, so that the first item displays only a large image and article title, and the others display thumbnail, title and abstract, for instance. The line templates are cloned, so you don't have to worry about specifying 10 line designs if you need a 10-article long list.

The possible definitions you can use, should be specified in the specific module's inline documentation on http://www.cyclone3.org.

You probably noted some strange tags inside the template. Yes, the % and # tags. These are called gateways. The % gateways specify placeholders for module output data - typically database field values. The # tags represent placeholders for template definitions. But let's look at how it all works:

The module starts, loads the template, and gets the requested db data (say, we get 6 articles). It loads the first database line with its values, and loads the item template definition into a temporary placeholder.

It fills in the temporary placeholder's % gateways using the raw database values, or processed/generated values:

  <div class="article">
    <div class="image">
      <a href="http://www.yoursite.com/article-54-my-new-article"><img src="http://media.yoursite.com/a501/0000/ashf23bnasb3.jpg" align="left" width="110" height="62" alt="My picture" /></a><br />
    </div>
    <div class="text">
      <a href="<%alias_url%>/article-<%db_ID_entity_article%>-<%db_name_url%>"> <%db_name%></a> <br/>
      <span class="info">18. 05. 2008 16:21 | Autor: Robert Greenford</span> <br/>
        This is my totally new article on my totally new site!
    </div>
    <div class="cf-both"> </div>
  </div>
<#item#>

and replaces the <#item#> placeholder in the TMP definition, so now this looks like:

  <div class="article-list">

    <div class="head">
       
    </div>

    <div class="content">

  <div class="article">
    <div class="image">
      <a href="http://www.yoursite.com/article-54-my-new-article"><img src="http://media.yoursite.com/a501/0000/ashf23bnasb3.jpg" align="left" width="110" height="62" alt="My picture" /></a><br />
    </div>
    <div class="text">
      <a href="<%alias_url%>/article-<%db_ID_entity_article%>-<%db_name_url%>"> <%db_name%></a> <br/>
      <span class="info">18. 05. 2008 16:21 | Autor: Robert Greenford</span> <br/>
        This is my totally new article on my totally new site!
    </div>
    <div class="cf-both"> </div>
  </div>
<#item#>

      <div class="paging">
<#previous#>
<#next#>
      </div>

      <div class="cf-both"> </div>
    </div>

    <div class="foot"> </div>
  </div>

As you can see, we smuggled the next <#item#> gateway in for the next row using the item template (as the previous one in TMP just got replaced by the temporary placeholder data). This is common for all list modules.

Now, the module fetches another row, and another, and continues to add/replace the items until it has no data to process.

When it's done with the rows, and finds out, that there are more than the current limit of 6, it replaces the <#next#> gateway using the next template definition (while replacing its <%offset%> gateway with the respective offset. The same with <#prev#>.

We're done, with all data inside the TMP definition.Now, the module just returns a success, and the system takes the TMP and outputs it where it belongs to.