Template construction

From Sharetronix Developer Documentation
Jump to: navigation, search


Template construction overview

Sharetronix Opensource template system is composed of two types of HTML content - layouts and blocks. Layouts are responsible for the structure of the page layout and how header, body and footer will look like. The blocks are responsible for the html which will be used in these parts or with other words blocks are all the posts, side elements, menus and etc.
There could be some complex blocks which could contain inner blocks. In MVC system the controller loads and controls the view.
In Sharetronix this is done by specific template variables which are in this format:
Template_variable is the name of the variable and it is surrounded by curly braces and percentage symbol({}%) by each side. After the controller load a layout or a block it determines what to load in the template variables. Template variables are replaced by html content. If a variable is not used by the controller it is removed after the view loads.
Pay attention that if your html code or javascript require using of ID, in order to prevent conflict with the apps of other developers it will be good to use specific prefix for this ID.
The default layouts and blocks are located in the ./static/ folder there are also located the default css, javascript and image files. Layouts, blocks and template itself are managed by the classes: class_layout.php class_template.php class_htmlBlock.php located in ./system/classes/ folder. After the template is loaded all the html functions in the ./system/helpers/func_html.php are loaded and could be used in the template. There are functions which could help to create standart html content like menus, message(ok, error), tables etc. More about these functions you could find in the Function Reference. We will explain layouts, blocks and inner blocks in the next chapters and more detialed information how the controller loads the html content in the view.


As we said in the overview you control the view in the controller. In order to do this you should initialize the template and set the contents you want in it. Let's see how to do this:
$tpl = new template(); //now the template is initialized. The template class constructor could receive two parameters: $params - this is an array of parameters which will be given to the header. Format is array_key = name of the var in the header and array_value = value of the variable. See header layout to see available variables in it. $default_load - it is TRUE by default and controls the way the template will load. Default load means that the header will be loaded automatically. This is very useful in all the pages, but there are some situations you do not want header to load, like in the ajax request output.

$tpl = new template( array('page_title' => 'My Sharetronix Site Title', 'header_page_layout'=>'sc') );

This is the most used example of the template() object. As you can see $params array (or the first parameter) contains two entries - 'page_title' - this will be the Title of the page or with other words the contains of the <title></title> in the header. 'header_page_layout' - is the layout type which you will use in the template, there are up to three columns possible, see the image above. Possible options are:

  • 'c' - main content only;
  • 'cs' - main content and right sidebar;
  • 'sc' - left sidebar and main content;
  • 'scs' - left sidebar, main content and right sidebar.

After all the data is loaded in the template you can display it on the screen with the display() method: $tpl->display(); display() method awaits single parameter $return_html which is FALSE by default. If it is FALSE it will print the contents on the user's screen if you set it to TRUE it will return you as a result the loaded template contents, this could be very useful in some situations like in ajax requests. Example to load template not by default method and get the html contents

$tpl = new template( array(), FALSE ); //some actions here 
$html = $tpl->load(TRUE);

 Figure 3. Sharetronix OPEN SOURCE layout construction
STX DEV Tpl1.png



