smd_admin_themes

Install, manage, edit and switch admin-side themes then share them with the community.

Features

• Create and Edit admin-side themes
• Employ images, CSS, JS, HTML/PHP (for changing masthead, header & footer) in your theme
• Use constants in your CSS files
• Base your theme on an existing theme to tweak it to your taste
• Export a theme package for distribution to the community in either .tar, .tgz, .bz2 or .zip format (requires smd_crunchers plugin)
• Import / install other themes from the community repository
• Administrator can set a default theme for all users, or enable per-user / per-role themes

Installation / Uninstallation

Requires Textpattern 4.6.0+ and smd_crunchers plugin for import/export

Download the plugin from either GitHub, or the software page, paste the code into the Textpattern Admin->Plugins pane, install and enable the plugin. A new tab labelled Extensions->Admin themes is created. Only publishers will see this tab.

The plugin should automatically install the preferences for you. Click ‘Preferences’ from the Extensions->Admin themes tab or Options from the Admin->Plugins tab to alter, delete or reinstall them.

Visit the forum thread for more info or to report on the success or otherwise of the plugin.

To uninstall, simply delete the plugin from the Admin->Plugins page. The preferences will automatically be removed. Please be aware that removing the plugin does not remove any themes you have installed, nor does it remove per-user theme preferences. Per-user prefs will simply be ignored when the plugin is deleted.

Usage

On the Extensions->Admin themes tab is a list or grid containing installed themes. Out of the box, there will be two available: hive and hiveneutral. It’s advisable not to change these themes so you can always go back to them if everything goes sideways. Plus it’s a very useful starting point from which to base a new theme.

In the list layout, the columns are:

Theme

The name of the theme and (optional) thumbnail assigned to it. Click to activate the theme.

If the theme is based on another user’s theme, this dependency will be shown in parentheses after the theme name.

Author

You! Linked to your web site if you supply it in your Manifest.

Version

Theme version number in major.minor.subrev notation. If a newer version of a theme is available from Textgarden, the version number will be hyperlinked to the theme on Textgarden so you may download/install it.

The versions are checked, at most, once every 24 hours to avoid hammering the server.

Description

Brief one- or two-liner explaining your theme. If you have offered a help URL in your manifest, it will be linked here as well.

Actions

Actions to perform on each theme:

[New theme]

Create a new blank, empty folder ready for your theme. No spaces / odd characters are allowed in the name and it must not start with a number.

[Edit]

Edit the various details, files and content within the theme.

[Base]

Extend one of the existing themes to make your own changes under a new name.

[Export]

Save the theme package to your hard drive for distribution/backup in your chosen compression format.

[Delete]

Completely remove the theme. Not available to the core themes, for obvious reasons! Also not available if a theme has been used as a basis for another theme in the current site.

The currently selected theme is shaded and the current default theme that is in effect is highlighted. The grid view has parts of the above information, laid out slightly differently.

Switching themes

As the administrator, you can play God over everyone else’s themes. You are free to install as many as you wish and switch between them without affecting any other logins. Nobody else will even know you have installed the plugin.

If, however, you visit the Preferences page you can configure the themes that others use. There are three mechanisms to choose from:

• Force one theme for all users (except yourself)
• Force one theme for each user privilege level (except yourself)
• Allow all users (except yourself) to pick their favourite theme from a shortlist you define

At all times, you can choose any theme you please for your own use. This allows trialling, tweaking and testing of themes before unleashing them on your user base.

Theme preferences

• Case-sensitive theme list : When set to Yes, upper-case theme names take precedence over lower case theme names and will be listed first. For example, 3 theme called ‘Angelic’, ‘barbaric’ and ‘Cohesive’ will be ordered: Angelic, Cohesive, barbaric. Set to No to mix upper and lower-case themes together (order is then Angelic, barbaric, Cohesive ). The core themes are always listed first.
• Export compression type : Only if smd_crunchers is installed Depending on your version of PHP and which modules have been compiled into it, you will see a list of compression formats here. Choose one that suits you as the default in which to export your theme packages. You may choose from Tar, GZip (actually tar+gzip), Bzip2 (tar+bzip), or Zip (the default).
• Layout method : Choose from a List View (useful if you prefer to hide or use small thumbs) or a Grid View of installed themes. This setting applies to both admin and user theme selection tabs. Default: Grid View
• Thumb dimensions : Set the thumbnail dimensions in the theme list. Set either dimension to 0 to turn off thumbnail display. Default: 260 × 150px
• Filename format : Define the format of the exported theme. You can use {theme} and {version} replacement variables in this field. For example, {theme}_v{version}. Default: {theme}
• Max theme file size : Any (compressed) theme that exceeds this file size will not be imported. Default: 512000
• Default theme : Set the theme for all other users. If using ‘One theme for everyone’ the theme chosen here is forced upon all users. If using any of the other mechanisms, this theme is a fallback should something go pear-shaped.
• Theme system : As detailed in Switching themes, you may choose the way the Textpattern interface is presented to other users:
  • One theme for all : uses the Default theme for all users; they have no choice in the matter
  • One theme per privilege level : allows you to assign one or more privilege levels to a theme. Choose a theme from the left-hand list and then shift/ctrl-click the privilege levels to assign them. Flick between themes in the left column to see which ones are set for various user levels, or hover over a privilege level to see a tooltip. Only one level can be assigned to a theme so if you click a level that has already been assigned to another theme, it will be removed from its original assignment. Note you must Save the changes for them to take effect
  • One theme per user : define a shortlist from the available installed themes to offer to all users. A new panel will become available to other users under Admin that is essentially a cut-down version of the Admin themes tab. Users can switch between any one of the themes you have permitted.

