USING THE TEMPLATE SYSTEM by gigi12

VIEWS: 15 PAGES: 14

									       YaBB SE 2 - Trinity
        Template System
         Specifications




Yet Another Bulletin Board SE
http://www.yabbse.org/


                                -1-
                                               Table of Contents
                                   - incomplete -
Chapter 1 – Introduction
      What is the template system?
      How does the template system work?
Chapter 2 – The Template Loader
      What does the template loader do?
      Invoking the template loader
Chapter 3 – The Template Compiler
      What does the template compiler do?
      Invoking the template compiler
Chapter 4 – Creating Templates
      HTML Code
      Tags
      Primary Types
Chapter 5 – Tag Reference
      template
      function
      param-declaration
      parameter
      function-body
      include
      call-function
      supply-parameters
      literal
      if
      else-if
      else
      for-each




                                        -2-
                                                                     Chapter




                                                           Introduction
                                                                            1
Judging from the needs and desires of our clients, we have constated they want
higher customizability. Therefore, we have designed a powerfull templating system
with endless capabilities. The template system defines standard files that specify the
HTML to build our forum software around. The template system takes care of loading
and compiling templates. Templates are built from html, with easy, simple to learn
html-based templating tags (see chapter 4) to pure php code to ensure they are fast
at run-time. The template system involves two packages: TemplateLoader and
TemplateCompiler, both discussed in the next two chapters.

Folder Structure
The template system is structured into one second-level directory: theme.

Path                                              Description
theme/                                            Theme Main Folder
theme/{SkinName}                                  Skin‟s Main Folder
theme/{SkinName}/*.{Language}.php                 Compiled Templates
theme/{SkinName}/src                              Template Sources
theme/{SkinName}/src/{TemplateName}.html          Template Source


Package Diagram

     TemplateLoader                    TemplateCompiler




                                         -3-
                                                                     Chapter




                                        The Template Loader
                                                                              2
The template loader loads compiled templates and executes them when called. It is
used in the process of language selection, and context variable assignment.

Usage
You invoke the template loader by creating a new TemplateLoader object:
      $TemplateLoader =& new TemplateLoader ();
      $TemplateContext =& Array ();

You must then load a skin and template and set the language to display the content
as:
      $Skin =& $TemplateLoader->LoadSkin ('default', 'nl'); //Loads
         the template index within the default skin
      $Template =& $Skin->LoadTemplate ('boardindex', 'nl');
      //Display all content in Dutch

You can now proceed with the rest of the code and possibly also set template
variables:
      //Set the variable ‘date’ to ‘Tuesday December 3, 2002’
      $TemplateContext['date'] = ‘Tuesday December 3, 2002’;

When you are finshed and want to print the entire template to screen, call:
      //Display the selected template in the selected language
      $TemplateLoader->Execute ($Forum);




                                         -4-
Class Diagram

    TemplateLoader   1             Skin

   setTemplate ()         loadTemplate ()
   setLanguage ()
   display ()                         *

             1



                     1        Template
       Language

   load ()               load ()




                          -5-
                                                                      Chapter




                                      The Template Compiler
                                                                           3
The template compiler compiles template source files into pure php code. The
template compiler will look for certain xml tags within a certain namespace and
transform them and their content into php.

Usage
You invoke the template loader by creating a new TemplateCompiler object:
       $TemplateCompiler =& new TemplateCompiler ();
       //Tell the compiler not to debug every line
       $TemplateCompiler->SetDebugLevel (DEBUGLEVEL_LOW);

You then must specify a skin to compile
       $Skin =& $TemplateCompiler->LoadSkin (‘default’);

If you want to validate the template syntax first, call:
       $TemplateCompiler->ValidateSyntax ();

When you are ready to buid, call:
       $Skin->Compile ();



Class Diagram
                        1                         *
  TemplateCompiler                      Skin               Template

  setSkin ()                           load ()              load ()
  validate ()
  build ()




                                            -6-
                                                                     Chapter




                                            Creating Templates
                                                                           4
Creating templates can be a confusing task if you‟re not familiar with the standards
used here. This guide will help you understand the basics of creating templates. The
next chapter will give a detailed description on each tag.

HTML Code
You are more than able to use any valid xhtml code between inside the
<yse:template> and <yse:function-body> elements.

Variables
Variables are strings or other data types stored within the memory of the server your
YaBB SE forum is hosted on. You can call for variables inside template source by
prepending their identifier with a dollar sign:
      // A variable storing the current time
      <td><b>The current time is: $CurrentTime</b></td>

Variables that can be understood by the template are those that are designated to be
so by the caller module. You may also call on object members by using the dot (.)
operator:
      /* A member variable of the object identifying the current
         logged user (you) */
      Welcome, <i>$CurrentUser.DisplayName</i><br />

