Skip to content

Latest commit

 

History

History
356 lines (336 loc) · 11 KB

ui-modal.md

File metadata and controls

356 lines (336 loc) · 11 KB
layout group subgroup title menu_title version github_link redirect_from
default
UI_Components_guide
components
Modal сomponent
Modal component
2.1
ui_comp_guide/components/ui-modal.md
guides/v2.0/ui-components/ui-modal.html

This topic describes the modal UI component.

Modal component: overview

The Modal UI component implements a secondary window that opens on top of the main window. It uses the modal widget.

Similar to the widget's configuration, the component's configuration allows you to set the window type and action buttons behavior (including linking action buttons to methods of the other UI components).

The Modal component can be used for both Admin panel and storefront.

For recommendations about modal windows usage from the UX point of view, see the corresponding topic in the Magento Admin pattern library.

Structure

The modal UI component comprises the following files:

  • JS component: <Magento_Ui_module_dir>/view/base/web/js/modal/modal-component.js
  • Template: <Magento_Ui_module_dir>/view/base/web/templates/modal/modal-component.html

Options

Component's options are set in the configuration .xml file as follows:

{%highlight xml%} %value% %value% ... {%endhighlight%}

The modal component uses general configuration options, similar to other UI components. However, it uses the following specific options as well:

Modal options
state

Set the state of the modal window: true for open.

Type: Boolean

Required?: Optional

Default value: false

options

Configuration for the modal widget. Passed to the widget initialization as is.

Type: Object

Required?: Optional

Default value: {}

title

The title of the modal window. Set as follows: 

<item name="options" xsi:type="array">
    <item name="title" xsi:type="string">%window_title%</item>
</item>

Type: String

Required?: Optional

Default value: ''

subTitle

The subtitle of the modal window. Set as follows: 

<item name="options" xsi:type="array">
    <item name="title" xsi:type="string">%window_subtitle%</item>
</item>

Type: String

Required?: Optional

Default value: ''

type

The type of the modal window. Can be one of the following: slide or popup. Set as follows: 

<item name="options" xsi:type="array">
    <item name="type" xsi:type="string">%slide|popup%</item>
</item>

Type: String

Required?: Optional

Default value: slide

buttons

The action buttons of the modal window.

Type: Array Required?: Optional Default value: []

text

The button label.
Set as follows: 

<item name="options" xsi:type="array">
    <item name="buttons" xsi:type="array">
         <item name="%button_number%" xsi:type="array">
             <item name="text" xsi:type="string">%label%</item>
         </item>
    </item>
</item>

Type: String

Required?: Optional

Default value: Undefined

class

The CSS class for the button.
Set as follows: 

<item name="options" xsi:type="array">
    <item name="buttons" xsi:type="array">
         <item name="%button_number%" xsi:type="array">
             <item name="class" xsi:type="string">%class%</item>
         </item>
    </item>
</item>

Type: String

Required?: Optional

Default value: Undefined

actions

Button actions. On button click, actions are performed in the same order as they are specified in config.
Set as follows: 

<item name="options" xsi:type="array">
    <item name="buttons" xsi:type="array">
         <item name="%button_number%" xsi:type="array">
             <item name="actions" xsi:type="string">
                <--! Action that calls the method of the other UI component -->
                <item name="%action_number%" xsi:type="array">
                    <item name="targetName" xsi:type="string">%component_which_performs_action%</item>
                    <item name="actionName" xsi:type="string">%method_of_target_component%</item>
                </item>
                <--! Action that calls the method of the modal component -->
                <item name="%next_action_number%" xsi:type="array">%method_of_modal_component%</item>
             </item>
         </item>
    </item>
</item>

Type: Object

Required?: Optional

Default value: Undefined

onCancel

Action (method name), that is performed on canceling interactions: pressing Esc, clicking outside the modal window, or clicking the 'X' (close) icon.

Type: String

Required?: Optional

Default value: closeModal

Example of the Modal component configuration

The following sample is an example of the configuration for a simple modal window containing one text field and a standard set of action buttons (Cancel, Clear, Done):

{%highlight xml%} actionCancel Cancel action-secondary actionCancel Clear action-secondary ${ $.name }.testField clear Done action-primary actionDone test field input true

Open modal ${ $.parentName}.test_modal openModal {%endhighlight%}

Public API (JS)

  • actionCancel(): returns all modal's child components to the state they had on modal open and closes the modal window.
  • actionDone(): validates the changes in the modal's child components and, if valid, closes the modal.
  • closeModal(): closes the modal window.
  • openModal(): opens the modal window.
  • setPrevValues(elem): returns all elem's child components to the state they had on modal open.
  • setTitle(): sets modal title.
  • setSubTitle(): sets modal sub title.
  • toggleModal(): toggles the modal window state (open/close).