Content Blocks

The blocks component is a very powerful content management functionality that allows you to quickly assign pieces of dynamic content to your content pages or other custom entities of yours that support block assignment.

In order to provide you with a complex crud functionality inside the admin, the blocks crud implements the following out of the box:

Admin Interface

Before going deeper, you should know that there's already a section in the admin from where you can manage all your content.

You can find the blocks section inside Admin -> Manage Content -> Blocks.
Feel free to explore all available options this section offers.

Blocks List

How It Works

First of all, let's understand the architecture behind content blocks and their workflow.

The Workflow

Configuration File

The blocks component comes bundled with a config/varbox/blocks.php config file.

From here you can specify what block types your application contains and a custom upload configuration for blocks only, if you happen to use file uploads.

You should specify a new block type for any different piece of content present in your frontend, that you wish to treat as a content block.

You should specify a custom upload config only if at least of one of your block types uses file uploads and you want to overwrite the default configuration.

Generated Files

Running the artisan command for making blocks, will generate all necessary files for a block inside the app/Blocks/{YourType} directory. The generated files for each block type are:

app/Blocks/{YourType}/Composer.php

This is the view composer for the block. In this view composer you can also add any additional logic your block type might have. It already exposes to the view the following variables:

The view composer is automatically bound to the front.blade.php block view file, so you don't have to worry about that, it just works.

app/Blocks/{YourType}/Views/front.blade.php

This is the actual blade view that will be rendered where you assign your block. In here, you should add the code for rendering your actual piece of content.

app/Blocks/{YourType}/Views/admin.blade.php

This blade will be used inside the admin panel when you add / edit a block of this type. In here, you should add your fields that are specific for this block type.

Generate New Block

In order to be able to create blocks from the admin panel and assign them to your entities, you first need to define the block types your application has.

Define The Type

Inside the config/varbox/blocks.php config file, specify your block type

'types' => [

    'YourType' => [

        // The pretty formatted block type name. 
        // This is mainly used inside the admin panel, in places that reference blocks.
        'label' => 'Your Block Type',

        // The full namespace to the block's view composer. 
        // Each block you create will have a view composer. 
        // You can define any extra logic in the block's view composer class.
        'composer_class' => 'App\Blocks\YourType\Composer',

        // The full path to the block's views directory. 
        // When creating a new block type, you will also have two views (front & admin).
        'views_path' => 'app/Blocks/YourType/Views',

        // The name of the image used as block type preview in admin. 
        // This should contain the full path to an image inside the "public/" directory. 
        // The path is relative two the "public/" directory.
        'preview_image' => 'images/blocks/your-type.jpg',
    ],

],

Run The Command

After you've defined your block type, you can generate the block files by running the below command. Please note that the command accepts a single argument, which is your block type.

php artisan varbox:make-block YourType

Running the command, will generate all necessary files for a block inside the app/Blocks directory.

Check out the generated files section to see what those files are and how they're being used.

Manage Uploads

If some of your blocks require file uploads (eg. images), please know that you can overwrite their specific configuration from inside the config/varbox/blocks config file, specifically from the upload section.

To learn more about model specific upload configuration, please read this documentation section.

Custom Entity Blocks

As you've probably noticed by now, after generating a block and creating a record from the admin panel, you can instantly assign it to a page.

But what about adding the block assignment functionality to other custom entities of yours, such as a blog post? Let's learn how you can achieve this.

Apply The Trait

Your models should use the Varbox\Traits\HasBlocks trait and the Varbox\Options\BlockOptions class. The trait contains an abstract method getBlockOptions() that you must implement yourself.

Here's an example of how to implement the trait:

<?php

namespace App\Models;

use Illuminate\Database\Eloquent\Model;
use Varbox\Options\BlockOptions;
use Varbox\Traits\HasBlocks;

class YourModel extends Model
{
    use HasBlocks;

    /**
     * Set the options for the HasBlocks trait.
     *
     * @return BlockOptions
     */
    public function getBlockOptions(): BlockOptions
    {
        return BlockOptions::instance()
            ->withLocations(['content', 'sidebar']);
    }
}

Add Blade Code

Inside your edit blade file, add the following code responsible for generating the block assignment html component.

<div class="col-md-12">
    ...
