Contents...

• Croquet England Directory Forms App
• Form Parameters
  • Instance
  • Form Configuration Parameters
  • Database Update From Forms - Fields Map
• Form Types
  • Form Type: 'Use Form Description' (Default)
  • Form Type: 'Web Page'
• Form Process
  • Form Process: 'None'
  • Form Process: 'Subscription'

Online Croquet England Directory Help.

The Directory's built-in forms app is not for the faint-hearted. To collect information from club members there are many highly effective free-to-use third-party apps including the following recommended ones:

• Google Forms allows a flexible form design to collect information into an online spreadsheet
  • Can be set up to force log in with a Gmail account and so control respondents
• Survey Monkey can give you a very comprehensive survey, though the free version can be difficult to deal with large amounts of response information - still worth investigating
• Doodle Poll - ideal for a simple option choice or scheduling a meeting

All result in a web link you can send to members, which is unlikely for anyone to guess but does not prevent multiple entries or outsiders responding.

Croquet England Directory Forms App

Forms allow organisation admins a flexible way to collect information from their members. They may be created and flexibly defined and then assigned to individuals or organisations.

Forms may be managed, filled and read by any club officer.

Assignment can be ad hoc by sending a URL (web page link) to an individual or club that includes their identity as the TargetID parameter. An instance of the form is created only when they have completed the requested information and saved it. The owner can complete a form on behalf of any target.

The URL for completing a form is

Where FID and TID are defined below; but you don't need to be concerned because there's an easy mechanism to assign the form to someone (described further below):

• FID: form ID number identifying the form type - find it in the form's configuration page.
• TID: Target ID - the database identifier of the target, or (for people) the literal string User.
  • To find someone's ID, look them up in the Directory and use the DbEntityID parameter from the URL. For example, when looking at Croquet England's details, the URL is croquet.org.uk/?p=members/directory&DbEntityID=1 and so you use the number 1 as the TID.
  • If TargetID is User then any logged-in person can use the URL and will submit their individual response to the form.
  • If TargetID is a number, only the referenced person (or an admin if an organisation) may access the form.

