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
• Import / install other themes from the community repository
• Administrator can set a default theme for all users, or enable per-user / per-role themes

Author

Stef Dawson.

Installation / Uninstallation

Download the plugin from either textpattern.org, or the software page, paste the code into the TXP 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: classic and remora. 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 directory 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 row of 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 ‘classic’ theme is always listed first.
• Export compression type : 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 size : Set the thumbnail dimensions in the theme list. Set either dimension to 0 to turn off thumbnail display. Default: 260 × 150px
• 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 TXP interface is presented to other users:
  • One theme for everyone : 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 tab will appear 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 tab 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

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. Note that the edit box automatically takes focus, so you can type straight away.

No spaces or odd characters are permitted, because the name you enter is the name of the directory that will be created in the theme folder and them name of your theme’s class. If you do manage to use odd characters, the name will be “dumbed down” for you. Once the name is set, that is it; you cannot change it from within the interface. The only way to rename it is via your FTP client and in the PHP file if you know what you are doing.

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 directory in which it can reside.

Extend an existing theme

Click Base to create a new theme based on another. A box will slide down (the cursor focuses automatically in the box for you) 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

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. 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.

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 directory under textpattern/theme. The name of the directory 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 three vertical parts, as follows:

Image handling

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

Other images for use in CSS rules can also be added to a theme. Browse for an image and select it, then click Upload to add it to the theme. You can currently only upload one image at a time, though you can delete one or more at once by Shift/Ctrl clicking the ones you wish to remove and hitting the ‘x’ button. Warning: files will be deleted immediately, without confirmation.

The best way to refer to image URLs in stylesheets is with a relative path:

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

Content

The central pane 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, it is safer to click the New file button in the right hand column to ensure you are not editing an existing file by mistake.

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 directory and all files beneath it.

The theme files are distributed in TXP 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 directories to 777 in order to make them writable by TXP — run Apache/PHP in a different way which might require higher permissions in order to write to the theme directory. This is unfortunately outside the scope of the plugin so you will have to experiment if it causes you problems.

File handling

This column begins with a select list of all installed themes; the current theme selected. Changing the item 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 directory. 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 tab)

Below those buttons are up to four sections containing all the (non-image) files that make up your theme. Click a filename to load it into the central text area for editing.

Stylesheets

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

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 you would normally 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 directory 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 directory name. Just hit [Edit] and alter the PHP file to bring everything back on track.

Others

Any files that are not of the above three types (and are not images) appear here. You will probably never see this section. If you do try to create a file that is not of the above three types, a warning will be issued. You must hit Save again to confirm you really wish to create the file.

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 tab appears under the Admin tab 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.

Changelog

• 12 Jun 09 | 0.1 | Initial public beta
• 03 Sep 09 | 0.11 | Improved Textgarden theme feed and links ; improved file support (both thanks thebombsite) ; made global theme more obvious ; altered prefs tab a bit ; added .ssc support ; ignored .svn subdirs (all thanks pieman) ; improved warning messages ; misc fixes and housekeeping
• 02 Nov 09 | 0.12 | Reduced theme feed clutter in the prefs table
• 04 Nov 09 | 0.13 | Removed ereg_replace to conform with PHP5.3+ (thanks thebombsite) ; changed ‘global’ to ‘default’ ; fixed rogue untranslated string
• 09 Nov 09 | 0.14 | Moved URLs in line with Textgarden layout alterations (thanks for the headsup thebombsite) ; made feeds more robust in the event Textgarden is down / under maintenance (thanks mlarino)
• 09 Feb 10 | 0.2 | Native support for zip importing and exporting (almost) irrespective of your PHP environment ; zip is now the default system ; better notification of supported compression types and more robust rejection if something is missing
• 10 Feb 10 | 0.21 | Fixed bzip2 warning (thanks thebombsite) ; fixed recursive mkdir problem with bzip2 files (thanks PHP manual comments) ; fixed rogue temp file left behind with zip import
• 15 Feb 10 | 0.22 | When renaming the core theme PHP file, automatically rename directory too (thanks floodfish)
• 28 Feb 10 | 0.23 | Rudimentary validation of zip file contents (thanks Tuts_and_Tipps); fixed export notification

Credits

This plugin would not have existed without the dedication, ideas and genius of the Textpattern development team, especially 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, and Mike Dennis.

I am also indebted to the libraries hosted at PHP Classes that enabled native compression and decompression of various types. The hard work of Devin Doucette and Alexandre Tedeschi really added the icing on the cake for this plugin.

Kudos and thanks to you all.