%META:TOPICINFO{author="ProjectContributor" date="1700242676" format="1.1" version="1"}%
%META:TOPICPARENT{name="JQueryPlugin"}%
---+!! %TOPIC%

%TOC%

---++ Summary
%JQPLUGINS{"ui::dialog"
  format="
    Homepage: $homepage <br />
    Author(s): $author <br />
    Version: $version
  "
}%

%STARTSECTION{"summary"}%
A dialog is a floating window that contains a title bar and a content area. The dialog window can be moved, resized and closed with the 'x' icon by default.

If the content length exceeds the maximum height, a scrollbar will automatically appear.

A bottom button bar and semi-transparent modal overlay layer are common options that can be added.

A call to =$(foo).dialog()= will initialize a dialog instance and will auto-open the dialog by default. If you want to reuse a dialog, the easiest way is to disable the "auto-open" option with: 
=$(foo).dialog({ autoOpen: false })= and open it with =$(foo).dialog('open')=. To close it, use =$(foo).dialog('close')=. 
%ENDSECTION{"summary"}%

---++ Usage

To load the library into the current wiki page, add this somewhere on the page:

<verbatim class="tml">
%JQREQUIRE{"ui::dialog"}%
</verbatim>

This will initialize the following css classes to build the dialog widgets:

   * =jqUIDialog=: dialog definition  
   * =jqUIDialogLink=: anchor pointing to a dialog 
   * =jqUIDialogButton=:  buttons to be added to the dialog 

Dialogs can be created inline or loaded on demand. The basic skeleton of a dialog definition looks like

<verbatim class="tml">
<div class="jqUIDialog" id="mydialog" title="Here's the title of the dialog" >

  Here goes the content.

  ...

  <a class="jqUIDialogButton jqUIDialogClose" data-icon="ui-icon-circle-check">%MAKETEXT{"Ok"}%</a>
  <a class="jqUIDialogButton jqUIDialogClose" data-icon="ui-icon-cancel">%MAKETEXT{"Cancel"}%</a>
</div>
</verbatim>

... which is activated by something like this:

<verbatim class="tml">
<a href="#mydialog" class="jqUIDialogLink">Open Dialog</a>
</verbatim>

A dialog can also be opened using <nop>JavaScript:

<verbatim class="js">
jQuery("#mydialog").dialog("open");
</verbatim>

To load a dialog asynchronously use a fully quallified hyperref as in

<verbatim class="tml">
<a href="http://...." class="jqUIDialogLink">Open Dialog</a>
</verbatim>

This will fetch the content of the dialog from the given url and add it to the page before opening it.
Once the dialog opend will the =jqUIDialogLink= element receive an "opened" event.

---++ Button Click Actions
When the button is clicked:
   * If the &lt;a&gt; element has the =jqUIDialogClose= class, then the dialog box will close.
   * If the &lt;a&gt; element has the =jqUIDialogDestroy= class, then the dialog box will closed and destroyed (removed from DOM).
   * If the &lt;a&gt; element has the =jqUIDialogSubmit= class, then a form defined in the dialog box will be submitted.
   * If the &lt;a&gt; element has an href attribute, then the specified page will be loaded.

---++ Parameters 

Parameters can be set using HTML5 data (=data-&lt;name>=)

| *Name* | *Description* | *Default* |
| width | width of the dialog | 300 |
| height | height of the dialog | auto |
| auto-open | boolean flag to either open the dialog when loaded (true) or delay opening it until the user says so (false) | false |
| draggable | boolean flag to make the dialog draggable | false |
| resizable | boolean flag to make the dialog resizable | false |
| close-on-escape | boolean flag to let the user close the dialog using the ESC key | false |
| destroy-on-close | boolean flag to destroy the dialog when it is closed | false |
| show | animation to be used to display the dialog | fade |
| hide | animation to be used to hide the dialog |  |
| modal | If set to true, the dialog will have modal behavior; other items on the page will be disabled (i.e. cannot be interacted with). Modal dialogs create an overlay below the dialog but above other page elements. | false |
| position | Specifies where the dialog should be displayed, e.g.  'center', 'left', 'right', 'top', 'bottom', [350,100], ['right','top'] | center |