Remember to click Save to apply the changes. Clicking any other panel will undo any modifications you may have made.

Browse themes

Click this button to be taken to the central admin theme repository where you may browse themes and download them ready for installation.

Install a theme

Only available if smd_crunchers is installed.

Locate a theme package on your hard drive or paste a URL to a package in the box at the top of the page. Hit Upload and it will be installed. If it already exists it will be overwritten. Note that you may receive a warning if the theme is packaged using a compression algorithm that is not built into your version of PHP. A list of supported compression types is given below the upload box.

Create a new (empty) theme

Click Create new theme and a box will slide down allowing you to give your theme a name.

No spaces or odd characters are permitted, because the name you enter is the name of the folder that will be created in the theme folder and the name of your theme’s class. If you do manage to use odd characters, the name will be “dumbed down” for you.

In order to avoid name clashes with other people’s themes, it is recommended that all themes you design begin with a unique 3-letter prefix of your own choosing, plus an underscore — exactly like plugins. Thus, smd_BlueMeanie might well be the name of a theme. When you have named your theme, click [Go] to create a folder in which it can reside.

Once the name is set, the only ways to rename it are to:

1. edit the theme’s main .php filename from the plugin’s interface. The folder will be automatically renamed to match.
2. manually rename the folder and .php filename.

In both cases, you must also alter the theme’s class name inside the .php file itself.

Extend an existing theme

Click [Base] to create a new theme based on another. A box will slide down so you may enter the name of your copy.

Observe the naming convention, then click [Go] to create the new theme.

Please remember, your theme will be dependent on the chosen theme and both must be present on a user’s system for the theme to work. It is worth ensuring that users of your theme are made aware of this dependency to avoid unnecessary frustration; perhaps add a link to the theme’s base, mention the dependency in the Help link and/or in the theme’s article on Textgarden. You will not be able to delete any theme from the list that has such a dependency, otherwise your admin side will stop working.

Export a theme

Only available if smd_crunchers is installed.

If you wish to back up a theme or share it with others, click [Export]. A box will slide down offering you a choice of compression formats; the default is the format you chose from the Preferences page.

When you have chosen the appropriate format, click [Go] to export the theme and save it to your computer. All related files in the theme will be packaged together into a single download file for convenience.

The filename is governed by the Filename format preference.

Delete a theme

Hit this (and confirm you are sure) to remove the entire theme folder and contents from the file system. This is not undoable, so be careful.

Edit a theme

A theme is a collection of files. The files all reside in their own self-contained folder under textpattern/theme. The name of the folder is the name of your theme, hence the reason it cannot contain any obscure characters that would be invalid in the filesystem or PHP variables.

When you click [Edit] you will be taken to a screen that allows you to make changes to the theme. The Edit screen is broken into two sub-panels, as follows:

Content

This is where you edit the contents of the files in your theme. The small edit box at the top is the filename and the large text area is its content. Click Save to commit changes. You may freely rename any file you are editing.

Important: if you select a file, edit it, rename it, and click Save you will overwrite whatever was in the previous file — even if you empty the contents of the textarea in an effort to make a “new” one. If you wish to create a new file, you must click the New file button to ensure you are not editing an existing file by mistake.

When creating a new file, another box will appear allowing you to specify the folder for the file. Although files can be renamed, folders cannot. Once a file is inside a folder it cannot be moved to a different folder from the user interface: you will have to use your FTP program to move files or rename folders.

It is also worth noting that file permissions vary from host to host. If you try and save a theme file and receive a yukky warning message about not being able to write the file, try increasing the permissions on the theme folder and all files beneath it.

The theme files are distributed in Textpattern with 644 permissions which should be fine for a standard host. Some shared hosting companies — and these are usually the ones that tell you to set your files and images folders to 777 in order to make them writable by Textpattern — run Apache/PHP in a different way which might require higher permissions in order to write to the theme folder. This is unfortunately outside the scope of the plugin so you will have to experiment if it causes you problems.

File handling

Alongside the editing area is where theme files are managed. Firstly is a select list of all installed themes; the current theme being edited is selected. Changing the theme here will immediately allow you to edit another theme. This is very useful if you are copying and pasting files from one theme to another and saves you having to go back to the theme list first.

Beneath that are two buttons:

• New file : Create a new, empty file in your theme folder. Nothing is actually created until you hit Save but using this button ensures you begin with a clean slate and don’t accidentally overwrite the previous file you were editing
• Theme list : A shortcut back to the main theme list (equivalent to clicking the Admin themes menu item)

