Creating Page Components

Page components usually have two main parts:

  1. The Component Class, which defines what attributes the component will have
  2. View files, which are used to display component's output


Creating Components

Textstem provides a convenient Artisan command to generate new components quickly. Run the following command to make a new Card component:

 php artisan textstem:make:pagecomponent card

This will generate a compont class in your project

  • app/Wrangler/Components/Card.php

It will also create some supporting files in

  • resources/views/wrangler/components/card

The Component class (Card.php) will look like this

<?php

namespace App\Wrangler\Components;
use Textstem\Wrangler\ActiveComponent;

use Illuminate\Http\Request;
use Textstem\Models\WranglerPage;

class Card extends ActiveComponent
{
    public static string $description="Write a description";
  
    public $config;

    public array $editSetup = [
 		[
            'name' => 'template',
            'controltype' => 'select-template',
            'value' => 'default',
            'size' => 1
        ] 
    ];


    public function render(Request $request, WranglerPage $wranglerPage)
    {
        $view = $this->getView();
        return view($view, $this->config)->render();
    }

    public function preview()
    {
        $view = $this-> getPreview();
        return view($view, $this->config)->render();
    }
}

All components should implement the WranglerComponent Contract. Creating a new custom component that extends the ActiveComponent base class is the simplest way to do this.

Editor Setup

The $editSetup is an array of attributes that define the component and are used to create an admin form for updating the component. Each attribute should have a controltype, label, default value and so on. Some control types require some additional parameters. For example, a select requires any 'options' array.

The following are valid properties used to define an attribute:

  • name - this is passed to to templates as a variable name, so be a single word, no spaces, and should start with a letter or the underscore character
  • label - this is displayed to Admin users in the editor
  • value - the default value
  • controltype - the type of input used by the editor (select, text etc)
  • instructions - additional instructions shown in the editor
  • casts - specify the type of the value (most controls will default to string)
  • options - some control types expect an array of options to select from
  • size - the colum width of the input group (1 to 4)

 

 

Rendering Components

The render and preview methods of all components should return HTML .The render method is for the public view. The preview method is for admin views such as the page editor.

In the example above, the Card component will use Laravel's blade template. The getView method (inherited from the ActiveComponent class) returns the 'dot-path' to the blade template for the component.

In this example, the data() method is used to collect data for the view. This is a method inherited from the ActiveComponent and returns an array, merging the instance config and any additional scaffolding added to the component nstance.

Note - the preview method needs to return something without access to the request or current page. Some components are dynamic - and need the request or some data in a page to work their magic. In these case, the preview method should just return some placeholder to display. In the card example above, the component doesn't need access to the page or request, so it returns the same view as the actual render method.

The view file generated for our Card example above might look like this:

<div class="overflow-hidden bg-white shadow sm:rounded-lg my-4">
    <div class="px-4 py-5 sm:p-6">
        @if ($title)
            <h4 class="h4 mt-0">{{$title}}</h4>
        @endif
        {!! $content !!}
    </div>
</div>

The styles and structure of the output are generally customised for each site or theme (the example here uses Tailwind CSS)