Adding Vue components to the admin panel using plugins

Overview

This tutorial explains how to add a Vue plugin to Kuroco's admin panel.

For demonstration purposes, we will be adding a color picker in a text input field on the content editor screen.

About the plugin

We will be using the sample directory diverta/management-vue-plugin-sample to create the plugin.

The ContentsColorPickerInput plugin will be installed as an additional field in your content structure of choice. It enables you to select a color by one of the following ways:

  • Entering the color code
  • Clicking on the gradient palette and/or color sliders

Image from Gyazo

Before you start

For the development part of this tutorial, you need to have Vue devtools installed in your browser.

Note: This tutorial was written for use with Google Chrome. Actual controls may be different depending on the browser you are using.

What you'll learn

The steps for installing this plugin can be divided into two phases:

  1. Setup phase

  2. Development phase

Plugin setup

Preparing the content field

In a new or existing Content structure editor, set up a new additional field as follows:

SettingValue
IDNote down the field ID ("01" in this example).
Field nameColor picker
Field settingsSelect "Single-line text" from the dropdown menu.

Image from Gyazo

Click [Update] or [Add] at the bottom of the screen to save this content structure.

Now, navigate to the Content editor you just modified. The newly added field should look like this:

Image from Gyazo

Sample component installation

Next, clone the sample repository using the following code:

git clone https://github.com/diverta/management-vue-plugin-sample.git

Navigate to the cloned directory.

cd management-vue-plugin-sample/packages/ContentsColorPickerInput

Then, run the following command to install the relevant dependencies:

npm install

Component build

Run the following commands in the cloned directory:

npm run lint:fix
npm run build

When the build process is done, you will see the following bundle files in the dist/ folder. (Note: The hashes in the file names will be different for each build.)

manifest.json
vendors.43ede78aa5d8feb80b64.js
ContentsColorPickerInput.b584f61c71a18c07edb8.js

Component deployment

The next step is to deploy the created files and make them externally available. You can use any hosting or storage service to do this. For this tutorial, we are uploading them to the Kuroco File manager.

Select [File manager] from the sidebar menu. In the dialog, right click [KurocoFiles] and select [New subfolder].

Image from Gyazo

Enter mng_vue_components in the name field and click [OK] to save the new subfolder.

Image from Gyazo

Select the /mng_vue_components subfolder and click [Add files] to upload the three bundle files from your local /dist directory.

Image from Gyazo

Admin panel plugin creation

Now, you are ready to set up the admin panel plugin to read the uploaded bundle files.

In the sidebar menu, select [Environment] -> [Admin panel plugin].

Image from Gyazo

In the upper right corner of the screen, click [Add].

Image from Gyazo

Enter the following values in the dialog:

