# apostrophe-modal (browser)

# Inherits from: apostrophe-context

apostrophe-modal is a base class for modal dialog boxes. Define a new type that extends apostrophe-modal, set the source option to the name of a server-side route that outputs suitable HTML, extend the beforeShow method to add custom event handlers and dynamic content, and extend saveContent to take action when the save button is clicked.

Where the markup comes from

The source option is combined with the action option to arrive at the URL for fetching the modal's markup:


action is usually pushed from the server side via pushBrowserCall, so that the server-side code can just implement its route via self.route. The route is a POST route. Any data present in the body option is passed as POST parameters.


The apostrophe-tags, apostrophe-widgets and apostrophe-pieces modules provide excellent examples of how modals are defined, created and populated.

An alternative to "save and cancel"

An alternative approach: if a single save operation doesn't make sense, you can implement buttons that perform actions immediately and use a "cancel" button labeled Done to close the modal.

When a modal creates another modal, they "stack," unless the new modal has the transition: slide option and the top modal already on the stack has the apos-modal-slideable CSS class, in which case the new modal "slides in" creating a breadcrumb trail.

Subclasses of apostrophe-modal can also provide a $view jQuery reference, in which case the new "modal" actually populates that div directly and doesn't actually block the page or display in its own modal dialog box. This is convenient when you wish to build up modals by composition.

# Methods

# getSource(callback)

Fetch rendered HTML to populate self.$el with the actual content of the modal. The HTML is fetched from:

self.options.action + '/' + self.options.source

Via a POST request.

If a self.body object exists it is passed to the server side as POST parameters.

Invoked for you as the first step of afterConstruct.

# enableGlobalEventsOnce()

Enables support for the escape key and click-outside-to-cancel behaviors. The handlers are installed on first use and then reused by any nested modals. Invoked for you as part of afterConstruct.

# disableGlobalEvents()

Removes the global event handlers for ESC and click-outside- to-close. Invoked when the last open modal closes.

# enableButtonEvents()

Add event handlers for the cancel and save buttons, [data-apos-cancel] and [data-apos-save]. If the save also has the [data-next] attribute, the self.next() method is invoked with no arguments after the normal save-and-close operation. This is meant to allow "save and create another" behavior, which is popular with experienced users.

In this base class self.next() is not implemented.

# enableBreadcrumbEvents()

Enable clicks on the breadcrumb trail [data-modal-breadcrumb], which is present when "stacked" modals "slide in" instead by setting the transition option to slide when constructing the modal. The breadcrumb trail can be used to back up to any point in the series of slides. All modals after that point have their cancel operation invoked, starting with the last/newest modal.

# captureTitle()

Fetches the title of the modal from the element with [data-modal-title] and records it in self.title. Called as part of afterConstruct.

# captureControls()

Locates the div that contains the controls for saving, cancelling, and other top-level operations on this modal and stores a jQuery reference to it in self.$controls. Part of the implementation of the slide transition, which moves these controls to a shared div outside of the individual slide modals for layout reasons.

# captureFilters()

Locates the div that contains the filters for this modal and stores a jQuery reference to it in self.$modalFilters. Part of the implementation of the slide transition, which moves these filters to a shared div outside of the individual slide modals for layout reasons. The name modalFilters avoids a bc break with the pieces manager modal.

# captureInstructions()

Locates the div that contains the instructions (the explanatory caption) for the modal and stores a jQuery reference to it in self.$instructions. Part of the implementation of the slide transition, which moves these controls to a shared div outside of the individual slide modals for layout reasons.

# resetEl()

Part of the implementation of the slide transition. When sliding a new modal in, self.$el is reset to the [data-modal-content] element within the modal, so that event handlers relying on self.$el work reasonably after the original modal div is diced up to move the controls, filters and instructions to one area of the slide container and the content div to another.

If this modal does not have the { transition: 'slide' } option, or there is no modal already open with the apos-modal-slideable CSS class, this method does nothing.