Layouts control the way the page will be displayed and contain only basic html information for the header, footer and body parts. A layout is loaded by the template. $tpl->useLayout('layout_name');//$tpl is a template object, see above how to load it where 'layout_name' is the name of the layout you want to load( without the .pxp extension).
Available layouts you could find in ./static/templates/layouts/ folder. For example:
$tpl->useLayout('header'); //this will load the header layout
If you load a template by the default way the header will be loaded and saved, and body will be loaded and will be ready to use it. After you load a layout the 'layout' variable in template object is initialized and you could start using it. At a given time only one layout could be initialized in the 'layout' variable. If you initialize another the previous will be saved and after that the new will be ready to use it. After the header is loaded 'page_layout' layout is initialized, it will contains all the body data.
As we said at the begining of this charapter in every layout/block there is template variables in this format {%template_variable%} We could store html information in it. Layouts has such variables and if you want to put some data in it you should first initialize the layout you want to use, let's say you initialized header layout and want to save some data in its variables. To do that use the following format:
$tpl->layout->setVar('var_name', 'var_value');
'var_name' is the name of the value - in the template will be {%var_name%}
'var_value' is the value you want to put in it, lets say Hi.
$tpl->layout->setVar('var_name', Hi');
Then var_name will be replaced by <strong>Hi</strong> in the layout output.
setVar do not save the data in the layout so you can use it again to store more data in the asme variable $tpl->layout->setVar('var_name', '<strong>Hi</strong>'); $tpl->layout->setVar('var_name', '<strong> Again</strong>');
The result in the layout html will be '<strong>Hi</strong><strong> Again</strong>' in the place of {%var_name%} when you use setVar() the vars are stored in array and are saved after saveVars() method is called. This method is called automatically so you do not need to call it by yourself, but if you need it foor some reason you can call it to save your variables.

$tpl->layout->setVar('var_name', '<strong>Hi</strong>');
$tpl->layout->setVar('var_name', '<strong> Again</strong>');

Let's see real world example. We will set '<strong>Hi</strong>' the body. <code >$tpl = new template(); $tpl->layout->setVar('main_content', '<strong>Hi</strong>'); $tpl->load(); </code> As we said above when you call template() the constructor loads the header and loads the body, in the body there is a variable
{%main_content%} in which we set '<strong>Hi</strong>'. when you call load() method it first saves the vars, so you do not have to do it manually. After that load() automatically loads the page footer.  


Blocks are parts of big, pre-usable html content. They are html pieces of code which could be used more than once, or they are too big to load with setVar(). As an example, block is a post. There are many places where posts are loaded. The html content of a post is loaded in the activity.php block. All blocks are loaded in the ./static/template/blocks/ folder. Every block could contain its own variables like the ones in the layout. Blocks are part of the loaded layout, so if you want to load a specific block you should write


which is the name of the block without .php extension. After the block is initialized a variable called 'block' in the layout object is initialized. You could have only one block initialized. To save the block in the layout you shoud specify a place (template variable) where the block will be saved. $tpl->layout->block->save('layout_variable'); //where 'layout_variable' is {%layout_variable%} in the layout. As we said, every block could contain its own template variables and if you want to put some data in it use

$tpl->layout->block->setVar('block_var_name', 'block_var_value'); //the principle is the same as in the layout
//note that setVar() method is called in the block object.

For example lets say we have a block that contains the following content: <!-- block starts here --> <dir> <p> {%block_var%} </p> </div> <!-- block ends here --> Let's do the the same example as the one in the layouts sector, but with blocks

$tpl = new template();
$tpl->layout->block->setVar('block_var', '<strong>Hi</strong>'); $tpl->layout->block->save('main_content');

This will load the 'my-block', set its data and save it in the 'main_content' part of the used layout. See the layout to see available variables. Important!!! In the example above the block has a variable called 'block_var' and it is replaced by html content, but what will happen if you do not set the variable? Let's see: $tpl = new template(); $tpl->layout->useBlock('my-block'); $tpl->layout->block->save('main_content'); $tpl->load(); In this case in the layout the 'main_content' will be replaced by

 <!-- block starts here -->
<!-- block ends here -->

So with other words we included additional variable in the layout, so if you use other block or just use setVar(), there will be one more avalable variable. So we could do this example and the result will be the same

$tpl = new template();
$tpl->layout->setVar('block_var', '<strong>Hi</strong>');

This is a very useful feature of the blocks. But some times you do not want it to happen. If you have for example two posts which place this part twice (some cycle for example as the 10 posts on the dashboard)

<!-- block starts here --> <dir> <p> {%block_var%} </p> </div> <!-- block ends here -->
<!-- block starts here --> <dir> <p> {%block_var%} </p> </div> <!-- block ends here -->

This is what will happen and if you put

$tpl->layout->setVar('block_var', '<strong>Hi</strong>'); 

There are two {%block_var%} so the '<strong>Hi</strong>' will be placed twice on the screen. To prevent this to happen when you save a block the save() method get two parameters 'place' - this is where the block content will be saved delete_vars - FALSE by default, if it is FALSE these vars will not be deleted, TRUE it will be deleted. Example:

$tpl->layout->block->save('main_content', TRUE);


$tpl = new template();
$tpl->layout->block->save('main_content', true);
$tpl->layout->setVar('block_var', '<strong>Hi</strong>');

This will not be valid because with save() parameters set to true 'block_var' will be removed before save.  

Inner Blocks

There are some situations when you will need a block html content to be saved in the another block. For example every post is a html block, post comment is another block. So let's say you have a post with comments, the post block do not contain the comments html data, because it is located in a separete block and will be included only if needed(post has comments). Everything for inner blocks is the same as with the regular blocks, exept 1) To initialize an inner block you shoudl use $tpl->layout->useInnerBlock('my-block'); After you initialize it the variable called 'inner_block' is set in the layout object. 2) To save inner block

$tpl->layout->inner_block->saveInBlockPart( 'block_part' );

where 'block_part' is a part of the current block initialized in the layout. So you will have you have block and after that use inner_block which is reasonable:). Inner blocks could have their own template variables and saveInBlockPart has second parameter which could be set to true to remove template variables in the inner block.



