Buttons

There are several standard buttons in Nexus. Each can be used several different ways, documented below.

There is also a base component <ButtonWithIcon> for creating custom buttons.

TODO: There is currently a lot of duplication and some inconsistency between the different button types. I hope to fix this in the future by making all buttons use the base component. For now, I have documented each component separately. If you need any of the buttons to do something it can't, please talk to me about the best way to fix it. --Dave (Jan 2021)

`<ButtonView>`

This is a green button with an eye icon and the tooltip "View".

The most common way to use this button is in a table (<CardTable>):

<template #row-buttons="{ row: example }">
    <ButtonView
        :href="$route('examples.show', example.slug)"
        :name="example.name"
        small
    />
</template>

You can also use it in other places, e.g. to open a modal popup:

<ButtonView
    small
    text="More Details"
    tooltip=""
    @click="showMoreDetails = true"
/>

Props:

The most commonly used props are:

href (String) - The URL to link to. May be internal or external.
name (String) - The name of the record that will be viewed. This is used in the default alt text ("View "), for accessibility.
text (String) - Optional text to display on the button (along with the icon).
small (Boolean) - Uses the small button size.

You may also want to use these:

disabled (Boolean) - Display the button in disabled state (not clickable).
target (String) - Set to _blank to open links in a new tab.

It also inherits the following props from <ButtonWithIcon>:

action (String) - Used in the default alt text. Defaults to "View".
alt (String) - The alt text for the icon. Defaults to "View " or just "View" if no record name is given.
tooltip (String) - The tooltip to display on hover. Defaults to "View". May be set to an empty string to disable it.
text-class (String, Array or Object) - Classes to add to the  around the text.
method (String) - Defaults to GET, but can be changed to POST, etc.
data (Object) - When method is anything except GET (e.g. POST), this data is submitted like form data (via the $inertia.visit() method).
icon (Object) - Defaults to the Font Awesome faEye icon. Generally should not be changed.
variant (String) - The bootstrap button variant. Defaults to "success". Generally should not be changed.

Slots: None.

Events:

@click - Triggered when the button is clicked. Generally, href should not be provided when using the click event - although if you do, both will be triggered.

`<ButtonEdit>`

This is a yellow button with an pencil icon and the tooltip "Edit".

The most common way to use this button is in a table (<CardTable>) - generally alongside the View button:

<template #row-buttons="{ row: example }">
    <ButtonView
        :href="$route('examples.show', example.slug)"
        :name="example.name"
        small
    />
    <ButtonEdit
        v-if="userCan.EditExamples"
        class="ml-1"
        :href="$route('examples.edit', example.slug)"
        :name="example.name"
        small
    />
</template>

And also in the #buttons slot of <CardSimple> (or <CardTable>):

<CardSimple primary :title="example.name">

    <template #buttons>
        <ButtonEdit
            v-if="userCan.EditExamples"
            :href="$route('examples.edit', example.slug)"
            small
            text="Edit"
            text-class="d-none d-sm-inline"
        />
    </template>

    ...

</CardSimple>

Note: text-class is used here to hide the text on small screens, leaving only the icon. This is optional but recommended.

Props:

The most commonly used props are:

href (String) - The URL to link to. May be internal or external.
name (String) - The name of the record that will be edited. This is used in the default alt text ("Edit "), for accessibility.
text (String) - Optional text to display on the button (along with the icon).
small (Boolean) - Uses the small button size.

You may also want to use these:

disabled (Boolean) - Display the button in disabled state (not clickable).
target (String) - Set to _blank to open links in a new tab.

It also inherits the following props from <ButtonWithIcon>:

action (String) - Used in the default alt text. Defaults to "Edit".
alt (String) - The alt text for the icon. Defaults to "Edit " or just "Edit" if no record name is given.
tooltip (String) - The tooltip to display on hover. Defaults to "Edit". May be set to an empty string to disable it.
text-class (String, Array or Object) - Classes to add to the  around the text.
method (String) - Defaults to GET, but can be changed to POST, etc.
data (Object) - When method is anything except GET (e.g. POST), this data is submitted like form data (via the $inertia.visit() method).
icon (Object) - Defaults to the Font Awesome faPencil icon. Generally should not be changed.
variant (String) - The bootstrap button variant. Defaults to "warning". Generally should not be changed.

Slots: None.

Events:

@click - Triggered when the button is clicked. Generally, href should not be provided when using the click event - although if you do, both will be triggered.

`<ButtonDelete>`

This is a red button with an trash can icon and the tooltip "Delete". When clicked, it prompts the user "Are you sure you want to delete ?". When they confirm it triggers a HTTP DELETE request.

It is commonly used in a table (<CardTable>) - generally alongside the View and Edit button:

