Inspired plugin composer

This plugin creates a new page under the ‘Extensions’ tab where you can edit plugins that are already installed in Textpattern and register new plugins.

Features

• Create, edit or upload plugin code and documentation, then publish your wares in the standard TXP plugin format (see an example)
• Full support for the official zem_tpl.php plugin template. The modified version by net-carver also incorporates a ‘style’ section for easy styling of your help text. The Plugin Composer looks for CSS sections in the template and will use them accordingly. It will also read SVN $LastChangedRevision entries (thanks net-carver)
• Export plugins in a variety of formats, allowing you to switch between editing in the plugin composer or your favourite editing program, test the file in the plugin_cache_dir, then import it back into TXP with the help of the Composer and publish your plugin for everyone. Look at the bottom of the Plugin Composer’s Edit page for the options; just remember to save your changes before exporting or copying/pasting the code! You can export as:
  • a standard BASE64-encoded text file
  • a gzipped version (useful for large plugins)
  • a php file in the standard template format
• When exporting, files can be saved with either the code block first or the help block first, and you can change the output filename format to taste. Use the Setup button to configure
• Support for all plugin types:
  • Client + Admin
  • Client-side only
  • Admin-side only
  • Library plugins
• Support for specifying a recommended plugin load order if your plugin needs special powers. ‘5’ is the default. Note that if using the plugin cache directory this feature is only available if the $plugin['order'] string is in the template to begin with. So if your load order keeps returning to ‘5’, edit your template directly to add that string or paste your plugin into the relevant parts of the empty plugin template and upload it
• Help text can be written in Textile or (X)HTML. Styles can be added to the help section
• Take advantage of the TinyMCE WYSIWYG editor for the help section or Edit Area for code markup (thanks variaas). See the setup and notes sections for more on these editors
• Built-in Textile help viewer (thanks to net-carver’s Plugin Help Viewer) to allow you to preview your Help text during development (the two viewers will happily co-exist if you wish)
• Resizable textarea, plus character limit/counters so there’s less chance of you making the plugin or docs too big to fit in the database
• Support for setting a code “restore point” and rolling back to that point if things go sideways. Also useful for returning plugin source code to its as-installed state

Authors

Original plugin: Yura Linnyk
Modifications (v0.5+): Stef Dawson
A touch of class: Steve Dickinson
Plus help from a host of forum contributors too numerous to mention. You know who you are ;-)

Installation / Uninstallation

Requires TXP 4.2.0+

Download the plugin (v0.5 and above) from stefdawson.com (previous versions are still available on the Inspired homepage), paste the code into the TXP Admin -> Plugins page, install and enable the plugin.

The default preferences are automatically installed. Visit the Extensions -> Plugin Composer tab and click the Setup button in the top-right of the screen to reinstall, delete and save the plugin preferences. See the setup section for details.

To remove the Plugin Composer (noooo!) simply delete the plugin as normal from the Admin -> Plugins page. All the preferences will automatically be removed as well. NOTE: deleting the plugin from the plugin composer window itself will not delete the preferences.

Usage

List page

There is a setup button to allow you to configure various options in the Composer, the rest of the page lists all installed plugins. The columns are:

• Plugin : click the plugin name to edit it. If the plugin has preferences associated with it, you will also see an [Options] link
• Author : if available, click the author to go to their site
• Version (Modified) : shows the current version number and whether the plugin has been modified from when it was either created or installed. If it has, you can click the version number to restore the plugin code to its installed state or last restore point
• Description : briefly, what the plugin does
• Publish : three links
  • Publish : exports the plugin as a .txt file for distribution to other Textpattern users
  • Zip : exports the plugin as a compressed (gzipped) .txt file for distribution
  • Help : displays the (textile processed) plugin documentation, if there is any. Can also be viewed from the Edit page
• Order : the recommended plugin load order from 1 (loaded first) to 9 (loaded last). 5 is default
• Active : enable or disable a plugin by clicking entries in this column — this will not trigger any enabled/disabled notification event in your plugin. Use the Admin -> Plugins tab for testing this
• x : delete the plugin — this will not trigger the ‘deleted’ notification event. Use the Admin -> Plugins tab for testing this

If you are using the plugin_cache_dir (Admin -> Advanced Prefs), any plugins in the standard template format uploaded to this directory will be available immediately for editing and testing. You can edit and publish the plugins in the same manner as the regular, installed plugins above, with the following exceptions:

1. There is no concept of ‘modified’ or of restore points as the files always represent the most up-to-date version
2. Cached plugins are “always on” and do not need to be installed. To deactivate the plugin the file must be removed from the plugin cache directory
3. It follows that the ‘installed’ notification event is not triggered from plugins in the cache directory
4. The recommended load order cannot be changed from the list page; it can only be altered via the Edit page. The load order is only taken into account when the plugin is exported

