Compiles multiple Textpattern plugins at once
Switch branches/tags
Nothing to show
Clone or download
Pull request Compare This branch is 7 commits ahead of gocom:master.
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Permalink
Failed to load latest commit information.
Netcarver/Textile
.gitignore
LICENSE
README.textile
compile
manifest.json
rah_plugcompile.php

README.textile

MassPlugCompiler/rah_plugcompiler

Compiles Textpattern’s plugin installer packages from separate source files. Sports XML-formatted meta files, automatic textile detection and localization file joining.

Requirements

At minimum rah_plugcompiler requires:

  • PHP 5.2 or newer.

Files explained

The repository contains three files that make the compiler:

The implement directory hosts some (or just one) implementation examples.

Plugin template

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

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 textpacks with the extension of .textpack

Default language and multi-file format

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.

Manifest and help file

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.

Installation

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.

Usage

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.

CLI — using command line

The compile file brings the compiler to command-line.

compile
compile /source/dir
compile /source/dir /output/dir

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

CLI examples

Single argument

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_plugin

Two arguments

Output 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/packages

Click and execute

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