Compiles Textpattern’s plugin installer packages from separate source files. Sports XML-formatted meta files, automatic textile detection and localization file joining.
At minimum rah_plugcompiler requires:
- PHP 5.2 or newer.
The repository contains three files that make the compiler:
- rah_plugcompile.php – is the actual compiler class.
- compile – command line wrapper for the class.
The implement directory hosts some (or just one) implementation examples.
The main difference compared to Textpattern’s official plugin template and compiler is how the plugins are constructed. Textpattern’s official template (by default) hosts everything in a single file. Rah_plugcompiler splits the sources to separate files: translations (i.e. textpacks), readme (i.e. help file), manifest (meta file) and the actual source code.
See abc_plugin repository for an example template. Cleverly named abc_plugin showcases all available features from textpacks to manifest’s options.
Textpacks, Textpattern’s plugin localization files, can be stored in a single file, or as separate files, each file storing a different language. Compiler searches textpacks from:
- Plugin template’s root directory with the name of
textpack(e.g.textpack.txt, only allows single file). - From a sub-directory named as
textpackswith the extension of.textpack
In multi-file format, where textpacks are stored in the textpacks directory, textpacks are recognized by the extension, .textpack. These textpack files follow Textpattern’s language file syntax.
Textpattern offers a way to set the default language which is used as the fallback when the plugin doesn’t come with user’s language. The default language is chosen based on #@language keyword, or lack of. Textpack files that do not define the language, are treated as the default language. Compare abc_plugin’s en-gb.texpack and fi-fi.textpack files. The en-gb doesn’t define the language code and is set as the default.
The language code (i.e. #@language line), as found in the fi-fi.textpack, is required in all but the default textpack file (that’s one file). If language code is included in all files, no default language is set, and user will see raw language strings if site’s language isn’t provided.
Refer to rpc.textpattern.com/lang/ for list of supported languages by Textpattern.
The manifest file, manifest.json, contains all plugin’s meta data. That’s the rest of the stuff a plugin is made of, including plugin’s version number, author, url, special flags, type, and recommended loading order. The manifest file can also be used to specify help file’s location. By default help file is expected to be named as help (with any extension), but different location/name can be chosen with a file option:
"help" : {"file" : "./path/to/help/file"}Textile markup can be used in the help file. If the help file’s filename ends with .textile extension, or the file contents start with h1. tag, the file is treated as it contained Textile markup.
Rah_plugcompiler is portable, and doesn’t need specific extra configuring or installation. The whole thing is just a class, with two example implementations. The compiler can also be run as Textpattern plugin by placing the compiler class (rah_plugcompile.php) to Textpattern’s plugin cache directory, where then other plugins could use the class as fits.
The compiler is a class, with couple implementation examples; CLI and recursive mass-compiler. The recursive.php showcases how the class can be used in it’s simplest form.
The compile file brings the compiler to command-line.
compile
compile /source/dir
compile /source/dir /output/dirThe command-line script compiles plugins and writes the installer packages to packages directory. The script takes zero, one or two arguments. If the script is executed with out arguments it waits for the user to input (type, drag, copy) in path to the plugin directory.
If no path is provided at all (script is executed and then Enter ⏎ is pressed), the compiler searches plugin files from the current directory the compile file is in. This means that the compiler can be dragged and dropped to plugin’s directory and simply executed, if include $rundir . '/rah_plugcompile.php'; line in compile file is changed to absolute path).
Note that in CLI all provided paths should be absolute (except standard output).
Specifying only plugin’s source directory (only one argument) will make the plugin to write the installer packages to the /packages directory (located in same directory as the compile file).
compile /absolute/path/to/abc_pluginOutput directory can be changed by specifying second argument. Path arguments should be absolute paths, point to a directory.
compile /absolute/path/to/templates/abc_plugin /absolute/path/to/packagesOn unix platforms (Linux, Mac OS) it’s also possible to simply execute the compile file (in file browser, e.g. Finder, double click the icon) and then drag and drop the plugin directories to the terminal window.