Building a Component

Introduction

In this section, you will learn how to build component and not how to attach components to theme templates. Building a component involves creating the class of your component by extending the BaseComponent class and some of its methods, then registering your component to be displayed on your site and available from the Admin Interface.

Components live in the /components subdirectory of an extension directory.

extensions/
  igniter/
    helloworld/         		<=== Extension directory
      components/				<=== Components subdirectory
        block/       			<=== Component partials directory
          default.blade.php        	<=== Component default partial (optional)
        HelloBlock.blade.php    		<=== Component class file

Defining the component

To begin, you can either use your preferred file manager to create files and directory for the Block component or simply call the following command from the application directory to generate a component with basic files and directories:

php artisan create:component Igniter.HelloWorld Block

Component class

The component class file should extend the \System\Classes\BaseExtension base class and define the functionality and properties of the component. The following is an example defines the Block component:

namespace Igniter\HelloWorld\Components;

class Block extends \System\Classes\BaseComponent
{
   	public function defineProperties()
    {
        return [];
    }
    
    public function alerts()
    {
        return ['Success Alert', 'Warning Alert', 'Danger Alert'];
    }
}

The component properties and methods are available on the page or layout its attached through the component variable which corresponds to the alias of the component. For example, if the HelloBlock component was defined on a page or layout as '[helloBlock]', you will be able to access its alerts through the $helloBlock variable:

@foreach ($helloBlock->alerts() as $message)
    <p>{{ $message }}</p>
@endforeach

Component registration

Components must be registered by overriding the registerComponents method within the Extension registration class. This lets the app know about the component and gives it an alias name for its use within themes. To register the Block component with the default alias name helloBlock, you may override the registerComponents method:

public function registerComponents()
{
    return [
        \Igniter\HelloWorld\Components\Block::class => [
            'code' => 'helloBlock',
            'name' => 'Name of the hello block component',
            'description' => 'Description of the hello block component',
        ],
    ];
}

More information on using components can be found in the Components article.

Component properties

Components can be configured using properties defined for each component by overriding the defineProperties method. Let's define a maxItems property to limit the number of alerts allowed

public function defineProperties()
{
    return [
        'maxItems' => [
             'title'      	=> 'Max items',
             'description'  => 'The most number of alert items allowed',
             'default'      => 10,
             'type'         => 'text',
        ]
    ];
}

The method should return an array with the property keys as indexes and the property parameters as values. The property keys are used to access the component property values within the component class.

Key	Description
label	required, the property label, it is used by the component Selector in the Admin Interface.
type	optional, specifies the property type. The type defines the form field type. Currently supported types are text, number, checkbox, radio, select and selectlist. Default value: text.
default	optional, the default property value.
comment	optional, the property description, it is used by the component Selector in the Admin Interface.
placeholder	optional placeholder for text and select properties.
options	optional array of options for checkbox, radio, select, selectlist properties.

The options property key can be static or dynamic. Using the maxItems property, let's define static options:

public function defineProperties()
{
    return [
        'maxItems' => [
            ...
            'type'   => 'select',
            'options' => [
                '20' => '20 Per page', 
                '50' => '50 Per page'
            ]
        ]
    ];
}

Dynamically, the options can be fetched by omitting the options key from the property definition and defining a method that returns the list of options. The method name should be the studly cased name of the property. For example, getPropertyOptions where Property is the name of the property. In this example, we'll define a method for the maxItems property.

public function defineProperties()
{
    return [
        'maxItems' => [
            ...
            'type'   => 'select',
        ]
    ];
}

public function getMaxItemsOptions()
{
    return [
        '20' => '20 Per page', 
        '50' => '50 Per page'
    ];
}

Reading the property value from within the component class:

// Get a single value
$maxItems = $this->property('maxItems');

// Get a value and return a default value if it doesn't exist
$maxItems = $this->property('maxItems', 8);

// Get all properties as array
$properties = $this->getProperties();

Accessing the property value from a component partial:

{{ $__SELF__->property('maxItems') }}

Component partials

Besides the default partial, components can also provide additional partials which can be used within other template files or in the default partial itself.

extensions/
  igniter/
    helloworld/
      components/
        partials/				<=== Component shared partials directory
          shared.blade.php			<=== Component shared partial file
        block/ 
          default.blade.php
          pagination.blade.php        <=== Component additional partial
        HelloBlock.blade.php    		<=== Component class file

Components can share partial files by placing them in the components/partials subdirectory of the extension directory.

Component initialization

Sometimes you might want to handle some initialization logic before AJAX handlers and before the execution cycle of the page. You can override the initialize method in the component class to handle such initialization logic.

Component class methods

The following methods are supported in the component class:

Method	Description
initialize()	initialization method, called when the component is attached to a page or layout
onRun()	override to hook into the page's execution life cycle.
onRender()	override to handle specific logic before rendering the default partial of the component.
renderPartial()	render a specified component partial or shared partial.

Page execution cycle handlers

Every time the page loads, the Main Controller executes the onRun method of the attached components. Overriding the method in the component class allows components to hook into the page execution cycle. Let's inject some variables into the page:

public function onRun()
{
    $this->page['var'] = 'value';
}

Handler functions can be defined in the layout and page PHP code section and component classes. These handlers are executed in the following sequence:

• onInit layout method.
• onInit page method
• onStart layout method
• onRun layout components method
• onStart page method
• onRun page components method
• onEnd page method
• onEnd layout method

Defining AJAX handlers

Components class can define AJAX event handlers can be defined in the component class as they can be defined in the page or layout PHP code section.

public function onAddItem()
{
    $value1 = post('value1');
    $value2 = post('value2');
    $this->page['result'] = $value1 + $value2;
}

If the alias for this component was helloBlock this handler can be accessed by helloBlock::onAddItem.

Please see the Handling AJAX Requests article for more details.

Inject page assets

Use the addCss and addJs controller methods to add assets to the pages or layouts the components are attached to:

public function onRun()
{
    // Assets path that begins with a slash (/) is relative to the website root directory
    $this->addJs('/extensions/igniter/helloworld/assets/js/controls.js');

    // Paths that does not begin with a slash is relative to the component directory
    $this->addJs('assets/js/controls.js');
}