Quick & Dirty Templating Tutorial for Raffle Factory.
Raffle Factory includes a very powerful templating engine - smarty. We will try to cover in this tutorial the essentials of building a template for Raffle Factory using this Template Engine. By far this can not cover the extensive manual of smarty. Making use of smarty, the auction 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 Raffle 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 Raffle 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 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_bids/templates folder.
The components/com_bids/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.
raffle/t_auctiondetails.tpl - Contains the template for displaying the Raffle Item details page
t_auctiondetails_plugins.tpl - Contains the code snipplet that enables "Listing Upgrade" to Gold, Silver, Bronze
t_categories.tpl - Display of Categories page (Category Directory)
raffle/t_editauction.tpl - is used to display the page for "New Raffle" and "Edit Raffle". The $task smarty variable contains the current task (newauction or editauction)
t_featured_purchase.tpl - display of available Pricing and Fees
t_header_filter.tpl - Displays a message div with the current active filters
t_javascript_language.tpl - Javascript birdge for language strings. Should not be modified in most cases and should be included in most templates
t_listauctions.tpl - The base template for raffle listing. Here are the listing elements being rendered. Most of the output is done in the corresponding *_cell.tpl
raffle/t_listauctions_cell.tpl - The Raffle listing cell. this is the cell for one raffle. The cycling is done in t_listauctions.tpl
t_listfooter.tpl - Listing footer (pagination links).
t_myauctions.tpl - similar to listauctions, only for "My raffles"
raffle/t_myauctions_cell.tpl - similar to listauctions_cell, only for "My raffles"
t_mybids.tpl - similar to listauctions, only for "My Bids"
raffle/t_mybids_cell.tpl - similar to listauctions_cell, only for "My Bids"
t_mywatchlist.tpl - similar to listauctions, only for "My watchlist"
raffle/t_mywatchlist_cell.tpl - similar to listauctions_cell, only for "My watchlist"
t_mywonbids.tpl - similar to listauctions, only for "My won bids"
raffle/t_mywonbids_cell.tpl - similar to listauctions_cell, only for "My won bids"
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_search.tpl - Template for the search page
t_showSearchResults.tpl - Template for the Search Results
t_tags.tpl - Template for the Tags selection
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 "newauctions" - 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=='newauctions'}You are creating a new auctions{else}You are editing an existing auction{/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 it useful for us in the matter of including the necessary javascript for the auctions. 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 RAFFLE 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 (Raffle).
* {set_css} - prints out the Raffle 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 raffle system.
* {$mosConfig_live_site} - the url of the site. as defined in Joomla Configuration
* {$Itemid} - The menu Itemid
* {$task} - the current task
* {$option} - the current option (should always be com_bids)
* {$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
All Language constants and configuration constants are accesible in the template; all are in the form {$smarty.const.xxxx} where xxxx is the contant name. For instance for the constant string defined as "bid_auction_number" you have to use {$smarty.const.bid_auction_number}. All saved options are the following:
* bid_opt_max_picture_size - max image size in kb
* bid_opt_date_format - Date format string (PHP style)
* bid_opt_date_time_format - Hour format string (PHP style)
* bid_opt_thumb_width - Thumbnail width
* bid_opt_thumb_height - Thumbnail height
* bid_opt_medium_width - Raffle Detail page image width
* bid_opt_medium_height - Raffle Detail page image height
* bid_opt_availability - max months that an raffle can last
* bid_opt_maxnr_images - max nr of images allowed for an raffle
* bid_css - css file
* bid_opt_min_increase - bid increment
* bid_opt_allow_messages - True if messages are allowed between auctioneer and bidder
* bid_opt_allow_proxy - true if proxy bidding is enabled
* bid_opt_archive - max moths that auctions are kept in the database
* bid_opt_nr_items_per_page - pagination
* bid_opt_allow_import - allow bulk import by the users
* bid_opt_enable_hour - enable hour for auctions (if false then auctions expire on midnight)
* bid_opt_enable_countdown - enables the countdown in auctions listings
* bid_opt_language - language file
* bid_opt_RSS_title - RSS feed title
* bid_opt_RSS_description - RSS feed decription
* bid_opt_RSS_nritems - max items in RSS
* bid_opt_RSS_feedtype - RSS feed type
* bid_opt_enable_acl - true if the site uses ACL (Access Class lists ) - Bidder and Seller group
* bid_opt_acl_type - Acl type - groups or field
* bid_opt_acl_bidder - Bidder group
* bid_opt_acl_seller - Seller Group
* bid_opt_max_nr_tags - max tags allowed for an raffle
* bid_opt_allowpaypal - allow users to specify their paypal email in order to facilitate the funds transfer
* bid_opt_allow_nr_tickets - Allow nr of tickets at new raffle create
* bid_opt_require_nr_tickets - Require nr of tickets
* bid_opt_allow_end_date - Allow user to select an end date to a raffle
* bid_opt_require_end_date - Require the end date when a raffle is created
5. Raffle Variables initialized in specific pages.
5.1. Variables initialized in Raffle Details and Raffle listings.
For raffle detail the main object is called $auction, in auction listings the cell templates will hold a similar object called $current_row The properties of $auction and $current_row are similar. We will present them for $current_row. If you need them in Raffle details or in Raffle Edit/New you must replace "$current_row" with "$auction"
* $current_row->id // The Raffle ID - Needed for specific calls
* $current_row->userid // The Auctioneer USER-ID (Joomla native)
* $current_row->title // The Raffle TITLE
* $current_row->shortdescription // The Raffle Short description
* $current_row->description //The Raffle Description
* $current_row->picture // The raffle MAIN picture name (not the URL!)
* $current_row->link_extern //The external link (Settable by the auctioneer)
* $current_row->initial_price // The Raffle initial price - as an float. for formatting use {$auction->initial_price|string_format:"%.2f"}
* $current_row->currency // The Currency ID (Not the currency name!)
* $current_row->currency_name // Currency Name (Ex. USD)
* $current_row->auction_type //The Raffle Type public auctions =1, private auctions=2
* $current_row->automatic // If true, then the raffle is automatic
* $current_row->payment // Chosen payment type ID
* $current_row->payment_name // Payment Method Name
* $current_row->shipment_info // The Raffle shipment info
* $current_row->start_date //Start date of the Raffle in a datetime type (not formatted)
* $auction->start_date_text //Start date of the Raffle in a datetime type (formatted)
* $current_row->end_date //End date of the Raffle in a datetime type (Not formatted)
* $auction->start_date_text //End date of the Raffle in a datetime type (formatted)
* $current_row->closed_date //Closing date of the Raffle. To format use {printdate date=$auction->closed_date}
* $current_row->published // True if published. Just for MY Auctions
* $current_row->close_offer // True if Raffle is closed
* $current_row->close_by_admin //True if Raffle is BANNED - just for MY Raffle
* $current_row->hits // Nr of hits
* $current_row->featured //"gold","silver","bronze" or "none"
* $current_row->modified // Last edit time - not formatted, use printdate
* $current_row->newmessages// True if New messages are available for the current looged user in this auction
* $current_row->winner_id // Winner userid.
* $current_row->ticket_price // The price per ticket if any
* $current_row->i_am_winner // true if the current logged user is winner in this auction
* $current_row->winners // list of selected winners by stage reached
* $current_row->nr_bidders // Number of raffle buyers
* $current_row->nr_tickets_bought // Number of raffle tickets bought
* $current_row->nr_tickets_available // Number of tickets available
* $current_row->cat // Category id (NOT category name)
* $current_row->catname // Category Name (Ex. Automobiles)
* $current_row->auction_nr // AUN (Auction Unique Number)
* $current_row->username //auctioneer Username
* $current_row->verified_auctioneer //True if auctioneer is verified
* $current_row->rating_auctioneer // Rating as a seller for the auctioneer
* $current_row->rating_bidder // Rating as a bidder for the auctioneer
* $current_row->rating_overall // Overall auctioneer rating
* $current_row->auctioneer // object containing the auctioneer joomla user info
* $current_row->auctioneer_details // object containing Auction Factory relevant Auctioneer User info (city, country,..)
* $current_row->tags // Raffle related tags - use $current_row->links.tags to display links
* $current_row->rownr // Current number (for cells only)
* $current_row->nr_new_messages // Nr of new messages in this auctions message board for the current user
* $current_row->is_my_auction // True if the current logged user is also the auctioneer of the auction
* $current_row->del_from_watchlist //true if current raffle IS in the users watchlist
* $current_row->add_to_watchlist //true if current raffle IS NOT in the users watchlist
* $current_row->countdown //if show countdown is enabled contains the current countdown text (Ex: "2 days,2 hrs,10 min,2secs")
* $current_row->expired // True if the raffle is expired (the end date is passed)
* $current_row->thumbnail //countains the thumbnails html code.
* $current_row->links.otherauctions // contains the url to "Other auctions by this auctioneer"
* $current_row->links.bids // Contains the link to the current bids of the auction
* $current_row->links.edit // Contains the link to "Edit this auction"- just for my raffles
* $current_row->links.cancel //Contains the link to "Cancel this auction"- just for my raffles
* $current_row->links.publish //Contains the link to "Publish this auction"- just for my raffles
* $current_row->links.republish //Contains the link to "Republish this auction"- just for my raffles
* $current_row->links.filter_cat //Contains the link to the category filter for the auctions category
* $current_row->links.messages //Contains the link to the message list for the current raffle
* $current_row->links.add_to_watchlist //Contains the link that adds the current auction to the users watchlist
* $current_row->links.del_from_watchlist //Contains the link that removes the current raffle to the users watchlist
* $current_row->links.tags // contains the links for the tags of the current raffle
* $current_row->links.auctioneer_profile // contains the link to the auctioneer profile
5.2. Variables for search template.
* {$lists.cats} - category pick up list HTML code
* {$lists.country} - country pick up list HTML code
* {$lists.city} - city pick up list HTML code
* {$lists.users} - Users pick up list HTML code
5.3. Variables for Raffle details.
* {$auctioneer} - contains the object that defines the Joomla user
* {$auctioneer_details} - contains the object that defines the Auctioneer details (city, country, verified..)
* {$bid_list} - the list of tickets bought on this raffle
* {$message_list} - list of messages to the current user
* {$terms_and_conditions} - true if there are terms and conditions to accept
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.
There are virtually no security issues in changing the templates. The data that should not appear is also not initialized (lets say for a private raffle). But caution is always a good approach, so test first what kind of raffle or what kind of rights are currently active.
MOST IMPORTANT OF ALL: do not hesitate to search and to ask! The forums are a great place to share information.
Revised "Raffle Factory" version 1.0.x.
