Using kintone UI Component v1 in Vue

[dong0]

Background

Some developers want to use kintone UI Component (KUC) v1 in their Vue project.
But now, we don't provide Vue version and don't have a plan to support it officially in the future.

Internally we are using Web Components so that developers can access it from Vue.
https://vuejs.org/guide/extras/web-components.html#vue-and-web-components
So as an option for Vue users, we want to share the possible coding way with it.
Here is an unofficial guide on how to use KUC v1 in Vue.

Unofficial means that we don't test the behavior and support it.

Note for Coding

We are not supporting Vue coding way officially now, so please develop on your own responsibility.

Currently, there is a version conflict issue when defining multiple KUC packages (both same version and different version) on custom JS/plug-in at the same time.
Using tag directly like Vue, the first loaded KUC version will be used.
So we are working on solving the issue now and note that there is a possibility that you need to write with version number included tag like <kuc-button-1-3-0> in the near future.

Guide

Developer needs to write in different way depending on the property type, event and method of KUC.

We created some sample codes for property type, event and method.
These samples are authored in "Options API" styles.
You can refer to them.

KUC is using custom element, so you can specify the "compilerOptions.isCustomElement" option to exclude it from component resolution.
https://vuejs.org/guide/extras/web-components.html#using-custom-elements-in-vue
e.g. Using "vue-loader" in webpack.config.js

{
  test: /\.vue$/,
  use: [
    {
      loader: "vue-loader",
      options: {
        compilerOptions: {
          isCustomElement: tag => tag.startsWith("kuc-"),
        },
      },
    },
  ]
}

KUC component properties

String type property

• This type property can be set like an HTML Attribute.
  For example, "type" and "text" of Button component.
  In this case, the static value can be passed.

• It also can be set dynamically with v-bind directive. (: is the shorthand)

• Pay attention to the name of property and its reflecting attribute.
  property is "className", attribute is "class"
  property is "visible", attribute is "hidden"
  Note: only the property with the setting "reflect: true" have the reflecting attribute, not all.
  So please be careful if you use setAttribute and getAttribute.

Sample code

• Setting the static value to "text", "type" and "className" of Button component.

<kuc-button
    text="Show text value"
    type="submit"
    className="kuc-button"
/>

• Setting the dynamic value to "text", "type" and "className" of Button component.

<kuc-button
    :text="buttonText"
    :type="buttonType"
    :className="buttonClass"
/>

Boolean, Array, Number or HTMLElement type property

• These properties can be set with v-bind directive.
  We can call a function to change the value dynamically.
  For example, "requiredIcon" and "items" of Dropdown component, "duration" of Notification component, "content" and "footer" of Dialog component.

• About how to create a HTMLElement in Vue, you can refer to the following steps.
  (1) Creating a HTMLElement by document.createElement().
  (2) Using createApp() to create an application instance and mount() to mount in this HTMLElement.
  Then you can set this HTMLElement as "content" or "footer".

Sample code

A sample of Dropdown component

• When user changes the selected item, the old value and new value will show on page.

<template>
  <div class="dropdown-sample">
    <kuc-dropdown
        label="kuc dropdown"
        :selected-index.camel="1"
        :required-icon.camel="requiredIcon"
        :items="[{
          label: '------',
          value: '',
          },
          {
          label: 'orange',
          value: 'Orange',
          },
          {
          label: 'apple',
          value: 'Apple',
          },
          {
          label: 'banana',
          value: 'Banana',
          }]"
        @change="handleChange"
    />
    <div>
      <div style="padding:10px 0 0 10px">Value: {{detail.value}}</div>
      <div style="padding:10px 0 0 10px">
        Old Value: {{detail.oldValue}}
      </div>
    </div>
  </div>
</template>

<script>
import "kintone-ui-component";

export default {
  data() {
    return {
      detail: {
        value: "",
        oldValue: "",
      },
      requiredIcon: true
    };
  },
  methods: {
    handleChange(event) {
      console.log(event.detail);
      this.detail = event.detail;
      this.requiredIcon = event.detail.value !== "Apple";
    },
  },
};
</script>