See the plugin's homepage for more.

---++ Events

Events are fired on different occasions during the lifetime of a dialog. 

| *Name* | *Event* | *Description* | 
| create | dialogcreate | This event is triggered when dialog is created |
| open | dialogopen | This event is triggered when the dialog is opened. |
| beforeClose | dialogbeforeclose | This event is triggered when a dialog attempts to close. If the beforeClose event handler (callback function) returns false, the close will be prevented. |
| focus | dialogfocus | This event is triggered when the dialog gains focus. |
| dragStart | dialogdragstart | This event is triggered at the beginning of the dialog being dragged. |
| drag | dialogdrag | This event is triggered when the dialog is dragged. |
| dragStop | dialogdragstop | This event is triggered after the dialog has been dragged. |
| resizeStart | dialogresizestart | This event is triggered at the beginning of the dialog being resized. |
| resize | dialogresize | This event is triggered when the dialog is resized. |
| resizeStop | dialogresizestop | This event is triggered after the dialog has been resized. |
| close | dialogclose | This event is triggered when the dialog is closed. |

A custom event handler can either be registered when creating the dialog:

<verbatim class="tml">
<div class="jqUIDialog {open: functon() {myOpen.call(this);}}"></div>
</verbatim>

... or by binding it afterwards using a jQuery way like =$("selector").bind(event, function)=
to register an event to a dom node.

<verbatim class="js">
<script>
$("#mydialog").bind("dialogclose", function() {
  alert("got a dialogclose event");
});
</script>
</verbatim>

---++ Examples
%JQREQUIRE{"ui::dialog, ui::button"}%

---+++ Drop-down login dialog
<a href="#dialog" class="jqUIDialogLink">Login</a>

<div id="dialog" title="%MAKETEXT{"Login"}%" class="jqUIDialog" data-modal="true" data-position='{"at":"top"}' data-width="auto" data-show='{"effect":"drop", "direction":"up", "duration":"fast"}' data-hide='{"effect":"drop", "direction":"up", "duration":"fast"}'>
  <table class='foswikiLayoutTable'>
    <tr>
      <th>%MAKETEXT{"Name:"}%</th>
      <td><input type="text" size="50" name="name" class="foswikiInputField" /></td>
    </tr>
    <tr>
      <th>%MAKETEXT{"Password:"}%</th>
      <td><input type="password" size="50" name="password" class="foswikiInputField" /></td>
    </tr>
  </table>
  <a class="jqUIDialogButton jqUIDialogClose" data-icon="ui-icon-circle-check">%MAKETEXT{"Come on in"}%</a>
  <a class="jqUIDialogButton jqUIDialogClose" data-icon="ui-icon-cancel">%MAKETEXT{"Never mind"}%</a>
</div>

---+++ Dialog fetched asynchronously

<a href="%SCRIPTURL{"view"}%/%WEB%/%TOPIC%?skin=text&section=dialog" class="jqUIDialogLink">Open Dialog</a>

<verbatim class="tml">
%STARTSECTION{"dialog"}%
<div title="From Ajax call" class="jqUIDialog" data-modal="true" data-resizable="true" data-draggable="true" data-height="300" data-width="600">
  Lorem ipsum dolor sit amet, consectetur adipisicing elit, sed do eiusmod tempor incididunt ut labore
  et dolore magna aliqua. Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip
  ex ea commodo consequat.
  <a class="jqUIDialogButton jqUIDialogClose" data-icon="ui-icon-circle-check">%MAKETEXT{"Ok"}%</a>
  <a class="jqUIDialogButton jqUIDialogClose" data-icon="ui-icon-cancel">%MAKETEXT{"Cancel"}%</a>
</div>
%ENDSECTION{"dialog"}%
</verbatim>

See http://jqueryui.com/demos/dialog/ for more demos.
