---json
{
    "aliases": [
        { "path": ":howto:create-theme" }
    ],
    "page_id": "092ki81cch4a60u9jd4h6"
}
---
====== How to create your own theme? ======

===== About =====

This page shows you how to create your own theme.

You can then apply advanced design and logic to your whole website application.

===== Theme introduction =====


Combostrap uses a theme system where:
  * each page has its own [[:docs:theme:template:template|template]]
  * and each template is a [[https://github.com/salesforce/handlebars-php|Handlebars template]] that is rendered as HTML page.

===== Steps =====

==== Where is the default theme ?====

The ''Combostrap'' default theme is located in this directory
<code>
dokuwiki_home/lib/plugins/combo/resources/theme/default
</code>

If you discover this theme, you will this layout directory:
  * the directory ''pages'' that contains:
      * the ''templates'' directory that contains:
         * The handlebar templates (''hbs'' file)
         * The template definition (''yml'' file).
      * the ''partials'' directory that contains the partials. They are chunks of handlebar templates that can be included in templates.
  * the directory ''components'' that contains:
      * the ''css'' directory that contains the stylesheet of each component
      * the ''html'' directory that contains the HTML templates of component
  


{{:howto:combostrap-default-theme-file-explorer.png|}}
=== What are handlebar templates (hbs)? ===
''Handlebar templates'' are files that are written in the following two languages:
  * HTML
  * and the [[https://github.com/salesforce/handlebars-php#expressions|handlebar templating language]].

They get an array of data called a model and replace their value at runtime.

To simplify, the model is:
  * The [[:docs:templating:variable|variable data]]
  * The content in HTML.
If you want to get the whole model definition, [[:support|contact us]].

For instance, the following handlebars expression would be replaced with the [[:docs:page:title|page tile]]
<code handlebars>
{{ title }}
</code>

=== What are template definition files (yml)? ===

The template definition files contain properties that apply to the template.

For instance, if you want to use [[:docs:theme:slot:slot|slots]] in your template, you need to define them.

The [[docs:theme:template:medium|median template]] for instance contains 4 slot elements.
<code yml median.yml>
slots:
    - 'page-header'
    - 'page-footer'
    - 'main-header'
    - 'main-footer'
</code>

=== What are partials? ===
''Handelbar partial'' are handlebars syntax that can be included and therefore reused in templates.

For instance, the below handlebars syntax will include the partial ''page-footer-partial.hbs'' that contains the [[:docs:theme:element:page-footer|footer]] of each template.
<code handlebars>
{{>page-footer-partial}}
</code>

=== What are components stylesheet? ===

A [[docs:theme:component-stylesheet|component stylesheet]] is a tiny CSS stylesheet that is applied when a component is used on your page.

It will overwrite the default styling of your [[:docs:theme:bootstrap|bootstrap stylesheet]].
==== Creation of your theme directory ====

Combostrap looks at themes in the directory ''combo/theme'' located in the [[doku>config:savedir|data directory]]

For a standard [[:howto:getting_started:1_dokuwiki|dokuwiki installation]], the directory is:
<code>
dokuwiki_home/data/combo/theme
</code>

If you name your theme, ''mytheme'', you should then create the following directories
<code>
dokuwiki_home/data/combo/theme/mytheme
dokuwiki_home/data/combo/theme/mytheme/components/css
dokuwiki_home/data/combo/theme/mytheme/components/html
dokuwiki_home/data/combo/theme/mytheme/pages/templates
dokuwiki_home/data/combo/theme/mytheme/pages/partials
</code>

==== Selecting your theme ====

Now that you have created your theme directory, you can select it.

  * Open the [[:docs:app:configuration|app configuration]]
  * Search for the configuration ''combo-conf-005''
  * And select your theme

{{:howto:theme-configuration-value-choice.png|}}

==== Creation of your first template ====

  * Go to the default theme directory
  * Copy the [[docs:theme:template:medium|median]] template by transferring it into your custom template theme directory:
    * the file ''median.hbs''
    * the file ''median.yml''
  * Rename them to
    * ''custom-median.hbs''
    * ''custom-median.yml''
  * You should now have two files
<code>
dokuwiki_home/data/combo/theme/mytheme/pages/templates/custom-median.hbs
dokuwiki_home/data/combo/theme/mytheme/pages/templates/custom-median.yml
</code>
  * Open the file ''custom-median.hbs'' and add modify the html header. Below we take over the page heading
<code handlebars>
<header id="main-header">
  <h1>Custom title: {{ title }}</h1>
</header>
</code>

==== Choose your new template for your page ====

  * Open the page 
  * Choose your ''custom-median'' [[:docs:theme:template:template|template]] in the [[:docs:metadata:manager|metadata manager]].

{{:howto:template-selection-meta-manager.png|}}

  * And refresh your page by pressing ''F5''
  * The custom title was applied.

{{:howto:theme-creation-custom-title-result.png?600|}}

==== How to apply a template for a whole namespace? ====


The default template follows the following pattern:
  * ''namespacename-index'' for an [[:docs:page:system:index|index page]]
  * ''namespacename-item'' for an [[docs:page:system:item|item page]]

If you want to apply the same template for the namespace '':howto'', you need to create the following templates:
  * ''howto-index''
  * and ''howto-item''

Note that these templates will be applied by default on every namespace that has this name. For instance, they will also be applied to the namespace '':docs:howto''. 

If you want to be more precise, you need to add all namespace name parts in the name of the template. In our case, you need to create the following templates:
  * ''docs-howto-index''
  * ''docs-howto-item''
==== Next ====

From there, you can create any theme that suits your needs.