Practice English Speaking&Listening with: Kintone Technical Training - Plug-in

Normal
(0)
Difficulty: 0

hi welcome to kintone technical training my name is leo and today i would like to

talk about one of my favorite topics which is building a plugin in kintone let's get started

this material was created using the april 2021 version of kintone

we may change our contents without prior notice before we get started there are some of the

prerequisites that you need to have first of all you need to have a kintone account and you

need to make sure your kintone account has kintone system administrator's privilege and then you need

to understand some basic of javascript of course you need to have google chrome and a code editor

installed you also need to clone our github repository if you would like to follow along

and you have created apps using the add template inside the github repository

this way you don't have to go through other steps to get your apps set up

last but not least you have installed node.js

and for more detail please refer to this slide and the link is provided here in this documentation

here are some useful resources that you can use after you go through

or before you start the tutorial

okay let's talk about today's agenda first of all i'll talk about what's is um what's kintone plugin

and then i'll go through the process of creating a plugin

template environment for you to build plugins using the library create-plugin

and then we'll go over some of the hands-ons where i will show you step by step of how a

kintone plugin is created using the libraries that we will be introduced and then last but

not least there will be some useful plugin tools for you to use when you are building your plugins

what is kintone plugin well kintone plugin is a packaged program you can have multiple javascript

or css file inside this packed program and as a user all you have to do is install

this plugin into kintone app and you can do the settings without having to do the codings again

you can easily replicate that plug-in package into multiple apps and this way you don't have to

go through a lot of reset you don't have to open your coding all you have to do is

change the setting of the plugins it will work across all your subdomains

let's talk about some of the advantages of using a plugin in comparison to using

a customization so first javascript and css file can all be applied at once now with plugins or

without plugins you would have to do all these settings inside javascript files and you would

have to do it in your css files but what plugin will do is it provides you a plugin setting

page where all you have to do is make some simple selections in the image that you're looking at we

are trying to change the color of certain fields text based on the value of a different field now

with coding you obviously have to write a lot of things but here the only thing a user will do is

just to use your mouse click around select the right field select the color and then that's it

the second advantage is that you can make changes very easily in those setting pages so for example

you deleted a field you don't need you longer than some fields or maybe the condition when

the color has changed is now different so now all you have to do is go into the plugin setting

and change the words change the options change the colors and you can easily change the setting

the next advantage is that in a javascript customization scenario if you look at the image

on the left hand side you will have multiple files and you will need to install those multiple files

into different app if you want to reuse it you will have to repeat that same

actions for multiple times whereas with plugin you only have to install

into your sub domain once and you can make it available inside your app very easily

this is a big advantage advantage number four is that if you're using a plug-in

sensitive informations can be concealed for example if you're using api keys in

one of your plug-in settings that you can hide them from your front-end user and just

be able to hide that information and when the user is trying to look for those

apis they won't be able to find it as easily advantage number five is it's easy to upgrade

now remember i've talked about all you have to do is install it once into your subdomain so

if you ever need to upgrade your plugin all you have to do is repeat that same action

upload the new file again into your subdomain and it will apply that update to all the

plugin that was already installed inside your apps so pretty neat advantages here

okay now let's talk about how to build a plugin template using this create-plugin library

first of all let me explain this create-plugin is a plugin development tool designed to make

the development of kintone plugin easier it is a cli tool that allows you to create templates

with some interactivity dialogue so if you look at the common prompt below

as a user you just have to type the command create-kintone-plugin and answer some of

the questions here and then the program will automatically generate the template for you

some of the optional tools that you can use

with along with create-plugin is for example the eslint now with kintone there is a specific

eslint that is called at cybozu slash esling dash config this is specifically

for kintone development so you can definitely use those this tool when you're developing plugins

now this is a really neat tool to use along with create-plugin and this is

basically helping you to automatically packaged your plugin and then upload that into your

subdomain you would never have to go to the app manually install the plugins and upload them and

tested it you will do all these actions inside your terminal when you use npm start

now remember you still have options to choose not to use this additional library

and the library name is called plugin uploader so when you set up your template it will ask you

do you want to use the plugin uploader if you choose yes then once you start developing plugins

it will ask for your credentials what's your sub domain what's your username what's your password

it will automatically package your code into plugin and upload it to your sub domain

this way you can develop you can test it and you can do more development

without having to break your flow okay let's talk about some of the basic procedure to develop

kintone plug-in using create-plugin library now the procedure here is pretty easy first of all

you need to make sure the environment you have now we've talked about some of the environment

in the beginning of the slides and one of them is basically for example is that you need to

have a node.js you need to have a kintone account your account needs to have administrative access

now the next step is you need to create a plugin template now with create-plugin library this can

be easily done the third step is you need to modify html css javascript now the html the css

those may be applicable to the plugin settings mostly because you need to understand what kind

