# Blade Components

---

<a name="about"></a>
## About

[Blade components](https://laravel.com/docs/blade#components) are a quick way for you to output a bit of HTML... that can then be customized by each Siberfx theme. It's a clean way of echoing theme-agnostic components, because for each Component that Siberfx provides, the theme itself can customize and make it pretty in their own way.

<a name="how-to-use-components"></a>
### How to Use

Anywhere in your blade files, you can use the Blade components we have. But most likely you'll be using them in your `resources/views/vendor/siberfx/ui/inc/menu_items.blade.php`, because all our components currently are concerned with outputting menu items in a theme-agnostic way.


<a name="mandatory-attributes"></a>
### Mandatory Attributes

There are no mandatory attributes.

<a name="optional-attributes"></a>
### Optional Attributes

All components also allow you to specify custom attributes. When you specify a custom attribute, that attribute will be placed on the most likely element of that component. In most cases, that is the anchor element. For example:

```php
<x-siberfx::menu-item title="Tags" icon="la la-tag" :link="siberfx_url('tags')" target="_blank" />
```

Even though the 'target' attribute doesn't _technically_ exist in the component, that attribute will be placed on that component's `a` element.


<a name="available-components"></a>
## Available Components

<a name="menu-item"></a>
### Menu Item

Shows a menu item, with the title and link you specify:

```php
<x-siberfx::menu-item title="Tags" icon="la la-tag" :link="siberfx_url('tags')" />
```

Note that you can further customize this using custom attributes. If you define a `target` on it, that will be passed down to the `a` element.

<hr>


<a name="menu-separator"></a>
### Menu Separator

Shows a menu separator, with the title you specify:

```php
<x-siberfx::menu-separator title="Some text for separation" />
```

Note that you can further customize this using custom attributes. If you define a `class` on it, that will be passed down to the `li` element.

<hr>


<a name="menu-dropdown-and-menu-dropdown-item"></a>
### Menu Dropdown & Menu Dropdown Item

To show a dropdown menu, with elements, you can use the `menu-dropdown` and `menu-dropdown-item` components:

```php
<x-siberfx::menu-dropdown title="Authentication" icon="la la-group">
    <x-siberfx::menu-dropdown-item title="Users" icon="la la-user" :link="siberfx_url('user')" />
    <x-siberfx::menu-dropdown-item title="Roles" icon="la la-group" :link="siberfx_url('role')" />
    <x-siberfx::menu-dropdown-item title="Permissions" icon="la la-key" :link="siberfx_url('permission')" />
</x-siberfx::menu-dropdown>
```

Notes:
- on `menu-dropdown` you can define `nested="true"` to flag that dropdown as nested (aka. having a parent); so you can have dropdown in dropdown in dropdown;
- on both components, you can also define custom attributes; eg. if you define a `target` on one, that will be passed down to the `a` element;


<hr>

<a name="overwriting-default-components"></a>
## Overriding Default Components

You can override a component by placing a file with the same name in your ```resources\views\vendor\siberfx\ui\components``` directory. When a file is there, Siberfx will pick that one up, instead of the one in the package.

>**Avoid doing this.** When you're overwriting a component, you're forfeiting any future updates for that component. We can't push updates to a file that you're no longer using.

<a name="creating-a-custom-component"></a>
## Creating a Custom Component

We do not support creating custom components within the `backpack` namespace. If you want to create a custom component, please create one in the `app` namespace. The [Laravel docs on Blade Components](https://laravel.com/docs/blade#components) will teach you everything you need to know.
