PoNG Module: Form View

From EWIKI
Jump to navigation Jump to search

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": "name", 
   "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 is supported:

  • hide fields with hidden attribute
    • "hidden":"true"
    • "hidden":"false" (default)
  • put field int HTTP request header or only in the request params or both
    • "request":"header"
    • "request":"header+param"
    • "request":"param" (default)

or in combination.

Text

"type:"text" (default)

defaultVal: property for presetting a value is supported.

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

You can define read onyl input fields by "readonly":"true".

Optional attribute:

  • "basicAuth":"user" used to create a HTTP basic-auth header field, ref. also password field
  • "basicAuth":"user+field" used to create a HTTP basic-auth header field, and send it also as POST param, ref. also password field

EMail

"type:"email"

... same as "text" type

Password

"type:"password"


Optional attribute:

  • "basicAuth":"password" used to create a HTTP basic-auth header field, ref. also text field
  • "basicAuth":"password+field" used to create a HTTP basic-auth header field and send also as POST field, ref. also text field

Select

"type:"select"

Static options: options array, e.g.

  • "options": [ { "option":"ABC" }, { "option":"XYZ" } ]
  • "options": [ { "value":"1", "option":"ABC" }, { "value":"2", "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

Simple Action

To render a button and perform an AJAX request, simply define an action with a actionName

"action"-Array:

  • id must always be specified
  • Action method is optional, default is "method":"POST"

Example:

{
   ...
   "actions" : [ 
      { "id":"btn", "actionName":"Save Data" }  
   ]
}
  • Action dataEncoding is optional
    • default is "dataEncoding":"JSON"
    • also available is "dataEncoding":"GETstyle", so payload is e.g. a=b&c=d
  • Action target has three options:
    • give the resource id of the module, where the output has to go to
    • or "_parent", if the whole page should be replaced. The result should be an URL.
    • special value "modal", to display an alert box with the result
    • target is optional, you can also ignore the response.

Warning: If you set "method":"GET", you may get problems with the length of the URL.

You can add add further actions to you button:

  • update
  • setData

Update

Action update parameter in the action is an (optional) array of resource (column/row) ids, where data updates should be triggered. Example:

{
   ...
   "actions" : [ 
      { "id":"OnInit", ..., 
        "update": [ { "resId":"xyz" } ]  
      }
   ]
}

As GET call parameter the id is send to the service.

setData

Action setResponse parameter in the action is an (optional) array of resource (column/row) ids. The response of the actions will be handed over to the named resource to be processed and shown in the view. Example:

{
   ...
   "actions" : [ 
      { "id":"setData", ..., 
        "setData": [ { "resId":"xyz", "dataDocSubPath": "searchResult.dataTbl" } ] } 
      }
   ]
}

A typical use case is a search form and a table to display the response of the GET request.

Optional the dataDocSubPath can be set to point to the data inside the result.

Link

If you want to open a new window or tab in the browser you can add a simple link: Just specify link and linkUrl

Example:

{
   ...
   "actions" : [ 
      { "id":"lnkToEditor", "link":"Open Editor", "linkURL":"editor.php?mode=easy" }  
   ]
}

Action target is optional and has three values:

  • "_blank" (=default) opens a new tab or window.
  • "_parent"
  • "_self"

To pass parameters you can define a getParams array, example:

{
   ...
   "actions" : [ 
      { "id":"lnkToEditor", "link":"Open Editor", "linkURL":"editor.php?mode=easy", getParams: [ "name", "id" ] }  
   ]
}

OnInit

Value should be

  1. the call parameter to get initialization data. AJAX GET request to the backend is performed to load data for the form or
  2. "GET", to indicate, that GET partameters from the page are passed to the onInit backend request

Example

{
   "label": "Product Configuration",
   ...
   "actions" : [ 
      ...
      { "id":"OnInit", "onInit":{ "getInitValues":"defaultValues" }, "actionURL":"svc/product/calcQuote/", "target":"quote" } 
   ]
}

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":"doSomething", "onChange":"*", "actionURL":"svc/product/calcQuote/", "target":"quote" } 
   ]
}

It is also possible to do an upate after the backend call.

Another option is to sepcify an update only. Example:

{
   "label": "Product Configuration",
   ...
   "actions" : [ 
      ...
      { "id":"doSomething", "onChange":"*", "update":[ { "resId":"shipping" } ] } 
   ]
}


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).

AfterUpdate

To do cascading updated.

Example

{
   "label": "Product Configuration",
   ...
   "actions" : [ 
      ...
      { "id":"cascadeUpdate", "afterUpdate":"*", "update": [ { "resId":"anotherView" } ] } 
   ]
}

actionURL

The actionURL parameter can direct the request other than resourceURL of the form.

Also actionURL can use form fields an placeholders:

Example:

 {
   "label": "Product Configuration",
   ...
   "actions" : [ 
      ...
      { "id":"cascadeUpdate", 
        "actionUrl":"http://${xyz}/customers/", 
        "setData": [ { "resId":"resultTable" } ] 
      } 
   ]
}

The ${xyz} will be replaced by the value of the input text field with ID "id":"xyz".

Simple example

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

PoNG-Form.png

CSS

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

  • TODO