An Introduction to the New Frontend Template Structure

January 18th, 2016 by  | Comments Off on An Introduction to the New Frontend Template Structure

When we redesigned the OJS/OMP backend, we introduced a separation between the frontend and the backend which should make customizing the frontend a lot easier. In this post, I’ll introduce you to some of those changes and what they mean for the future of theming our software.

In this post I’ll provide links to code on our GitHub repositories and code snippets. You will need some understanding of PHP/HTML/CSS/LESS code to understand these.

Separation of frontend and backend

The look of the backend is now completely independent of the frontend, with a different set of templates and a unique stylesheet. To make things easier, we’ve isolated (almost) all of the frontend templates within their own directories:

pkp-lib/templates/frontend

ojs/templates/frontend

omp/templates/frontend

Each of these directories is organised into a set of subdirectories:

/pages

This directory contains all of the top-level template files that are called by the application. For instance, a request to the homepage returns the /pages/index.tpl file. A request to an announcement returns the /pages/announcement.tpl file.

Each of these template files represents an entire page request. If you’re trying to hunt down the HTML code for a particular element, this is your first point of entry. In general, page template files will not handle many things themselves, but will instead include various other template files as needed.

/objects

This directory contains template files which map to a particular data object. In OJS you’ll find specific views for a particular issue or article. In OMP you’ll find specific views for a specific monograph.

Each of these template files represents a particular view of the data object. So there is article_summary.tpl for displaying the article in, for instance, an issue table of contents. And there is article_details.tpl for displaying the article on its own page.

/components

This directory contains template files which handle specific UI components or templates that don’t fit into other places. For instance, our breadcrumb navigation and search form elements are defined in component template files. You’ll also find components for lists of objects, such as the list of monographs used across the OMP catalog.

Other frontend templates

You’ll find a few template fragments in other places right now. We’re working to bring all of them under the /templates/frontend directories for easily locating them.

Frontend template variable documentation

Along with the new frontend template structure, we’ve made a concerted effort to better document the variables that each template expects. You’ll find these identified by @uses in the doc blocks at the top of template files.

Let us know if we’ve missed any!

Overriding template files

You can easily override any of the template files in your own custom theme. You do this by adding a /templates directory to your theme plugin, and then adding the template file you’d like to override.

For example, if you wanted to define your own custom homepage, you’d find the template you want to modify. In this case, it’s /template/frontend/pages/index.tpl. You’d then copy that file into a subdirectory in your theme that follows the same pattern. In this case, that means /plugins/themes/your-theme/template/frontend/pages/index.tpl. You could then customize that file and it would override the core template.

This way, when you need to update OJS/OMP, you won’t have to go back in and adjust your templates again.

Modifying the CSS stylesheet

Our CSS is generated from many different files which mimic the file structure of our template files. You’ll find the stylesheets within the theme plugins themselves. These are combined and compiled into the frontend stylesheet.

You’ll find /objects and /pages directories with styles applying to their counterparts in the template directories. For instance /plugins/themes/default/styles/objects/monograph_summary.less defines styles which apply to the monograph summary template in /templates/frontend/objects/monograph_summary.tpl.

The stylesheets aren’t a one-to-one match, though. There are a number of general files which you may want to be aware of:

  • index.less – Loads all the different files for compilation into the CSS file. If you’ve created your own file with customizations, make sure you’ve imported it here.
  • variables.less – Common definitions for colours, font sizes, spacings, borders and more. If you just want to change colours, you should only ever have to touch this file.
  • components.less – All template component styles are in this one file, as well as a few other css-only reusable components, like button styles.

You’ll find some other files in there which house various style elements:

  • body.less – Site-wide elements and layout scaffolding (eg – responsive grid).
  • footer.less – All styles relating to the footer.
  • head.less – All styles relating to the header.
  • helpers.less – Helper components. These are often utility classes assigned to various elements but without being restricted or attached to any one specific component.
  • main.less  – Generalizable styles for main content on a page (<h*> elements and other things)
  • sidebar.less – All styles relating to the sidebar.

OMP users will be familiar with the LESS coding language we use to generate our CSS stylesheets. It may be new OJS developers who haven’t worked with the 3.0 development version.

LESS looks very similar to CSS, but supports variables and block-level nesting (among many other tricks) which will make your life a lot easier if you want to tweak the existing styles. I’ll do a  more detailed walkthrough in a future post. But don’t be put off just yet if it looks unfamiliar to you.

Note that LESS files are compiled into a cached CSS file. If you change one of the LESS files, you’ll need to trigger re-compilation. This is best done by removing any .css files from your cache/ directory; they’ll be generated again as needed. It’s not safe to edit the CSS files in cache/ directly, as changes will eventually be overwritten.

Other theme plugin possibilities

Adding new stylesheets and overriding built-in templates are the most common things you’ll do with a theme plugin, but since theme plugins are full-fledged plugins, there are many more possibilities. Theme plugins are free to work with the system’s API, register hooks, etc., as long as the lifecycle of a theme plugin (particularly the point in execution at which it is loaded) suits the task you want to accomplish.

Working towards a multi-theme environment

We’re just getting started with the theming capabilities in OJS 3.0 and OMP 1.2. In the future, we hope to be able to offer more than one official theme. And we’d like to recruit people from our community to build and maintain community-supported themes. With the changes we’ve introduced, this should be easier than ever.

In the future, I’ll go into greater detail about adjusting template files, working with the new CSS code and building custom themes. If there’s anything specific you’d like to learn about, let us know in the comments below. Or reach out on Twitter @pkp.

Comments are closed.