PoNG Module: Form View

This PoNG module creates an input form with button(s) to post data to backend services.

Please have a look at the other standard modules coming with PoNG.

Usage in "structure"

Simply "type": "pong-form" to the rows or cols resource. Example structure file extract:

{
  "layout": {
     ...
     "rows": [
     {
       "rowId": "bla",
       "resourceURL": "customer",
       "type": "pong-form",
       ...
     },
     ...
   ],
   ...
}

Form Definition

The resource will load the form definition from the URL ../svc/<resourceUrl>/pong-form

Two column form layout

An easy one or two column layout (formFields2 is optional) is available. Example JSON definition from ../svc/customer/pong-form

{
   "label": "Customers",
   "description": "Create or edit a customer data record", 
   "id": "cloudFormId", 
   "formFields1": [ 
   	{ "id":"name", "label":"Name", "type":"text" }, 
   	{ "id":"email", "label":"E-Mail" }, 
   	{ "id":"phone", "label":"Phone" }
   ],
   "formFields2": [ 
   	{ "id":"company", "label":"Company" }, 
   	{ "id":"address", "label":"Address" }
   ],
   "actions" : [ 
   	{ "id":"CustomerLoad", "actionName": "Load Customer", "method":"GET" ,"actionURL": "svc/customer", "target": "customerActionOut" }, 
   	{ "id":"CustomerCreate", "actionName": "Create Customer", "method":"POST", "actionURL": "svc/customer", "update": [ { "resId":"customerTbl" } ] },
    	{ "id":"CustomerDelete", "actionName": "Delete Customer", "method":"DELETE", "actionURL": "svc/customer", "target": "customerActionOut" } 
   ]
}

Groups and columns form layout

You can do a more flexible form set up by arranging groups and columns, but you can't mix the 2-column and the flexible form layout:

{
   "label": "Customers",
   "description": "Create or edit a customer data record", 
   "id": "cloudFormId", 
   "fieldGroups":[
      {
        "fieldset":"name",
        "columns":[
           {
              "fieldset":"name",
              "formFields":[     
                 { ... field def ... }
                 { ... field def ... }
              ]
           }
        ] 
     }
   ],
   "actions" : [ 
       ...
   ]
}

The fieldset is optional and will render a fieldset (border) for this section and the name in the legend.

Field Types

The idea is to have a two column form.

For all fields "hidden":"true" is supported.

Text

"type:"text" (default)

defaultVal: property for presetting a value is supported.

If "rows":"number" property is set, then a textarea is rendered.

TODO PONG-72: readonly: true, false of checkbox field

Password

"type:"password"

Select

"type:"select"

Static options: options array, e.g. "options": [ { "option":"ABC" }, { "option":"XYZ" } ]

Dynamic options: optionsResource, e.g. "optionsResource": { "resourceURL":"myObjType", "optionField":"name", "optionValue":"id" }

Warning: The dynamic options will perform a blocking call. If there fails something, it will block the browser.

Checkbox

"type:"checkbox"

You should specify "name":"..." attribute, so the values can be collected for that name. If no name given, the id is a stand alone comitting field.

You're able to preselect a checkbox by defining "defaultVal":"true".

For checkboxes you can also set "readonly":"true".

Example

 "formFields":[     
    { "id":"c0", "type":"checkbox", "name":"extras", "value":"ac-adapter", "label":"include AC adapter" , defaultVal":"true" }, 
    { "id":"c1", "type":"checkbox", "name":"extras", "value":"colordisplay", "label":"with color display" }, 
    { "id":"c2", "type":"checkbox"  "name":"extras", "value":"double", "label":"double size" }
 ]

"type:"checkboxList"

You can load checkbox inputs from a resource per HTTP GET:

 "formFields":[     
    { "id":"c0", "type":"checkboxList", "name":"extras", "resourceURL":"myresource", "valueField":"id", "labelField":"name" , "defaultValField":"default" }
 ]

Separator

"type:"separator" adds a horizontal line instead of a field

Text in Form

• "type:"label" adds the text in label as a simple text w/o any form related things, good for hints or explanations
• descr field adds a tool tip to the field.

Form Actions

"action"-Array:

• Action method is optional, default is "method":"POST"
• Action target has three options:
  • give the resource id of the module, where the output has to go to
  • special value "modal", to display an alert box with the result
  • target is optional, you can also ignore the response.
• Action update is an (optional) array of resource (column/row) ids, where data updates should be triggered. Example: "update": [ { "resId":"xyz" } ] }

OnChange

A special action is the on-change-action "onChange":"*". The * means, it listen to changes on all fields. You may limit the event-action to dedicated field IDs (comma separated). Multiple action specification with different on-change definitions are allowed.

No button is generated, but a JS to handle changes in the form. The main use case is to ask a backend service e.g. for a price quote and update another resource to display the result.

Example

{
   "label": "Product Configuration",
   ...
   "actions" : [ 
      ...
      { "id":"OnChng", "onChange":"*", "actionURL":"svc/product/calcQuote/", "target":"quote" } 
   ]
}

Improvement TODO: Default delay is 1 sec to wait for an other change before calling the backend, but you can use "onChangeDelay":"3" to set it (to 3 sec in this example).

Simple example

This is the result of the 2-column layout definition above:

Fehler beim Erstellen des Vorschaubildes: Die Miniaturansicht konnte nicht am vorgesehenen Ort gespeichert werden

CSS

You can use the following CCS elements to modify thy styles:

• TODO