</div>

@if($item->exists)
    @include('varbox::helpers.block.container', [
        'model' => $item, 
        'revision' => $revision ?? null
    ])
@endif

Add Controller Code

Finally, you'll want to actually save the assigned blocks for your entity, so inside your admin controller, specifically in the update method, use the saveBlocks() method to save your assigned blocks.

public function update(Request $request, YourModel $item)
{
    return $this->_update(function () use ($request, $item) {
        ...

        $item->saveBlocks($request->input('blocks') ?: []);

        ...
    }, $request);
}

Now you can assign blocks for your custom entities and display them in your frontend views.

Display Assigned Blocks

After you've generated a block, created an entry for it in the admin and assigned it to your entities, it's time to actually display the block's contents in your frontend.

You can display all assigned blocks from a location by using the renderBlocks() method present on the HasBlocks trait, inside your frontend blade view.

{!! $item->renderBlocks('content') !!}

This line of code will output the concatenated parsed html for all blocks assigned to the "content" location. That method uses the app/Blocks/{YourType}/front.blade.php of each block type as the html source, so make sure you update those files accordingly.

Useful Methods

If you want to manually leverage the Varbox\Traits\HasBlocks trait's capabilities, read on.

Fetch Blocks

You can fetch a model record's blocks by using the revisions() morph many relation present on the Varbox\Traits\HasBlocks trait.

$model = YourModel::find($id);
$blocks = $model->blocks;

Fetch Locations

You can fetch a model's available block locations by using the getBlockLocations() method present on the Varbox\Traits\HasBlocks trait.

$locations = app(YourModel::class)->getBlockLocations();

Get Blocks In Location

You can get all assigned blocks in a certain location for a model record by using the getBlocksInLocation() method present on the Varbox\Traits\HasBlocks trait.

$model = YourModel::find($id);
$blocks = $model->getBlocksInLocation('content');

Get Blocks Of Location

You can get all potential blocks that could be assigned to a location by using the getBlocksOfLocation() method present on the Varbox\Traits\HasBlocks trait.

$blocks = app(YourModel::class)->getBlocksOfLocation();

Sync Blocks

You can sync all assigned blocks for a model record by using the saveBlocks() method present on the Varbox\Traits\HasBlocks trait.

$blocks = [
    [
        $blockIdOne => [$blockLocationOne, $blockOrderOne]
    ],
    [
        $blockIdTwo => [$blockLocationTwo, $blockOrderTwo]
    ],
    ...
];

$item = YourModel::find($id);
$item->saveBlocks($blocks);

Assign Block

You can assign a block for a model record by using the assignBlock() method present on the Varbox\Traits\HasBlocks trait.

$item = YourModel::find($id);
$item->assignBlock($blockModel, $blockLocation, $blockOrder ?? null);

Un-assign Block

You can unassign a block for a model record by using the unassignBlock() method present on the Varbox\Traits\HasBlocks trait.

$item = YourModel::find($id);
$item->unassignBlock($blockModel, $blockLocation, $blockPivotId);

Configuration

The blocks configuration file is located at config/varbox/blocks.php.

For more information on how you can customize the content management components, please read the comments from their configuration files.

Overwrite Bindings

In your projects, you may stumble upon the need to modify the behavior of these classes, in order to fit your needs. Varbox makes this possible via the config/varbox/bindings.php configuration file. In that file, you'll find every customizable class the platform uses.

For more information on how the class binding works, please refer to the Custom Bindings documentation section.

The block classes available for binding overwrites are:

Varbox\Models\Block

Found in config/varbox/bindings.php at models.block_model key.
This class represents the block model.

Varbox\Controllers\BlocksController

Found in config/varbox/bindings.php at controllers.blocks_controller key.
This class is used for interactions with the "Admin -> Manage Content -> Pages" section.

Varbox\Requests\BlockRequest

Found in config/varbox/bindings.php at form_requests.block_form_request key.
This class is used for validating any block when creating or updating.

Varbox\Filters\BlockFilter

Found in config/varbox/bindings.php at filters.block_filter key.
This class is used for applying the filtering logic.

Varbox\Sorts\BlockSort

Found in config/varbox/bindings.php at sorts.block_sort key.
This class is used for applying the sorting logic.