{{>api-button}}

<style type="text/css">
{{>index-css}}
</style>

<div class="intro">
    <p>
        {{description}} The Panel-instance (descendant of <a href='http://gallerydocs.itsasbreuk.nl/gallery-itsapanel/'>Y.ITSAPanel</a>) is also capable of handling <a href='http://gallerydocs.itsasbreuk.nl/gallery-itsaformmodel/'>Y.ITSAFormModel</a>-instances, which gives you a great way to define html-forms.
        <img src="{{componentAssets}}/screenshot.png" alt="Screenshot of ITSAViewModelPanel">
    </p>
</div>

{{>getting-started}}

<h2>Description</h2>
    <p>
        Using Y.ITSAViewModelPanel is great to render Models on the page, where the panel keeps synced with the model. ITSAViewModelPanel uses internal Views, which will re-render automaticly whenever a new Model-instance is attached, or the template changes. To make use of the panel, at least two attributes need to be set:
        <ul>
            <li><code>model</code> the model or object that holds the data.</li>
            <li><code>template</code> the template which determines how the data will be rendered, either as a Y.Lang,sub - or Y.Template.Micro</li>
        </ul>
        There is another attribute as well: <code>footerTemplate</code>, which can be used for templating the same model.
    </p>
    <p>
        Under the hood, the body-section (and optionally the footer-section) have a <a href="http://gallerydocs.itsasbreuk.nl/gallery-itsaviewmodel/">Y.ITSAViewModel</a> instance which takes care of all the rendering-processes.
    </p>

<h2>Using the model-attribute</h2>
    <p>Here is a small example of how the code can be used:
    </p>
    ```
    YUI().use('gallery-itsaviewmodelpanel', function(Y) {
        var panel, artistobject, artisttemplate;

        artistobject = {
            artist: 'U2',
            country: 'Ireland'
        };

        artisttemplate = 'name: {artist}<br />'+
                         'country: {country}';

        panel = new Y.ITSAViewModelPanel({
            visible: true,
            centered: true,
            dragable: true,
            title: 'Artist:',
            footer: 'ready',
            model: artistobject,
            template: artisttemplate
        }).render();
    });
    ```
    <p>The model-attribute is responsible for the content that will be rendered inside the Panel. There are several ways to use this attribute:
    </p>
<h3>Attaching models v.s. objects</h3>
    <p>
        Both can be attached. The view is allmost fully responsive in both cases, which might be a reason to prefer plain objects (for performance reasons). However, there are some issues to keep in mind when using objects:
        <ul>
            <li>Changes to objectproperties will not make the panel to be updated. You need to call the <code>syncUI()</code> manually in order to do so.</li>
            <li>Objects cannot create form-elements: you need <a href="http://gallerydocs.itsasbreuk.nl/gallery-itsaformmodel/">Y.ITSAFormModel</a> to do so.</li>
        </ul>
    </p>

<h3>Attaching Y.ITSAFormModel</h3>
    <p>
        When a Y.ITSAFormModel-instance is attached to the model-attribute, you can make advantage of the UI-elements defined by <a href="http://gallerydocs.itsasbreuk.nl/gallery-itsaformmodel/">Y.ITSAFormModel</a>. Whether the panel renders the UI-elements or not, depends on the attribute <code>editable</code>.
    </p>

<h3>Attaching plain text</h3>
    <p>
        Y.ITSAViewModelPanel makes it is posible to add plain text (string) to the model-attribute. This leads to 'just' rendering the text inside the view-container ignoring the template. However, in such cases, you probably want to use <a href="http://gallerydocs.itsasbreuk.nl/gallery-itsapanel/">Y.ITSAPanel</a> which is less weight.
    </p>
