Hotaru Docs

 [həʊdɒks]

Customizing Plugin Templates

The Problem

Hotaru itself doesn't have many templates in its default theme. That's because plugins extend Hotaru by providing their own templates.

Wouldn't upgrading a plugin overwrite template customizations?

Yes. This is a problem with most CMS plugin systems. Take Wordpress for example. If you edit a plugin, you're going to lose those edits when you upgrade that plugin.

In Hotaru, if you've customized a template in a plugin, e.g. bookmarking_post.php in the Bookmarking plugin, you'll lose your edits if you upgrade. Fortunately, most customization will use CSS, so you shouldn't need to physically edit the template files anyway. Of course, if you do make edits, you'll need a workaround...

Note about CSS: In the default theme's header.php template, plugin files are included before a theme's style.css file. Therefore, the latter takes precedence over any css files included from plugins.

The Solution

Before looking in the plugin folder for a template, Hotaru looks for it in your theme folder. That means you can copy a template from a plugin into your theme folder, keeping it safe from any unwanted upgrades. When new versions of plugins become available, you can simply compare your existing template to the new one and copy any new features into it.

E.g. Copy a plugin template from 
/content/plugins/plugin_name/templates/template_name.php
to 
/content/themes/theme_name/template_name.php
The same applies to CSS, JavaScript and language files, just make sure you put those in folders named css, javascript and languages within your theme folder. Hotaru will look for them there before using the ones in a plugin. 
/content/themes/theme_name/css/
/content/themes/theme_name/javascript/
/content/themes/theme_name/languages/

Going further...

Hotaru doesn't just look in your theme folder before the plugin folder. Let's imagine Hotaru is looking for the bookmarking_post.php template that comes with the Bookmarking plugin. Here's what it does:

  1. Check the user's theme folder for bookmarking_post.php
  2. If not found, check the default theme folder for bookmarking_post.php
  3. If not found, use bookmarking_post.php from the Bookmarking plugin.

That means you could put the templates in the default theme and change your theme without having to copy any more files.

Here's how Hotaru finds the language it needs:

  1. Check the user's language pack for bookmarking_language.php (for example)
  2. If not found, use the language file from the plugin

That means you can copy all the plugin language files to your own language folder.

Here's how Hotaru finds the css it needs:

  1. Check the css folder in the user's theme for bookmarking.css (for example)
  2. If not found, check the css folder in the default theme
  3. If not found, use the css file from the plugin

That means you can copy all the plugin css files to your own css folder.

Here's how Hotaru finds the javascript it needs:

  1. Check the javascript folder in the user's theme for bookmarking.js (for example)
  2. If not found, check the javascript folder in the default theme
  3. If not found, use the javascript file from the plugin

That means you can copy all the plugin javascript files to your own javascript folder.

Note: Hotaru automatically combines all plugin CSS files together into a single cached stylesheet, and the same for JavaScript files, too. That means you don't have to worry about too many files slowing Hotaru down.

Getting Started • Design and Layout • Plugin Development • Advanced Topics • Function Reference • Troubleshooting
Retrieved from "http://docs.hotarucms.org/index.php/Customizing_Plugin_Templates"