jquery-emodal

jQuery eModal Plugin

$.eModal is a easy way to manage Bootstrap 4 modal dialogs using javaScript. It is not only a system that facilitates the use of the Bootstrap modal dialog, but an alternative to dialog boxes, such as alert, confirm and prompt.

Bootstrap 4 and jQuery are dependencies to jquery.eModal.js.

This plugin is based on the work of Samuel Pinto (saribe), but has been completely reengineered. https://github.com/saribe/eModal

Dependencies

The plugin requires jQuery 3 and Bootstrap 4.

Installation

NPM: npm install jquery-emodal

Yarn: yarn add jquery-emodal

Bower: bower install Reload-Lab/jquery-eModal

Example And Usage

The index.html file in the example/ folder contains many examples of using the script that illustrate its full potential.

You can see the plugin in action at this url: https://www.reloadlab.it/cantieri/jquery-eModal/example/

To initialize your modal:

1. Add the script to your page:

<script src=path/to/emodal/folder/dist/ jquery.eModal.min.js></script>

2. Call one of the methods of the $.eModal object to open your modal dialog

<script>
$(document).ready(function(){
   $.eModal.ajax('ajax.html?_uid' + Math.random(), 'Ajax modal');
}); 
</script> 

or add an event to some element.

<button class="open-ajax" type="button">OPEN MODAL</button>
<script>
$(document).ready(function(){
   $('.open-ajax').on('click', function(e){
      $.eModal.ajax('ajax.html?_uid' + Math.random(), 'Ajax modal');
   });
}); 
</script> 

Modal methods

All methods take two arguments:

1. data (required): the value passed can be a string that represents the message to be displayed, or an object that configures the characteristics of the modal dialog.
2. title (optional): the value passed must be a string representing the title that appears in the modal header.

Method	Description
$.eModal.alert	Traditional notice box. You can pass a text or a reference to a jQuery object to the method.
$.eModal.ajax	This method allows you to get remote views into your modal using an URL.
$.eModal.confirm	Get an okay from user with a traditional confirm modal.
$.eModal.prompt	A simple form to ask the user a question and get an answer.
$.eModal.iframe	This method allows you to open a page in an iframe within the modal dialog.
$.eModal.embed	A modal dialog that allows you to show a video from YouTube or a map from Gmap embedded in an iframe.

Available Options

It is possible to set numerous characteristics of the modal through an object to be passed as the first argument of the methods described above.