<h2>Creating forms</h2>
    <p>
        Forms can be created by using a <a href="http://gallerydocs.itsasbreuk.nl/gallery-itsaformmodel/">Y.ITSAFormModel</a>-instance as 'model' and setting 'editable' true. By doing this, you create UI-elements for all the models attributes, just by reffering to the attribute in the template.
    </p>
    <p>
        It is common use, to use the attribute <code>template</code> for rendering model's attributes, while <code>templateFooter</code> is set up to hold the buttons.
    </p>
    <p>
         The formelements have the focusmanager active out of the box which makes <code>tabbing</code> inside the container posible as soon the container has focus. The UI-elements even can get focus using hotkeys, when specified (see the examples). When creating a template with formelements, then the view-container ought to be a <code>form-tag</code>, no need to define this inside the template. If neither the container, nor the template has a form-tag, then <a href="http://gallerydocs.itsasbreuk.nl/gallery-itsaviewmodel/">Y.ITSAViewModel</a> will create a formtag automaticly inside the container.
    </p>
<h3>Using formbuttons</h3>
    <p>
        You can use a lot of handy predefined formbuttons right out of the box (see below). It is important to know that <i>clicking a button</i> normally leads to hide the panel. This behaviour is set by the attribute <code>hideOnBtn</code> which default true. However, there are 2 buttons that will overrule this behaviour:
        <ul>
            <li><code>load</code> --> defined by the attribute 'noHideOnLoad' which defaults true</li>
            <li><code>reset</code> --> defined by the attribute 'noHideOnReset' which defaults true</li>
        <ul>
        Should you need these buttons to hide the panel, just set 'noHideOnLoad' or 'noHideOnLoad' false.
    </p>

<h4>Standard available formbuttons</h4>
    <p>Because the model exists of its attributes (no buttons), this module comes with several button-definition 'out of the box'. These can be reffered to by templating, just as all attributes. All buttons have their own defaultfunction, so they work right away. As said before, it is common use, to use the attribute <code>templateFooter</code> for holding the buttons. Below is the list of all buttons that are available:
    </p>
    <ul>
       <li>btn_abort</li>
       <li>btn_cancel</li>
       <li>btn_close</li>
       <li>btn_destroy</li>
       <li>btn_ignore</li>
       <li>btn_load</li>
       <li>btn_no</li>
       <li>btn_ok</li>
       <li>btn_remove</li>
       <li>btn_reset</li>
       <li>btn_retry</li>
       <li>btn_save</li>
       <li>btn_submit</li>
       <li>btn_yes</li>
       <li>imgbtn_abort</li>
       <li>imgbtn_cancel</li>
       <li>imgbtn_close</li>
       <li>imgbtn_destroy</li>
       <li>imgbtn_ignore</li>
       <li>imgbtn_load</li>
       <li>imgbtn_no</li>
       <li>imgbtn_ok</li>
       <li>imgbtn_remove</li>
       <li>imgbtn_reset</li>
       <li>imgbtn_retry</li>
       <li>imgbtn_save</li>
       <li>imgbtn_submit</li>
       <li>imgbtn_yes</li>
       <li>spinbtn_load</li>
       <li>spinbtn_remove</li>
       <li>spinbtn_save</li>
       <li>spinbtn_submit</li>
    </ul>
    <p>
        The buttons that start with <code>imgbtn</code> have an imageicon. The buttons that start with <code>spinbtn</code> have an imageicon that starts spinning during its defaultfunction. There are 4 buttons that have this fascility, because these are calling an asynchronious function through the model's synclayer. Here is a small example of how the code can be used:
    </p>
    ```
    YUI().use('gallery-itsaviewmodelpanel', 'gallery-itsaformmodel', function(Y) {
        var panel, artistobject, artisttemplate;

        Y.ArtistModel = Y.Base.create('formmodel', Y.ITSAFormModel, [], {
            sync: function (action, options, callback) {
                switch (action) {
                  case 'submit':
                    ...
                    return;
                  default:
                    callback('Invalid action');
                }
            }
        }, {
            ATTRS: {
                name: {
                    formtype: 'text',
                    formconfig: {
                        label: 'Artist',
                        placeholder: 'artist',
                        required: true
                    }
                },
                country: {
                    country: 'text',
                    formconfig: {
                        label: 'Country',
                        placeholder: 'country',
                        required: true,
                        initialfocus: true
                    }
                }
            }
        });

        artist = new Y.ArtistModel({
            name: 'U2',
            country: 'Ireland'
        });

        artisttemplate = 'name: {artist}<br />'+
                         'country: {country}<br />'+
                         '{spinbtn_save}';

        panel = new Y.ITSAViewModelPanel({
            visible: true,
            centered: true,
            dragable: true,
            title: 'Artist:',
            model: artistobject,
            template: artisttemplate
        }).render();

    });
    ```

