@wellmo/component-devkit v0.1.46

@wellmo/component-devkit

Develop and build Wellmo components using Vue.

Introduction

The user interfaces of Wellmo-powered applications are constructed using components and pages. With @wellmo/component-devkit you can develop custom Wellmo components to use in Wellmo-powered applications. @wellmo/component-devkit will create a Wellmo-like environment with mocks for all necessary client-side APIs where development can be done easily.

When the component is ready you can build it with @wellmo/component-devkit. The build output is a yaml file that can be imported to Wellmo Pro where the end user service is created and managed.

Wellmo Pro has a service page editor where component instances are configured. The available configuration options for a component instance are defined when developing components. How the component is used and how it integrates with the whole service is defined in Wellmo Pro.

Installation

NPM

$ npm install --save-dev @wellmo/component-devkit

CLI

Wellmo provides official CLI (Component-starter) that makes easier to start developing Wellmo components with Vue.js. It provides basic Wellmo component templates for further development. It takes only a few minutes to set up and run with hot-reload, easy to build for the Wellmo platform environment.

Usage

Add following scripts to your package.json:

"scripts": {
    "build": "wellmo-component-devkit build --entry <entryFile> --output <outputDir> --config <configFile> --trackers <mockTrackerDataFile> --data-sources <mockDataSourcesFile> --profile <mockProfileDataFile>,
    "serve": "wellmo-component-devkit serve --entry <entryFile> --config <configFile> --props <mockPropsFile> --trackers <mockTrackerDataFile> --data-sources <mockDataSourcesFile> --profile <mockProfileDataFile> --images <mockImagesDir> --app-state <mockAppStateFile> --port 3333",
    "help": "wellmo-component-devkit --help"
}

Developing Wellmo components

@wellmo/component-devkit uses webpack's dev server to compile and serve components during development. Use the serve command to start the dev server. All API's that are available to components in Wellmo-powered apps are mocked and can be used during development. You can define mock data for those APIs by providing mock data files using the optional arguments.

The serve command requires following arguments:

• --entry Path to source code entry file
• --config Path to component configuration file

Paths to mock data files can be provided with following optional arguments:

• --props Path to mock properties file
• --trackers Path to mock wellness data file
• --reminders Path to mock reminders data file
• --data-sources Path to mock data source data
• --profile Path to mock profile data file
• --images Path to mock images directory
• --app-state Path to mock app state data file

Other optional arguments:

• --port Dev server port number
• --watchPath Path to watch for file changes to restart dev server

Note: All paths must be defined as relative to your project root.

Building Wellmo components

Wellmo components are defined as yaml files that contain all required configuration and JavaScript code. Use build command to create wellmo component from your source code and configuration.

build command takes following required arguments:

• --entry Path to your source code entry file
• --output Path to a directory where the wellmo component yaml file will be created
• --config Path to component configuration file

build requires mock data to enable proper preview rendering in Wellmo Pro. In the end user app this data is not included. Path to mock data files can be provided with following optional arguments:

• --trackers Path to mock wellness data file
• --data-sources Path to mock data source data

Note: All paths must be defined as relative to your project root.

Defining component configuration

Example config.yaml

name: my component
description: My component description
componentId: my_component_v1

import:
  Vue: vue-2.5

properties:
  text:
    title: Message
    type: string
    default: Hello!
    required: true
  textColor:
    title: Text color
    format: color
    type: string
    default: "#555555"
  addBorder:
    title: Add border
    type: boolean
  textAlign:
    title: Text alignment
    type: string
    enum:
      - "left"
      - "center"
      - "right"
      - "justify"
  fontSize:
    title: Font size
    type: number
    default: 1
  dataSourceId:
    title: Data source id
    type: string
    default: sourceId1
    required: true
  imageUrl:
    title: Image
    type: string
    format: image
    default: "/rest/files/61432ead8845cd2da286a0363a5c74212aca6aa8.png"
    required: true
  image:
    title: Image with possible alternative text
    type: object
    format: image_v2
    default: 
      src: "/rest/files/61432ead8845cd2da286a0363a5c74212aca6aa8.png"
      alt_text: ""
      extension: "png"
      width: 640
      height: 212
    required: true

actions:
  onClickAction:
    eventLabel: 'on-click'
    title: On click action

previewImage: "img/preview.png"

Define the path to your config file using the argument --config.

Using properties