of plugin settings what kind of information you want the users to be able to set

and then you would then do the customization and basically what the plugin how the plugin

is going to work when the user opens up an app after the setting is provided

and then you need to modify the configuration files let's say for example you need to

change the icon you need to include more libraries and then you need to do before you

before you're able to test your code you need to package that plug-in file and then upload

it to kintone step domain and then you're going to come back to the third step test your code

repeat the third step all the way throughout the sixth step and you'll repeat that same cycle of

process until you your plugin is finished now let's go in deeper with each process

so let's talk about how to create a plugin template using

this create-plugin library in detail

first of all you need to prepare the environment for using the create-plugin

it is important that you install node.js which should be already done in

your prerequisite again node.js is required because create-plugin is published on npm package

it is available in windows mac os and linux please refer to the engines property inside

the package.json inside this repository for the version of node.js required to use this tool

now everyone's engines may be slightly different and you need to make sure that your node.js is

either equivalent or above the version mentioned in this link which you won't get unless if you

download these slides and then the next thing is once you have node.js installed you need to make

sure you install create-plugin libraries and you can find that step by step flow

by clicking in this link where it says this article for that installation procedure

and then in terms of how to use this

plugin you can then create a template using the command create-kintone-plugin

you need to type the name enter the name of your plugin after you've finished typing the command

and you'll see an interactive dialog to go through setting up the template for you

for example what your plugin name is going to be like

does your plugin name support japanese does your plugin support chinese what's your homepage url

and does it support mobile view and do you want to use the plugin uploader such as such

once you finish answering all these questions this folder along with the files will be created

using the example that i was demonstrating the folder the plugin name is called simple plugin

and inside that folder you'll see files like node modules

you'll see package.json you'll see private.ppk you'll see scripts yours you will see eslint and

what's most important is that you'll see this folder source folder which refers to src directory

inside src there are folders for css for html for image for javascript

and there's a configuration file called manifest and it's a json format file

so to begin you will need to modify your html css or javascript file for your plugin settings

now um by default there's a css file called

51-modern-default.css now this is one of the style sheet that allows you to style

your forms your your html elements that looks like kintone and then there's a config.css

which is for your plugin files a css file specifically just for your plugin setting

page and there's html config.html so this is a setting page html for your setting page as well so

you will need to modify those three files in order to set up your plugin setting page now of course

there's more than just that there's a javascript file and you once you finish writing your html

and css files basically once you finish doing your interface user interface

then you need to add some interactions to it and you can do that by modifying

the javascript file so for example your html file has a message label and it has an input box

and inside your well on top of that you would have the button the cancel button the save button now

what you're looking at the screen this is before you apply any kintone styling and this is before

you possibly apply any javascript plug-in stylesheet which is the 51-modern-default.css

this will allow you to apply kintone's styling to your html element you will need to make sure that

you use the name provided inside the the style sheet the default style sheet you will add that

class name when you create those html elements in order to provide to apply those stylings

so once you apply the styling you'll see that the same output of the html elements

now becomes a little bit more close to what kintone looks like

next thing is you need to modify the javascript file so this is done inside

this file called config.js and again it's under the src folder inside a js folder

so there are a couple things you need to include inside this javascript file for the

plugin setting page you need to think about what happens when the save button is clicked

so one of the event is when the save button is pressed the input the data required for processing

the data that's required to for your settings in order for your plugin to work it acquires those

data inside the fields that you have defined for the user it's going to process that value

in each field and it's going to format the data so that kintone knows what it is

and then it outputs it to a kintone environment this way when someone opens up the app the

the it has your plugin has enough information to execute

there is a specific method inside the plug-in set setting page that save the setting in kintone this

method is kintone.plugin.app.setConfig and it's going to taking a config as well as a callback

now this config is an object that is required this is basically um you need to store the value

um a key pair a key value pair object and you need to define what's key what's key

one what's key one's value what's key two what's key two's value you can pass that into a callback

and this callback will be executed once your settings are saved now this is not

a required callback so if you don't need to have any functions any actions that need to

be executed after the save you don't have to pass a function here you can use other api to retrieve

those information from the plugin setting page and that method is kintone.plugin.app.getConfig

and you need to pass in the plugin id in which we'll go over a little bit more

later but plugin id is a tax it is required and it helps the system to understand which plugin

are we talking about because obviously you may have more than one just one plugin into your app

so here we need to make sure that we get the input

from the plug-in setting page so that it can be used when the user opens up the app now the reason

it is different from regular kintone javascript is because

when we pass the input value entering the settings screen to kintone javascript

there is a plugin id that is dedicated to this plugin and kintone will recognize

that these settings are specifically from those plugin ids this way it will not make mistake um

getting other plug-in setting and use it for a different purpose

and please make sure that you're using IIFE which is referred to immediately

invoked function expression when you run when you write your plugin setting page and this is just a

