gadGetStates()
This function returns the meta-information needed to validate the parameters to a gadget. Normally there is a catalog of all legal states, a description of the required parameter names, and possibly a title for the state.
The function returns a hash keyed by state. If the state does not appear in the hash, it is assumed not to exist (see Asterix exception to this rule). After that, another hash appears keyed by the following values:
| Value | Description | Format Description |
|---|---|---|
| public | describes if the state is a public state, an internal process state, or a private state. If the state is public, then it will not carry context information when it is entered. Most general-purpose pages on the website are public including all special format pages (with the exception of dialogue and HTML formats). Private states get context information and are expected to return to the host page immediately after being executed. These are typically one click operations (remove me from our group and return me back to the host page). Internal states are used to identify steps that are intermediate to a process. | true = public, 'c' = internal, false = private |
| process | List the states used in the process, excluding the current state. | array of state names or null for no process |
| params | A list of parameters that are required. The check of parameters currently just looks to see if the parameter exists. No parameter validation is currently done. No indication of whether or not the parameter comes from a POST, GET, or direct population is made either. In the future, this may be expanded to include those considerations. | array of parameter names that are required, if an array appears in the array and the members of the subarray are considered to be aliases of each other. For example, array('id',array('site','branch'), 'list') indicates that the ID parameter in a list parameter are required by name, and that either site OR branch must also be included. |
| title | the title of the state | string which indicates the title in English of the state |
| security | the name of the security provider for the state | security providers can be specified on a per state basis with a string specifying the name of security provider |
| securitydesc | specifies a description to provided the security UI to describe any special considerations that need to be made for the state | an English string describing any security information that should be taken into consideration |
| freeformat | specifies whether or not a strict check of parameters and states should be done. In some cases third-party software is dispatched to within the framework. Normally the third-party software is responsible for maintaining its own parameters. In that case the freeformat flag should be set ( usually in the Asterix state, see below ) | true or false |
| redirect | describes where to go in the case of security or parameter-format violation | this is an array specifying gadget name, state, and a map of parameters to translate into redirecting |
Special States
There are a couple special states which deserve mention. I state defined with an Asterix (*) applies the parameters defined in the state to all the states. If a security provider is defined in the Asterix state, then it applies to all states that don't define a security provider.
In some of the third-party integrated components, the freeformat state is set to true in order to skip parameter validation. Parameters are considered validated by the third-party software.
Example Implementation
This is taken from RiverGadget and shows all the parameters that are handled by the main gadget. Notice the call to the base static function which gathers all the states for the sub gadgets that are proxied to via the main river gadget ( like river detail and River books information ).
static public function gadGetStates()
{
return (array_merge(array (
// Manage Directories in general. No Parameters.
'drain-summary' => array (
'public' => true,
'params' => array (
'state'
)
),
'list' => array (
'public' => true,
'params' => array (
'list'
)
),
'state-summary' => array (
'public' => true,
'params' => array (
'state'
)
),
'view' => array (
'public' => true
),
'search' => array (
'public' => true,
),
'geo-summary' => array (
'public' => true,
'params' => array (
'geoN',
'geoS',
'geoE',
'geoW'
)
),
'list-personal'=>array(
'public'=>true
)
), CGadget :: subGetStates(self::$subgadgets,self::$subparams) ));
}
The following shows how processes defined from one of the gadgets in the stream maintence gadgets.
static public function gadGetStates()
{
return (array (
// Manage Directories in general. No Parameters.
'assign-sk-to-state' => array (
'public' => true,
'process'=>array('finalize-sk-to-state'),
'title' => 'Assign to State StreamTeam'
),
'finalize-sk-to-state' => array (
'public' => 'c'
)
));
}