@hotelkeyrepo/hk-trainkey-npm v4.5.56

HK-Trainkey

What is trainkey?

HK-Trainkey is a npm package designed to enable HK-developers to create in-app tutorials through interactive tooltips. With HK-Trainkey, you can easily add a step-by-step tutorial to HK web applications, making it easy for users to learn how to use HK products or services.

The package is easy to install and use, and offers a variety of customization options to help you tailor your tutorial to your specific needs. You can choose the size, and position of your tooltips, as well as the content and layout of your tutorial steps.

Overall, HK-Trainkey is an excellent tool for developers who want to create engaging and informative in-app tutorials that can help users get the most out of their product or service.

Install and Setup HK-Trainkey

1. Open your terminal or command prompt.
2. Navigate to the root directory of your project.
3. Run the following command to install HK-Trainkey:

npm i @hotelkeyrepo/hk-trainkey-npm

4. Once the installation is complete, you can import HK-Trainkey into your project using the following code:

   Keep in mind this can be vary from project to project.

main.js

In main.js import the global trainkey components, and flowy plugin, and then initialize the components, and flowy like such:

// other code

import { trainkeyComponents, FlowyPlugin } from "@hotelkeyrepo/hk-trainkey-npm/src";

trainkeyComponents.forEach((component) => {
	Vue.component(component.name, component.component)
})

Vue.use(FlowyPlugin);

// other code

Trainkey also needs to be initialized and needs it styles, so don't forget to import them like this:

import '@hotelkeyrepo/hk-trainkey-npm/src/trainkey/init'
import '@hotelkeyrepo/hk-trainkey-npm/src/trainkey/plugins/flowy-vue/dist/lib/flowy-vue.css'

mixin.js

In mixin.js import useTrainkeyStore and set getTooltipObject as a global computed value:

import {useTrainkeyStore} from "@hotelkeyrepo/hk-trainkey-npm/src";

