====== Lightbox ======

The new Lightbox (version 3.0, aka the Delightbox) focuses on using the same paths as VuFind® would without Javascript. The general idea is that it emulates a seamless iframe with hooks and methods that allow more control. It uses ''data-'' attributes in the HTML for control.

====== Controlling the Lightbox ======

===== Universal Controls =====

These controls can be used on links or forms and they behave similarly.

**data-lightbox** - this creates a Lightbox launch-point from a link or form. Add this to a link if you want it to open a lightbox from the href attribute of the link. Add this to a form if you want the result of the submission to appear in a lightbox.

**data-lightbox-ignore** - all links that appear inside of the lightbox will be bound to the lightbox (like an iframe). This data attribute will cause clicking this link to escape the lightbox and navigate to a new page.

**data-lightbox-title** - override the default title of a page (the h2 at the top) with this string. Also works on submit buttons.

===== Link Controls =====

**data-lightbox-href** - used to specify a url you want the lightbox to follow instead of the regular href attached to the link.

**data-lightbox-post** - used to add post data to the request caused by the link. An example of this is the hierarchy tree which requires more data than normally encoded into the href.

===== Form Controls =====

**data-lightbox-onsubmit** - Specify a callback to be evaluated and run. Callbacks will be passed the event and all of the parsed form data (includes [[http://api.jquery.com/serialize/|json of form data]] and the button clicked). Returning true or false will pass that value to the form. True will submit the form without the lightbox. Returning false will prevent stop the default lightbox actions, in the case where you want to construct your own handler (see cart.js for examples). Returning anything else (though null is preferred) will allow the lightbox to submit the form and handle the output within itself.

**data-lightbox-onclose** - Specify a callback to be evaluated and run when the lightbox closes next.

:!: Prior to VuFind® 4.0, a callback could be either a function name in the global scope, or a block of Javascript code. VuFind® 4.0 and later, the callback MUST be either a function name in the global scope (e.g. myFunction) or a function name within the global VuFind® object (e.g. VuFind®.myFunction).

===== Script Controls =====

By default lightbox only runs inline scripts, or no scripts at all when it finds a success message and displays only the message (see below for more information).

Starting with VuFind® 9.1 it's possible to use the following attributes with script tags to indicate that they should be run in lightbox:

**data-lightbox-run** - Run the script when the lightbox displays normal content.

**data-lightbox-run="always"** - Run the script when the lightbox displays normal content or a success message.

====== Built-in Stops ======

The Lightbox is programmed to close under the following conditions:

===== Non-forced login =====
VuFind® refreshes the page after a login to update information and present new fields. The lightbox determines if a login has occureed using the following criteria:
  * the request came from a form
  * the form's action matches login/create account
  * the response to the form doesn't include an error
 
If the above is true and the form action is directly from UserLogin or catalogLogin, the page will refresh immediately. Else, the lightbox will automatically refresh after it is closed (allowing the current action to complete).

===== A success message is reached =====
When an .alert-success message is found, it is isolated in the lightbox, representing the end of a path. The lightbox can only be closed or escaped after this (by default).

===== 204 Status Code =====
If a form results in a 204 status code (No Content), it will immediately close the lightbox.

===== 205 Status Code =====
If a form results in a 205 status code (Reset Content), it will immediately refresh the page.

====== Transitioning ======

^ Old Lightbox ^ New Lightbox ^
| Lightbox.addFormCallback | data-lightbox-onsubmit |
| Lightbox.addFormHandler  | ::: |
| Lightbox.addCloseAction  | data-lightbox-onclose |
| Lightbox.addOpenAction   | $('#modal').on('shown.bs.modal', function() {}); |