<template #row-buttons="{ row: example }">
    ...
    <ButtonDelete
        v-if="userCan.DeleteExamples"
        :action="$route('examples.destroy', example.slug)"
        class="ml-1"
        :name="example.name"
        small
    />
</template>

And also in the #buttons slot of <CardSimple> (or <CardTable>):

<CardSimple primary :title="example.name">

    <template #buttons>
        ...
        <ButtonDelete
            v-if="userCan.DeleteExamples"
            :action="$route('examples.destroy', example.slug)"
            class="ml-1"
            :name="example.name"
            small
        />
    </template>

    ...

</CardSimple>

Props:

The most commonly used props are:

action (String) - The URL to submit the DELETE request to. (Note: This is different to the <ButtonWithIcon> action prop.)
name (String) - The name of the record that will be deleted. This is used in the default alt text ("Delete "), for accessibility, as well as the modal confirmation.
text (String) - Optional text to display on the button (along with the icon).
small (Boolean) - Uses the small button size.

The other props available are:

alt (String) - The alt text for the icon. Defaults to "Delete " or just "Delete" if no record name is given.
confirm (String) - The text for the confirmation message. Defaults to "Are you sure you want to delete ?".
confirm-title (String) - The title for the confirmation promps. Defaults to "Delete ".
text-class (String, Array or Object) - Classes to add to the  around the text.
tooltip (String) - The tooltip to display on hover. Defaults to "Edit". May be set to an empty string to disable it.

Slots: None.

Events:

@click - Triggered when the button is clicked. Generally, action should not be provided when using the click event - although if you do, both will be triggered.

`<ButtonRemove>`

This is a red button with an "unlink" icon and the tooltip "Remove". When clicked, it prompts the user "Are you sure you want to remove ?". When they confirm it triggers a HTTP DELETE request.

This is similar to the Delete button, but intended for use in Many-Many links where the record isn't actually deleted.

It is generally used in a table (<CardTable>):

<template #row-buttons="{ row: related }">
    ...
    <ButtonRemove
        v-if="userCan.EditExamples"
        :action="$route('examples.related.destroy', [example.slug, related.slug])"
        class="ml-1"
        :name="related.name"
        small
    />
</template>

TODO: The props & events are different to <ButtonDelete> for historical reasons - we should update/combine them at some point.

Props:

The most commonly used props are:

action (String - required) - The URL to submit the DELETE request to. (Note: This is different to the <ButtonWithIcon> action prop.)
name (String) - The name of the record that will be deleted. This is used in the default alt text ("Delete "), for accessibility, as well as the modal confirmation.
small (Boolean) - Uses the small button size.

The other props available are:

alt (String) - The alt text for the icon. Defaults to "Delete " or just "Delete" if no record name is given.
confirm (String) - The text for the confirmation message. Defaults to "Are you sure you want to delete ?".
data (Object) - Additional form data (submitted via the $inertia.visit() method).
disabled (Boolean) - Display the button in disabled state (not clickable).
method (String) - The HTTP method. Defaults to DELETE.
tooltip (String) - The tooltip to display on hover. Defaults to "Edit". May be set to an empty string to disable it.

Slots: None.

Events: None.

`<ButtonNew>`

This is a black button with a "plus" icon.

It is commonly used in the header row of <CardTable>:

<template #heading-buttons>
    <ButtonNew v-if="userCan.CreateExamples" :href="$route('examples.create')" small text="New" />
</template>

And also in the fallback message when the table is empty:

<template #empty-buttons>
    <ButtonNew v-if="userCan.CreateExamples" class="mr-1" :href="$route('examples.create')" text="New Example" />
    <ButtonClearSearch />
</template>

Props:

alt (String) - The alt text for the icon. Empty by default.
href (String) - The URL to link to. May be internal or external.
small (Boolean) - Uses the small button size.
target (String) - Set to _blank to open links in a new tab.
text (String) - Optional text to display on the button (along with the icon).
text-class (String, Array or Object) - Classes to add to the  around the text.
tooltip (String) - The tooltip to display on hover. Empty by default.

Slots: None.

Events: None.

`<ButtonClearSearch>`

This button clears the current query string. It is generally used on a search/filter form. It is automatically hidden if there is no query string.

For compatibility with the server-side remember_query middleware, it links to <currentUrl>? by default - the ? at the end tells the middleware to clear the saved query instead of redirecting.

There are two different styles. The default is a dark grey button with "Clear Search" written on it. This is designed to be used in the fallback text of <CardTable>:

<template #empty-buttons>
    <ButtonNew v-if="userCan.CreateExamples" class="mr-1" :href="$route('examples.create')" text="New Example" />
    <ButtonClearSearch />