<h4>Custom formbuttons</h4>
    <p>
        In case you need normal buttons that are not in the list -and which need to have their own subscribers- you can define them with <code>addCustomBtn()</code>. The first param will define the property-name, f.i. 'btn_alert' will generate a button which the template can access with {btn_allert}. See the <a href="http://gallerydocs.itsasbreuk.nl/gallery-itsaviewmodel/">Y.ITSAViewModel</a> for examples.
    </p>

<h4>Changing standard formbuttons</h4>
    <p>
        While custombuttons can be defined exactly to your whishes, the standardbuttons are already predefined. However, you can change the <code>label</code> and <code>hotkey</code> of these buttons by using:
        <ul>
            <li><code>setButtonLabel()</code></li>
            <li><code>setHotKey()</code></li>
        </ul>
        See the Y.ITSAViewModel for examples.
    </p>

<h3>Internationalized buttonlabels</h3>
    <p>
        The standardbuttons have Internationalised labels. While this is great, you must also be aware of:
    </p>
        <ul>
            <li>When redefine the labels, the Internationalization is gone. If you want to keep the labels Internationalized, you should apply an Internationlized label yourself.</li>
            <li>When defining hotkeys, the labels will differ for several languages. This means you might want to set the <code>s</code>-character as the hotkey for saving, while other languages have a different name. <code>Save</code> will appear as <code>Opslaan</code> in The Netherlands. To handle this issue, you can choose to supply an object as argument to the <code>setHotKey()</code> method instead of a character-hotkey. See the API.</li>
        </ul>
    <p>At this moment the following languages are supported:</p>
    <ul>
        <li><code>ar</code> (Arabic)</li>
        <li><code>bg</code> (Bulgarian)</li>
        <li><code>bs</code> (Bosnian)</li>
        <li><code>cs</code> (Czech)</li>
        <li><code>da</code> (Danish)</li>
        <li><code>de</code> (German)</li>
        <li><code>en</code> (English)</li>
        <li><code>es</code> (Spanish)</li>
        <li><code>fa</code> (Perian)</li>
        <li><code>fi</code> (Finnish)</li>
        <li><code>fr</code> (French)</li>
        <li><code>he</code> (Hebrew)</li>
        <li><code>hi</code> (Hindi)</li>
        <li><code>hr</code> (Croatian)</li>
        <li><code>hu</code> (Hungarian)</li>
        <li><code>it</code> (Italian)</li>
        <li><code>ja</code> (Japanese)</li>
        <li><code>nb</code> (Norwegian)</li>
        <li><code>nl</code> (Dutch)</li>
        <li><code>pl</code> (Polish)</li>
        <li><code>pt</code> (Portugese)</li>
        <li><code>ru</code> (Russian)</li>
        <li><code>sk</code> (Slovak)</li>
        <li><code>sr</code> (Serbian)</li>
        <li><code>sv</code> (Swedish)</li>
        <li><code>uk</code> (Ukrainian)</li>
        <li><code>zh</code> (Chinese)</li>
    </ul>

