<!-- 
/*
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": "Popup Forms",
  "Menu": ["Models","Forms"],
  "Code": [
    "/models/FormPopup_Cust.json",
    "/models/FormPopup_Cust_Listing.json",
    "/models/FormPopup_JavaScript.json"
  ],
  "Demo": [
    { "url": "jsHarmonyTutorials/FormPopup_Cust?action=update&cust_id=1", "title": "Popup Form", "windowparams": "width=600,height=400" },
    { "url": "jsHarmonyTutorials/FormPopup_Cust_Listing", "title": "Linking to a Popup Form from a Grid" },
    { "url": "jsHarmonyTutorials/FormPopup_JavaScript?action=update&cust_id=1", "title": "Opening a Popup Form via JavaScript" }
  ]
}
</script>

<h3>Overview</h3>
Popup forms are rendered using a "popup" template - a stripped down version of the system template without menus or toolbars.<br/>
<br/>
Popup forms are primarily used for "detail" views of data.  When the system displays a grid listing of data, the popup form can be used to edit an individual item.<br/>
<br/>
There are several benefits to using popup forms instead of in-page links when editing data:
<ul>
  <li>Multiple records can be edited and compared at the same time</li>
  <li>Data can be copied / pasted between records</li>
  <li>The user does not have to reload their paged position within the grid when pressing the back button</li>
</ul>
When used on a tablet or phone, the popup forms will be opened as a new tab.

<h3>Using Popup Forms</h3>
Popup forms are defined by setting the model.popup property to the width and height of the popup:
<pre>
{
  "popup":[WIDTH, HEIGHT]
}
</pre>
For example:
<pre>
{
  "table":"cust",
  "layout":"form",
  "onecolumn":true,
  "popup":[600,400],
  "caption":["Customer","Customers"],
  "fields":[
    {"name":"cust_id","caption": "ID"},
    {"name":"cust_name","caption":"Name"},
    {"name":"cust_sts","caption":"Status"}
  ]
}
</pre>
<%-getScreenshot('jsHarmonyTutorials/FormPopup_Cust?cust_id=2&action=update','Popup Form', { width:600, height:400 })%>

<h3>Linking to Popup Forms</h3>
When linking using the field.link or button.link properties, the system will automatically read the target model and add code to open the target in a popup window if the "popup" property is set on the target model.
<pre>
//Link to the cust form from a grid column
{
  "fields":[
    {"name":"cust_name","caption":"Customer","link":"update:Cust"}
  ]
}
</pre>

<h3>Opening Popup Forms via JavaScript</h3>
Popup forms can also be opened via custom JavaScript:
<pre>
// XExt.popupForm :: Open the target model as a popup
//
// Parameters
//   modelid (string):           The full path to the model, including any namespace
//   action (string):            Either "insert", "update", or "browse"
//   querystringParams (object): Querystring parameters appended to the model URL
//   windowParams (object):      JavaScript window.open parameters, as an object
//   existingWindow (Window):    (Optional) Existing JavaScript Window to use instead of opening a new window
//
// Returns
//   (Window) Either the newly created popup window, or the existing window passed as an input parameter
//
XExt.popupForm(modelid, action, querystringParams, windowParams, existingWindow)
</pre>
For example:
<pre>
XExt.popupForm('Cust', 'update', {'cust_id':XModels[modelid].controller.form.Data.cust_id}, {width:850,height:600});
</pre>