You can use the same technique to access associative array members. To access
numbered array you may put the key between brackets:
      /* Displays the value of the subject field of the first entry
         in the posts array */
      <b>The subject of the first post is:</b> {posts[0].subject}

For template elements expecting a variable address instead of it‟s contents, you
would simply type it‟s identifier:
      // This piece of code loops through an array of ‘user’ objects
      <yse:for-each set=”user_list” as=”user”>
        <b>User:</b> $User.DisplayName</br >
      </yse:for-each>



                                         -7-
Operators and statements
You may use relational and logical operators in loops and conditions to expand the
loop or condition. The YaBB SE Template System supports both unary and binary
operators. Operands are the arguments passed to an operator. Statements are bits
of code that return either true or false.
Relational
Relational operators generate a boolean result.
Logical
Just like logical operators, do the logical operators AND (&&), OR (||) and NOT (!) all
generate a boolean value of true or false based on the logical relationship of the
operands. The operator AND (&&) requires that both operands evaluate to true.
       /* If the user if an admin and debugging is enabled, print
          debug window */
       <yse:when test=”$CurrentUser.IsAdmin() &&
       $Settings.CompilationDebugEnabled”>
         <table>
                 <th colspan=”2”>Debug</th>
                 (...)
         </table>
       </yse:when>

The OR (II) operator will produce true if either one of its‟ operands evaluates to true.
       /* If guests can post or the user is logged in display the post
          box */
       <yse:when test=”$CurrentUser.IsAllowedTo ($Permissions.Post) ||
       $Settings.GuestsCanPost”>
         (...)
       </yse:when>

The NOT (!) operator will invert the boolean value of its‟ operand. If the operand
evaluates to true, this operator will invert it to false and vica-versa.
       // While NOT at the end of posts
       <yse:while test=”!$Posts.End()”>
         <yse:set variable=”$Post” value=”$Posts.Next()” />
         <b>Poster:</b> $Post.Poster.DisplayName
         (...)
       </yse:when>


Parenthesis
You can use parenthesis to group statements.
       /* While don’t stop looping and the username list has more
          entries */
       <yse:while test=”!($StopLooping && UserList.HasNext())”>
         (...)
       </yse:when>

As you can see in the example, the parenthesees group together two statements
bound with the AND (&&) operator and pass the result to the NOT (!) operator.



                                          -8-
Literals
Literals are things that aren‟t variables, but can be used where a variable is expected.
       /* Set the post.poster.name to Guest */
       <yse:when test=”!$CurrentUser.IsLogged()”>
         <yse:set variable=”$Post.Poster.DisplayName” value=”Guest” />
       </yse:when>




Templates
Several templates can be within a single file. You must seperate these by specifying
which template the current html is for.
       /* Start the done_registering template */
       <yse:template name=”start_registering”>
         <html>
             (...)
         </html>
       </yse:template>



Conditions
Conditions are statements that must be correct in order to execute a certain piece of
code. They are like „if‟ statements in formal programming languages:
       // If the user if an admin, display a link to the admin panel
       <yse:when test=”$CurrentUser.IsAdmin()”>
         <a href=”index.php?a=admin”>Administrator Control Panel</a>
       </yse:when>

As you can see in the example above, simple treeless conditions are created by
using the <yse:when> tag. The code inside the test attribute will be executed and if it
generates true, the code between the tags will be executed. You can also program
complex conditions using the template system:
       <yse:conditional>
         <yse:if test=”$CurrentUser.IsAdmin()”>
                 You are a forum administrator. Lucky you 
         </yse:if>
         <yse:else-if test=”$CurrentUser.IsLogged()”>
                 You are a registed user…
         </yse:else-if>
         <yse:else>
                 You are a guest…
         </yse:else>
       </yse:conditional>