recommendation to make sure that your plugin is running when the user opens up the page

okay and then please also check the settings of the actions um that you know this

may be ignored or maybe neglected uh when we are writing uh plugins for example

when someone clicks cancel plugin uh sorry cancel button

what needs to happen if you don't do anything nothing is going to happen sometimes i would write

code so that when people click when people click cancel it takes the user back to the previous page

and then another example is that some of the input fields they are necessary to run the plugin

to run the code you might need to think about well i want to make sure that the users need to

put a required value here they need to have a value here so that this plugin can work seamlessly

so you can add conditions to check page when you click save please please make sure you

have a message inside this field so on and so forth you can also set things like well

in case if they don't give you anything there's an initial value here so you'll never have to

worry about this uh plugin from breaking because it doesn't have the right value

and this is very important those are just actions that require for fields that inside your plugin

settings for example um if you're expecting that i'm getting an app id here now this app

id it needs to be an integer it could be a string value but it has to be it has to be a number

so that even if it's a number in string i can still turn that into a number but there

are times when people might just pass things you know out of your imagination people are creative

basically so it's um you need to make sure in your code that you're handling some of

those situations and we would strongly suggest you to go through the secure coding guidelines

to understand for example uh what's making your code vulnerable

against attackers hackers or people who are trying to break your plugins

so it is necessary to check your operations to make sure that those input values are appropriate

the next step once you finish doing all the plugin settings now you can start writing your javascript

customization this is where the code is is executed when the user start doing something

oh and i should have mentioned that there's the file is the this is called desktop.js file

and this is inside js folder under uh src the source folder directory now i'll explain

a little bit more later but desktop.js it's often referred as it executes when you use

your when you open kintone in a desktop computer in a web app basically if so if you're using let's

say if you open kintone if you open the app using a mobile device or using a tablet device

um there will be additional process needed additional setting needed to make sure

those will work when the user is not using a desktop device so again the desktop.js it's

uh just referring to files that will execute in when user is accessing kintone using the desktop

device

okay so we'll need to modify the code a little bit to up to um to get the settings from the

configuration file now when you have a plugin installed inside your app

you would have this property called plugin id and that's when where you would start

executing your code so again it's also you have to write write it in the IIFE

style and pass the plugin id into your function now in this example it also has jquery it's not

required unless if you're using it inside your code otherwise you can just pass the plugin id

in the format that was written here and then inside this um underused scriptinside

the function you can now get your configuration your plugin setting configuration by using the

method kintone.plugin.app.getConfig and pass an argument of your plugin id now once you have

done that you can now access your variable you'll see that i i assign my settings into the config

and there's a a key value pair called message so basically what i did here is in my message

element that tags the html tags is going to be coming from the configurations message property

okay and then once you're done writing your customization you can do more settings

one of the thing that you can do here is change the icon so your plugins will

come with the icon just to make it look really nice and you can change the icon

to to the to to be whatever you need the other important thing that you need to always change

is the manifest.json file this is basically how this template is running this is the key

structure of this plugin and it's over here where you can tell them let's say if you

don't name your desktop.js the same way as what we have inside the template if you're going to

change your desktop.js to index.js for example you need to make sure that your manifest is updated

as well you need to make sure your manifest understand that it's not looking for a desktop.js

it's looking for file name index.js so this is uh manifest is very important file for your plugin

again um just some of the additional information for the the icon file it is required

if you don't have anything um you can just use the one that's already included inside the template

and you can it's only limited to like png jpg gif or png files and then the maximum

file size is 20 megabytes which is actually pretty big compared to uh for an icon actually

for the manifest file um it's there are fields that are required and there are

additional fields that are not required but once you if you are trying going to expand your plugin

to uh to more functionalities then you may find those additional files very helpful

so first thing is you need to have the version of this manifest um it's just similar to uh when you

write package.json there's always a version of your package.json and it's the same thing you

have a version number for your manifest now you can also put the version of your plugin

i'm sure that sometimes when you first write your plugin it's it's very well done but you wanted to

add additional functionality to it and you want to be able to differentiate between the versions

from version one to version two so this is where you can say this is what version of the plugin

you usually just default it to app you don't really have to change that

and then the name this is basically the plugin name for each language so by default you'll see

that it has a key of en which stands for english and then the name the plugin name in english

now if you wanted to go a little bit further to make sure that it supports additional language

you can use ja for japanese name and you can use zh for chinese name for that plugin

and then you can also change the name of that plugin if it has a specific local the kelly

and then the description of this plugin as well now the description

also comes in similar structure where you can give it a different language

you can use a different language depending on the locality of the of the user

and then icon that's where the icon file is if your icon is in a different folder

they need to be inside the project but it's in a different folder you need to make sure that

manifest knows where to get that icon file now all the rest are just not required but

desktop is where the customization file is this is the file that runs when the user opens up the

