Made withOctober CMSTutorial

Making Websites With October CMS - Part 23 - Extending User Plugin

W

Watch and Learn

Creator on the October CMS channel

Watch on YouTube ↗

17K viewsNov 21, 201616:41 runtime

Learn the best-practice method for extending plugins in October CMS without modifying core files. This tutorial demonstrates how to add custom fields, like a Facebook URL and a biography, to the RainLab User plugin. You will see how to create a new plugin, write a database…

Chapters

#octobercms#tutorial#cmscrm

This document outlines the key concepts for extending the October CMS User plugin with custom fields, as demonstrated in the video.

Plugin Extension Strategy

The primary takeaway is to always extend plugins by creating your own plugin, rather than modifying the original plugin's files directly.

Important
Modifying core plugin files (like those in vendor/rainlab/user) is a bad practice. Your changes will be lost when the plugin is updated. The correct method is to create a separate plugin that hooks into the original.

Step 1: Create a Database Migration

To store an extra user profile data, you first need to add columns to the users database table. This is done with a migration.

Create a New Plugin: Use the Builder or php artisan create:plugin to create a new plugin (e.g., WatchnLearn.Profile).
Create a Migration File: In your plugin's updates directory, create a new PHP file (e.g., add_new_fields.php).
Write the Migration Logic:
- Use Schema::table('users', ...) to modify the existing users table.
- The up() function adds the new columns.
- The down() function removes them. This is crucial for rollbacks and plugin refreshes.

// In updates/add_new_fields.php

class AddNewFields extends Migration
{
    public function up()
    {
        Schema::table('users', function($table)
        {
            $table->string('facebook')->nullable();
            $table->text('biography')->nullable();
        });
    }

    public function down()
    {
        Schema::table('users', function($table)
        {
            // Use an array to drop multiple columns
            $table->dropColumn(['facebook', 'biography']);
        });
    }
}

Step 2: Run the Migration

Register the Migration: Add your new migration file to your plugin's version.yml.

1.0.1: First version of Profile plugin
1.0.2:
    - 'Add new fields for users.'
    - updates/add_new_fields.php

Run the Refresh Command: Use the command line at the root of your October CMS project to run the migration.
```
php artisan plugin:refresh WatchnLearn.Profile
```
Verify: Check your database (e.g., with an SQLite browser) to confirm the new facebook and biography columns exist in the users table.

Step 3: Extend the Backend Form

With the database ready, you can now add the fields to the User management form in the backend.

Edit Plugin.php: Open the Plugin.php file in your custom plugin.
Use the boot() Method: The boot() method is executed on every page load, making it the perfect place to register listeners.
Hook into extendFormFields: Listen for the extendFormFields event on the Users controller.

Tip
This technique allows you to add fields to almost any backend form in October CMS without editing YAML files. The target is usually [Author]\[Plugin]\Controllers\[ControllerName].

// In plugins/watchlearn/profile/Plugin.php

use RainLab\User\Controllers\Users as UsersController;

class Plugin extends PluginBase
{
    // ...

    public function boot()
    {
        UsersController::extendFormFields(function($form, $model, $context)
        {
            // Add fields to a new 'Profile' tab
            $form->addTabFields([
                'facebook' => [
                    'label' => 'Facebook',
                    'type' => 'text',
                    'tab' => 'Profile'
                ],
                'biography' => [
                    'label' => 'Biography',
                    'type' => 'textarea',
                    'tab' => 'Profile'
                ]
            ]);
        });
    }
}

After completing these steps, the User edit page in the backend will show a new "Profile" tab containing the Facebook and Biography fields, which will save data to the new columns in the database.

Introduction: Extending the User Plugin

In this episode, we are going to be extending a user plugin with a few fields. We are going to add a Facebook field to our users and also biography so that our users can input their Facebook page or add some information about themselves. As you will see, October has this pretty well covered, so it's not going to be hard at all. October already has some hooks for you to hook into other plugins and extend them. So this episode isn't just about the users plugin, but it can be applied to whatever plugin you want.

