Merge pull request aumcode#9 from itadapter/patch-1

Patch 1

Guides/WAVE/Field/readme.md

@@ -0,0 +1,125 @@
+# Field Class
+Field is the property of Record and represents a FieldDef from server-side NFX.DataAccess.CRUD.Schema on the client side along with view model/controller.
+
+## Field()
+Constructor. Initializes a new instance using string field definition and value.
+```js
+new rec.Field(object fieldDef)
+```
+### Examples
+```js
+var rec = new WAVE.RecordModel.Record("ID-123456", function(){
+            new this.Field({Name: "FirstName", Type: "string", Required: true});
+            new this.Field({Name: "LastName", Type: "string"});
+            new this.Field({Name: "Age", Type: "int"});
+          });
+```
+```js
+var rec = new WAVE.RecordModel.Record("ID-123456");
+new rec.Field({Name: "FirstName", Type: "string"});
+new rec.Field({Name: "LastName", Type: "string"});
+new rec.Field({Name: "Age", Type: "int", Stored: false}); 
+```
+
+
+## drop()
+Deletes this field from the record.
+
+
+## deferValidation()
+Defer or NOT validation event while changing of field’s value.
+```js
+deferValidation(bool flag)
+```
+### Examples
+```js
+var rec = ...
+var elog = "";
+rec.fldLastName.deferValidation(true);
+rec.fldLastName.eventBind(WAVE.EventManager.ANY_EVENT, function(evtType, field, phase){
+      elog += "|"+evtType + field.name() + phase + field.value();
+    });
+rec.fldLastName.value("Brown");
+// elog = "|data-changeLastNamebeforeSmith|data-changeLastNameafterBrown"
+```
+```js
+var rec = ...
+var elog = "";
+rec.fldLastName.deferValidation(false);
+rec.fldLastName.eventBind(WAVE.EventManager.ANY_EVENT, function(evtType, field, phase){
+      elog += "|"+evtType + field.name() + phase + field.value();
+    });
+rec.fldLastName.value("Brown");
+// elog = "|data-changeLastNamebeforeSmith|validateLastNameundefinedBrown|validatedLastNameundefinedBrown|data-changeLastNameafterBrown"
+```
+
+
+## eventBind()
+Binds a function to the named event handler on field.
+```js
+eventBind(string evtName, function handler)
+```
+| Parameter | Requirement | Description                                   |
+| --------- |:-----------:| --------------------------------------------- |
+| evtName   | required    | name of event from WAVE.RecordModel namespace |
+| handler   | required    | callback-function which fires on event        |
+### Examples
+```js
+var rec = ...
+var elog = "";
+rec.eventBind(WAVE.RecordModel.EVT_FIELD_DROP, function(field, phase){
+          elog += "|" + field.name() + phase;
+         });
+rec.fldLastName.drop();
+// elog = |LastNamebefore|LastNameafter          
+```
+
+
+## isGUIModified()
+Returns true when this field was modified from an attached control.
+
+
+## isModified()
+Returns true when this field has been modified.
+
+
+## loaded()
+Returns true when this field has finished loading.
+
+
+## toString()
+Returns string like `[fieldType]Field(fieldName = 'fieldValue')`.
+
+
+## stored()
+Returns true if field must be stored back in the server (db).
+
+
+## Validation functions
+* valid()     - returns true if field has not validation error.
+* validate()  - validates field and returns true if it is valid.
+* validated() - returns true if field has been validated.
+* validationError() - returns error thrown during validation.
+### Examples
+```js
+var rec = new WAVE.RecordModel.Record("1", function(){
+            new this.Field({Name: "A", Type: "string"});
+            new this.Field({Name: "B", Type: "string", Required: true});
+          });
+
+rec.fldB.validated(); // false
+rec.fldB.validate();
+rec.fldB.validated(); //true
+rec.fldB.valid();     // false
+var err = rec.fldB.validationError(); // contains: 'B' must have a value
+rec.fldB.value("aaaaa");
+rec.fldB.valid();     // true
+```
+
+
+## value()
+`value()` - then returns field’s value.  
+`value(object value, bool fromGUI)` - Sets value and modified, validated flags if new value is different from an existing one. `fromGUI` indicates that field is being altered from an attached control.
+
+
+

Guides/WAVE/Record/readme.md

