@evoke-platform/context

Evoke Context

Utilities that provide Evoke widgets context about the runtime environment.

Installation

Note: This package is included as part of the Evoke SDK. It is recommended to install the SDK instead.

npm install @evoke-platform/context

If your project was scaffolded using the plugin generator, then @evoke-platform/context is already available and no further installation is necessary.

Documentation

• Working With Objects
• REST API Calls
• Authentication Context
• Notifications

Working With Objects

Use ObjectStore to work with objects and instances of objects. Obtain an object store with the useObject hook:

const applications = useObject('application');

• useObject
• Class: ObjectStore
  • get
  • findInstances
  • getInstance
  • getInstanceHistory
  • newInstance
  • instanceAction
  • invalidateCache
  • invalidateAllCache

useObject(objectId)

Hook for use in a functional component. Returns an instance of ObjectStore for the specified object.

• objectId [string]
  • The id of the object you want to work with.
• Returns ObjectStore instance for the given object. Note there are no guarantees about whether the given object actually exists. If the specified object does not exist, failures will not occur until you try to use the object store.

Class: ObjectStore

This class enables you to perform operations on an object and its instances. Both promises and callbacks are supported. If a typical JavaScript callback function is provided as the last argument, the callback will be used to return the results. Otherwise, a promise is returned. For example:

function callback(err, result) {
    if (err) {
        // error occurred
    } else {
        // process result
    }
}

applications.findInstances(callback);
           -- or --
const results = await applications.findInstances();

ObjectStore includes built-in caching for object definitions with a 30-second time-to-live (TTL). This improves performance by reducing API calls for frequently accessed objects.

get(options)

Get the object definition for this store's object. The returned object includes inherited properties and actions if this object is derived from another object. Results are cached for improved performance.

• options [object] - optional
  • sanitized [boolean]
    • If true, returns a sanitized version of the object reflecting only the properties and actions available to the current user.
  • bypassCache [boolean]
    • If true, bypasses the cache and forces a new API call. The cache is still updated with the results of the new API call.
  • skipAlphabetize [boolean]
    • If true, preserves the original order of properties instead of alphabetizing them (properties are alphabetized by default).

findInstances(filter)

Retrieves instances of the object that match the filter.

• filter [object] - optional
  • fields [array(string)] - optional
    • Object fields to be returned in the results. If not provided, all fields will be returned.
  • where [object] - optional
  • order [array(string)] - optional
  • skip [number] - optional
    • If provided, skip the specified number of instances before returning results. Typically used together with order and limit.
  • limit [number] - optional
    • If provided, limits the number of results to the specified count.
• Returns an array of matching instances.

getInstance(instanceId)

Retrieves a specific instance of the object.

• instanceId [string]
  • ID of the instance to be retrieved.

getInstanceHistory(instanceId)

Retrieves the history of an instance of the object.

• instanceId [string]
  • ID of the instance.
• Returns an array of history records.

newInstance(input)

Creates a new instance of the object.

• input [object]
  • Create action to be executed. The action must have type = 'create'.
• Returns newly created instance.

instanceAction(input)

Performs an action on an existing instance.

• input [object]
  • Action to be executed. The action must not be a create action.
• Returns updated instance.

invalidateCache()

Invalidates cached data for this specific object ID and all its option variants. Use this when you know the object definition has changed on the server.

invalidateAllCache() (static)

Static method that invalidates the entire object cache across all ObjectStore instances. Use this when you need to force fresh data for all objects.

Page Context

• usePageParam
• usePageParams
• useNavigate
• useApp

usePageParam(param)

Return the specified parameter value from the page route.

• param [string]
  • Parameter in the page route. For example, if the current page is /applications/12345 matching the page route /applications/:instanceId, then passing 'instanceId' will return '12345'.
• Returns the matched parameter's value from the current page's route, or undefined if the page does not have a matching parameter.

usePageParams()

Returns an object with all of the current page's matched parameters, where the keys are the parameter names and the values are the corresponding parameter values.

useNavigate()

Returns a function that can be used to navigate to another page. The returned function has the following signature:

function (page, params)

• page [string]
  • Page to navigate to. This can either be the exact route or a route template that includes parameter placeholders (e.g. a page id). With the latter, use the params argument to specify the path parameters.
• params [object] - optional
  • Key/value object mapping parameter names with their corresponding value. If page contains parameter placeholders, they will be replaced with corresponding values provided in params.

useApp()

Returns the currently loaded Evoke App as well as the following function.

• findDefaultPageSlugFor: An asynchronous function that takes an objectId as a parameter and returns the default page slug for that object, if no default page slug is found and the object is a subtype, the page slug of the first ancestor with a default page will be used. It returns undefined if no default page slug is found for any ancestor type.

Example usage:

const { id: appId, findDefaultPageSlugFor } = useApp();
const defaultPageSlug = await findDefaultPageSlugFor(objectId);

REST API calls

• useApiServices
• Class: ApiServices
  • get
  • post
  • patch
  • put
  • delete

useApiServices()

Hook used to obtain an instance of ApiServices.

Class: ApiServices

This class enables you to call the Evoke REST API. If the user is logged in to the Evoke platform, this class takes care of adding the appropriate authentication token to the API call.

Note: For accessing objects and instances, you can use ObjectStore instead.

This class is meant for use with the Evoke REST API, so any relative URLs provided are relative to the Evoke environment's APIs, e.g. https://[environment-host]/api. You can, however, call external APIs by providing an absolute URL.

get(url, options)

post(url, data, options)

patch(url, data, options)

put(url, data, options)

delete(url, options)

Authentication Context

• useAuthenticationContext

useAuthenticationContext()