The original div is captured in self.$shell, which is currently used only as a test for whether the modal is a slide.

# getSlideableAncestorEl()

Part of the implementation of the slide transition. Checks the most recent non-sliding modal in the stack to see whether it has the apos-modal-slideable CSS class and, if so, returns a jQuery reference to that modal.

# setSelfReference()

Records a reference to the modal in the aposModal jQuery data attribute of self.$el, the div corresponding to the modal. Invoked by afterConstruct.

# enableLifecycleEvents()

Adds jQuery event handlers to self.$el, the div corresponding to the modal, for the aposModalCancel and aposModalHide events.

# beforeunload()

# getLastSlide()

Return the last slide, or the modal itself if it has no nested slides. Returns the apostrophe-modal object, not a jQuery element. Use findSafe so we are not faked out by nested views.

# getSlides()

Returns the apostrophe-modal objects corresponding to each slide nested in this modal, which presumably is a slide parent modal (one with the apos-modal-slideable CSS class). The slides are returned in the order they slid in, so the deepest (currently visible) slide is the last in the array. Used by the breadcrumb trail mechanism that displays the titles of all of the slides and allows clicking to jump backwards, closing intervening slides.

# show()

Displays the modal. The enhance Apostrophe event is triggered, with self.$el as the argument, allowing progressive enhancement to take place. If the modal has a $view option, it is appended to that div rather than displaying as a modal normally would.

Otherwise, if the transition option is set to slide and the top modal already on the stack has the apos-modal-slideable CSS class, the new modal "slides in," adding its title to the breadcrumb trail.

Otherwise, the modal is pushed onto the stack, appearing on top of the previous modal if any.

Note that self.beforeShow(callback) and self.afterShow() are provided for your overriding convenience. Usually it is better to override these rather than changing the implementation of self.show() to do extra work.

# slideIn()

Invoked for you by self.show(), this method causes the modal to "slide in" and add itself to the breadcrumb trail if the top modal on the stack has the apos-modal-slideable CSS class. Otherwise it defaults to calling self.stackPush() instead, causing the modal to appear normally on top of any modals already open.

# setDepthAttribute($el)

Make the current modal's depth available as an attribute on various elements such as data-apos-modal-instructions. This is needed for reliable Nightwatch testing

# stackPush()

Called for you by self.show(), this method adds the modal to the stack, blacking out the page, preventing unwanted interaction with the page while the modal is active, and stacking on top of any modals already open, if any. This is normal behavior for modals that do not have the transition: 'slide' option set, and fallback behavior if there is no parent modal already on the stack or the parent modal does not have the apos-modal-slideable CSS class.

# indicateCurrentModal(adding)

For ease of browser regression testing, make sure the current modal and its proxies such as $instructions, $modalFilters, etc. all have the data-apos-modal-current attribute, and that nothing else does.

# resizeContentHeight()

Calculates the appropriate modal body height by subtracting header, breadcrumb, and footer heights and an additional 50 pixels from the browser window height. Invoked for you by self.show(). Not needed anymore with use of flexboxes

# refreshBreadcrumb()

Rebuilds the breadcrumb trail of slide titles inside the slideable ancestor of the current slide, or the modal itself if it is a parent of slides. Normally the text of the breadcrumb is simply the title of the corresponding slide modal. If the field option is set, the slide is assumed to be either the modal for editing an array schema field (see apostrophe-schemas) or a modal related to editing one entry in that field. For the former, the title is set to field.label. For the latter, the title is set to the value of the field.titleField property of the array element indicated by the active property of the slide for the array (the previous slide).

TODO: this is dodgy separation of concerns. Where possible the code that pokes into the implementation of the array modal should be replaced by suitable methods that could also be implemented in other places where a similar behavior is desired.

# beforeShow(callback)

This method is provided as your opportunity to modify the DOM via self.$el and add your own event handlers before the modal appears. By default it does nothing, however if you are extending a subclass such as apostrophe-pieces-editor-modal that provides its own version, be sure to invoke the original version before or after yours.