opens up the the app itself now it takes it takes notice that you can actually pass a string

a array of strings into it this means you can have multiple js file inside your plugin

same thing with css file and if you're making your code available on mobile

you can also have a mobile.js and you need to also specify where your config file is

your config files html and their css last but not least you can make sure

that there's a required parameter for those plugins before your user is able to save them

okay so this is obviously the previous chart um does not have colors so if you look at this

it's a lot more clear and just want to emphasize on the part where it says desktop so

inside desktop you'll see that there's a js and that's basically you can pass multiple

files in there you can use a cdn if you want to there's a css folder this points

to where that css files are and by default all these these all come in by default by the way

so you'll have 51-modern-default.css style sheet for you to use and the icon file is already there

it comes with the default blank icon um the config file this is all for plug-in settings

now html is for plug-in settings and those js files for plug-in settings as well

and on the right-hand side that require parameter that's where uh the plug-in settings basically

if you have a required parameter user tries to save it does not and it doesn't have that value

it will prevent you from saving and in the names and the descriptions

okay we're at the last step of that flow so bear with me here before i start

doing more uh something more fun so when you use that temp that library create-plugin

it will ask you hey do you want to use uh the kintone uploader so if you select yes

what happened is when you run mp and start command it's going to package for you and it's going to

upload the packaged plugin for you so it's going to ask you hey can you enter your sub domain

can you provide your username can you provide your password obviously most username and password they

need to have administrative access and if you don't want to use that uploader that's totally

fine you can just type npm run build and you can type npm run upload to use that same flow

very similarly now npm start is all you need to get your plugin project development started

another important thing is this file private.ppk now remember we

talked about you need to have a plugin id passed from your plugin file setting file

to your kind of like front end the javascript customization file

so private.ppk that's where the kintone plug-in id is is stored so this this file is very important

make sure you don't lose it if you lose it obviously it's not going to be a huge issue but

your your plugin will be installed as a separate identity when you install those plugins again

um so make sure that you don't lose this file you know and you don't delete them

now this file will be automatically generated when you use the create-plugin library

the other thing that i want to talk about is if you don't use if you don't want to

use npm start for some reason you want to do things individually you can use

this thing called kintone plugin packer which will allow you to manually update that plugin

without uh if you're not using the template basically uh if that's the case you just need

to make sure you pass the parameter to tell this library where your private.ppk file is located

now just to give you a checklist to validate your code before you code it down project

first of all let's look at the installation can this be loaded into kintone environment

can your plugin apply to kintone app that's the first thing that you need to uh to double check

and then for plugin setting pages do you have a cancel button

do you have a save button does your plugin work as intended and then

for the customization does it work when you load that application does it work so those are kind of

like a general checklist for you to get started uh checking whether your plugin is working correctly

so let's go to something more exciting the hands-on first of all we'll go through how

to prepare the environment for creating the kintone plugin now i'm going to use the slides

and i'm going to switch back and show with my vs code so you don't have to follow along

but if you want to follow along feel free to pause this video and see what we are doing here so the

goal here is to prepare your environment so that you can use the create-plugin command and then

we'll learn about how to use that create-plugin command as well as apply that same simple plug-in

created by create-plugin to your app so we'll learn all of those

okay the basic procedure first of all let's prepare the environment for using

create-plugin now this is mentioned previously you need to install node.js and you need to check what

version what engines you have and then install the create-plugin accordingly and then and then

you can install the create-plugin so let's refer let me open up this page right there

and then we can see more details of what it looks like i am going to

drag my screen over

there you are great so look at the engine right there

okay so it says that then your node is needs to be uh equivalent or more advanced than version 10. to

check the version of your node.js you can go to your terminal you can type oops

you can type node -v you can see that i'm using 8.9.4 obviously that's not what the requirement

tells me to do so you probably don't have to do this but i will just upgrade my current node

using this command again your comments may be different from mine but uh if you're

using for uh well i know that i'm using uh i have another version still i'm using 14.10

um point zero so i can switch my node to that more recent version and if i type no feed again

now you can see that i'm i just switched to version version 14. okay

and now you can the next step is to install this create-plugin so npm install and now install this

plugin globally this way i can access this command anywhere inside my uh my laptop and it's a kintone

create-plugin let me just make sure i don't have a smiley mistake click enter and it's going to

download this package for me and we'll just wait until it finishes downloading installing

all right fantastic so let's go to the next step

okay so now that you have finished prepare your environment to for this library create-plugin

we're going to actually create a template using this create-plugin library

so what you would have to do is open up your terminal and type in

the command create-kintone-plugin and we'll follow through is this comments here so what's going to

happen is when you type the command itself will pass the directory name simple-plugin

and it's going to initiate a bunch of codes to ask you how you want to create your plugin project

so back to my vs code i'll type create-kintone-plugin

leave a space type simple-plugin enter

