Buttons

Button definitions are used often in other UI definitions. For example module sections can define buttons and form actions extend them.

Understanding the anatomy and general behavior of button definitions is integral in working proficiently with UI builders.

Introduction

This section will introduce you to buttons and how to define them.

Defining Buttons

Buttons are defined by simple arrays. These buttons are ran through various processing and is used to hydrate instances of the \Anomaly\Streams\Platform\Ui\Button\Button class for use by the Streams Platform.

The idea behind defining buttons is that you can provide minimal information about a button and the Streams Platform can do the rest for you. Saving you from having to define the instance yourself with all required parameters.

Button definitions are simply an array:

'buttons' => [
    'create'          => [
        'url' => '/admin/example/test/create',
        'text' => 'streams::button.create',
        'icon' => 'fa asterisk',
        'type' => 'success',
    ],
]

The Button Definition

Button definitions are ran through valuation, evaluation, and resolving, as well as other processes like guessing. These are the simple property descriptions for buttons.

Properties
Key Required Type Default Description
$url false string {section.path}/{button.slug}/{entry.id} The HREF attribute of the button.
$button false string Anomaly\Streams\Platform\Ui\Button The target button class to build.
$text false string {vendor}.module.{module}::button.{button}.title The button text.
$icon false string null A registered icon string or icon class.
$class false string null The CSS class to append ot the button class attribute.
$type false string default The button type or context. Bootstrap state colors (primary, success, etc) are supported by default.
$size false string md The button size. Bootstrap button sized are supported by default.
$attributes false string null An array of `key => value` HTML attributes. Any base level definition keys starting with `data-` will be pushed into attributes automatically.
$permission false string null The permission key required to display the button.
$disabled false boolean false Determines whether the button will be disabled or not.
$enabled false boolean true Determines whether the button will be rendered or not.
$dropdown false array null An array of item definitions. See below for more information.
$position false string left The position of the button's dropdown.
ButtonRegistry::register()

The register method adds a globally available button definition.

Returns: Anomaly\Streams\Platform\Ui\Button\ButtonRegistry
Arguments
Key Required Type Default Description
$button true string none The button key.
$parameters true array none The registered button parameters.
Example
$registery->register(
    'purchase', 
    [
        'type' => 'success',
        'text' => 'Purchase',
        'icon' => 'fa fa-credit-card',
        'href' => 'checkout/{entry.id}',
    ]
);

The Dropdown Definition

The button dropdown property can be used to define a dropdown menu for the button.

'buttons' => [
    'save' => [
        'dropdown' => [
            [
                'icon' => 'save',
                'text' => 'Save and exit',
            ],
            [
                'icon' => 'fa fa-sign-out',
                'text' => 'Save and continue',
            ]
        ]
    ]
]
Properties
Key Required Type Default Description
$text true string null The text or translation key.
$icon false string null A registered icon string or icon class.
$url true string null The button URL. This gets pushed into `attributes` automatically as HREF.

The Button Registry

Below are the basic registered buttons. Some definitions like form actions that extend buttons may add to these or use them in their own registry. In such cases they will be documented separately.

Registered buttons can be found in Anomaly\Streams\Platform\Ui\Button\ButtonRegistry.

/**
 * Default Buttons
 */
'default'       => [
    'type' => 'default'
],
'cancel'        => [
    'text' => 'streams::button.cancel',
    'type' => 'default'
],

/**
 * Primary Buttons
 */
'options'       => [
    'text' => 'streams::button.options',
    'type' => 'primary',
    'icon' => 'cog',
],

/**
 * Success Buttons
 */