Creating and naming plugins

There are two ways of creating plugins from the Plugin Composer list page. The first is to create a blank, empty plugin; use the text box at the top for this. Points to note:

• If you use a standard plugin name (e.g. abc_my_plugin) it will be created in the database
• If you add .php to the plugin name, it will be created in the plugin cache directory in a standard template format
• Avoid specifying the version of the plugin in the name — you should use the Rename file or Export options in the Edit page to alter the filename into your preferred filename format (see setup)

The second method of creating a plugin is to upload one using the Browse/upload box at the bottom of the list. Please note:

• You can upload code in either standard plugin template format (either code-first or help-first, complete with CSS areas) or simply upload a PHP file containing code only
• The plugin will always be installed in the database when using this method (upload the template manually via FTP or create a new one with a .php extension and paste the code into it if you want it in the plugin cache)
• If the plugin exists it will be updated with your new info
• This is the only place you can upload raw PHP with the <?php ?> markers. Everywhere else you should use a full template

Every plugin should be created with a three-letter prefix, an underscore, then the name of the plugin. You are free to choose your own three-letter prefix (usually your initials) subject to avoiding ones already taken by other plugin authors so people can get to know your work. Plus, it groups your plugins together in the plugin archive.

All functions, variables (including DOM nodes), CSS classes, and anything else you inject into the global scope should be prefixed by at least your three letter code; preferably the whole plugin name (or abridged version thereof) to avoid namespace clashes with your own and other plugins.

Edit page

The Edit page is where you craft your masterpiece. It is divided into various sections and boxes, as detailed here:

• Plugin : the name of your plugin, which you can change at any time. Note that if you are editing a file from the plugin cache directory and the $plugin['name'] row is commented out in the file, you will not be able to change the plugin name; it will always be the name of the file.
  To the right of this box will be one of two items:
  • Enable : if the plugin is a regular (installed) plugin, this checkbox allows you to switch the plugin on and off
  • (file name) : if you are editing a plugin in the cache directory, the current filename you are writing to will be displayed instead
• Source code : your plugin code goes here. The box is resizable by grabbing the --- + --- below the box and dragging. The box size will be remembered via a cookie for 30 days from your last adjustment.
  Plugins are limited to 16Mb of code so there is also a character countdown just below the edit box. If you start approaching the limit(!), it might be worth considering splitting your plugin into a few parts or working for Micro$oft, where code bloat is acceptable
  In Firefox and IE7+ you can use the Jump to line: textbox. Enter a line number and press Enter to jump to that line in the code. In other browsers, ymmv
• Plugin type : choose one of the types that best fits the intended use of your plugin. If you choose ‘Client’ and try to access the admin side in your code, a warning will be issued when the plugin is saved so you can choose a more appropriate type
• Flags : choose which plugin flags are to be associated with the plugin:
  • Has prefs : check this to indicate your plugin responds to the plugin_prefs.your_plugin_name event
  • event notify : check this to indicate your plugin responds to the plugin_lifecycle.your_plugin_name event/steps

Load order : choose the recommended order in which you think your plugin should be loaded by users. Most of the time, the default of ‘5’ is fine but for special cases where your plugin has to set up an environment or has to wait for other plugins to load first, you might require one of the numbers either side. Be aware that this is a recommendation and is overridable by the site admin. If the plugin is already deployed on a site, the load order already set will be used regardless of the setting of this value. Only new installations will be set to this value by default

• Version : the current version of your plugin. To the right of this box will be one of two items:
  • Restore point : selecting this checkbox will (upon save) store the current code as a baseline to which you may “roll back” to at a later date. See restore points for more
  • Rename file : by default, when you save a file that is being edited in the plugin cache directory, it is overwritten with your changes. Once a plugin is released you would normally download a copy via FTP from the plugin_cache_dir for safekeeping. If you then subsequently modify the plugin and increase the version number, you may wish to alter the filename as well. Checking this box will (upon save) rename the file in the plugin cache directory to reflect the current version number. See the setup page for details on customising the filename format
