How To Design a Pligg Template

In today’s post I will be teaching you the basics for designing a Pligg template. I’ve designed about a dozen Pligg templates so far, and through those experiences I have compiled some quick tips for beginners wanting to create their first Pligg template. Before I dive into the details let me first mention that there is some existing documentation about Template Structure and Template files, which can be read on the Pligg Wiki. This article is a primer for Pligg template designers, and is by no means a good reference for advanced template techniques.

Javascript, CSS and PHP in .tpl Files

Pligg uses a variation of the Smarty template engine, called Template Lite. Smarty code requires special markup when you want to use Javascript, CSS or PHP code in your .tpl files. For Javascript and CSS you will need to begin the code with a {literal} tag and end it with {/literal} tags. For PHP code, you will need to replace the closing tag with {/php}. Examples are provided below to demonstrate each of these languages being used in a Pligg .tpl file.

Javascript Example

{literal}
<script type="text/javascript">
document.write("Hello World!");
</script>
{/literal}

A large number of new threads being created on the forums are by users who attempt to add javascript to their templates without knowing that they should use {literal} tags. If you have added javascript to a .tpl file and you see an error beginning with “Parse error: syntax error, unexpected ‘{‘ ” you more than likely forgot to wrap the javascript with {literal} tags.

CSS Example

{literal}
<style type="text/css">
.example {font-weight:bold;}
</style>
{/literal}

Beginners often overlook CSS files as a good first step for changing the style of your site. Many design projects could probably be completed by only editing the stylesheet file(s). I highly suggest that users start out modifying a Pligg template by tweaking the stylesheet file.

PHP Example

{php}
echo 'Hello World!";
{/php}

You can see more examples of using PHP in .tpl files in the Wiki article “PHP in Template Files“. I will occasionally write entire features into Pligg template files by using {php} tags, which should only be done for very simple {php} code, or when you don’t have time to create a module.

The Top 5 Template Files

Most people who begin a Pligg template without any previous experience will probably feel a little intimidated by the number of .tpl files that Pligg uses. There are roughly 40 files to work with in the stock Pligg template(s). These files control every small detail that a designer might want to take advantage of, but don’t feel like you need to edit all of the files to achieve a unique looking template. You could probably customize just 5 template files and in no time at all your site will look radically different.

1. Pligg.tpl

This template is the main “wrapper” for all other templates. It controls the main layout for the site and includes most of the data located in the of the document. After you’ve finished changing your CSS the pligg.tpl file is the first template file that you should open up and explore.

2. Header.tpl

This template is usually used for navigation for the upcoming, published and submit pages. It is also used commonly to wrap the category, breadcrumb and search box.

3. Sidebar.tpl (and sidebar2.tpl)

As you can guess by the name, these two files are typically used for the sidebar content. It is divided up into two files should you want to have 2 sidebars or use the second sidebar in a more creative position like just before your footer. The sidebar will contain “sidebar widgets” which is what we call things like the “Top Today” or “Latest Comments” modules.

4. Footer.tpl

As you may have guessed by the name, footer.tpl controls the footer content on your website. This is normally used for credits, contact information and site links.

5. Link_summary.tpl

Last, but certainly not least is probably the most misunderstood template file for Pligg. Link_summary.tpl is responsible for styling the story data used by Pligg wherever the story appears. This includes the story data used on the story page, profile page, group page, upcoming page, or third submission step page. It holds the vote number and links, admin tools, story title, story description and a lot of other items. This is probably the most complicated template file to understand because there are so many features in it, but if you take ten minutes to carefully read the code you probably won’t struggle to pick up on how the template is laid out. Because this file deserves it’s own article I will not dive into every detail for this file, but I will emphasize the important features.

Understanding the Language File

The way that Pligg handles language elements is another item that trips up some people. Since we wanted to support as many languages as possible we chose early on to move all of the phrases and words used by Pligg into a single language file. This file can be located in the /langauges directory, and by default Pligg will use lang_english.conf. By making all of the language elements local to one file it makes it easy for users to find words and phrases that they might want to change in their template. Even more important is that it makes it very easy for users to translate Pligg into another language.

You will see language phrases inserted into template files like: {#PLIGG_Visual_Comments_Comment#}. This example would use the language phrase for PLIGG_Visual_Comments_Comment from the language file, which would be the word “Comment”. I’ve copied a small sample from language file below to demonstrate the language file structure.

PLIGG_Visual_Comments = "Latest Comments"
PLIGG_Visual_Comments_Comment = "Comment"
PLIGG_Visual_Comments_Author = "Author"

It’s important for template developers to make use of existing language variables rather than “hard-coding” words into the template to make it easy for others to change the words. One final note about concerning the language file is the updating process. Occasionally we will add new lines to the language file with new releases. To make the update process easier we now will automatically update the language file by adding the new lines to the bottom of your own language file when you run the upgrade script. This is a new feature that was introduced with 1.0.0 and hopefully it has made the upgrade process easier for users who have made an upgrade to 1.0.1.

Resources

I highly recommend that you read and contribute articles on the Pligg Wiki for further reading. The wiki articles are fully editable by any Pligg.com users. If you discover an error or would like to add more complete documentation to an existing thread you can do so by clicking the edit button on the wiki page. The Wiki gives more complex examples for templating and is a great resource for users who want to step it up to the next level.