Download the PHP package oza75/laravel-hubble without Composer

Laravel Hubble

Build a beautiful dashboard with laravel in no time.

Requirements

• php : ^7.1
• Laravel : ^6.0

Installation

You can install the package via composer:

Then install laravel-hubble

Now go to : http://yourapp.tld/hubble (or http://localhost:8000/hubble if you use artisan serve)

Authentification

Hubble uses the default Laravel authorization gate to check if a user can access to the dashboard. By default, everyone can access to hubble dashboard. You can restrict access by using authorizesAccess method on App\Providers\HubbleServiceProvider.

Usage

Resources

A hubble resource is a simple php class which aims to represent the resource you want to add, namely the different fields, actions, filters, etc. that it has.

Create resource

You can create a new resource by running hubble:resource command

This will automatically create a new resource under app/Hubble folder

After your resource is generated, you need to set the eloquent builder hubble should use to get your data. When generating this resource we will try to obtain the eloquent builder according to the name of the resource passed in php artisan hubble:resource command. You can modify this query builder to add some computed fields.

fields method is used to return all fields your want to display. By default, hubble comes with some fields like TextField, TextareaField, ImageField and more. But you can also create your own custom field.

Configure your resource

You can configure your resource by setting some properties on your resource class.

If you want to customize the title that should be shown in each different screen (index page, edit page, details page etc...) you may define configure method in your resource. For example:

Registering your resource

By default, hubble will automatically register all resources you have under app/Hubble folder.

Just go to http://yourapp.tld/hubble and you will see the new user resource that we add.

You can customize the folder within hubble must look for your resources in config file. The auto registration is very useful when developing your dashboard but you may disable it in production to gain a small performance.

In your app/Providers/HubbleServiceProvider.php :

Actions

Action is used to perform custom tasks on one or more Eloquent models. You can generate action using :

This command will generate a new ActiveUsers class under app/Hubble/Actions

The title property contains the name of the action that will be shown on the User Interface

In the handle method you can perform your action. For our example, let's assume that our users table has an active column which determine whether the user is active or not.

When you created your action you can add it in your resource.

Filters

As the name suggests, filters are used to filter your data and display only data that satisfy certain conditions. There are many ways to add filter into your resource :

• the first way (the easiest way ) :

Filter::make take as is first argument, the column in the database. The second argument is the title and then the third array of options.

The options' argument is an associative array where the key is the label and the value, the value of the option. You can also pass an url where the options should be fetched or a custom array. for those cases you may set the valueKey and the textKey using the setValueKey(string $key), and the setTextKey(string $key).

For example:

Another example:

• the second way to define a filter (more powerful) :

With this way, you can use the setHandler method to pass a callable that takes the query builder as his first argument and the value of the filter, you can add any where clause you want.

• The last way is to generate a new filter class.

This command will generate a new filter class under app/Hubble/Filters.

You can also generate a filter with a custom VueJs components.

This will generate a VueJs component under resources/hubble/components/filters/my-custom-filter.vue

Fields

Fields are used to display your data. the base Field class can be used to create fields. Any types of fields extend this class.

• sortable

You can also tell to Hubble to sort your data by default using a certain field.

Custom Display

There are a few methods you can use to customize how you want to display the field value in the different sections of the dashboard.

• displayUsing
• displayOnIndexUsing
• displayOnDetailsUsing
• displayOnFormsUsing
• displayWhenEditingUsing
• displayWhenCreatingUsing

The displayUsing method customize the display in all sections of the dashboard.

All these methods as the same signature.

Visibility

Field comes with some methods that you can use to tell when to display

• hide : will hide the field in all screen
• hideOnIndex
• hideOnForms
• hideOnDetails
• hideWhenCreating
• hideWhenEditing
• hideOnExport
• showOnIndex
• showOnDetails
• showOnForm
• showWhenCreating
• showWhenEditing
• showOnExport
• onlyOnIndex
• onlyOnDetails
• onlyOnForms
• onlyOnCreating
• onlyOnEditing
• onlyOnExport

All of these methods can pass a closure that will be used to hide or display the field on a specific screen.

Hubble ships with many types of fields, but you can also create your own.

• TextField
• BooleanField
• NumberField
• TextareaField
• DateTimeField
• SelectField
• ColorField
• FileField
• ImageField
• BelongsToField (relation field)
• HasManyField (relation field)

TextField

Used to display a text Field.

• text type

this type will be used to display correct input type in forms.

• limit

limit the number of character that should be displayed in tables.

BooleanField

the text method set the text to display when this field has true or false value.

NumberField

Used to display number values

TextareaField

Used to display long text values

DateTimeField

Used to display dates values

• date format

• date locale

SelectField

• display using label

ColorField

Used to display colors

• display using hex value

FileField

Used to display and upload files

• multiple

• max

Limit number of files

ImageField

Used to display image and upload images.

ImageField extends to FileField so it has all methods that FileField has, such as multiple or max.

or

BelongsToField

Used to display a related resource

• signature

The first argument is the name relationship method. Let's assume we have in our User model a belongsTo method to City Model.

Then to add this relationship in our resource

HasManyField

Used to display related resources

• signature

As the BelongsToField, the HasManyField takes the relationship method name as his first argument.

Create a custom field

You can create a custom field by using this command:

You can also generate a new field with custom components by using this command:

This will create new VueJs components for your field under resources/hubble/components/fields/color

Use this command to build the newly components

or

php artisan hubble:field will generate a new Field Class under app/Hubble/Fields

Rules

You can automatically validate your forms data by setting rules on each field.

There are also rules methods for each creation and editing screen

• rulesWhenUpdating will define the rules only when updating
• rulesWhenCreating will define the rules only when creating

Warning: the rules' method cannot yet take a validation object (such as a rule class) or a closure but any Pull Request is welcoming.

For frontend interactivity, you may set a handler that can be used to validate automatically your field value under resources/hubble/rules.js. If you don't, an ajax request will be sent to the backend to check if the value is valid when user is filling the form.

Authorization

Authorization is used to restrict access of certain screen of your dashboard. Internally, it uses mostly Laravel Authorization Gate.

You just need to create a Laravel Policy for your resource that will control which user can access or not to a specific screen.

For example, let's assume I have a Post model :

This will generate a new Laravel Policy under app/Policies.

Testing

Changelog

Please see CHANGELOG for more information what has changed recently.

Contributing

Please see CONTRIBUTING for details.

Security

If you discover any security related issues, please email [email protected] instead of using the issue tracker.

Credits

• Zié Aboubacar OUATTARA
• All Contributors

License

The MIT License (MIT). Please see License File for more information.

Laravel Package Boilerplate

This package was generated using the Laravel Package Boilerplate.