Wondering what’s next for npm?Check out our public roadmap! »

    apostrophe-dialog-box

    1.2.0 • Public • Published

    CircleCI

    apostrophe-dialog-box

    apostrophe-dialog-box provides simple pop-up dialog boxes for your Apostrophe site. Manage them you would like any other piece type, edit their content in-context, provide your own templates, and have users trigger them with various configuration.

    Installation

    npm install apostrophe-dialog-box

    Basic configuration

    In app.js

    var apos = require('apostrophe')({
      shortName: 'dialog-sandbox',
      modules: {
        // ... other modules
        'apostrophe-dialog-box': {},
        'apostrophe-dialog-box-modal': {},
        // optional index page for dialog boxes, useful if dialog styles conflict with apos modal styles
        'apostrophe-dialog-box-pages': {}
      }
    });

    This will give you a piece type called Dialog Boxes in the admin bar as well as several enhancements to existing Apostrophe modules.

    Working with your first Dialog Box

    Create a new dialog box from the admin bar. Give it a title and leave the template as Default.

    You'll be brought back to the manager where your new Dialog Box will have a Launch link in it's table row. Click it! Launch the dialog;

    This will activate the basic dialog template. It comes stock with basic Apostrophe area. Make your edits and close the dialog naturally and your edits will save.

    Dedicated Index Page of Dialogs

    If you've opted to install apostrophe-dialog-box-pages you can also create a new page and give it a type of Dialog Index. Placing it in your page tree will give you a dedicated space where you can trigger and edit dialog boxes outside the Apostrophe modal context. This is useful if your site's styles are being overridden by apos-modal styles and you want a more accurate representation of your modal.

    Note that logged-out users will be forwarded to the homepage if they try to visit this URL.

    Triggering dialog boxes

    Dialog boxes can be triggered by page load or by clicking on elements with the proper data attributes attached to them.

    Options for triggering dialog boxes on page load

    Page load settings can contain

    • Delay (in seconds) for when the dialog box will appear after load
    • Ability to set an expiration cookie so that dialogs will only appear once during the expiration lifespan

    Triggering a dialog box on all pages

    Go to the Global menu and find the Dialog Boxes tab. Join the dialog box you made previously

    Triggering a dialog box on one page

    Go to the Page Settings of the page the page you want to activate a dialog on. In the Page Settings find the Dialog Boxes tab and configure your dialog

    Triggering a dialog box via text link

    You can optionally enable a Dialog Box plugin for your rich text editors by passing the proper options:

    {{
      apos.area(data.page, 'body', {
        widgets: {
          'apostrophe-rich-text': {
            toolbar: [ 'Bold', 'Italic', 'Link', 'Dialogbox' ]
          },
          'apostrophe-video': {}
        }
      })
    }}

    Dialog box icon

    Using it will present you with a text field you can enter as well a dropdown to select which dialog box you'd like to associate with the ink.

    Dialog box rich text editor

    Triggering a dialog box from other things

    All you need to do to trigger a dialog box from custom widgets or UI is add a data attribute to the element with the dialog boxes ID. The attribute is formatted like data-apos-dialog-box-trigger="APOS_PIECE_ID" To get the snippet open the Dialog Boxes admin menu, find the dialog box you want to trigger in the manager, and click "Copy Code to Clipboard" (you can attach the attribute to anything you want, not just a link).

    Copy to clipboard

    Listening to events for analytics

    There are a few events are triggered for dialog boxes:

    • time-triggered when a dialog box is opened automatically on page load
    • opened whenever a dialog box is opened
    • closed whenever a dialog box is closed

    A dialog opening on page load will trigger the two open events, and a manually clicked link opening a dialog box will trigger only the opened event.

    These events are dispatched on the page body. Therefore, event listeners can be added to be notified. It can be useful for analytics purposes.

    Example of listener to add at project level:

    document.body.addEventListener('apostrophe-dialog-box:time-triggered', function (evt) {
      // code for `evt` handling
    }, false);
    document.body.addEventListener('apostrophe-dialog-box:opened', function (evt) {
      // code for `evt` handling
    }, false);
    document.body.addEventListener('apostrophe-dialog-box:closed', function (evt) {
      // code for `evt` handling
    }, false);

    The event emitted contains the dialog box id dialogId in order to distinguish between multiple dialog boxes on a page.

    Extending and Customizing Dialog Boxes

    You'll probably want to customize and potentially have multiple Dialog Box templates to choose from. In these custom templates you can include projet-level widgets, markup, and CSS.

    Adding a new template

    • Create a new template like /lib/modules/apostrophe-dialog-box/views/dialogs/MY_COOL_DIALOG.html
    • Populate the file with the boilerplate markup
    {% extends "dialogs/base.html" %}
    
    {% block main %}
      <!-- your areas here -->
    {% endblock %}
    
    • Override the default template select with your project level choices in app.js
    'apostrophe-dialog-bo x': {
      addFields: [
        {
          name: 'template',
          label: 'Template',
          type: 'select',
          choices: [
            { label: 'Default', value: 'default' },
            { label: 'My Cool Dialog', value: 'MY_COOL_DIALOG' }
          ]
        }
      ]
    },
    'apostrophe-dialog-box-modal': {},
    

    Your template will now be available to editors. You can also change the template of existing dialogs by modifying them in the Dialog Box manager.

    Install

    npm i apostrophe-dialog-box

    DownloadsWeekly Downloads

    3

    Version

    1.2.0

    License

    MIT

    Unpacked Size

    506 kB

    Total Files

    41

    Last publish

    Collaborators

    • avatar
    • avatar
    • avatar
    • avatar
    • avatar
    • avatar
    • avatar
    • avatar