Introduction
Forms enable editing data, one record at a time. Grids usually list rows, and then link to forms for further editing.
Forms are defined by setting the "layout" to "form".
Standard Form
<%-getScreenshot('jsHarmonyTutorials/FormBasic_Standard?action=update&cust_id=2&popup=1','Basic Form')%>
{
"table":"cust",
"layout":"form",
"onecolumn":true,
"caption":["Customer","Customers"],
"fields":[
{"name":"cust_id","caption": "ID"},
{"name":"cust_name","caption":"Name"},
{"name":"cust_sts","caption":"Status"}
]
}
Form with Subforms
Forms can contain subforms:
<%-getScreenshot('jsHarmonyTutorials/FormBasic_Subform_Cust?action=update&cust_id=1&popup=1','Form w/Subform')%>
//Parent Form
"Cust": {
"table":"cust",
"layout":"form",
"onecolumn":true,
"caption":["Customer","Customers"],
"fields":[
{"name":"cust_name","caption":"Name"},
{"name":"cust_sts","caption":"Status"},
{"control": "subform","target": "CustAddr"}
]
}
//Subform
"CustAddr": {
"table":"cust_addr",
"layout":"form-m",
"onecolumn":true,
"caption":["Address","Addresses"],
"fields":[
{"name":"cust_addr_country","caption":"Country"},
{"name":"cust_addr_line1","caption":"Address"},
{"name":"cust_addr_line2","caption":""},
{"name":"cust_addr_city","caption":"City"},
{"name":"cust_addr_state","caption":"State"},
{"name":"cust_addr_zip","caption":"Zip"}
]
}
Tabbed Forms
Forms can be tabbed:
<%-getScreenshot('jsHarmonyTutorials/FormBasic_Tabbed_Cust_Container?action=update&cust_id=1&popup=1','Tabbed Form')%>
//Tabbed Parent Form
"FormBasic_Tabbed_Cust_Container": {
"table":"cust",
"layout":"form",
"caption":["Customer","Customers"],
"tabpanelstyle":"min-width:500px;",
"tabs":[
{"name":"Overview","target":"FormBasic_Tabbed_Cust"},
{"name":"Contacts","caption": "Contacts","target":"FormBasic_Tabbed_CustContact_Listing"}
]
}
//Overview Tab
"FormBasic_Tabbed_Cust": {
"table":"cust",
"layout":"form",
"onecolumn":true,
"caption":["Customer","Customers"],
"fields":[
{"name":"cust_name","caption":"Name"},
{"name":"cust_sts","caption":"Status"}
]
}
//Contacts Tab
"FormBasic_Tabbed_CustContact_Listing": {
"table":"cust_contact",
"layout":"grid",
"caption":["Contact","Contacts"],
"fields":[
{"name":"cust_contact_name","caption":"Name"},
{"name":"cust_contact_title","caption":"Title"},
{"name":"cust_contact_email","caption":"Email"}
]
}
Unbound Forms
Unbound forms are fully disconnected from any database access, except via JavaScript API calls.
<%-getScreenshot('jsHarmonyTutorials/FormBasic_Unbound?popup=1','Unbound Form')%>
{
"layout":"form",
"unbound":1,
"title":"Message",
"fields":[
{"control":"html","value":"Lorem ipsum dolor sit amet, consectetur adipiscing elit."}
]
}
Fully Custom Forms
Forms can also use fully custom JS / HTML. More information is available in the Custom Form tutorial.
Form SQL / Datasource
A form's datasource is a table or view. The database table or view is defined by the "table" property. The database statements (Browse / Insert / Update / Delete) are automatically generated based on the table and fields.
It is best practice to use a table, since primary keys and foreign keys can be automatically read from the database. However, editable views can also be used if the primary / foreign keys are defined in the models using the "key" and "foreignkey" properties.
Custom SQL
Custom SQL can be used to override any of the SQL statements. For example:
{
"table":"cust",
"layout":"form",
"onecolumn":true,
"caption":["Customer","Customers"],
"sqlinsert":"%%%SQL%%%; update cust set cust_start_dt = date('now', 'localtime');",
"fields":[
{"name":"cust_id","caption": "ID"},
{"name":"cust_name","caption":"Name"},
{"name":"cust_sts","caption":"Status"},
{"name":"cust_start_dt","caption":"Start Date","control":"label"}
]
}
Please note, custom SQL should generally not be used. Database-level business logic should be implemented using database triggers.
More information on custom SQL is available in the Database / SQL tutorial.
Form Fields / Controls
The "fields" property defines the fields that are selected from the database.
Primary keys are automatically added to the table, if they are defined as primary keys in the database. Foreign keys for tables are automatically added when required by bindings.
A variety of controls are available. The control can be set using the "control" property:
<%-getScreenshot('jsHarmonyTutorials/FormBasic_Controls?action=update&cust_id=1&popup=1','Form Controls')%>
{
"table":"cust",
"layout":"form",
"onecolumn":true,
"caption":["Customer","Customers"],
"fields":[
{"name":"cust_id","caption": "ID"},
{"name":"cust_name","caption":"Name","control":"textzoom"},
{"name":"cust_sts","caption":"Status","control":"dropdown_L"},
{"name":"cust_start_dt","caption":"Start Date","control":"date_mmddyy"},
{"name":"cust_desc","caption":"Notes","control":"textarea"}
]
}
More information about form fields and controls is available in the Fields tutorials.
HTML Content
Additional HTML can be added to a form by creating a MODEL.ejs file.
<%-getScreenshot('jsHarmonyTutorials/FormBasic_HTMLContent?popup=1','Form HTML Content')%>
//FORM.json
{
"layout":"form",
"unbound":1,
"title":"HTML Content"
}
//FORM.ejs
Sample Content
Lorem ipsum dolor sit amet, consectetur adipiscing elit.
Querystring
Insert vs Browse vs Update Mode
Forms can be acccessed in either "insert", "browse", or "update" mode.
Insert Mode
Insert mode is accessed by adding "?action=insert" to the querystring:
/jsHarmonyTutorials/FormBasic_Standard?action=insert
<%-getScreenshot('jsHarmonyTutorials/FormBasic_Standard?action=insert&popup=1','Form Insert Mode')%>
Browse Mode
Browse mode is accessed by adding "?action=browse&PRIMARYKEY=VALUE" to the querystring:
/jsHarmonyTutorials/FormBasic_Standard?action=browse&cust_id=1
<%-getScreenshot('jsHarmonyTutorials/FormBasic_Standard?action=browse&cust_id=1&popup=1','Form Browse Mode')%>
Update Mode
Update mode is accessed by adding "?action=update&PRIMARYKEY=VALUE" to the querystring:
/jsHarmonyTutorials/FormBasic_Standard?action=update&cust_id=1
<%-getScreenshot('jsHarmonyTutorials/FormBasic_Standard?action=update&cust_id=1&popup=1','Form Update Mode')%>
Default Values
Default values can be set on insert by adding the field value to the querystring:
/jsHarmonyTutorials/FormBasic_Standard?action=insert&cust_sts=ACTIVE
<%-getScreenshot('jsHarmonyTutorials/FormBasic_Standard?action=insert&cust_sts=ACTIVE&popup=1','Form Insert Mode Default Value')%>
Always Editable on Insert
Passing a default value will make the field read-only. In order to keep the field editable, set the "locked_by_querystring" property to false:
{
"fields":[
{ "name":"cust_sts", "caption":"Status", "locked_by_querystring":false }
]
}
<%-getScreenshot('jsHarmonyTutorials/FormBasic_EditableDefault?action=insert&cust_sts=ACTIVE&popup=1','Form Insert Mode Default Value Editable')%>