Skip to content

This library allows Surix apps to interact with the Surix web client.

Notifications You must be signed in to change notification settings

alphamanuscript/surix-client-service

This branch is 1 commit ahead of master.

Folders and files

NameName
Last commit message
Last commit date

Latest commit

67f954b · Dec 11, 2020
Nov 23, 2018
Oct 1, 2018
Nov 23, 2018
Nov 19, 2018
Aug 16, 2018
Nov 23, 2018
Nov 22, 2018
Aug 24, 2018
Nov 23, 2018
Nov 22, 2018
Aug 28, 2018
Dec 11, 2020

Repository files navigation

App Service

This library allows Surix apps to communicate with the host Surix web client.

The service needs to be imported first before use

import { Service, requests } from '@surix/client-service';
const service = Service.init();

or

const Surix = require('@surix/client-service'); 
const service = Surix.Service.init();
const requests = Surix.requests;

or

<script src="https://cdn.jsdelivr.net/npm/@surix/[email protected]/dist/client-service.min.js"></script>
const service = Surix.Service.init();
const requests = Surix.requests;

Service is the service itself.

Service contains all the methods grouped according to their operations

data contains:

  • createEntity: Creates an entity in the current Surix project (expects entity: any parameter).
  • getEntities: Queries entities from the current Surix project.
  • getEntityById: Gets a single entity by its Surix id.
  • addTagsToEntity: Add tags to an existing entity.
  • removeTagsFromEntity: Removes tags from an entity.
  • getTags: Gets all the entity tags in the project.
  • updateTag: Updates the specified tag in an entity.
  • project: Fetches the current Surix project.
  • getAppData: Fetches app data stored by the app in the current project
  • updateAppData: Updates/adds app data to the current project.
  • createFile: Creates a file in the current Surix project (expects fileParams: any parameter).
  • getFiles: Queries files from the current Surix project.
  • getFileById: Gets a single file by its Surix id.

toast contains:

  • show: Displays a message on Surix toast (expects message: string parameter).

menu contains:

  • populate: Submits the menu items to Surix. The menu is updated immidiately (expects items: any parameter).

events contains:

Menu Methods

Populating Surix menu:

menu payload is an array of objects:

const menuItems = [
    {
        icon: 'speaker_notes', 
        // This is the icon to be displayed on the menu
        // The icon name follows the material icon standard.
        title: "MPESA Transactions", 
        // This is the text displayed on the menu
        // and also on the title bar when this item is clicked.
        action: 'mpesa', 
        // This is a tag, the value is abitrary. The developer 
        // could use this to check which menu list item was clicked
        default: true 
        // This will be selected by default when the menu populates
    },
    {
        icon: 'settings',
        title: "Settings",
        action: 'settings'
    }
]

Populating the menu:

service.menu.populate(menuItems).then(res => {
    // The menu was updated automatically
}).catch(err => {
    // Handle the error
});

Toast Methods

Show a Toast Message:

const toast = {
    message: 'Welcome to Surix',
    type: 'info' // could also be 'success', 'error'
};
service.toast.show(toast).then(res => {
    // Toast was displayed successfully 
}).catch(err => {
    // Handle error
});

Data Methods

Fetch Entities:

// Fetch entities
const query = {
    query: {
        age: { $gt: 20 }
    },
    tags: ['people']
};
service.data.getEntities(query).then((entities) => {
    // Do something with the response
}).catch(err => {
    // Handle error
});

Fetch and entity by its Surix ID

const id = '1I7OBNmpPRYMS3s6WmoxeA';
service.data.getEntityById(id).then((entity) => {
    // Do something with the entity
}).catch(err => {
    // Handle error
});

Create Entity:

// Create an Entity
const entity = {
    data: {
        value: 18,
        type: 'number',
        label: 'Age'
    }
};

service.data.createEntity(entity).then((createdEntity) => {
    // Do something with the newly created entity
}).catch(err => {
    // Handle the error
});

Add tags to an entity

const args = {
    tags: ['people', 'friends'],
    entityId: '1I7OBNmpPRYMS3s6WmoxeA'
};

service.data.addTagsToEntity(args).then((updatedEntity) => {
    // Do something with the updated entity
}).catch(err => {
    // Handle the error
});

Note: And entity cannot have duplicate tags. If a tag is already in the entity, it will be ignored.

Remove tags from an entity

const args = {
    tags: ['people', 'friends'],
    entityId: '1I7OBNmpPRYMS3s6WmoxeA'
};

service.data.removeTagsFromEntity(args).then((updatedEntity) => {
    // Do something with the updated entity
}).catch(err => {
    // Handle the error
});

Note: Tags that are not in the entity will be ignored.

Updating a tag

const args = {
    tags: 'people',
    update: {
        name: 'persons'
    }
};

surix.data.updateTag(args).then(updatedTag => {
    //Tag updated successfully
}).catch(error) => {
    //Error
});

Get all tags

service.data.getTags().then((tags) => {
    // Do something with the tags
}).catch((err) => {
    // handle error
});

The response of the request is an array of tag objects:

[
    { name: 'contacts' },
    { name: 'products' },
    { name: 'messages' }
]

Fetch Project:

service.data.project().then(project => {
    // Do something with the fetched project
}).catch(err => {
    // Handle error
});

Get App Data:

service.data.getAppData().then(data => {
    // do something with the data
}).catch(err => {
    //handler error
});

Update App Data:

const update = {
    data: {
        theme: {
            type: 'text',
            value: 'blue'
        },
        active: {
            type: 'boolean',
            value: true
        }
    }
};
service.data.updateAppData(update).then(updatedData => {
    // do something with updated data
}).catch(err => {
    // handler error
});

Upload a file:

const file = document.getElementById('file'); // Assuming the element is an input of type file

const fileParmas = {
    name: 'My picture',      // File title
    mimeType: file.type,     // Image mime type (this type is checked against the type of the file itself)
    public: true             // Is the file publicly accessible?
    file,                    // The file itself (has to be of type File)
}

service.data.createFile(fileParams).then(fileDetails => {
    // Do something with the file details
}).catch(err => {
    // Handle error
})

Fetch a file by ID

const fileId = '123';

service.data.getFileById(fileId).then(fileDetails => {
    // Do something with the fileDetails
    // NOTE: fileDetails has  field downloadUrl that contains a url 
    // to the actual file
}).catch(err => {
    // Handle error
});

Fetch all files

service.data.getFiles().then(files => {
    // DO something with the files, file is an array of fileDetails
}).catch(err => {
    // Handle error
})

Events Methods

There are times where Surix sends information to the app without the app requesting.

Menu Item Clicked:

When one clicks on the menu populated by the app, Surix tells the app about the click using a menuItemClicked event.

Listening to the menu click event:

let handler = (event) => {
    const msg = event.detail;
    // msg.body contains the action value in your menu item
    switch(msg.body) {
        case 'settings':
            // The settings menu item was clicked
        break;
        case 'mpesa':
            // The mpesa menu item was clicked
    }

service.events.menuItemClicked(handler);

About

This library allows Surix apps to interact with the Surix web client.

Topics

Resources

Stars

Watchers

Forks

Packages

No packages published