Differences

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

--- tutorials:design_adv:replace_system_templates [2013/09/23 14:46]
jonyo [Getting Started - Copying Files to Customize]
+++ tutorials:design_adv:replace_system_templates [2014/09/30 17:33] (current)
geojames
@@ Line 2: / Line 2: @@
 ====== 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.  Because of this there are certain risks involved with customizing such template files, as listed below.
-**Risks of Customizing System, Module, or Addon Templates:**
-  * May require **compatibility changes when updating the software**. Such changes are the responsibility of the site owner and are not covered by the software update service provided by Geodesic Solutions.  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. <
-  * Problems caused by customizations are **not covered by Geo support**, if support finds that something works with the "default" templates but not with customized templates, they will not be able to help further. 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**
-  * 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 - Copying Files to Customize =====
-Note that by //module template//, we mean any template used by a built in Geo module, one that is working "behind the scenes", one that is in the **module/** sub-folder in a template set.  A //system template// is one that is used by some overall system-level process, or used to display the dynamic part of the **{body_html}**, one that is in the **system/** sub-folder in a template set.
-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 5.0.
-This tutorial assumes you already have your own template set created, and named **my_templates**((If your template set is named something different, you would use your own template set name in place of my_templates in the tutorial.)).  If you do not have a template set yet, be sure to create one using the tools available to do so in the admin panel, **never edit files in the default template set**.
-  - 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 system or module template file, as it makes updates much more easy. <
-  - In the admin panel, go to the page **[[/admin_menu/design/template_sets/start|Design > Template Sets]]**. <
-  - In the top right corner of the page, make sure you are in **Advanced Mode**.  If you are not, click the button to **Switch to Advanced Mode**. <
-  - On the page, make sure the settings are set as follows:
-    * Next to //my_templates// - checkbox for admin editing is checked. <
-    * Next to //default// - checkbox for admin editing is checked.((For the default template set, checking the box for Admin Editing just allows you to view files in read-only mode for the default template set, you will never be able to edit default templates from the admin panel as you should not be editing files in the default template set.  (Edit them in your own template set instead.) )) <
-    * If using 7.2.5 or before:  In **Advanced Settings**, check the box next to the setting **Allow Edit of system, module, and addon Templates**. <
- <
-  - Save the changes. <
-  - If using **7.3.0 or higher**:  In **Design > Settings**, check the box next to the setting **Allow Edit of system, module, and addon Templates** - then **save changes**. <
-  - In the admin, go to the page **[[/admin_menu/design/manager/start/|Design > Manager]]**. <
-  - In the manager, browse to the sub-folder within the default template set, that contains the file you wish to customize.  For example: **default/system/cart/display_cart/**.  You should be in the **default** template set, viewing the folder that contains the template file you wish to modify. <
-  - Check the box next to the file(s) you wish to modify so that it is selected.  For example: **index.tpl**. <
-  - On the bottom of the manager window, click the link to **copy** the file.  After you click it, the file(s) that were selected should appear in the **File Clipboard** below the manager, make sure that it lists the correct template file(s). <
-  - On the left side of the manager, click on the Jump To link to go to the **Base Folder**. <
-  - In the manager, click on the **my_templates** folder so that you are viewing the files within that template set. <
-  - On the bottom of the manager, click the link to **paste** the file(s).  Note that when copying/pasting any system, module, or addon files, all you need to do it browse into the template set you wish to copy them to, as it will automatically duplicate the "parent folder structure" for you.  This is different than how main_page or external file copy/paste works, which will paste to the current folder you are viewing. <
-  - 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>
-<
-  - Make changes to the file(s) in **geo_templates/my_templates/**, with the setting checked to allow editing system, module, and addon templates from the admin panel, you will be able to edit the templates in the admin panel or you can edit them directly using FTP, it is you choice.  Just be sure, **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.
-<tip c n>**Note:**  The update tips here only apply for **system/**, **addon/**, or **module/** template customizations.</tip>
-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 ====
-In our user forums, in the [[http://geodesicsolutions.com/geo_user_forum/forumdisplay.php?f=10|New Release Info Section]], for every release starting with version 5.0.0 we will list all of the template files that have changes in them for that release.  View the forum post for every release between your current version and the version you are updating to, and make a note of every template file changed that you have made customizations to.
-If you are updating from a version prior to **4.1.3**, or if the number of updates between your current version and the latest makes it difficult to find all the template files that have changed, you can instead use this method to determine what templates might need changing:  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 for when template files have been changed on the new release, the ones you found by following instructions in the [[#After Update: Check for Template Changes|Check for Template Changes]] section above.
-**For the "Easy" Changes:**
-Your main resource for seeing what needs to be changed, is the [[/developers/changes_to_note/templates/start]] page in this wiki.  In most cases you will be able to reference that page to see exactly what you need to change to bring your custom templates up to date.
-If that is not the case however, keep reading as you may need to do some more complex things to bring your templates to be compatible with a newer version.
-**Manual Template Checking/Adjusting:**
-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 its 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/design/template_sets/start|Design > Template Sets]] - Help for the template sets page in the admin <

Geodesic Solutions Community Wiki

User Tools

Site Tools

Differences

Page Tools