Quick & Dirty Template Tutorial for Ads Factory.

Ads Factory includes a very powerful template engine - smarty. We will try to cover in this tutorial the essentials of building a template for Ads Factory using this Template Engine. By far this cannot cover the extensive manual of smarty. Making use of smarty, the ads engine will provide to this engine some pre-filled objects and arrays of objects that are relevant to the current page displayed. Also all language constants defined in Ads Factory can be accessed in the template. 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 Ads Factory Component. For most users the default template should contain all the necessary information.

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 our case most are auction related.

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. Where are the files and what can be changed?

All template files are in the components/com_adsman/templates folder.

The components/com_adsman/templates/cache folder contains the pre-processed files and normally you should not have to edit or delete something in it. We recommend that this folder has writing rights for PHP scripts, so the engine can improve the speed by caching the templates.

  • adsman.css  -  Component css file
  • googlemap_tool.tpl  -  Google map selector for user profile page
  • t_buy_contact.tpl  - Template for buy contact plugin
  • t_catlist.tpl  -  Category list template
  • t_details_add.tpl  -  Contains the template for displaying the Ad Item details page
  • t_details_add_plugin - Contains the code snipplet that enables "Listing Upgrade" to Gold, Silver, Bronze
  • t_editadd.tpl - is used to display the page for "New Ad" and "Edit Ad". The $task smarty variable contains the current task (newadd or editadd)
  • t_featured_purchase.tpl - Display of available Pricing and Fees
  • t_googlemap.tpl  - The googlemap template included / or not ( can configure this) in ad detail page
  • t_javascript_language - Javascript birdge for language strings. Should not be modified in most cases and should be included in most templates
  • t_list.tpl  - The regular mode listing template
  • t_list_grid.tpl - The grid mode listing template
  • t_favorites.tpl  - The regular mode favorite ads listing template
  • t_favorites_grid.tpl - The grid mode favorite ads listing template
  • t_myadds.tpl  - The regular mode personal ads listing template
  • t_myadds_grid.tpl - The grid mode personal ads listing template
  • t_myuserdetails.tpl – My user details template
  • t_overlib.tpl  - JS for overlib. Should be included if overlib is used
  • t_payment_cancel.tpl  - Returning page from Paypal if the payment was canceled
  • t_payment_return.tpl  - Returning page from Paypal on successful payment (can be overridden in the payment plugin)
  • t_report.tpl  - Template for reporting an ad page
  • t_search.tpl  - Template for the search page
  • t_userdetails.tpl – User view details template


2. Basic smarty knowledge.

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 {$task} will be replaced with the current Joomla task (for instance with "newadd" - without the quotation marks).

Smarty also allows IF clauses, so you an branch out two different displays depending on a condition. So for example {if $task=='newadd'}You are creating a new ads{else}You are editing an existing ad{/if} will display one of the two texts depending on the current task. Another useful smarty command is {include file='xxxxx'} - this includes another smarty template file. For instance it is useful for us in the matter of including the necessary Javascript for the ads. Since most pages use the same Javascript codebase we can have just a single page containing these statements. For assigning a value to a variable (if the variable does not exist, it will be created) you have to use {assign var=variablename value='VALUE'} in this way you may use smarty for advanced templating techniques that resembles more with programming.

3. Custom defined smarty functions for Ads Factory.

Since Smarty is a very powerful tool for templates, 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 (Ads).

  • {set_css} - prints out the Ads CSS
  • {infobullet text="some info text"} - creates a standard joomla help bullet (requires overlib to be initalized first)
  • {printdate date=$some_date_variable use_hour=0} - prints out the date variable according to the datetime format chosen in admin backend (use_hour=0 - ignores hours, use_hour=1 prints also the time)
  • {createtab} - initalizes the Tabbed output (joomla standard)
  • {startpane id="content-pane" usecookies=0} - starts the Tabbed pane (the container that holds all tab pages). the usecookies setting can be set to 1, leading to the tabbed display to remember what particular tab was last time active when you visited that page
  • {endpane} - ends a previously started tabbed pane
  • {starttab paneid="content-pane" text="Tab caption"} - Starts a new TAB in the pane with the id "content-pane" (you must use the id from the startpane call)
  • {endtab} - Ends a TAB


4. Variables that are ALWAYS initialized by the auction system.

  • {$Itemid} - The menu Itemid
  • {$ROOT_HOST} - the url of the site. as defined in Joomla Configuration
  • {$is_logged_in} - true if the user is logged in. false if not
  • {$userid} - the joomla user id. if not logged in it will be null or 0
  • {$opt_date_format}
  • {$option} - the current option (should always be com_ads)
  • {$resetFilters} url


5. Ads Variables initialized in specific pages.

5.1. Variables initialized in Ads Details and Ads listings. 

For ads detail the main object is called $add, in ads listings will be a similar object called $item. The properties of $add from detail page and $add from list are similar.

  • id, // The ad ID - Needed for specific calls
  • title,// The ad Title
  • short_description, // The ad short description
  • description,// The ad description
  • start_date,
  • end_date,
  • addtype (1 or 0  ie public or private ),
  • userid,// The Ad USER-ID (Joomla native)
  • askprice,
  • currency( ID ),
  • picture,
  • hits,
  • status,
  • close_by_admin,
  • closed,
  • closed_date,
  • newmessages, // True if New messages are available for the current logged user in this ad
  • featured = "none"
  • tags = Array (3) of tags associated
  • catname string of category
  • currency_name = "USD"
  • favorite added or not to favorite
  • start_date_text,
  • end_date_text,
  • countdown = "15 days, 04:06:58"
  • expired bool
  • messages = Array (0)
  • is_my_add = true
  • links = Array (12)
       otheradds, details, edit, republish, cancel, user_profile, report,
       filter_cat,  add_to_favourite,  del_from_favourite, terms, tags
  • thumbnail
  • gallery   

5.2. Listing Pages.

Favorites listings, my ads are including listing template. For custom templating you can just copy the content from listing template into favorites and modify it.  

{$item}

  • id,
  • category (ID),
  • title,
  • short_description,
  • description,
  • start_date,
  • end_date,
  • addtype (1 or 0 – private or public)
  • status = "1",
  • userid,
  • askprice = "150",
  • currency (ID)
  • picture = "1_87287304_9ba820e2be.jpg"
  • featured = "none"
  • hits = "0"
  • close_by_admin(state),
  • newmessages (state),
  • closed (state),
  • closed_date,
  • username,
  • thumbnail,
  • countdown = "15 days, 04:01:23"
  • expired (state)
  • start_date_text
  • end_date_text
  • tags = Array (3)
      0 => "joomla"
      1 => "joomfish"
      2 => "fact"
  • links = Array (12)
      otheradds, details, edit,  republish, cancel, user_profile, report,
      filter_cat, add_to_favourite, del_from_favourite, terms, tags (text tags)
  • favourite(state)
  • catname

5.3. Category Page.

Display listing of categories as tree. Array {$categories} contains objects of categories with subcategories with same structure.  Array () of  

  • id
  • catname
  • descr = ""
  • parent (ID)
  • hash
  • ordering = "1",
  • watchListed_flag = 0,
  • link_watchlist,
  • img_src_watchlist,
  • link,
  • subcategories = Array (0) with the same structure

Revised "Ads Factory" version 1.3.5.