Download the PHP package okipa/laravel-brickables without Composer

Package abandoned

This package has been abandoned, use with caution if you still need it.
Please fork this package and give it new life if you're interested!

This package allows you to associate content bricks to Eloquent models and provides a fully customizable admin panel to manage them.

This package is shipped with few pre-built brickables. You can use them as is but you definitely should consider them as examples: customizing them or create new ones has been designed to be simple as hell! :fire:

Found this package helpful? Please consider supporting my work!

Compatibility

Upgrade guide

• From V2 to V3
• From V1 to V2

Usage

Associate content bricks to Eloquent models:

Display bricks in your views:

Display the model-related bricks admin panel in your views:

Table of contents

• Installation
• Configuration
• Views
• Translations
• Implementation
  • Models
  • Routes
• How to
  • Define brick constraints for model
  • Add content bricks
  • Update a content brick
  • Remove content bricks
  • Set content bricks order
  • Retrieve content bricks
  • Query content bricks
  • Display content bricks
  • Retrieve brickables
  • Manage model content bricks
  • Create your own brickable
  • Define brickable css and js resources
  • Empower bricks with extra abilities
  • Get Eloquent model from Request
• Testing
• Changelog
• Contributing
• Security
• Credits
• Licence

Installation

Install the package via composer:

Then, publish and run the database migrations:

Finally, to benefit from smart loading of brickables css and js resources, add these directives to your blade layout as shown in the example bellow:

Configuration

Publish the package configuration:

:warning: You may have to run a composer dump-autoload after changing a path in your configuration file.

Views

Publish the package views:

Translations

All words and sentences used in this package are translatable.

See how to translate them on the Laravel official documentation : https://laravel.com/docs/localization#using-translation-strings-as-keys.

Here is the list of the words and sentences available for translation by default:

• Content Bricks
• No saved content brick.
• Content
• Left content
• Right content
• Brick data
• Add
• Edit
• Update
• Destroy
• Cancel
• Move up
• Move down
• The entry :model > :brickable has been created.
• The entry :model > :brickable has been updated.
• The entry :model > :brickable has been deleted.

You will also have to define the validation.attributes.brickable_types translation.

Finally, you will have to translate each registered brickable label translation.

Implementation

Models

Implement the HasBrickables interface and use the HasBrickablesTrait trait to any Eloquent model that you want to be able to be associated to content bricks to.

Routes

Add the web routes that will be required by the content bricks admin panel:

These routes are consuming the Okipa\LaravelBrickables\Controllers\BricksController controller by default.

To customize the admin panel actions, you can add routes inside or outside of the brickables route group.

Check the Empower bricks with extra abilities part to get more information about the customization possibilities.

How to

Define brick constraints for model

In your Eloquent model, you optionally can define constraints:

• Define the brickables that your model is being authorized to manage,
• Define the minimum number of bricks of each brickable that the model must hold,
• Define the maximum number of bricks of each brickable that the model can hold.

In this example:

• The Page model will only be allowed to handle OneTextColumn bricks.
• The admin panel will only allow to manage OneTextColumn bricks.
• The admin panel will not allow to remove a OneTextColumn brick if there is only one left.
• The admin panel will not allow to add more OneTextColumn bricks if 3 are already added.
• Programmatically clearing all bricks for this model will keep the OneTextColumn one with the highest position.
• Programmatically adding a 4th OneTextColumn brick will thrown a ModelHasReachedMaxNumberOfBricksException.

Important note: you can disable a brickable management for a model by setting its max number to 0.

Add content bricks

Associate a single content brick to an Eloquent model:

You also can associate several content bricks at once:

Update a content brick

Just update your content brick as you would fo for any other Eloquent model instance:

Remove content bricks

Just delete your content brick as you would fo for any other Eloquent model instance:

Clear all the content bricks associated to an Eloquent model, or only those with specific brickable types:

Clear all the content bricks except specific ones:

Note

