panel/docs/panel-form.mustache

	panel-form.mustache revision 84765788c559bfdead67172a79759ac60c77231b
84765788c559bfdead67172a79759ac60c77231bTilo Mitra<div class="intro">
84765788c559bfdead67172a79759ac60c77231bTilo Mitra    <p>This example demonstrates how to set up and instantiate Y.Panel to take advantage of its nested modality and header/footer button support. In this example, we create a simple datatable with some basic information that is updated and removed through a modal form with some custom buttons.</p>
84765788c559bfdead67172a79759ac60c77231bTilo Mitra</div>
84765788c559bfdead67172a79759ac60c77231bTilo Mitra
84765788c559bfdead67172a79759ac60c77231bTilo Mitra<div class="example">
84765788c559bfdead67172a79759ac60c77231bTilo Mitra    <style type="text/css">
84765788c559bfdead67172a79759ac60c77231bTilo Mitra        {{>panel-form-css-source}}
84765788c559bfdead67172a79759ac60c77231bTilo Mitra    </style>
84765788c559bfdead67172a79759ac60c77231bTilo Mitra
84765788c559bfdead67172a79759ac60c77231bTilo Mitra
84765788c559bfdead67172a79759ac60c77231bTilo Mitra    {{>panel-form-html-source}}
84765788c559bfdead67172a79759ac60c77231bTilo Mitra
84765788c559bfdead67172a79759ac60c77231bTilo Mitra    <script type="text/javascript">
84765788c559bfdead67172a79759ac60c77231bTilo Mitra        {{>panel-form-js-source}}
84765788c559bfdead67172a79759ac60c77231bTilo Mitra    </script>
84765788c559bfdead67172a79759ac60c77231bTilo Mitra</div>
84765788c559bfdead67172a79759ac60c77231bTilo Mitra
84765788c559bfdead67172a79759ac60c77231bTilo Mitra<h2>Creating a modal form using Panels</h2>
84765788c559bfdead67172a79759ac60c77231bTilo Mitra
84765788c559bfdead67172a79759ac60c77231bTilo Mitra<h3>Setting Up The YUI Instance</h3>
84765788c559bfdead67172a79759ac60c77231bTilo Mitra
84765788c559bfdead67172a79759ac60c77231bTilo Mitra<p>To create an instance of a Panel on your page, the only module you need to request is the `panel` module. The `panel` module will pull in the `widget`, `widget-stack`, `widget-position`, `widget-position-align`, `widget-position-constrain`, `widget-stdmod`, `widget-buttons`, `widget-modality` and `widget-autohide` extensions it uses.</p>
84765788c559bfdead67172a79759ac60c77231bTilo Mitra
84765788c559bfdead67172a79759ac60c77231bTilo Mitra<p>For this example, we also use the YUI3 Datatable, and the Drag plugin to make the panels draggable. This requires us to also request the `datatable-base` and `dd-plugin` modules in our use statement.
84765788c559bfdead67172a79759ac60c77231bTilo Mitra
84765788c559bfdead67172a79759ac60c77231bTilo Mitra```
84765788c559bfdead67172a79759ac60c77231bTilo MitraYUI({...}).use("panel", "datatable-base", "dd-plugin", function(Y) {
84765788c559bfdead67172a79759ac60c77231bTilo Mitra    // We'll write example code here where we have Y.Datatable, Y.Plugin.Drag and Y.Panel available
84765788c559bfdead67172a79759ac60c77231bTilo Mitra});
84765788c559bfdead67172a79759ac60c77231bTilo Mitra```
84765788c559bfdead67172a79759ac60c77231bTilo Mitra
84765788c559bfdead67172a79759ac60c77231bTilo Mitra<p>Note, using the `panel` module, will also pull down the default CSS required for panel. The CSS that styles the Panel requires you to have the class `yui3-skin-sam` on a parent element, commonly the `<body>` tag.</p>
84765788c559bfdead67172a79759ac60c77231bTilo Mitra
84765788c559bfdead67172a79759ac60c77231bTilo Mitra<h3>Creating a Panel From Markup</h3>
84765788c559bfdead67172a79759ac60c77231bTilo Mitra
84765788c559bfdead67172a79759ac60c77231bTilo Mitra<p>For this example, we'll need two panel instances. The first will be created through markup, while the second will be created through JavaScript (just to illustrate the differences). The code snippet below is the markup for our modal form. It consists of a fieldset with a couple of `<input>` boxes. The `yui3-widget-bd` class is not required, but tells the Panel that this content goes in the body of the widget.</p>
84765788c559bfdead67172a79759ac60c77231bTilo Mitra
84765788c559bfdead67172a79759ac60c77231bTilo Mitra```
84765788c559bfdead67172a79759ac60c77231bTilo Mitra<div id="panelContent">
84765788c559bfdead67172a79759ac60c77231bTilo Mitra    <div class="yui3-widget-bd">
84765788c559bfdead67172a79759ac60c77231bTilo Mitra    <form>
84765788c559bfdead67172a79759ac60c77231bTilo Mitra      <fieldset>
84765788c559bfdead67172a79759ac60c77231bTilo Mitra        <p><label for="id">ID</label><br/>
84765788c559bfdead67172a79759ac60c77231bTilo Mitra        <input type="text" name="id" id="productId" placeholder=""></p>
84765788c559bfdead67172a79759ac60c77231bTilo Mitra        <p><label for="name">Name</label><br/>
84765788c559bfdead67172a79759ac60c77231bTilo Mitra        <input type="text" name="name" id="name" value="" placeholder=""></p>
84765788c559bfdead67172a79759ac60c77231bTilo Mitra        <p><label for="password">Price</label><br/>
84765788c559bfdead67172a79759ac60c77231bTilo Mitra        <input type="text" name="price" id="price" value="" placeholder="$"></p>
84765788c559bfdead67172a79759ac60c77231bTilo Mitra      </fieldset>
84765788c559bfdead67172a79759ac60c77231bTilo Mitra      </form>
84765788c559bfdead67172a79759ac60c77231bTilo Mitra  </div>
84765788c559bfdead67172a79759ac60c77231bTilo Mitra```
84765788c559bfdead67172a79759ac60c77231bTilo Mitra
84765788c559bfdead67172a79759ac60c77231bTilo Mitra<p>The container DIV with id="panelContent" is specified as the contentBox for the Panel instance, and during instantiation, the panel will look for DIV's marked with the `yui3-widget-hd, yui3-widget-bd, yui3-widget-ft` classes to setup the Overlay's header, body and footer content attributes.</p>
84765788c559bfdead67172a79759ac60c77231bTilo Mitra
84765788c559bfdead67172a79759ac60c77231bTilo Mitra<h3>Instantiating the Parent Panel</h3>
84765788c559bfdead67172a79759ac60c77231bTilo Mitra
84765788c559bfdead67172a79759ac60c77231bTilo Mitra<p>To create a panel instance, we use the panel constructor `Y.Panel`. We can pass in some additional configuration attributes such as `modal`, `headerContent`, and `centered`. We can make the panel draggable by adding the `Y.Plugin.Drag` plugin.</p>
84765788c559bfdead67172a79759ac60c77231bTilo Mitra
84765788c559bfdead67172a79759ac60c77231bTilo Mitra<p>After creating the panel instance, we invoke `panel.render()` to update the DOM to reflect the current state of the panel.</p>
84765788c559bfdead67172a79759ac60c77231bTilo Mitra
84765788c559bfdead67172a79759ac60c77231bTilo Mitra```
84765788c559bfdead67172a79759ac60c77231bTilo Mitravar panel = new Y.Panel({
84765788c559bfdead67172a79759ac60c77231bTilo Mitra  srcNode: "#panelContent",
84765788c559bfdead67172a79759ac60c77231bTilo Mitra  width: 250,
84765788c559bfdead67172a79759ac60c77231bTilo Mitra  centered: true,
84765788c559bfdead67172a79759ac60c77231bTilo Mitra  visible: false,
84765788c559bfdead67172a79759ac60c77231bTilo Mitra  modal:true,
84765788c559bfdead67172a79759ac60c77231bTilo Mitra  headerContent: "Add A New Product",
84765788c559bfdead67172a79759ac60c77231bTilo Mitra  plugins: [Y.Plugin.Drag]
84765788c559bfdead67172a79759ac60c77231bTilo Mitra});
84765788c559bfdead67172a79759ac60c77231bTilo Mitra
84765788c559bfdead67172a79759ac60c77231bTilo Mitrapanel.render();
84765788c559bfdead67172a79759ac60c77231bTilo Mitra```
84765788c559bfdead67172a79759ac60c77231bTilo Mitra
84765788c559bfdead67172a79759ac60c77231bTilo Mitra<h3>Adding Footer buttons to the Panel</h3>
84765788c559bfdead67172a79759ac60c77231bTilo Mitra
84765788c559bfdead67172a79759ac60c77231bTilo Mitra<p>The parent panel has two buttons in the footer, "Add Item" and "Remove All Items". We add these buttons through the `addButton()` method present on the Y.Panel instance. For each button, we specify an `action` function, which will be called when the button is clicked, and a `section` property that specifies whether it should get rendered in the header or the footer.</p>
84765788c559bfdead67172a79759ac60c77231bTilo Mitra
84765788c559bfdead67172a79759ac60c77231bTilo Mitra```
84765788c559bfdead67172a79759ac60c77231bTilo Mitrapanel.addButton(
84765788c559bfdead67172a79759ac60c77231bTilo Mitra  {
84765788c559bfdead67172a79759ac60c77231bTilo Mitra      value: "Add Item",
84765788c559bfdead67172a79759ac60c77231bTilo Mitra      action: function(e) {
84765788c559bfdead67172a79759ac60c77231bTilo Mitra        e.preventDefault();
84765788c559bfdead67172a79759ac60c77231bTilo Mitra        addItem(); //this method adds a record to the datatable
84765788c559bfdead67172a79759ac60c77231bTilo Mitra      },
84765788c559bfdead67172a79759ac60c77231bTilo Mitra      section: Y.WidgetStdMod.FOOTER
84765788c559bfdead67172a79759ac60c77231bTilo Mitra  }
84765788c559bfdead67172a79759ac60c77231bTilo Mitra);
84765788c559bfdead67172a79759ac60c77231bTilo Mitrapanel.addButton(
84765788c559bfdead67172a79759ac60c77231bTilo Mitra  {
84765788c559bfdead67172a79759ac60c77231bTilo Mitra      value: "Remove All Items",
84765788c559bfdead67172a79759ac60c77231bTilo Mitra      action: function(e) {
84765788c559bfdead67172a79759ac60c77231bTilo Mitra        e.preventDefault();
84765788c559bfdead67172a79759ac60c77231bTilo Mitra        removeAllItemsConfirm();
84765788c559bfdead67172a79759ac60c77231bTilo Mitra      },
84765788c559bfdead67172a79759ac60c77231bTilo Mitra      section: Y.WidgetStdMod.FOOTER
84765788c559bfdead67172a79759ac60c77231bTilo Mitra  }
84765788c559bfdead67172a79759ac60c77231bTilo Mitra);
84765788c559bfdead67172a79759ac60c77231bTilo Mitra```
84765788c559bfdead67172a79759ac60c77231bTilo Mitra
84765788c559bfdead67172a79759ac60c77231bTilo Mitra
84765788c559bfdead67172a79759ac60c77231bTilo Mitra<h3>Creating the nested Panel through JavaScript</h3>
84765788c559bfdead67172a79759ac60c77231bTilo Mitra
84765788c559bfdead67172a79759ac60c77231bTilo Mitra<p>In the example, clicking the "Remove all items" button renders a nested confirmation panel. Since Y.Panel implements the `Y.WidgetStack` and `Y.WidgetModality` extensions, creating nested panels are easy to do for the developer. The nested panel code is as follows:</p>
84765788c559bfdead67172a79759ac60c77231bTilo Mitra
84765788c559bfdead67172a79759ac60c77231bTilo Mitra```
84765788c559bfdead67172a79759ac60c77231bTilo Mitravar nestedPanel = new Y.Panel({
84765788c559bfdead67172a79759ac60c77231bTilo Mitra  bodyContent: "Are you sure you want to remove all items?",
84765788c559bfdead67172a79759ac60c77231bTilo Mitra  zIndex: 5, //We set a z-index higher than the parent's z-index
84765788c559bfdead67172a79759ac60c77231bTilo Mitra  centered:true,
84765788c559bfdead67172a79759ac60c77231bTilo Mitra  width:400,
84765788c559bfdead67172a79759ac60c77231bTilo Mitra  modal:true,
84765788c559bfdead67172a79759ac60c77231bTilo Mitra
84765788c559bfdead67172a79759ac60c77231bTilo Mitra  //We add the "Yes" and "No" buttons
84765788c559bfdead67172a79759ac60c77231bTilo Mitra  buttons: [
84765788c559bfdead67172a79759ac60c77231bTilo Mitra    {
84765788c559bfdead67172a79759ac60c77231bTilo Mitra        value: "Yes",
84765788c559bfdead67172a79759ac60c77231bTilo Mitra        action  : function(e) {
84765788c559bfdead67172a79759ac60c77231bTilo Mitra          e.preventDefault();
84765788c559bfdead67172a79759ac60c77231bTilo Mitra          nestedPanel.hide();
84765788c559bfdead67172a79759ac60c77231bTilo Mitra          panel.hide();
84765788c559bfdead67172a79759ac60c77231bTilo Mitra          removeItems(); //this method removes all data from the datatable
84765788c559bfdead67172a79759ac60c77231bTilo Mitra        },
84765788c559bfdead67172a79759ac60c77231bTilo Mitra        section: Y.WidgetStdMod.FOOTER
84765788c559bfdead67172a79759ac60c77231bTilo Mitra    },
84765788c559bfdead67172a79759ac60c77231bTilo Mitra    {
84765788c559bfdead67172a79759ac60c77231bTilo Mitra        value: "No",
84765788c559bfdead67172a79759ac60c77231bTilo Mitra        action: function(e) {
84765788c559bfdead67172a79759ac60c77231bTilo Mitra          e.preventDefault();
84765788c559bfdead67172a79759ac60c77231bTilo Mitra          nestedPanel.hide();
84765788c559bfdead67172a79759ac60c77231bTilo Mitra        },
84765788c559bfdead67172a79759ac60c77231bTilo Mitra        section: Y.WidgetStdMod.FOOTER
84765788c559bfdead67172a79759ac60c77231bTilo Mitra    }
84765788c559bfdead67172a79759ac60c77231bTilo Mitra  ]
84765788c559bfdead67172a79759ac60c77231bTilo Mitra});
84765788c559bfdead67172a79759ac60c77231bTilo Mitra
84765788c559bfdead67172a79759ac60c77231bTilo MitranestedPanel.render('#nestedPanel');
84765788c559bfdead67172a79759ac60c77231bTilo Mitra```
84765788c559bfdead67172a79759ac60c77231bTilo Mitra
84765788c559bfdead67172a79759ac60c77231bTilo Mitra<p>In this case, we pass in an array of buttons to the `buttons` attribute. As a result, the nested panel does not have the close button in the top-right corner.</p>
84765788c559bfdead67172a79759ac60c77231bTilo Mitra
84765788c559bfdead67172a79759ac60c77231bTilo Mitra<p>
84765788c559bfdead67172a79759ac60c77231bTilo Mitra
84765788c559bfdead67172a79759ac60c77231bTilo Mitra
84765788c559bfdead67172a79759ac60c77231bTilo Mitra<h3>CSS: Panel Look/Feel</h3>
84765788c559bfdead67172a79759ac60c77231bTilo Mitra
84765788c559bfdead67172a79759ac60c77231bTilo Mitra<p>The panel.css Sam Skin file (build/panel/assets/skins/sam/panel.css) provides the default functional CSS for the panel. In addition, an image file (build/panel/assets/skins/sam/sprite_icons.gif) provides the icons for the "close" button.</p>
84765788c559bfdead67172a79759ac60c77231bTilo Mitra
84765788c559bfdead67172a79759ac60c77231bTilo Mitra
84765788c559bfdead67172a79759ac60c77231bTilo Mitra<p><strong>NOTE:</strong> As discussed on the Widget landing page, all widgets are enclosed in 2 containing elements - the boundingBox is the outer(most) element, and the contentBox is the inner element into which the widget's content is added. It is advised to apply any look/feel CSS for the widget to the content box and it's children. This leaves the bounding box without padding/borders, allowing for consistent positioning/sizing across box models.</p>
84765788c559bfdead67172a79759ac60c77231bTilo Mitra
84765788c559bfdead67172a79759ac60c77231bTilo Mitra<h2>Complete Example Source</h2>
84765788c559bfdead67172a79759ac60c77231bTilo Mitra```
84765788c559bfdead67172a79759ac60c77231bTilo Mitra    <style type="text/css">
84765788c559bfdead67172a79759ac60c77231bTilo Mitra        {{>panel-form-css-source}}
84765788c559bfdead67172a79759ac60c77231bTilo Mitra    </style>
84765788c559bfdead67172a79759ac60c77231bTilo Mitra
84765788c559bfdead67172a79759ac60c77231bTilo Mitra
84765788c559bfdead67172a79759ac60c77231bTilo Mitra    {{>panel-form-html-source}}
84765788c559bfdead67172a79759ac60c77231bTilo Mitra
84765788c559bfdead67172a79759ac60c77231bTilo Mitra    <script type="text/javascript">
84765788c559bfdead67172a79759ac60c77231bTilo Mitra        {{>panel-form-js-source}}
84765788c559bfdead67172a79759ac60c77231bTilo Mitra    </script>
84765788c559bfdead67172a79759ac60c77231bTilo Mitra```