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.