GDS Report Guidelines

Goto: Documentation Home | Parameter Naming Convention | Symbol Replacements

While HTML reports are free to do whatever they wish, having a standard set of guidelines ensures a consistent user experience and also simplifies the automatic porting to alternative platforms.

Widget Report Guidelines

A Widget report is a small report designed to primarily show a small number of facts, rather than full blown interative reports.

Features:

A widget report is designed to be displayed in a 250px by 250px display. This should be the output size, but it may be slightly different on some devices. Having a standard size means that reports can be interchangably used in different places, much like clipart.
A widget report does NOT have outbound hyperlinks by default. A widget may however have an outbound link to a page that describes the widget report, such as documentation. The intent is that widgets can be safely used in places such as Intranet portal pages, where browsing away from the key fact is not desired. However, widgets that have explicitly been told to use hyperlinks may do so (see parameters below)

Standard Report Guidelines

A Standard report is a report that has full use of the browser window and will display large amounts of information.

Features:

Has full access to the browser window and should expect to use all available space.
Should hyperlink wherever possible and desired.
URLs should be relative wherever possible, not absolute. This ensures that test versions can co-exist with other versions of the same report
Should be based around a common base HTML source. This ensures that consistent appearance and headers can be easily applied.
Should use lib.js for common operations, such as formatting numbers for display. This ensures that user specific requirements can be implemented.
Do not try and overly influence the font, colors and other visual aspects - these should be controlled by the CSS.
Use the defined CSS tags to identify different components.
Use HTML correctly. For example <H1> should be used to identify the major heading, not as a shortcut to get larger text

Standard Report Base HTML

It is highly recommended that all standard reports include the following fixed base

<HTML>
<HEAD>
 <fieldpine:symbol name="default-theme">
 <fieldpine:variable name="report-name" value="Short Report Name" replace="0">
 <fieldpine:nlq Something>
 <script src="/report/pos/lib.js"></script>
</HEAD>
<BODY>
 <fieldpine:symbol name="context-header">
  ...  Your Report body goes here ...
 <fieldpine:symbol name="context-footer">
</BODY>
</HTML>

The <fieldpine:symbol name="default-theme"> causes the server to insert a reference to the current CSS style sheet in use for the user. This stylesheet may change under user control, and may also be different on different devices, scuh as a desktop browser vs a PDA.

Defining the variable "report-name" can be useful for header and footer files, as these may wish to display the report name and having it present in the variable means it does not need to be hardcoded.

The <fieldpine:symbol name="context-header"> causes the server to insert HTML to supply a standard header for the page and theme. This means you do not need to insert headers, or be concerned with different headers for different types of devices.

The <fieldpine:symbol name="context-footer"> causes the server to insert HTML to supply a standard footer for the page and theme.

The <fieldpine:nlq ... > provides a server side comment to assist NLQ. This allows a form of searching for reports, by allowing a report to describe what it is displaying. This does not form part of the report, but is used for locating and automatic calling of reports. (RLB@@: Need more here)

Standard Report CSS Classes

In order to allow a clean switching of themes, which define overall appearance, reports should use the CSS classes defined in the themes. This ensures that the HTML is rendered with the correct appearance.

(RLB: Table contains examples, these are yet to be defined ...)

HTML Element	Class	Description
p	m	Marks a main paragraph of text
*	eg	Describes a block as an example
*	total	Describes a field as a total, such as a grand total
	subtotal	Describes a field as a subtotal.

Report Parameter Naming Convention

A common standard for parameter naming is adopted. This ensures that report X and call report Y, without needing to be manually linked in all cases. If parameter names and purposes was not standardised, every link betwewn reports would need to be manually implemented.

Reports may receive parameters they do not require, these should simply be ignored, and passed along if possible on outbound links

Name Description

u* Reserved for customers to use as they wish.

sdt Start Date/Time.

edt End Date/Time

loc

link Provide hyperlinks. 0=no, 1=yes.

head Provides explicit control to include or disable theme headers. The default is to include theme headers, however in some circumstances, notably when a report is called inside a frame, headers are not desired.

theme Provides a theme name which overrides the default theme. The GDS server uses this parameter internally.

report-name Holds the name of the report, much like a title

Symbol Replacements

As each page is prepared for the client browser, a number of optional symbol replacements can occur. This allows page authors to create a generic report and the server will replace and insert certain values.

<fieldpine:symbol name="date" [mask="..."]>

<fieldpine:symbol name="time">

<fieldpine:symbol name="datetime">

<fieldpine:symbol name="sitelogo">

<fieldpine:symbol name="agent-base-stylesheet">

Causes the processor to insert a common base stylesheet for this device, such as Apple iPod/iPhone, Nintendo Wii Console, Nokia phones etc. This stylesheet contains device specific default rendering and preferences. This symbol will generate a <LINK .. type=stylesheet> value insertion and should placed in the HEAD section of the page. If no suitable stylesheet exists for the current device, nothing will be inserted.

<fieldpine:symbol name="default-theme">

Inserts the main theme (or appearance) CSS stylesheet(s). The theme is selected from the following

Is the parameter ?theme= present on the URL. If so, this theme is loaded and used for the request.
Has the folder specified a theme to use with an entry in the gds.txt file. This file provides a way a prefered theme can be applied for a single folder.

<fieldpine:symbol name="context-header"> and <fieldpine:symbol name="content-footer">

<fieldpine:symbol name="theme-header"> and <fieldpine:symbol name="theme-footer">

<fieldpine:symbol device="names" attributes="list" target="filename">

<fieldpine:auth ...>

<fieldpine:cif ...>

<fieldpine:variable ...>

<fieldpine:pinboard ...>

<fieldpine:bucket ...>

<fieldpine:html-select ...>

<fieldpine:chart ...>

<fieldpine:if ...>

<fieldpine:map ...>

<fieldpine:special ...>

<fieldpine:display-object ...>

<fieldpine:mergefile ...>

Lib.js utility routines

To ensure a uniform presentation, a javascript file exists to provide a number of routines to assist report writers. Writers are strongly encouraged to use this library. /report/pos/lib.js

Functions:

PosLib_NiceFormat(Number, Decimals)
Formats a number for user presentation, such as adding commas at thousand intervals. The decimals parameter is used to control how many decimal places are shown. This function does not assume anything about the number so does NOT apply dollar signs or any other adornments.
```
	var xyz = Number(12345.873495);
	document.getElementById("output").innerHTML = PosLib_NiceFormat(xyx,2);
	

	Resulting output:  12,345.87
	
```

Name	Description
u*	Reserved for customers to use as they wish.
sdt	Start Date/Time.
edt	End Date/Time
loc
link	Provide hyperlinks. 0=no, 1=yes.
head	Provides explicit control to include or disable theme headers. The default is to include theme headers, however in some circumstances, notably when a report is called inside a frame, headers are not desired.





theme	Provides a theme name which overrides the default theme. The GDS server uses this parameter internally.
report-name	Holds the name of the report, much like a title