PoNG Module: Form View: Unterschied zwischen den Versionen
Mh (Diskussion | Beiträge) (Die Seite wurde neu angelegt: „TODO“) |
Mh (Diskussion | Beiträge) |
||
Zeile 1: | Zeile 1: | ||
− | TODO | + | [[Category:PoNG]]This [[PoNG]] module creates an input form with button(s) to post data to backend services. |
+ | |||
+ | Please have a look at the other [[PoNG_Modules#Standard_Modules_coming_with_PoNG|standard modules coming with PoNG]]. | ||
+ | |||
+ | == Usage in "structure" == | ||
+ | Simply <code>"type": "pong-form"</code> to the <code>rows</code> or <code>cols</code> resource. Example [[PoNG Structure Specification|structure file]] extract: | ||
+ | { | ||
+ | "layout": { | ||
+ | ... | ||
+ | "rows": [ | ||
+ | { | ||
+ | "rowId": "bla", | ||
+ | "resourceURL": "customer", | ||
+ | '''"type": "pong-form"''', | ||
+ | ... | ||
+ | }, | ||
+ | ... | ||
+ | ], | ||
+ | ... | ||
+ | } | ||
+ | |||
+ | == Form Definition == | ||
+ | The resource will load the form definition from the URL <code>../svc/<resourceUrl>/pong-form</code> | ||
+ | === Two column form layout === | ||
+ | An easy one or two column layout (formFields2 is optional) is available. Example JSON definition from <code><nowiki>../svc/customer/pong-form</nowiki></code> | ||
+ | { | ||
+ | "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 <code>fieldset</code> 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 <code>"hidden":"true"</code> is supported. | ||
+ | === Text === | ||
+ | <code>"type:"text"</code> (default) | ||
+ | |||
+ | <code>defaultVal</code>: property for presetting a value is supported. | ||
+ | |||
+ | If <code>"rows":"<i>number</i>"</code> property is set, then a textarea is rendered. | ||
+ | |||
+ | TODO [https://192.168.2.112/jira/browse/PONG-72 PONG-72]: <code>readonly</code>: true, false of checkbox field | ||
+ | |||
+ | === Password === | ||
+ | <code>"type:"password"</code> | ||
+ | |||
+ | === Select === | ||
+ | <code>"type:"select"</code> | ||
+ | |||
+ | '''Static options:''' <code>options</code> array, e.g. <code>"options": [ { "option":"ABC" }, { "option":"XYZ" } ]</code> | ||
+ | |||
+ | '''Dynamic options:''' <code>optionsResource</code>, e.g. <code>"optionsResource": { "resourceURL":"myObjType", "optionField":"name", "optionValue":"id" } </code> | ||
+ | |||
+ | ''Warning: The dynamic options will perform a blocking call. If there fails something, it will block the browser.'' | ||
+ | |||
+ | === Checkbox === | ||
+ | '''<code>"type:"checkbox"</code>''' | ||
+ | |||
+ | You should specify <code>"name":"..."</code> 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 <code>"defaultVal":"true"</code>. | ||
+ | |||
+ | For checkboxes you can also set <code>"readonly":"true"</code>. | ||
+ | |||
+ | 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" } | ||
+ | ] | ||
+ | |||
+ | <strike>'''<code>"type:"checkboxList"</code>''' | ||
+ | |||
+ | 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" } | ||
+ | ] | ||
+ | </strike> | ||
+ | |||
+ | === Separator === | ||
+ | <code>"type:"separator"</code> adds a horizontal line instead of a field | ||
+ | |||
+ | === Text in Form === | ||
+ | * <code>"type:"label"</code> adds the text in label as a simple text w/o any form related things, good for hints or explanations | ||
+ | * <code>descr</code> field adds a tool tip to the field. | ||
+ | |||
+ | == Form Actions == | ||
+ | <code>"action"</code>-Array: | ||
+ | * Action <code>method</code> is optional, default is <code>"method":"POST"</code> | ||
+ | * Action <code>target</code> 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 | ||
+ | ** <code>target</code> is optional, you can also ignore the response. | ||
+ | * Action <code>update</code> is an (optional) array of resource (column/row) ids, where data updates should be triggered. Example: <code>"update": [ { "resId":"xyz" } ] }</code> | ||
+ | |||
+ | === OnChange === | ||
+ | A special action is the on-change-action <code>"onChange":"*"</code>. 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 <code>"onChangeDelay":"3"</code> to set it (to 3 sec in this example). | ||
+ | |||
+ | == Simple example == | ||
+ | This is the result of the 2-column layout definition above: | ||
+ | |||
+ | [[Datei:PoNG-Form.png]] | ||
+ | |||
+ | == CSS == | ||
+ | You can use the following CCS elements to modify thy styles: | ||
+ | * TODO |
Aktuelle Version vom 17. Februar 2015, 19:26 Uhr
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.
Inhaltsverzeichnis
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 explanationsdescr
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:
CSS
You can use the following CCS elements to modify thy styles:
- TODO