| Both sides previous revisionPrevious revisionNext revision | Previous revisionLast revisionBoth sides next revision |
| customization [2011/01/28 15:11] – demiankatz | legacy:vufind_1.x_developer_manual:user_interface_customization [2015/12/11 20:28] – ↷ Page moved and renamed from customization to legacy:vufind_1.x_developer_manual:user_interface_customization demiankatz |
|---|
| ====== User Interface Customization ====== | ====== User Interface Customization (VuFind 1.x) ====== |
| |
| VuFind is developed using [[http://www.smarty.net/|Smarty]] templates for HTML and CSS for design. Templates and CSS are bundled into themes, which are found in the web/interface/themes folder. You can use one of VuFind's built-in themes (classic or default), or you can build your own. The theme used by VuFind is determined by the theme setting in the [Site] section of web/conf/config.ini. | // This page refers to VuFind 1.x; for documentation on version 2.x, see [[development:architecture:user_interface|User Interface Customization (VuFind 2.x)]] //. |
| |
| The layout is controlled by the Yahoo UI CSS, which means that by modifying the class declarations within the HTML, you can modify the layout. For more information on how to use the Yahoo UI CSS, please see the [[http://developer.yahoo.com/yui/grids/|Yahoo UI web site]]. To modify the colors and design elements, you can edit the styles.css file located in the css directory of your chosen theme. | VuFind is developed using [[http://www.smarty.net/|Smarty]] templates for HTML and CSS for design. Templates and CSS are bundled into themes, which are found in the web/interface/themes folder. You can use one of VuFind's built-in themes (blueprint, classic or default), or you can build your own. The theme used by VuFind is determined by the theme setting in the [Site] section of web/conf/config.ini. |
| | |
| | The layout in the classic/default themes is controlled by the Yahoo UI CSS, which means that by modifying the class declarations within the HTML, you can modify the layout. For more information on how to use the Yahoo UI CSS, please see the [[http://developer.yahoo.com/yui/grids/|Yahoo UI web site]]. The blueprint theme uses [[http://www.blueprintcss.org/|Blueprint CSS]] instead of YUI. Regardless of layout, to modify the colors and design elements, you can edit the styles.css file located in the css directory of your chosen theme. |
| |
| All of the HTML is stored in Templates. There is one main template that controls the overall web site - the layout.tpl file stored in the root of your chosen theme's directory. Each module also has its own subdirectory in the theme where the individual templates for each web page are stored. They can be modified as needed. | All of the HTML is stored in Templates. There is one main template that controls the overall web site - the layout.tpl file stored in the root of your chosen theme's directory. Each module also has its own subdirectory in the theme where the individual templates for each web page are stored. They can be modified as needed. |
| The main benefit of theme inheritance is that it can make it easier for you to manage your local customizations. If you only need to change a few files, creating a separate theme for your custom versions makes it easier to remember exactly what you have changed. As the VuFind code evolves, you won't have to worry about copying templates for new features into your custom theme -- inheritance will simply take care of them. The only time you need to worry about reconciling changes is when a template you have customized changes in the trunk, which should be a fairly infrequent event if your theme is simple enough. //In the example above, suppose you just want to change headers and footers -- you could put a new layout.tpl in your MyUniversity theme but leave everything else in default.// | The main benefit of theme inheritance is that it can make it easier for you to manage your local customizations. If you only need to change a few files, creating a separate theme for your custom versions makes it easier to remember exactly what you have changed. As the VuFind code evolves, you won't have to worry about copying templates for new features into your custom theme -- inheritance will simply take care of them. The only time you need to worry about reconciling changes is when a template you have customized changes in the trunk, which should be a fairly infrequent event if your theme is simple enough. //In the example above, suppose you just want to change headers and footers -- you could put a new layout.tpl in your MyUniversity theme but leave everything else in default.// |
| |
| Note that theme inheritance is only one possible strategy for managing your themes. If you are planning something more complicated than the customization of a few files, you might find it helpful to read up on using [[subversion#vendor_branching|vendor branches]] in [[subversion|Subversion]] as another possible approach to the problem. | Note that theme inheritance is only one possible strategy for managing your themes. If you are planning something more complicated than the customization of a few files, you might find it helpful to read up on using [[legacy:vufind_1.x_developer_manual:subversion#vendor_branching|vendor branches]] in [[legacy:vufind_1.x_developer_manual:subversion|Subversion]] as another possible approach to the problem. |
| |
| ==== CSS Inheritance ==== | ==== CSS Inheritance ==== |
| * In order for CSS files to load correctly, every theme's CSS folder must include the .htaccess file containing special rules for Apache. If you are creating a new theme including css, be sure to copy .htaccess from one of the existing themes or else your CSS files will not load! | * In order for CSS files to load correctly, every theme's CSS folder must include the .htaccess file containing special rules for Apache. If you are creating a new theme including css, be sure to copy .htaccess from one of the existing themes or else your CSS files will not load! |
| * Watch out for @import statements in your CSS files. The target of the @import must be in the same theme as the caller. Inheritance cannot apply here since "@import" is resolved by the client's web browser rather than the server-side logic. //For example, suppose you customize styles.css and copy it to your MyUniversity theme. styles.css has an "@import layout.css" statement in it. If you do not copy layout.css into your MyUniversity theme, it will not load at all -- the user's browser isn't smart enough to find it in the default theme.// | * Watch out for @import statements in your CSS files. The target of the @import must be in the same theme as the caller. Inheritance cannot apply here since "@import" is resolved by the client's web browser rather than the server-side logic. //For example, suppose you customize styles.css and copy it to your MyUniversity theme. styles.css has an "@import layout.css" statement in it. If you do not copy layout.css into your MyUniversity theme, it will not load at all -- the user's browser isn't smart enough to find it in the default theme.// |
| | |
| |
| ==== Image Inheritance ==== | ==== Image Inheritance ==== |
| As of this writing, images do NOT follow the same inheritance rules as template and CSS files. Their paths are explicitly set, and many of them exist entirely outside of the theme folders. This may be worth revisiting at some point -- an {image} Smarty function similar to {css} could be helpful. For now, though, be careful about using relative paths to images if you are not sure which version of a template or CSS file is going to be loaded. | As of this writing, images do NOT follow the same inheritance rules as template and CSS files. Their paths are explicitly set, and many of them exist entirely outside of the theme folders. This may be worth revisiting at some point -- an {image} Smarty function similar to {css} could be helpful. For now, though, be careful about using relative paths to images if you are not sure which version of a template or CSS file is going to be loaded. |
| |
| | ==== Javascript Inheritance ==== |
| | |
| | // This feature is not available prior to VuFind 1.1. // |
| |
| | VuFind includes a {js filename='xxxx'} Smarty tag that works similarly to the {css} tag. The {js} tag will first go through the theme list searching for files in their js folders. If none of the themes contain the requested file, the web/js folder in the root of the VuFind install will be checked as a last resort. As a general rule, library-specific (i.e. YUI/jQuery) files should be stored inside themes, but generic "pure Javascript" files may be stored in the top level web/js folder to avoid redundancy. |
| |
| ===== Icon Libraries ===== | ===== Icon Libraries ===== |
| Some of the graphics provided with VuFind's themes come from the Fugue, Silk and Tango icon libraries. For more information on licensing terms and to find additional icons for use in your local customizations, see these links: | Some of the graphics provided with VuFind's themes come from the Fugue, Silk and Tango icon libraries. For more information on licensing terms and to find additional icons for use in your local customizations, see these links: |
| |
| * [[http://p.yusukekamiyamane.com/|Fugue]] | * [[http://p.yusukekamiyamane.com/|Fugue]] (Copyright © Yusuke Kamiyamane) |
| * [[http://www.famfamfam.com/lab/icons/silk/|Silk]] | * [[http://www.famfamfam.com/lab/icons/silk/|Silk]] |
| * [[http://damieng.com/creative/icons/silk-companion-1-icons|Silk Companion Icons]] | * [[http://damieng.com/creative/icons/silk-companion-1-icons|Silk Companion Icons]] |
