verbant/wn-livewire-plugin

Plugin to use Livewire in Winter CMS

Maintainers

Details

github.com/wverhoogt/wn-livewire-plugin

Source

Issues

Installs: 1

Dependents: 0

Suggesters: 0

Security: 0

Stars: 1

Watchers: 1

Forks: 0

Open Issues: 0

Type:winter-plugin

v0.9.0-beta 2023-07-17 13:51 UTC

Requires

MIT d1b85266ee665e0ed6c7bdbda29e950a114979ed

  • Wim Verhoogt <wim.woop@verbant.nl>

plugincmslivewirewinter

This package is not auto-updated.

Last update: 2024-05-08 15:22:33 UTC

README

The verbant/wn-livewire-plugin package provides the option to load Livewire components in WinterCMS projects.

Installation

You can install the package via composer:

composer require verbant/wn-livewire-plugin

Usage

This package supports Livewire components in a theme, in plugins or in the backend. Each of these usages requires a specific approach:

Theme usage

The plugin creates a menu entry in the top menubar, ¨Livewire¨ and a ¨Conponents¨ side menu entry. You can add a new component or modify an existing one. The Markup tab contains the Livewire-markup, the code tab contains the Livewire PHP-class containing the callback functions.

Plugin component usage

Component registration

Component and backend Livewire components require registration, so that Livewire can find the markup and its backing class. You register these components by creating a public function registerLivewireComponents() returning information for the components as an array. Each element of this array has the following layout:

    'component name' => ['LivewireClass' => Class of Livewire, 'ViewName' => 'name of view in components|controllers/component name', 'ViewPath' => "full path to this view"];

Component usage

A plugin can define a component which has both Livewire-markup and a Livewire PHP-class. You can still have other component partials, and render these in the usual way using the twig {% partial %} twig directive. The Livewire-markup is rendered by the {% component %} directive and renders the markup as defined as the ViewName during registration.

Plugin backend usage

A plugin can have a backend controller which supports Livewire components. The markup will probably in the controllers/controller name directory. The Livewire PHP-class could be there as well. To render the Livewire-component, call

$this->renderLivewire("name", [optional arguments]); somewhere in a PHP markup-file.

Installation

Add the following tags in the head tag, and before the end body tag in your page or layout.

<html>
<head>
    ...
    {{ livewireStyles() }}
</head>
<body>
    ...
    {{ livewireScripts() }}
</body>
</html>

Examples

Theme example

Create a Livewire component by choosing ¨Livewire¨ from the top bar en then ¨Add +¨ from the sidebar. Name it counter. On the markup tab, enter:

<div class="input-group py-3 w-25">
    <button wire:click="add" class="btn btn-outline-secondary">
        Add
    </button>
    <div class="form-control">
      {{ count }}
    </div>
    <button wire:click="subtract" class="btn btn-outline-secondary">
        Subtract
    </button>
</div>

On the code tab, enter:

public $count = 1;

public function add()
{
  $this->count++;
}

public function subtract()
{
  $this->count--;
}

Note that the code editor flags an error on the top line. It doesn´t know that this code will be embedded in a class.

Create a page and on the markup tab enter:

<h3>Example</h3>
{% livewire "counter" with {'count': 2 } %}

And add the {{ livewireStyles() }} and {{ livewireScripts() }} on this page or on a layout, used by it.

Plugin component example

Create a plugin and a component named ¨lw¨ within that plugin. In the Plugin.php file include:

<?php namespace YourNamespace\PluginName;

use YourNamespace\PluginName\Components\Lw;
use YourNamespace\PluginName\Components\Lw\Lw as LiveW;

class PluginName extends PluginBase
{
  public function registerComponents()
  {
    return [
      Lw::class => 'lw',
    ];
  }
  
  public function registerLivewireComponents()
  {
    return [
      'lw' => ['LivewireClass' => LiveW::class, 'ViewName' => 'default', 'ViewPath' => $this->getPluginPath() . '/components/lw'],
    ];
  }

  // other plugin code
}

In the components directory create a file Lw.php:

<?php namespace YourNamespace\PluginName\Components;

use Cms\Classes\ComponentBase;

class Lw extends ComponentBase
{
  use \Verbant\Livewire\Traits\LivewireComponent;
  /**
   * Gets the details for the component
   */
  public function componentDetails()
  {
    return [
      'name'        => 'lw Component',
      'description' => 'No description provided yet...'
    ];
  }

  /**
   * Returns the properties provided by the component
   */
  public function defineProperties()
  {
    return [];
  }
}

The LivewireComponent trait adds a onRender() function which takes care of rendering the markup as Liveewire markup.

In the components/lw directory create 2 files: default.twig with contents:

<div class="input-group py-3 w-25">
    <button wire:click="add" class="btn btn-outline-secondary">
        Add
    </button>
    <div class="form-control">
      {{ count }}
    </div>
    <button wire:click="subtract" class="btn btn-outline-secondary">
        Subtract
    </button>
</div>

And Lw.php with contents:

public $count = 1;

public function add()
{
  $this->count++;
}

public function subtract()
{
  $this->count--;
}

You can now add this component to a CMS page by dragging it from the side bar. Note that you can pass variables to the component, which will be made available to the Livewire component, like

{% component 'lw' count=5 %}

Backend example

Create a plugin and a controller named ¨lwc¨ within that plugin. In the Plugin.php file include:

<?php namespace YourNamespace\PluginName;

use System\Classes\PluginBase;
use YourNamespace\PluginName\Controllers\Lwc\Lwc as LiveWc;

class Plugin extends PluginBase
{
  public function registerLivewireComponents()
  {
    return [
      'lwc' => ['LivewireClass' => LiveWc::class, 'ViewName' => 'default', 'ViewPath' => $this->getPluginPath() . '/controllers/lwc'],
    ];
  }

  // other plugin code
}

In the controllers directory create a file Lwc.php:

<?php namespace YourNamespace\PluginName\Controllers;

use BackendMenu;
use Backend\Classes\Controller;

/**
 * Lw Controller Backend Controller
 */
class Lwc extends Controller
{
  use \Verbant\Livewire\Traits\LivewireController;
  /**
     * @var array Behaviors that are implemented by this controller.
     */
    // public $implement = [
    //     LivewireController::class
    // ];

    public function __construct()
    {
        parent::__construct();
        // possible setContext() and other code
    }
    
    public function index()
    {
    }
}

The LivewireController trait provides the renderLivewire function.

In the controllers/lwc directory create 2 files: lwc.twig with contents:

<div class="input-group py-3 w-25">
    <button wire:click="add" class="btn btn-outline-secondary">
        Add
    </button>
    <div class="form-control">
      {{ count }}
    </div>
    <button wire:click="subtract" class="btn btn-outline-secondary">
        Subtract
    </button>
</div>

And Lwc.php with contents:

public $count = 1;

public function add()
{
  $this->count++;
}

public function subtract()
{
  $this->count--;
}

You can now add this component to a backend view by calling

$this->renderLivewire("lwc", [optional value for the component]);

Note that for the backend you do not need to add the { livewireStyles() }} and {{ livewireScripts() }} directives.

License

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