Custom Template Reference
Contents |
Download .zip how-to package with PDF tutorial
Want to learn how to create your own templates for Pro Edition? Download this great how-to article (with example files!) written by Soholaunch customer Jaun-Vincent Haasbroek.
Introduction
This section covers the creation and integration of custom templates for use with the Soholaunch Pro Edition, and is intended for graphic designers and site developers. As such, a working knowledge of Adobe Photoshop and HTML programming is recommended.
How Pro Edition interprets template information
Within the maintenance platform, users will only have access to the page “content” area for editing. This means that each site must have a template design that maintains continuity throughout the site. Automatic menu generation is built in to the Soholaunch management tool so that Menu Display buttons and sub-page buttons can be defined within the template (using special Pound Variables). This gives you the option of placing Menu Display systems vertically, on the left or right of the page layout, or horizontally, across the top or bottom of your pages.
You may also wish to custom-design your main navigation system and not use the Menu Display feature at all. This allows you to have total control over font, colors and sizes of your navigation structure. For even greater flexibility in design, different templates may be assigned to individual site pages throughout your site.
Your template designs can take on any level of complexity that you wish them to have. However, please note that the user, via the management tool, cannot change any images, text, or links built into the template. This should always be planned and noted well ahead of the build process.
Template folder and files
Place all files(images,index.html,custom.css, etc) into a folder and name the folder like this...
Category-Sub_Category-Color Example: Category-Template_Name-Color
Possible files in your template folder (aside from images):
index.html (REQUIRED) - The main HTML template file for your website used accross all site pages. This file must exist in your template folder in order for site pages to display at all.
cart.html (OPTIONAL) - Custom shopping cart template. If found in your template folder, it will be used in place of index.html on shopping cart system pages (as in: when website visitor is browsing/purchasing products via your online checkout process).
home.html (OPTIONAL) - If found in your template folder, it will be used in place of index.html on the "Home Page" (whatever page you've assigned to be your start/index/home/default page).
news.html (OPTIONAL) - Custom blog/article display template. If found in your template folder, it will be used in place of index.html when visitor views full text of blog entry or news item.
custom.css (OPTIONAL) - If found in your template folder, it will be used in place of the default stylesheet (runtime.css).
cart.css (OPTIONAL) - If found in your template folder, it will be used in place of the default stylesheet (runtime.css) on shopping cart system pages. This is mainly usefull in conjunction with cart.html. That way you can have a separate template html file as well as a separate style sheet for shopping cart system pages.
shopping_cart.css (OPTIONAL) - If found in your template folder, will be included instead of pulling the colors/styles set in Shopping Cart > Display Settings. Note that this performs a completely different function than cart.css.
template_variable_rules.php (OPTIONAL) - If found in your template folder, it will be included within pgm-realtime_builder.php right before all of the other #variables# are processed, allowing your template to use custom pound variables and even override standard pound variable functionality if you want to.
Source file overrides
pgm-auto_menu.php (OPTIONAL) - This is the file that puts together the html output for the various menu navigation systems (vmenu, hmains, etc) when your website is viewed. If found in your template folder, it will be used instead of the standard pgm-auto_menu.php file. The idea here it to download the original pgm-auto_menu.php from your docroot or from sohoadmin/client_files/base_files (same file, 2 locations), make a copy of it and stick it in your template folder, then modify it to all kinds of crazy things with your menu system.
pgm-faq_display.php (OPTIONAL) - When a visitor views a page with FAQs on it, this file is called to build the HTML output for the FAQs. If you make a copy of this file and stick it in your template folder, your (presumably modified) copy will be used instead of the standard file. Do this when you want to trick out how your FAQs display, like Soholaunch did on our main website --- links to the support page, scroll down to see FAQs...we added those big 'Q' graphics and customized the font.
pgm-promo_boxes.php (PRO Only, OPTIONAL) - When a visitor views a page whose template uses #NEWSBOX#, #BOX1#, etc, this file is called to build the HTML output for the news/promo boxes. If you make a copy of this file and stick it in your template folder, your (presumably modified) copy will be used instead of the standard file. Do this when you want to trick out how your news/promo boxes display further than you can via the Template Box Manager. Literally unlimited modification potential here.
pgm-blog_display.php (OPTIONAL) - Called when visitor views a page with a blog dropped on it. This is the file that spits out the archive links, etc. If found in your template folder, it will be used instead of the standard pgm-auto_menu.php file. Added in v4.9 r32.
slider.php (ULTRA Only, OPTIONAL) - Called when visitor views a page with a photo album/ slider on it. If found in your template folder, slider.php will be used instead of the standard /sohoadmin/client_files/pgm-photo_slider.php file.
Pound Variables
Pound Variables: unique variables that tell Pro Edition where to place specific “client changeable” headers, Menu Display buttons, and automatic text menus within your layout. These are not case sensitive, and can be placed visually within your HTML editor as text, so long as they contain the pound sign.
Note: Should be in all-caps!
#CONTENT# - Tells the system where to display the table that will hold all the content created within the Pro Edition’s Page Editor. Note: User will not be able to manage page content unless this variables is placed somewhere in your html template file (i.e. index.html).
#LOGO# - Replaced with data from "Template Manager > Template header line". Inserts an editable Header line that can be changed by the user via the Soholaunch Pro Edition's Template Manager feature.
#LOGO#-ALT Same as #LOGO# except #LOGO#-ALT only displays if a logo image is not specified for #LOGOIMG# . This allows template designers to create templates that can accommodate an image or text logo, but not both.
#LOGOIMG# - Custom Logo variable added which inserts a logo which is chosen in the Template Manager Module.
#SLOGAN# - Custom Logo variable added which inserts a company slogan or moto which is chosen in the Template Manager Module.
Menu systems
#HMAINS# - Main page links only, arranged horizontally (links managed via the Menu Display module; must set "Auto-Menu Display Type" to "Text Links").
#VMAINS# - Main page links only, arranged vertically (links managed via the Menu Display module; must set "Auto-Menu Display Type" to "Text Links").
#HSUBS# - Sub page links only, arranged horizontally (links managed via the Menu Display module; must set "Auto-Menu Display Type" to "Text Links").
#VSUBS# - Sub page links only, arranged vertically (links managed via the Menu Display module; must set "Auto-Menu Display Type" to "Text Links").
#TMENU# - Inserts a horizontal, text based menu system that matches the “setup” of the Main and Sub menu system as configured via the Menu Display feature. Typically used for footer links.
- Ultra only #FLYOUTMENU# Inserts a horizontal menu with a flyout menu for subpages.
- Ultra only #VFLYOUTMENU# Inserts a vertical menu with a flyout menu for subpages.
#PAGENAME# - Replaces with name of current page (underscores converted into spaces).
#PAGETITLE# - Unique page name. Replaced with text defined via Edit Pages > Page Properties > Page Title
#USERSONLINE# - Replaced with the number of visitors currently browsing your website. This particular variable may be also be used within the Text Editor.
#AUTODATESTAMP# - Replaced the current weekday, month, day, and year.
#PROMOTXT1#/#PROMOTXT2# - Text variables added which inserts the first 255 characters of blog_data pulled from random blog_content entry (under special "Promo Box 1/2" blog categories)
#PROMOHDR1#/#PROMOHDR2# - Promo entry title. Works with --- the blog_title associated with blog_content entry pulled for #PROMOTXT1#/#PROMOTXT2#
#NEWSBOX# - Newsbox variable added which inserts text arranged by date, blog_title, and if desired a few lines of blog_data.
Company Information
Ruben 11:40, 22 May 2006 (CDT) Below are a list of BIZ tags which information is pulled from the Global settings area.
contact information tags that can be used:
#BIZ-DOMAIN# - Replaces with Domain name.
#BIZ-COMPANY# - Replaces with Company name.
#BIZ-ADDRESS1# - Replaces with 1st address line.
#BIZ-ADDRESS2# - Replaces with 2nd address line.
#BIZ-ZIP# - Replaces with zip code.
#BIZ-CITY# - Replaces with City name.
#BIZ-STATE# - Replaces with State name.
#BIZ-COUNTRY# - Replaces with Country name.
#BIZ-EMAIL# - Replaces with email address.
#BIZ-PHONE# - Replaces with phone number.
#BIZ-FAX# - Replaces with fax number.
#COPYRIGHT# -Replaced with copyright text from global settings, prefixed with the copyright symbol ©
Custom script includes
#CUSTOMINC#
Replaced with output of "includethis.inc" (if found), which should be placed in the template's folder along with index.html, custom.css, etc.
#CUSTOMINC2#
Replaced with output of "includethis2.inc" (if found), which should be placed in the template's folder along with index.html, custom.css, etc
<!---#INC-myfile.php#-->
Initiates php call to include("myfile.php"). Note that the pound variable itself is not actually replaced in the template html when this happens, which is it should be contained within an HTML comment tag. Include file (i.e. myfile.php) should be in your template folder.
#OUTPUT-myfile.php#
Replaced with the output of file you specify (i.e. myfile.php). Include file (i.e. myfile.php) should be in your template folder.This is what you should use if you want your custom include file to dynamically build some html and spit it out at certain place in the template html (or similiar situation). This is also handy for pulling in javascript functions that have php-created pieces to them.
Other/Misc
#BOX1# - #BOX8#
Adding #BOX1# to a template is similar to #NEWSBOX# but gives the user much more control within the Template Manager in the Box Manager.
Once a template with this variable is selected in the template manager, the option to modify #BOX# display settings will become available within the Template Features area.
#BOX-TITLE1# - #BOX-TITLE8#
Adding #BOX-TITLE1# to a template allows the user to change a box title within the Box Manager.
#JQUERY# (Ultra Only)
Placing #JQUERY# into the template's index.html/.php file adds the latest stable version of the jQuery library. This enables your template to use jQuery if you are using the library as part of your development. It works whether you're referencing an external javascript file or using jQuery directly on the index page.
#template_folder#
Replaced with folder name of template assigned to page currently being viewied. Added so plugin/template developers can know the current template folder for image paths, etc.
Example value of #template_folder#:
ANIMALS-Kittens_Awww-Cute_Blue.
- Ultra only ====#relative_template_path#==== Replaced with relative path from document root foler.
Example value of #relative_template_path#:
sohoadmin/program/modules/site_templates/pages/ANIMALS-Kittens_Awww-Cute_Blue
#template_path#
Replaced with full server path from root, up to and including folder name of template assigned to page currently being viewied.
Example value of #template_path#:
/home/sites/example.com/sohoadmin/program/modules/site_templates/pages/ANIMALS-Kittens_Awww-Cute_Blue
Added so plugin developers can know the current template folder for script include paths and such.
====#template_path_full_url#==== - Replaced with absolute url path to template folder, accounts for http/https, helps with image src's and such.
Example value of #template_path_full_url#:
http://example.com/sohoadmin/program/modules/site_templates/pages/ANIMALS-Kittens_Awww-Cute_Blue
#plugin-[whatever]#
- Put #plugin-[whatever]# pound variable(s) in your custom templates to designate areas designed to work with a specific plugin (that when installed will replace that var with it's own content).
All remaining (unreplaced by a plugin) #plugin-[whatever]# tags will be stripped from template html before final page content displays. That way if the plugin that works with a given #plugin-[whatever]# var is not installed, you won't see a bunch of raw #plugin-[whatever]#'s all over the template when the site is viewed.
Example usage Let's say somebody develops a plugin called "Say Hello World 1.0" that as one of it's features searches for #pound-helloworld# within the template html and replaces it with the text "Hello World".
Template developers who wish to make their templates more appealing by accommadating people who use the "Say Hello World 1.0" plugin can stick #pound-helloworld# in their template in some special place and not have to worry about the raw "#pound-helloworld#" pound var text displaying on sites where the "Say Hello World 1.0" plugin is NOT installed because if the plugin's not installed that pound var text will be simply stripped from the output html before the site page is loaded.
User Images
One of the top modification requests from purchases of custom templates is "Can you change that one image to something else?". This is what the Template Images feature was designed to address.
You can give the user control over any image in your template by prefixing the image's file name with "_userimg-", like so...
<img src="_userimg-template_header.jpg">
All you have to do is name the file right
As the template developer, all you have to worry about is naming your image files with that _userimg- prefix. The Soholaunch tool will take care of the rest.
The system only needs the right image filename to detect that a particular image should be user-controllable. It doesn't matter where or how you use the image in your template html. It could be a background image assigned via a css in rule, it could be a normal image tag...whatever.
Note: Image must be called in your template html file. Will not work with image calls in separate custom.css file. So if you have css rules that you want to use the _userimg- thing with, put them directly in your template html using <style> tags.
Code Examples - Any image can be a user image
The following are just a few examples of how you could utilize the _userimg- functionality.
You could let them change the header background image defined in your css rules...
#header { background-image: url('_userimg-header_bg.gif'); }
Or maybe the menu background pattern defined via inline css...
<div id="vmenu" style="background-image: url('_userimg-vmenu_bg.gif');repeat: repeat-y;"> #vmenu# </div>
Or maybe you have an image of a semi truck in your home page splash template (home.html) and you want the template to be easily used for other industry applications...
<img src="_userimg-semi_truck.jpg"/>
The point is: You can make any image in your template controllable by the user as long as you give the image file that _userimg- prefix.
Uploading custom templates
If you're running v4.8.5 or later... Zip up your Template Folder and Files and upload the .zip file via Template Manager > Upload Custom Template (below Base Site Template selection). Once uploaded the product will automatically extract your .zip file in the correct location, and the template will be availible in the list of templates (drop-downs and browse by screenshot).
If you're running a version prior to v4.8.5, or if you want to quickly update individual template files... Log-in to your site via FTP and upload your template folder (containing all template files) to this folder:
sohoadmin/program/modules/site_templates/pages
Hard-coded page links
When using custom navigation elements, you will need to know how to code various links. Since the entire site created within the product platform is database-driven, it is necessary to call pages differently than when coding for traditional HTML pages. Theses links must be added inside the template file.
Normal Page Links
Let’s say that you have created a navigation button that should be linked to the “About Us” Page. The following code is what should be used to link your navigation element:
index.php?pr=About_Us
Note: The page name is case sensitive and page name must be accurately depicted for proper operation. Notice that all spaces between words in the page names are separated by an underscore. This must be manually coded in place of spaces for the link to work properly.
The actual page name is directly related to the page name created within the “Create Pages” module of the Soholaunch Pro Edition.
Because your site is database driven, you will always call the “index.php” file when linking to normal site pages, like so...
http://example.com/index.php?pr=Home_Page
And thanks to recent upgrades to make Soholaunch-created website more SEO-friendly, you can also link to the .php file that is automatically created for each site page, like so...
http://example.com/Home_Page.php
Note: Don't hard-code menu links if you're planning to sell your template on the Addons site. This option is only recommended if you're building a template for a specific site only and you know exactly what links will be on the menu and that they're not going to change much. But even in those cases it'll usually be easier for you in the long run to use the Menu Navigation system, even if heavily-modified, because at some point you're almost certainly going to want to add, reorder, or remove menu links... better to make that process as easy as clicking a couple buttons in Pro Edition's Menu Navigation feature.</nowiki>