About Features Downloads Getting Started Documentation Events Support GitHub

Love VuFind®? Consider becoming a financial supporter. Your support helps build a better VuFind®!

Site Tools


Warning: This page has not been updated in over over a year and may be outdated or deprecated.
development:architecture:user_interface

Differences

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

Link to this comparison view

Both sides previous revisionPrevious revision
Next revision
Previous revision
development:architecture:user_interface [2021/08/03 13:56] demiankatzdevelopment:architecture:user_interface [2023/11/09 19:32] (current) – [Icon Libraries] demiankatz
Line 1: Line 1:
 ====== User Interface Customization ====== ====== User Interface Customization ======
  
-:!: // This page refers to VuFind 2.x and later; use of earlier versions is no longer recommended. // +VuFind® uses a theme system to isolate the user interface from the business logic, and to make it easy to customize the software's look and feel. You can use one of VuFind®'s built-in themes, or you can design your own. This page provides guidance and background information to help you make the most of VuFind® themes.
- +
-VuFind uses a theme system to isolate the user interface from the business logic, and to make it easy to customize the software's look and feel. You can use one of VuFind's built-in themes, or you can design your own. This page provides guidance and background information to help you make the most of VuFind themes.+
  
 ===== Technical Background ===== ===== Technical Background =====
  
-VuFind is developed using PHP templates for HTML and [[development:architecture:less|LESS]] / CSS for design.  Templates and CSS are bundled into themes, which are found in the themes folder under VuFind's home directory.+VuFind® is developed using PHP templates for HTML and [[development:architecture:less|LESS]] / CSS for design.  Templates and CSS are bundled into themes, which are found in the themes folder under VuFind®'s home directory.
  
