Documentation

Inline dialog

Code snippetsDesign guidelines

Summary

The inline dialog is a wrapper for secondary content/controls to be displayed on user request. Consider this component as displayed in context to the triggering control with the dialog overlaying the page content.

A inline dialog should be preferred over a modal dialog when a connection between the action has a clear benefit versus having a lower user focus.

Status

API status:general
Included in AUI core?Yes. You do not need to explicitly require the web resource key.
Web resource key:com.atlassian.auiplugin:ajs
Experimental since:1.0

Examples

Show inline dialog

Code

HTML and JavaScript

The HTML component is simply a trigger with an ID, which can be used by Inline Dialog's JavaScript.

<a href="#" id="inlineDialog">Inline dialog</a>

To inject content from a URL:

AJS.InlineDialog(AJS.$("#inlineDialog"), "myDialog", "path/to/your/content.html");

This binds an InlineDialog to the trigger element with id="inlineDialog". Clicking the trigger element displays a container element with id="inline-dialog-myDialog" and sets its innerHTML value to the content fetched from "dialog-content.html". NOTE: "content.html" could have something like the following HTML: <div id="dialog-content"><h2>AUI Inline Dialog</h2></div>

To inject content directly with JavaScript:

AJS.InlineDialog(AJS.$("#inlineDialog"), "myDialog",
    function(content, trigger, showPopup) {
        content.css({"padding":"20px"}).html('<h2>Inline dialog</h2><p>Content.</p>');
        showPopup();
        return false;
    }
);

Primary instantiation function

AUI Inline Dialog uses a function to attach and inline-dialog to a DOM element.


AJS.InlineDialog(items, identifier, url, options);
            

Parameters

  • items - The elements that will trigger the inline-dialog, use a jQuery Selector to select items.
  • identifier - A unique identifier for the inline-dialog.
  • url - The URL of the dialog contents
  • options - A number of different options may be passed in as an associative array, options explained below.

Default behavior

  • If no options are changed the Inline Dialog will be default display below the trigger aligned to the left of the trigger.
  • If the dialog is drawn offscreen to the right it will be re-positioned such that it is on-screen.
  • If the dialog is drawn off-screen to the bottom it will be displayed above the trigger with the arrow flipped.
  • In all cases the arrow will be drawn in the middle of the trigger.

Advanced usage

Passing a function instead of a URL String

You can pass a function into the url parameter of inlineDialog instead of a url string. Your function must be:


function(contents, trigger, showPopup);
            

Where:

  • Contents is the div element that will contain your custom content
  • trigger is the element of your dialog trigger
  • showPopup is the function from within InlineDialog that shows the popup (your function should call this at the end)

This function will override the contents loading section in Inline-Dialog.

Quick example:


AJS.InlineDialog(AJS.$("#inlineDialog"), "myDialog", function(content, trigger, showPopup) { /* do stuff */ });
            

Options

To pass options into the InlineDialog function you must use an associative array:


AJS.InlineDialog(AJS.$("#inlineDialog"), "myDialog", "dialog-content.html", {optionName: optionValue});
            

The following options can be passed in as an object in the fourth parameter of an Inline Dialog instantiation.

AJS.InlineDialog(
    AJS.$("#inlineDialog"), 
    "myDialog", 
    "dialog-content.html", 
    {
    onHover: true,
    noBind true,
    fadeTime: 500,
    initCallback: function(){alert("Hello World");
    }
});
OptionDetailsExamples
onHover

determines whether the inline-Dialog will show on a mouseOver or mouseClick of the trigger.
Options: true/false
Default: false

AJS.InlineDialog(
    AJS.$("#inlineDialog"), 
    "myDialog", 
    "dialog-content.html", 
    {
        onHover:true
    }
);
closeOnTriggerClick

determines if the the inline dialog is closed when its trigger is clicked
Options: true/false
Default: false

AJS.InlineDialog(
    AJS.$("#inlineDialog"),
    "myDialog",
    "dialog-content.html",
    {
    closeOnTriggerClick: true
    }
);
noBind

determines if the inline-Dialog will bind the event-handler to the trigger event, use this option if you wish to bind the event handler programatically at a different point. If true then useLiveEvents is disabled. If true then the items argument to the inline dialog constructor can be the empty jQuery collection, i.e., AJS.$().
Options: true/false
Default: false

AJS.InlineDialog(
    AJS.$("#inlineDialog"), 
    "myDialog", 
    "dialog-content.html", 
    {
    noBind: true
    }
);
fadeTime

determines the fade in and fade out duration of the dialog in milliseconds.
Accepts a numerical value.
Default: 100

AJS.InlineDialog(
    AJS.$("#inlineDialog"), 
    "myDialog", 
    "dialog-content.html", 
    {
    fadeTime: 200
    }
);
hideDelay

