Archived ⇒ Templating guidelines

Hi all;

I have been trying to get a complete understanding of the templating system so that any module that I port will be completely template compatible. I also noticed DJ's post about things that need to be done -- templating of existing modules was included in that list. So, I figured, what better way to get more experience with the templating system, and help with the development to get the feature freeze lifted, than to convert existing modules to the templating system?

I started with the Contact module this morning... yeah, simply because it's an easy one, and it was the first in my directory of modules!

From looking at various modules, trying to get a good grasp on the system, I noticed that there were inconsistancies, which brings me to a couple of questions. I also think answering these questions here may also get some good information posted here that the DocuMentors can take advantage of, and eventually make a Wiki page for it.

Because the Downloads Pro module is the latest out, I have, mostly, used that as a reference and started using the same naming conventions. Discussing this here will also help us determine a standard for naming theme variables.

So far I have been using the following;

I_SOMENAME for Images
I_, is used to store images.

L_SOMENAME for Lables (or Lang?)
L_, is used for label (lang) definitions.

U_SOMENAME for URL's
U_, is used to store URL's (links)

S_SOMENAME for ?? (don't know what the S_ stands for)
S_, is used to store all other data, such as $sitename, or $username, etc. Variables that are, usually, after a label --> {L_SOMELABEL}: {S_SOMEDATA}


So, what does the S_ stand for? Are these all the naming conventions used within a template? Any comments, tips, tricks or suggestions? Please post what you know about the templating system so that we may all better understand it and continue it's development.

PS - I don't have a problem getting the templates to work, this post is designed more to get people talking about the templating system (such as the use of assign_vars and assign_block_vars, etc., etc.) and create a set of standards to use within. All comments are welcome and appreciated.

When working with the code, I've always read the S_'s as String. I'm not sure if that is correct or not though, since it does seem to be used for everything not captured in the I, L, and U groups.

I've encountered some other common ones:

B_L_xxx -or- B_R_xxx refers to a left or right block
G_xxx refers to a graphic(image)

S_ = String! Oh, how obvious was that? Thanks, Brennor!

OK, how about assign_vars and assign_block_vars today? It took me a bit when first looking at those to figure out what the difference was and when to use each one.

Both assign_vars and assign_block_vars take on, basically, the same syntax, but do very different things. The sytax, or structure, of assign_vars is like so;

$cpgtpl->assign_vars(array( 'L_LABEL' => _SOMELABEL, 'I_IMAGE' => $someimage, 'U_URL' => $someurl, 'S_STRING' => $somestring ));

and assign_block_vars;

$cpgtpl->assign_block_vars('block_label', array( 'L_LABEL' => _SOMELABEL, 'I_IMAGE' => $someimage, 'U_URL' => $someurl, 'S_PROJECTNAME' => $somestring ));

The major difference between the two functions is that assign_vars is used to hold simple variables, where each defined key of the array holds one value. assign_block_vars does basically the same thing, except each defined key will hold multiple values.

Now, for using these variables inside an html template. Let's use the forums to think about the use of each. Take the main forum index, for example. The page is created with a table of information, with labels at the top of each column. These labels are used once (although they can be used as many times in the template as you wish) and will be assigned with assign_vars. To use these labels you would simply use the name of the defined variable, wrapped in curly brackets, like so {L_SOMELABEL}. An example of creating a table with column labels, is like so;

<table class="forumline" align="center" width="100%" border="0" cellspacing="1" cellpadding="3"> <tr> <th width="100%" colspan="2">{L_SOMELABEL}</th> <th align="center">{L_SOMEOTHERLABEL}</nobr></th> <th align="center">{L_YETANOTHERLABEL}</nobr></th> </tr>

Now, creating multiple rows of data underneath these labels is where we're going to use assign_block_vars. If you think about a while routine as a 'block' of code that is executed, it will help understanding assign_block_vars.

while (list($var1, var2, var3) = $db->sql_fetchrow($result)) { [i]this code gets run as long as the while routine returns true (as long as there is data coming from the database)[/i] }

As you can see from the code above, the more the while routine runs, the more data is created and needs to be defined so we can use them inside our template. Using assign_vars would not work here as the first time the routine is run $var1, $var2 and $var3s data would be defined, and each successive time the routine is run, the previous data would be over-written with the newly assigned data. Once the routine is finished, we would only have one set of variables, which would be the last set to come from the database... not what we want.

To solve this, we use assign_block_vars. assign_block_vars stores the data in rows of an array, with each row being unique. Let's take a look at the while block, with assign_block_vars in place.

while (list($var1, var2, var3) = $db->sql_fetchrow($result)) { [i]this code gets run as long as the while routine returns true (as long as there is data coming from the database)[/i] $cpgtpl->assign_block_vars('block_label', array( 'S_VAR1' => $var1, 'S_VAR2' => $var2, 'S_VAR3' => $var3 )); }

Using our example of the forums, we are now trying to display multiple rows underneath our column labels, which represent multiple threads in the forum. Let's say we're trying to display topic, author and last post date (to use our 3 vars above). We cannot simply use the variable, wrapped in curly brackets, as we did above. Why? Because we are holding multiple rows of data and the system needs to know which row to display, and to keep displaying rows until there are no more. We do this, inside the html template, by using BEGIN and END.

Accessing the variables is also different than we did with assign_vars, as we need to know which set of variables we want to access. This is done by adding the name/label of the block to the variable you want to display, like so --> {block_label.S_VAR1}

<!-- BEGIN project_rows --> <tr> <td class="row1" align="center" colspan="2">{project_rows.S_VAR1}</td> <td class="row1">{project_rows.S_VAR2}</td> <td class="row1" align="center">{block_label.S_VAR3}</td> </tr> <!-- END project_rows -->

There are two important parts to using assign_block_vars.

1) you assign a name, or label, to the block variables (block_label was used above as an example) so that you have something to reference the block variables with.

2) you use BEGIN and END to loop through and display the block variables.

Well, that's about all I can think of regarding assign_vars and assign_block_vars right now.... as usual, comments are welcome and appreciated.