Properties are variables that can be configured for each component instance in Wellmo Pro. Typically properties are used for making texts, styles, images, etc. configurable for each component instance. Also each language can have their own values for properties enabling localization. During development properties can be mocked by defining a js file that exports an object as shown below:

const imagesPath = 'images/'; // DO NOT CHANGE

export default {
  text: "Hello world!",
  textColor: "green",
  addBorder: false,
  textAlign: "center",
  fontSize: 1,
  dataSourceId: "sourceId1",
  imageUrl: `${imagesPath}test.jpg`,
  image2: {
    src: "/rest/files/61432ead8845cd2da286a0363a5c74212aca6aa8.png",
    alt_text: "",
    extension: "png",
    width: 640,
    height: 212
  },
};

Define the path to your properties mock file using the argument --props.

Using wellness and account data

Wellness and account data in Wellmo-powered apps can be used in components through a property called wellmo. It contains both the wellmo account data and apis to read and manipulate that data.

// In <entryFile>. For example, Main.vue

<script>
export default {
  props: {
    wellmo: Object,
    ...,
  }
}
</script>

Note: Access to props in the app is restricted to those explicitly defined here. This means that in order for props like wellmo, app, and data to be accessible in the app, they must also be declared explicitly in this context.

Reading wellness data

When you want to show wellness data in your components you first need to ensure that the data is available through the wellmo property. To ensure data for a tracker in a given time range call the below function:

wellmo.api_v1.tracker.ensureData(trackerId, options)

where the trackerId is the id of the tracker (steps, exercise, etc.) and the options object contains following required fields:

{
  aggregation: String,  // raw | daily | weekly
  start: Date,          // start date
  end: Date             // end date
}

After calling ensureData the data will appear asynchronously in:

wellmo.data.tracker[trackerId].samples[aggregation]

Each data point with aggregation daily or weekly has date and data fields. The value of data field is an object and its fields depend on the tracker. Data points with aggregation 'raw' have different fields and they also contain the id of the data point which can be used e.g. to delete the data point.

In Wellmo powered apps the user may choose the preferred unit system (e.g. metric vs. imperial). The values of the data point data are in the user units. The current units are available through wellmo property as shown below:

wellmo.data.tracker[trackerId].units[dataKey]