# afterShow()

Called after the modal is visible. Normally you should use beforeShow to do your work behind the scenes, but perhaps you need to call self.$el.width(), which only works properly on visible elements. There is no callback because the modal has no more work to do after yours.

# save(callback)

Save the modal. Prevents simultaneous saves, displays a busy indicator, saves all views if any and then invokes saveContent to do the actual saving of data. If there is no error the modal is hidden (dismissed).

The callback is optional. If it is provided any error preventing the save operation will be passed to it.

self.saveContent is invoked to carry out the actual work (e.g. saving to a database via an API route, for instance) and by default does nothing. If self.saveContent delivers an error to its callback, the save operation fails and the modal is not hidden.

# afterHideInternal()

# saveContent(callback)

Override this method to carry out the actual storing of data when a modal is saved.

If you invoke the callback with an error, the modal does not disappear.

Displaying the error to the user is your responsibility.

# afterHide()

Override this method to clean up timers, etc. after the modal or view has been dismissed.

# afterHideInternal()

Reserved for internal implementation use.

# afterHideWrapper()

Invoked after the modal or view has been dismissed. Calls self.afterHideInternal, which invokes the callbacks of self.save or self.cancel when appropriate, and also invokes self.afterHide, an initially empty method for your overriding convenience.

# confirmCancel(callback)

This method is invoked to confirm the user's request to cancel the modal. Currently invokes confirm, which is ugly. However confirmCancel is async so this can be replaced with a more attractive implementation.

# getBeforeUnloadText()

Returns text to be displayed by the browser in the event the user attempts to leave the page without saving or cancelling the modal, if self.unsavedChanges is truthy.

Note that some browsers now display a generic message in this case in order to discourage misleading wording.

By default the label option passed when creating the modal is used to customize the text.

# getConfirmCancelText()

Returns the text to be displayed to the user when they attempt to cancel the modal, if self.unsavedChanges is truthy.

By default the label option passed when creating the modal is used to customize the text.

# beforeCancel(callback)

Override this method to alter the behavior when the modal is dismissed by clicking the cancel/done button, pressing escape or clicking outside the modal.

You can prevent the modal from disappearing by invoking the callback with an error. The error is not displayed; doing so is your responsibility if you wish to.

You must invoke the callback, with or without an error.

# cancel(callback)

Cancels the modal, dismissing it without invoking save.

Currently this method assumes you wish to close the top modal (or most recent slide of the top modal) and does not actually check to make sure self is that modal. Generally speaking modals that are lower in the stack should not attempt to interfere when the user is working with a new modal on top of the stack.

If the modal has views, their cancel methods are also invoked first.

If the confirmCancel or beforeCancel method invokes its callback with an error the modal is not closed.

self.afterHide is invoked.

# afterHideInternal()

# hide()

Hides (dismisses) the modal, sliding out or popping off the stack as appropriate. Invokes for you when the user saves or cancels. If the modal is a view, nothing happens by default. The hide() methods of any views within the modal are also called.

# slideOut()

Reverses the slide transition, revealing the previous slide. Invoked for you when the user saves or cancels a slide.

# stackPop()

Pops this modal off the stack. Assumes the modal is a stacked modal and not a slide. Called for you when the modal is saved or cancelled.

# overrideFormSubmission()

Prevents the enter key from inadvertently submitting a form the old-fashioned way. Invoked for you by afterConstruct.

# applyBlackout()

Applies a blackout div with the apos-modal-blackout CSS class to hide the content of the page (with partial opacity) and prevent unwanted interactions with the page while the modal is active. Blackouts are also applied to modals higher in the stack for the same reason. The top-level blackout adjusts its height at regular intervals so that it always adequately covers the document while the modal is active. Invoked for you when a new stacked modal is added.

# focusFirstFormElement()

Gives the focus to the first form element in the modal. Invoked for you when a modal is displayed. TODO: should respect tabindex if present.

# getViews()

Returns an array of views nested within the modal.