About Features Downloads Getting Started Documentation Events Support GitHub

Love VuFind®? Consider becoming a financial supporter. Your support helps build a better VuFind®!

Site Tools


Warning: This page has not been updated in over over a year and may be outdated or deprecated.
development:architecture:lightbox

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.

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 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() {});
development/architecture/lightbox.txt · Last modified: 2023/06/07 12:19 by demiankatz