determines how long (in milliseconds) the inline-dialog will stay visible for until it is hidden (if no other trigger for hiding the dialog is fired) if null is passed auto-hide is disabled for this inline-Dialog
Accepts a Numerical value.
Default: 10000 (or null)

AJS.InlineDialog(
    AJS.$("#inlineDialog"), 
    "myDialog", 
    "dialog-content.html", 
    {
    hideDelay: 3000
    }
);
showDelay

determines how long in milliseconds after a show trigger is fired (such as a trigger click) until the dialog is shown.
Accepts a Numerical Value
Default: 0

AJS.InlineDialog(
    AJS.$("#inlineDialog"), 
    "myDialog", 
    "dialog-content.html", 
    {
    showDelay: 200
    }
);
width

Sets how wide the inline-dialog is in pixels.
Accepts a Numerical value
Default: 300

AJS.InlineDialog(
    AJS.$("#inlineDialog"), 
    "myDialog", 
    "dialog-content.html", 
    {
    width: 400
    }
);
offsetX

Sets an offset distance of the inline-dialog from the trigger element along the x-axis in pixels
Accepts a Numerical Value or a function that takes the same arguments as calculatePositions and returns a numeric value.
Default: 0 for 'n' and 's' gravity; 10 for 'w' gravity

AJS.InlineDialog(
    AJS.$("#inlineDialog"), 
    "myDialog", 
    "dialog-content.html", 
    {
    offsetX: 30
    }
);
offsetY

Sets an offset distance of the inline-dialog from the trigger element along the y-axis in pixels
Accepts a Numerical Value or a function that takes the same arguments as calculatePositions and returns a numeric value.
Default: 10 for 'n' and 's' gravity; 0 for 'w' gravity

AJS.InlineDialog(
    AJS.$("#inlineDialog"), 
    "myDialog", 
    "dialog-content.html", 
    {
    offsetY: 30
    }
);
container

The element in which the dialog itself will be appended.
Accepts a String or an element.
Default: "body"

AJS.InlineDialog(
    AJS.$("#inlineDialog"), 
    "myDialog", 
    "dialog-content.html", 
    {
    container: "head"
    }
);
cacheContent

determines if the contents of the dialog are cached. If set to false the contents will be reloaded everytime the dialog is shown.
Options: true/false
Default: true

AJS.InlineDialog(
    AJS.$("#inlineDialog"), 
    "myDialog", 
    "dialog-content.html", 
    {
    cacheContent: false
    }
);
hideCallback

a function that will be called after the popup has faded out.
Accepts a javascript function
Default: function(){}

AJS.InlineDialog(
    AJS.$("#inlineDialog"), 
    "myDialog", 
    "dialog-content.html", 
    {
    hideCallback: function(){alert("Hello World");}
    }
);
initCallback

a function that will be called after the popup contents have been loaded
Accepts a javascript function
Default: function(){}

AJS.InlineDialog(
    AJS.$("#inlineDialog"), 
    "myDialog", 
    "dialog-content.html", 
    {
    initCallback: function(){alert("Hello World");}
    }
);
isRelativeToMouse

determines if the dialog should be shown relative to where the mouse is at the time of the event trigger (normally a click) if set to false the dialog will show aligned to the left of the trigger with the arrow showing at the center.
Options: true/false
Default: false

AJS.InlineDialog(
    AJS.$("#inlineDialog"), 
    "myDialog", 
    "dialog-content.html", 
    {
    isRelativeToMouse:true
    }
);
closeOthers

determines if all other dialogs on the screen are closed when this one is opened
Options: true/false
Default: true

AJS.InlineDialog(
    AJS.$("#inlineDialog"), 
    "myDialog", 
    "dialog-content.html", 
    {closeOthers:true}
);
responseHandler

a function that determines how the content retrieval response is handled, the default assumes that the data returned is html. The implemented function must handle the three variables: data, status, xhr and at the end return html
Accepts a javascript Function
Default: function(data, status, xhr) {
return data;
}

AJS.InlineDialog(
    AJS.$("#inlineDialog"), 
    "myDialog", 
    "dialog-content.html", 
    { 
    responseHandler: 
        function(data, status, xhr) { 
            return parseHTML(data);
        }
    }
);
onTop Deprecated as of 5.5

determines if the dialog should be shown above the trigger or not. If this option is true but there is insufficient room above the trigger the inline-dialog will be flipped to display below it.
Deprecated in favour of gravity.
Options: true/false
Default: false

AJS.InlineDialog(
    AJS.$("#inlineDialog"), 
    "myDialog", 
    "dialog-content.html", 
    {onTop:true}
);
gravity

