How to Build an OctoberCMS Widget Plugin

This article delves into building an OctoberCMS backend widget plugin, expanding on basic plugin creation. We'll develop a "Quick Note" widget, mirroring WordPress's quick draft functionality.

Key Concepts:

• Plugin scaffolding with php artisan create:plugin.
• Extending the User model to manage user-specific notes.
• Implementing a Report Widget (QuickNoteWidget) for the backend dashboard.
• Defining widget properties (defineProperties) for customization (e.g., hiding the note list, changing the title).
• Utilizing controllers and models for form handling, note management (CRUD operations).

Building the Quick Note Widget:

We'll create a widget that allows users to quickly add and manage short notes directly from their OctoberCMS dashboard.

1. Plugin Setup:

Generate the plugin using the command line:

php artisan create:plugin RAFIE.quicknote

Update Plugin.php with plugin details:

public function pluginDetails()
{
    return [
        'name'        => 'Quick Note Widget',
        'description' => 'Quickly add and manage short notes.',
        'author'      => 'RAFIE Younes',
        'icon'        => 'icon-pencil'
    ];
}

And the version.yaml:

# uploads/version.yaml
1.0.1: First version of quicknote
1.0.2:
  - Created Notes Table
  - create_notes_table.php

2. Database Model:

Create the Note model and migration:

php artisan create:model RAFIE.quicknote Note

The migration (create_notes_table.php) will look like this:

Schema::create('rafie_quicknote_notes', function ($table) {
    $table->engine = 'InnoDB';
    $table->increments('id');
    $table->string('title', 255);
    $table->text('description')->nullable();
    $table->integer('user_id')->unsigned()->index();
    $table->timestamps();
});

Refresh the plugin:

php artisan plugin:refresh RAFIE.quicknote

Extend the User model in Plugin.php:

public function boot()
{
    User::extend(function ($model) {
        $model->hasMany['notes'] = ['RAFIE\Quicknote\Models\Note'];
    });
}

The Note model (models/Note.php):

use October\Rain\Database\Traits\Validation;

class Note extends Model
{
    use Validation;

    public $table = 'rafie_quicknote_notes';

    protected $guarded = ['*'];

    protected $rules = [
        'title' => 'required|min:4'
    ];

    public $belongsTo = ['user' => ['Backend\Models\User']];
}

3. Widget Creation:

Create QuickNoteWidget.php (within the widgets folder):

class QuickNoteWidget extends ReportWidgetBase
{
    public function render()
    {
        $notes = BackendAuth::getUser()->notes;
        return $this->makePartial('notes', ['notes' => $notes]);
    }

    public function defineProperties()
    {
        return [
            'title' => [
                'title' => 'Widget Title',
                'default' => 'Quick Note'
            ],
            'showList' => [
                'title' => 'Show Notes List',
                'type' => 'checkbox'
            ]
        ];
    }
}

Register the widget in Plugin.php:

public function registerReportWidgets()
{
    return [
        'RAFIE\Quicknote\QuickNoteWidget' => [
            'label' => 'Quick Notes',
            'context' => 'dashboard'
        ]
    ];
}

Create the partial _notes.htm (in widgets/quicknotewidget/partials):

<div class="report-widget">
    <h3 id="this-gt-property-title">{{ $this->property('title') }}</h3>
    <div class="pane">
        @if ($this->property('showList'))
            <ul class="list-nostyle">
                @foreach ($notes as $note)
                    <li class="list-group-item">{{ $note->title }}</li>
                @endforeach
            </ul>
        @endif
        <br/>
        {{ Form::open(['url' => Backend::url('rafie/quicknote/notes/store'), 'method' => 'POST']) }}
        <div class="form-group">
            <input class="form-control" type="text" name="title" placeholder="Title" required/>
        </div>
        <div class="form-group">
            <textarea class="form-control" name="description" id="" cols="30" rows="10"
                      placeholder="Your note..."></textarea>
        </div>
        <div class="form-group">
            <button type="submit" class="btn btn-primary" value="Submit">Submit</button>
            <a href="https://www.php.cn/link/b4c174fbc208372a8facfe462868ebf1'rafie/quicknote/notes/index') }}">Manage your notes</a>
        </div>
        {{ Form::close() }}
    </div>
</div>

4. Controller (controllers/Notes.php):

class Notes extends Controller
{
    public function store()
    {
        $note = new Models\Note;
        $note->title = Input::get('title');
        $note->description = Input::get('description', null);
        $note->user_id = BackendAuth::getUser()->id;

        if ($note->save()) {
            Flash::success('Note added successfully.');
        } else {
            Flash::error('Validation error');
        }

        return Redirect::to(Backend::url());
    }

    // ... (rest of the controller code as described in the original response) ...
}

Remember to complete the remaining controller actions (index, create, update, delete) and their associated configuration files (config_list.yaml, config_form.yaml, columns.yaml, fields.yaml, partials) as detailed in the original response. The image showing the controller structure is helpful:

5. Backend List and Form Configuration:

Configure the backend listing and form using config_list.yaml and config_form.yaml as shown in the original response. Pay close attention to the listExtendQueryBefore method in the controller to ensure only the current user's notes are displayed. The screenshot of the form configuration is useful:

This detailed breakdown should help you build the Quick Note widget. Remember to consult the OctoberCMS documentation for further assistance and to adapt the code to your specific needs. The FAQs at the end of the original response provide additional helpful information for working with OctoberCMS.

The above is the detailed content of How to Build an OctoberCMS Widget Plugin. For more information, please follow other related articles on the PHP Chinese website!