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 templates
• The OverlayFactory class: Let you create overlays on top of existing element. It's usually use to give feedback or simply to tell users that an operation is in progress
• The FormHelper class: Let you interact with a form validation state
• The HtmlHelper class: Provides utility functions to build HTML (or jQuery objects) such as HTML tables from a configuration.

UIFactory usage

Exposes shorthand functions for frequently used operations such as opening a toast or loading a modal from an URL without the hurdle of instantiating an object

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',
    () => {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'), {text: 'Fetching user index'})
    .then(userHtml => {
        console.log(userHtml);
    }.catch(error => {
        console.log(error.message)
    })

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. Must be used with the rawHtml function. POSTSuccessCallback expects a function to be called after the POST operation was a success.

UI.modal({
    rawHtml: modalHTML,
    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

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'
    ]
})

HtmlHelper usage

Provides utility functions to build HTML (or jQuery objects) from a configuration

HTML table

// HtmlHelper.table(head=[], body=[], options={}) 
const $table = HtmlHelper.table(
    ['Header 1', 'Header 2'],
    [
        ['Row 1.1', 'Row 1.2'],
        ['Row 2.1', 'Row 2.2'],
    ],
    {
        small: true,
        hoverable: true,
        bordered: true,
        tableClass: ['m-0'],
        variant: 'warning',
        caption: 'Table caption'
    }
)