<style scoped>
.dropdown-sample {
  display: inline-flex
}
</style>

A sample of Dialog component

• There are three files, creating content, creating footer and the main.
• Dialog content
  Export a function to handle text change. So the value of text can be used in the main file.

<template>
  <kuc-text
      style="margin: 15px"
      label="Content"
      @change="handleTextChange"
  />
</template>

<script>
import "kintone-ui-component";

export default {
  props: {
    handleTextChange: {
      type: Function,
      default(event) {
        console.log(event);
      },
    },
  },
};
</script>

• Dialog footer
  Export a function to handle button clicking.

<template>
  <kuc-button
      style="margin: 15px"
      text="Set Title"
      @click="handleButtonClick"
  />
</template>

<script>
import "kintone-ui-component";

export default {
  props: {
    handleButtonClick: {
      type: Function,
      default(event) {
        console.log(event);
      },
    },
  },
};
</script>

• The main file
  In mounted lifecycle function, creating HTMLElement for setting "content" and "footer".

<template>
  <kuc-dialog
      ref="kucDialogRef"
      :title="title"
      :content="content"
      :footer="footer"
      @close="handleClose"
  />
  <kuc-button
      text="Show Dialog"
      @click="openDialog"
  />
</template>

<script>
import "kintone-ui-component";
import { createApp } from "vue";
import KucDialogContent from "./kuc-dialog-content.vue";
import KucDialogFooter from "./kuc-dialog-footer.vue";

export default {
  data() {
    return {
      title: "",
      value: "",
      content: null,
      footer: null,
    };
  },
  mounted() {
    const contentDiv = document.createElement("div");
    createApp(KucDialogContent, {
      handleTextChange: this.setValue,
    }).mount(contentDiv);
    this.content = contentDiv;

    const footerDiv = document.createElement("div");
    createApp(KucDialogFooter, {
      handleButtonClick: this.setTitle,
    }).mount(footerDiv);
    this.footer = footerDiv;
  },
  methods: {
    handleClose(event) {
      console.log(event);
    },
    openDialog() {
      this.$refs.kucDialogRef.open();
    },
    setValue(event) {
      this.value = event.detail.value;
    },
    setTitle() {
      this.title = this.value;
    },
  },
};
</script>

KUC component event

• We can use v-on directive to attach an event listener to the element. (@ is the shorthand)

Sample code

• Defining two functions "updateCount" and "handleChange" and using "v-on" to attach them to the element as the event listener.
• "click" is the event of Button component, "change" is the event of Text component.

<template>
  <div class="text-sample">
    <kuc-button
        :text="count"
        @click="updateCount"
    />
    <kuc-text
        className="kuc-text-ui"
        :label="label"
        :error="error"
        :hidden="hidden"
        @change="handleChange"
    />
  </div>
</template>

<script>
import "kintone-ui-component";

export default {
  data() {
    return {
      label: "",
      error: "",
      hidden: null,
      count: 0,
      value: "",
    };
  },
  methods: {
    updateCount() {
      this.count += 1;
      this.error = this.count % 2 === 0 ? "" : this.count;
      this.label = this.count.toString();
    },
    handleChange(event) {
      console.log(event);
      this.value = event.detail.value;
    },
  },
};
</script>

<style scoped>
.text-sample {
  display: inline-flex
}
</style>

KUC component method

• We need using ref to get kuc component instance and call method.
  e.g. this.$refs.kucNotification.open();

Sample code

• Setting the ref of kuc-notification.
• Defining two functions to open and close notification and attaching them to button as the "click" event listener.
• "this.$refs.kucNotification.open()" and "this.$refs.kucNotification.close()" will run when click button.
• "open" and "close" are the methods of Notification component.

<template>
  <div>
    <kuc-notification
        ref="kucNotification"
        text="Notification"
        type="info"
        @close="handleClose"
    />
    <kuc-button
        text="Open Notification"
        @click="openNotification"
    />
    <kuc-button
        text="Close Notification"
        @click="closeNotification"
    />
  </div>
