Allow /local and custom theme override of Plugin templates

[Aaron Wells]

One of the handiest features for site admins to tweak their Mahara site without making hacks that make upgrades difficult, is the relatively obscure local theme overrides feature: https://wiki.mahara.org/index.php/Customising/Themes/1.2#Local_theme_overrides

Theme support is there, but you have to put the theme template dirctories under the plugin's own theme directory. i.e. artefact/internal/theme/primary/static/templates/content.tpl . So, this is handy for plugin authors, but not for custom theme developers.

I propose the following:

1. We allow for /local overrides of plugin templates. The path should be local/theme/templates/{plugintype}/{pluginname}/{template} . Or in the case of plugins that live underneath other plugins (i.e. blocktypes under artefacts) local/theme/templates/{plugintype1}/{pluginname1}/{plugintype2}/{pluginname2}/{template}.

So:

local/theme/templates/artefact/internal/content.tpl
local/theme/templates/artefact/internal/blocktype/textbox/content.tpl

2. For custom themes, we take a similar approach: theme/{themename}/static/templates/{plugintype}/{pluginname}/{template}

theme/aaronstheme/static/templates/artefact/internal/content.tpl
theme/aaronstheme/static/templates/artefact/internal/blocktype/textbox/content.tpl

And in order of precedence:

1. /local theme overrides
2. custom theme located under /theme directory
3. theme template files locate under plugin's directory

[Aaron Wells (u-aaronw)]

Hm, I've taken a crack at implementing this, and I've got a system working for templates as described above. But, I realize I need to do something similar for static assets, i.e. images and stylesheets.

Which brings up a question of directory structures. Within the custom theme directory, should we have a directory for each plugin, each with its own "templates" and "static" subdirectories? Or, within the theme's main "templates" and "static" subdirectories should there be a separate directory for each plugin?

Option 1: Multiple "templates" and "static" subdirectories:

theme/
+- raw/
  +- templates/
    +- index.tpl
  +- static/
    +- images/
      +- mahara--logo.png
  +- blocktype/
    +- clippy/
      +- templates/
        +- clippy.tpl
      +- images/
        +- thumb.png
    +- creativecommons/
      +- templates/
        +- summary.tpl
      +- assets/
        +- images/
          +- cclogo.png

Option 2: Multiple plugin subdirectories

theme/
+- raw/
  +- templates/
    +- index.tpl
    +- blocktype/
      +- clippy/
        +- clippy.tpl
      +- creativecommons/
        +- summary.tpl
  +- static/
    +- images/
      +- mahara-logo.png
    +- blocktype/
      +- clippy/
        +- images/
          +- thumb.png
      +- creativecommons
        +- images/
          +- cclogo.png

Basically the choice comes down to grouping files together by type (static v templates) or grouping them together by plugin.

[Aaron Wells (u-aaronw)]

Another weird thing, is that under the current system, plugin theme directories don't actually contain a "templates" directory like normal theme directories. Instead the templates sit loose in the root level of the plugin theme directory. In other words:

Expected location:
/blocktype/clippy/theme/raw/templates/path/to/template.tpl

Actual location:
/blocktype/clippy/theme/raw/path/to/template.tpl

Static assets on the other hand, are under a "static" directory. Maybe part of my fix should be to regularize plugin theme directories. Or, keep it so they support having the templates loose (so that non-updated plugins will continue to work) but add a theme/templates directory to the search path.

[Mahara Bot (dev-mahara)]

Patch for "master" branch: https://reviews.mahara.org/3425

[Aaron Wells (u-aaronw)]