Hook to obtain the authentication context based on the current logged-in user.

The authentication context includes the following property and functions.

• account [object]
  • The account of the currently logged-in user. This includes both the user's id and name.
• logout()
  • A function that logs out the currently logged-in user. The user will be redirected to Evoke's logout page upon logout.
• getAccessToken()
  • A function that returns an access token that is associated to the currently logged-in user. This token can be used to make API calls to Evoke's APIs to authenticate the API call.
  • Note: As a general recommendation, the ApiService class should be used to make API calls as it will take care of appending an access token to the call.

Notifications

• useNofitication
  • documentChanges
  • instanceChanges
• useSignalRConnection (Deprecated)
  • documentChanges (Deprecated)
  • instanceChanges (Deprecated)

useNofitication()

Hook used to obtain an instanceChanges instance and a documentChanges instance.

documentChanges.subscribe(objectId, instanceId, (data: DocumentChange[]]) => {})

Subscribe to the specified object instance changes.

const { documentChanges } = useNotification();

documentChanges.subscribe('myObjectId', 'myInstanceId', (data) => {
    console.log(data);
});

The data provided to the callback will be an array of DocumentChange which contains the following data:

• objectId
  • Object describing the instance associated with the updated document.
• instanceId
  • Instance that the updated document is associated with.
• documentId
  • Document that was updated.
• type
  • The type of update. Possible values are BlobCreated, BlobDeleted, and BlobMetadataUpdated.

documentChanges.unsubscribe(objectId, instanceId, (changes: DocumentChange[]) => {})

Unsubscribe to the specified object instance changes.

Callback function is optional. If callback function is not defined, all subscriptions will be removed. If callback function is defined, you must pass the exact same Function instance as was previously passed to documentChanges.subscribe. Passing a different instance (even if the function body is the same) will not remove the subscription.

const { documentChanges } = useNotification();

const callback = (changes: DocumentChange[]) => {
    console.log(changes);
};

documentChanges.subscribe('myObjectId', 'myInstanceId', callback);

documentChanges.unsubscribe('myObjectId', 'myInstanceId', callback);

instanceChanges.subscribe(objectId, (changes: InstanceChange[]) => {})

Subscribe to the specified object changes.

const { instanceChanges } = useNotification();

instanceChanges.subscribe('myObjectId', (changes) => {
    console.log(changes);
});

The data provided to the callback will be an array of InstanceChange which contains the following data:

• objectId
  • Object describing the instance associated with the updated document.
• instanceId
  • Instance that the updated document is associated with.

instanceChanges.unsubscribe(objectId, (changes: InstanceChange[]) => {})

Unsubscribe to the specified object changes.

Callback function is optional. If callback function is not defined, all subscriptions will be removed. If callback function is defined, you must pass the exact same Function instance as was previously passed to instanceChanges.subscribe. Passing a different instance (even if the function body is the same) will not remove the subscription.

const { instanceChanges } = useNotification();

const callback = (changes: InstanceChange[]) => {
    console.log(changes);
};

instanceChanges.subscribe('myObjectId', callback);

instanceChanges.unsubscribe('myObjectId', callback);

useSignalRConnection()

Deprecated This has been deprecated in favor of useNotification.

Hook used to obtain an instanceChanges instance of SignalRConnection and a documentChanges instance of SignalRConnection.

documentChanges.subscribe('{objectId}/{instanceId}', (data: DocumentChange[]]) => {})

Deprecated This has been deprecated in favor of useNotification.

Subscribe to the specified object instance document changes.

const { documentChanges } = useSignalRConnection();

documentChanges.subscribe('myObjectId/myInstanceId', (data) => {
    console.log(data);
});

The data provided to the callback will be an array of DocumentChange which contains the following data:

• objectId
  • Object describing the instance associated with the updated document.
• instanceId
  • Instance that the updated document is associated with.
• documentId
  • Document that was updated.
• type
  • The type of update. Possible values are BlobCreated, BlobDeleted, and BlobMetadataUpdated.

documentChanges.unsubscribe('{objectId}/{instanceId}', (data: DocumentChange[]) => {})

Deprecated This has been deprecated in favor of useNotification.

Unsubscribe to the specified object instance document changes.

Callback function is optional. If callback function is defined, you must pass the exact same Function instance as was previously passed to documentChanges.subscribe. Passing a different instance (even if the function body is the same) will not remove the subscription.

const { documentChanges } = useSignalRConnection();

const callback = (data: DocumentChange[]) => {
    console.log(data);
};

documentChanges.subscribe('myObjectId/myInstanceId', callback);

documentChanges.unsubscribe('myObjectId/myInstanceId', callback);

instanceChanges.subscribe('{objectId}', (instanceIds: InstanceChange[]) => {})

Deprecated This has been deprecated in favor of useNotification.

Subscribe to the specified object instance changes.

const { instanceChanges } = useSignalRConnection();

instanceChanges.subscribe('myObjectId', (instanceIds) => {
    console.log(instanceIds);
});

The data provided to the callback will be an array of instance IDs that were updated.

instanceChanges.unsubscribe('{objectId}', (instanceIds: InstanceChange[]) => {})

Deprecated This has been deprecated in favor of useNotification.

Unsubscribe to the specified object instance changes.

Callback function is optional. If callback function is defined, you must pass the exact same Function instance as was previously passed to instanceChanges.subscribe. Passing a different instance (even if the function body is the same) will not remove the subscription.

const { instanceChanges } = useSignalRConnection();

const callback = (instanceIds: InstanceChange[]) => {
    console.log(instanceIds);
};

instanceChanges.subscribe('myObjectId', callback);

instanceChanges.unsubscribe('myObjectId', callback);

License

MIT