Documentation

Transform is a WordPress plugin that reads JSON or XML* feeds and transforms the feeds to HTML using display templates written in Dust (for JSON) or XSLT (for XML). Feeds and displays can be URLs to pages on the local or a remote web server, a path to a file on the site’s web server or static text in the WordPress database.

* Transforming XML feeds requires XSLT support in PHP (see http://php.net/manual/en/xsl.installation.php).

The unregistered version of the Transform plugin allows the creation of five Transform instances. To have more than five instances the Transform plugin needs to be registered. Thanks!

Installation

There are two different ways to download and install Transform. The first is to select the “Plugins” option in the site’s dashboard, click on the “Add New” button then search for “Transform”. Find the Transform plugin by Net Innovations LLC and click the “Install Now” button.

The second option is to download the zip archive of the plugin, extract the archive then upload the “transform” folder to your site’s wp-content/plugins folder.

Once installed, go to the site’s dashboard, open the Plugins option, find the Transform plugin and click “Activate” to enable the plugin.

Transform Configuration Overview

To understand how to configure Transform a basic understanding of how it works is important. The diagram below shows the composition of a Transform instance on a page.

A Transform instance is added to a WordPress page using a button on the editor to insert an instance previously defined in the WordPress dashboard. These predefined Transform instances are simply the selection of a data feed and a display template. When a request for a post/page with a Transform instance is received by WordPress it calls the Transform plugin (1), which gets the data feed and display template information for the requested instance (2).

Data feeds are a way for Transform to load JSON or XML data; the location for the data can be either a web URL or a file path on the local server. Either of these options can use variables in the location specified. For web URLs, additional HTTP protocol parameters can be sent with the request (eg POST variables). Transform requests the data feed and receives back either JSON or XML data.

Next, Transform requests the display template for this instance (4). Display templates are used to convert the data to HTML. For JSON data the display template is a Dust template while for XML data the template is written in XSL. Display templates can be read from a web URL, a local file on the server or as static text. Note, Dust templates are executed on the server rather than on the browser – to the browser the transformed data/template appears as HTML and no JavaScript libraries are necessary.

Once Transform has the data and template for the instance it performs a transform of these to create HTML markup (5). This HTML is then returned to WordPress which replaces the Transform shortcode for the instance with the HTML provided by Transform (6).

Data feeds and display templates are tied together through feed types. With feed types it is possible to define multiple display templates for a single data feed and multiple data feeds. For example, a hotel with multiple locations could define a feed type named “Local Weather” with one display template to present the weather forecast. The feed type would then have multiple data feeds, one for each hotel location. Creating instances of each data feed paired with the display template would show the weather at each hotel location.

Settings in Transform provide a way to conveniently defined text, dates or numeric values that can be used as parameters within feeds or displays. For example, a numeric setting could be defined named “items” with a value of 5 and then used that setting as the number of items to display for a feed of images. Later, if it is decided to only display three items the setting can changed, changing the value of “items” to 3 and all of the display templates would then show three images.

Specific details on how to do configure Transform are defined below.

Settings

Transform settings are used as parameters for feeds and displays. Although generally text, the values for these settings can be restricted to dates or numeric values. For example, a university might have settings for the current term (Fall or Spring) and year that are sent as parameters to a feed that would return XML for a student’s current schedule.

Settings consist of three components: a type (text, date or numeric), a name for referencing the setting and a value:

For examples of how to reference settings see the “Displays” and “Feeds” sections below.

Feed Types

Feed types are a way to group similar feeds and displays together (eg a single Flickr feed might have several displays, none of which are useful for a Twitter feed).

Feed types consist of a feed name and description as well as the MIME type for the data returned by feeds or transformed by displays. Available options for the MIME type are application/json for JSON data and text/xml for XML data. Note that the XML option may not be available if your server’s PHP installation does not support XSLT transformation: see the PHP XSLT documentation for more information.

Displays

Transform displays are used to transform the data return by a feed into HTML that is displayed in the web browser. Each display is composed of five required fields and any optional parameters:

Feed Type – this display will only be available for use with feeds that also are of this type
Display Name – a name for this display
Display Description – a description of the display
Display Type – where the data for the display can be found, either through a full path to a file on the local server, through a URL to a file or as text entered into the text box
File Location, URL or Text – depending on the Display Type selected, this value will be used as the location of the file on the server, a URL to a file or text.
Parameters (optional) – display parameters are made available to the transformation (see “Display Parameters” below)

Display Types

There are two different types of displays that are used by Transform depending on the “Feed Type MIME Type” for the feed of the display. Displays for “application/json” data use Dust as a templating system while “text/xml” data is displayed using XSLT. Both are simply text used to convert feed data into HTML; see the relevant sites for more information on how to write templates in these languages.

Displays can be read from a URL, a file on the local server or entered as text into the “New Feed Display” pop-up window.

File Location, URL or Text

Depending on the “Display Type” setting, you need to enter either a URL or file location for the display’s template or enter the display text directly into the pop-up window for “New Feed Display”.

Display Parameters

Transform can pass parameters to displays for use in rendering HTML. For example you might pass a parameter that is the number of records you want show in a feed of images.

To create a new parameter, click on the “Add New” button to the right of the Display Parameters text. This adds a new row of inputs to the pop-up window where you can define the following fields:

Type: the type of parameter being passed; either “Text” for static text, “Transform Setting” for a setting defined within Transform, “Form Field” for a POSTed form field, or “URL Parameter” for a parameter passed as part of the URL; note that Form Field and URL Parameter values are sanitized before being passed to the display
Name: the name to use to access the parameter within a display
Default Value: used for the value of the parameter if a value is not otherwise assigned for this parameter

These parameters are passed in different ways for Dust and XSLT displays. For Dust displays the JSON data returned by the feed has a “parameters” field prepended which is a JSON object containing the name/value pairs for parameter. For example, if the feed returns this JSON data:

{
 "employee":{ "name":"John", "age":30, "city":"New York" }
 }

and the display has a Text parameter with a name of “count” and a value of “5”, the JSON data would be modified to:

{
 "parameters":{ "count": "5" },
 "employee":{ "name":"John", "age":30, "city":"New York" }
 }

The Dust template for the display can then reference the “parameters” field of the JSON data.

For XSLT displays the parameters are appended after the first “xsl:template” tag in the display using “xsl:variable” tags, eg:

<xsl:variable name="count" select="5" />

Feeds

The “Feeds” section of Transform is where the locations for retrieving data for transformations are defined. The location can be either a URL or a file location on the site’s web server. Click on the “New Feed” button and a pop-up window with the New Feed form is displayed:

The “Feed Type” menu will link together feeds and displays so that only displays for a specific feed are displayed when creating a Transform instance (see Instances below).

“Feed Name” and “Feed Description” are used to identify the feed while the “Feed Source” menu allows for the specification of where the feed’s data will located. If File is selected for Feed Source then the only option for in the remainder of the form is to enter the file name; if Web is selected for the Feed Source then Feed URI, method and additional parameters can be specified. For File and Feed URI the value entered is interpreted for variable substitution (see File and Feed URI Variable Substitution below).

The Feed Method input and Feed Parameters are Web-only options, the first being used to specify the request method for the web request while the second is an option to add any variables to the request. Clicking on the “Add Parameter” button adds a new parameter definition section to the form:

The “Name” and “Type” fields are the name of the parameter and it’s HTTP type that will be sent to the web server (eg, a GET parameter is appended to the Feed URI using the name specified). Variables can be sent as GET, POST, HTTP Header or Cookie values.

The “Value comes from” is used to specify where the value for this variable is determined, either a GET or POST variables, a HTTP Header, a Cookie value, a Transform setting (see Settings above), a WordPress User value (either the user’s login or ID) or Static Text. Clicking on the X in the upper right will remove a parameter.

Once the form has been filled out clicking on the Add New Feed will create the feed and allow it to be selected when creating a Transform instance.

File and Feed URI Variable Substitution

The file location or feed URI string can contain substrings that will be replaced by Transform before the feed data is loaded. All variables are of the form ${[AREA].[name]} with the following areas being recognized:

GET: variable is part of the request URL; in this case the “name” in the variable is the name of the GET parameter passed as part of the web request
POST: variable’s value is the value of the  named POSTed form input
COOKIE: variable’s value is taken from an HTTP cookie with the name specified in the variable definition
WP: variable’s value is taken from the currently logged in user viewing the transform instance; “name” is either “ID” for the WordPress ID or “login” for the WordPress login
SETTING: variable’s value is the value of the named setting (see Settings above)

Examples:

${GET.menu} would be substituted with the “menu” GET parameter in the requested URL
${WP.login} would be substituted with the login for the user viewing the transform instance

Instances

Once a display and feed of the same feed type are defined an instance can be created that can be added to a WordPress post or page. Clicking “Transform” in the dashboard navigation and then clicking the “Add New” button at the top of the page displays a form to add a new Transform instance:

The Instance Name input provides the name that will be selected when an instance is added to a page. Selecting a Feed from the menu populates the Display menu while selecting a Display shows any parameters that need to be specified for the selected display.

Once the form is filled out the “Add New Instance” button will create the instance, allowing it to be added to a WordPress page/post.

Adding an Instance to a Post/Page

The final step is to add the Transform instance to a post or page. Depending on the version of WordPress you are using, the editor may be the classic editor (WordPress before version 5.0) or the Gutenberg editor (WordPress version 5.0 and later).

Classic Editor

Editing the post, placing the editing cursor where the instance should appear and then clicking on the “Add a Transform” button will open the Transform instance selection window:

Selecting the instance that will appear on the post and clicking the “Insert” button will add the shortcode for the transform instance to the page. If the changes to the post are saved and the post is then viewed the transform instance’s output should appear on the web page.
Gutenberg Editor (available soon with Transform version 1.4)
When you edit a post, click on the plus button that will appear when you hover your mouse cursor just below the lower left corner of the bottom-most block. Expand the “Embeds” section and click on the “Transform Instance” option:
The editor will add a block with a menu to select an instance you’ve created. Select the instance then click the Save button. View the page and the output of the Transform instance will be displayed.