Dashboard > CMS Help and Advice > Plugins > 06. Plugin Developers Guide
06. Plugin Developers Guide Log In View a printable version of the current page.

Added by John Latham , last edited by John Latham on Sep 02, 2010  (view change)
Labels: 
(None)

Contents

Version history

Date Updated by Summary of changes
2009-09-24 John Latham Documented plugin parameters
2007-12-14 John Latham Documented "password" attribute of textField and numbersField
2007-12-07 John Latham Documented <cookie/> element and sk-viewset header
2007-10-30 John Latham Documented <textField/> "rows" attribute
2007-09-19 John Latham Converted to wiki page
Documented <image/> element and new vpad attribute of <static/>
2006-12-17 John Latham Corrections to multiSubmitField (element name and attributes)
2006-02-02 John Latham Updated plugin schema location.
Documented support for selectField.
Applied LookingLocal document style.
2004-10-07 John Latham Draft for review

Background

The Looking Local Starter Kit provides content and basic interactive elements: forms, questionnaires, and search facilities. These can be authored in any microsite defined in the Starter Kit content management system (CMS), and are then accessible via any of the DiTV platforms supported by the Starter Kit content delivery service (CDS).

Supported platforms as of September 2007 are:

Sky Active
Virgin (Liberate platform)
Mobile (WAP1 & WAP2)
Netgem

Questionnaires comprise a set of multiple-choice questions, and are suitable for polling and feedback. Submitted questionnaire data is stored in the CMS.

Forms combine static text elements and input fields (free-text or multi-choice). The CMS includes a form designer for use by content editors. Individual form submissions are stored in the CMS, and may also be sent to a local authority e-mail address.

Whilst forms and questionnaires provide a basic level of interactivity, they are not suitable for self-service applications which require immediate feedback based on data held outside the Starter Kit by local authorities. Furthermore, the use of SMTP to deliver Starter Kit form submissions to Local Authorities makes this basic capability inappropriate for applications where guaranteed secure delivery is required.

In principle, third parties can develop digital interactive TV (DITV) services separately from the Starter Kit; these can be integrated via external links from local authority microsites.

This approach presents a number of challenges, such as maintaining a consistent user experience and "brand", considerable development and testing effort, time to market etc, and is impractical for small services.

Introduction

Local authorities are investing in development of self-service applications accessible to the public through web browsers.

In many cases, the core elements of the user interface (text prompts, input fields, option lists) are simple enough to be presented through DITV.

The plugin solution allows a web application to be presented on DITV with the "look and feel" of a Starter Kit microsite, with the same colours, fonts, and navigational elements as content authored in the CMS.

Once a web app has been registered as a plugin in the Starter Kit CMS, editors can create links to the plugin from any menu or content screen.

Connectivity model

When a DITV viewer selects a plugin link, an HTTP request is made from the Starter Kit to the web application. The application responds as it would to a web browser request, except that the response contains not HTML but XML representing the interactive and content elements in the central part of the screen. The Starter Kit adds navigational elements (breadcrumb trail, quicklinks, red button etc) and transforms the XML into markup required by whichever DITV platform the viewer is using (e.g. Sky, Virgin, Netgem).

When the DITV viewer makes an on-screen selection, the request is again "proxied" through the Starter Kit to the web application, which responds with XML for the next screen.

The HTTP request/response mechanism is the same as a normal web application serving HTML to a web browser, except that the response must contain XML conforming to the plugin XML schema. Server-side redirections are supported, allowing workflow to be developed exactly like a normal browser application.

Separation of concerns

This solution provides clear "separation of concerns" between the Starter Kit and the plugin web application:

Starter Kit Plugin
Platform-specific markup
Microsite "theme" (fonts, colours and images)
Peripheral navigation (breadcrumb trail, quicklinks, help, terms & conditions) 		Content and interactive elements
Workflow
Data retrieval
Transactions
"Chunking" - ensuring that the content and interactive elements fit in the space available in the central area of the screen without scrolling on any platform.

Protocols and ports

