Differences

This shows you the differences between two versions of the page.

--- tutorials:design_adv:replace_system_templates [2009/06/19 15:44]
jonyo changed link reference
+++ tutorials:design_adv:replace_system_templates [2014/09/30 17:33] (current)
geojames
@@ Line 1: / Line 1: @@
+{{indexmenu_n>20}}
 ====== Customizing System or Module Templates ======
-This tutorial will walk you through all the steps necessary to customize system or module template file(s), without touching the base files in the default template set.
+This support wiki article has been [[startup_tutorial_and_checklist:design_configuration:design_tools:system_template_changes:system_module_changes|moved here in the support wiki]]
-<tip c w>**Warning:** This is an **advanced** tutorial, involving making changes to **template files**.
-Before attempting to make changes as described here, be sure you have a **firm grasp of [[tutorials/design/start|the basics]]**.
-Module and System templates, by their very nature, are very dynamic and closely related with their PHP file counterparts.  Be prepared to adjust any module or system templates you customize to make it compatible when you update the Geo software.  See [[#Geo Updates & Customized Templates]] for more info, and be sure to read those sections **BEFORE** a problem occurs, as they have some pre-update steps that will help the transition.
-Also note that supporting file-based template changes is outside the scope of the support we offer for Geo support.  Geo Support can try to help you with the //how// and //where// for editing templates, but they cannot make changes for you or try to troubleshoot problems related to customized templates.</tip>
-===== What you need =====
-**Skills**
-  * Comfortable with using FTP (to upload and download template files from your site) <
-  * Basic understanding of how HTML, Smarty Templates, and/or PHP works will help. <
-  * Not afraid to learn new things. ;-) <
-**Handy tools when editing template files:**
-  * [[http://smarty.net/manual/en/|Smarty Documentation]] <
-===== Getting Started - Creating a Template Set =====
-Note that by //module template//, we mean any template used by a built in Geo module, one that is working "behind the scenes".  A //system template// is one that is used by some overall system-level process, or used to display the dynamic part of the **(!MAINBODY!)** (or **{body_html}** in file-based templates).
-Use the following instructions to modify 1 (or more) module or system templates.  For the purposes of this tutorial, we will demonstrate how to modify **system/cart/display_cart/index.tpl** which is the template responsible for displaying the main cart view((the one that shows all the items you are going to be purchasing)) in Geo 4.0.
-  - In your Geo admin, and in this user manual, check to see if what you are attempting to accomplish can already be done by changing settings in the admin.  You might find that you can already do what you are needing by making a setting change, which is always the better option over editing a template file. <
-  - Using FTP, create a new directory **geo_templates/my_templates/** (you can name my_templates to whatever you want). <
-  - Duplicate the //directory path// for the template you wish to modify.  In this case, that means creating the sub-directories **system/cart/display_cart/** inside **my_templates**. <
-  - Copy the file **geo_templates/default/system/cart/display_cart/index.tpl** to the newly created **geo_templates/my_templates/system/cart/display_cart/** directory.  This is a comparison of the 2 files so you can better see how to set it up:\\
-**Original template file (ships with software, do not edit)**
-  geo_templates/default/system/cart/display_cart/index.tpl
-**Customized template file (you create and edit this one)**
-  geo_templates/my_templates/system/cart/display_cart/index.tpl
-<
-  - Repeat the copy for any other templates you may want to customize, for instance if you also planned to modify the **item.tpl** file.  Note that you should **not** copy a file unless you plan to customize it.  You do not need to worry if the file you are customizing //includes// another template file, if you do not copy that template file, when it is included the system will automatically look for the file in the default template set if it is not found in **my_templates**.
-<tip c w>**Warning:** Only copy files you are going to customize.  With every file you copy over, when you next update the Geo software, there is a chance that template file may have changed to work differently, so the fewer files that are copied over, the less chance something might break and need adjustment after an update.
-Also, be sure to keep the part at the top of the file that looks like **{* $Rev: 12345$ *}** - when you update you will be able to compare this "revision number" to the one in the default template set, to see if changes have been made in the new Geo version.</tip>
-<
-  - In the admin, on the page [[admin_menu:templates:template_system:start|Templates > Template System]] click on [[admin_menu:templates:template_system:start#Use Set]] next to the **my_templates** template set. <
-Now, the **my_templates** should be at the top of the template sets to use in the admin.  This means that any template found in that template set, will be used, if a template is not found in that template then it uses the one from the default template set.
-Make changes to the file(s) in **geo_templates/my_templates/**.  **Do not** change files in **geo_templates/default/**, as they will be over-written during an update.  Also the templates in the default template set are fair game to be over-written by Geo support for troubleshooting purposes.
-===== Geo Updates & Customized Templates =====
-When you update the Geo software, there is a chance a template you have customized may have changed, to add some new feature, to fix something, or perhaps just to change how it works to make it easier to understand.  The result of such changes could be totally unnoticeable (such as some new feature may not be displayed), or it could cause the template to no longer work as intended.
-Since module and system templates are closely tied to their PHP file counterparts, it is likely that at some point, if you have customized a module or system template, you will need to make changes to it when you update the Geo software.  Below are a few tips to help you with this task.
-==== Before you update ====
-  * At the top of each smarty template file should be something that looks like this:((If you don't see this at the top of a system or module template in the default template set, let us know!))
-  {* $Rev: 12345$ *}
-When you customize a template, be sure you leave that top part intact in your custom template, and the same as the template from the default template set. <
-  * Make a copy of the default template set without any modifications, and keep it handy on your local computer.  This will come in handy to compare a new template to the original one in your current version to see what has changed. <
-==== After Update: Check for Template Changes ====
-When you update, for every custom template you have, compare the //Rev number// at the top, to the one at the top of the corresponding template in the default template set.  If the numbers are the same, you can breath a sigh of relief, as nothing has changed in that template in the new Geo version.  If they are different numbers however, you know that something has changed in that template file, so there is a chance you may need to make changes to your customized template to account for it.  If that is the case, see [[#After update: Fixing Changed Templates]]
-==== After Update: Fixing Changed Templates ====
-These are a few tips on what to do if the //Rev number// has changed for your customized template in the new Geo version.
-Compare the template from the //new// default template set in the new Geo version, to the copy of the default template set you made from the original Geo version.  (you did make a copy before updating, right?) If it is a long file, you might need to use software that is designed to compare differences between files, commonly called a "diff" program.  There are a lot of good diff programs out there, some can even show you a line by line comparison, and even highlight what has changed on each line for you.  If you do not already have something that does file comparisons, you should be able to find such software online, just look for "diff software" in your favorite search engine or software download site.
-Once you figure out what has changed between the old and new version of the template:
-^ Nature of Template Changes ^ Recommended Solution ^
-| Changes to HTML only ((no changes to //smarty tags//)) | Easiest change to "fix": Most likely **no changes are needed** for your custom template to keep working like it has.  You may still want to go over what has changed and apply those changes to your template (if the changes apply smoothly), for instance if the changes are to make the template W3C compliant.  |
-| Smarty $variable name change | Apply the same change to your custom template.  For instance, if in the original, it used a smarty variable named **$is_allowed**, and in the new file it has been changed to **$isAllowed**, in your custom template you would search for all instances of **$is_allowed** and replace with **$isAllowed**.  |
-| Template does not exist in new version | Check in [[developers/changes_to_note/templates/start]] for any notes about if the file has simply been re-named or if it's purpose has been replaced/moved to somewhere else.  If you are having trouble, you can ask us in a support ticket((Note that diagnosing or fixing problems caused by custom templates is outside of the support we offer, but if you ask nicely we will be happy to help you with figuring out what has happened to a template and point you in the right direction.)).   |
-| Other trivial changes | Review on a case by case basis, and decide if you want to apply the changes to your customized template.  For //trivial// changes, it should be easy to apply those to your customized template manually one by one without too much trouble.  |
-| Non-trivial changes | This would be the "other" category: anything where the differences are so many or the new version of the template is so different it says the entire page has changed when you compare the old to the new template.  Basically, anything that is not easy to apply the changes to your custom template.  Your best option may be to start out from scratch by using the new template.  Then re-apply your customizations to the new file (as opposed to applying changes to your custom template, instead you are re-customizing the new stock template).  |
-Editing Smarty templates is a lot better solution than having to edit PHP files, as there is less of a chance that there will be a change to a template file.  But the chance is still there.  When you update the Geo software, be prepared to run into a situation as outlined in the "non-trivial changes" above.
-===== See Also =====
-  * [[admin_menu:templates:template_system:start|Templates > Template System]] - Help for the template system page in the admin <
-  * [[tutorials:design_adv:replace_db_templates]] <

Geodesic Solutions Community Wiki

User Tools

Site Tools

Differences

Page Tools