'green'         => [
    'type' => 'success'
],
'success'       => [
    'icon' => 'check',
    'type' => 'success'
],
'save'          => [
    'text' => 'streams::button.save',
    'icon' => 'save',
    'type' => 'success'
],
'update'        => [
    'text' => 'streams::button.save',
    'icon' => 'save',
    'type' => 'success'
],
'create'        => [
    'text' => 'streams::button.create',
    'icon' => 'fa fa-asterisk',
    'type' => 'success'
],
'new'           => [
    'text' => 'streams::button.new',
    'icon' => 'fa fa-plus',
    'type' => 'success'
],
'new_field'     => [
    'text' => 'streams::button.new_field',
    'icon' => 'fa fa-plus',
    'type' => 'success'
],
'add'           => [
    'text' => 'streams::button.add',
    'icon' => 'fa fa-plus',
    'type' => 'success'
],
'add_field'     => [
    'text' => 'streams::button.add_field',
    'icon' => 'fa fa-plus',
    'type' => 'success'
],
'assign_fields' => [
    'text' => 'streams::button.assign_fields',
    'icon' => 'fa fa-plus',
    'type' => 'success'
],
'send'          => [
    'text' => 'streams::button.send',
    'icon' => 'envelope',
    'type' => 'success'
],
'submit'        => [
    'text' => 'streams::button.submit',
    'type' => 'success'
],
'install'       => [
    'text' => 'streams::button.install',
    'icon' => 'download',
    'type' => 'success'
],
'entries'       => [
    'text' => 'streams::button.entries',
    'icon' => 'list-ol',
    'type' => 'success'
],
'done'          => [
    'text' => 'streams::button.done',
    'type' => 'success',
    'icon' => 'check'
],
'select'        => [
    'text' => 'streams::button.select',
    'type' => 'success',
    'icon' => 'check'
],
'restore'       => [
    'text' => 'streams::button.restore',
    'type' => 'success',
    'icon' => 'repeat'
],
'finish'        => [
    'text' => 'streams::button.finish',
    'type' => 'success',
    'icon' => 'check'
],
'finished'      => [
    'text' => 'streams::button.finished',
    'type' => 'success',
    'icon' => 'check'
],

/**
 * Info Buttons
 */
'blue'          => [
    'type' => 'info'
],
'info'          => [
    'type' => 'info'
],
'information'   => [
    'text' => 'streams::button.info',
    'icon' => 'fa fa-info',
    'type' => 'info'
],
'help'          => [
    'icon'        => 'circle-question-mark',
    'text'        => 'streams::button.help',
    'type'        => 'info',
    'data-toggle' => 'modal',
    'data-target' => '#modal'
],
'view'          => [
    'text' => 'streams::button.view',
    'icon' => 'fa fa-eye',
    'type' => 'info'
],
'export'        => [
    'text' => 'streams::button.export',
    'icon' => 'download',
    'type' => 'info'
],
'fields'        => [
    'text' => 'streams::button.fields',
    'icon' => 'list-alt',
    'type' => 'info'
],
'assignments'   => [
    'text' => 'streams::button.assignments',
    'icon' => 'list-alt',
    'type' => 'info'
],
'settings'      => [
    'text' => 'streams::button.settings',
    'type' => 'info',
    'icon' => 'cog',
],
'configure'     => [
    'text' => 'streams::button.configure',
    'icon' => 'wrench',
    'type' => 'info'
],

/**
 * Warning Buttons
 */
'orange'        => [
    'type' => 'warning'
],
'warning'       => [
    'icon' => 'warning',
    'type' => 'warning'
],
'edit'          => [
    'text' => 'streams::button.edit',
    'icon' => 'pencil',
    'type' => 'warning'
],

/**
 * Danger Buttons
 */
'red'           => [
    'type' => 'danger'
],
'danger'        => [
    'icon' => 'fa fa-exclamation-circle',
    'type' => 'danger'
],
'remove'        => [
    'text' => 'streams::button.remove',
    'type' => 'danger',
    'icon' => 'ban'
],
'delete'        => [
    'icon'       => 'trash',
    'type'       => 'danger',
    'text'       => 'streams::button.delete',
    'attributes' => [
        'data-toggle'  => 'confirm',
        'data-message' => 'streams::message.confirm_delete'
    ]
],
'prompt'        => [
    'icon'       => 'trash',
    'type'       => 'danger',
    'button'     => 'delete',
    'text'       => 'streams::button.delete',
    'attributes' => [
        'data-match'   => 'yes',
        'data-toggle'  => 'prompt',
        'data-message' => 'streams::message.prompt_delete'
    ]
],
'uninstall'     => [
    'type'       => 'danger',
    'icon'       => 'times-circle',
    'text'       => 'streams::button.uninstall',
    'attributes' => [
        'data-toggle'  => 'confirm',
        'data-message' => 'streams::message.confirm_uninstall'
    ]
]

Using Registered Buttons

There are a number of buttons registered in the \Anomaly\Streams\Platform\Ui\Button\ButtonRegistry class. To use any of these buttons simply include their string slug and the button's registered definitions will be merged into your own.

'buttons' => [
    'save',
    'delete' => [
        'text' => 'Delete me!', // Overrides the default "Delete" text.
    ],
]

The above save and delete buttons are registered as:

'buttons' => [
    'save' => [
        'icon' => 'save',
        'type' => 'success',
        'text' => 'streams::button.save',
    ],
    'delete'        => [
        'icon' => 'trash',
        'type' => 'danger',
        'text' => 'streams::button.delete',
        'attributes' => [
            'data-toggle' => 'confirm',
            'data-message' => 'streams::message.confirm_delete'
        ]
    ],
]

Note that the delete text will be overridden since you defined your own text.