@@ -0,0 +1,155 @@
+# Record Class
+The purpose of this class is to represent server-side NFX.DataAccess.CRUD.Schema on the client side along with view model/controller.
+Record instances are initialized using server NFX.Wave.Client.RecordModelGenerator class that turns Schema into JSON object suitable for record initialization on client.
+
+## Record()
+Constructor. Initializes a new instance using record id with optional field initialization function
+or complex initialization vector:
+```js
+new WAVE.RecordModel.Record(string recID, function fieldFunc)
+```
+or
+```js
+new WAVE.RecordModel.Record(object initVector)
+```
+| Parameter  | Requirement | Description                                                       |
+| ---------- |:-----------:| ----------------------------------------------------------------- |
+| fieldFunc  | optional    | callback-function which contains fields initialization statements |
+| recID      | required    | unique record id                                                  |
+| initVector | required    | contains record id and fields' definitions with values            |
+
+**Notes**  
+In both cases fields will be named as concatenation string 'fld' and field name from definition.
+
+### Examples
+```js
+var rec = new WAVE.RecordModel.Record("ID-123456");
+```
+```js
+var rec = new WAVE.RecordModel.Record("ID-123456", function(){
+            new this.Field({Name: "FirstName", Type: "string"});
+            new this.Field({Name: "LastName", Type: "string"});
+            new this.Field({Name: "Age", Type: "int", Required: true, MinValue: 10, MaxValue: 99});
+          });
+```
+```js
+var rec = new WAVE.RecordModel.Record({ID: 'REC-1', 
+            fields: [
+              {def: {Name: 'FirstName', Type: 'string'}, val: 'John'},
+              {def: {Name: 'LastName', Type: 'string'}, val: 'Smith'},
+              {def: {Name: 'Age', Type: 'int'}, val: 33},
+              {def: {Name: 'Helper', Type: 'string', Stored: false}}
+            ]});
+```
+
+
+### Examples
+```js
+var rec = new WAVE.RecordModel.Record("1", function(){
+            new this.Field({Name: "A", Type: "string"});
+            new this.Field({Name: "B", Type: "string", Required: true});
+          });
+
+rec.validate();
+var allErr = rec.allValidationErrorStrings();
+// allErr contains: 'B' must have a value
+```
+
+
+## data()
+Returns a map of fields: `{fieldName:fieldValue,...}`.
+
+```js
+data(bool modifiedOnly, bool includeNonStored)
+```
+| Parameter        | Requirement | Description                         |
+| ---------------- |:-----------:| ----------------------------------- |
+| modifiedOnly     | optional    | only get fields that have changed   |
+| includeNonStored | optional    | include fields that are not stored |
+### Examples
+```js
+var rec = new WAVE.RecordModel.Record({ID: 'REC-1', 
+            fields: [
+              {def: {Name: 'FirstName', Type: 'string'}, val: 'John'},
+              {def: {Name: 'LastName', Type: 'string'}, val: 'Smith'},
+              {def: {Name: 'Age', Type: 'int'}, val: 33},
+              {def: {Name: 'Helper', Type: 'string', Stored: false}}
+            ]});
+
+var d = JSON.stringify(rec.data(false, true));
+// d = {"FirstName":"John","LastName":"Smith","Age":33,"Helper":null}
+
+rec.fldLastName.value("Brown");
+var d = JSON.stringify(rec.data(true));
+// d = {"LastName":"Brown"}
+```
+
+
+## eventBind()
+Binds a function to the named event handler on record.
+```js
+eventBind(string evtName, function handler)
+```
+| Parameter | Requirement | Description                                   |
+| --------- |:-----------:| --------------------------------------------- |
+| evtName   | required    | name of event from WAVE.RecordModel namespace |
+| handler   | required    | callback-function which fires on event        |
+### Examples
+```js
+var rec = new WAVE.RecordModel.Record("ID-123456", function(){
+            new this.Field({Name: "FirstName", Type: "string"});
+            new this.Field({Name: "LastName", Type: "string"});
+          });
+
+var elog = "";
+rec.eventBind(WAVE.RecordModel.EVT_FIELD_DROP, function(rec, field, phase){
+          elog += "|" + field.name() + phase;
+         });
+rec.fldLastName.drop();
+// elog = |LastNamebefore|LastNameafter          
+```
+
+## fieldByName()
+Returns a field by its case-insensitive name or null.
+```js
+fieldByName(string fieldName)
+```
+### Examples
+```js
+var rec = new WAVE.RecordModel.Record("ID-123456", function(){
+            new this.Field({Name: "FirstName", Type: "string"});
+            new this.Field({Name: "Age", Type: "int"});
+          });
+
+rec.fieldByName("FirstName").value("John");
+var v = rec.fldFirstName.value();
+// v = John        
+```
+
+
+## loaded()
+Returns true when record has finished loading data and constructing fields.
+
+
+##toString()
+Returns string like `Record[RecID]`.
+
+
+## Validation functions
+* allValidationErrorStrings() - returns all record and field-level validation errors.
+* validate() - validates record and returns true is everything is valid.
+### Examples
+```js
+var rec = new WAVE.RecordModel.Record("1", function(){
+            new this.Field({Name: "A", Type: "string"});
+            new this.Field({Name: "B", Type: "string", Required: true});
+            new this.Field({Name: "C", Type: "int", Required: true});
+          });
+
+rec.validate();
+var all = rec.allValidationErrorStrings();
+// all contains 'B' must have a value
+// all contains 'C' must have a value
+```
+
+

Guides/WAVE/RecordView/readme.md

@@ -0,0 +1,27 @@
+# RecordView
+
+Binds Record model (an isntance of Record class) with UI builder/rendering library which dynamically builds the DOM in the attached view components (div placeholders). Thus, changes made to view model/data model in record instance will get automatically represented in the attached UI.
+
+## RecordView
+Constructor. Initializes a new instance using string field definition and value.
+```js
+new WAVE.RecordModel.Record(string ID, object record, object gui, bool manualViews)
+```
+| Parameter   | Requirement | Description                                                           |
+| ----------- |:-----------:| --------------------------------------------------------------------- |
+| ID          | required    | id - unique in page id of the view                                    |
+| record      | required    | data record instance                                                  |
+| gui         | optional    | GUI library, if null then default script "wv.gui.js" must be included |
+| manualViews | optional    | if true then view controls will not be auto-constructed               |
+### Examples
+```js
+var REC =  new WAVE.RecordModel.Record({ID: 'R1', 
+            fields: [
+                {def: {Name: 'FirstName', Type: 'string', Required: true}, val: 'John'},
+                {def: {Name: 'LastName', Type: 'string', Required: true}, val: 'Smith'},
+                {def: {Name: 'Age', Type: 'int', MinValue: 10}, val: 33},
+                {def: {Name: 'MusicType', Type: 'string', LookupDict: {HRK: "Hard Rock", CRK: "Classic Rock", RAP: "Rap", CMU: "Classical music"}}},
+            ]}
+        );
+var RVIEW = new WAVE.RecordModel.RecordView("V1", REC);
+```