Req:GUI

This document describes the technical requirements for a GridLAB-D Graphical User Interface.

All changes to this document shall be processed as follows:


 * 1) A request for change is opened as a new top-level section in the discussion page.
 * 2) An impact assessment of the change shall be presented by those having standing to do so.
 * 3) The pros and cons of the changes shall be discussed in a subsections so labeled.
 * 4) The disposition of the change request shall be documented in a subsection so labeled.

= Level 1 Requirements =

All Level 1 requirements require Project Manager approval to be adopted.

Platforms supported
The GUI shall be implemented as a platform independent extension to the core.

Presentment encoding
The GUI layout shall be encoded so that it is driven by the GLM file. Ancillary files may be referenced by the GLM file.

Input entities
All GUI input entities functionality shall be implemented by the core.

Output entities
All GUI output entities functionality shall be implemented using a third-party plotting package (e.g., gnuplot, jpgraph).

Client/server model
The GUI shall be implemented using a client/server model over a TCP port registered with IANA.

Communication protocol
The server shall support HTTP 1.1 traffic according to RFC2616. All major clients conforming to HTTP 1.1 shall be supported.

= Level 2 Requirements =

All Level 2 requirements require Technical Manager approval to be adopted.

Entities supported
All GridLAB-D property types shall be supported for both input and output.

Entities with limited supported
TIMESTAMP, loadshape, enduse, and schedules shall be supported only as strings.

Synchronous loading
The GUI shall permit multiple gui blocks to the identified in a single session, provided each block is given a wait condition that pauses the loading process, presents the current GUI, and waits for the specified action to be selected by the user. After the wait condition is satisfied by the user, the current GUI is destroyed, and the load proceeds.

Supported clients
Runtime checks of supported browsers shall be performed at GUI startup to ensure that the GUI supports the major browsers at the time of delivery, specifically IE8, Firefox3, Safari5, and Chrome2 and

= Level 3 Requirements =

All Level 3 requirements require Task Manager approval to be adopted.

GUI block
A GUI block shall be introduced by the term gui followed by a GLM block enclosed in {} braces.

Page entity
A page entity shall be introduced in a GUI block by the term page followed by a GLM block. Page entities shall instruct the server to copy the contents referred to by the source term. The source shall refer to the file containing the HTML code for the page, relative to the same path as the GLM file in which it is specified.

Wait entity
A wait entity shall be introduced in a GUI block by the term wait. Wait entities shall instruct the GUI loader to wait for the specified action button to be clicked before continuing the load process. The value of the wait entity shall determine what action button is required to continue the loading process.

Connection threading
The server shall use a single thread only when connected to a GUI client and shall not accept other incoming connections while a connection is active.

Connection shutdown
The server shall respond to queries on the first successful connection received and shutdown the simulation when that connection is closed.

Multiple connection
The server shall have an option to operate in multi-client mode, as specified by the server_quit_on_close global variable.

XML object property queries
XML queries for object properties shall be transmitted in the current form /name/property. The response shall be mime text/xml</tt> in the form

value

If the value is given in a known unit, the unit shall be appended to the value and separated by a space character.

XML global variable queries
XML queries for global variables shall be transmitted in the form /name</tt>. The response shall be mime text/xml</tt> in the form

value

If the value is given in a known unit, the unit shall be appended to the value and separated by a space character.

XML updates
All queries containing an = character followed by text shall be treated as a set operation and update the specified variable or property as requested. The previous value of the variable or property shall be returned. The set value shall be parsed in a manner identical to the loader, including unit handling and functionals, but excluding macros, equations, transforms, and expressions.

XML object property list queries
XML queries for a list of known object properties shall be transmitted in the form /properties?name</tt>. The response shall be mime text/xml</tt> in the form

name1 name2 ...  nameN

XML global variable list queries
XML queries for a list of global variables shall be transmitted in the form /globals?</tt>. The response shall be mime text/xml</tt> in the form

name1 name2 ...  nameN

XML object find queries
XML queries for a list of objects shall be transmitted in the form /objects?filter</tt> where filter conforms to the search filter syntax for FINDPGM *find_mkpgm(char *search)</tt> (see Search functions for details). The response shall be mime text/xml</tt> in the form

name1 name2 ...  nameN

where the objects listed are those returned by FINDLIST *find_runpgm(FINDPGM *pgm, FINDLIST *list)</tt> (see Search functions for details).

XML unit conversion queries
XML queries for unit conversion shall be transmitted in the form /convert/value%20fromunit?tounit</tt>. The response shall be mime text/xml</tt> in the form

value tounit

GUI entity requests
GUI page requests shall be transmitted in the form /gui/pagename</tt>. All GUI page responses shall be mime text/html</tt>.

Output entity requests
Output requests (e.g., csv data) shall be transmitted in the form /output/filename</tt>, where the file is the name given in the GLM tape object. All output responses shall be the appropriate mime type, e.g., png, text/csv.

Gnuplot entity requests
Any request in the form <tt>/gnuplot/file?mime</tt> shall run Gnuplot with the indicated file name as the script, which is assumed to generate an output file of the specified mime type. The response shall be the specified mime output from gnuplot.

Perl entity requests
Any request in the form <tt>/perl/file?mime</tt> shall run Perl with the indicated file name as the script, which is assumed to generate an output file of the specified mime type. The response shall be the specified mime output from Perl.

Java entity requests
Any request in the form <tt>/java/file?mime</tt> shall run Java with the indicated file name as the script, which is assumed to generate an output file of the specified mime type. The response shall be the specified mime output from Java.

Favicon requests
A request for <tt>/favicon.ico</tt> shall return the file stored in <tt>rt/favicon.ico</tt> if present.

Cache support
All responses shall request that the client not store data and disable caching.

= Level 4 Requirements =

All Level 4 requirements require Technical Contributor approval to be adopted.

Object property get function
The object property get function shall use the function prototype <tt>gldGetProperty(name,property)</tt> and shall return the value of the object's property.

Object property set function
The object property set function shall use the function prototype <tt>gldSetProperty(name,property,value)</tt> and shall return the previous value of the object's property.

Global variable get function
The global variable get function shall use the function prototype <tt>gldGetVariable(name)</tt> and shall return the value of the global variable.

Global variable set function
The global variable set function shall use the function prototype <tt>gldSetVariable(name,value) </tt> and shall return the previous value of the global variable.

Object properties get function
The object get function shall use the function prototype <tt>gldGetProperties(name)</tt> and shall return a list of the object's properties.

Globals get function
The global get function shall use the function prototype <tt>gldGetVariables</tt> and shall return a list of the defined global variables.

Object find function
The object find function shall use the function prototype <tt>gldFindObjects(filter)</tt> and shall return a list of the object names that match.

Unit conversion function
The unit conversion function shall use the function prototype <tt>gldConvertUnit(value,from,to)</tt> and shall return the converted value.