README

Rah_external_output is a Textpattern plugin that can be used create custom content-type snippets. These snippets can be requested with a publicly accessible URL, and used as pages or to provide site’s content over in form of JSON or XML to JavaScript or across domains.

While these snippets can act as pages, they are independent from Textpattern’s normal content model. Snippets won’t require or overpopulate page templates or sections.

This makes the plugin ideal for generating various publicly accessible snippets, including XML feeds or JavaScript Object Notations that can be then used to feed site’s content to JavaScript applications, build application layers or to transmit content across domains.

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.

Requirements

Rah_external_output’s minimum requirements:

Textpattern 4.4.1 or newer.
PHP 5.2.0 or newer.

Install

Using Composer:

$ composer require rah/rah_external_output:*

Or download a plugin package.

Basics

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:

http://example.com/?rah_external_output=FormNameWithoutPrefix

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

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

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:

http://example.com/?rah_external_output=hello_world

Where 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!

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

; Content-type: text/javascript
; Cache-Control: no-store, no-cache, must-revalidate, pre-check=0, post-check=0, max-age=0
; Expires: Sat, 24 Jul 2003 05:00:00 GMT
; Last-Modified: Wed, 1 Jan 2025 05:00:00 GMT
; Pragma: no-cache

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 .json, .js, .xml, .css, .txt and .html.

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.

Example snippets

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.

For developers

The plugin comes with few features targeted to developers.

Callback

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 register_callback() function.

register_callback(callback, 'rah_external_output.snippet_end');

Please see Plugin Basics for more information about plugin development and callbacks.

File extensions

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';

Changelog

Version 1.1.0 – 2014/03/18

Added: Clean URL support. Snippet can now be requested by its name, e.g. http://example.com/snippet.

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.
Removed: <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.
Added: rah_external_output.snippet_end callback 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 .html extension 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 parameter (&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 <txp:rah_external_output /> tag.
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.
Added: <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 <tbody> and <thead> tags to the tables.
Changed: Now uses new, improved multi-selection/edit feature, seen in other rah-plugins.
Changed: now uses textpattern callback 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).
Set $pretext indexes 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.

rah / rah_external_output

Maintainers

Details