Getting Started with Gform

  1. Defining the data model
  2. Declarative example
  3. Programmatic example
  4. Displaying state
  5. Validate and save
  1. Defining the data model

    Gform is all about schemas. Our data model has two fields of type "string". Both are required and only allow letters as input.

    				{
    						"attributes":[
    								{
    									"type":"string",
    									"code":"name",
    									"required": true,
    									"pattern": "[a-zA-Z]*"
    								},
    								{
    									"type":"string",
    									"code":"greetings",
    									"pattern":"[a-zA-Z]*",
    									"required": true
    								}
    						]
    				}
    			
  2. Declarative example

    The first step is to load an editorFactory. EditorFactories are responsible for creating the form according to the schema. There are two predefined editorFactories: one for general use and one especially for use inside layout containers. You can either load the editorFactory with the module "createXXXEditorFactory" which returns a function to create it or you can have the editorFactory be made available in the global variable "gform.ef.XXX" by using the module "registerXXXLEditorFactory".

    			// load the standard editorFactory and make it
    			//  globally available as 'gform.ef.standard'.
    			require(["gform/registerStandardEditorFactory"]);
    		

    To create the acutal form we can now declare the widget "gform/Editor" and set the properties editorFactory and metaUrl. The metaUrl is a relative url to the gform schema.

    			

    That's it! View.

  3. Programmatic example

    This time we assemble the widget and then put it in the dom.

    		require(["gform/createStandardEditorFactory", "gform/Editor", //
    							"dojo/json", "dojo/text!./schema.json"],
    		function(createEf, Editor, json, meta) {
    			var props= {
    				editorFactory: createEf(),
    				meta: json.parse(meta)
    			}
    			var editor = new Editor(props);
    			editor.placeAt("editor");
    		});
    		

    In the html we just need to mark the position to place the form with an id.

    			

    That's it! View.

  4. Displaying state

    Some dijits support validation and so do the attributes that use them. The attribute for type "string" is based on dijit/ValidationTextBox which supports the constraints "required" and "regex pattern". These dijits support three states: invalid ("Error"), incomplete ("Incomplete") and valid (""). Incomplete fields require the user to input a value but the user has not touched them yet. The state of the whole form is therefore characterized by the numbers "errorCount" and "incompleteCount".

    In the next example the two values are displayed below the form and are updated when a "state-changed" event is emitted by the Editor.

    		require(["gform/createStandardEditorFactory", "gform/Editor", //
    							"dojo/json", "dojo/text!./schema.json", "dojo/query"],
    		function(createEf, Editor, json, meta, query) {
    			var props= {
    				editorFactory: createEf(),
    				meta: json.parse(meta)
    			}
    			var editor = new Editor(props);
    			editor.placeAt("editor");
    			var updateState = function() {
    				query("#errorCount").innerHTML=editor.get("errorCount");
    				query("#incompleteCount").innerHTML=editor.get("incompleteCount");
    			}
    			editor.onChange(updateState)
    			updateState();
    		});
    		

    In the html we add extra spans for the two numbers.

    			

    That's it! View.

  5. Validating and Saving

    After the user has finished editing he will want to save/submit/send the changed json. Beforehand the json needs to be validated by calling 'validate(true)'. If the data is valid the json will be displayed in a popup.

    Also the user may want to reset his changes. We add a button to call 'reset' on the form.

    		require(["dojo/parser", "gform/createStandardEditorFactory", "gform/Editor", //
    							"dojo/json", "dojo/text!./schema.json", //
    							"dojo/query", "dijit/registry", "dijit/form/Button"],
    		function(parser, createEf, Editor, json, meta, query, registry) {
    			parser.parse();
    			var props= {
    				editorFactory: createEf(),
    				meta: json.parse(meta)
    			}
    			var editor = new Editor(props);
    			editor.placeAt("editor");
    			editor.startup();
    			// click listener to validate and display data.
    			var validateAndSave=function() {
    				// force the validation of unvisited and required widgets.
    				var errorCount=editor.validate(true);
    				if (errorCount==0) {
    					alert("saved: "+json.stringify(editor.get("plainValue")));
    				}
    			}
    			registry.byId("save").on("click",validateAndSave);
    			registry.byId("reset").on("click",function(){editor.reset()});
    		});
    		

    In the html we add extra spans for the two numbers.

    			

    That's it! View.