Custom wizards

From GTwM

Jump to: navigation, search

Contents

Wizards overview

To create a wizard

applications.vm

A file called applications.vm in the folder WEB-INF/templates/gui/customisations/{companyname} specifies any custom actions. {companyname} is a lower case version of the company name as shown in the portalBase window title, with all spaces and special characters removed.

A custom action has a link that appears in pane 1 of portalBase in a module. Custom action links appear under a module title, before the list of reports in that module. Typically, a custom action will display a modal wizard or popup which includes custom logic.

applications.vm will contains

The list of custom actions is specified by a line

$viewMethods.addModuleAction(moduleID, caption, tooltip, attributes, template, buttons, callback)

Parameters

An example module is 

$viewMethods.addModuleAction("a861d3dcdd146db70","add data","add a new organisation, site or  contact","width=800px;  height=600px","gui/customisations/gtwm/actions/add_address_data/start_address_adddata_wizard","ok cancel next  back","fAddOK")

Some example callbacks: 

function fAddOK(sResponseText,sResponseXML) {
   top.document.getElementById('oViewPane').contentWindow.pane_2.document.location='AppController.servlet?return=gui/reports_and_tables/report_data';
}
 
function fPrintInvoice(sResponseText,sResponseXML) {
   top.spawnWindow('AppController.servlet?return=gui/customisations/$companyName/actions/print_invoices/invoices_printout_wrapper','print_window','width=865px,toolbar=no,location=no,directories=no,status=no,copyhistory=no,menubar=no,resizable=yes,dialog=yes');
}

The callback function is run when the OK button is clicked and the server has sent a non-objectionable result (i.e. the wizardResult is 'ok')

XML File

Item Purpose Mandatory Syntax Acceptable Values Notes
Wizard Result Indicates whether the last wizard step was successful. yes <wizardResult>ok</wizardResult> ok {string}

<errorData>..</errorData> {xml}

The result is detected as an error if wizard result is present and result isn't 'ok'

If there's no wizardResult tag, success is assumed

Error Data Provide further information about an error no <errorData>[xml data]</errorData> One or more of:

<message>{string}</message> <internalFieldName>{string}</internalFieldName> <fieldName>{string}</fieldName>

if errorData isn't included, the default message 'an error has occurred but no information about it could be found\nPlease try again' is shown on error

if an internalFieldName is found, the wizard will attempt to detect a table row containing it and set its id as 'errorRow' which will highlight it.

Next Template location of the template for the next step of the wizard to be shown if the result is detected as successful no <nextTemplate>[location]</nextTemplate> [location] {string}

<validations>..</validations> {xml}

.vm is NOT needed at the end of location

try and use $company_name in the string location to aid portability

'next' button is activated if <nextTemplate> is detected and disabled if its not

Validations validations to be carried out before the wizard will allow a move to the next step no <validations>[validations]</validations> [validations]{semicolon separated list}

e.g. [fieldname]!=

Each validation is a line of Javascript

If a validation fails, i.e is interpreted as false, the wizard will stop.

A message "can't move on" will be alerted.

If the element causing the error has an expando property "validationMessage" this will be appended to the error alert

Back Template location of the template for a back step of the wizard no <backTemplate>[location]</backTemplate> [location]{string} .vm is NOT needed at the end of location

try and use $company_name in the string location to aid portability

'back' button is activated if <backTemplate> is detected and disabled if its not

OK Template location of the template for the last wizard step no <okTemplate>[location]</okTemplate> [location]{string} This template should just return an XML Wizard Result (see above), as the dialog will close on success, no other content should be returned.

.vm is NOT needed at the end of location

try and use $company_name in the string location to aid portability

'ok' button is activated if <okTemplate> is detected and disabled if its not

Caption A caption to appear in the titlebar of the wizard no <caption>[caption]</caption> [caption] {string}
HTML Content The HTML content of the dialog yes <htmlContent><![CDATA[ [content] ]]></htmlContent> [content]{html} an error is assumed if no HTML content section is defined - in which case the whole XML file is alerted as plain text

N.B. use of CDATA tags

Any form fields in the HTML will be sent to the server when Next or OK is pressed. The field names and values are submitted as part of the AJAX request that happens, not as a separate POST.

onload property allows script to be run when the content is shown no <htmlContent onload="[script]">...</htmlContent> [script]{javascript snippet} script will silently fail if there's an error.

For example, if the screen contains agileBase combo components, you can use onload="fComboComponents();"

Creating a picker

The wizard is able to display a picker which will set the value of a (hidden) field 'preset_row_id' to the value of the row_id property for the row clicked. Further the row will be highlighted.

This is implemented by adding an fPicker() event to the onload instruction of HTML Content i.e. <htmlContent onload="fPicker()">... This will load the default report for the session table or the table passed as a parameter in fPicker by internal id.

To start with a particular report, in the module action setup in applications.vm, add 

&set_custom_report=true&reportkey=picker_report&custominternalreportname=[internalreportname]

after the template path

Customisations

Including a file 'modal_framework_customisations.js' within the 'customisations/[company_name]/' folder allows a suite of custom javascript functions to be made available to a wizard on a per-company basis (N.B. that all the functions for all the wizards for that company must be included).

This is a useful feature because the modal customisations also have DOM access to oDialog and therefore all the objects within the popup.

The file must wrap everything inside a function: function _md_fCustomisations(oDialog) { }. Functions can then be called which use this e.g. 

function fClearCompanySelector() {
   var oHiddenField=oDialog.content.picker.rowid_store;
   oHiddenField.value=;
 }

which then have to be made public: 

this.fClearCompanySelector=fClearCompanySelector;

It can be quite useful to make the dialog a global variable so that customisations are easily called by page elements. 

 function fMakeDialogGlobal() {
   // make the customisations global so that functions can be called by HTML elements in the page
   gDialog=oDialog;
 }
 
 this.fMakeDialogGlobal=fMakeDialogGlobal;

and calling the function onload in HTML Content:

<htmlContent onload="oCustomisations.fMakeDialogGlobal()"> ... </htmlContent>

A custom function can then be called as e.g. 

gDialog.customisations.fMakeDialogGlobal();

Exposed objects and functions

Name Type Purpose
oDialog.setCaption({string}) function Sets the caption of the dialog
oDialog.content DOM object The DIV containing the HTML content of the wizard
oDialog.customisations Collection The functions defined by _md_fCustomisations()
Retrieved from "http://gtwebmarque.com/wikis/gtwm/index.php/Custom_wizards"
Personal tools
Namespaces
Variants
Actions
Navigation
Toolbox