• Author : you!
• Website : your home page or plugin page. Will be hyperlinked to your Author name in the list page
• Description : very brief one-liner describing your plugin’s core function / reason for existence
• Plugin Help : documentation for detailing the plugin usage. Can (probably should!) be written using Textile. There were some loose documentation guidelines proposed that serve as a good starting point. Note that the character countdown here is only approximate because when your plugin is saved and the help is converted to HTML, it usually takes up more space than Textile; please check that your help file renders correctly when your plugin is exported
• Style : Any CSS style rules you wish to apply to your documentation to make it more pretty. It’s best to target your documentation specifically by surrounding the entire Plugin Help section with something like: <div id="abc_help">h1. Docs go here...</div>.
  Note that both the Plugin Help and Style are governed by a size limit. Since they are both stored in the same 64kB field, the size is shared between them. Styles are not passed through the Textile processor and you don’t need to add the <style> tags; the Composer will do that for you (but see Notes)
• Save : commits the changes
• [ View Help ] : shows the documentation as users will see it (i.e. Textile processed into HTML). Any help text over 64kB in length is truncated so you can verify that all your documentation fits

Once you have saved your plugin, there is a section right at the bottom that allows you to export your plugin in a variety of formats:

• Plugin code for distribution : is a direct copy ‘n’ paste area that contains your entire plugin + docs. You can take this entire area and paste it into the ‘Install plugin’ box on the Admin -> Plugins page
• Export as abc_myplugin.txt : converts the plugin help to HTML and saves the plugin to your computer as a redistributable text file for other Textpattern users to install
• Export as abc_myplugin.txt (compressed) : converts the plugin help to HTML and saves the plugin as a redistributable, gzipped text file for other Textpattern users to install. Useful for large plugins or to offer an alternative for people who have stringent size limits imposed by their host
• Export as abc_myplugin.php : saves the plugin in a Textpattern standard template format. Useful for keeping the plugin for yourself — complete with Textile markup — so it can be later edited and re-issued / updated or shared with other developers who have the Plugin Composer or zem_tpl.php compiler

Note that when exporting as a standard plugin, the Textile processor attempts to decide if you have used Textile or not; it simply looks for a textiled header (h1. through h6.). Running pure HTML through Textile may occasionally cause encoding issues depending on the original character set used so it is always best to try and stick to Textile as the documentation system.

Restore points

When a plugin is installed, a copy is kept in the database. If the plugin code (not help text) is subsequently edited, the plugin is considered “modified”; indicated in the Plugin Composer list page and Admin -> Plugins page. Sometimes you may wish to revert any changes back to the as-installed state and the Composer allows this.

Any time a plugin is marked as ‘modified’, the version number becomes clickable in the list page. Clicking it (and confirming you are sure) will wipe out any changes you made and return the plugin to its installed state.

During the editing process of your own plugins, it may be that at certain times you wish to put a stake in the ground and say “this is my current baseline that I might want to return to later”. Perhaps you are about to make some monster edits or try something experimental and want an easy fallback mechanism. That’s where the “Restore point” checkbox comes in.

By checking the box when you save your plugin, the current code will become your new rollback point and the plugin will no longer be marked “modified”. Any changes made beforehand will not be recoverable so you will have to rely on your own backups if you wish to go back further. Any edits you make after creating a restore point can be undone by visiting the list page and clicking the version number next to your plugin. Currently, only one rollback point can be stored in the database.

Setup page

Clicking Setup from the main list page allows access to the plugin preferences.

You can Install them — which retains any previous settings and adds new ones when updating the plugin — or Delete them. The plugin checks if all required preferences are available and offers you the choice of deleting/reinstalling in case the prefs become corrupted or need updating.

Once the prefs are installed you will see the available options:

• Plugin editor : you may choose to edit the code using a 3rd party syntax highlighter. Current support is for Edit Area and (sort of) CodePress (see the notes). Choose the system here, whereby the box beneath becomes available so you can specify the URL path of the EditArea installation on your server; this is normally everything up to and including /edit_area. No trailing slash is required
• Plugin editor width : the number of characters wide to make the boxes on the Edit page to suit your screen resolution
• Help editor : you may choose to edit the help manually via Textile or use TinyMCE for a more WYSIWYG experience. This is experimental and probably won’t work right now
• PHP export order : when saving your plugin in the standard template format, this governs whether you prefer the code block to be at the top of the file and the help block below, or vice versa

The next three textboxes are all very similar; they define the format of the filenames when you export plugins. The first is for when you export standard BASE-64 plugins; the second is for compressed plugins; the third is for exporting a standard PHP template.

Wherever you type {name}, the plugin name will appear. Similarly, {version} will be replaced with the current plugin version number. You can type anything you like in these boxes, but it’s more useful to include both of the replacement strings somewhere in each box so you don’t get name / version clashes.

For example, if you don’t like the fact that zipped plugins are exported as pfx_my_plugin_v0.1_zip.txt, you can change it. Perhaps you may prefer pfx_my_plugin-compressed-0.1.txt. In which case, set the 2nd box to {name}-compressed-{version}.txt.

