Examples of Parameter Customisations

Table of Contents

1 Introduction

Introduction

At the end of this section, you should be able to:

Create Weave Edit Configurations with various parameter configurations.

We have seen how an edit configuration can be modified to restrict access to a single attribute (description) and only allow point geometry objects to be created for an entity e.g.,

<edit:config id="custom.edit">
    <entity>graffiti</entity>
    <label>Grafitti (custom)</label>
    <publish>true</publish>
    <description>Report graffiti for removal</description>
    <geometry>
      <point minimum="1" maximum="1"/>
    </geometry>
    <parameter id="description">
      <label>Description</label>
      <controlType>textarea</controlType>
      <column>description</column>
      <hidden>false</hidden> <!-- this is not needed but is included for completeness -->
    </parameter>
</edit:config>

Parameters can also be used to specify how attributes appear to the user e.g., a pulldown menu can be configured to restrict values for a particular attribute such as the Graffiti table’s status column.

When any parameters are specified, they will completely replace any parameters that may have been created by Weave.

Parameters are created by adding one or more parameter items to the edit configuration. Each parameter item specifies one input parameter. parameter XML items can have the following elements (see also the parameter description in the Configuration Reference’s Edit’s non-spatial Editor document).

Name	Type	Required	Default	Description

Name	Type	Required	Default	Description
id	string	yes		A unique identifier for the parameter
label	string	yes		The prompt text displayed when user input the parameter value
column	string	no		The name of the column within the table that this parameter references
helptext	string	no		Additional text to display for the parameter to explain how to use the parameter
hidden	boolean	no	false	Hides the parameter from the parameter UI
alignment	'left', 'center', 'right', 'auto'	no	'auto'	How the items should appear in the UI
controltype	'listbox', 'checkbox', 'radiobutton', 'textbox' or 'textarea'	no	'textbox'	The suggested type of UI control to use when displaying the parameter
datatype	'any', 'date', 'time', 'datetime', 'integer', 'string'	no	'string'	The data type for the parameter
allownull	boolean	no	false	Whether a null value is allowed for this parameter
allowblank	boolean	no	true	Give the user the choice of an empty value in the listbox (as opposed to a null value)
allownewvalues	boolean	no	false	Allow the user to enter values not in the listbox already
defaultvalue	any	no		The default value of the parameter
dataset	ref urn:com.cohga.server.data.database#1.0:datadefinition	no		Where to get the values for a listbox
labelcolumn	string	no		Column in the datadefinition that supplies the label of the value to show the user
valuecolumn	string	no		Column in the datadefinition that supplies the value of the value to use in the SQL
uppercase	boolean	no	false	Should the value be converted to upper case in the generated SQL
readonly	boolean	no	false	Can the user change the value
readonlyoninsert	boolean	no	false	Can the user change the value when a new entity is being created
readonlyonupdate	boolean	no	false	Can the user change the value when an entity is being edited
updatable	boolean	no	true	Can the underlying value ever be changed once set (implied readonlyonupdate if set to true)
value	any	formula or any		A value to insert into the database, provides a means of creating values beyond what the user enters (implied readonly if set
persisted	boolean	no	false	Should the value the user chooses for the field become the default value for the field?
minvalue	any	no		The minimum value allowed for a field.
maxvalue	any	no		The maximum value allowed for a field.
minlength	integer	no		The minimum length allowed for a field.
maxlength	integer	no		The maximum length allowed for a field.
increment	integer	no		The increment to use for fields that support it, the units are dependant upon the field type. Available only for time fields.

A few things to note about the properties that can be applied to parameters:

column is optional, if not provided then the field will still appear, but an attempt to write the entered value into the underlying spatial table will not be made. The user entered value can still be used by other means that will be covered later.
The controltype supports 'textarea' which provides a multi-line text input field.
readonly, readonlyoninsert and readonlyonupdate are special markers that allow you to alter the ability of the user to change the value in a field. These are client-side flags, and if set alters the display of the field so that the user cannot change the value, the field is still displayed, just not editable.
updatable specifies that once a value is set it can't be changed, this is similar to readonlyonupdate, and in fact readonlyonupdate will be set to true if updatable is set to false, but it also provides additional checks on the server to ensure that the value is not updated.
value can be used to set a value explicitly by directly supplying the value, or there are a number of formulas that are available.
- entity() The name of the entity type being edited.
- userid() The current username.
- ip() The current users IP address.
- datetime() The current date/time.
- operation() The type of operation being performed will be one of the strings 'create', 'update' or 'delete'.
- nextval() The value used for the column will be the previous largest value from the column plus one, the underlying column must be numeric.
- geometry() A WKT (Well Known Text) representation of the geometry if available, otherwise null.
- id() The value for the key field for the spatial table will be used if available, otherwise null.
- auto() The value for the field is auto-generated by the database.
- count() The number of geometry objects.
- area() The area of the geometry.
- length() The length of the geometry.
- guid() Generate a new globally unique id.

When a geometry is being written to multiple spatial tables the count(), area() and length() value functions will behave differently when used in an edit config item versus an edit audit item.
The value will only contain the count, area and length for the geometries that match the table that the geometry is being written to, not the total, when used in an edit config item. But, when used in audit config item then count, area and length will be the total of all the geometries (if there are more than one).

Example: Monitoring Who Makes Modifications

Hidden parameters with functions to set values can be used to create “in place” auditing of who makes changes, and when, for an entity. “In place” auditing means that the audit information is stored in the spatial table itself. The graffiti entity’s associated public.graffiti table contains four columns: createdby, createdon, modifiedbyand modifiedon which can be used to implement auditing. (The createdby and modifiedby columns need to be character fields, and the createdon and modifiedon need to be timestamps.)

The following edit configuration allows the recording of who created and modified the graffitientity:

<edit:config id="audit.edit">
    <entity>graffiti</entity>
    <label>Grafitti (Audit)</label>
    <description>Report graffiti for removal</description>
    <geometry>
      <point minimum="1" maximum="1"/>
    </geometry>
    <parameter id="description">
      <label>Description</label>
      <controlType>textarea</controlType>
      <column>description</column>
    </parameter>
    <!-- Hidden parameters to record audit information -->
    <parameter id="createdby">
      <hidden>true</hidden>
      <column>createdby</column>
      <value>userid()</value>
      <updatable>false</updatable>
    </parameter>
    <parameter id="createdon">
      <hidden>true</hidden>
      <column>createdon</column>
      <value>datetime()</value>
      <updatable>false</updatable>
    </parameter>
    <parameter id="modifiedby">
      <hidden>true</hidden>
      <column>modifiedby</column>
      <value>userid()</value>
    </parameter>
    <parameter id="modifiedon">
      <hidden>true</hidden>
      <column>modifiedon</column>
      <value>datetime()</value>
    </parameter>
</edit:config>

Saving the audit.edit configuration, refreshing the client, and selecting the Graffiti (Audit) configuration from the Edit tab’s pulldown will display the following. Note that the audit columns are not displayed.

Edit Panel showing Graffiti (Audit) Edit Configuration.

By not creating a parameter for the idcolumn that's used to identify the records, the column is hidden. However, its column value is auto generated (serial) by the database and is not user editable (hence can be hidden).

Creating a graffiti point is done as follows:

Graffiti Point Creation with in-line Auditing

Checking the database reveals that the id, createdby, createdon, modifiedbyand modifiedoncolumns are populated:

Example: Setting an id Field Value

Where the underlying table’s primary key column is not a serial (PostgreSQL) or identity (SQL Server) column, Weave can specify a field as an id field whose values are created by using the maximum value in the column (using the nextval() function).

  <edit:config id="id.edit">
    <entity>graffiti</entity>
    <label>Grafitti (id)</label>
	<description>Create ID from table values</description>
    <geometry>
      <point minimum="1" maximum="1"/>
    </geometry>
    <parameter id="id">
      <hidden>true</hidden>
      <column>id</column>
      <value>nextval()</value>
    </parameter>
    <parameter id="description">
      <label>Description</label>
      <controlType>textarea</controlType>
      <column>description</column>
    </parameter>
  </edit:config>

This example sets an id field that's hidden from the user, and it's created from the existing values in the table.

This is not an optimal solution to generating new key values. It is recommended that the functionality (sequences, serial, auto-generate, identity, etc) provided by the underlying database be used to generate id values.

Example: Drop Down List

To show how dropdown lists can be created using parameters we firstly define a parameter, status, in which its column values are defined by a static list of values.

Then we create a parameter, reporter, whose list-box values are defined as a dynamic list of staff names populated from a data definition called lu.staff which is defined against the public.stafftable.

The dropdown.edit is as shown below.

Saving the dropdown.edit edit configuration, refreshing the client, and selecting Graffiti (Drop Down) from the Edit tab’s pulldown list of edit configurations, looks like the following.

Example: Using Check Boxes and Radio Buttons

The status parameter above defines a pulldown list. Alternately we could define the parameter to present its options as a radio button.

Also, we can present a Yes/No parameter, fieldverified, for the fieldverified column via a checkbox.

Saving the final.edit edit configuration, refreshing the client, and selecting Graffiti (Final) from the Edit tab’s pulldown list of edit configurations, looks like the following.

<< Previous

Next >>