@sharedo/mobile-core

Getting started

About this package

This is an npm package containing reusable components and services to help kick-start your sharedo mobile app. It is hosted on github and available to install via npm.

Check out the sample app demonstrating example usage.

Language and tools

We recommend Vue and Vuetify to make your app look great, and maintain consistency with the components contained within this package.

Icons

You can use any icon from this library: Material Design Icons

Responsive layout

The components in this package are all responsive, making the best use of space on either mobile or desktop browsers.

Installation

First, create your Vuetify app: Getting started with Vuetify

Vue 3 is not officially supported yet for Vuetity apps, so we recommend sticking to Vue 2.

Create a dependency on this package as follows:

npm install @sharedo/mobile-core

Now put this in your main.js:

import '@sharedo/mobile-core/dist/global.css'
import Core from '@sharedo/mobile-core'

// Registers all components globally
Vue.use(Core, settings);

where settings contains the following:

{
identity: (sharedo identity URL),'
api: (sharedo URL),
clientId: "e.g. mobile-app",
clientSecret: "e.g. not a secret",
redirectUri: "https://localhost:8080/oAuthReply"
}

Services

InstallPrompt

If appropriate, this prompts the user to install the progressive web app onto their device.

import {InstallPrompt} from '@sharedo/mobile-core'
...
mounted: function() {
InstallPrompt.init();
}

SharedoAuth

Initialise this service in your main.js to help manage sharedo access tokens. It will automatially redirect the user to the sharedo login page when the token expires.

import {SharedoAuth, SharedoProfile}
from '@sharedo/mobile-core'

// Initialise sharedo authentication
SharedoAuth.initialise(loginPage).then(()=>{

// We have a token! Cache user details
SharedoProfile.loadProfile().then(()=>{

// Now show your main app
createApp(mainAppPage).$mount('#app');
})
}, err=>{ document.write(err); })

Add a login button to your app as follows:

<v-btn
@click="SharedoAuth.reallyRedirectToLogin()">
Log in
</v-btn>

SharedoFetch

Make a request to the sharedo API, using the currently cached access token.

import {SharedoFetch as Fetch}
from '@sharedo/mobile-core'

const id = "...";
Fetch.get(`/api/v1/public/workItem/${id}`)
.then((task) => {
// ...
});

SharedoProfile

Retrieves and stores the current user's details, including global permissions; see full example in SharedoAuth section.

You can log these out as follows:

console.log(SharedoProfile.profile)

Components

The following components are available in this package.

All components are registered globally, so you can use them in your templates without having to import them first.

Bottom Nav

This is a tabbed bottom navigation component, which can be used to navigate between pages of your app.

It should be added to the main view of your app, e.g. in your Main.vue file:

<v-main class="has-bottom-nav">

<VBottomNav>
<template slot="contents">
<v-btn>
<span>Account</span>
<v-icon>mdi-account</v-icon>
</v-btn>
</template>
</VBottomNav>

</v-main>

Add primary-action CSS class to a button to make it stand out.

This is the top toolbar component, which

shows the current page title
handles the side menu
is used for "back" nagivation.

It should be included on every page of your app, e.g.

<VTopToolbar title="Task list" />

An more involved example, with button customisation:

<VTopToolbar title="Task" :showBack="true">
<template slot="right">

</template>
</VTopToolbar>

Displays a banner

<VBannerSharedo>
<template slot="actions">
<v-btn @click="DoSomething()" />
</template>
Click the button to do something.
</VBannerSharedo>

Traffic Light

Displays a red, amber or green traffic light

<VTrafficLight :value="myNumericValue" />

Traffic Light (Date/Time)

Displays a red, amber or green traffic light for a date/time value.

<VDatetimeTrafficLight :value="myDatetimeValue" />

UI helpers

Action sheet

Show an action sheet at the bottom of the screen:

this.$coreUi.actionSheet({
items: [
{type: "header", text: "My header"},
{text: "Click me", color: "primary",
icon: "mdi-check", handler: ...}
]
})

Show a banner across the top of the screen, with configurable buttons:

this.$coreUi.banner({
message: "You're online.",
color: "success",
icon: "mdi-wifi",
multiline: false,
btns: [
{text: "OK", color: "success",
handler: ...}
]
})

If no icon is provided, the 'color' property is applied to the text instead.

Return `false` from your button click handler to prevent the banner from being dismissed.

Dialog

Shows the given component in a full-screen dialog. It is recommended that you use a VCard in the root of your component's template. Initial data is passed into your dialog's props.

this.$coreUi.dialog(MyComponent, [props], [events])

An example with properties and a callback:

this.$coreUi.dialog(SampleForm,
{ ref: "123-AB", title: "Item 123" },
{
closing: function(result) {
console.log("closed", result);
}
});

To close the dialog from within your component:

this.$emit("close", result);

Loading

Show a loading overlay:

var l = this.$coreUi.loading()
// ...
l.dismiss()

Alternatively, you can dismiss all loading overlays at once:

this.$coreUi.loading.dismissAll()

Message box

Show a configurable message box on the screen:

this.$coreUi.messageBox({
title: "Continue",
message: "Are you sure?",
btns: [
{text: "Cancel"}
{text: "Continue", color: "success",
handler: ...}
]
})

The message box is closed and the appropriate handler function is triggered when the user clicks a button.

Toast

Show a "toast" message at the bottom of the screen:

this.$coreUi.toast("Hello there", opts)

You can specify further options as below:

this.$coreUi.toast({
message: "Good job!",
color: "success",
icon: "mdi-check",
dismissable: true,
timeout: -1 // never, default=3000 (ms)
})

Toasts are stacked above one another.