Quick & Dirty Templating Tutorial for Love Factory
Love Factory includes a very powerful templating engine - Smarty. We will try to cover in this tutorial the essentials of building a template for Love Factory using this Template Engine. By far this can not cover the extensive manual of Smarty. Making use of Smarty, the Love Factory engine will provide to this engine some pre-filled objects and arrays of objects that are relevant to the current page displayed. We advice against writing hard coded text into the Templates, since this would render the multi language concept useless. If you do not care about the ability to translate your site, then you can do as needed.
This tutorial is addressed to the HTML savvy webmaster that need to change the default appearance of Joomla's Love Factory Component. For most customers the default template should be sufficient accommodating.
First of all what is a template engine. A (web) template engine is software that is designed to process web templates and content information to produce output web documents. It runs in the context of a template system. It is practically a php script that interprets some kind of pseudo HTML pages containing placeholders for specific variable content.
In order to update much easier, we recommend that you note all the changes made on the templates, then apply them on each update in order to avoid any issues!
1. Before we start...
First of all you must enable the use of Smarty Templates. This can be done by checking the "Use Smarty Templates" option in the admin backend (Settings -> General tab). Here you will find the full path to the templates. Usually the location is: [Joomla Location]/components/com_lovefactory/smarty/templates
2. Where are the files and what can be changed?
As mentioned before, the folder containing the templates is [Joomla Location]/components/com_lovefactory/smarty/templates. The components/com_lovefactory/templates/cache folder contains the pre-processed files and normally you should not have to edit or delete something in it. We recommand that this folder has writing rights for PHP scripts, so the engine can improve the speed by caching the templates.
- blacklist/view.tpl - Contains the template for displaying the Blacklisted (or Ignored) users
- friends/view.tpl - Contains the template for displaying the Friends list
- friends/pending.tpl - Contains the template for displaying the Pending Friendship Request list
- interactions/view.tpl - Contains the template for displaying the received Interactions list
- mailbox/error.tpl - Contains the template for displaying an error in case the Messaging System is disabled in the admin, but the user still tries to access it
- mailbox/inbox.tpl - Contains the template for displaying the list of all the received messages
- mailbox/outbox.tpl - Contains the template for displaying the of all the sent messages
- mailbox/read.tpl - Contains the template for displaying a received or sent message
- mailbox/write.tpl - Contains the template for displaying the form for writing a new message
- mailbox/_menu.tpl - Contains the template for displaying the Mailbox menu
- memberships/buy.tpl - Contains the template for displaying a list with all the memberships
- memberships/cancel.tpl - Contains the template for displaying a message when the users cancels a payment
- memberships/comparison.tpl - Contains the template for displaying a comparison list between all the memberships
- memberships/complete.tpl - Contains the template for displaying a message when a user completes a successful payment
- memberships/confirm_moneybookers.tpl - Contains the template for displaying a confirmation message when using Moneybookers
- memberships/confirm_paypal.tpl - Contains the template for displaying a confirmation message when using Paypal
- memberships/error.tpl - Contains the template for displaying an error message, if one occurs
- profile/banned.tpl - Contains the template for displaying a message if the user has been banned
- profile/edit.tpl - Contains the template for displaying the edit profile page
- profile/error_guest.tpl - Contains the template for displaying an error if a guest tries to accees a page available only for the registered users
- profile/error_registered.tpl - Contains the template for displaying an error if a registered user tries to register again
- profile/signup.tpl - Contains the template for displaying the registration form
- profile/view.tpl - Contains the template for displaying the user profile page
- profile/view_friends.tpl - Contains the template for displaying a message if a non-friend user is trying to access a profile available only for friends
- profile/view_offline.tpl - Contains the template for displaying a message if a user tries to access a offline profile
- profile/_comments.tpl - Contains the template for displaying the comments on the profile page
- search/advanced.tpl - Contains the template for displaying the form for an advanced search
- search/online.tpl - Contains the template for displaying the online users
- search/quick.tpl - Contains the template for displaying the form for a quick search
- search/_list.tpl - Contains the template for displaying the results from the "search/advanced.tpl", "search/online.tpl" and "search/quick.tpl" templates
- search/_sort.tpl - Contains the template for displaying the sort options for the "search/advanced.tpl" and "search/quick.tpl" templates
- terms/default.tpl - Contains the template for displaying the Terms and Conditions
All smarty templates are pure HTML. What the template engine needs to interpret must be put in accolades { }, a so called smarty tag. If the smarty contains a variable or a constant, then smarty just replaces it with its value. for instance this tag {$Itemid} will be replaced with the current joomla Itemid (for instance with "56" - without the quotation marks).
Smarty also allows IF clauses, so you can branch out two different displays depending on a condition. So for example {if $message eq ''}The message is empty{else}The message is NOT empty{/if} will display one of the two texts depending on the current message. Another useful smarty command is {include file='xxxxx'} - this includes another smarty template file.
4. Custom defined smarty functions for Love Factory.
Since Smarty is a very powerful tool for templating, we can create custom functions that can be called out from templates. Functions that are not in the standard distribution of smarty. We created following functions that can be used especially for our purpose.
* {jroute route='index.php?option=com_lovefactory&view=friends&layout=view&Itemid=%Itemid%&id=%id%' Itemid=56 id=9} - creates a Joomla page link using the routing system.
* {jtext _='Some text to be translated'} - translates the text using Joomla's translation system.
4. Variables that are ALWAYS initialized.
* {$Itemid} - The menu Itemid
5. Variables initialized in specific pages.
5.1. Variables initialized in blacklist/view.tpl
* $count - total number of users on the Blacklist (or Ignore list)
* $blacklist - array containing all the users on the Blacklist. Each element of the array has the properties: sender_id (the user that blacklisted), username (the username of the blacklisted user), date (the date when it happened), id (the id from the database of the current blacklist entry).
* $pagination - Joomla pagination object containing the pagination links. To access the links you must use the method getPagesLinks() on the pagination object (eg: $pagination->getPagesLinks())
5.2.1. Variables initialized in friends/view.tpl
* $layout - contains the current layout, it's required for the menu, to highlight the current layout
* $friends - array containing all the friends
* $pagination - same as blacklist/view.tpl
5.2.2. Variables initialized in friends/pending.tpl
* $layout - contains the current layout, it's required for the menu, to highlight the current layout
* $friends - array containing all the pending requests
* $pagination - same as blacklist/view.tpl
5.3. Variables initialized in interactions/view.tpl
* $interactions - array containing all the interactions
* $pagination - same as blacklist/view.tpl
5.4.1. Variables initialized in mailbox/inbox.tpl
* $messages - array containing all the received messages
* $pagination - same as blacklist/view.tpl
5.4.2. Variables initialized in mailbox/outbox.tpl
* $messages - array containing all the sent messages
* $pagination - same as blacklist/view.tpl
5.4.3. Variables initialized in mailbox/read.tpl
* $message - the messege being read. Has the following properties: isSent(), isReceived() - checks if the message was sent or received; getReceiverName(), getSenderName() - retrieves the receiver name or the sender name; date - the date when it was sent; title - the title; text - the text; isSystemMessage() - checks if the message was sent automatically by the system; reported - checks if the message has been reported
* $blacklisted - the blacklist status of the sender/receiver
5.4.4. Variables initialized in mailbox/write.tpl
* $message - containes the messages being replyed to in case the user writes a reply
5.5. Variables initialized in memberships/buy.tpl
* $prices - array containing all the published membership prices set in backend
5.6.1. Variables initialized in profile/edit.tpl
* $page->description - description about the current page, set in backend
* $zones - array containing the zones and fields for the edit page
* $settings - array containing all the settings set in backend
* $profile - array containg all the information about the current profile
5.6.2. Variables initialized in profile/signup.tpl
* $page->description - description about the current page, set in backend
* $zones - array containing the zones and fields for the signup page
* $settings - array containing all the settings set in backend
5.6.3. Variables initialized in profile/view.tpl
* $page->description - description about the current page, set in backend
* $zones - array containing the zones and fields for the view page
* $settings - array containing all the settings set in backend
* $profile - array contain all the information about the current profile
* $my_profile - checks if the profile belongs to the current user
* $friend - information about the friendship status between the users, if the profile doesn't belong to the current user
* $blacklisted - information about the blacklist status between the users, if the profile doesn't belong to the current user
* $friends - array contain the latest friends of the user
5.6.4. Variables initialized in profile/_comments.tpl
* $comments - array containing the comments
* $pagination - same as blacklist/view.tpl
* $user - information about the current user
* $id - the user id of the current profile
5.7.1. Variables initialized in search/advanced.tpl
* $page->description - description about the current page, set in backend
* $zones - array containing the zones and fields for the advanced search page
5.7.2. Variables initialized in search/quick.tpl
* $page->description - description about the current page, set in backend
* $zones - array containing the zones and fields for the quick search page
5.7.3. Variables initialized in search/_list.tpl
* $results - array of users matching the current search
* $profile_zones - array containing the zones and fields for the profile search
* $pagination - same as blacklist/view.tpl
5.8. Variables initialized in terms/default.tpl
* $terms - containes the text for the terms and conditions
6. Final advices and considerations.
Before starting to work on the templates take a look at the provided ones, and try to understand how they are done. Leave all hidden inputs as they are. If unsure better ask in our forums. Remove the inputs from the template only if sure what you do. you can put them where you like on the page, but if you what to remove one better ask.
Test if your changes generate JS errors. These could alter the behavior of the pages.
MOST IMPORTANT OF ALL: do not hesitate to search and to ask! The forums are a great place to share information.