</template>

The "subtle" style is transparent with a grey border and the default text says "Reset". This is designed to be used in search forms:

<CardSimple title="Search">

    <template #buttons>
        <ButtonClearSearch small subtle />
    </template>

    ...

</CardSimple>

Note: It is automatically included in <CardSearchForm>.

Props:

alt (String) - The alt text for the icon. Empty by default.
href (String) - The URL to link to. May be internal or external. Defaults to the current URL without its query string.
small (Boolean) - Uses the small button size.
subtle (Boolean) - Uses the "subtle" style described above.
text (String) - Optional text to display on the button (along with the icon).
text-class (String, Array or Object) - Classes to add to the  around the text.
tooltip (String) - The tooltip to display on hover. Empty by default.

Slots: None.

Events:

@click - Triggered when the button is clicked.

`<ButtonSave>`

This is a blue (primary colour) button with a "save" icon. It submits the form it is contained in, so it has no href or action parameter itself.

It is normally used at the bottom of a form, outside the cards (example 1). It can also be used in the buttons bar of a card (example 2):

<form @submit.prevent="submit">

    <div class="row">
        <div class="col mb-3">
            <CardSimple primary :title="(example.id ? 'Edit' : 'New') + ' Example'">

                <template #buttons>
                    <ButtonSave small /> <!-- EXAMPLE 2 -->
                </template>

                ...

            </CardSimple>
        </div>
    </div>

    <div class="row">
        <div class="col mb-3">
            <ButtonSave /> <!-- EXAMPLE 1 -->
            <RequiredHelpText />
        </div>
    </div>

</form>

If there are multiple cards, it should generally be added to the top-right card only.

Note: The card displayed in the top-right may be different at different breakpoints. You can use the Bootstrap display utilities to hide/show it as required - for example:

<!-- In the card that is first on mobile / top-left on desktop, show the button on mobile only: -->
<ButtonSave class="d-xl-none" small />

<!-- In the card that is second on mobile / top-right on desktop, show the button on desktop only: -->
<ButtonSave class="d-none d-xl-inline-block" small />

Props:

disabled (Boolean) - Display the button in disabled state (not clickable).
no-icon (Boolean) - Disables the icon.
small (Boolean) - Uses the small button size.
saving (Boolean) - Disables the button and replaces the save icon with a spinner.
saving-text (String) - Text to use when saving (optional).
text (String) - Text to display on the button (along with the icon). Defaults to "Save".
text-class (String/Array/Object) - Class(es) to add to the  around the text.

Slots: None.

Events: None.

`<ButtonUpload>`

This is a blue (primary colour) button, similar to <ButtonSave> with an "upload" icon. It submits the form it is contained in, so it has no href or action parameter itself.

It should be used the same way that <ButtonSave> is (see above).

Props:

disabled (Boolean) - Display the button in disabled state (not clickable).
no-icon (Boolean) - Disables the icon.
small (Boolean) - Uses the small button size.
saving (Boolean) - Disables the button and replaces the save icon with a spinner.
saving-text (String) - Text to use when saving. Defaults to "Uploading...".
text (String) - Text to display on the button (along with the icon). Defaults to "Save".
text-class (String/Array/Object) - Class(es) to add to the  around the text.

Slots: None.

Events: None.

`<ButtonWithIcon>`

This is a base component that can be used to create your own custom buttons. See <ButtonView> and <ButtonEdit> for examples.

Note: You do not have to use this component - you can choose to create buttons manually with regular <button> tags and (optionally) the <FontAwesome> component.

Props:

These props should be overridden in the custom child component:

icon (Object) - A Font Awesome icon.
variant (String) - The Bootstrap button variant, e.g. primary.

The remaining props can either be overridden in the child component or when the component is used:

action (String) - Used in the default alt text, if given.
alt (String) - The alt text for the icon. Defaults to " " or "" or empty, depending which props are given.
href (String) - The URL to link to. May be internal or external.
data (Object) - When method is anything except GET (e.g. POST), this data is submitted like form data (via the $inertia.visit() method).
disabled (Boolean) - Display the button in disabled state (not clickable).
method (String) - Defaults to GET, but can be changed to POST, etc.
name (String) - Used in the default alt text, if given.
small (Boolean) - Uses the small button size.
target (String) - Set to _blank to open links in a new tab.
text (String) - Optional text to display on the button (along with the icon).
text-class (String, Array or Object) - Classes to add to the  around the text.
tooltip (String) - The tooltip to display on hover. Defaults to "View". May be set to an empty string to disable it.

Slots: None.

Events:

@click - Triggered when the button is clicked. Generally, href should not be provided when using the click event - although if you do, both will be triggered.