Overview

Bindings are primarily used to link from parent forms to child forms. When a parent form links to a child form, it will usually need to filter the records of the child form, often by a foreign or primary key.

For example, bindings cab be used in the following scenarios:

Tabs
A parent form that has a tab for a child form
Example: An "Edit Customer" form, that has a tab for editing Customer Addresses
Parent: Multi-tab "Edit Customer" form
Child: Customer Addresses form
Binding: Customer ID
Subforms
A parent form that has a subform grid, filtered by the key
Example: An "Edit Customer" form, that has a subform grid listing all of the customer's personnel
Parent: Edit Customer
Child: Customer Personnel Listing
Binding: Customer ID
Buttons
A parent form has a button to open a report
Example: An "Edit Customer" form has a button to generate a Sales Order Template report, that takes the customer type as a parameter
Parent: Edit Customer
Child: Sales Order Template report
Binding: Customer Type

Syntax

Bindings can be declared as follows:

"bindings": { 
  "[i]child_column1[/i]": "[i]parent_column1[/i]",    //Bind child column to a column in the parent model
  "[i]child_column2[/i]": "[i]'CONSTANT_VALUE'[/i]",  //Bind child column to a constant value - must be in single quotes
  ...
}

Below is an example of bindings in a subform: <%-getScreenshot('jsHarmonyTutorials/ModelBindings_Subform_Cust?cust_id=1&action=update&popup=1','Model Bindings')%>

"Cust": {
  "table":"cust",
  "layout":"form",
  "onecolumn":true,
  "caption":["Customer","Customers"],
  "fields":[
    {"name":"cust_id","control":"hidden","key":1},
    {"name":"cust_name","caption":"Name"},
    {"name":"cust_sts","caption":"Status"},
    {"control": "subform","target": "CustContact","bindings":{ "cust_id": "cust_id" } }
  ]
},
"CustContact": {
  "table":"cust_contact",
  "layout":"grid",
  "caption":["Contact","Contacts"],
  "fields":[
    {"name":"cust_contact_id","control":"hidden","key":1},
    {"name":"cust_id","control":"hidden"},
    {"name":"cust_contact_name","caption":"Name"},
    {"name":"cust_contact_title","caption":"Title"},
    {"name":"cust_contact_email","caption":"Email"}
  ]
}

The subform field in cust has bindings defined, connection the "cust_id" column in the subform to the "cust_id" column in the parent form.

Bindings are defined for the following elements:

tab.bindings
button.bindings
duplicate.bindings
field[subform].bindings
field[popuplov].bindings
model.bindings (for top-most forms binding to querystring values)

The bindings define the relationship between the element target and the parent form.

Querystring Bindings

By default, form fields that are set in the querystring will have the querystring values applied to the form. However, in certain instances, it may be necessary to explicitly define how the querystring values will be passed to the form.

model.bindings

If the model is the top-level model on a page, the bindings in model.bindings will be applied on save. For example, the following model.bindings:

{
  "table":"cust",
  "layout":"form",
  "onecolumn":true,
  "caption":["Customer","Customers"],
  "bindings": { "cust_id": "customer_id" },
  "fields":[
    {"name":"cust_id","control":"hidden"},
    {"name":"cust_name","caption":"Name"},
    {"name":"cust_sts","caption":"Status"}
  ]
}

Will populate the "cust_id" field with the querystring value for "customer_id":

/jsHarmonyTutorials/ModelBindings_TopLevel?action=update&customer_id=1

model.querystring

The model.querystring property can be used to override or lock querystring values. The syntax is as follows:

"querystring":: {
  "&[i]required_parameter1[/i]": "[i]value[/i]",
  "&[i]required_parameter2[/i]": "[i]value[/i]",
  "|[i]optional_parameter1[/i]": "[i]value[/i]",
  "|[i]optional_parameter2[/i]": "[i]value[/i]",
  ...
}
[i]value[/i] :=
  [i]constant_value[/i], or
  @[i]global_param[/i], defined in jsHarmonySite.globalparams

Optional querystring parameters will default the querystring value if it does not exist.
Required querystring parameters will always override the value.

