deawx / pure-dialog

Web component to simplify creation of web/mobile dialogs

pure-dialog

HTML dialog web component written in pure JavaScript to simplify the creation of dialogs in Web and Hybrid Mobile apps. For example:

<pure-dialog id="example" title="Pure Dialog Demo" buttons="Absolutely, No">
Is this project worth a star?
</pure-dialog>

Becomes:

Try the demo

Table of Contents

• How to use
• In HTML
• In JavaScript
• Methods
• Events
• Properties and attributes
• Styling
• Contribute
• Local development
• Testing
• Update .min files
• Reporting bugs
• Pull requests

How to use

Add dist/pure-dialog.min.js and dist/pure-dialog.min.css files to your page.

If your browser does not support Web Components you will need to add the document.registerElement polyfill.

In HTML

<pure-dialog id="example" title="Pure Dialog Demo" buttons="Absolutely, No">
Is this project worth a star?
</pure-dialog>

In JavaScript

// create the element
var dialog = document.createElement('pure-dialog');

// set its properties
dialog.id = 'example';
dialog.title = 'Pure Dialog Demo';
dialog.innerHTML = 'Is this project worth a star?';
dialog.buttons = 'Absolutely, No';
dialog.closeButton = false;

// append to DOM
dialog.appendToDOM();

// show as a modal
dialog.showModal();

Methods

Assuming var dialog = document.getElementById('example'):

dialog.show();        // show the dialog
dialog.showModal();   // show the dialog as a modal
dialog.close();       // close the dialog
dialog.appendToDOM(); // add the dialog to the DOM (not require if using HTML literal)
dialog.remove();      // remove the dialog from the DOM

Events

All pure-dialog events bubble up so it is possible to listen for pure-dialog events at the root of the DOM. Assuming var dialog = document.getElementById('example'):

// detect button clicks on the #example element
dialog.addEventListener('pure-dialog-button-clicked', function(e) {

  if (e.detail === 'Absolutely') {
    // Absolutely was clicked!
  }
  else {
    // Absolutely was not clicked, stop the dialog from closing ;)
    e.preventDefault();
  }
});

// detect button click on all dialogs in the DOM
document.addEventListener('pure-dialog-button-clicked', function(e) {
  console.log(e.detail); // log button label
});

// detect closed clicked
dialog.addEventListener('pure-dialog-close-clicked', function(e) {
  console.log(e.target.id) // log dialog id

  // stop the dialog from closing by using e.preventDefault()
});

// detect dialog is opening
dialog.addEventListener('pure-dialog-opening', function(e) {
  console.log(e.target.id) // log dialog id

  // stop the dialog from opening by using e.preventDefault()
});

// detect dialog has opened
dialog.addEventListener('pure-dialog-opened', function(e) {
  console.log(e.target.id) // log dialog id
});

// detect dialog is closing
dialog.addEventListener('pure-dialog-closing', function(e) {
  console.log(e.target.id) // log dialog id

  // stop the dialog from closing by using e.preventDefault()
});

// detect dialog has closed
dialog.addEventListener('pure-dialog-closed', function(e) {
  console.log(e.target.id) // log dialog id
});

// detect dialog is appending to DOM
dialog.addEventListener('pure-dialog-appending', function(e) {
  console.log(e.target.id) // log dialog id

  // stop the dialog from been inserted by using e.preventDefault()
});

// detect dialog removed from DOM
dialog.addEventListener('pure-dialog-removing', function(e) {
  console.log(e.target.id) // log dialog id

  // stop the dialog from been removed by using e.preventDefault()
});

Properties and attributes

Property	Attribute	Description	Type	Default
title	title	Get/set the dialog title	string	empty
buttons	buttons	Get/set comma separated list of buttons	string	empty
closeButton	close-button	If true, renders a close button	boolean	false
removeOnClose	remove-on-close	If true, remove dialog from DOM on close	boolean	false
autoClose	auto-close	auto close when button clicked	boolean	true
innerHTML	n/a	Injects HTML into body of dialog	string	empty
body	n/a	Gets dialog inner body tag	object	null

Assuming var dialog = document.getElementById('example'):

dialog.title = 'Pure Dialog Demo';        // set title
dialog.buttons = 'Absolutely, No';        // set buttons
dialog.closeButton = true;                // set close button visibility
dialog.removeOnClose = true;              // remove dialog from DOM on close
dialog.autoClose = false;                 // do not auto close when button clicked
dialog.innerHTML = 'Hello World!';        // set dialog body HTML
dialog.body.textContent = 'Hello World';  // set inner text via body tag

Styling

pure-dialog was designed to be light and so only produces the following output, making it easy to style:

<pure-dialog id="example" title="Pure Dialog Demo" buttons="Absolutely, No">
  <div class="pure-dialog-container">
    <div class="pure-dialog-title">Pure Dialog Demo</div>
    <div class="pure-dialog-body">Is this project worth a star?</div>
    <div class="pure-dialog-buttons">
      <input class="pure-dialog-button" type="button" value="Absolutely">
      <input class="pure-dialog-button" type="button" value="No">
    </div>
  </div>
</pure-dialog>

To change the style of a particular button, you could use its value as a selector:

#example input[value="Absolutely"] { background: #880000; }

Contribute

Local development

The project includes everything needed to continue development, including a node webserver. If you'd like to help out, run the following to get started:

git clone https://github.com/john-doherty/pure-dialog
cd pure-dialog
npm install
npm start

Then visit http://localhost:8080 in your browser.

Testing

The project includes Unit Test. To run tests, execute the following from within the pure-dialog folder:

npm install
npm test

Tests are written using jsdom/jasmine and are broken into 3 files:

Filename	Description
pure-dialog-interface-spec.js	Check properties, methods and defaults are exposed
pure-dialog-method-spec.js	Executes methods and verifies functionality by inspecting output
pure-dialog-rendering-spec.js	Various rendering checks

Update .min files

The minified pure-dialog.min.js and pure-dialog.min.css files included in this project are the latest version. To generate new .min files, execute the following:

npm run build

The version number is picked up from the package.json file.

Reporting bugs

If you find a bug, please create an issue and include a jsfiddle or CodePen if possible.

Pull requests

Please ensure your work is covered with unit test(s) and your code follows the ESLint coding style defined in the package.json file.

License

Licensed under MIT License © John Doherty