// other code
computed: {
  ...piniaMapState(useTrainkeyStore, {
      getTooltipObject: (state) => state.getTooltipObject,
    }),

// other code

router.js

In order to be able to use the rule engine functionality we need to handle them on the router.js file:

// other code

import { handleTriggers } from "@hotelkeyrepo/hk-trainkey-npm/src";
import piniaInit from "@/plugins/piniaInit";

// other code

router.afterEach((to, from) => {
  handleTriggers(to, from, router, piniaInit);
})

// other code

directory.js

In your directory initializer import trainkey like this, in order to be able to use it like a directory:

import * as hotelkeyTip from "@hotelkeyrepo/hk-trainkey-npm/src/trainkey/directives/v-training/hotelkey-tip.directive";

export default {
    // other directives
	hotelkeyTip
};

App.vue

In App.vue import

• TrainkeyComponent and TriggerToastMessage then set them as an App.vue component.
• setBaseRouterPath and set the value of your default screen.
• useRuleEngineStore as we need it for the trigger toast messages.

<template>
  <div id="app">
    <router-view/>
    <trigger-toast-message v-if="triggerToastMessage && triggerToastMessage.show"/>
    <trainkey-component></trainkey-component>
  </div>
</template>

<script>
import { TriggerToastMessage, TrainkeyComponent, useRuleEngineStore, setBaseRouterPath } from '@hotelkeyrepo/hk-trainkey-npm/src';
export default {
  components:{
    TrainkeyComponent,
    TriggerToastMessage
  },
  beforeMount(){
    setBaseRouterPath('dashboard');
  },
  computed: {
    ..piniaMapState(useRuleEngineStore, {
      triggerToastMessage: state => state.triggerToastMessage,
    }),
  }
}
</script>

Home.vue

In Home.vue you will need to initialize the trigger rules and the trainkey store, and also import some trainkey components.

<template>
    <div>
      <sidebar-component             
        @openTrainKeyTopics="trainKeyTopicsVisible=true, hideCurriculumTab=false" 
        @showNotifications="show_notifications=true"></sidebar-component>
      <div> CONTENT </div>
    </div>
    <train-key-debug-table
      v-if="openTrainKeyDebugTable"
      @close="openTrainKeyDebugTable=false"
    />
    <TrainKeyTopic
      v-if="trainKeyTopicsVisible"
      @close="trainKeyTopicsVisible=false"
      :hideCurriculumTab="hideCurriculumTab"
      @openNotifications="show_notifications = true"
    ></TrainKeyTopic>
    <notifications-manager
      v-if="show_notifications"
      @close="show_notifications = false"
    />
  </div>
</template>

<script>
import { setEnterprisePermissionsForTrainkey, setPropertyForTrainkey, getTrainKeyTriggerRules TrainKeyDebugTable, TrainKeyTopic NotificationsManager, InitializeRuleEngine } from '@hotelkeyrepo/hk-trainkey-npm/src/index';

// these can be different depending from the project
import router from "@/router/router"
import piniaInit from '../plugins/piniaInit'
import SidebarComponent from "@/components/SidebarComponent.vue";

export default {
  name: 'HomeView',
  components: {
    SidebarComponent,
    TrainKeyDebugTable,
    TrainKeyTopic,
    NotificationsManager,
  },
  data() {
    return {
      trainKeyTopicsVisible: false,
      hideCurriculumTab: false,
      show_notifications: false,
      openTrainKeyDebugTable: false,
    }
  },
  mounted() {
    // other code

    // set these two under the appropriate api calls.
    setEnterprisePermissionsForTrainkey(enterprisePermissions);
    setPropertyForTrainkey(property);

    // other code

    if (this.hasTriggerRulePermission) {
      getTrainKeyTriggerRules(this.$route, router, piniaInit);
      InitializeRuleEngine(this.$route, router, piniaInit);
    }

    // other code
  },
  methods: {},
  computed: {
    hasTriggerRulePermission(){
      return checkPermission(this.enterprisePermissions 'ENTERPRISE_TRAINKEY_RULE_TRIGGER','READ_WRITE') || checkPermission(this.enterprisePermissions, 'ENTERPRISE_TRAINKEY_RULE_TRIGGER','READ')
    },
  }
}
</script>

Sidebar.vue

Depending on the project this file name can different. Here import TrainkeyMenuItem component and the GetTooltipWatcher function. And use them in a similar way.

<template>
    <trainkey-menu-item
        @openTrainKeyTopics="openTrainKeyTopics($event)"
        @showNotifications="showNotifications($event)"
    ></trainkey-menu-item>
</template>

<script>
import { GetTooltipWatcher, TrainkeyMenuItem } from '@hotelkeyrepo/hk-trainkey-npm/src'
export default {
  name: "SidebarComponent",
  components:{
    TrainkeyMenuItem
  },
  methods:{
    openTrainKeyTopics() {
      this.$emit('openTrainKeyTopics');
    },
    showNotifications() {
      this.$emit('showNotifications');
    },
  },
  watch: {
    getTooltipObject: {
      handler(newVal, oldVal) {
        GetTooltipWatcher(newVal);
      }
    }
  },
}
</script>

interceptor.js

Depending on if the project requires trainkey to continue the flow when interrupted by errors, in Interceptor.js add:

import {continueFlow} from '@hotelkeyrepo/hk-trainkey-npm/src';
...
if (response?.status >= 400) {
    continueFlow();
  }
  ...

5. With HK-Trainkey installed, you can now create interactive tooltips and in-app tutorials for your web application or website by adding v-hotelkey-tip="{id:''}" to a HTML element.

You can also refer to projects that have already implemented the trainkey package such as web-frontdesk or rate-administration.

Use v-hotelkey-tip

To use HK-Trainkey to add tooltips to your web application or website, use the v-hotelkey-tip directive on any HTML element to create a tooltip. The id attribute follows the structure simple_description@Screen. Here are three types of tooltips:

Normal tooltip

Used to display a simple tooltip

<p v-hotelkey-tip="{id:'message_text@HomeView'}">
    {{ message_text }}
</p>

Branch tooltip

Used to create branching tooltips

<div v-hotelkey-tip="{id: 'test_branches@TestForm', hasBranches: true}" >
   <div v-hotelkey-tip="{id:'test_branch1@TestForm', isBranch: true, branchWrapper:'test_branches@TestForm'}">
      Test branch 1
   </div>
   <div v-hotelkey-tip="{id:'test_branch2@TestForm', isBranch: true, branchWrapper:'test_branches@TestForm'}">
      Test branch 2
   </div>
</div>

Placement tooltip

Used to set the placement of a tooltip. Placement can have these values: top, top-start, top-end, right, right-start, right-end, bottom, bottom-start, bottom-end, left, left-start, left-end

<div v-hotelkey-tip="{id: 'test@TestForm',  placement:'right-start'}">
    Test
</div>

HK-trainkey UI functionalities

Help Center

When a user installs and completes the setup process successfully, the below component should be displayed at the Sidebar.

Topics

Upon clicking the Help Center, the trainkey topics pop-up should open. Depending on the user permissions, the view of the pop-up is going to change.

Use trainkey

• If the user wants to design a new trainkey flow, first, we toggle the "Show Trainkey Designer" to ON, close the pop-up, and start adding tooltips to the flow by hovering over components and clicking the "Add to Topic" button. When clicked, the tooltip will be added to the trainkey designer.

• If the user wants to play an existing trainkey flow, they will choose a topic from the "Topic Repository" or "Tracks". Once the flow (topic) is clicked, if the user has "Show Trainkey Designer" on, trainkey will open the trainkey designer. If not, the trainkey flow should start.

Edit Tooltip

If the user wants to edit the tooltip, he can do that by clicking Advanced Editing, or for a simple edit he can click the edit button.

And that's it! You've successfully installed HK-Trainkey and can now start creating informative and engaging in-app tutorials.