Development: UI API

Overview

The bootstrap-helper.js contains classes providing utility functions to create and interact with UI components such as modal or toast.

• The UIFactory class: Exposes quick and easy to use functions for frequently used operations such as opening a toast or loading a modal from an URL
• The Toaster class: Let you create bootstrap toasts and manipulate them
• The ModalFactory class: Let you create bootstrap modals and manipulate them. It supports callback functions for various events and pre-build template
• The OverlayFactory class: Let you create overlays providing a loading feedback or simply to tell users that an operation is in progress
• The FormHelper class: Let you interact with a form validation state

UIFactory usage

Create and open a toast

// toast(options)
UI.toast({
    title: 'Title',
    body: 'Body',
    muted: 'Muted',
    variant: 'danger',
    delay: 20000
})

Create and open a modal

// modal(options)
UI.modal({
    title: 'Title',
    bodyHtml: '<b>Body</b>',
    variant: 'danger',
    type: 'confirm-warning',
    cancelText: 'Dismiss modal',
})

Create and open a modal from a URL. Additionally a reload URL can be passed to reload the table after a successful operation

// openModalFromURL(url, reloadUrl=false, tableId=false)
UI.openModalFromURL('/users/add', '/users/index', 'table-id-to-reload')

Create and open a modal from a URL where the modal's content is fetched from the provided URL. The callbacks functions will be fired upon modal submission

// modalFromURL(url, POSTSuccessCallback=function(){}, POSTFailCallback=function(){})
UI.modalFromURL(
    '/users/add',const loadingOverlay = new OverlayFactory(clicked, {
            spinnerVariant: 'dark',
            spinnerType: 'grow',
            spinnerSmall: true
        });
    () => {console.log('success')},
    () => {console.log('error')}
)

Fetch the content at the provided url and override the $container's content. $statusNode allows to specify another HTML node to display the loading animation

// reload(url, $container, $statusNode=null)
UI.reload('/users/index', $('#userIndexTableContainer'), $('#userIndexTable')).then(() => {
    console.log('reload complete')
})

Place an overlay onto a node and remove it whenever the promise resolves

// overlayUntilResolve(node, promise, overlayOptions={})
UI.overlayUntilResolve($('#userIndexTable'), AJAXApi.quickFetchURL('/users/index'))

Toaster usage

Usually UI.toast(options) should be used as it's basically a shorthand function for the operation below

const toast = new Toaster(options);
toast.makeToast() // build the toast HTML based on the provided options & append to the body
toast.show()      // Reveal the toast for the specified duration then remove it from the body

ModalFactory usage

Usually UI.modal(options) should be used as it's basically a shorthand function for the operation below

const modal = new ModalFactory(options);
modal.makeModal() // build the modal HTML based on the provided options, register listeners & append to the body
modal.show()      // Reveal the modal then remove it from the body after it's been hidden

Callback examples

1. Confirm and Cancel

UI.modal({
    title: 'Confirm?',
    confirm: () => { console.log('confirmed!') },
    cancel: () => { console.log('canceled') },
})

2. APIConfirm and APIError APIConfirm expects a function that behaves like the confirm option but exposes an AJAXApi object (where the $statusNode is linked to the modal's button) that can be used to issue requests

UI.modal({
    title: 'Confirm?',
    APIConfirm: (api) => {
        return api.quickFetchURL('/foo/bar').then(html => {
            console.log(html)
        })
    },
    APIError: (closeModalFunction, modalFactory, evt) => {
        closeModalFunction() // close modal
        console.log('An error occurred during the submission')
    },
})

3. POSTSuccessCallback and POSTFailCallback Internally relies on APIConfirm to POST the form contained in the modal. POSTSuccessCallback expects a function to be called after the POST operation was a success

UI.modal({
    title: 'Confirm?',
    POSTSuccessCallback: (data) => {
        console.log(data)
        location.reload()
    },
    POSTFailCallback: (errorMessage) => {
        console.log(errorMessage)
    },
})

OverlayFactory usage

Usually UI.overlayUntilResolve(node, promise, overlayOptions) should be used as it's basically a shorthand function for the operation below

const loadingOverlay = new OverlayFactory(document.getElementById('myButton'), {
    variant: 'warning',
    spinnerType: 'grow',
    spinnerSmall: true
});
loadingOverlay.show()
setTimeout(() => {loadingOverlay.hide()}, 3000)

FormHelper usage

This class provides a means to inject validation text inside a form

const formHelper = new FormValidationHelper(document.getElementById('myForm'))
formHelper.injectValidationErrors({
    password: [
        'Password must be longer than 8 characters',
        'Password must match the confirm_password field'
    ]
})