now it's going to ask you some of the questions first of all what's your plugin name in english

so i'll call simple plugin you just make sure that i'm not missing anything here and then input your

plugin description in english so it's going to be the same as the name here does it support japanese

no for now does it support chinese no for now you can put your homepage url for english it's

optional so i'll just skip does it support mobile views no would you like to use the

plugin-uploader i will choose yes and i'll show you how uploader works it saves a lot of your time

now it's going to install the dependencies and create the template file for you

i'll show you my folder structure and you will see that this simple-plugin folder is already

created for you and right now it's just installing all the dependencies all the templates for me

and this is going to take about a minute or two depending on how fast your computer and your

connection is and let's pause the video for now and we'll come back when it's finished downloading

all right so success that to create your plugin templates is now created you can run those

following comments npm start and npm run build and npm run lint then so again you can see the folder

here a simple plugin you'll see the files note modules those are where all your dependencies are

don't worry about the scripts folder um the source file that's where your css html image

and javascript files and most important of all the manifest.json file again this is the one of the

key component for your plugin and then outside of that you have the link file for eslint you have

the package.json file and then the private.ppk file and that's where your plugin ids are stored

so make sure you don't lose those files here now looking at manifest.json and again it's it has

some libraries pre-installed for you for example the jquery's and if you right now when we install

i didn't select that i wanted to support mobile view um but if you do that you'll see

your manifest files to be a little bit different from mine and you'll actually have another key

pair of mobile here after desktop and you will see more bio points file structures that it points to

okay so that's pretty much it for this step we'll go to the next one

um just to uh briefly explain uh more about this folder structure

um package.json file is generated um if your npm is above five or later then this file

is automatically generated you don't have to delete this file you can just leave it there

now some of the other usual functions that comes with the plugin as mentioned is

first of all the lint so this lint file is going to help you check whether your files are

following the rules that kintone follows and all these are done automatically for you

and then on top of that because i choose yes using kintone uploader so now i have the functionality

i have the ability to do automatic packaging and uploading while developing the plugin itself

okay so after you have set up your um plugin templates let's talk about some of the optional

features that you can use in this in this template first feature is the eslint this helps you

check your code to see if it has some kind of issues against to this to the javascript styling

specifically related to the kintone's cybozu's rule when you write javascript so first of all

i will cd into my folder which is the simple-plugin folder and i'll type npm

run lint and it's going to check the styling in my code and if there's no errors it will just return

as it is now just to be experiment if i remove this through a true property you'll see i actually

got a deprecate uh deprecation warning and that's just because um i've used the eslint globally

so you may or may not have this arrow depending on your setting but uh this is just a a quick way

to help you check whether you're stealing styling um is up to the standard so i'll turn this back on

and run the link again and you'll see that there's no errors here all right so that's the first one

and the next one is the automation of packaging and uploading now remember when we install

the plugin it asks you for options to see whether you want to use the kintone plug-in operator

and this is what it is for so when you type npm start imagine well let's say you're using

the uh uploader when you type npm start it's going to have those messages after the package

the plugin bundle for you and it's going to ask you for your sub domain address your username your

password again your username and password needs to have that administration access to the subdomain

and it will upload the plugin the bundle plugin for you so let's see it in action

so let me just clear this out

speaker actually and if i type i can start you'll see that first of all it's going to package

this plugin for you which is why you see the succeeded message and now it's asking you

to input your base url so i will type intel um technical training which is my url kintone.com

your username you're going to type your username and i'll type mine here and now it's it will

give you messages like it's logging in it's navigating it's trying to upload your plugin.zip

and now your plugin uh that's it has been uploaded when you see this message this means your uploader

has uploaded your plugin for you successfully great um and then just to add more notes when you

when you are developing each time when you change the code this is going to run re-run automatically

um this way you don't have to you don't have to upload your plugin manually each time when you

change something it's uh it's just done here so very useful uh optional features that you can use

okay so i've uploaded the plugin let's check whether this plugin has been uploaded

so here i'm going to go to um let's see i'm going to go to my environment here the

kintone-technical-training.kintone.com i'll click on this gear icon here

and go to kintone administrations if i scroll down i can go to plugins

and you'll see that simple plugin that i just created great so now i know that it's here

and the next thing i want to do is to add this plugin to one of my app

in this case it's the sales deals app now this um sales deals app is provided to you

in the github repository so you can just download it and install that um app template

i've already done that so i'll just go into this app and click on the sales deals

go to the app settings here go to the app settings and the plugins i'll click on app plugin and

here you should find a list of plugins that you have i'll click a check on the simple plugin

and then click this add button one more time and now this plugin is installed in this app

let's see what uh what we need to do next

so here we know that it has this description required field has not been set and that's because

in this plugin it has a required parameter set inside my manifest.json file so if i open up this

file here if i scroll down to this part you'll see that there is a require parameter message and

