basic-modals

    1.1.0 • Public • Published

    Basic-Modals

    A basic and ultra lightweight set of promise based HTML modals (prompt, alert, confirm, veil).

    Install

    npm install basic-modals

    Usage

    Alert

    Parameter list

    This is the parameter list accepted by alert. All of them are optional.

    • message: Text content. The default value is "Default Message".
    • button_ok_content: Text for the "ok button". Default value is "Ok".
    • title: A title on the top of the modal. If a value evaluated as false is provided, like null or false, this modal won't have any title.

    Use 1: Invoking it with a message without parameters

    const { alert } = require('basic-modals')
    
    alert('hello world')

    Use 2: Invoking it using parameters

    alert( { message: 'hello world', button_ok_content: 'close' } )

    Use 3: Using it with a promise

    alert( 'Accept this' )
        .then( _ => console.log('The alert modal has been closed') )

    Use 4: Using the BasicModals global object in a browser's scope

    <script>
        BasicModals.alert('hello world')
    </script>

    Confirm

    Parameter list

    This is the parameter list accepted by confirm. All of them are optional.

    • question: Text content for the question. Default value is "Default Question".
    • button_yes_content: Text for the "yes button". Default value is "Yes".
    • button_no_content: Text for the "no button". Default value is "No".
    • button_cancel_content: Text for the "cancel button". Default value is null. If a value evaluated as false is provided, like null or false, this modal won't have any cancel button.
    • title: A title on the top of the modal. If a value evaluated as false is provided, like null or false, this modal won't have any title.

    Use 1: Invoking it with a question without parameters

    const { confirm } = require('basic-modals')
    
    confirm('is this cool?')
        .then( response => console.log(`The user said ${ response ? 'yes' : 'no' }`) )

    Use 2: Customizing button texts

    confirm( { question: 'like notifications?', button_yes_content: 'always', button_no_content:'never' } )
        .then( response => { /* ... */ } )

    Use 3: Adding a Cancel button

    For adding a cancel button, just add a button_cancel_content parameter with the button text content.

    confirm({
        question: 'save changes?',
        button_yes_content: 'Of course',
        button_no_content:'Never',
        button_cancel_content:'Cancel'
        })
        .then( saved => { /* saved = true if button_yes was clicked, false if button_no was clicked */ } )
        .catch( _ => { /* catch section is executed when button_cancel is clicked */ })

    Use 4: Using the BasicModals global object in a browser's scope

    <script>
        BasicModals.confirm('do you want some pizza?')
            .then( response => { /* ... */ })
    </script>

    Prompt

    Parameter list

    This is the parameter list accepted by prompt. All of them are optional.

    • question: Text content for the question. Default value is "Default Question".
    • value: Default value in place for the input text box. Default value is '' (empty string).
    • placeholder: Placeholder value for the input text box. Default value is '' (empty string).
    • button_accept_content: Text for the "yes button". Default value is "Accept".
    • button_cancel_content: Text for the "cancel button". Default value is "Cancel".
    • title: A title on the top of the modal. If a value evaluated as false is provided, like null or false, this modal won't have any title.

    Use 0: Import prompt from the package

    Use 1: Invoking it with a question without parameters

    const { prompt } = require('basic-modals')
    
    prompt("what's your name?")
        .then( name => console.log(`The user's name is ${name}`) )

    Use 2: Catching when the user closes the modal

    prompt("what's your name?")
        .then( name => console.log(`The user's name is ${name}`) )
        .catch( _ => console.warning('The user closed the modal') )

    Use 3: Customizing button texts, add a default response and placeholder

    prompt( {
        question: "what's your name?",
        value: 'Eric',
        placeholder: 'Your name here',
        button_accept_content: 'Next',
        button_cancel_content:'Quit',
        })
        .then( response => { /* ... */ } )

    Use 4: Using the BasicModals global object in a browser's scope

    <script>
        BasicModals.prompt("what's your name?").then( response => { /* ... */ })
    </script>

    Veil

    An empty veil to block the viewport. It returns a function which will remove the veil when called.

    Parameter list

    This is the parameter list accepted by veil. All of them are optional.

    • text: Text content. The default value is '' (empty string).

    Use 0: Import veil

    const { veil } = require('basic-modals')

    Use 1: Invoking it and closing it after 3 seconds

    // render the veil
    const close = veil()
    // remove the veil after 3 seconds
    setTimeout( close, 3000)

    Use 2: Adding some text to the veil

    const close = veil('some text here')
    setTimeout( close, 3000)

    or

    const close = veil({ text : 'some text here' })
    setTimeout( close, 3000)

    Use 3: The "close method" returns a promise

    When calling close the veil won't be removed immediately, it will be removed asynchronously once a fade out transition ends. If you need to know when the veil is removed from the DOM you can use the promise returned by the close method.

    const close = veil()
    close().then( _ => do_something() )

    Use 4: Using the BasicModals global object in a browser's scope

    <script>
        const close = BasicModals.veil( { text: 'loading... please wait' } )
    </script>

    Adding custom styles

    This package will add a style tag with the modal's CSS in your head section. The classes are prefixed by .BasicModals and they should be self-explanatory, so you can add your own CSS selectors for those classes in your CSS and override / expand the default style.

    Example:

    .BasicModalsButtonOk:hover: {
        background: red
    }

    The above will turn the Ok button to red when the mouse cursor is over it.

    Every modal is a children of a "veil" div with one of the following classes: BasicModalsVeilAlert, BasicModalsVeilConfirm and BasicModalsVeilPrompt. You can use this to customize the style of the different modals separately.

    /* this only will affect the confirm modal */
    .BasicModalsVeilConfirm .BasicModalsButtonOk:hover: {
        background: red
    }

    If you need to increase the specificity of your selectors to override the default ones, just use:

    body .BasicModalsButtonOk:hover: {
        background: red
    }

    or some similar redundant ascendent section starting the selector.

    Adding default values

    You can add default values for any parameter, so you don't need to set them again and again.

    Getting access to the defaults object

    const { defaults } = require('basic-modals')

    or, in a browser's scope:

    const defaults = BasicModals.defaults

    Changing the default value for the alert button

    defaults.alert.button_ok_content = 'Agree'

    Then, for the scenario below:

    alert('hello')
    
    alert( { message: 'world' } )

    in both cases the "button ok" will have the text 'Agree' instead of the default 'Ok'.

    More examples

    The defaults object contents the following pattern:

    defaults[modal_type][parameter_name]

    So, the defaults are available for every parameter of every modal, a few examples below:

    // setting a default for the ok button in alert modals
    defaults.alert.button_ok_content = 'Agree'
    
    // setting a default for "yes" and "no" buttons in confirm modals
    defaults.confirm.button_yes_content = 'Yep!'
    defaults.confirm.button_no_content = 'Nope'
    
    /* setting a default for the question and the cancel button in a
       single line, overriding the original default objects */
    defaults.prompt = { question:'¿?', button_cancel_content: 'Back' }
    
    // setting a default for the veil text
    defaults.veil.text = 'loading'

    Install

    npm i basic-modals

    DownloadsWeekly Downloads

    17

    Version

    1.1.0

    License

    MIT

    Unpacked Size

    48.2 kB

    Total Files

    8

    Last publish

    Collaborators

    • lanshor