Next is an upload area allowing you to upload new files and images to your theme. You can browse for as many files to upload as you wish — subject to the maximum file size restriction as set in your Advanced Preferences — and (optionally) store them in the nominated folder. These can be any of the supported file types, including images.

Below those buttons are a bunch of collapsible sections containing all the files that make up your theme. Click:

• a section heading to toggle the group of files visible/hidden
• a filename to load it into the text area for editing
• a regular (binary) image filename to preview it: svg files are previewed separately while editing them in the text area

Note that other binary files may not be edited and are prevented from being clicked.

You can use the checkboxes alongside each file to select files for deletion. Use the ‘With selected…’ box at the bottom of the list for this task. You may shift-click multiple files to select a range.

Images

Images must have a lower-case file extension or they will not show up in the list (although they will be uploaded). Supported extensions are .jpg, .jpeg, .gif, .png and .svg.

Upload any images that your theme uses. Note the best way to refer to image URLs in stylesheets is with a relative path:

.myStyle {
   background: url(my-image.png);
}

Each theme can also contain an optional thumbnail. This is an image of 260×150px in size, called screenshot.png (or .jpg, .gif, etc) in your root theme folder. Note it will be squashed / stretched to fit your thumbnail dimensions set in the plugin prefs.

If you select an SVG image it will be opened up in the editor just like a regular file. You may preview it by clicking the Preview link alongside the filename input box. All other image files are previewed by clicking their name in the file list.

Stylesheets

Files can be any valid filename but MUST end in .css or .scss (i.e. Sass files)

The meat and potatoes of your theme. Add as many sheets as you like and load them from your PHP file(s).

Styleplates

Files can be any valid filename but MUST end in .ssc

A special version of a stylesheet that allows you to define constants throughout your sheet. Write your stylesheet in exactly the same way as normal, but where you find yourself, for example, using the same color value repeatedly or the same rules block, you can save yourself typing by using constants:

@branding: #123456;
#header {
  color: @branding;
}
h2 {
  color: @branding;
}

You can also specify whole rule blocks like this (Note the colon after the block name) :

@my_block: {
  margin:0 20px;
  border:3px solid #999;
  font-size:120%;
}
#header {
  color: @branding;
  position:relative;
  @my_block;
}
h2 {
  @my_block;
}

If you put all your constants at the top of the .ssc file they will be removed from the generated css file.

When you save a .ssc file, a corresponding-named .css file will also be created. The two will be kept in sync as far as practicable (even if you rename the original file). When it comes to deletion though, they are treated separately. This allows you to either keep the .ssc file in the distribution archive or remove it prior to export.

Javascript

Files can be any valid filename but MUST end in .js

Any trickery you may wish to employ in your theme can be written in these files. Remember that jQuery is loaded by default on the admin side so you can play with that.

PHP

One file must be named exactly the same as your theme, i.e. smd_BlueMeanie.php. Any other files must end in .php

Consult the Admin Side theme guide on Textbook for the rules on making themes. Note that corrupt themes are detected to the best of the plugin’s ability and you may not export, base or switch to any theme that is broken.

If you rename the theme’s core PHP file (i.e. the one with the same name as the theme folder itself) the plugin will attempt to rename the folder as well; essentially renaming the theme. This should prevent a theme from becoming uneditable, but it is up to you to keep the class name in sync with the file name. If at any time you go back to the theme list/grid and find a theme exists but has no information associated with it, chances are it’s because the class name doesn’t match the theme’s folder name. Just hit [Edit] and alter the PHP file to bring everything back on track.

Text / Textile docs

Any files with a .txt or .textile extension are supported. Textile files can be previewed by clicking the Preview link alongside the filename input box. Note that when the main textarea is edited, the preview becomes unavailable because the file must be saved to update it first.

Others

Any files that are not of the above supported types appear here. If you do try to create a file that is not supported, a warning will be issued. You must hit Save again to confirm you really wish to create the file.

Folders

Any folders that your theme is using will be listed here. If you click the ‘x’ alongside any one, it and all its contents will be deleted. By contrast, if you delete all files from a folder using the regular ‘With selected’ mechanism, the folder itself will remain in the filesystem (although it won’t be shown) in this folder list.

Manifest

In your main PHP file is a function called manifest() which contains info about you and your theme. Edit the values here to stamp your mark on the theme. Note that if your description contains apostrophes they must be escaped by preceding them with a single backslash \. e.g.

'description' => 'Don\'t fear the reaper!',

Per-user theme selection

If an administrator chooses to allow per-user themes, a new panel appears under the Admin menu item of all users (except administrators). This simply displays all available themes — ones that the administrator has explicitly allowed.

Clicking a theme name or thumbnail will immediately switch to that theme until the user chooses another or the administrator changes theme system.

Author and credits

Stef Dawson.

This plugin would not have existed without the dedication, ideas and genius of Robert Wetzlmayr for the theme support. Plus of course the army of beta testers, ideas hamsters and tireless theme advocates, most notably Stuart Butcher, Dale Chapman, Dave DeSandro, Mike Dennis and Phil Wareham.

Kudos and thanks to you all.