that is exactly what this is for so i'll go into the plugin settings by clicking that gear icon

and i'll take the message and this message is for kintone technical training hands on

a little bit whole message and then i'll click save it's going to tell me give me

a conform message that it has been saved now you need to update the app so notice now it

automatically navigate back to this setting page where you can then click update the app

and now you can see the message that i just typed in kintone technical training hands-on number one

great so that's the step let's go to uh hands-on number two

here we are going to create we're going to dive deeper into the kintone plugin development the

goal for this hands-on number two is to learn this step to develop a plug-in using that create-plugin

so here we will we have provided a plugin that is um already developed in the repository folder

and you can just download it and run the plugin itself so what this plugin will do is it's

going to change the background color if the user selected if the user selected inside the record

matches with the user who's currently logged in so on the top right hand side you can see that this

is user01 and down here for any record that also says user01 it will have a different color

okay so let's talk about um the settings needed to make this function work

if you go into the setting pages here first of all as a user uh not a developer but as a user i will

first need to select which user field do i want to change the colors for so here you will have

to define a user selection field just because you might have multiple user selection fields

and you want to choose the one that you want to change the colors on and then the next option

is you need to select which background color do you want to change it to here we're kind of like

using the neon blue light um and this is the color that the user if it matches with who's locked in

then the fill color will be changed to this neon blue light and further down in the page

you'll see that the record list view page inside the app uh the background color has been changed

and it also works inside the detail view of the page of the app

so to get started first of all you need to go to that github repository folder and download

this file this plugin project folder to your local now this was already kind of like mentioned in the

prerequisite steps so if you already download that folder you should have this inside the hands-on

number two folder and then next thing is you need to change your working folder and install

the dependencies so cd into the handset number two uh sitting into that project folder of the plugin

and then click npm install now before i show you um how i did it let's just uh briefly talk about

the changes done here inside the src folder on the right hand side so inside the src folder

you'll see again the css folder the html folder the image folder and the gs folder

what has been changed for this plugin are all the files that is in red

and you can see that we've changed a couple files in order to build this plugin once you set up the

plugin template you need to modify your html css and javascript file for your plugin setting page

so let's go to my vs code which is over here and i am still in my simple plugin so i'll exit

and i'll go to end zone number two which is this folder right here and it has

another folder down in there so that's user selection conditional format plugin

and now we're here so again first step is that we need to install the dependencies here so i'll type

npm install just so that i have all the libraries all the dependencies needed for this plugin

and we'll pause the video here until it finishes installing

all right so this has finished installed and then before i move on to the next one let me

just briefly show you what i want you to what i wanted to describe in my next step so um first

thing is we want to make sure we update the html um and what's important is that you need to make

sure you label the class name if you want to create something that looks like kintone

that applies skin tone styling you would write the class name using the 51-modern-default.css classes

and i can show you in my vs code to see where those are located so inside stores again there are

css folders and that's your 51-modern-default.css that's where all the classes names are

and you can see that it's uh it's clearly labeled that these followings are for alert messages

and this is for plug-in rows this is for titles so on and so forth so using the

information provided here open up the html and go to the config.html

and just make sure that you have those and because this is a title so i put the class name kintone

plugin dash title basically just follow the rules here inside 50 first modern to fold.css

so pretty straightforward um and then the next step is we need to

um put additional css if you have other css that you want to include but instead of writing

it inside the 51-modern-default.css you will write it inside config.css

remember that this is just for configuration file and you can find that setting inside your manifest

json file notice that inside desktop there's no files in css that's because we didn't use anything

there but inside config config file which is the plugin setting page you'll see that it's using two

css file here that's the modern default and then the config.css so just make sure because you don't

want to because this is already a huge file so it is recommended that you create a different file

and write your additional custom css here in a separate file

so that's the next thing is um the javascript file so inside the plugin settings um because

we're trying to select the users and rather than having asking the user to type the username

which has to be which whatever they type it has to match 100 with your kintone setting so

if it's let's say if it's supposed to be your upper case k but the administrator accidentally

use a lowercase k then they will probably break the code and to prevent that from happening

we want to make sure that we pre so we give the users a set of selections so we need to populate

those selections for them and have them choose it based on what's already available in kintone

so in this example we're using this library called kintone rest api client

which will help us get all the user's name and populate them into the options inside the html

so if you look at this example again you will need to pass the argument of plugin id

into your configuration page so that kintone knows which plugin settings this is for

and then after that we'll instantiate the restful api client and we will get the elements

from the field and those are all the elements that's coming from your html file

and we will escape html so that we can just get the user's input value

without wholly different characters now it's not supposed to be there

um another thing that you need to be aware of is if you're looking at the code in this example

is written in es6 because it's using const now obviously i think most browsers in the

current days have already updated their code so they should be able to support es6