I decided it was most beneficial to group the files together by plugin (scenario #1 in my comment above).

I also spun off the plugin "templates" directory issue into a separate bug: https://bugs.launchpad.net/mahara/+bug/1328319

Also, I realized that /local/theme template files were *not* overriding normal theme files like I thought they were. So I spun off another bug to make that work the way I expected it to: https://bugs.launchpad.net/mahara/+bug/1328310

[Mahara Bot (dev-mahara)]

Patch for "master" branch: https://reviews.mahara.org/3428

[Mahara Bot (dev-mahara)]

Reviewed: https://reviews.mahara.org/3428
Committed: http://gitorious.org/mahara/mahara/commit/97e96de04a988b4144da29806ed94348f3439b37
Submitter: Son Nguyen (<email address hidden>)
Branch: master

commit 97e96de04a988b4144da29806ed94348f3439b37
Author: Aaron Wells <email address hidden>
Date: Tue Jun 10 13:19:12 2014 +1200

Refactor the Dwoo_Template_Mahara files

Bug 1231755

- Cleanup, documentation, and removing replicated code.

- Not checking for whether the file exists. We'll just make a list
of search paths and pass those through to Dwoo_Template_File, and
let it determine which path has the file.

- Eliminating the separate Dwoo_Template_Mahara classes for plugintypes,
and moving the custom logic for how plugintypes find their template files,
into the Plugin class itself.

Change-Id: I877a4221323333e8e8b6c6df54062a0f8bf2b817

[Mahara Bot (dev-mahara)]

Patch for "master" branch: https://reviews.mahara.org/3441

[Mahara Bot (dev-mahara)]

Reviewed: https://reviews.mahara.org/3441
Committed: http://gitorious.org/mahara/mahara/commit/2bdb96c715b5d9e0148f322ae0ebbc67526cddeb
Submitter: Aaron Wells (<email address hidden>)
Branch: master

commit 2bdb96c715b5d9e0148f322ae0ebbc67526cddeb
Author: Aaron Wells <email address hidden>
Date: Fri Jun 13 14:33:36 2014 +1200

Dwoo includes were breaking when the plugintype was written as uppercase

Bug 1231755

Change-Id: I198f04bb652d3220bcceb77c685edcae2fe68e52

[Mahara Bot (dev-mahara)]

Reviewed: https://reviews.mahara.org/3440
Committed: http://gitorious.org/mahara/mahara/commit/da4efc6accef590307190852b7b531b8b8a8d5dc
Submitter: Aaron Wells (<email address hidden>)
Branch: master

commit da4efc6accef590307190852b7b531b8b8a8d5dc
Author: Aaron Wells <email address hidden>
Date: Fri Jun 13 14:11:56 2014 +1200

Incorrect Dwoo template paths

Bug 1231755. The refactor of the Dwoo_Template_Mahara class also closed
a bug in the include path, which made it so that, in the template files
of plugins, if you had an {include} tag which tried to include a core
Mahara template file, it would also have the plugin's own theme
directory on the search path.

It turns out the blocktype/activitystream and search/elasticsearch plugins
had code which depended on this bug. They referred to plugin template
files as if they were core template files, and relied on the bug to locate
them appropriately.

Change-Id: Iec6b0d41d41c540166c972ec9a3dfc80e646cb98

[Mahara Bot (dev-mahara)]

Reviewed: https://reviews.mahara.org/3425
Committed: http://gitorious.org/mahara/mahara/commit/fd85506f254ebc3675718ce54029ff96a4c13856
Submitter: Yuliya Bozhko (<email address hidden>)
Branch: master

commit fd85506f254ebc3675718ce54029ff96a4c13856
Author: Aaron Wells <email address hidden>
Date: Mon Jun 9 20:24:58 2014 +1200

Allow plugin theme files to live under the /theme and /local directory

Bug 1231755. In order to make it easier for custom theme authors to customize
the appearance of plugins, I'm adding the /theme directory to the search path
for plugin files.

Example: smarty->display('artefact:fun:path/to/file.tpl')

Old searchpath:

/artefact/fun/theme/(themename)/path/to/file.tpl

New searchpath (in order of precedence):

1. /local/theme/artefact/fun/templates/path/to/file.tpl
2. /theme/(themename)/artefact/fun/templates/path/to/file.tpl
3. /artefact/fun/theme/(themename)/path/to/file.tpl

Further notes:

The /local directory doesn't have separate copies for separate
themes. It's a sitewide override of all themes.

For some reason theme directories under plugins don't have a "templates"
directory. The templates sit loose under the theme directory. In my new
version, plugin directories under themes DO have a "templates" directory.

Change-Id: Id90ee1d1dec0bda93a0d30e54229fd7dacbe5b96

[Kristina Hoeppner (kris-hoeppner)]

For a quick overview of what's new, see https://mahara.org/interaction/forum/topic.php?id=6342&offset=0&limit=10#post26920