So first of all, let's go to our code editor, and we're going to go to RainLab User. And as you can see, the user has some models, and one of those models is the user model. So these are our users essentially.

And if we go to user/fields.yaml, we can see all the available fields that we have for our user. So if I click on John Doe right here, we can see the fields like email, reset password, password confirmation, groups, and so on. And that is all reflected right here. So password confirmation, password, create, you have this send invites, email, and so on. So you have those fields.

Now, what you could do is just add those fields right here, and that would kind of work, but whenever you update that plugin, all of that information would be gone. So we don't want to do it that way.

Creating a New Plugin with Builder

The way that we want to do it is create our own plugin and then with that plugin extend the user plugin. So I'm going to go to Builder and create a new plugin. So, create plugin, and I'm just going to call it Profile. Click okay.

Now we have our plugin created. If we go to our code editor, we can go to plugins/watchlearn/profile and now we have that plugin right here.

Understanding Database Migrations

So, in that plugin, we are going to extend the user's plugin from RainLab. So we want to add a Facebook field and biography field to our users, but to do that we would have to create database columns or fields in our table to account for that, so that we can save in some place that Facebook or biography.

So to do that, we are going to be using migrations. So migrations, I'm not going to go into much detail about it. You can read about it on Larevel's page. So migrations are essentially abstracts of your database, and once you migrate them, they will create fields and columns in your database. You write code for migration, and that code is very simple to understand as you will see. So let's see an example of that migration.

So I'm going to go to user plugin, so RainLab User, and then you would go to updates. And these are all the migrations for that plugin. So one of those migrations is called create_users_table.php. So if you click on it, you can see something like this. So this is the migration and these are the fields that you are creating in your database. So you just do table->increments('id'), name, email, password, activation_code, and so on. So I'm just actually going to copy all of this and then I'm going to create my own updates in my profile plugin. So we just go here and I'm going to create a call that migration add_new_fields.php.

Writing the Migration Logic

Okay, and paste this in. So the namespace is not going to be RainLab User, but it's going to be watchlearn profile. And then you leave all of this as it is. Instead of class CreateUsersTable, we are just going to call it AddNewFields. AddNewFields. And instead of this Schema::create, if you leave this as it is, the October or Laravel, which is running under October, is going to try to create the users table. We don't want to do that. We want to update the users table with our own fields. So instead of create, we are just going to write table right here. Okay. So the table is users. And I'm going to delete everything.

And now we are going to create our own migration. So first of all, we need a Facebook field in our database.

Okay, so we create the string type of field which is going to be called facebook and is going to be nullable. That just means that the user doesn't have to input anything into our field.

Defining the 'down' Reversal Function

Next thing we are going to do is create biography field. And it's also going to be nullable, but it's going to be a type of text so that the user can enter much more text than it could in the string field. Okay, so we got that covered.

One more, one more very important thing to do is to create this down function. So the down function is used when you want to refresh your database and start anew or when you wanna revert the database to the previous version, you want to drop some fields and so on. So you have to create that right here. And you have to especially create it for this case because if you leave this as it is when you refresh your plugin, it's going to delete the users table. So we don't want that. We just actually want to delete these two fields from the table.

Completing the Migration File

And to do that we're going to delete this, and instead of that, we're just going to do table->dropColumn(). So we just open up an array and set those fields right here. So a 'facebook' field and 'biography' field. So now whenever you refresh your plugin, it's just going to delete those two fields from the user table and then create them again if you are creating or if you are refreshing your plugin. If you are removing your plugin, then it's just going to remove all of these two fields from the users table, and that's it.

Now, in the version.yml file we are just going to add another point right here, which is going to be called add_new_fields.php. Okay, so that the October knows about it. And that's about it.

Running the Migration and Verifying Changes