<h3>Validation</h3>
    <p>
        Validation is done through <a href="http://gallerydocs.itsasbreuk.nl/gallery-itsaformmodel/">Y.ITSAFormModel</a>, which supplies very nice and easy validationmethods. When validation fails, Y.ITSAViewModel will take care of refocussing to the first item whose validation failed.
    </p>

<h2>About templating</h2>
    <p>
        When using Y.ITSAFormModel as 'model' and 'editable' is set true, be aware that all property-values are <u>html-strings</u>. Should you templating with micro-templates, to render the UI-elements you need to use
        ```html
        <%== data.someattribute %>
        ```
        instead of
        ```html
        <%= data.someattribute %>
        ```
        If you need to access the original attribute-value, use the underscore-reference:
        ```html
        '<% if (data._activated===false) { %>system down<% } else { %>system running<% } %>'+
        ```
    </p>

<h2>Adding statusbar</h2>
    <p>
        By setting the attribute <code>statusBar</code> true, you create a statusbar inside the ViewModelPanel. See <a href="http://gallerydocs.itsasbreuk.nl/gallery-itsastatusbar/">Y.ITSAStatusbar</a>. The statusbar is targeted by the bounded model automaticly. You can also target specific messages to this statusbar by using targeting the messages to the instance, f.e.: <code>Y.alert('oops, something went wrong', {target: yourViewModelPanel});</code>.
    </p>

<h2>Styling</h2>
    <p>
        By default, the Y.ITSAViewModelPanel comes with its own style supplied by <a href="http://gallerydocs.itsasbreuk.nl/gallery-itsapanel/">Y.ITSAPanel</a>: see that module how to customize the style of the panel. When you need to style form-elements, then it is higly recommended to include <a href="http://purecss.io/">Purecss</a>.
    </p>
<h3>Purecss compatable</h3>
  <p>
      Y.ITSAFormPanel and the formelements of Y.ITSAForm are full <a href="http://purecss.io/">Purecss</a>-compatable!
  </p>

<h2>Memory management</h2>
    <p>
        When re-render a view that holds UI-elements, widgets might be re-rendered. Y.ITSAViewModelPanel uses <a href="http://gallerydocs.itsasbreuk.nl/gallery-itsaviewmodel/">Y.ITSAViewModel</a> under the hood, which automaticly takes care of destroying the widgets that are no longer needed, or refreshed.
    </p>

<h2>Y.ITSAViewModelPanel v.s. Y.ITSADialog</h2>
    <p>
        Y.ITSAViewModelPanel looks quite the same as <a href="http://gallerydocs.itsasbreuk.nl/gallery-itsadialog/">Y.ITSADialog</a>. Actually, Y.ITSADialog uses Y.ITSAViewModelPanel under the hood. So when to choose one above the other:
    </p>

    <h3>Advantages Y.ITSADialog</h3>
        <ul>
            <li>Messages are queued. So the user will see only 1 message at the time. And when there appears an warn- or error-message during your custom message, your messaga will be temporarely replaced</li>
            <li>You always get the userinteraction in return (the Promise-value)</li>
        </ul>

    <h3>Advantages Y.ITSAViewModelPanel</h3>
        <ul>
            <li>Easier to setup, you just attach a model</li>
            <li>Can handle Y.ITSAFormModel-types, you don't need to create an Y.ITSAMessage</li>
            <li>The model-instance remains, while Y.ITSAMessages are cleaned up by Y.ITSADialog</li>
            <li>You could setup multiple panels at the same time</li>
        </ul>

    <h3>General best practice</h3>
        <p>
            In general, when you want <code>one time modal user-interaction</code> (that is: an 'editable' panel were the model isn't needed for something else), you better create an Y.ITSAMessage and use Y.ITSADialog. In all other situations, use Y.ITSAViewModelPanel.
        </p>

<h2>Licence</h2>
    Copyright (c) 2013 <a href="http://itsasbreuk.nl">Its Asbreuk</a><br />
    Copyright (c) 2013 <a href="http://developer.yahoo.com/yui/license.html">YUI BSD License</a>