Getting started writing Known themes
Themes allow you to easily extend, or provide alternatives to, Known's look and feel.
While plugins can also extend or replace Known's UI, in conjunction with extending or replacing its internal logic, themes are a lightweight alternative. Whereas multiple plugins can be installed, only one theme can be enabled at any one time.
Themes use standard Known templates. It's a good idea to be familiar with the core Known template concepts.
Themes are selected from the
Themes section of the administration panel.
The theme's folder must sit inside /Themes.
Each theme must have at least three things:
- theme.ini: a configuration file that provides information about the theme in the admin panel
- preview.png: a screenshot of the theme for use in the administration panel
- A set of templates under the theme's
Structure of theme.ini
The theme.ini file contains a number of text entries::
[Plugin description] name = "The name of the theme" version = "The theme's version number" author = "Author's name" author_email = "Author's email address" author_url = "http://authors-url/" description = "A short description that will be displayed in the administration panel"
More may be added over time. These entries are displayed in Known's administration panel but may also be displayed in a future plugin directory.
In addition, you can extend templates with entries in a special
[Extensions] section. For example::
[Extensions] "template/one" = "mytheme/template/one" "template/two" = "mytheme/template/two"
Here, any calls to
template/one will also call
mytheme/template/one with the same variables.
Let's say your theme is called PDX Carpet.
Your theme would live in the folder
/Themes/PDXCarpet/, and contain a
preview.png file as described
above, to help describe the theme in the administration panel.
You will also need a
You could overwrite the
shell/footer theme simply by adding a new file called
/Themes/PDXCarpet/templates/default/shell/footer.tpl.php. This could contain some simple text::
<p> This is a custom <a href="https://withknown.com">Known</a> theme! </p>
To add a custom, static CSS file, you might want to
shell/head theme to reference it. To do ths, you would add an extension to your
[Extensions] "shell/head" = "pdxcarpet/shell/head"
You would then create a new template file in
/Themes/PDXCarpet/templates/default/pdxcarpet/shell/head.tpl.php with some HTML to be injected into the page header::
<link href="<?= \Idno\Core\Idno::site()->config()->url ?>Themes/PDXCarpet/css/default.css" rel="stylesheet">
Finally, you'd create a normal static CSS file in
Known ships with several reference themes. We recommend you take a look at the
Solo theme to see how a simple alternative theme is put together.