Theme hooks allow you to modify the HTML templates. The HTML templates within the IPS Community Suite are structured into groups, locations and applications. Each application will have at least 3 locations:
- front (templates used for the front-end)
- admin (templates used for the Admin CP)
- global (templates which are used for both)
Though some applications may have more for specific purposes (for example, the core application has another location for installer/upgrader called setup). Each location can contain any number of groups - groups are generic collections of templates, for example, the core application has one group (in the front location) called messaging which contains all the templates for composing and viewing personal conversations.
One Theme Hook acts on one template group.
You can create Theme Hooks in the Plugin Developer Center. Once created there are two ways to use Theme Hooks - each of which work differently and so will be appropriate for different circumstances.
Editing your Theme Hook in the Plugin Developer Center will display a panel showing all of the templates in that group:
Selecting any template will bring up a tabbed interface showing the modifications your Theme Hook is making to that template, and allow to create more:
To make a modification to the selected template, you will provide a CSS selector - you can use any of the selectors supported by jQuery (it's worth mentioning that jQuery isn't involved in making your Theme Hook work, it is simply that the supported selectors are the same). The easiest way to choose a selector is with the interactive "Select Element" feature, which will launch a model displaying the template allowing you to simply click on the element you want to use:
It is important to note that when using the "Select Element" feature, it will use the most specific CSS selector it can for the element selected, however, that selector may also match other elements so you may need to adjust it.
When providing the content, in addition to the variables that are available to the template (which are shown next to the editor) you can also use any variables available at that point in the template (for example, if you're inserting code within a foreach loop, you can use the variables created by it). You can also use template logic and template tags.
Under the hood, each template group is compiled into a PHP class, with a method for each template. You can extend this class by manually editing the file which will have been created in /plugins/<your plugin>/hooks.
It is important to note that when using this mode, you are overloading the compiled template group so the return value will be the HTML that will be displayed, without any template logic or template tags.
All of the same considerations as for Code Hooks (see "Important things to remember when creating code hooks") also apply here.