Dialog

Creates a modal Dialog on the client side (of sorts). This component may prove useful for cutting down on typical CRUD operations where you normally have to navigate to a lot of seperate pages to do things like "edit" / "view" / or "add" something. Why make your users navigate all over the place when they can do it right there? :)

Also note that this particular component comes with two very useful methods that you can invoke in java code to hide and show the Dialog. They are aptly named hide() and show().

Warning:

There are quite a few gotchas and special conditions you need to be aware of when using this component. You can find them outlined as well as solutions to common problems at the bottom of this document.

Dialog Example

This component needs a Body component and a Shell or ScriptIncludes component to work.

See also: org.apache.tapestry.dojo.html.Dialog

Parameters

Name Type Required Default Description
hidden boolean no true Whether or not the Dialog should be hidden by default. (Which is what you want in most cases.)
backgroundColor String no literal:black The html style color to give the background of the dialog. The color given can be a literal color name or hex string such as #efefef.
opacity float no 0.4 Controls how opaque the background is. This parameter is given in the form of a percent, so valid values would range from 0.1 - 1.
followScroll boolean no true Whether ot not the dialog should follow the scroll remaining centered on the browser viewport.
closeOnBackgroundClick boolean no false Whether ot not the dialog should close when clicking on the background.
blockDuration int no 0 Number of seconds for which the user cannot dismiss the dialog.
lifeTime int no 0 The number of seconds the dialog will be displayed before automatically disappearing.
toggle String no literal:fade The type of effect to be used on dialog show/hide. Possible values are: litera:plain, literal:wipe, literal:fade, literal:explode
toggleDuration int no 150 The number of milliseconds for the toggle effect to complete.

Body: allowed

Informal parameters: allowed

Reserved parameters: none

Gotchas

There are a few things that most poeple will need to keep in mind when using this component/client side control.
  • Dialog display flickering - In the typical situation of defining a simple html template definition of a Dialog - such as in: 
    <div jwcid="testDialog@Dialog" hidden="ognl:dialogHidden" >
    <p>Sample dialog display</p>
</div>

    With the definition given above you will inevitably get a flickering effect of the content within the dialog being breifly displayed before being hidden by the client side widget control. This is simply because your html content is rendered in the browser before the client side widget has had a chance to hide it. To be sure that you don't have flickering on your dialog content simply define a style="display:none" attribute on your Dialog tag: 

    <div jwcid="testDialog@Dialog" hidden="ognl:dialogHidden" style="display:none;">
    <p>Sample dialog display</p>
</div>
  • Dialog content background color - By default the content you display within the dialog will have an opaque background because that is the background of the dialog itself. If you don't want this (the majoriy won't..) you should define a background color and style accordingly for your content. It is often easier to define a single css class definition for dialog content and apply it to a single outer node within the dialog like this: 
    ..
.dialog { background-color: white; width: 400px; height: 300px; }
...

<div jwcid="testDialog@Dialog" hidden="ognl:dialogHidden" style="display:none;">
    <p class="dialog">
        Sample dialog display
    </p>
</div>
  • Updating Dialog in AJAX requests - This is by far the biggest gotcha, so you'll want to read this section carefully. Because of the way the client side widget displays/manipulates the Dialog the ultimate position your dialog html node in the overall document will not be the same as how it is initially rendered by Tapestry. The short of it is that the client side takes your dialog html node and moves it to the very bottom of the document - regardless of what is surrounding it or any other careful semantics you have setup. ...So given a sample html template definition looking like this: 
                     
<body>

  <div id="content">
     <p>
        <div jwcid="testDialog@Dialog" hidden="ognl:dialogHidden" style="display:none;">
            <p>Sample dialog display</p>
        </div>
    </p>
  </div>

</body>

    ..the actual placement of your dialog node will actually be more like:

    <body>

  <div id="content">
     <p>

    </p>
  </div>

<div id="testDialog" style="display:none;">
  <p>Sample dialog display</p>
</div>
</body>

    This can cause endless hours of frustration if you don't know about its behaviour - and can get even worse with certain ajax updating semantics. The key things to remember with doing ajax updates involving dialogs are:

    • Only update the dialog directly or things contained within it.

      This means that you can't do things like: 

      <a jwcid="@DirectLink" listener="listener:showDialog" updateComponents="dialogUpdateArea">Show Dialog</a>

<div jwcid="dialogUpdateArea@Any">
<div jwcid="testDialog@Dialog" hidden="ognl:dialogHidden" style="display:none;">
    <p class="dialog">
        Sample dialog display
    </p>
</div>
</div>

      The above example would have questionable results because the actual client side dom node of the dialog will be detached and not actually be a child of the dialogUpdateArea Any component you are trying to update. The good news is that updating a Dialog directly or children within it should work fine, so rewriting the example above to the more correct version will yield better results: 

      <a jwcid="@DirectLink" listener="listener:showDialog" updateComponents="testDialog">Show Dialog</a>

<div jwcid="testDialog@Dialog" hidden="ognl:dialogHidden" style="display:none;">
    <p class="dialog">
        Sample dialog display
    </p>
</div>
    • Don't wrap portions of a Form.

      Because the Dialog client dom node is always detached you are almost assured to have problems if you try and take a small portion of a form and wrap it within a dialog. The form input controls will be moved to the bottom of your document - outside the scope of the containing form - along with all the other content the Dialog normally moves. This will likely result in your form breaking and / or just not submitting the input values contained within the dialog.

      For this situation the only real answer is that you need to break the form up in to two separate forms - one that you will nest within the Dialog itself and the other being your main outer form.