Object Browser

The Object Browser is a core app designed to enhance user interaction with Managed Objects. It streamlines the process of locating, creating, deleting, and updating Managed Objects, making it a versatile tool for users and developers. While the Object Browser allows users to initiate these actions, the execution is delegated, through Capabilities, to the specific app responsible for the Managed Object in question.

How to install

1. Install as developer dependency

   npm install -D @webprovisions-registry/alliance-app-object-browser --registry https://registry.webprovisions.io

2. Add app to your Alliance configuration file.

   // alliance.config.ts
   import { defineConfig } from '@telia-ace/alliance-framework/config';
   
   export default defineConfig({
       server: {
           apps: ['@webprovisions-registry/alliance-app-object-browser'],
       },
   });

Capabilities

browse

Used to browse a given managed object type with built in support for pagination.

Example

// app.ts
import { runCapability } from '@telia-ace/alliance-framework';

provideObjects('my-object', async (args) => {
    /**
     * Fetch objects from app backend.
     * Use the passed `skip`, `take` and/or `pageSize` arguments to paginate the result.
     *
     * Args may contain custom properties defined in the `query` property when running the browse capability.
     **/
    const { total, myObjects } = await fetchObjectsFromMyBackend({
        skip: args.skip,
        take: args.take,
        pageSize: args.pageSize,
        customProperty: args.customProperty,
    });

    return {
        /**
         * Total amount of objects available
         **/
        total,
        /**
         * Objects to display
         **/
        items: myObjects.map((object) => {
            return {
                id: object.id,
                name: object.title,
                created: object.createdDate,
                modified: object.modifiedDate,
            };
        }),
    };
});

runCapability('object-browser', 'browse', {
    app: 'my-app',
    type: 'my-object',
    capabilities: {
        create: 'create-my-object',
        delete: 'delete-my-object',
        update: 'update-my-object',
        default: 'update-my-object',
    },
    header: 'My Objects',
    query: {
        customProperty: 'foo',
    },
});

Args

Property	Type	Required	Description
app	string	Yes	Name of the app, that will handle the managed objects.
type	string	Yes	Type of managed object to browse.
header	boolean | string	No (default true)	Header text to use in the object browser. If false it will not render the header, including the create action. If true it defaults to "Object Browser".
capabilities	CapabilitiesObject	No	Object specifying capabilities dedicated to managing the managed object.
columns	ColumnsRecord	No	Optional object of arguments to pass into the managed object query.
query	QueryObject	No	Optional object of arguments to pass into the managed object query.

CapabilitiesObject

INFO

When the Object Browser attempts to run the capabilities specified for update and delete, it will pass the entire object as the arguments.

For instance, if I have the following object: { id: 1, title: 'Some Object', status: 'Ready' }, the update and delete capabilities will receive { id: 1, title: 'Some Object', status: 'Ready' } as arguments.

Property	Type	Required	Arguments	Description
create	string	No		Capability for creating the managed object.
delete	string	No	object	Capability for deleting the managed object.
update	string	No	object	Capability for updating the managed object.
default	string	No	object	Capability ran when left clicking on an object.

QueryObject

INFO

Pass custom query arguments in the query property when running the capability.

Example:

runCapability('object-browser', 'browse', {
    app: 'my-app',
    type: 'my-object',
    query: {
        pageSize: 10,
        someOtherProperty: 'foo',
    },
});

Property	Type	Required	Default	Description
pageSize	number	No	8	Amount of items to display on each page.

ColumnsRecord

Record that defines the table columns. Each column is represented by a key-value pair, where the key is used to fetch the corresponding object value for that column in each row, and the value is used as the column header.

WARNING

When specifying the columns object, the corresponding Managed Object Query has to return an object containing values for the specified keys.

Defaults to { name: 'Name', type: 'Type', created: 'Created', modified: 'Modified' }

Example:

provideObjects('custom-columns-object', async (args) => {
    const { total, myObjects } = await fetchObjectsFromMyBackend(args);
    return {
        total,
        /**
         * Return an object containing the properties specified in the columns argument property when running the capability.
         **/
        items: myObjects.map((object) => {
            return {
                id: object.id,
                objectTitle: object.title,
                status: object.status,
                owner: object.owner,
            };
        }),
    };
});

runCapability('object-browser', 'browse', {
    app: 'my-app',
    type: 'custom-columns-object',
    columns: {
        objectTitle: 'Title',
        status: 'Status',
        owner: 'Owner',
    },
});

In the example above, the runCapability call passes a columns object that defines three columns: objectTitle, status, and owner.

The corresponding values 'Title', 'Status', and 'Owner' will be used as the column headers and the key will be used when reading the value for each object in each column.

Managed Object Query

WARNING

Please ensure that the object provider returns the correct format.
Implement pagination using the skip and take parameters arguments.

Don't return more items than the take argument specifies.

Input

INFO

May contain custom properties defined in the query property when running the browse capability.

Property	Type	Required	Description
skip	number	Yes	Number of objects to skip before starting to retrieve managed objects.
take	number	Yes	Number of objects to retrieve from a set of managed objects.
pageSize	number	No	Configured value for page size.

Output

Property	Type	Required	Description
total	number	Yes	The total count of objects in the data set, ignoring pagination.
items	object[]	Yes	An object array items objects to display. The properties used depend on the columns passed when running the capability.

Result

No returned result.