Quick & Dirty Templating Tutorial for Auction Factory (starting with version 1.4.x and above).
As of Version 1.4.0 Auction Factory includes a very powerful templating engine - smarty. We will try to cover in this tutorial the essentials of building a template for Auction 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 Auction 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 Auction 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.
t_auctiondetails.tpl | Contains the template for displaying the Auction 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) |
t_editauction.tpl | is used to display the page for "New Auction" and "Edit Auction". 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 auction listing. Here are the listing elements being rendered. Most of the output is done in the corresponding *_cell.tpl |
t_listauctions_cell.tpl | The Auction listing cell. this is the cell for one auction. The cycling is done in t_listauctions.tpl |
t_listfooter.tpl | Listing footer (pagination links). |
t_myauctions.tpl | similar to listauctions, only for "My auctions" |
t_myauctions_cell.tpl | similar to listauctions_cell, only for "My auctions" |
t_mybids.tpl | similar to listauctions, only for "My Bids" |
t_mybids_cell.tpl | similar to listauctions_cell, only for "My Bids" |
t_mywatchlist.tpl | similar to listauctions, only for "My watchlist" |
t_mywatchlist_cell.tpl | similar to listauctions_cell, only for "My watchlist" |
t_mywonbids.tpl | similar to listauctions, only for "My won bids" |
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 AUCTIONS 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 (Auctions).
4. Variables that are ALWAYS initialized by the auction system.
All Language constants and configuration constants are accessible in the template; all are in the form {$smarty.const.xxxx} where xxxx is the constant 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:
5. Auction Variables initialized in specific pages.
5.1. Variables initialized in Auction Details and Auction listings.
For auction 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 Auction details or in Auction Edit/New you must replace "$current_row" with "$auction"
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 auction). But caution is always a good approach, so test first what kind of auction 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 "Auction Factory" version 1.4.0.
First you must login as a registered user. To register you must provide your username and a valid email. The Email is important since you will receive your communications regarding your articles through email. After you login you should see your user menu like this:
Click on the My Articles and you will be forwarded to the new screen like this:
1. Article Title - just put the Title of the article here. 2. Section - choose the appropriate Section for your Article. If none applies then pick the "other" section. 3. Categories - choose the most accurate category for your article. This will increase the chances in search engines like Google, and also will help your article not being rejected. 4. Publish Date - you can choose a date in the near future for your article to be published (useful for products not launched yet). 5. Intro Text - it is a short text that will appear on the frontpage of our site and should be a introduction to the article itself. It should not be a summary, since this introduction will appear as the first paragraph of the whole article. so do not repeat it in the main text. Also this Intro text does not allow you using HTML tags. 6. Main Text - this is the main article. There are some html tags allowed. Most important is that you can add up to 4 links to your article in any place you want. Use the Resource box for your signature, do not repeat it in the main article. 7. Preview Button - use it to see a preview of your article with the Site CSS. 8. Meta Description - you may add your own meta info to the article. |
9. Meta Keywords - you may add your own meta info to the article. Meta Description and Keywords will appear in the header of the article page.
10. Resource Box - you may change your resource box for any article, but its recommanded to save the most used in your resource box section in order to have it always at hand. There are no HTML tags allowed besides link tag (<a>). You may add 2 links in your Resource box.
Tips regarding submitting a New Article:
This Tutorial is compliant with Article Factory Manager 1.0.0.
Requirements > Auctions Factory (at least version 1.0.2) with option "Allow users to import from CSV" set to yes.
A new button will appear into "My Auctions" - "Import from CSV". By pressing the button you are taken to the import area. There you can specify a CSV file and a ZIP containing the images for the Auctions in the CSV. The zip MUST not contain Folders or pictures in folders. Zip all images into one file.
The CSV must be TAB delimited with NO HEADER ROW!
The structure for the CSV MUST be the following (please keep the exact field order):
USERID | Joomla Userid (will be ignored for frontend bulk upload, but must be present as field) - this is the id before the user in the userlist (admin). If empty or not a number - the uploading user will be used instead | EXAMPLE | |
Auction Title | Auction Title | 2001 Porsche : Boxster Speedster | |
Shortdescription | The short Description | Miles:70800 | |
Description | The Long description (can contain HTML) | This is a highly modified Porsche Boxster S. As you can tell, I have had a lot of extras added to the body and the engine. The body was modified by adding, a TechArt GT3 front bumper, rear diffusers, a wing on the lid of the trunk, sport spring suspensions, K&N air filters, fuel mapping for the new CPU and the rest of the Power Kits from Gemballa. | |
Main Picture | Picture that appears on the Auctions list | auction37_main.JPG | |
External link | link to some external info | http://porsche.com | |
Initial Price | starting bid price (can't be 0) | 22000 | |
Currency | USD,EUR…. From the list that is available on the site | USD | |
BIN Price | Buy it now price | 25000.99 | |
Auction type | public/private | public | |
Automatic | 1=yes / 0 = no | 1 | |
Payment type | Text from the list available in the site | VISA / MASTER CARD | |
Shipment info | Shipment description & info | Buyer pays for shipping | |
Start Date | date when the auction starts (required to be filled in) | 2007-11-29 | |
End Date | date when the auction ends (required to be filled in) | 2010-11-29 17:00 | |
Param Picture | 1=yes / 0 = no | 1 | |
Param Additional Pic | 1=yes / 0 = no | 1 | |
Param Autoaccept Bin | 1=yes / 0 = no | 1 | |
Param Show Bid Counts | 1=yes / 0 = no | 1 | |
Param Show Max price | 1=yes / 0 = no | 1 | |
Param Published | 1=yes / 0 = no | 1 | |
Category | Text from the list available in the site | Cars | |
Picture_1 | Additional picture (not more then allowed on site) | auction36_1.JPG | Optional |
Picture_2 | Additional picture (not more then allowed on site) | Optional | |
Picture_3 | Additional picture (not more then allowed on site) | Optional | |
Picture_4 | Additional picture (not more then allowed on site) | Optional | |
Picture_5 | Additional picture (not more then allowed on site) | Optional | |
Picture_6 | Additional picture (not more then allowed on site) | Optional | |
Picture_7 | Additional picture (not more then allowed on site) | Optional | |
Picture_8 | Additional picture (not more then allowed on site) | Optional | |
Picture_9 | Additional picture (not more then allowed on site) | Optional | |
Picture_10 | Additional picture (not more then allowed on site) | Optional | |
Separator Field | The value must be "Shipment" | Shipment | Only From Version 1.6.9 |
Shipment Zone Name1 | The name of the shipment zone (not the ID) .. for instance "Europe" | Europe | Only From Version 1.6.9 |
Shipment Zone Price1 | The Shipment Price for the zone | 520.99 | Only From Version 1.6.9 |
Shipment Zone Name2 | The name of the shipment zone (not the ID) .. for instance "Europe" | USA | Only From Version 1.6.9 |
Shipment Zone Price2 | The Shipment Price for the zone | 200 | Only From Version 1.6.9 |
[...]any number of shipment zones | alternation of shipmen zone and price | Only From Version 1.6.9 | |
This tutorial covers most of the features implemented in versions 1.0.x
Install Auction Factory just like a normal Joomla component (Installers / Component), pick up (browse) the downloaded file (latest ZIP release):
After the component has installed you should see the following screen. If during this process you receive any error message make a screenshot and post it to our forums.
The installer is creating automatically a Menu with most common menu items for Auction Factory. You can create your own as needed or modify the one provided. In the installing process are also the Auction Factory Modules installed (we will talk about them separately).
If you Joomla installation already has Community Builder installed, then the Community Builder plugins for Auction Factory will be automatically installed. You can disable them from Community Builder plugin management.
You can now set up Auction Factory! Under Components/Auctions/General Settings:
A. Photos and Pictures
B. Other settings
C. Currency
Here you can Add or delete Currencies on this site:
D. Payment Types
Here you can Add and edit the Payment list for Auctions:
E. Terms and Conditions
If your auction site has terms and conditions that your users must agree upon bidding, then add them here. If you do not need users to agree to terms and conditions, just leave this text empty.
MAIL SETTINGS
Components/Auctions/Mail Settings
Here you can set up the mail messages for your Auction suite. These messages are sent per email to bidders or auctioneers on several events. In the message body and subject you can add replacements tags that will be substituted with the appropriate content (for instance %AUCTIONTITLE% for the Title of the auction).
The whole list of events is can be seen here:
Revised "Auction Factory" version 1.0.3.
Please note that this guide may vary depending on each site template and module positions.