For example - a club admin could create a form (let's say it is form type number 37) and then email to all its members requesting them to fill in the form using:

croquet.org.uk/?p=members/directory&Action=Form&FormID=37&TargetID=UserId

Note that in combination with a workflow, an informative message for the target can automatically incorporate the TargetID as a parameter and the form's lifecycle (completion and processing the result) can be managed easily. The workflow can be permanently linked to a specific form type, which automates the availability of a link to the form from the workflow.

Forms can be revisited and amended by their target or owner until the owner-administrator locks it by clicking the Accept button, at which point the target can no longer modify their responses.

Saved instances of forms appear on the owner-organisation administrator's list in the Forms application.

Data submitted in a form is encrypted and saved for inspection by the owner (as a string of name=value pairs, separated with an ampersand (URL Encoded)), and presented in the owner's view of the completed forms. Clicking on the form icon presents the submitted data in the form, clicking on the target's name presents the instance of the form controller.

Three slightly different icons indicate the status of a form instance: initial, filled, or locked (no longer modifiable).

Form Parameters

Instance

The form definition includes an instance identifier so the same form definition can be used multiple times to gather the same information but held separately - most commonly it's needed for a fresh copy of the form to be submitted each year. To allow this without the owner needing to update the form configuration, special values for the form instance include:

• InsertYear which causes the current calendar year number to be used.
• AcademicYr which causes to be used the current calendar year number until September, when it is replaced with the subsequent year.

When looking at a form, if the instance matches that already saved the user sees the currently saved form data (and can save updates if not locked), otherwise (if it doesn't match saved data, or there is no saved data yet) creates a new instance (using the form's instance parameter).

Form Configuration Parameters

The form definition can include a parameter string, comprising name=value pairs separated by & (i.e. URL encoded) whose usage depends on the form type. For example:

ParamName=27&OtherParam=32

Database Update From Forms - Fields Map

Database administrators can set up a mapping of form fields to database fields. When set-up, a completed form viewed by its owner-administrator who presses the Accept button updates the database from the form data for the organisation or individual who completed the form.

This is a URL-encoded list form-field=database-field and is editable only by developer admins.

A special "form field" value Today inserts the date the Accept button is pushed.

Form Types

All form types use rich text content, which makes layout very flexible. The system supports templates, a mechanism allowing rich text content access to configuration parameters and form controls. Review the separate description of templates for details.

Through the template mechanism, the form's context adds its own parameters so that when the content is displayed as a targetted instance of the form the following templates are substituted:

• $#[FormTargetName] - the Display Name of the targetted person, organisation, or whatever.
• $#[FormTargetID] - the TargetID (see above).
• $#[FormTargetCode] - a four-letter reference code assigned by Croquet England to Affiliate Clubs, otherwise blank.
• $#[FormInstance] - the interpreted value of the form's configured Instance parameter, or its literal content if not a special value.

The string __TargetID__ is substituted for the TargetID (note that it has two underscore characters on each side). This substitution is useful in hyperlink definitions and is made before template processing.

In addition to the above, the form definition allows the administrator to define arbitrary parameters. Note that the name of each parameter defined in the form's parameter string is prepended with form before passing into the template expansion in order to distinguish it from those defined elsewhere. So a page must use $#[Param(FormTheName)] in order to pick up a parameter defined in the form definition's parameter field as TheName=<value>.

When an administrator is setting up a form, the related content appears in a special mode that displays the form controls and conditionals in a highlighted way - this is available from the form configuration screen. Hover the mouse over any of the highlighted controls to see information about it. For example, a 5-character text box appears as [         ].

Form Type: 'Use Form Description' (Default)

Like type Web Page (below), except the rich text content comes form the form's Description (which has no version control) and so this is for simple forms and for use by those without the capability to create and maintain website pages.

Form Type: 'Web Page'

These form types can only be created by those with the privilege to create website pages.

The form uses a (standard, versioned) web page, usually defined under hidden folder /admin/forms (adjacent to templates) as its template.

The form links to the web page by the page node defining a parameter FormName and the form a parameter PageFormName with matching string values.

Form Process

This defines how to process the data the user submits.

Form Process: 'None'

This option is the default and just securely saves the data.

Form Process: 'Subscription'

The form parameters and submitted user data are used to calculate the subscription amount from the defined subscription types for the organisation.

Subscription types include a setting for Calculation Type, which results in the following form parameters being available to the form (don't forget the prefixing of Form as they are made available to the page):

• No Fee: No parameters.
• Annual Fee:
  • Fee_<SubscriptionID> - the numeric value of the fee identified by the Subscription ID.
• Per Capita (CA): runs a (fairly complex) calculation as follows:
  • Using the following parameters returned by the form having been selected or entered by the user:
    • ClubType (usually selected by a radio button) returns a value of the form:
      • SubscriptionTypeID_<SubscriptionID> - example: SubscriptionTypeID_29
        • with an optional postfix of _Y2 or _Y3 that tweaks the algorithm as described below.
    • AdultMembers - a count of adult members (primary club)
    • JuniorMembers - a count of junior members (primary club)
  • The following parameters are then available if the above are submitted (note the template SkipIfBlank):
    • ToPay - calculated or looked-up amount.
  • ToPay is calculated by combining the configured form parameters with the form's submission as follows:
    • Fee_<SubscriptionID>_Adult - The per capita rate for an adult, multiplied by the form's returned parameter AdultMembers
    • Fee_<SubscriptionID>_Junior - The per capita rate for a junior (primary club), multiplied by the form's returned parameter JuniorMembers
    • Fee_<SubscriptionID>_Cap_Y2 - The cap on the total fee in year 2, applied to the total calculated if the ClubType parameter has a _Y2 suffix.
    • Fee_<SubscriptionID>_Cap_Y3 - The cap on the total fee in year 3, applied to the total calculated if the ClubType parameter has a _Y3 suffix.
    • Fee_<SubscriptionID>_Min - The minimum fee applied to all types.
  • If any of the user data is changed by the submission then the form is displayed again and again until the data submitted is not changed by the user (i.e. they have accepted the calculation and amount).

The above form parameters must be supplied in the form's Parameters configuration but will soon be moved to the subscription type definition.