The extension should usually be specified so your system/browser knows the file’s type when it is exported, but it’s not mandatory as the MIME type is given so (good) browsers should read that.

Finally, if you wish to take advantage of help cacheing, put the path to a temporary directory in the Cache dir box. Empty the box if you prefer saves and exports to be slower! Defaults to TXP’s temporary directory.

Notes / known issues

1. More editors can be integrated into the Composer fairly easily. If you find a good one, get in contact. Be warned that the editors do tend to slow the plugin down, especially as code size increases.
2. Tentative support for CodePress is available but it inexplicably blanks out the plugin code when saved, so support is disabled for now. If anyone can shed any light on why it does this, please speak up! Look in the ied_plugin_setup() function towards the bottom of the file, uncomment the commented out line and comment out the one beneath it to enable support, then visit the Setup page and select CodePress from the list. Don’t experiment with this setting on an important plugin :-)
3. When a plugin is saved to the plugin_cache_dir, if you have not put <style> markers in your CSS block they will be added for you in the text area but not saved in the actual template until you save it again (exporting as a PHP file is unaffected). So if you are in the habit of manually downloading the file from your FTP client immediately after a save, just save the plugin again to be sure

Changelog

• 25 Feb 06 | 0.1 | Initial release
• 25 Feb 06 | 0.2 | Added ‘save as’ option
• 17 Mar 06 | 0.3 | Added ‘save as php’
• 10 Apr 06 | 0.4 | Added support for plugin_cache_dir
• 04 Jan 08 | 0.5 | Full support for std template; compressed plugins; Library plugins; Textile help and styling; integration with net-carver’s Plugin Help Viewer
• 07 Jan 08 | 0.6 | Built-in help viewer (thanks net-carver); support for Edit Area & CodePress(ish) (thanks variaas); Help block/Code block position switchable on export; added Setup prefs page; line break/style bugfixes
• 08 Jan 08 | 0.7 | Re-importing plugins now retains style block; added ‘admin side plugin with client-side type’ warning; changed button styling and positions (all thanks net-carver); gTxt() pref labels and ‘intelligent’ prefs (go jQuery go!); cached plugins now also have direct export from Edit page; ‘don’t textile HTML’ check; minor bugfixes
• 09 Jan 08 | 0.71 | Textarea width can now be controlled from prefs, and height from a drag bar; default width increased to 110 chars; publish plugins from the list page; Install button removed when prefs all correctly installed (all thanks variaas / iblastoff)
• 10 Jan 08 | 0.72 | Fixed bug if plugin has no help; style section no longer stored/exported if it’s not in use (thanks the_ghost / iblastoff)
• 11 Jan 08 | 0.73 | Added support for reading an optional revision from the template parser and appending it to the version (thanks net-carver); more gTxt() strings converted
• 28 Mar 08 | 0.74 | Fixed empty plugin code if Style block left blank ; fixed strip/slash/encoding errors (thanks the_ghost/ruud) ; fixed crlf newlines in code block (thanks hakjoon/ruud)
• 28 May 08 | 0.75 | Added ‘modified’ to the Version column (thanks uli) ; added ability to rename files in the plugin cache dir when the version changes
• 03 Nov 08 | 0.8 | Added support for recommended plugin load order ; added Admin-only plugin type; added ability to override filename format on export ; added restore point/rollback (thanks maverick) ; added character count (thanks pepebe) ; rationalised the list and edit pages ; sped up export/save routines ; fixed a few corner case bugs (e.g. empty plugin name, missing quotes in template options)
• 03 Jan 09 | 0.81 | Added textile cacheing to improve performance with large help files ; profiled code and improved speed in various functions
• 23 Feb 09 | 0.82 | Can now create new template files on the fly (thanks azw) ; fixed Textile limit on large help files ; fixed database calls for MySQL strict mode (thanks Gocom / azw)
• 11 Apr 09 | 0.83 | Fixed help file CSS output so it validates ; use $prefs instead of $GLOBALS internally ; check if plugin_cache_dir exists before trying to use it on the list page
• 29 Aug 09 | 0.9 | Requires TXP 4.2.0+ ; added support for plugin prefs/lifecycle and larger plugin code ; fixed CSS delimiter for backwards compatibility ; new plugin template details used
• 11 Feb 10 | 0.91 | Added Jump To Line capability — in most browsers (thanks thebombsite)

Writing a plugin

You should be aware of the Plugin Author Resources topic on the Textpattern Support Forum, and you might also want to have a look at the TextPattern plugin cheat sheet and the tutorials and guides for Extending Textpattern on TextBook.

Happy plugin authoring :-)