Differences

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

--- development:architecture:user_interface [2017/08/02 15:55] – [Configuring VuFind's Theme Options] demiankatz
+++ development:architecture:user_interface [2023/11/09 19:27] – [Icon Libraries] demiankatz
@@ Line 1: / Line 1: @@
 ====== User Interface Customization ======
-// This page refers to VuFind 2.x and later; for 1.x documentation, see [[legacy:vufind_1.x_developer_manual:user_interface_customization|User Interface Customization (VuFind 1.x)]]. //
+:!: // 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.
@@ Line 7: / Line 7: @@
 ===== Technical Background =====
-VuFind is developed using PHP templates for HTML and 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.
@@ Line 15: / Line 15: @@
 ==== Creating a Theme ====
-Starting with VuFind 4.1, a 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 ====
@@ Line 25: / Line 25: @@
 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 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 ====
-The first thing you'll have to set up in a new theme is the file **theme.config.php**. This file allows you to establish your theme as a child of another theme (see the section below on Theme Inheritance for more on this) and allows you to add new CSS and Javascript files (among other things). If you've created custom [[development:plugins:view_helpers|view helpers]], you will also set up their service manager configuration in this file. You only need to add settings here that wouldn't be loaded from a parent theme via inheritance (such as adding a new jQuery plugin).
+The first thing you'll have to set up in a new theme is the file **theme.config.php**. This file allows you to establish your theme as a child of another theme (see the section below on [[#theme_inheritance|Theme Inheritance]] for more on this) and allows you to add new CSS and Javascript files (among other things). If you've created custom [[development:plugins:view_helpers|view helpers]], you will also set up their service manager configuration in this file. You only need to add settings here that wouldn't be loaded from a parent theme via inheritance (such as adding a new jQuery plugin).
-A basic setup is already included in the custom theme template. For a full example, see the [[https://github.com/vufind-org/vufind/blob/master/themes/bootstrap3/theme.config.php|bootstrap config file]].
+A minimal setup is already included in the template used by the custom theme generator. For a full example, see the [[https://github.com/vufind-org/vufind/blob/dev/themes/bootstrap3/theme.config.php|bootstrap config file]].
+After establishing the basic configuration, you can add template and resource files to your theme. Understanding the structure and inheritance rules described below should help you achieve the desired effects.
+==== 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.
+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]].
+<code php>
+<?php $this->slot('footer-left')->start(); ?>
+    <p>Custom left foot(er)</p>
+<?php $this->slot('footer-left')->end(); ?>
+<?php include $this->parentTemplate('footer.phtml'); ?>
+</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.
+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 =====
@@ Line 40: / Line 60: @@
   * 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.
+  * 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.
   * 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 - 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 =====
@@ Line 55: / Line 77: @@
 The way CSS inheritance works requires a few notes.  If you are going to take advantage of this feature, here are some important things to keep in mind:
-  * Always use Zend Framework's $this->headLink() helper to include CSS files.  If you don't use the helper, CSS inheritance will not happen!
+  * Always use [[development:architecture:laminas|Laminas]]' $this->headLink() helper (as opposed to inline HTML tags) when you need to include specific CSS files in your templates.  If you don't use the helper, CSS inheritance will not happen!
   * 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.//
@@ Line 66: / Line 88: @@
 To take advantage of Javascript inheritance, use the $this->headScript() view helper.
+===== 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.
+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 configuration for a mix-in is called mixin.config.php, not theme.config.php.
+.) 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.
+==== 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.
+==== Mix-Ins and Inheritance ====
+Note that when you load a mix-in into a custom theme, the custom theme's templates and other files take precedence over the mix-in's. This allows you to load and customize a mix-in. However, it means that you cannot load a mix-in into an existing theme and overwrite that theme's behavior. The expected way of using mix-ins is to create a new custom child theme that extends an existing core theme, adds mix-ins to it, and then locally customizes those mix-ins as needed.
 ===== Icon Libraries =====
@@ Line 71: / Line 113: @@
 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:
+  * [[https://fontawesome.com/|Font Awesome]] (Font: SIL OFL 1.1 License, Icons: CC BY 4.0 License)
+  * [[https://remixicon.com/|Remix Icons]] (Apache License, Version 2.0)
   * [[http://p.yusukekamiyamane.com/|Fugue]] (Copyright © Yusuke Kamiyamane)
-  * [[http://www.famfamfam.com/lab/icons/silk/|Silk]]
+  * [[https://github.com/legacy-icons/famfamfam-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 =====
+The [[videos:creating_themes|Creating Themes]] video provides an introduction to VuFind's theme system.
 ---- struct data ----
+properties.Page Owner :
 ----