materializemodal v1.0.5

MaterializeModal

Work more efficiently with modals from the MaterializeCSS framework.

• Demo
• Installation
• Options
• Methods
• Global options
• Helper
• Presets

I've been working on a single-page application for our company in which I heavily used modals for all the functionality. I quickly realized that adding all those modals to the HTML file was kind of a mess and doing anything dynamic was a pain in the ass (forms, collections, ..). That's why I've decided to write this small library. I just wanted to share this in case someone might find it helpful. Feel free to suggest any improvements that could be made.

Demo

Try it out right here!

Installation

If you'd like to use this library, you'll need the latest version of MaterializeCSS. Then, simply include materialize.modal.min.js & materialize.modal.min.css in your HTML file. No initialization needed. Also, no need to include JQuery. Alternatively, you can use npm: npm i materializemodal

Example:

let myFirstModal = new Modal({
  title: 'My First Modal !',
  openButton: '#open_myFirstModal',
  width: 70,
  height: 80,
  opacity: 0.7,
  dismissible: true,
  preventScrolling: false,
  inDuration: 150,
  outDuration: 75,
  onOpen: (modal) => {
    modal.setContent('Some content');
  }
});

Options:

Methods:

open(data)

Opens the modal. If needed, custom data can be passed in to the onOpen(modal, data) function.

isOpen()

Returns a boolean value indicating if the modal is currently open.

close(callback)

Closes the modal. An optional callback function can be passed in that executes when the modal is closed (and gets the modal object as its parameter).

select(el)

Returns an element in the modal based on a query string. For example:

let element = modal.select('#myElement');

selectAll(el)

Returns all elements in the modal based on a query string. For example:

let elements = modal.selectAll('.my-element');

on(event, callback)

Binds an event (click, keypress, ...) to the modal. The callback gets the event data as its parameter.

setContent(content)

Removes all dynamic content from the modal (the fixedContent from the options will not be affected) and sets the content passed in. The content must be a string or a DOM Element.

addContent(content)

Adds content to the end of the modal. Content must be a string or a DOM Element.

removeContent(selector)

Removes content based on a HTML query selection. For example: modal.removeContent('.myNiceDiv')

setTitle(title)

Sets the title of the modal. Argument must be a string and can contain HTML.

getTitle()

Returns the current title of the modal.

setFooterButtons(buttons)

Removes the current buttons and sets the buttons passed in (HTML string).

setAttribute(attribute, value)

Sets a custom HTML attribute.

getAttribute(attribute)

Returns the value of the specified attribute.

insertForm(options)

Inserts a form.

Options

Form field options:

Example:

modal.insertForm({
  width: 80,
  fields: [{
    name: 'firstname',
    label: 'First name',
    type: 'text_short',
    icon: 'account_circle',
    width: 50,
    required: true
    }, {
    name: 'lastname',
    label: 'Last name',
    type: 'text_short',
    icon: 'account_circle',
    width: 50,
    required: true
    }, {
    name: 'position',
    label: 'Position',
    type: 'custom',
    icon: 'label',
    required: true,
    chips: [{
      tag: 'Accounting'
      }, {
      tag: 'Sales'
      }, {
      tag: 'Human Resources'
      }]
    }, {
    name: 'date_started',
    label: 'Start date',
    type: 'date',
    icon: 'date_range',
    required: true
    }]
});

setFormValues(values)

Sets the values for the form fields. The parameter must be an object. Considering our previous example, it should look something like this:

modal.setFormValues({
  firstname: 'Alex',
  lastname: 'Smith',
  position: [{tag: 'Sales'}],
  date_started: '2018-10-10' // depends on your Datepicker setup
});

In order for this to work, the property name must be equal to the name you gave the field in the 'insertForm' function. Setting the value for type 'custom' or 'custom_multiple' requires an array with the selected element(s), the structure must be similar to the 'chips' array when creating the form field. Setting the value for a 'checkbox' field requires a boolean value.

getFormValues(mode)

Returns the form values. An optional argument can be passed in to specify how the data should be structured: single or combined - default is combined. If there are required fields that are not filled in, this method returns this object: {requiredFieldMissing: true}. In addition, the missing fields' bottom border will be colored in red to give the user some kind of visual feedback. Example:

let values = modal.getFormValues();
if(values.requiredFieldMissing) {
  // One or more required field(s) not filled in, display some kind of error message
} else {
  // All good
  console.log(values);
}

getFormFields()

Returns all HTML form fields.

getFormField(field)

Returns the specified HTML form field. Argument must be a string equal to the name of the field given in the insertForm function.

clearForm()

Clears the form.

hideFormField(fields)

Hides one or more form fields. Argument is an array of fields. Each element in the array must be a string equal to the name of the field given in the insertForm function.

formFieldChange(event, field, callback)

Adds an event listener to a form field (change, keyup, keypress, ..). The callback gets the event data.

displayImage(src)

Adds an image to the modal.

displayFormImage(src)

Adds the path of the image to the already existing image field.

hideFormImageDeleteButton()

Hides the delete button of the image field.

showFormImageDeleteButton()

Shows the delete button of the image field.

removeImage()

Removes the image.

getImage()

Returns a FormData object of the selected image.

addChipsField(chips)

Adds a chips field to the form - the argument is an array of chips equal to the structure of chips in a form field.

insertCollection(options)

Inserts a collection.

Options:

Collection item options

Secondary content options:

Example:

Let's consider the example from the insertForm() method. We've added the data to some database and now we would like to display the members of the staff:

// We've got the staff data from an API
let collection = [];
staff.forEach(empl => {
  collection.push({
    label: `${empl.firstname} ${empl.lastname}`,
    attributes: {"employee-id": empl._id},
    secondaryContent: [
      {
      icon: 'edit',
      class: 'edit-employee',
      color: '#00bcd4'
      },
      {
      icon: 'delete',
      class: 'delete-employee',
      color: '#df0101'
      }
    ]
  });
});
modal.insertCollection({
  searchBar: true,
  items: collection,
  onInserted: () => {
    // do something when the collection has been fully inserted, for example:
    modal.selectAll('.edit-employee').forEach(el => el.addEventListener('click', (e) => /*open modal to edit employee*/));
    modal.selectAll('.delete-employee').forEach(el => el.addEventListener('click', (e) => /*delete employee*/));
  }
});

getCollection()

Returns the HTML collection.

getCollectionItems()

Returns all HTML collection items.

minimize()

Minimize the modal programatically.

maximize()

Maximize the modal programatically.

Global options

M_Modal.datePickerOptions

To customize the MaterializeCSS Datepicker, you can set options as described in their documentation. M_Modal.datePickerOptions = {options} Important: you need to add container:'body' to the options for the picker to show up (weird bug in MaterializeCSS).

M_Modal.timePickerOptions

To customize the MaterializeCSS Timepicker, you can set options as described in their documentation. M_Modal.timePickerOptions = {options} Important: you need to add container:'body' to the options for the picker to show up (weird bug in MaterializeCSS).

M_Modal.searchBarPlaceholderText

By default, the placeholder text of the searchbar in the header of the modal is Search... This can be changed like this: M_Modal.searchBarPlaceholderText = 'Search..'

Helper

Submit form by pressing the Enter key

Adding the class 'modal-submit-form' to an element triggers its click event when pressing the Enter key.

Presets

Predefined modals can be used for different purposes:

M_Modal.presets.alert(message)

Shows a small modal with an alert message.

M_Modal.presets.alert('Attention!');

M_Modal.presets.error(message)

Shows a small modal with an error message.

M_Modal.presets.error('An error ocurred, please try again later.');

M_Modal.presets.confirm(message, callback)

Shows a small modal for confirmation purposes. Use it like this:

M_Modal.presets.confirm('Please confirm this action', (confirmed) => {
  if(confirmed) {
    // Confirmed, do something
  } else {
    // Denied, do something else
  }
});

M_Modal.presets.prompt(title, callback)

Shows a small modal with a text input. Use it like this:

M_Modal.presets.prompt('Enter your name', (input) => {
  if(input) {
    // Text was entered and the OK button has been clicked
  } else {
    // Cancel button has been clicked, do something else
  }
});

M_Modal.presets.password(title, callback)

Shows a small modal to enter a password. Use it like this:

M_Modal.presets.password('Enter your password', (pw) => {
  if(pw) {
    // Password was entered and the OK button has been clicked
  } else {
    // Cancel button has been clicked, do something else
  }
});