Complex conditionals may involve extra cases and default actions. Therefore they
are far more powerfull than rows of <yse:when> tags. The above conditional can be
phrased as: “If the user is administrator, do write so, if not but the user is logged on,
do tell the user he is registered, otherwise tell the user he is a guest”. Complex
conditionals are wrapped inside <yse:conditional> tags. Besides the complex
conditional <yse:when> equivalent <yse:if>, complex conditionals may also specify
otherwise-if‟s (<yse:else-if>) that will execute if all proceding if‟s and else-if‟s fail and


                                             -9-
the current one succeeds. If all conditions fail, an optional <yse:else> statement will
execute. It might seem complicated, but it‟s really simple and straighforward once
you have gotten the hang of it.

Loops
Loops are sections of code that are repeatedly executed:
       // This piece of code loops through an array of ‘User’ objects
       <yse:for-each set=”$UserList” as=”$User” index=”$Key”>
         <b>User $Key:</b> $User.DisplayName</br >
       </yse:for-each>

There is currently only one type of loop implented, that is the for-each loop. It loops
through an array key-by-key and will give you the current key‟s value every time.

Functions
Sometimes, when a certain process is done often, you find yourself wishing you had
functions – just like in formal programming languages. Lucky for you, YaBB SE‟s
template system includes just such a feature.
       // Show the user’s profile link.
       <yse:function name=”user_profile”>
         <yse:parameter-list>
             <yse:parameter variable=”$User” default=”null”>
         </yse:parameter-list>
         <a
       href=”index.php?a=profile;sa=view;u={$User.ID}”>{$User.DisplayN
       ame}</a>
       </yse:function>




                                          - 10 -
                                                                        Chapter




                                    Complete Tag Reference
                                                                              5
All tags are grouped into levels and can contain all of the children of the levels
specified in the table below, unless otherwise specified.
 Level Description                              Parents Children
    1     Template and function declaration none             2, 3
    2     Template statements                   1, 2         3
    3     HTML                                  1, 2         n/a

<yse:template>
Store a certain template
Level
1
Attributes
name         required          The name to call this template by

<yse:function>
Define a template function
Level
1
Attributes
name         required       The name to call this function with
Children
<yse:parameter-declaration>
<yse:function-body>

<yse:parameter-declaration>
Declare all applicable parameters to the overlying function
Level
2
Parents
<yse:function>
Children
<yse:parameter>




                                          - 11 -
<yse:parameter>
Declare a single parameter to a function
Level
2
Attributes
name         required         The name of the attribute that can later be recalled as
                              a variable in the function body
Parents
<yse:parameter-declaration>
Children
None

<yse:function-body>
Define the function content
Level
2

<yse:when>
Define a simple condition
Level
2
Attributes
test         required           The statement to test against

<yse:conditional>
Define a complex conditional
Level
2
Children
<yse:if>
<yse:else-if>
<yse:else>

<yse:if>
Tests against a certain statement
Level
2
Attributes
test         required         The statement to test against a variable in the function
                              body
Parents
<yse:conditional>

<yse:else-if>
Tests against a certain statement if all preceding tests fail
Level
2
Attributes


                                          - 12 -
test          required          The statement to test against a variable in the function
                                body
Parents
<yse:conditional>


<yse:else>
Execute if all preceding tests fail
Level
2
Parents
<yse:conditional>

<yse:while>
A loop that will execute until the test returns false
Level
2
Attributes
test         required            The test to repeat on each loop and to check on each
                                 loop

<yse:for-each>
A loop that will execute while an array still has elements left over
Level
2
Attributes
array        required           The array to loop through
key          optional           The variable to assign the key of the element to on
                                each loop
value        required           The variable to assign the value of the element to on
                                each loop

<yse:include-template>
Include a defined template
Level
2
Attributes
name         required           The name of the template to include

<yse:call-function>
Call a defined function
Level
2
Attributes
name         required           The name of the function to call




                                         - 13 -
Children
<yse:supply-parameters>

<yse:supply-parameters>
Supply parameters to a function being called
Level
2
Parents
<yse:call-function>
Children
<yse:literal>


<yse:literal>
Define a literal (usually to supply to template functions)
Level
2




                                          - 14 -

								
To top