but there may be some browsers that are still using es5 so please make sure that

you know which browser are you targeting to before you finish writing your javascript code

all right so the next thing we want to do inside the javascript file is first of all on the right

hand side we want to set the full now this function is basically let's say if you already

have this plugin settings next time when you open the same setting page

if you don't do a set default functionality to populate your pro uh previous value

then it's going to always get empty and your administrators may be

confused they may be like well i already set my settings last time why can't i see it

so you need to first of all populate what's the previous setting inside this config file

and before you continue so again you're using this this api called kintone.plugin.app.getconfig

pass the argument of plugin id which is always unique to uh to each plugin

and then this is how you will get your configuration file

and then once you have that configuration file you can destructure it and then pass it to your

html html so that you can set a default value for it on the right hand side we're basically getting

all the user selections here so uh the function is set set user selections you pass the app id

and then um you use the kintone's restful api client specifically the method of get form fields

then once you have a response you can iterate that to first of all make sure

it has properties it has the fields that you need and then you will select the option which is

also defined inside your html and you will set the user selection you would set the values

according to the return value from your form field from your api basically

whatever user you have uh populate them into options on that specific option field

and last but not least once the user has finished selecting which field

for that user selection they will we will first save inside this

uh config file and then we will use this api method kintone.plugin.app.setConfig

to save that configuration file this way you're when you actually go to the app not

the app setting but when you actually go to the app you can you can find that configuration file

in case if the user doesn't want to do anything they just want to cancel you will need to add

another open listener to track the clicking of the cancel button and when it happens it

execute this code of history.back which basically takes you back to the previous page and then the

last code basically says you know turn it into a promise object so you get the you get the users

whatever users you have first once that is done then you set the default value obviously

you don't have you can't really set a default value if you don't have your options available

so that's pretty much it for the plugin settings our next step is to modify the

javascript customization now this is very similar to your actual customization which is

um if you took previous training materials i have explained a little bit about how javascript

customization is done in kintone so in this customization file you would have to pass

the plugin id as the argument into your enviroment this is very very important again if you don't do

that kintone has no way it will have no access to your plugin id um to the settings of your plugins

and it will not recognize whatever settings you have so pass the perimeter of past

sorry pass the argument of plugin id and then use that plugin id to get the configurations

and then the next line is we also want to find out who is currently logging to kintone

and this is another api method that kintone offers the kintone.getlogginguser.code

so that's pretty uh that's pretty much the uh the first two things that you do

the next thing you do is you add a different listener for the details so here

we're adding event listener when the user opens up a detail view it gets the field

element based on your field selection from the configuration you can see that there is

a config field selection and that's basically your user selection field it's going to fetch

the field code which user selection fields are we are we trying to change the color

if there's no selection fields if it's not there then we'll just terminate this function and return

the event if there is a field selected and then that field exists then we want to we want to

get the field code the user code of that those values and if it includes the login user code

then we'll change the field color and this takes us back to the

the function at the top is we basically use uh change the style um change the background color

of that specific element to the color that the user has specified inside the plugin settings

and that's for detail view we'll basically do the same thing

in the index view where there's multiple records and we'll just follow a very similar process

to check whether this user is equivalent to the user that logged in and if it is change the color

um once you finish writing javascript for your product plugins for your javascript customization

then you would modify your configuration file switch an icon um change your manifest

file settings in case if you change something again the icon size it takes

file type of png jpeg gif or bmp and then the maximum file size is 20 megabyte i would

recommend you use something a lot smaller because this is an icon that's very pixelated so you don't

have to give something high you don't have to find a picture with very high qualities all right

and the man is fast file again you can change uh the name of this plugin the descriptions

um if your icon is on the folder that's otherwise specified if it's different from the template file

then you would change the directory of that if you have more than one javascript file

in the template it's using a jquery so if if that's the case you will need to improve

the cdn for that jquery or uh you can download jquery library locally and use it as well

and then the file the desktop.js if it's there um and then this desktop again is just for the

customization for the configuration it follows a different formatting a similar structure but just

using different files so first of all you would need to tell the plugin where the html file is

and then what js file are we using we're using the kintone rest api client library here so

we're basically including the cdn url here before we even call the config.js um order is very

important so if you're using any cdn libraries make sure those are in the order where it was code

and config.js because it's using a restful api client library so you need to make sure your

restful api client is at the top of config.js and then the css file and then the require parameter

okay and then once you're done with all of those uh you can just do a packaging

um turn that into the actual plugin file and then do be uploading i've enhanced one

uh hands-on number one we've talked about the npm start command so um that is just very very

convenient so i'd strongly recommend use that kintone uploader this way you can use npm start

command and do the packaging and uploading at the same time automatically and you would

do again the npm start enter the sub domain insert your username enter your password

and that's that's about it once you uh start that flow you would just

continue to validate your code to validate your um your plugin to see if it's working as expected