where the dataKey is the data field name (same as in the raw sample's data object), e.g. wellmo.data.tracker.exercise.units.energy -> kcal.

Creating wellness data

To create wellness data call the below function:

wellmo.api_v1.tracker.createData(trackerId, data)

where the trackerId is the id of the tracker (steps, exercise, etc.) and the data is the data point data.

Deleting wellness data

To delete data points call the below function:

wellmo.api_v1.tracker.deleteData(trackerId, dataPointId)

where the trackerId is the id of the tracker (steps, exercise, etc.) and the dataPointId is the id of the data point (e.g. 5df790450dcb694dd0e25bec)

Reading tracker target

Some trackers may have targets. To access the target call the below function:

wellmo.api_v1.tracker.ensureTarget(trackerId)

where the trackerId is the id of the tracker (steps, exercise, etc.).

After calling ensureTarget the target will appear asynchronously in:

wellmo.data.tracker[trackerId].target

Setting tracker target

To set the tracker target call the below function:

wellmo.api_v1.tracker.setTarget(trackerId, target)

where the trackerId is the id of the tracker (steps, exercise, etc.) and the target is an object containing the following mandatory fields:

{
  active: Boolean,
  data: {
    ...
  }
}

Reading reminders

Trackers may also have reminders which are used to remind users to enter data for those trackers. To access the reminders call the below function:

wellmo.api_v1.tracker.ensureReminders(trackerId)

where the trackerId is the id of the tracker (steps, exercise, etc.).

After calling ensureReminders the reminders will appear asynchronously in:

wellmo.data.tracker[trackerId].reminders

Creating reminders

To create a reminder call the below function:

wellmo.api_v1.tracker.createReminder(trackerId, reminder)

where the trackerId is the id of the tracker (steps, exercise, etc.) and the reminder is the reminder object containing the folowing mandatory fields:

{
  trackerId: String,     // The id of the tracker (e.g. steps, exercise, etc.)
  time: String,          // Time in format 'hh:mm'
  weekDay: Int           // 0 = Monday, ..., 6 = Sunday, 7 = weekdays, 8 = weekends, 9 = daily
}

Delete reminder

To delete a reminder call the below function:

wellmo.api_v1.tracker.deleteReminder(reminderId)

where reminderId is the id of the reminder.

Providing mock wellness data

During development wellness data can be mocked by defining a js file that exports an object as shown below:

const today = (days = 0) => {
  return new Date(Date.now() + days * 24*60*60*1000).getTime();
};

export default {
  steps: {
    samples: {
      daily: [
        {
          date: today(),
          data: {
            steps: 1234,
            distance: 800
          }
        },
        {
          date: today(-1),
          data: {
            steps: 8000,
            distance: 5000
          }
        },
        ...
      ],
      weekly: [
        {
          date: new Date(),
          data: {
            steps: 50000,
            distance: 30000
          }
        }
        ...
      ]
    },
    target: {
      active: true,
      data: {
        steps: 10000
      }
    }
  }
}

Define the path to your wellness data mock file using the argument --trackers.

See documentation about Wellmo Account and supported wellness data types.

Providing mock reminders data

Tracker reminders can also be mocked by defining a js file that exports an object as shown below:

export default [
  {
    "id": "mock-reminder-1",
    "trackerId": "sleep",
    "weekDay": 6,
    "time": "08:00"
  },
  {
    "id": "mock-reminder-2",
    "trackerId": "steps",
    "weekDay": 0,
    "time": "21:00"
  }
]

Define the path to your reminders mock file using the argument --reminders.

Reading account data

Account data can be accessed through:

wellmo.data.account

The exposed fields are the following:

  firstName: string,
  lastName: string,
  email: string,
  gender: string,
  height: number,
  weight: number,
  unitSystem: string,
  energyUnit: string,
  bloodGlucoseUnit: string,
  language: string,
  country: string,  
  dateOfBirth: date

Setting account data

Functions for setting account data are provided by the wellmo.api_v1.account.* -namespace, exceptions being email and weight -fields.

Functions are asynchronous and will return a promise that will either get resolved when the value is set or rejected with an error message if the given value does not get through validation. During development validation is mocked by the devkit.

Set first name

• firstName
  • string
  • no special characters
  • no numbers
  • no more than 50 characters long

wellmo.api_v1.account.setFirstName(firstName)

Set last name

• lastName

  • string
  • no special characters
  • no numbers
  • no more than 50 characters long

wellmo.api_v1.account.setLastName(lastName)

Set gender

• gender
  • string
  • m or f

wellmo.api_v1.account.setGender(gender)

Set height

• height
  • number
  • greater than 0

wellmo.api_v1.account.setHeight(height)

Set unit system

• unitSystem
  • string
  • METRIC or IMPERIAL

wellmo.api_v1.account.setUnitSystem(unitSystem)

Set energy unit

• energyUnit
  • string
  • CALORIE or JOULE

wellmo.api_v1.account.setEnergyUnit(energyUnit)

Set blood glucose unit

• bloodGlucoseUnit
  • string
  • MMOL_PER_L or MG_PER_DL

wellmo.api_v1.account.setBloodGlucoseUnit(bloodGlucoseUnit)

Set language

• language
  • string
  • language code for one of the supported languages
    • en, fi, sv, nl, de, pl, nb

wellmo.api_v1.account.setLanguage(language)

Set country

• country
  • string
  • country code for one of the supported countries
    • AE, AT, AU, BE, CA, CH, CZ, DE, DK, EE, ES, FI, FR, GB, GR, HU, IE, IS, IT, LT, LU, LV, NL, NO, NZ, PE, PL, PT, RU, SE, SK, TR, US, ZA

wellmo.api_v1.account.setCountry(country)

Set date of birth

• dateOfBirth
  • javascript date
  • valid date
  • not less than 14 years ago

wellmo.api_v1.account.setDateOfBirth(dateOfBirth)

Providing mock account data

Account data can be mocked by defining a js file that exports an object as shown below:

export default {
  firstName: 'John',
  lastName: 'Doe',
  email: "test@foo.com",
  gender: "m",
  height: 180,
  weight: 70,
  unitSystem: "METRIC",
  energyUnit: "CALORIE",
  bloodGlucoseUnit: "MMOL_PER_L",
  language: "en",
  country: "FI",  
  dateOfBirth: new Date("05/22/1990")
}

Define the path to your account/profile mock file using the argument --profile.

Using external data sources

Components can also use external data. In most cases you shouldn't do AJAX requests directly from your components. Instead, you can use Wellmo's configurable data sources and Wellmo will handle fetching the data for you. In Wellmo Pro you can select which data sources you want to use in your component instance. The data from the selected data sources is provided to the component in a property called data. The data property is an object containing all data sources as shown below:

{
  dataSourceId1: {
    ...
    $loading: false,
    $default: false,
    $error: false,
    $age: 0
  },
  dataSourceId2: {
    ...
    $loading: true,
    $default: true,
    $error: false,
    $age: undefined
  },
  ...
  $loading: true
}

Wellmo extends the data with metadata fields. When data sources are configured it is possible to define default data that will be instantly available when the app is used first time. Default data will be replaced by the actual fetched data when available. The $default flag defines whether or not the data is default data or actual data returned from the data source endpoint. $loading flag is true when the data fetch is in progress. If for some reason the fetch fails the $error flag will be true. When the fetch is successfull the returned data is cached. When cached data is available that will be provided instantly instead of the default data. The $age metadata value defines the age of the data in milliseconds. The data is refreshed automatically.

During development data source data can be mocked by defining a js file that exports an object as shown below:

export default {
  sourceId1: {
    data: {
      key1: 'value1',
      key2: 'value2'
    },
    defaultData: {
      key1: 'default-value-1',
      key2: 'default-value-2'
    }
  }
};

Define the path to your data source mock file using the argument --data-sources.

Using application state data

Application state currently contains the number of unread Wellmo messages and the number of triggered tracker reminders and the navigation history of pages the user has traversed through to the current page.

Application state is available in:

app.state

During development app state data can be mocked by defining a js file that exports an object as shown below:

export default {
  unreadMessageCount: 2,
  triggeredRemindersCount: 1,
  navigation: {
    history: [
      { pagePath: "my_company/main" },
      { pagePath: "my_company/service_page1" },
      { pagePath: "my_company/service_page2" }
    ]
  },
  page: {
    pageState: {}
  }
};

Define the path to your app state mock file using the argument --app-state.

Using images

We recommend that you make images configurable meaning that you should define a string property of type format:image for each image and use that string as the image url. That way the images can be chosen in the Wellmo Pro service page editor.

Below is an example how to configure an image in config.yaml:

myImageUrl:
  title: Image
  type: string
  format: image
  default: "/rest/files/61432ead8845cd2da286a0363a5c74212aca6aa8.png"
  required: true

The above configuration will add a field to your component configuration form in Wellmo Pro. The image url is provided to your component in a property called myImageUrl.

During development you can use images in your local filesystem. You need to put all images that you want to use to a single directory. Provide the path to your local images directory using the argument --images. You also need to define your images in the mock properties js file as shown below:

const imagesPath = 'images/'; // DO NOT CHANGE

export default {
  ...
  imageUrl: `${imagesPath}test.jpg`,
};

where test.jpg is your image filename.

Note that you should not change the imagesPath above and it is not the same as the path to your local images directory.

Using dynamic actions

You can execute actions directly from the component using the methods provided by the app.api_v1.* -namespace.

For instance, you could trigger opening a page directly from the component vue source code by defining the following click handler (Note that the second argument 'page parameters' is optional):

<button @click="app.api_v1.openPage('example_page_id', {example_key: 'example_value'})">
  Open example page
</button>

During development triggering dynamic actions displays an alert on success, and helpful console error on failure so remember to keep your development console open.

The app.api_v1.* provides supports for the following actions:

Open a page

/**
 * pageId (required, string)
 * pageParameters (optional, object)
 */
app.api_v1.openPage(pageId, pageParameters);

Open a URL

/**
* url (required, string)
* webLoginWithSSORequired (required, boolean)
*/
app.api_v1.openUrl(url, webLoginWithSSORequired);

Go back to the previous page

app.api_v1.goBack();

Log out

app.api_v1.logOut();

Send an email

/**
 * emailAddress (required, string with "@")
 */
app.api_v1.sendEmail(emailAddress);

Call a phone number

/**
 * phoneNumber (required, string)
 */
app.api_v1.callNumber(phoneNumber);

Execute wellmo pro configured action

/**
 * action (required, string)
 * actionId (optional, string)
 */
app.api_v1.executeWellmoProConfiguredAction(action, actionId);

You can define actions that your custom component can trigger for example when the user clicks on an element. These actions can be configured in Wellmo Pro to do the following:

• Open a page
• Open a URL
• Go back to the previous page
• Send an email
• Call a phone number
• Open a native app
• Subscribe the member to group(s)
• Continue flow

Actions are configured in Wellmo Pro when creating an instance of your component. You can define actions in your config.yaml as shown below:

actions:
  onClickAction:
    eventLabel: 'on-click'
    title: On click action

To trigger the above action from your component you can call the action with your defined eventLabel as the only argument: app.api_v1.executeWellmoProConfiguredAction('on-click') or also with an action ID to be able to track the status of a given action: app.api_v1.executeWellmoProConfiguredAction('on-click', 'my-on-click-action-id'). Then, the method returns:

• undefined if the action is not started,
• the value of the actionId if any is passed, or
• a random UUID associated to that action if no string is passed.

At the same time, the following page state parameters (see below for how to retrieve them) are updated:

• $isActionExecuting, a boolean flag regarding whether an action is being executed or not at the moment.
• $executingActions, an array of strings with the different actionIds of the actions being executed.

During development, triggering actions will just call alert with the given eventLabel. At the moment, the changes in $isActionExecuting and $executingActions cannot be observed there, only in production.

To get better accessibility for the actions, it is recommended to use <w-action-v1> instead of calling the method.

Writing data to page state

You can write data to page state which can be sent to a custom data store if such sending action is configured already in the Wellmo Pro platform.

Wellmo provides APIs to retrieve, set, and delete page state property for component development:

Retrieve page state

/**
 * The default pageState is {}
 */
app.state.page.pageState;

Write data to page state

/**
 * path (required, string)
 * data (required, any)
 */
app.api_v1.page.setPageStateProperty(path, data);

// Here's an example of usage
app.api_v1.page.setPageStateProperty('question.color', 'red');
app.api_v1.page.setPageStateProperty('question.food', 'apple');
/**
 * The above would set the pageState to the following:
 * {
 *   question: {
 *     color: 'red',
       food: 'apple'
 *   }
 * }
 */

Delete data in page state

/**
 * path (required, string)
 */
app.api_v1.page.deletePageStateProperty(path);

// Here's an example of usage
app.api_v1.page.deletePageStateProperty('question.food');
/**
 * The above would delete the pageState property 'question.food'.
 * The pageState after deletion:
 * {
 *   question: {
 *     color: 'red'
 *   }
 * }
 */

Configure action to store page state

Please note that the data stored in page state is not sent to the server database automatically. If you need to store the user input data, you have to configure an action to send a request with the page state.

The first step to configure an action to store data is to create a custom data storage that defines the source ID, data schema, and default data. The following is an example of custom data storage that can be edited in Wellmo Pro:

source ID: member_food

data schema:

{
  "type": "object",
  "properties": {
    "food": {
      "type": "string"
    }
  }
}

default data: {}

Then you can start to configure the action in Wellmo Pro. For example, if you want to store the page state into the custom data storage created above, you might need to configure the action as follows:

{
  "member_food": [
    {
      "field": "food",
      "action": "set",
      "value": {{pageState.question.food}}
    }
  ]
}

The configuration of this action means that when the action is executed, the value would be set in custom data storage with the field "food". The supported actions are listed in the Wellmo Pro API documentation.

But before setting the value to custom data storage, the value {{ pageState.question.food }} will be replaced with the page state object { question: { food: "apple" } }. So the final action would be:

{
  "member_food": [
    {
      "field": "food",
      "action": "set",
      "value": "apple"
    }
  ]
}

After the above action is executed, the member custom data { "member_food": { "food": "apple" } } would be stored.

You can also use {{}} to subscribe/unsubscribe to a member group. To do so, you can configure the action as follows in Wellmo Pro:

{
  "subscribe": [
    "{{ pageState.subscription.group1 }}"
  ]
}

If the page state object is { subscription: { group1: "smoking" } }. When action is executed, the member would subscribe to the group "smoking" if there is a group "smoking" created already.

Except for the pageState, you can use the data source to apply data to your action template as well. The first step is to create data sources in Wellmo Pro platform. Please read more about supported data sources.

After creating the data source and selecting the data source in your component instance, the data from the selected data sources is provided to the component in a property called data. For example, if the data source id of the selected data source is sourceId1 and the data source object contains a property food, we can then configure the component action template as follows:

{
  "member_food": [
    {
      "field": "food",
      "action": "set",
      "value": {{ data.sourceId1.food }}
    }
  ]
}

When the above action is executed, the {{data.sourceId1.food}} would be replaced with the data contained in the data source sourceId1.food.

The last variable you can use in your action template is timestamp which is created on the server-side when the action to store custom data is executed. So if you need to store the timestamp into custom data storage, you can configure your action template with {{server.timestamp}} which would be replaced with date format "yyyyMMddHHmmssSS".

Retrieving parameters from the previous page

You can access the data passed from the previous page. For example, on the previous page, there is a component having an action to open the current page and it also passes page parameters to the current page. The page parameters passed from the previous page are stored on the current page and any components on the current page can retrieve it by calling app.state.page.pageParameters.

It is also possible to pass data in data source or page state as page parameters to the next page. For example, on the current page, there is a component having an open page action with the following arguments:

<button @click="app.api_v1.openPage('example_page_id', { example_key: '{{pageState.id}}' })">
  Open example page
</button>

If the page state object in the current page is { id: 1 }, when clicking this button to open the example page, the page parameters { example_key: '{{pageState.id}}' } will be replaced to { example_key: '1' } and then be passed into the example page.

Using third party libraries

You can use the following third party libraries:

• vue-2.5
• d3-5.4
• moment-2.24
• moment

To use for example d3 library you need to add following configuration to your config.yaml:

import:
  d3: d3-5.4

where d3-5.4 is the library to import and d3 is the variable name you want to use in your code. If you need to use libraries that are not in the above list, please contact Wellmo support.

Wellmo app also has some libraries bundled in, e.g. moment. To use the same version of the library that is bundled into the app leave the version number undefined. Using the bundled version of the library will have some benefits. The initial load is faster and in some cases it may be configured based on user settings. Example of this is the moment library which is localized based on the user preferences.

Note that everything you import directly in your source code will be bundled into your component. This is fine if the library is very small, e.g. a single lodash function, but in most cases you should avoid bundling libraries to the component and instead use the above described system.

In summary, if you still need to use a specific third party library (such as lodash) which is not provided by the platform, you can install it as you normally would by using the traditional npm commands, such as npm install --save-dev lodash.

Writing CSS (best practices)

Since version 0.1.31 of the component-devkit, the preferred way of writing CSS for new components is to use CSS Modules syntax.

The reason for moving away from the more traditional Scoped CSS approach is the fact that it could not guarantee truly unique styles between components using CSS selectors with same names; In addition, the selector names (css class names) might also conflict with the wellmo.css which is a special stylesheet included by the platform for every page the components are being rendered at. For these reasons, you should always prefer writing CSS with CSS Modules syntax because it is a bug-free approach. In any case, the Scoped CSS approach is still supported by the component-devkit, but mostly for backwards compatibility reasons.

You can compare the two different approaches for writing the CSS below. The CSS Modules syntax is arguably more harder syntax to understand, but in return you can guarantee that the components looks and feels the way you intended in a live environment, as the CSS selector names are generated in a format of e.g. .redText-94411ba.

CSS Modules

<template>
  <div class="container">
    <div :class="$style.redText">Hello World!</div>
  </div>
</template>

<style module>
   /* Global style */
  :global(.container) {
    padding: 10px;
  }

  /* Local style */
  .redText {
    color: red;
  }
</style>

Scoped CSS

<template>
  <div class="container">
    <div class="red-text">Hello World!</div>
  </div>
</template>

<style>
  /* Global style */
  .container {
    padding: 10px;
  }
</style>

<style scoped>
  /* Local style */
  .red-text {
    color: red;
  }
</style>

Vue component's lifecycle

At present, the beforeDestroy hook isn't available for use within the Main.vue file, which is a Single File Component (SFC). This limitation stems from the fact that components are forcibly removed from the Document Object Model (DOM) during certain operations, such as page navigation or when a component needs to be hidden based on specific visibility settings. Despite this restriction, subcomponents nested within Main.vue are still able to utilize the beforeDestroy hook without any issues.

Creating a Vue.js component library

In case you are creating multiple wellmo components with similar UI, or your company needs to have consistent UI across different Vue projects, you might want to consider creating a Vue component library that can be added as a dependency to your npm projects. In other words, Vue component library is just a Vue plugin similar to BootstrapVue that provides multiple UI components, such as buttons, alerts and banners to your needs. That being said, creating a Vue component library have nothing to do with the wellmo devkit in particular, and there are multiple different ways of creating such, but we figured that this process is important to document as we are using our own UI component library as well in some of our wellmo components.

In any case, like being said, there are multiple different ways of creating such library, but at the time of this writing, using either Vue CLI in library mode, or vue-sfc-rollup seems to be the best alternatives. Hence, we propose that you choose the latter as we have tested that it works, and seems to offer more benefits than Vue CLI which is just a nice wrapper around Webpack.

Rollup offers optimizations like tree shaking that make it ideal for building shared libraries. This plugin also prioritizes defaults that are ideal for most Vue plugins and UI component libraries. (Source)

In short, creating the UI component library using Rollup results to smaller bundle size, as the bundled version of your custom wellmo component contains only the source code of the UI components you are actully importing in your code as e.g. import { ExampleButton } from 'my-ui-library';

For further reading, I recommend checking out Packaging Vue Components for npm which basically explains how does the vue-sfc-rollup is made-up.

1) Creating a Vue.js component library using vue-sfc-rollup