• According to the number of bricks constraints defined in the Eloquent model, these methods could be brought to keep the min number of bricks instead of removing the targeted brick(s).

Set content bricks order

By default, all bricks are ordered by their creation order (last created at the end).

The Brick model uses the spatie/eloquent-sortable package to handle the content bricks positioning.

To see how to use this third party package, check its documentation here: https://github.com/spatie/eloquent-sortable.

You may note that the bricks order management is already handled in the provided admin panel and that you can use it as is.

Retrieve content bricks

Retrieve all the content bricks associated to an Eloquent model, or only those with a specific brickable type:

Get the first content brick associated to an Eloquent model, or the one with a specific brickable type:

Query content bricks

As each brickable can specify its own brick model, you should query content bricks and then cast them ito the model defined in their related brickable:

Display content bricks

Display a single content brick in your view:

Or display all the content bricks associated to an Eloquent model:

Or only display content bricks from given brickable types:

Retrieve brickables

Get all the registered brickables:

Get all the brickables that are allowed to be added to an Eloquent model:

Retrieve a brickable from a brick instance:

Manage model content bricks

Use the ready-to-use admin panel to manage related-model content bricks:

Customize the admin panel views by publishing them.

:bulb: Tips

• It is highly recommended adding a javascript confirmation request to intercept the content bricks delete action, otherwise the removal action will be directly executed without asking the user agreement.

Create your own brickable

Create a new brickable class that extends class in your app/vendor/Brickables directory.

In your brickable class, you can override any method from the extended abstract Brickable to customize the brickable behaviour.

Then, register it in your config('brickables.registered') array:

Finally, create the brickable views in the resources/views/vendor/laravel-brickables/my-new-brickable directory (you can customize the view paths in your MyNewBrickable class):

• the brick view that will be used to display your MyNewBrickable brick in the front.
• the form view which will embed the form inputs that will be used to CRUD your MyNewBrickable bricks in the admin panel.

You should see the existing brickables implementation to get familiar with their management.

Your brickable is now ready to be associated to Eloquent models.

Define brickable css and js resources

You have the possibility to define a css and js resource to customize each brickable rendering.

In addition, this package embeds a smart resource management system : it determines which brickables are actually displayed on the page and only loads the resources once, even if a brickable is used more than once on the page.

To benefit from this feature, make sure you have implemented the @brickablesCss and the @brickablesJs directives as precised in the installation part.

Then, define which resources your brickables are using:

Finally, use the @brickableResourcesCompute directive under the last displayed brick in the page:

:warning: Important: Please note that you will always have to declare the @brickableResourcesCompute directive from a child view from the one which is declaring the brickablesCss and @brickablesJs directives. As you can see in our example, the @brickableResourcesCompute blade directive is called on the page.blade.php view, which is a child of layout.blade.php (where the brickablesCss and @brickablesJs are declared). This is the only way for this package to know which brickables are actually displayed on the page, in order to intelligently load the resources.

Empower brickables with extra abilities

To add abilities to your brickables, you will have to implement the additional treatments in the brickable-related brick model and brick controller.

Let's add the ability to manage images in our MyNewBrickable from the previous example.

First create a MyNewBrickableBrick model that will extend the Okipa\LaravelBrickables\Models\Brick one in order to give the image management ability to this brick.

Then, create a MyNewBrickableBricksController model which will extend the Okipa\LaravelBrickables\Controllers\BricksController one where you will add the image management treatments.

Do not forget to validate your form inputs:

Finally, tell you brickable to use your MyNewBrickableBrick model and your MyNewBrickableBricksController controller:

That's it, your custom model and controller will now be used by the MyNewBrickable brickable.

Get Eloquent model from request

It can be useful to retrieve the Eloquent model from the request, for navigation concerns, for example.

This helper will be able to return the related model when navigating on the brickables form views (bricks creation and edition requests).

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

• Arthur LORENT
• All Contributors

License

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