and if you ever need to modify that customization just go return to step three

because template is already created so you just need to

change the files that you need to change and then follow this cycle or flow until you're finished

now let's go ahead and do the same thing here in my vs code so

i'm already in the right folder and i'll type npm start

and it's going to uh first of all package the plugin file for me and then it's going to ask me

uh what's your base url so kintone technical training

your training.kintone.com developer and my password now assuming i type everything correctly

it's going to log into my kintone sub domain it's trying to upload

the plugin file and you'll see that plugin.zip has been uploaded to see that we can again go

back to the administration settings here so go to settings kintone administration

and i'll go to the plugins and now you'll see that this

is a new plugin that just that just got installed so great um i'll go back to the sell steals app

and i will add this plugin

or actually before i do that um i will add another record

or two so notice that this is um i'm locking as leo kintone my first record is leo kintone

and i'll create i'll create another record that does not have the same value

i know i have a developer here so i'll put developer

and i'll create another record use this leo kintone and just one more record that use

a different value whatever other choice i have john there you go okay so back to my list view

all right so then i'll go ahead and add the plugin so select the plugin click add there's a required

field and there's a required field because inside manifest we have a required parameter

specified so you will need to go to the setting you need to select the user selection fields

and that background color i'll use something that's close to near blue light and click save

and then it will click the settings one more time and click to update the app

so we've done that with create simple records um now you'll see wow kintone whatever records

that has leo kintone is now highlighted in that liam blue light missions accomplished all right

so just to um review on the process for validation when you build your plugins first of all during

installation does your plugin cannot be loaded into kintone environment and up to kintone app

does it what this basically means can users even install your plugin is your plugin

compile successfully that's the first thing you want to check and then the plugin setting page

you want to also check uh your whether your cancel button is working whether your save save button is

working and is your overall your plugin setting page is working as intended for like for example

if you select option a then it shows option a if you select option b then it shows option b

is it working as expected then the next thing is you want to check your customization and see well

is it loading is this code loading in the right place so is it loading in the list view or is

it loading in the detail view or did it load in both those are the things that you want to check

again just the validations the behavior of those plugins are really really important

can it be installed and then

is all the button working is it working as intended

does it save there's a popular message when it's successfully saved

and then um all the background colors uh when you use when you choose a different

background color does it actually show that different background colors

if i select black i'm just expecting that this color uh the preview color button is showing black

and then at the end is your code working in general according to your plugin settings

so that's about it with hands-on let's review a little bit of what we have went over today

the advantages of kintone plugin um your javascript file and css file can all

be applied at once rather than having to install them one by one to multiple apps

and then the next advantage is that the changes can be easily made in the settings so rather

than having to open your code editor open the coding file change the settings you can just

use a more intuitive interface to change the settings so that it's applicable to different app

with different settings batch application to multiple apps and book upgrading as possible

so if you have multiple files inside inside that customization that you need to use

if you turn it into a plug-in it is possible to have um to to apply multiple files at once

and it's possible that in case if you need to update one of the file it would apply to

all the files um all the in different apps and then this is very important that save

sensitive information can be concealed and then that it's easy to upgrade

the other thing is when you use create-plugin to make the development of kintone plug plugins

it's making your life a lot easier first of all because it creates a template for you

without you having to guess yourself and then you can easily modify the html css javascript

files for your plugin settings page you can modify the javascript customizations we've also

talked about you can modify your configuration files like your icons your manifest.json file

and then we talked about how packing and uploading um is also automated for you if

you choose to use uh use the plugin alone with kintone uh uploader plugin uploader

all right so before we end this session i just wanted to give you

additional useful tools that you may use uh when you develop plugins first of all

there's a kintone ui customization tool that you can use and that is kintone ui component now this

kintone has a specific styling by default you would have to look at you have you

you would have to check the class name of the 51-modern-default.css file find the class name

and then write that plugin sorry write that class name into the html yourself manually

if you use hint on ui component you can create those for example your alert message spinners

checkboxes options in javascript and those stylings will be automatically applied for you

in terms of plugin development tools again uh we went over the create kintone plugin tools

uh make it available in your global state and then you can just use the command line to create a

template file for your kintone plugin you can also if you choose to go a little bit more advanced you

can use the webpack plug-in kintone plugin library this allows you to use webpack for your file

which means it opens up to more possibility such as using like react using view

you can use a lot more different libraries out there using this webpack

um and if you want to use webpack you can use it alone for this vlogging

there's another plugin called kintone configuration helper or kintone config helper this

allows you to get the field information from basically the field information and then the

layout information from the kintone app um this is if you're not using any api calls if you're not

familiar with any api calls this may be a great tool for you in order to get the field settings

all right thanks again for you joining this session and i hope you enjoy your wonderful day

so i'll see you next time thank you

The Description of Kintone Technical Training - Plug-in