Modals

One of the most important sub-class of Component, which are defined by Ember FW, that you will need to be familiar with when developing for Informatics is Modals, which are used on virtually every page of the apps. Modals are Components that pop up and are displayed hovering over the rest of the page. In order to properly use a modal component, you need to have one defined in the "modals" sub-folder of components. Then you must call the modal on a page using the FwFullscreenModal component on the page you wish to call it on. We will speak of each of these in turn.

Unless you are using a predefined modal, you will need to create a javascript Component file, and a template for your modal. In the case of a predefined modal (Ember FWs are listed below but a few other packages make a few more), you can skip this step because it is done for you, but otherwise you need to create your files. In order to make a custom modal, you must create a component in the subfolder "modals". So it needs both a javascript file located in app/components/modals/my-modal.js and a handlebars file located in app/templates/components/modals/my-modal.hbs. If there is not a file meeting that description in both places, then there will be an error saying it could not find component "my-modal" when it is attempting to render it through FwFullscreenModal. The name of the file must also match exactly with the string modal attribute you pass to the FwFullscreenModal.

The Javascript file:

The javascript file is very simple. The only thing that is required is that you extend the BaseModal component rather than extending a generic component in general. This is exactly how your modal component should look:

import BaseModal from '@bennerinformatics/ember-fw/components/modals/base';

export default BaseModal.extend({
    //... regular component information goes here
});

The rest of the information for the modal is up to the end users decision, but it should function as any other component file would. It might be that the user desires to extend the closeModal function (which is passed in by the FwFullscreenModal), and this is able to be done by defining a closeModal action and within that action calling this.closeModal(). At the minimum, this action should be called during the save/confirm action in order to get the modal to actually close. The most basic example would be the following action:

actions: {
   save() {
       //call the action to save the model as a promise
       return this.get('model').save().then(() => {
           //after the promise resolves, close the modal
           this.closeModal();
       });
   }
}

For more information about the BaseModal Component in general, and what options you have built in, you can check out the API Docs for it, here.

The Handlebars File:

The handlebars file can be formatted however the end user decides, however because the modal darkens the background, it is best that the user utilize a bootstrap panel in some way when defining the modal. Here are some general guidelines for formatting the handlebars file:

It should probably be a panel with a header, body and footer, which means it should either use the FwContentBox component or it could even use an FwTableSortable component (from ember-fw-table). It can also be made a panel manually by using the following code:

<div class="panel panel-default">
     <header class="panel-heading">
     </header>
     <section class="panel-body">
     </section>
     <footer class="panel-footer clearfix">
    </footer>
</div>

The footer should contain at the least a button to close the modal, but often a button to "confirm" or "save" the action.
Many modals also wrap their entire modal in a form tag, which gives the added capacity of functioning like a form (which most modals are forms on the basic level). To learn more about the form tag, checkout this documentation.

Overall, modals are very versatile and can be made in many different ways. Perhaps one of the best ways to learn about modals other than this brief introduction is look at how modals are used in the various apps that Benner Library Informatics has developed. Modals are perhaps the most commonly used aspect of the ember-fw package.

Built in Modals

Ember FW defines a few built in modals as options, which allow you to do very basic things (such as confirm an action) without needing to create a whole modal file. These modals are used all over the place in our apps, so they are good to get to know. Our API Docs cover very well how to use these built in modals, so here is just a link and small description for them:

Confirm-Choice Modal is a modal designed to just confirm an action. It displays a simple message with a "confirm" or "cancel" buttons, which will either do the action that is confirmed or close the modal without doing it. This should ordinarily be used instead of Javascript's native confirm where possible.
Confirm-Dialog Modal is a modal which just displays a simple message with a close button. It is similar to an "alert", and should be used instead of Javascript's native alert where possible.

In order to render the modal you just created above, you will need to use the FwFullscreenModal component. You can find details about the component itself, and how to use it in the API Docs for FwFullscreenModal. It is important to note that the best way to have a modal "open" and "close" is to wrap it in an if helper, with that property toggled by various buttons. For example:

{{#if openMyModal}}
    <FwFullscreenModal @modal="my-modal" @size="md" close={{action 'toggleOpenMyModal'}} />
{{/if}}

The reason for this is then you can have a button, which calls an action, such as the following:

toggleOpenMyModal() {
  this.toggleProperty('openMyModal');
}

In the example above, the same action is used for opening and closing the modal. The first button will toggle the property and set it to true, displaying the modal, and then the close button will set it to false, hiding the modal. This can also be done with separate actions one setting openMyModal to true, and one setting it to false.

Note: All of the attributes for the component are well described in FwFullscreenModal API Docs, so you should get a good idea of what to do from there, but I will draw attention to a few of the properties for you to especially look at, which are vital for properly calling any modal: modal, model, and close. The property size also deserves special attention, as it will determine how much of the screen the modal will cover (it has 6 options: xs, sm, md, lg, xl, and full). For more information on any of these properties, visit the API docs.

Modals

Building the Modal

The Javascript file:

The Handlebars File:

Built in Modals

Calling the Modal