Now what we have to do is run our migration. So once we run the migration, it's going to create those two fields in the users table hopefully. So to run the migration for our plugin, we are going to have to refresh the plugin, and you do that from the command line. So you go to the directory or folder where your October website is installed and do PHP artisan command. PHP artisan commands work with a lot of things in October and Laravel and I advise you to get familiar with them. I will definitely make a video about most of the available commands that you have for your command line for October CMS.

So we are just going to refresh our plugin and once you refresh it, it is going to run the migration for the plugin. So you do php artisan plugin:refresh, and then the namespace of the plugin... come on, what happened here... so, the namespace of the plugin, which is WatchnLearn.Profile in our case, and then the name of the plugin, and that should be it. You just hit enter.

Okay, I'm a little bit worried that it didn't say the add new fields. So we are going to check our database right now to see if those new fields have been created. Since I'm using the SQLite table for these examples, for our website I'm using this SQLite browser application. So we can check out our database. And as you can see, this is the users table, and if we click down you can see the name, email, password and so on, but at the end right here you can see the Facebook and bio. So these are the fields that we created via our migration.

Extending the Backend Form via Plugin.php

Now that we have those fields right here, we are going to extend the user plugin to display those fields in the administration because right now in our backend, there are no fields for adding Facebook links or biography text. So now let's actually extend the user plugin. We are going to go to plugin.php, so plugins/watchlearn/profile/Plugin.php.

And now we are going to use the controller of the users plugin, and we are going to use it as UsersController. Okay, so we can now use this name instead of all of this right here. So UsersController, and we are going to need that UsersController to extend the user's plugin. So I'm going to do it down here, and we're going to create a function called boot. So this is the October's function, and it's going to run before everything else gets displayed on the page. So it's going to go through that boot function, see that it is extending the user's plugin, and then it's going to do something.

Okay, so now that we did that, we are going to extend the form fields. So remember, right now in our users, we don't have any profile fields. So we need to add those profile fields right here. As I said before, you could technically go to the user and then go to models and fields, but we don't want to do that. We want to create those fields by extending the user plugin. And to do that, you would use the UsersController and then the extendFormFields function.

Okay, this a bit long. So we create a function that is using this form, model, and context variables. And now we can just add those fields right here instead of in the fields.yml file. So we are going to put those fields in a separate tab from the usual fields that you get with the user's plugin.

Defining the New Form Fields in Code

So what I did here is I said I want this Facebook field to have the label of Facebook, it's going to be type text, and it's going to appear in the profile tab. Okay, so let's do the same thing for the bio field. But it's not going to be using the type of text but textarea because we need more text in that field. Save this and actually that should be it, if we did everything correctly.

Verifying the UI and Final Result

Let's go right here, refresh this page. And I have some trouble, I misspelled controllers right here. So with one l. Save it. And as you can see, now we have this profile tab and it has two fields, Facebook and biography. So now you can click 'Update details', click on 'Profile', and then you can add something to Facebook field, add something to biography field, and click 'Save and close'. As you can see, this all works. Let's see. So our new data has been saved to the database. Okay, so this is it for this episode.

Conclusion and Next Steps

In the next episode, I'm going to show you how you can add those fields to the front end and also save them. As you will see, if you try it out, you can't as of right now save those fields to the database via the front end, which is not very useful to you if you don't want the users to see this administration. And in most cases, you don't. So this is the administration mostly for the super users, and for your users you would have something like we did in one of the previous episodes when we did the users plugin. So we are going to do that. So the same thing as right here, but on the front end. It's going to be much quicker as you will see because we already did the most of the heavy lifting. Remember, everything we did here will be available for you on GitHub. The link will be in the description below. You can ask me questions on YouTube or on my website or you can follow me on Facebook or on Twitter and ask me questions there. If you like this video, please give it a thumbs up. If you like the content I put out, maybe subscribe to the channel. And that's it. This has been it for this video. Thank you guys for watching, and I will see you in the next one.