Creating an Admin Side Theme
From Textbook
Contents |
Admin side theme
Admin side themes were introduced to the trunk of Textpattern in r3149, and allows Textpattern users with the right privileges to apply a theme to the Textpattern admin environment.
Creating a basic theme
Naming Conventions
Theme names must be unique for a single Textpattern site. To avoid naming clashes, consult the list of Reserved Plugin Prefixes, choose a free three-letter prefix for your themes and register your prefix by adding it to the list. Theme names must follow PHP's naming restrictions:
A valid variable name starts with a letter or underscore, followed by any number of letters, numbers, or underscores. As a regular expression, it would be expressed thus: '[a-zA-Z_\x7f-\xff][a-zA-Z0-9_\x7f-\xff]*'
Directory Structure
Each single theme occupies a directory beneath ../textpattern/theme/ whose name equals the theme name. Thus, a theme named foo_theme will be stored in the ../textpattern/theme/foo_theme/ directory.
Theme Code
A theme constitutes at least one single PHP file whose name equals the theme name plus .php, e.g. ../textpattern/theme/foo_theme/foo_theme.php. Add additional subdirectories and support files like style sheets or library files ad lib.
A working theme implements methods which draw fractions of the admin-side user interface:
- Entries in the HTML
<head>element:html_head() - Navigation menu and other header markup
header() - Footer
footer()
messagepane from your custom header() function, you may render code that relies on the existence of such a DOM element inoperative. In this case, users of your theme would not see any of TXP's feedback messages. If you must rename elements as it is integral to your theme, consider leaving the existing items intact, adding your own and then setting the originals to display:none via CSSOptionally, a theme may contain administrative data in its manifest() method. Current items are:
- title
- a human-friendly name for your theme. Without this item, the theme name will be the same as the folder name
- author
- You :-)
- author_uri
- URL to your home page
- version
- Some version information that increments as the theme is revised. No versioning convention is enforced. Note that the built-in themes use a programmatic way of displaying the version based on the
$prefsarray. This keeps it in step with TXP but it is not recommended to do this for your own themes: you should use an actual numeric version number instead - description
- Brief reason why this theme exists, what it offers, or simply some marketing blurb about how great it is
- help
- A hyperlink to some documentation about the theme
Refer to ../textpattern/lib/txplib_theme.php and ../textpattern/theme/classic/classic.php for coding examples.
Theme CSS
Theme Javascript
Inheriting Themes
Any theme can inherit methods from existing themes and choose to override or extend only specific parts of the user interface while keeping others unmodified. The Remora theme makes use of this technique by inheriting from the Classic theme.
Inheritance is kicked off by including one line into the theme:
theme::based_on('classic');
Choosing Themes
To support visual theme selection methods, add a screenshot of your theme into the theme directory as either "screenshot.png", "screenshot.jpg", "screenshot.gif", etc. It should be a 260×150 pixels sized image.
You may also add a README file to your theme that could explain certain features of your theme or additional installation steps that may be required.
Admin side themes are hosted on Textgarden so please consider submitting your themes there when they have been perfected.
Themes may also be deployed easily on a per-user, per-privilege or global basis, edited, installed, and shared using the smd_admin_themes plugin.