FieldSub-fieldValueDescription
Status-Enabled-
Plugin name-ContentsColorPickerInputEnter a name for your plugin.
Type-Vue-
SourceComponent nameContentsColorPickerInputMake sure the name you enter here matches the component name in the sample repository.
URL/files/user/mng_vue_componentsURL where the component is stored. For Kuroco-external URLs, use the absolute path (https://**).
  • Note: If you modify this path afterwards, make sure to also update publicPath in all relevant rcms-js.config.js files to reflect any changes.
Manifest keysvendors.\*;ContentsColorPickerInput.\*Enter the manifest.json keys in this format: vendors.*;(component name).*
TargetPage URI/topics/topics_edit/Path of the content editor screen (following /management/).
Slot nameext_1Name of the additional field that you set up in "Preparing the content field". The naming format is ext_X, where "X" is the field ID.
Slot paramstopics_group_id=19Content structure ID or topic group ID where the plugin will be added. This can be found on the Content structure list screen.
Props-{"defaultColor":"#000000"}Props to be passed to the component, if any. Here, we are specifying a default value of "#000000" upon initiation.

Image from Gyazo Image from Gyazo

Plugin verification

To verify that your plugin is working correctly, go to [Content] -> [(Name of your content group)] in the sidebar menu. You should see the following color picker when you open an existing or new content editor.

Image from Gyazo

Create a new content post. Select a color in the color picker and click [Add] to save the post.

Image from Gyazo Image from Gyazo

After saving, access the post from the content list. The color picker should display the color code you saved earlier instead of the default.

Image from Gyazo

Plugin development

Next, you will learn how to develop the admin panel plugin. We will walk you through the process of editing the ContentsColorPickerInput source code that you set up above in your local environment and verify its operations.

To do this, you need to first activate Kuroco's developer tools. This will allow you to synchronize your admin panel with your local development server for component editing and operation checks.

Enabling developer tools

In the left sidebar menu, select [Environment] -> [Admin panel plugin]. Then, click [Set up] in the upper right corner of the screen.

Image from Gyazo

In the Configure plugin dialog, input the following and click [Update].

FieldValueDescription
Developer toolsEnabled-
Developer groups(No selection)Select the group(s) authorized to use developer tools.
  • Note: All superusers are authorized by default. Therefore, the selections you make here only apply to groups without superuser status.

Image from Gyazo

After saving these settings, refresh the screen once. If the developer tools have been activated successfully, you will see a <> button in the top right corner.

Image from Gyazo

Developer tool settings

Go to the content editor that you set up above in "Preparing the content field".

Image from Gyazo

Click [ <> ] in the top right corner to display the developer tools dialog. It should display a list of all detected plugins on the current screen.

Image from Gyazo

Input the following and click [Update] to save these settings.

FieldValueDescription
EnabledCheck this boxEnable development tools on the selected component.
Hosthttps://127.0.0.1:26787Enter the host name of the development server.
Enable development modeCheck this box-

Image from Gyazo

Note: If you see the following error message ("Plugins not found."), there may be errors in your plugin display settings. Go back to the "Admin panel plugin creation" step and make sure you have entered all the information correctly.

Image from Gyazo

Starting the development server

In your local terminal, navigate to the ContentsColorPickerInput directory.

cd management-vue-plugin-sample/packages/ContentsColorPickerInput

Run the following command to start the development server:

npm run serve:https

You should see the execution results below, indicating that the Webpack development server has been launched in the local environment at https://127.0.0.1:26787/.

> contents-color-picker-input@1.0.0 serve:https .../management-vue-plugin-sample/packages/ContentsColorPickerInput
> cross-env WEBPACK_DEV_SERVER=true RCMS_JS_HTTPS=true webpack-dev-server

ℹ 「wds」: Project is running at https://127.0.0.1:26787/
ℹ 「wds」: webpack output is served from /files/user/mng_vue_components

...

ℹ 「wdm」: Compiled successfully.

In your browser, go to the URL https://127.0.0.1:26787/files/user/mng_vue_components/manifest.json.

You will see a privacy certificate error. This can be safely ignored. Click [Advanced] and then [Proceed to 127.0.0.1 (unsafe)].

Image from Gyazo

Verify that the contents of manifest.json are correct.

Image from Gyazo

Note: You can safely continue development by ignoring any SSL errors. However, if you wish to resolve them, you can set up a self-signed certificate in your local environment by following the steps below.

Optional: SSL certificate setup

To resolve SSL errors, you can use mkcert to set up a self-signed certificate.

In your terminal, go to any directory and run the following:

mkcert -key-file rcms_js_key.pem -cert-file rcms_js_cert.pem 127.0.0.1

Set the paths to the generated certificate as environment variables in the format RCMS_JS_HTTPS_(TYPE)_FILE. You can use either absolute or relative paths:

export RCMS_JS_HTTPS_KEY_FILE=(path)/rcms_js_key.pem
export RCMS_JS_HTTPS_CERT_FILE=(path)/rcms_js_cert.pem
export RCMS_JS_HTTPS_CA_FILE=(path)/rcms_js_cert.pem

For Windows operating systems, use set instead of export:

set RCMS_JS_HTTPS_KEY_FILE=(path)/rcms_js_key.pem
set RCMS_JS_HTTPS_CERT_FILE=(path)/rcms_js_cert.pem
set RCMS_JS_HTTPS_CA_FILE=(path)/rcms_js_cert.pem

Then, run npm run serve:https again.

Alternatively, you can also set the environment variables and start the development server all in one line:

RCMS_JS_HTTPS_KEY_FILE=(path)/rcms_js_key.pem RCMS_JS_HTTPS_CERT_FILE=(path)/rcms_js_cert.pem RCMS_JS_HTTPS_CA_FILE=(path)/rcms_js_cert.pem npm run serve:https

Component development

Return to your content editor screen in Kuroco and refresh once. Run the Vue devtools extension in your browser.

If you get the following error, you may need to access Vue devtools from the Inspect Element panel (right click on the page and select [Inspect]):

Image from Gyazo

If synchronization with the local environment has been successful, you should see the detected plugin in Vue:

Image from Gyazo

Now, open the file management-vue-plugin-sample/packages/ContentsColorPickerInput/src/pages/ContentsColorPickerInput.vue in your local terminal. Add the following code after mounted() and save the changes:

console.log('Successfully connected to dev server!');

Image from Gyazo

Refresh your content editor screen in Kuroco. You should see the user message you added in the developer tools console.

Image from Gyazo

Delete the console.log() line. Then, find the input element and make the following modification:

<!-- Make the color picker text blue -->
<input
    type="text"
    :name="extConfig[0].ext_col_nm"
    :value="colorCode"
    size="60"
    :style="{ color: 'Blue' }"
/>

The ContentsColorPickerInput package has built-in static code analysis using ESLint and Prettier. If you get a syntax error after saving the file, run the following command to fix it:

npm run lint:fix

Verification and unsync

Then, reload the Kuroco content editor screen and select a color in the color picker. Verify that the text in the color picker field remains blue and does not change with your selection.

Image from Gyazo

When you have finished editing the component, perform the following steps again to reflect the changes in the admin panel:

The final step is to desynchronize with the development server.
Open the Kuroco developer tools dialog, uncheck "Enable developer mode" and click [Update].

Image from Gyazo

Refresh your screen and verify that the changes are preserved.

Image from Gyazo

More information

This tutorial explained how to install a plugin as an additional field in the content editor screen. You can also install plugins on other screens, but the actual setup varies depends on the screen element (i.e., slot) to which they are added.

For a list of all available slots and their settings, see Reference: Slots available for admin panel plugins.

If you have any other questions, please use our contact form or Slack workspace.