The Starter Kit supports HTTP and HTTPS connections to the remote plugin.

Whilst the Starter Kit supports connections on non-standard ports (i.e. other than port 80 for HTTP or port 443 for HTTPS), firewalls and proxies may cause problems. In this case, contact the Starter Kit administration team via normal points of contact.

Session support

The Starter Kit has the capability to maintain a session with the remote plugin.

Cookie-based sessions are implemented using the "compatibility specification" of the Commons HTTPClient (see http://jakarta.apache.org/commons/httpclient/cookies.html for more information). This ensures compatibility with the widest range of web servers.

Session management via URL re-writing is also supported.

HTTP request details

Header fields

Header field values should be handled in a case-insensitive fashion in plugin code.

Field name Meaning Values
sk-microsite Name (a.k.a "URL context") of the microsite through which the plugin is being accessed. Depends on microsite configuration in the Starter Kit CMS.
sk-viewset Name of the "view set" through which the plugin is being accessed. Liberate
Netgem
SkyActive
SkyNet
WAP1
WAP2
sk-channel Name of the "channel" through which the plugin is being accessed. 3
Mobile
Netgem
NTL
Sky
SkyNet
Telewest
Virgin
WAP1
WAP2
Mobile

The "sk-microsite" header may be used to provide microsite-specific behaviour, although since URL contexts may change over time, this feature should be used with extreme care, after discussion with the Starter Kit development team.

The "sk-viewset" header may be used to provide platform-specific behaviour, e.g. different field hint text to account for varying remote control button configurations on a particular TV platform.

The "sk-channel" header is similar to (and pre-dates) the "sk-viewset" header. It gives more fine-grained information about the platform, specifically the entry point used to access the service.

Relationship between sk-viewset and sk-channel

In the design of the Starter Kit, the "channel" reflects the entry point taken by the user, whereas the "view set" determines interface behaviour (markup, cookie handling etc).

Some channels map to a single viewset, others "auto-detect" the viewset using HTTP request headers.

The following table shows the relationships between viewsets and channels:

Value of sk-viewset Possible values of sk-channel
Liberate NTL
Telewest
Virgin
Netgem Netgem
SkyActive Sky
SkyNet SkyNet
WAP1 WAP1
Mobile
WAP2 WAP2
Mobile

As the table shows, the "Mobile" channel maps to both "WAP1" and "WAP2" viewsets - this channel auto-detects the viewset. Because the channel is determined by the entry point URL, "Mobile channel" URLs may be accessed by both WAP1 or WAP2 clients, and are used in links from third party sites.

At some future point the concept of "channels" may be eliminated from the design of the Starter Kit, and the viewset auto-detected for every platform.

Request parameters

The following request parameter names are used by the Starter Kit and should be avoided in form field names.

Field name Meaning Values
id ID of the plugin configuration record in the Starter Kit CMS. (various)
sequence Auto-generated sequence number used to detect backup. (various)
buttonPressed Logical name of the button pressed on previous plugin screen. left
right
go
formMethod Used to track the form method of the previous plugin screen. get
post
staging Identifies that the request is for staging content. N/A

Of these parameters, "buttonPressed" is the most useful, allowing a plugin to take different actions depending on which button was pressed by the user in the previous screen. Note that in contrast to HTML submit buttons, the label used on the button is irrelevant.

Character restrictions in field values

The Starter Kit generally provides good support for extended characters, both in text elements (page title, static fields, button labels etc) and field values, provided that these are properly encoded in the XML.

However, for fields which result in submitted data (textField, numbersField, selectField, multisubmitField) you should avoid values with leading or trailing spaces, as these have been found to be trimmed on form submission by certain platforms (Liberate/Virgin in particular).

Plugin parameters

There are some circumstances where you will want to launch a plugin in a number of different ways, from different entrypoints within the Starter Kit.

For instance, you might have a News section with a number of different article categories, and want to access each category from a different point within a Starter Kit microsite.

This can be achieved by having a number of distinct plugin entrypoint URLs registered, e.g.

Plugin name: Westhampton News - Business
Entry point: http://westhampton.gov.uk/plugins/news?category=business

Plugin name: Westhampton News - Entertainment
Entry point: http://westhampton.gov.uk/plugins/news?category=entertainment

Plugin name: Westhampton News - Sport
Entry point: http://westhampton.gov.uk/plugins/news?category=sport

This will work fine, but is somewhat cumbersome.

The same thing can be achieved with a single plugin using parameters.

Parameters are defined in your Plugin Configuration, which is set up by the Looking Local support team.

You can define a number of parameters for each plugin.

Each parameter has the following attributes:

Name - the querystring parameter name that will be passed in the entrypoint URL.
Label - the description of the parameter presented to the content editor who links to your plugin.
Mandatory - boolean. True if you want to force the content editor to enter a non-empty value.
Help text - further description presented to the content editor.

You can see the effect of these properties in the following screenshots from the Starter Kit content management system.

As described above, this feature is a content management convenience, and does not give you any more functionality than a collection of distinct plugins with variant entrypoint URLs.

You must support the content managers by agreeing working protocols for use of parameterised plugins - inappropriate use can lead to broken plugins!

Plugin XML Schema Guide

This section may be read alongside the plugin schema...

http://www.lookinglocal.gov.uk/schemas/plugin.xsd

...and the example application illustrated in later in this document.

High-level elements

screen

This is the main document element.

Attributes
none (other than schema and namespace declarations)

Child elements
<cookie> (zero or more elements)
<redirect> or <page>

redirect

The <redirect> element instructs the Starter Kit to present a screen in a Starter Kit microsite. The screen is identified by microsite name (referred to as "URL context" in the microsite configuration) and screen ID.

Since screen IDs are not stable (screens may be withdrawn and deleted by microsite editors) it is not recommended that this element be used except under special circumstances. The functionality was introduced for the Microsite Search plugin, which presents lists of microsite screens generated by directly searching the Starter Kit CMS database; in this context screen IDs are likely to remain valid for the short period the search results are shown.

Attributes

Attribute name Use Values
microsite required Name ("URL context" of the Starter Kit microsite
screen required ID of the screen

Child elements
None.

cookie

The <cookie> element instructs the Starter Kit to set a cookie with a value that will be passed back in subsequent plugin requests using an sk-cookie-... header.

A Starter Kit cookie is similar to a normal web cookie, in that the value is set in an HTTP response, and available in subsequent HTTP requests via a header.

Attributes

Attribute name Use Values
name required
scope required global
microsite
host
plugin
lifetime required session
persistent
value optional Anything but "deleted"

Child elements
None.

name

The cookie name determines the header name used to pass the cookie value back in subsequent requests.

The header naming convention is sk-cookie-<cookie name>

For instance, if your plugin sets a cookie using:

<cookie name="postcode" value="HD1 2NQ" scope="plugin" lifetime="session" />

your plugin will receive a header "sk-cookie-postcode" with value "HD1 2NQ" for the remainder of the session.

value

Omit this attribute to delete the cookie in the specified scope.

Do not use the cookie value "deleted", as this has special meaning on parts of the Sky platform.

lifetime

Lifetime determines how long the cookie lasts. Two values of "lifetime" are supported: session and persistent.

Session cookies last for the duration of the Starter Kit user session, which may be greater than the duration of the plugin session.

If it is likely that a user will re-enter your plugin in the same Starter Kit session, you may choose to "remember" data using an session cookie rather than (or in addition to) a session-scoped variable internal to your webapp.

Persistent cookies persist over multiple user sessions, for up to a year. The precise longevity of a cookie depends on the end user device and TV/mobile platform capabilities. Not all platforms support persistent cookies consistently, so do not assume cookie support is available.

scope

Scope determines which plugins (and through which microsites) the cookie will be available.

Cookie scopes have the following meaning:

Scope Meaning
plugin Only available to this plugin
host Available to all remote plugins sharing the same entry point hostname
microsite Available to all plugins in the current microsite
global Available to all plugins

There is potential for header namespace collisions between cookies in different scopes, since the scope does not affect the header name. To make this behaviour predictable, cookies are added to the plugin request in the following order:

global
microsite
host
plugin

For instance, if there exist two cookies named "postcode", one in global scope and one in plugin scope, the plugin will receive only the plugin-scoped cookie.

As a plugin developer, you have effective control over the plugin and host scopes, may be "on the receiving end" of cookies set by other plugins in microsite or global scope. These higher-level scopes are deliberately shared, in order that plugins can exchange common information.

For instance, both the Local Search plugin and Jobcentre Plus plugin use a "postcode" cookie, with persistent lifetime and global scope. Since end users may reach your plugin having previously gone through a postcode-based local search, you may find this cookie a useful default value for location-based services in your plugin. Since plugin scope takes precedence over global scope, you may also "ignore" this cookie and set your own at plugin scope, however if you clear your plugin-scoped cookie, you may then receive the global cookie in its place in subsequent requests.

If it is critical to the functioning of your plugin that you have uncontended control over a cookie, using a unique name (perhaps prefix your cookie name with your plugin domain name).

Cookie security

Do not store sensitive user information (credit card details, full address information etc) in cookies. If you think there is a good case for doing so, please contact the Looking Local team to discuss this further.

page

The <page> element represents the central portion of the screen.

Here is a simple extract from the intro screen of the GP booking plugin:

Screenshot XML

(click thumbnail to enlarge)

Attributes

Attribute name Use Values
transform required Name of a transform set defined in the plugin configuration within the Starter Kit. Should be "default" unless otherwise agreed.
title required Text to appear in the title bar.
backup deprecated This attribute formerly specified a plugin URL to which the user should be directed on use of the backup button. This backup detection functionality has now been withdrawn, and the attribute is now DEPRECATED. Plugin developers who wish to enforce certain backup-restricted workflows will need to implement the backup detection and redirection within their plugin.

Special attention to backup is required if the plugin implements transaction-oriented workflows. For instance, in a plugin with a workflow comprising a sequence of screens, after completion of the workflow the user may be prevented from re-entering the workflow by specifying a backup target on the screen displayed on completion of the workflow.

See Backup for more discussion of backup behaviour, and consult Example application for a real-world example.

Child elements
<searchField>, optional
<form>, technically optional but required for meaningful presentation behaviour.

searchField

<searchField> represents an input box displayed in the title bar.

Attributes

Attribute name Use Values
name required Field name (equivalent to name attribute on HTML form field)
value required Default value for the search field
size required Minimum display width, in characters. Since the field is presented using proportional width font, the field may accommodate additional characters.
hint optional The hint text to be displayed below the breadcrumb trail when focus is in the search field.

Note: regardless of which button is pressed (left, right, or go), the searchField value will be posted. The plugin should use the "buttonPressed" parameter to determine which button has been pressed.

Child elements
None.

The <searchField> element was developed for the Microsite Search plugin:
The screen XML for this page is:

Screenshot XML

(click thumbnail to enlarge)

form

Attributes

Attribute name Use Values
pagingText optional Text to appear in the area between the left and right buttons, e.g. "Page 1 of 3".
action optional The plugin URL to which the form will be posted. May be absolute or relative to the current URL. If not specified, the form is posted to the current URL.
method optional get
post
name optional As some development tools generate name attributes, the name attribute is tolerated but ignored by the Starter Kit

Child elements
Zero or more:
<static>
<image>
<hiddenField>
<textField>
<numbersField>
<selectField>
<multisubmitField>
<submit>

Form elements

static

Attributes

Similar to HTML <p/>

Attribute name Use Values
value required Static text.
vpad optional Vertical space (in pixels) above and below the text

The vpad attribute can be used to control the spacing between the static and adjacent fields, particularly other static text.

The default vpad ("2") gives the look of slightly seperated paragraphs. A value of "0" will give the same spacing a single wrapped static, making a series of adjacent statics appear like a single naturally wrapped paragraph.

Child elements
None.

image

Displays an image on devices which support it (currently all except WAP1).

Attribute name Use Values
src required URL of the image, absolute or relative to the current plugin URL
alt required Alternative text for devices which do not support images
align optional left
right

Child elements
None.

An <image/> element may occur once or not at all as a child of the form element. There are two required attributes, src and alt, which specify the same thing as their equivalents in the HTML <img/> tag.

The optional attribute "align" may be "left" or "right" - this is a hint which the Starter Kit may use on some platforms to position the image relative to other content. It is important to note that this is a HINT only, and we may decide on some platforms (e.g. mobile) to vary the position of the image as we see fit. Consequently, plugin developers should NOT make reference the the position in any accompanying text, e.g. "This house is beautifully presented (see picture on left)".

The <img/> element may be positioned anywhere amongst the other fields on the form. We may use this relative position to guide the layout on some platforms, or we may not. For example, if the image element is placed between two static text elements, on some platforms the image may appear between the two text blocks, and on others left, right, above or below.

For more information on using images, see Image Guidelines.

hiddenField

Similar to HTML <input type="hidden"/>.

Attributes

Attribute name Use Values
name required
value required Value to be passed back in form submission.

Child elements
None.

textField

Similar to HTML <input type="text"/>, except that the input box is presented to the right of a label.

Attributes

Attribute name Use Values
name required Parameter name in form post
value required Default value.
label required Label presented to the left of the input box.
hint optional The hint text to be displayed below the breadcrumb trail when focus is in the search field.
size optional Minimum width, in characters. This does not constrain the number of characters that can be input.
rows optional Number of rows in the input field (analagous to textarea "rows" attribute in HTML). Ignored on WAP1.
password optional If true, masks the input with asterisks (on supported platforms). Default is false.

Child elements
None.

The password attribute has an effect on Sky and WAP2 platforms, but is ignored on Liberate platforms and the Netgem preview.

numbersField

Same attributes and behaviour as <textField>, except that on Sky, single button presses on the remote produce numbers.

selectField

Similar to HTML <select>. The look and feel varies slightly between platforms.

Attributes

Attribute name Use Values
name required Parameter name in form post.
value required Default value.
label required Label presented to the left of the input box.
hint optional The hint text to be displayed below the breadcrumb trail when focus is in the search field.

Child elements
Sequence of <fieldOption>

multisubmitField

Presented as a table of options, where focus can be placed on one row at a time. Selection of an option causes the form to submit, so this is usually the only input field on a screen.

Attributes

Attribute name Use Values
name required Parameter name in form post.

Child elements
Sequence of <fieldOption>

fieldOption

Specifies one option in a <multisubmitField> or <selectField>.

Attributes

Attribute name Use Values
name required Option text
value required Value submitted in form post.

Child elements
None.

submit

Left and right buttons are specified using <submit> elements.

As described in section 4.2 - Request parameters, button presses result in an HTTP request containing the "buttonPressed" parameter, which may be used to direct workflow within the plugin web application.

Attributes

Attribute name Use Values
name required left
right
title required Button label

Child elements
None.

Image Guidelines

Image proxy and transcoding

The Starter Kit acts as a proxy for all images delivered to TV and mobile platforms. This is required since the platforms tend to operate as "walled gardens" and will not accept images from arbitrary internet URLs.

In addition to proxying the images through our servers, the Starter Kit applies platform- and theme-specific transformations to each image as it passes through, including:

  • Resizing to meet the platform-specific resolution requirements, to reflecting the differing screen space available for content on different platforms. For example on Virgin the screen space is reduced by the TV window/ad banner.
  • Adding theme-matched coloured borders to non-square images on TV (but not on mobile platforms).
  • Re-compressing using platform-specific quality parameters, to optimise file size for available client bandwidth.
  • Output using JPEG v1.01.

The output resolutions are currently:

  • Sky - 256x256 pixels
  • Virgin (Liberate) - 240x240 pixels
  • Mobile - 128x128 pixels
  • Wii - 280x280 pixels

Supported formats

Images referenced in plugin screens with the <image> tag are transcoded by the Starter Kit to meet platform-specific requirements for image size and binary format.

Currently, the Starter Kit image transcoder accepts images in the following formats:

Format Typical file extension
Graphics Interchange Format .gif
JPEG .jpg
Portable Network Graphics .png
Windows Bitmap .bmp

File size

Since all images must be downloaded to the Starter Kit server and transcoded before being relayed to the TV or mobile device, large images may slow down the user experience (and use excessive CPU usage on our servers). There is no need to use anything larger than 200kb. For performance reasons the final image used on TV will be limited to under 20kb, so uploading a larger image will not result in a better picture on TV.

Aspect ratio

The transcoder will add theme-matched coloured borders to non-square images on TV, however very non-square images (with a very wide border) tend not to look good.

Image quality considerations

Avoid:

  • Thin lines. These tend to cause interlace flicker and may not scale nicely
  • High levels of colour saturation. These cause chroma crawl.
  • Highly detailed images, such as maps. These may not be legible from typical TV viewing distance.
  • Images containing text. These may not scale well.

Error handling

If the image cannot be downloaded or transcoded for any reason (e.g. 404, unsupported format) the Starter Kit may display a placeholder image.

Caching

In an attempt to keep response time acceptable, the Starter Kit uses a two-stage cache to speed up image delivery.

The remote image cache stores retrieved images in their original format.
The image transcoding cache stores the transcoded images (resized, bordered, compressed), on a per-theme, per-platform basis.

Both caches are in-memory on our web servers, and have limited capacity (currently 300 in the remote image cache, 1000 in the transcoding cache).

The default cache expiry policy is currently that images will be expired from the cache 1 day after insertion into cache, or 1 hour after their last use, whichever is sooner. We may vary these parameters as we see fit.

Additionally, both caches should respect common cache headers sent by the remote server, according to the HTTP 1.1 specification (in theory, but this spec is little complex though so we may not be totally compliant). So, the remote server can specify (for instance) that the images should not be cached at all but retrieved on every request, although this would degrade the end user response time considerably.

Error Handling

It is vital that all HTTP requests to the plugin generate valid XML according to the plugin schema. This may take some effort to achieve, since most Web applications (servers, proxies etc) revert to HTML responses when exceptions occur.

In addition to runtime errors generated during processing within the plugin application, (database access errors, for instance), error screens may be presented by the underlying infrastructure. For instance, if the plugin is exposed to the Internet through an HTTP proxy which generates "network busy" errors when the connection is heavily contended, the error pages will almost certainly not conform to the plugin XML schema, resulting in a "Could not parse plugin" error presented to the end user.

With appropriate error handling, almost all exception conditions can be caught and errors presented in the context of a well-formed plugin screen.

Troubleshooting

Could not parse plugin xml.org.xml.sax.SAXException:

These errors are typically caused by the plugin returning malformed or invalid XML.

To determine what the plugin is actually returning, access the plugin through a web browser using the Netgem channel, and append the staging parameter. This will cause the Starter Kit to display the plugin response in an HTML textarea.

This approach is easiest if the screen in question is accessible via a "get" type HTTP request, as any required parameters from the preceding screen can be simulated using an appropriate querystring. For this reason, it is advisable to use "get" methods in all forms wherever possible.

If the plugin application supports logging of HTTP responses, these issues are easier to diagnose.

Registering a plugin in the Starter Kit

In order for a plugin to be used in a Starter Kit microsite, it must first be registered in the Starter Kit CMS by creating a Plugin definition. This can be done by any appropriately authorised user (with the Designer role).

The following information is required to create the Plugin definition:

Name. This is used within the CMS to refer to the plugin, for instance when creating a menu item or screen link. The name allows the plugin to be differentiated from others in the CMS. The name is not exposed to end users of the service (i.e. general public).

Breadcrumb title. This text was formerly used as the title for the "breadcrumb" navigational element presented to end users when using the plugin. This element is not currently used in any production TV or mobile interfaces.

Starting URL. This is used internally by the Starter Kit to make the initial connection to the remote plugin when a plugin link is followed by an end user. It must be fully qualified with protocol, hostname and path, and a port may optionally be specified.

Microsite scope. Plugins can be available to CMS content editors in all microsites, or selected microsites. Where a plugin provides services appropriate to a limited geographical area, or where a national service is being piloted locally, microsite scope should be restricted.

Plugin testing

Whilst each application has its own particular testing requirements, there are common issues across all Starter Kit plugins.

Scrolling/wrapping behaviour

The Starter Kit was designed to present a similar user interface on all platforms, so that a single set of content works on all. Whilst this has been achieved to a large degree, there are some differences in scrolling and wrapping behaviour between platforms. For instance, the number of characters which will display in the main content area (defined by the <form> element in plugin screen XML) varies between platforms.

On all platforms, scrolling of the main content area is discouraged. On some platforms (e.g. Virgin) any service which behaves in this way violates agreements in place with the platform providers.

Consequently, text should be appropriately cropped by the plugin to prevent scrolling. In dynamic data driven applications, it may be difficult to control the size of content at source (i.e. in the back-end data), so some post-processing may be required to truncate text in a controlled manner.

For instance, consider the presentation of paged search results containing some long items. Two approaches may work:

  1. Determine which items are likely to scroll, and on those pages present fewer items. This is a good user experience, as users will see long items in their entirety.
  2. Truncate long items, and distribute items evenly.

Both approaches need an algorithm for determining whether a given item is too long to fit on one line. Starter Kit developers have done some R&D work in Java using AWT font metrics, and whilst this gives better optimised results than a simple "WWWWW=worst case" approach, it doesn't give perfect results and some margin of error is still required.

Until further research is done, develop boundary-case tests based on analysis of back-end datasets and check on all supported platforms.

Error handling

If possible, both design and infrastructure defects should be simulated in a test environment to verify that the plugin returns well-formed and valid plugin screen XML in all cases.

For example:

  • Mis-configure database connections to simulate a database outage
  • Introduce arbitrary run-time logic problems (e.g. accessing array index out of bounds)
  • Specify an invalid form action URL to generate 404 not found errors

Backup

Some interactive TV platforms (e.g. Sky) have a backup button on the STB remote control. This imposes particular constraints on the behaviour of plugins.

Usability requirement

A usability requirement imposed by the Sky platform (and recommended for all TV services) is that a user must be able to gracefully exit a service using the backup button on the TV remote. The pages presented may not necessarily be those that the user has previously visited, although they must make sense in the overall navigational structure of the service.

Handling backup in workflow

Different interactive TV and mobile browser clients vary in their approach to browser history and backup.

The default behaviour of the Sky microbrowser is to re-issue the last HTTP request in its history stack.

On the Liberate (Virgin) service, page transitions within a Starter Kit plugin do not get added to the history stack. This means that on Virgin, the user will not be able to back up within a plugin, only to the last screen accessed before the plugin was entered, so effectively backup and the Menu button do the same thing.

On mobile devices the backup behaviour will depend on the behaviour and configuration of browser cache. Previous views may be retrieved from the cache, redisplayed and resubmitted when a left/right/go on-screen button is pressed, in which case it may appear to the plugin that a request is coming completely out of sequence.

As a consequence of these variances, plugin developers should code defensively and be prepared to redirect out-of-sequence requests to an appropriate "error screen" (which must also be valid Starter Kit plugin XML).

Backup detection in the Starter Kit

In previous versions of the Starter Kit the backup attribute of page could be specified in the plugin XML, and the Starter Kit redirected the user to this URL when an out-of-sequence request was received. This feature proved unreliable and is currently deprecated.

Examples

07. Example plugin walkthrough - GP appointment booking
Powered by Atlassian Confluence 2.7.3, the Enterprise Wiki. Bug/feature request - Atlassian news - Contact administrators