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.
Layout
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
templates
subfolder
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.
Extending themes
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.
Example
Let's say your theme is called PDX Carpet.
Your theme would live in the folder /Themes/PDXCarpet/
, and contain a plugin.ini
and preview.png
file as described
above, to help describe the theme in the administration panel.
You will also need a /Themes/PDXCarpet/templates/default/
folder.
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 extend
the shell/head
theme to reference it. To do ths, you would add an extension to your theme.ini
file::
[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()->getStaticURL() ?>Themes/PDXCarpet/css/default.css" rel="stylesheet">
Finally, you'd create a normal static CSS file in /Themes/PDXCarpet/css/default.css
.
Note
While it's not required, it is recommended to create a minified version of your CSS file and link to that, e.g. yui-compressor default.css > default.min.css
Reference themes
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.