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:

• menuItemClicked: The event dispatched when a menu item is clicked.

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);