Differences

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

--- tutorials:design_adv:replace_addon_templates [2014/09/25 16:55]
127.0.0.1 external edit
+++ tutorials:design_adv:replace_addon_templates [2014/09/30 17:37] (current)
geojames
@@ Line 2: / Line 2: @@
 ====== Customizing Addon Templates ======
-This tutorial will walk you through all the steps necessary to customize Addon template file(s), without touching the original template files in the addon's sub directory.  This will only work for addons that use smarty-based templates, located in the addon's directory under a sub-directory named **templates/**.  The addon must also use the built in system for loading those templates, but if an addon uses its own methods for loading templates this tutorial may not work((All addons created by Geodesic Solutions that use Smarty templates, this tutorial will work for.  Addon developers:  Just make sure you use the **geoTemplates** and/or **geoView** classes when using Smarty templates.  If you use the Smarty class directly, the methods described in this tutorial will not work for your clients.)).
+This support wiki article has been [[startup_tutorial_and_checklist:design_configuration:design_tools:system_template_changes:addon_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]]**.
-Addon 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 addon**. 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 to Geodesic Addon templates 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 //addon template//, we mean any template used by an addon, one that is found in the addon's directory, in a sub-directory **templates**, one that is working "behind the scenes".
-Use the following instructions to modify 1 (or more) addon templates.  For the purposes of this tutorial, we will demonstrate how to modify **addon/example/eWidget_preview.tpl** which is a template used by the example addon to display the preview of the example order item named eWidget.
-  - 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.) )) <
-    * In **Advanced Settings**, check the box next to the setting **Allow Edit of system, module, and addon Templates**. <
- <
-  - Save the 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/addon/example/**.  You should be in the **default** template set, viewing the folder that contains the template file you wish to modify.
-<tip c n>**Note:**  When an addon is installed or updated, the templates for that addon are automatically copied from **addons/ADDON NAME/templates/** to the default template set at **default/addon/ADDON NAME/**, except for templates in certain sub-folders that are "special cases".  </tip> <
-  - Check the box next to the file(s) you wish to modify so that it is selected.  For example: **eWidget_preview.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.
-For addons created by Geodesic Solutions, 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. <
-===== How Addon Templates Work =====
-There are a few things you should know about how addon templates work within the system, as noted below.
-==== Template Files Copied during Addon Install/Update ====
-When an addon is installed or updated, the system checks to see if that addon has any templates in the addon folder, in the sub-folder **templates/**.  If it finds any such files, it automatically copies the contents of the folder to **geo_templates/default/addon/addon_folder/**, including sub-folders and files.  See [[admin_menu/design/template_sets/start#Re-Scaning Default Templates]] for info on re-copying the templates on all currently enabled addons, to the default template, like is done during addon installation or update.
-The following sub-folders are "special cases" and are **not copied** along with the rest((Locations are relative to the addon templates/ folder)):
-  - **admin/** - If this folder exists, it is not copied over as it is assumed to be used for pages in the admin, which are rarely customized. <
-  - **main_page/** - If this folder exists, the contents are copied to default/main_page/ folder. This is handy to allow addons to add new overall templates specifically for pages in the addon that are able to easily be customized and attached to addon pages, such as the Storefront Addon's default Storefront template that is added this way. <
-  - **external/** - If this folder exists, the contents are copied to default/external/ folder.  This is handy to allow addons to have CSS or image files that are able to easily be customized in a template set. <

Geodesic Solutions Community Wiki

User Tools

Site Tools

Differences

Page Tools