-Starting with release 2.4, VuFind's default theme (bootprint3) uses the [[http://getbootstrap.com/|Bootstrap]] library (version 3) for layout. Earlier versions had a different default theme (blueprint) using the [[http://www.blueprintcss.org/|Blueprint CSS]] library. The default mobile theme (jquerymobile) was built with the [[http://jquerymobile.com/|jquerymobile]] library, but it was discontinued starting with VuFind 4.0.  Many basic design elements (such as colors and font sizes) can be customized through small CSS modifications, even if you do not have a detailed understanding of these frameworks.+Starting with release 2.4, VuFind®'s default theme (bootprint3) uses the [[http://getbootstrap.com/|Bootstrap]] library (version 3) for layout. Earlier versions had a different default theme (blueprint) using the [[http://www.blueprintcss.org/|Blueprint CSS]] library. The default mobile theme (jquerymobile) was built with the [[http://jquerymobile.com/|jquerymobile]] library, but it was discontinued starting with VuFind® 4.0.  Many basic design elements (such as colors and font sizes) can be customized through small CSS modifications, even if you do not have a detailed understanding of these frameworks.
  
 ===== Getting Started ===== ===== Getting Started =====
Line 15: Line 13:
 ==== Creating a Theme ==== ==== Creating a Theme ====
  
-Starting with VuFind 4.1, a [[development:code_generators#creating_themes|command-line generator tool]] is available to create and configure a new theme using a simple example directory as the foundation. If you are using an earlier version of the software, you can still make use of this example by manually copying the files from GitHub into a new subdirectory of your VuFind installation's themes directory. The structure of a theme is described in more detail below.+Starting with VuFind® 4.1, a [[development:code_generators#creating_themes|command-line generator tool]] is available to create and configure a new theme using a simple example directory as the foundation. If you are using an earlier version of the software, you can still make use of this example by manually copying the files from GitHub into a new subdirectory of your VuFind® installation's themes directory. The structure of a theme is described in more detail below.
  
-==== Configuring VuFind's Theme Options ====+==== Configuring VuFind®'s Theme Options ====
  
-The **theme** setting in the **[Site]** section of [[configuration:files:config.ini|config.ini]] controls VuFind's default theme.+The **theme** setting in the **[Site]** section of [[configuration:files:config.ini|config.ini]] controls VuFind®'s default theme.
  
-VuFind also supports the ability to select from one of multiple configured themes, either through a parameter on the URL or through a drop-down control within the user interface. See the comments in [[configuration:files:config.ini|config.ini]] above the **alternate_themes** and **selectable_themes** settings for more details on how this works.+VuFind® also supports the ability to select from one of multiple configured themes, either through a parameter on the URL or through a drop-down control within the user interface. See the comments in [[configuration:files:config.ini|config.ini]] above the **alternate_themes** and **selectable_themes** settings for more details on how this works.
  
-The **mobile_theme** setting can also be used to default to a different theme when a mobile device is detected; however, with the advent of responsive design, mobile-specific themes are no longer as useful as they once were, and VuFind no longer includes a default mobile theme as of release 4.0.+The **mobile_theme** setting can also be used to default to a different theme when a mobile device is detected; however, with the advent of responsive design, mobile-specific themes are no longer as useful as they once were, and VuFind® no longer includes a default mobile theme as of release 4.0.
  
-If you use the [[development:code_generators#creating_themes|command-line generator tool]] mentioned earlier, it will automatically set VuFind's default theme to your newly-created theme as well as turning on the theme selector so that you can switch back to VuFind's default theme. If you want other behavior, you will need to comment out or change the appropriate [[configuration:files:config.ini|config.ini]] settings.+If you use the [[development:code_generators#creating_themes|command-line generator tool]] mentioned earlier, it will automatically set VuFind®'s default theme to your newly-created theme as well as turning on the theme selector so that you can switch back to VuFind®'s default theme. If you want other behavior, you will need to comment out or change the appropriate [[configuration:files:config.ini|config.ini]] settings.
  
 ==== Configuring a Theme ==== ==== Configuring a Theme ====
Line 37: Line 35:
 ==== What Should I Start Editing? ==== ==== What Should I Start Editing? ====
  
-If you want to begin customizing your theme, a useful starting point is to identify a template that you would like to modify -- good starting points are the **header.phtml** and **footer.phtml** files that define VuFind's default header and footer. Copy one of the files from your theme's parent theme into your own, edit the HTML, and see how things change when you access your site through a web browser.+If you want to begin customizing your theme, a useful starting point is to identify a template that you would like to modify -- good starting points are the **header.phtml** and **footer.phtml** files that define VuFind®'s default header and footer. Copy one of the files from your theme's parent theme into your own, edit the HTML, and see how things change when you access your site through a web browser.
  
 As you do this, you will likely notice bits of code wrapped in "slots". Slots are a [[development:plugins:view_helpers|view helper]] that makes it easy to override and customize content. You can learn all the ways to use them on our [[development:plugins:view_helpers|view helpers page]]. As you do this, you will likely notice bits of code wrapped in "slots". Slots are a [[development:plugins:view_helpers|view helper]] that makes it easy to override and customize content. You can learn all the ways to use them on our [[development:plugins:view_helpers|view helpers page]].
Line 49: Line 47:
 </code> </code>
  
-If you want to begin customizing your styles, you can create a brand new CSS file to override some defaults, and register it in your theme's module.config.php -- or you can use the more advanced [[development:architecture:less|LESS]] technology to adjust some variables and recompile VuFind's core CSS with some local adjustments.+If you want to begin customizing your styles, you can create a brand new CSS file to override some defaults, and register it in your theme's module.config.php -- or you can use the more advanced [[development:architecture:less|LESS]] technology to adjust some variables and recompile VuFind®'s core CSS with some local adjustments.
  
-Looking at existing themes and templates should help give you some ideas about how to achieve the effects you need... and if you get stuck, please feel free to reach out to the VuFind community for help through the channels listed on our [[https://vufind.org/vufind/support.html|support page]].+Looking at existing themes and templates should help give you some ideas about how to achieve the effects you need... and if you get stuck, please feel free to reach out to the VuFind® community for help through the channels listed on our [[https://vufind.org/vufind/support.html|support page]].
 ===== Theme Structure ===== ===== Theme Structure =====
  
-Each theme has its own directory under VuFind's themes directory.  Each of these directories contains a few important files and directories:+Each theme has its own directory under VuFind®'s themes directory.  Each of these directories contains a few important files and directories:
  
-  * css - This directory contains CSS files.  All files within this directory can be accessed through the web server thanks to a rewrite rule in VuFind's Apache configuration. +  * css - This directory contains CSS files.  All files within this directory can be accessed through the web server thanks to a rewrite rule in VuFind®'s Apache configuration. 
-  * images - This directory contains images.  All files within this directory can be accessed through the web server thanks to a rewrite rule in VuFind's Apache configuration. +  * images - This directory contains images.  All files within this directory can be accessed through the web server thanks to a rewrite rule in VuFind®'s Apache configuration. 
-  * js - This directory contains Javascript files.  All files within this directory can be accessed through the web server thanks to a rewrite rule in VuFind's Apache configuration. +  * js - This directory contains Javascript files.  All files within this directory can be accessed through the web server thanks to a rewrite rule in VuFind®'s Apache configuration. 
-  * languages - This optional directory (supported starting in VuFind 2.5) can contain custom [[development:architecture:localization|language files]] to override strings on a per-theme basis.+  * languages - This optional directory (supported starting in VuFind® 2.5) can contain custom [[development:architecture:localization|language files]] to override strings on a per-theme basis.
   * less - This directory contains [[development:architecture:less|LESS]] files, often used to generate a compiled.css file in the css file.   * less - This directory contains [[development:architecture:less|LESS]] files, often used to generate a compiled.css file in the css file.
   * scss - This directory contains SASS files, made available as an alternative to [[development:architecture:less|LESS]] files for developers who prefer the SASS technology.   * scss - This directory contains SASS files, made available as an alternative to [[development:architecture:less|LESS]] files for developers who prefer the SASS technology.
-  * templates - This directory contains PHP templates for rendering all of VuFind's pages.  Most of these templates are named to correspond with controller actions within the VuFind application, though there are also some plugin-specific directories (i.e. Recommend, RecordDriver) and top-level layout pieces (layout/layout.phtml, header.phtml, footer.phtml).+  * templates - This directory contains PHP templates for rendering all of VuFind®'s pages.  Most of these templates are named to correspond with controller actions within the VuFind® application, though there are also some plugin-specific directories (i.e. Recommend, RecordDriver) and top-level layout pieces (layout/layout.phtml, header.phtml, footer.phtml).
   * theme.config.php - As described [[#configuring_a_theme|above]], this configuration file controls which resources (CSS, Javascript, etc.) are automatically loaded by all pages using the theme and which view helpers are available to the theme.  It also specifies a parent theme when using Theme Inheritance (see below).   * theme.config.php - As described [[#configuring_a_theme|above]], this configuration file controls which resources (CSS, Javascript, etc.) are automatically loaded by all pages using the theme and which view helpers are available to the theme.  It also specifies a parent theme when using Theme Inheritance (see below).
  
 ===== Theme Inheritance ===== ===== Theme Inheritance =====
  
-Theme inheritance is the mechanism which allows you to override some or all of the elements of a theme without having to copy and paste the entire contents of the theme.  For example, if you wanted to create a custom MyUniversity theme derived from the default bootprint3 theme, you would set the theme to "MyUniversity" in [[configuration:files:config.ini]] and create a MyUniversity directory under VuFind's themes directory containing a theme.config.php file setting the extends key to "bootprint3" in the configuration array.+Theme inheritance is the mechanism which allows you to override some or all of the elements of a theme without having to copy and paste the entire contents of the theme.  For example, if you wanted to create a custom MyUniversity theme derived from the default bootprint3 theme, you would set the theme to "MyUniversity" in [[configuration:files:config.ini]] and create a MyUniversity directory under VuFind®'s themes directory containing a theme.config.php file setting the extends key to "bootprint3" in the configuration array.
  
-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 main distribution, 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 new headers.phtml and footers.phtml files in your MyUniversity theme's templates folder but leave everything else in bootprint3.//+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 main distribution, 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 new headers.phtml and footers.phtml files in your MyUniversity theme's templates folder but leave everything else in bootprint3.//
  
 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 more helpful to use [[development:recommended_tools:git|Git]] version control 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 more helpful to use [[development:recommended_tools:git|Git]] version control as another possible approach to the problem.
Line 91: Line 89:
 ===== Mix-ins ===== ===== Mix-ins =====
  
-VuFind 4.1 introduced the concept of theme "mix-ins," inspired by PHP Traits. A mix-in is a package of related templates and assets, very similar to a theme but containing only a subset of functionality. These packages can be "mixed in" to a theme by adding a "mixins" array to the theme's theme.config.php file.+VuFind® 4.1 introduced the concept of theme "mix-ins," inspired by PHP Traits. A mix-in is a package of related templates and assets, very similar to a theme but containing only a subset of functionality. These packages can be "mixed in" to a theme by adding a "mixins" array to the theme's theme.config.php file.
  
 The directory structure and configuration for a mixin is identical to that of a theme -- mixins can contain templates, Javascript, CSS, etc. and may define view helpers and other settings. There are only two key differences: The directory structure and configuration for a mixin is identical to that of a theme -- mixins can contain templates, Javascript, CSS, etc. and may define view helpers and other settings. There are only two key differences:
Line 99: Line 97:
 2.) A mix-in may not extend anything, nor may it include additional mix-ins. 2.) A mix-in may not extend anything, nor may it include additional mix-ins.
  
-VuFind ships with a sample mix-in called local_example_mixin, which simply causes an alert box to appear on every page as a proof of concept. You can use the [[development:code_generators#creating_theme_mix-ins|mix-in code generator command-line tool]] to create copies of this example as a foundation for your own mix-in work.+VuFind® ships with a sample mix-in called local_example_mixin, which simply causes an alert box to appear on every page as a proof of concept. You can use the [[development:code_generators#creating_theme_mix-ins|mix-in code generator command-line tool]] to create copies of this example as a foundation for your own mix-in work.
  
 ==== Why Use Mix-Ins? ==== ==== Why Use Mix-Ins? ====
  
-The average VuFind user will probably not have much need to use mix-ins; however, this feature is useful for sharing functionality between VuFind instances. By creating a [[development:architecture:laminas|Laminas]] module full of custom code and a theme mix-in containing custom templates and assets, it should be possible to isolate entire custom features and share them between institutions without having to significantly change core VuFind code.+The average VuFind® user will probably not have much need to use mix-ins; however, this feature is useful for sharing functionality between VuFind® instances. By creating a [[development:architecture:laminas|Laminas]] module full of custom code and a theme mix-in containing custom templates and assets, it should be possible to isolate entire custom features and share them between institutions without having to significantly change core VuFind® code.
  
 ==== Mix-Ins and Inheritance ==== ==== Mix-Ins and Inheritance ====
Line 111: Line 109:
 ===== 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: +See the [[development:architecture:user_interface:icon_set|Icon Set]] page for icon-related discussion/notes.
- +
-  * [[http://p.yusukekamiyamane.com/|Fugue]] (Copyright © Yusuke Kamiyamane) +
-  * [[http://www.famfamfam.com/lab/icons/silk/|Silk]] +
-  * [[http://damieng.com/creative/icons/silk-companion-1-icons|Silk Companion Icons]] +
-  * [[http://tango.freedesktop.org/|Tango]] +
- +
-See also the [[development:architecture:user_interface:icon_set|Icon Set]] page for more icon-related discussion/notes.+
  
 ===== Related Video ===== ===== Related Video =====
  
-The [[videos:creating_themes|Creating Themes]] video provides an introduction to VuFind's theme system.+The [[videos:creating_themes|Creating Themes]] video provides an introduction to VuFind®'s theme system.
 ---- struct data ---- ---- struct data ----
 +properties.Page Owner : 
 ---- ----
  
development/architecture/user_interface.1627998979.txt.gz · Last modified: 2021/08/03 13:56 by demiankatz