Options	Type	Description
message	jQuery, Html, Url, String	Content to be loaded inside the body element of the modal. It can be a text string, a url to a web resource, html content or a jQuery object. The variable is mandatory.
async	Boolean	If the variable is set to true, the $.eModal functions return a Promise, that is resolved when the modal is closed. For modal confirm and prompt, the value must be true. Default: false
useBin	Boolean	If set to true, $.eModal keeps the content uploaded in the body element of the modal in a recycle bin can, so that it can be recalled without a new upload from the web. Default: false
binId	String, false	Unique identifier of the content saved in the recycle bin. In case the useBin variable is set to true, binId must be set in order for the content to be saved. Default: false
id	String, false	Set the ID attribute of the modal dialog. Default: false
cssClass	String, false	CSS class to apply to the modal dialog. Default: false
bodyStyles	Object, false	Inline CSS styles to be applied to the body element of the modal. Default: false
header	Boolean	If the value is set to false, $.eModal does not show the Bootstrap modal header. Default: true
title	String	The property sets the title that appears in the modal header. Default: Attention
wrapTitle	String	Html that frames the title that appears in the modal header. Default: <h5>
subtitle	String, false	The property sets the subtitle that appears in the modal header. Default: false
wrapSubtitle	String	Html that frames the subtitle that appears in the modal header. Default: <small>
headerClose	Boolean	If the value is set to false, $.eModal does not show the close button in Bootstrap's modal header. Default: true
headerCloseHtml	Html	Close button html in Bootstrap modal header.
footer	Boolean	If the value is set to false, $.eModal does not show the Bootstrap modal footer. Default: true
buttons	Array, String, false, null	You can set all button attributes and actions to be displayed in the modal footer. If the value is an array it is possible to set the characteristics of the button through an object. For example text (string) for the button label, style (string) for the css class to be applied to the button, close (boolean) if the button has to close the modal, click (function) to execute a function when the button is clicked. All other attributes can be passed through the properties of the object (key is the attribute and value is the attribute's value) If a string is passed, the text will appear in the footer. If the value is false, no footer is shown. By default, a close modal button appears. Default: null
width	Number, String, false	Width of the modal relative to the browser window. You can use a numeric value, a pixel value or a percentage value. Default: false
height	Number, String, false	Height of the modal relative to the browser window. You can use a numeric value, a pixel value or a percentage value. Default: false
size	String	Set modal width according to Bootstrap measurements: small (sm), large (lg) and extra large (xl). Default: empty string
position	Array	Sets the vertical and horizontal position of the modal relative to the screen. The first element of the array is the vertical position (top, middle and bottom). The second element indicates the horizontal position (left, center, right). Default: [top, center]
animation	String	You can choose the animation that will be performed when the modal is opened. If an empty string is passed there will be no animation. Default: 'fade'
modalOptions	Object, false	Options to pass to Bootstrap's modal function. Default: false
overlayClose	Boolean	If the variable is set to false, the possibility of closing the modal by clicking on the backdrop is inhibited. Default: true
onHide	Function, false	Function that is performed when the modal is closed. Default: false

Ajax modal options

Options	Type	Description
ajax.dataType	String	In the case of modal ajax, the variable indicates the type of content (html, text, json, xml) returned by the ajax call. Default: html
ajax.error	Function, false	Function to be performed in case of error in the ajax call. The function receives three arguments: The jqXHR object, a string describing the type of error that occurred and the configuration params passed to ajax modal. Default: false
ajax.loading	Boolean	In the case of an ajax modal, if the variable is set to true, $.eModal displays a content loading bar. Default: true
ajax.loadingHtml	Html	In the case of an ajax, Html of the content loading bar.
ajax.success	Function, false	Function to be performed in case of success in the ajax call. The function gets passed one argument: The data returned from the server, formatted according to the dataType parameter. Default: false
ajax.url	String, false	In the case of modal ajax, the variable sets the url of the resource to be loaded in the body element of the modal. Default: false
ajax.xhr	Object, false	In the case of modal ajax, you can set the properties of the call. To know all the values that can be set, you can read the documentation of the jQuery $.ajax function: https://api.jquery.com/jquery.ajax/. Default: false

Confirm modal options

Options	Type	Description
confirm.label	String	Confirm button label in confirm modals. Default: Ok
confirm.style	Array	CSS class of the confirmation and rejection buttons of the modal confirm. Default: [btn-primary, btn-danger]

Prompt modal options

Options	Type	Description
prompt.autocomplete	Boolean	In the case of a modal prompt, if the variable is set to true, the value ON is assigned to the autocomplete attribute of the field. Default: false
prompt.autofocus	Boolean	In the case of a modal prompt, if the variable is set to true, the focus is assigned to the input field when the modal is opened. Default: false
prompt.checkValidity	Boolean	In the case of a modal prompt, if the variable is set to true, a check is made on the validity of the content of the input field, using the browser api. Default: false
prompt.label	String	Confirm button label in prompt modals. Default: Ok
prompt.pattern	String, false	In the case of modal prompt, you can set the pattern attribute of the INPUT tag, so that the value entered by the user in the field can be validated using a regular expression. Default: false
prompt.placeholder	String, false	In the case of modal prompt, you can set the placeholder attribute of the INPUT tag, so that a placeholder text is displayed in the input field. Default: false
prompt.required	Boolean	In the case of modal prompt, set the required attribute of the INPUT tag, so that it is mandatory to fill in the input field before sending it. Default: false
prompt.style	Array	CSS class of the confirmation and rejection buttons of the modal prompt. Default: [btn-primary, btn-danger]
prompt.type	String	In the case of modal prompt you can set the type attribute of the INPUT tag. Default: text
prompt.value	String, false	In the case of modal prompt, you can set the value of the value attribute of the INPUT tag. Default: false

Iframe and embed modal options

Options	Type	Description
iframe.loadingHtml	Html	In the case of an embed and iframe modal, Html of the content loading bar.
iframe.url	String, false	In the case of modal embed and iframe, the variable sets the url of the resource to be loaded in the body element of the modal. Default: false
iframe.attributes	Object, false	In the case of modal iframe and embed, you can set the attributes of the IFRAME tag. The object keys correspond to the attributes and the values to the attribut's values. Default: false

Utility methods

Method	Description
$.eModal.close	Closes the modal. The onHide function is not performed. Nothing returns
$.eModal.label	Adds new labels. It takes two arguments: confirm button label and reject button label. Returns the $.eModal object for concatenation.
$.eModal.modal	Returns the jQuery object of the modal dialog.
$.eModal.defer	Return the Promise to be able to perform a resolve or reject.
$.eModal.size	It is possible to add a size to those provided by Bootstrap (sm, lg, xl). Returns the $.eModal object for concatenation.
$.eModal.emptyBin	The method empties the recycle bin. Returns the $.eModal object for concatenation.

Created by Domenico Gigante - Reload Laboratorio Multimediale, Rome, IT