Routines are not a part of the template system, but they could be very helpful. Routines contain template parts reusable initializations or in other words they contains actions which could be used on more than one place so it wont be necessary to write one thing more than one time and when you update a single routine the change will be available on all place where it is used. Routines are located in ./system/helpers/routines/ folder. and their name name starts with 'load' followed by the name of the object they load, for example - loadSingleActivity(); this routine loads a single activity (post). Routines are functions located in file with the same name. They could receive array with parameters, each routine could has different number of parameters in thiss array(). Routines are loaded by the template by using the initRoutine() method, first parameter is the name of the routine you want to load, without the 'load' in the name so we have routine called loadPostform() to load it we call $tpl->initRoutine('Postform', array()); $tpl->routine->load(); After calling initRoutine() method a 'routine' object is created and its method load() starts the routine. In this case we will load the postform block and set all the template variables in it automatically. We choose how to load these variables in the routine itself. Example we have this in the template

$tpl = new template();
$tpl->layout->block->setVar('block_var', '<strong>Hi</strong>');
$tpl->layout->block->setVar('block_var', '<strong>Hi</strong>');
$tpl->layout->block->setVar('block_var', '<strong>Hi</strong>');
$tpl->layout->block->setVar('block_var', '<strong>Hi</strong>');
$tpl->layout->block->setVar('block_var', '<strong>Hi</strong>');

So we do not want to write it everytime so we put in a routine. We have a lot of places where we will need '<strong>Hi</strong>'in the templates. So we create a routine called loadStrongText().

function loadStrongText( $tpl, $params=array() )
//$tpl is a variable which will keep the current loaded template object instance, it is send by automatically and params are eventual 
//paramaters we will need.
//contents from the above
$tpl->layout->block->setVar('block_var', '<strong>Hi</strong>');
$tpl->layout->block->setVar('block_var', '<strong>Hi</strong>');
$tpl->layout->block->setVar('block_var', '<strong>Hi</strong>');
$tpl->layout->block->setVar('block_var', '<strong>Hi</strong>');
$tpl->layout->block->setVar('block_var', '<strong>Hi</strong>');
$tpl->layout->block->setVar('block_var', '<strong>Hi</strong>');

As a result to we will have this code on every place we need it $tpl = new template(); $tpl->initRoutine('StrongText', array()); $tpl->routine->load(); $tpl->load(); We save a lot of writing. This is how the single posts are loaded by using loadSingleActivity() routine.  



Personal tools

STX User guide
STX Developer guide
Sharetronix Sites