Rah's External Output
A cup of coffee
Rah_external_output uses Textpattern’s form partials to power its snippets. A form partial that’s name is prefixed with a
rah_eo_ can be accessed directly with a URL, creating its own, independent, page. The term external directly refers to separateness and independency from sections and page templates while still serving client-side content.
List of features
- Form partials prefixed with a
rah_eo_can be requested, and their output accessed, directly using a public URL.
- In addition to normal form partials, these special forms, snippets, can contain HTTP header lines. Lines at the beginning of the form staring with a semicolon are treated as headers.
- Form partials can be served using different content-type by appending file extension to the name.
Rah_external_output’s minimum requirements:
- Textpattern 4.4.1 or newer.
- PHP 5.2 or newer.
The general behavior stands when it comes to installing rah_external_ouput. No extra steps or configuration that variates from normal is needed.
- Download plugin installation file and copy its contents to clipboard.
- Navigate to Plugins panel and paste the copied code into the Install plugin field, and click Upload.
- You will be shown a preview of the plugin and its documentation. Click Install at the bottom of the page.
- You will be returned to the plugin list when the plugin has been installed. Now activate the plugin by clicking its No link, which toggles the status to Yes and actives it.
- The plugin is now installed and activated. All done.
Rah_external_output treats any misc type form partial that name us prefixed with a
rah_eo_ prefix as a “external” content-type snippet. These special prefixed forms can be accessed using a public callback URL. This URL follows the pattern:
example.com is the site’s URL and
FormNameWithoutPrefix is the form’s name excluding the prefix. The above URL would output a misc form named as
Creating your first snippet
Creating a new rah_external_output’s custom form, a snippet, would follow the same steps as any other form. Go to Forms panel, located under Presentation, and click the Create new form button at the top of the column on the right. This will open a new empty editor.
As with any form partial, you can type in any Textpattern markup you wish to the large code field. This field contains what your snippet will output when accessed using its URL. For now, type in the field this:
; Content-type: text/plain <<txp:site_name /> says> Hello World!
You can then give the snippet a name by typing it in the Name field. This name will be also used for the snippet’s URL. To register a form partial as a rah_external_output’s snippet, the name should be prefixed with
rah_eo_. For now, give the form a name
Last but not least is a Type. The most appropriate type for a snippet is a misc, but it can be anything if you so wish. Form types are for the most part visual, used for organizing things on the admin-side, from the Write panel’s Override Form field to the Tag Builder.
When you have done with the code, giving it a name and selecting a type, hit the Save button. The snippet is now ready for being accessed. After you have saved the editor, you will notice that there is a View link next to the Name field. By clicking the link you will be taken to the snippet’s generated page.
That page is the snippets publicly accessible URL, which you can freely use as a page, to serve content to applications and use in client-side scripts. For the snippet
rah_eo_hello_world you just created, this URL would be:
example.com is your site’s URL and
hello_world the name of the snippet. When accessing the snippet, you should see the following output:
<MySiteName says> Hello World!
MySiteName is the name of the site. As you may notice, the page is served as a plain text opposed to HTML. This is due to a HTTP header line the snippet’s code included:
; Content-type: text/plain
All rah_external_output’s snippets support few unique features including custom HTTP header lines and file extensions.
Custom HTTP headers
In addition to a form partial’s normal features, rah_external_output’s special forms, snippets, support sending custom HTTP headers, including a content-type header.
All lines at the beginning of the form starting with a semicolon (
;) are sent as HTTP headers. These lines should be placed at the very beginning of a form, starting from the first line. HTTP header lines can not be preceded by any white-space or empty lines.
HTTP header lines follow the normal syntax you would expect from a HTTP header field definitions. A line consist of a header property, also commonly referred as a field, followed by a colon (
:) and a value.
; Property: Value
A form supports unlimited number of header lines. Each subsequent line starting with a semicolon is sent as a HTTP header.
Using these HTTP header lines visitor can be redirected, or document’s content-type, encoding, caching or timestamp attributes changed. A form that starts with the following header line would be sent as a plain-text:
; Content-type: text/plain
<txp:article_custom limit="15"> <txp:permlink><txp:title /></txp:permlink> </txp:article_custom>
Note that for security reasons HTTP header lines can not contain Textpattern tags. Headers are collected from the source code before any Textpattern tags are processed. This is to prevent any type of header injections that could occur otherwise.
Content-types and file extensions
In addition to custom HTTP headers, a snippet’s content-type can be set using a file extension, appended to the form’s name. Supported extensions are
If a form is named as a
rah_eo_jsontable.json, the snippet would be served as a JSON presentation when
http://example.com/?rah_external_output=jsontable.json is accessed.
Tag trace and debugging
As with Textpattern’s normal page templates, rah_external_output’s snippets support tag traces. In debugging mode, a tag trace is appended to the HTML output of each snippet that ends with a
.html extension. As a tag trace on a normal page, the trace tells you which Textpattern tags are being executed and their outcome.
As the plugin can be used to serve any type of snippet and content there is no to say what you should do with it or not. To give out a simple idea how you could benefit from the plugin, please see our examples directory on GitHub. The directory contains some basic, yet real-world proof examples. Examples include XML sitemap generation and some JSON serving.
The plugin comes with few features targeted to developers.
One of these developer features is a callback event which is fired when a snippet is viewed. The callback in question is named
rah_external_output.snippet_end and is executed at the very end of a snippet. This callback can be used like any other Textpattern’s callback event. Hooking to the event happens using
Please see Plugin Basics for more information about plugin development and callbacks.
Rah_external_output allows extending the recognized MIME types and extensions. This can be done by modifying a global variable. The variable is named
$rah_external_output_mime and it takes an array map of
extension => mime/type key-value pairs.
global $rah_external_output_mime; $rah_external_output_mime['png'] = 'image/png'; $rah_external_output_mime['svg'] = 'image/svg+xml';
Version 1.0.4 – 2013/05/07
- Changed: The installer doesn’t use embedded version numbers. The only purpose for the installer is to handle migrations anyway.
Version 1.0.3 – 2013/05/06
- Composer package now uses textpattern/lock and textpattern/installer. The package installs to Textpattern without any extra configuration.
Version 1.0.2 – 2013/04/23
- Fixed: PHP namespace compatibility.
- Changed: Under Textpattern 4.6.0-dev adds the ‘View’ link to the new action bar.
- Improved: Internal clean up.
- Improved: Use Textpattern’s assigned flags to ensure future compatibility.
- Improved: Creating preferences to the memory isn’t necessary.
Version 1.0.1 – 2012/08/31
- Changed: Now doesn’t uninstall
rah_eo_prefixed form partials with the plugin. These forms could be used for something else than just as the plugin’s snippets.
- Dropped: code path used as a plugin cache fallback. Now relays on existence of plugin-lifecycle callbacks.
- Dropped: migration cleaner deployed in v0.6. Is no longer relevant.
Version 1.0 – 2012/07/14
- Removed: Plugin’s own user interface. The plugin now uses
rah_eo_prefixed form partials and integrates with Forms panel.
<txp:rah_external_output />tag. As forms are used, normal and more flexible output_form tag can be used.
- Removed: Raw PHP support to comply with r3706.
- Added: Ability to set a snippet’s content-type using a file extension in the name.
- Added: Migration assistant script. The script is run automatically on install and migrates rah_external_output snippets from the old interface to Forms.
rah_external_output.snippet_endcallback event for developers.
- Changed: Returns a 404 page instead of the home page when requesting a nonexistent snippet.
- Changed: Tag trace can no longer be controlled using a URL parameter. A tag trace is added when the snippet name has a
.htmlextension and the site is in debugging mode.
- Now requires PHP5 or newer.
- Compatibility with Textpattern v4.5.0.
Version 0.9 – 2011/09/03
- Fixed: now handles raw PHP tags.
- Changed: now parses tag structure in same fashion as core. Do it twice. Provides identical results with core in every scenario.
- Added: ability to display tag trace, and error reporting, by adding
&rah_external_output_trace=1) to the snippet URL when site’s production status is set to debugging.
Version 0.8 – 2011/07/26
- Added: CSRF (session riding) protection using Textpattern’s core functions introduced in v4.4.1.
- Changed: Make sure the plugin interfaces is all in one language.
- Changed: Only try to drop old database tables when humanly possible that there is old leftovers. Don’t run queries when updating from clean to clean.
- Changed: set temporary version number when installing. Removes the possibility of running the installer twice for no reason.
- Now requires Textpattern version 4.4.1 or newer.
Version 0.7 – 2011/06/12
- Fixed: Error in
- Fixed: Closed open
<thead>tag in the main list view.
- Fixed: Now admin-side page title uses language strings.
Version 0.6 – 2011/04/15
- Fixed: Saving snippets while changing name.
- Fixed: Now keeps the sent data in the editor if error occurs during saving instead of fetching the old data from the database.
- Added: Translation support. Interface now uses language strings.
<txp:rah_external_output />tag now caches fetched results.
- Added: Now uses plugin_lifecycle callbacks, and includes uninstaller.
- Added: Adds an options link to the Plugins pane which directs to the plugin’s admin-interface.
- Removed: Mime-interface. Was confusing and not so many used it. Trying to simplify the user interface.
- Changed: The user-interface and markup. Removed heading, removed inline styles, added
<thead>tags to the tables.
- Changed: Now uses new, improved multi-selection/edit feature, seen in other rah-plugins.
- Changed: now uses
textpatterncallback instead of outputting the snippets right away when the plugin is loaded.
- Changed: Now checks if the saving/updating succeeds, instead of expecting.
- Now requires Textpattern 4.2.0 (or newer) for full feature compatibility.
Version 0.5 – 2010/04/11
- Added disable and activate actions to the multiedit feature.
Version 0.4 – 2009/06/08
- Fixed forgotten insert query escaping.
Version 0.3 – 2009/05/10
- Fixed error caused by non-set
$pretext(note: TXP load order).
$pretextindexes to empty: we are not on page template.
Version 0.2 – 2009/05/09
- Fixed forgotten parse call.
Version 0.1 – 2009/05/09
- Initial release.