The global_params are defined in jsHarmonySite.globalparams, and can be viewed in the "jshInstance.globalparams" client-side variable:

<%-(req ? JSON.stringify(req.jshsite.getGlobalParams(req), null, 4) : '{}')%>

The model.querystring property can be used to override a form so that it always opens in "update" mode by setting the "action" parameter:

"querystring": { "&action": "update" }

Additionally, the model.querystring property can be used to always open a form to edit a particular record, for instance the current user's settings:

{
  "table":"jsharmony.sys_user",
  "layout":"form",
  "onecolumn":true,
  "title":"User Settings",
  "actions":"BU",
  "querystring": { "&action":"update", "&sys_user_id": "@user_id" },
  "onupdate": "XPage.Reload({ force: true, browserRefresh: true });",
  "fields":[
    {"name":"sys_user_id","control":"hidden","key":1},
    {"name":"sys_user_fname","caption":"First Name"},
    {"name":"sys_user_lname","caption":"Last Name"}
  ]
}

In the above example, the page is forced to reload after update, so that the User Name in the top-right corner will be updated.

Automatic Bindings

In most cases, bindings can be automatically generated by the system. Automatic bindings are enabled by the following app.config.js parameter:

config.system_settings.automatic_bindings = true;

model.tabs, model.duplicate, field[subform], field[popuplov]

For tabs, duplicate forms, subforms, and popup LOVs, automatic bindings are generated as follows:

If the parent form's key fields exist in the target form, use the parent form's key fields
Otherwise, if the target form's key fields exist in the parent form, use the target form's key fields
Otherwise, generate an error

model.buttons

For buttons, on "insert" links, the following fields are automatically added to the bindings:

Any fields defined in model.querystring
Any of the model's bindings
Any query string fields except "action" and "tabs"
In form, form-m, and exec models, any fields that exist in both the parent model and link target models, except for the link target's key fields

On "browse", "update", and "savenew" links, the following fields are automatically added to the bindings:

The link target's key fields

Automatic Generation of Key Fields

Key fields are automatically added if the config.system_settings.automatic_schema.keys is set to true. If a foreign key necessary for an automatic binding is defined in the target or parent table schema, but not in the form, the field will be automatically added to the model as a hidden field.

Dynamic Bindings

Dynamic bindings are a more advanced form of automatic bindings. General-purpose components, such as jsHarmony Factory's Notes, can be used by multiple application models.

For instance, there could be an application with Customer Notes (C), and Customer Contact Notes (CC). Dynamic bindings can be used to automatically bind Notes to the Customer and Contact models by defining them in one place, without writing out the bindings each time they are used.

Dynamic bindings are defined in app.config.js:

config.dynamic_bindings = {
  "MODELID_OR_MODEL_GROUP": {
    //Add a binding from CHILD_FIELD to the Parent Form's Key Field:
    "CHILD_FIELD": "key"
    //Add a binding from CHILD_FIELD to the Parent's PARENT_FIELD:
    "CHILD_FIELD": "PARENT_FIELD"
    //Add a binding from CHILD_FIELD to the character string 'CONSTANT':
    "CHILD_FIELD": "'CONSTANT'"
    //Add a conditional binding based on the name of the Parent Form's Key.  Multiple conditions can be defined, one per PARENT_KEY:
    "CHILD_FIELD": {
      //If the parent form's key name is "PARENT_KEY", set the binding from CHILD_FIELD to the character string 'CONSTANT':
      "key:PARENT_KEY": "'CONSTANT'", 
      //If the parent form's key name is "PARENT_KEY", set the binding from CHILD_FIELD to the Parent's PARENT_FIELD:
      "key:PARENT_KEY": "PARENT_FIELD"
    }
  }
}

For example:

config.dynamic_bindings = {
  "JSHARMONY_NOTES": {   //Model ID or Model Group (from config.model_groups)
    "note_scope_id": "key", //Bind the "note_scope_id" column to the parent form's key
    "note_scope": {         //Bind the "note_scope" column based on the parent form's key name
      "key:cust_id": "'C'", //If the parent form's key name is "cust_id", set the binding to the character string 'C'
      "key:cust_contact_id": "'CC'"
    }
  }
}