As of 5.5: The preferred direction in which the inline dialog's arrow points, e.g., 'n' makes the inline dialog's arrow point up (with the inline dialog below the trigger). When there isn't enough room to display the inline dialog with its preferred gravity it automatically flips orientation.

Options: 'n', 's', or 'w'
Default: 'n'

useLiveEvents

AUI supports jQuery live events. If you choose this option, AUI will bind all events on the page to the HTML body element instead of to each individual element. This means that your events can be bound to all current elements and to elements that do not yet exist. You no longer need to rebind everything on an Ajax load. This is essential on a page which has, for example, a number of user avatars that react on hover. Binding can cause a performance problem when there is a large number of such elements. Disabled if noBind is true.
Options: true/false
Default: false

See AUI 3.1 Release Notes.

displayShadow

Instructs the InlineDialog on rendering the shadow.
Options: true/false
Default: true

See AUI 3.5 Release Notes

getArrowPath Deprecated as of 5.1

A function that returns a string representation of an SVG path that will represent the arrow being drawn. This function takes one argument, positions which is the return value of the calculatePositions method.

AJS.InlineDialog(AJS.$('#inlineDialog'),
    'myDialog',
    'dialog-content.html',
    {getArrowPath: function (positions) {
        return positions.displayAbove ?
            'M 0 0 L 0 0 0 8 8 8 8 0 0 0' :
            'M 0 0 L 0 0 0 8 8 8 8 0 0 0';
    }}
);
getArrowAttributes Deprecated as of 5.1

Returns an object which has attributes to be applied to the arrow svg element.

AJS.InlineDialog(AJS.$('#inlineDialog'),
                     'myDialog',
                     'dialog-content.html',
    {getArrowAttributes: function() {
            return {
                 fill: '#ff0000',
                 stroke: '#000000'
            };
        }
    }
);
                            
addActiveClass

Instructs the InlineDialog to add the 'active' class.
Options: true/false
Default: true

AJS.InlineDialog(AJS.$('#inlineDialog'),
    'myDialog',
    'dialog-content.html',
    {addActiveClass: false}
);
calculatePositions

Allows the consumer of InlineDialog to manually determine or calculate the position that the InlineDialog should be drawn at.

AJS.InlineDialog(AJS.$('#inlineDialog'),
    'myDialog',
    'dialog-content.html',
    {calculatePositions: function getPosition(popup, targetPosition, mousePosition, opts){
         return {
             displayAbove: true,
             popupCss: {
                 left: mousePosition.x,
                 top: mousePosition.y+20,
                 right: mousePosition.y+100
             },
             arrowCss: {
                 left: 20,
                 top: 0,
                 right: 20
             }
         };
    }}
);
arrowOffsetX

As of 5.0; arrowOffsetX defines an X axis offset in pixels for placement of the arrow (default is zero).

Accepts a Numerical Value or a function that takes the same arguments as calculatePositions and returns a numeric value.

AJS.InlineDialog(AJS.$('#inlineDialog'),
    'myDialog',
    'dialog-content.html',
    {arrowOffsetX: 50}
);
arrowOffsetY

As of 5.5; arrowOffsetY defines a Y axis offset in pixels for placement of the arrow (default is zero).

Accepts a Numerical Value or a function that takes the same arguments as calculatePositions and returns a numeric value.

AJS.InlineDialog(AJS.$('#inlineDialog'),
    'myDialog',
    'dialog-content.html',
    {arrowOffsetY: 50}
);
persistentAs of 5.1: if persistent: true the inline dialog can only be dismissed programatically by calling .hide(). This option, ignores the 'closeOthers' option. (inline-dialogs with closeOthers set to true will not close this one) and the hideDelay option.
AJS.InlineDialog(
    AJS.$("#inlineDialog"), 
    "myDialog", 
    "dialog-content.html", 
    {persistent: true}
);

JavaScript functions

The following functions have been available since AUI 3.0. They can be called on the DOM object returned by the Inline Dialog constructer. You can call these by assigning the constructor to a DOM object such as:


var inlineDialog1 = AJS.InlineDialog(AJS.$("#inlineDialog"), "myDialog", "dialog-content.html");
            

...after that you can call them directly from the object (as per the table below).

FunctionDetailsExample
show(e, trigger)Shows the Inline Dialog. As of 5.5: Accepts two optional parameters: an event, e, and an element, trigger. If the noBind option is true (when binding your own event handlers) and the items collection passed to the inline dialog constructor is empty, pass in the event object from your event handler as e and, optionally, pass your desired trigger element as trigger. If e is provided but trigger is not, e.target is used as the trigger element.inlineDialog1.show();
hide()Hides the Inline DialoginlineDialog1.hide();
refresh()Redraws the inline-dialog. Use this function when you need to add contents to the inline dialog and you need it to be redrawn after your contents are inserted.inlineDialog1.refresh();