</template>

<script>
import "kintone-ui-component";

export default {
  methods: {
    handleClose(event) {
      console.log(event);
    },
    openNotification() {
      this.$refs.kucNotification.open();
    },
    closeNotification() {
      this.$refs.kucNotification.close();
    }
  },
}
</script>

[dong0]

Overview

As we wrote in the main text, there is a version conflict issue when defining multiple kintone UI Component (KUC) packages on custom JS/plug-in at the same time.

When importing multiple KUC packages (ESM) and using custom HTML tags directly:

For example, we have two scripts that are packaged by webpack as follows.
Here, we have the v1.2.0 script loaded first and v1.3.1 loaded last.

• One script uses v1.2.0 and specifies the text color of Dropdown to be green.
• One script uses v1.3.1 and specifies the text color of Dropdown to be red.

We can see that the text color of Dropdown in the v1.3.1 script is overridden by v1.2.0 script.

You can refer to the Version conflicts issue and solution for the issue detail.

This issue is solved in KUC v1.4.0.

From v1.4.0, you need to write with version number included tag like <kuc-button-x-x-x /> and specify your expected version.
For example, <kuc-button-1-4-0 />, <kuc-text-1-4-0 /> and so on.

In addition, class names have also been changed to avoid CSS style conflicts.
For example, kuc-button-1-4-0__button kuc-button-1-4-0__button--normal.
If you are customizing CSS styles with KUC class names, please be aware of this change.

There is some sample code for reference.

Sample code

Assuming you are currently using KUC v1.4.0 in your project, you can refer to the following sample code.

• Button and Text component
  Using a button to change value of "label" and "error" of Text component.

<template>
  <div class="text-sample">
    <kuc-button-1-4-0
        :text="count"
        @click="updateCount"
    />
    <kuc-text-1-4-0
        className="kuc-text-ui"
        :label="label"
        :error="error"
        :hidden="hidden"
        @change="handleChange"
    />
  </div>
</template>

<script>
import "kintone-ui-component";

export default {
  data() {
    return {
      label: "",
      error: "",
      hidden: null,
      count: 0,
      value: "",
    };
  },
  methods: {
    updateCount() {
      this.count += 1;
      this.error = this.count % 2 === 0 ? "" : this.count;
      this.label = this.count.toString();
    },
    handleChange(event) {
      console.log(event);
      this.value = event.detail.value;
    },
  },
};
</script>

<style scoped>
.text-sample {
  display: inline-flex
}
</style>

• Notification and Button component
  Using two buttons to open/close notification.

<template>
  <div>
    <kuc-notification-1-4-0
        ref="kucNotification"
        text="Notification"
        type="info"
        @close="handleClose"
    />
    <kuc-button-1-4-0
        text="Open Notification"
        @click="openNotification"
    />
    <kuc-button-1-4-0
        text="Close Notification"
        @click="closeNotification"
    />
  </div>
</template>

<script>
import "kintone-ui-component";

export default {
  methods: {
    handleClose(event) {
      console.log(event);
    },
    openNotification() {
      this.$refs.kucNotification.open();
    },
    closeNotification() {
      this.$refs.kucNotification.close();
    }
  },
}
</script>

In order to avoid modifying too much code after future upgrades, you can use the version function to generate the suffix of the tag.
Please refer to the example below.

• Button and Text component

<template>
  <div style="display:flex">
    {{version}}
    <component
        :is="`kuc-button${generateVersionSuffix(version)}`"
        text="Show text value"
        type="submit"
        @click="label = value"
    />
    <component
        :is="`kuc-text${generateVersionSuffix(version)}`"
        :label="label"
        @change="handleChange"
    />
  </div>
</template>

<script>
import { version } from "kintone-ui-component";

export default {
  data() {
    return {
      label: "",
      value: "",
      version
    };
  },
  methods: {
    handleChange(event) {
      this.value = event.detail.value;
    },
    generateVersionSuffix(v) {
      return `-${v.replace(/\./g, "-")}`;
    }
  },
};
</script>