Follow the steps defined in README.md to create a Vue.js component library. Hence, do not forget to run npm run build as it will create the proper files inside the /dist folder that your custom wellmo component will be importing using e.g. import { ExampleButton } from 'my-ui-library';

2) Adding Vue.js component library as a dependency

After you have created the Vue component library and publihed it to npm, you can add it as a dependency to your custom wellmo component via npm as you normally would (using npm install my-ui-library). However, if you want to just test things locally before publishing anything you can use the npm install <path-to-your-library> -command which should add line similar to following inside your package.json file:

"dependencies": {
  "my-ui-library": "file:../my-ui-library",
  ...
}

3) Using a component from your Vue.js component library

You should be now able to use your UI components by importing them using e.g. import { ExampleButton } from 'my-ui-library'; and then placing them between the template blocks.

<template>
  <example-button />
</template>

Note: Make sure you replace my-ui-library and ExampleButton with whatever library name and component(s) you have inside your own Vue.js component library. So do not follow the examples above blindly. At the time of this writing, the vue-sfc-rollup seems to create an example component with a name based on the library name you have chosen.

Defining a preview image for Wellmo Pro

When the component is imported to Wellmo Pro it will be available in the service page editor tool. You can define how it is shown in the component list by defining a previewImage in your config file as shown in the example below:

