<!-- 
/*
Copyright 2017 apHarmony

This file is part of jsHarmony.

jsHarmony is free software: you can redistribute it and/or modify
it under the terms of the GNU Lesser General Public License as published by
the Free Software Foundation, either version 3 of the License, or
(at your option) any later version.

jsHarmony is distributed in the hope that it will be useful,
but WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
GNU Lesser General Public License for more details.

You should have received a copy of the GNU Lesser General Public License
along with this package.  If not, see <http://www.gnu.org/licenses/>.
*/
-->
<script type="text/x-tutorial-info">
{
  "Title": "Layout: Multisel",
  "Menu": ["Models","Forms"],
  "Code": [
    "/models/MultiselBasic_Standard.json",
    "/models/MultiselBasic_MultipleColumns.json"
  ],
  "Demo": [
    { "url": "jsHarmonyTutorials/MultiselBasic_Standard?action=update&cust_id=2", "title": "Basic Multisel" },
    { "url": "jsHarmonyTutorials/MultiselBasic_MultipleColumns?action=update&cust_id=2", "title": "Multisel w/Multiple Columns" }
  ]
}
</script>

<h3>Overview</h3>
The multisel layout provides an interface for editing many-to-many relationships.  In most implementations, the mutlisel would be programmed as a subform of a parent form.<br/>
<br/>
The multisel enables a user to add a link connecting the keys of two different tables.  For example, in the situation where there is one table of Flags (Inactive, Credit Risk, etc), and another table of Customers, the multisel layout allows the user to select multiple Flags for each Customer record.

<h3>Standard Multisel</h3>
<%-getScreenshot('jsHarmonyTutorials/MultiselBasic_Standard?action=update&cust_id=2&popup=1','Basic Multisel')%>
<pre>
{ 
  "MultiselBasic_Standard": {
    "table":"cust_flag",
    "layout":"multisel",
    "caption":["Customer Flag","Customers Flags"],
    "fields":[
      {"name":"cust_id"},
      {"name":"cust_flag_type","caption":"Flag"}
    ]
  }
}
</pre>
The "cust_flag" table contains two foreign keys - cust_id (Customer ID), and cust_flag_type (Flag Type).  Each checked checkbox will create a record in the "cust_flag" table with a unique cust_flag_id, which is automatically recognized from the table definition as the primary key.

<h3>Multiple Columns</h3>
The multisel can support multiple display columns, as well as links in the display columns:
<%-getScreenshot('jsHarmonyTutorials/MultiselBasic_MultipleColumns?action=update&cust_id=2&popup=1','Multisel w/ Multiple Columns')%>
<pre>
{
  "table":"cust_flag",
  "layout":"multisel",
  "caption":["Customer Flag","Customers Flags"],
  "fields":[
    {"name":"cust_id"},
    {"name":"cust_flag_type","caption":"Flag"},
    {"control":"html","value":"Flagged Customers","link":"update:MultiselBasic_MultipleColumns_Cust_Listing&cust_flag_type=code_val","caption":"Flagged Customers"}
  ]
}
</pre>

If using the multisel value in an expression, be sure to use "code_val" instead of the field name.  This will ensure that the expression still works if the value is not selected.

<h3>Canonical Syntax</h3>
The full multisel syntax should define a primary key, foreign key, and list of values:
<pre>
{
  "layout":"multisel",
  "title":"Customer Flags",
  "caption":["","Flag","Flags"],
  "table":"cust_flag",
  "actions":"BU",
  "fields":[
    {"name":"cust_id","type":"bigint","foreignkey": 1,"control":"hidden"},
    {"name":"cust_flag_id","type":"bigint","key":1,"control":"hidden"},
    {"name":"cust_flag_type","caption":"Flag Type","actions":"B","lov": { "code": "cust_flag_type" }}
  ]
}
</pre>
<ul>
  <li><b>Primary Key</b> ("key") should be set on the primary key of the many-to-many table.</li>
  <li><b>Foreign Key</b> ("foreignkey") should be set on the record that will have the List of Values attached to it.</li>
  <li><b>List of Values</b> ("lov") should be defined on the field whose values will be listed for selection.</li>
</ul>