Skip to content

Commit

Permalink
Update theme documentation
Browse files Browse the repository at this point in the history
  • Loading branch information
@vaemendis
vaemendis committed Oct 8, 2023
1 parent 6eece94 commit 2409aff
Show file tree
Hide file tree
Showing 2 changed files with 123 additions and 34 deletions.
110 changes: 81 additions & 29 deletions pages/theme-creation.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -9,20 +9,20 @@ title: Create a new theme

## Themes compatibility

Ubooquity 3 introduced a new theme system that gives full control over the served CSS, HTML and Javascript content.
Ubooquity 3 introduces a new theme system that gives full control over the served CSS, HTML and Javascript content.
However, this new system makes previous themes (for Ubooquity 2.x) incompatible wih Ubooquity 3.x.

## Generate a new theme template

In Ubooquity administration page, in the `General` section, click the `Create new theme...` button and choose the name of your theme. A folder with that name will be created in Ubooquity's working directory (by default the folder from where you launched it).
In Ubooquity administration page, in the `General` section, click the `Create new theme...` button and enter the name of your theme. A folder with that name will be created in Ubooquity's working directory (by default the folder from where you launched it).
This new folder will contain all the files of the default theme, that you can now edit to your liking.


## Edit the theme files

<div class="infobox">
When creating a theme, you only need to include the files that differ from the default theme. If Ubooquity needs to display a file and doesn't find it in your theme, it will fall back to the default theme version.
This makes the default theme very easy to tweak (you don't need to write a full theme).
This makes the default theme very easy to tweak (you don't need to all the files of a full theme).
</div>

Here are the structure and principal files of a theme:
Expand All @@ -49,67 +49,119 @@ your_theme_name
page-login.html ──> Login page
```

The five `page-*.html` files are the pages served by Ubooquity, they must exist in all themes.
The five `page-*.html` files are the pages served by Ubooquity, they are the entry points of the theme.
`inc-*.html` files are just HTML fragments included in page files by the templating engine, you can keep them, or remove them (or create new ones) depending on the structure of your theme.

### Templating syntax

The template files use the [**Mustache**](https://mustache.github.io/) syntax for variable substitution.
The complete syntax can be found in [Mustache syntax documentation](https://mustache.github.io/mustache.5.html).

> Insert examples
The main Mustache features used in the default theme are the following.

### Resources path (images, CSS...)
Themes contain template files but also resources (usually images and CSS).
Using such resources in your theme means using their URL, which fall into 2 categories depending on their usage location.
#### Variable substitution

Variables enclosed in `{{...}}` are replaced with values provided by Ubooquity.
See the [**variables reference page**](https://vaemendis.github.io/ubooquity-doc/pages/theme-variables-reference.html) for an exhaustive list of available variables for each page.

#### Sections

Mustache sections can be used to hide or show blocks of text depending on a varaible value.
They start with `{{#...}}` and end with `{{/...}}`.

```
{{#myVariable}}
<div>Some text</div>
{{/myVariable}}
```
The `div` block will be displayed only if `myVariable` is **not** `false` nor empty.

... unified path: "/..." -> only
Inverted sections, starting with `{{^...}}`, can be used to obtain the opposite behaviour: the block will be displayed if the value is false or empty.

<div class="infobox">
... auto sub in case of reverse proxy (CSS and templates only, not JS)
</div>
#### List sections

.. activate debug to get values of variables
When the variable is a list of objects, the content of the sections is rendered once for each element of the list.
Fields of the object then become variables that can be accessed using the usual `{{...}}` syntax.

**Example**
A list of book objects (`items`) with the following values
```
items:
- itemTitle: "Red Prophet"
itemCoverUrl: "/proxy-prefix/cover/3646"
- itemTitle: "Green Mars"
itemCoverUrl: "/proxy-prefix/cover/3645"
```
using the follwing template
```
{{#items}}
<div class="book">
<img src="{{itemCoverUrl}}"/>
<div class="title">{{itemTitle}}</div>
</div>
{{/items}}
```
will be rendered as the following HTML
```
<div class="book">
<img src="/proxy-prefix/cover/3646"/>
<div class="title">Red Prophet</div>
</div>
<div class="book">
<img src="/proxy-prefix/cover/3645"/>
<div class="title">Green Mars</div>
</div>
```

#### Partials

Mustache templates can import other Mustahce templates ("partials") with the `{{>...}}` syntax.

**Example**
```
{{>common/inc-header.html}}
```

### Resources path (images, CSS...)

Themes contain template files but also resources (usually images and CSS).
Using such resources in your theme means accessing them through their URL.

#### Using a theme resource in a template file

When using a theme resource link in a template, the URL must start with the current Ubooquity URL, that you get through the `rootUrl` variable, followed by the `theme` path. The rest of the path is your theme structure (the name of your theme does **not** appear in the URL though).
When using a theme resource link in a template, the URL must start with the current Ubooquity URL, that you get through the `rootUrl` variable, followed by the `theme` path.
The rest of the path is your theme structure (the name of your theme does **not** appear in the URL though).

**Example:** using a css file in a template
**Example:** using a CSS file in a template
```
<link rel="stylesheet" type="text/css" href="{{rootUrl}}/theme/library/books.css"/>
<link rel="stylesheet" type="text/css" href="{{rootPath}}/theme/library/books.css"/>
```
- `{{rootUrl}}/theme/` is the path of Ubooquity's theme provider (whatever the theme)
- `{{rootPath}}/theme/` is the path of Ubooquity's theme provider (whatever the theme)
- `library` is a folder inside the theme. The theme name (this one is "default") does not appear.


#### Using a theme resource in a CSS file

All CSS files inside a theme are considered Mustache templates, the `{{rootPath}}` is always available.

**Example**: using an icon from the theme

====

For advanced use, additional syntax capabilites are offered by the specific implementation of Mustach used by Ubooquity: [**JMustache**](https://github.com/samskivert/jmustache#special-variables) (see the "Special variables" section).

```
#arrowleft {
background-image:url('{{rootPath}}/theme/library/arrowleft.svg');
background-repeat:no-repeat;
}
```


## Advanced features

For advanced use, additional syntax capabilites are offered by the specific implementation of Mustach used by Ubooquity: [**JMustache**](https://github.com/samskivert/jmustache#special-variables) (see the "Special variables" section).

- CSS variables (cover W H and rootUrl)
- template files
- mustache, jmustache
- explanation of basic features
- template paths are relative to theme folder
- resource paths (e.g. image paths in your css or template files) must be prefixed with the absolute path "/theme/"


## Appendix: template variables

The list of variables available for each template page [is available here](https://vaemendis.github.io/ubooquity-doc/pages/theme-variables-reference.html).



47 changes: 42 additions & 5 deletions pages/theme-variables-reference.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -56,15 +56,52 @@ You can print all these variables and their actual values in your logs by activa



## CSS files

### Relevant templates

All CSS files.

### Variables

<table class="jh-type-object jh-root">
<tbody class="">
<tr class="header">
<td>Name</td>
<td>Example value</td>
<td>Description</td>
</tr>
<tr>
<th class="jh-key jh-object-key">rootPath</th>
<td class="jh-value jh-object-value">
<span class="jh-type-string">/proxy-prefix</span>
</td>
<td>The prefix part of Ubooquity URL if a proxy is defined, an empty string otherwise.</td>
</tr>
<tr>
<th class="jh-key jh-object-key">coverWidth</th>
<td class="jh-value jh-object-value">
<span class="jh-type-string">160</span>
</td>
<td>Width of an item cover.</td>
</tr>
<tr>
<th class="jh-key jh-object-key">coverHeight</th>
<td class="jh-value jh-object-value">
<span class="jh-type-string">230</span>
</td>
<td>Height of an item cover.</td>
</tr>
</tbody>
</table>





## Login page

### Templates used
### Relevant templates

- `login/page-login.html`
- `common/inc-header.html`
Expand Down Expand Up @@ -146,7 +183,7 @@ You can print all these variables and their actual values in your logs by activa

## Home page

### Templates used
### Relevant templates

- `home/page-home.html`
- `common/inc-header.html`
Expand Down Expand Up @@ -281,7 +318,7 @@ You can print all these variables and their actual values in your logs by activa

## Library - category root folders page

### Templates used
### Relevant templates

- `library/page-library-category-root-dirs.html`
- `common/inc-header.html`
Expand Down Expand Up @@ -545,7 +582,7 @@ You can print all these variables and their actual values in your logs by activa

## Library - items page

### Templates used
### Relevant templates

- `library/page-library.html`
- `common/inc-header.html`
Expand Down Expand Up @@ -668,7 +705,7 @@ Same variables as for the **Library - category root folders** page above, withou

## Library - item details

### Templates used
### Relevant templates

- `library/page-library-details.html`

Expand Down

0 comments on commit 2409aff

Please sign in to comment.