Both sides previous revisionPrevious revisionNext revision | Previous revisionNext revisionBoth sides next revision |
development:architecture:user_interface [2017/08/02 16:15] – [Configuring VuFind's Theme Options] demiankatz | development:architecture:user_interface [2020/03/04 13:40] – [Why Use Mix-Ins?] demiankatz |
---|
====== User Interface Customization ====== | ====== 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. | 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. |
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: | 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 to include CSS files. 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.// | * 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.// |
| |
| |
To take advantage of Javascript inheritance, use the $this->headScript() view helper. | 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: |
| |
| 1.) The configuration for a mix-in is called mixin.config.php, not theme.config.php. |
| |
| 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. |
| |
| ==== 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 ===== | ===== Icon Libraries ===== |