previewImage: "img/preview.png"

Use a simple image from which the Wellmo Pro user can understand what your component is. The whole component doesn't have to be shown in the image. A good width for the image is 375px. If possible try to keep the height below that.

If you don't define a previewImage then your component is shown as a box containing a description from your config file.

Note that when the component is put to a page in Wellmo Pro an instance of the real component is created and rendered using the provided mock data.

Accessibility

Using Wellmo Action Web Component

Wellmo provides accessibility features for actions via separate component. It can be accessed anywhere in your components using

<w-action-v1
    action-name="on-click"
    action-role="link"
    :action-label="ariaLabel"
>
<your-component-tag></your-component-tag>
</w-action-v1>

Component attributes:

1. action-name: Needs to refer to the action's eventLabel. For example, in config.yaml

actions:
  onClickAction:
    eventLabel: 'on-click'
    title: On click action

2. action-role: ARIA role for the screen reader (optional). Configures the role if the automatically assigned based on the action should be customised.

3. action-label : ARIA label for the screen reader (optional). It may override ARIA labels of the elements within.

Component properties (JS):

1. actionBeforeConfigured: a parameterless, void-returning function with any needed side effects to be carried out before the action configured in Wellmo Pro should be performed. It is optional, nothing is performed if nothing is passed and it triggers no error either.

2. actionAfterConfigured: a parameterless, void-returning function with any needed side effects to be carried out after the action configured in Wellmo Pro should be performed. It is optional, nothing is performed if nothing is passed and it triggers no error either.

Custom events:

1. update-action-id: the detail of the event contains updatedActionId property the value of which is the action ID of the just triggered action. It can be listened to and it requires stopping it to prevent it from bubbling up and affecting other action components. Its value will update with the new action ID every time the user clicks on the element and triggers the action. It can be watched, e.g. for loading spinners, to track the action and know its status.

Note:

1. The element or elements that should perform the action should always be wrapped by this component <w-action-v1>.

License

MIT