@ibm-wch-sdk/api-mock
v6.0.524
Published
Software development kit to simplify the development of Angular based single page applications against Watson Content Hub.
Downloads
33
Keywords
Readme
ibm-wch-sdk-api
Exposes framework independent APIs for ibm-wch-sdk-ng and similar SDK.
Details
Refer to the documentation.
Changes
Class documentation
Refer to the documentation.
API
Changelog
Current
Added
- Initial version
Delivery
Typescript definitions of the WCH Delivery APIs.
Index
External modules
- "index"
- "interfaces/delivery/v1/rendering/context/rendering.context"
- "interfaces/delivery/v1/site/site.context"
@ibm-wch-sdk/api-mock > "index"
External module: "index"
Index
@ibm-wch-sdk/api-mock > "interfaces/delivery/v1/rendering/context/rendering.context"
External module: "interfaces/delivery/v1/rendering/context/rendering.context"
Index
Variables
Variables
<Const>
EMPTY_RENDERING_CONTEXT
● EMPTY_RENDERING_CONTEXT: RenderingContext
= freezeDeep({
id: '00000000-0000-0000-0000-000000000000',
elements: {},
layouts: {},
markups: {},
context: EMPTY_SITE_CONTEXT
})
Defined in interfaces/delivery/v1/rendering/context/rendering.context.ts:5
@ibm-wch-sdk/api-mock > "interfaces/delivery/v1/site/site.context"
External module: "interfaces/delivery/v1/site/site.context"
Index
Variables
Variables
<Const>
EMPTY_SITE
● EMPTY_SITE: Site
= freezeDeep({
pages: [],
id: '00000000-0000-0000-0000-000000000000'
})
Defined in interfaces/delivery/v1/site/site.context.ts:4
<Const>
EMPTY_SITE_CONTEXT
● EMPTY_SITE_CONTEXT: SiteContext
= freezeDeep({
parent: undefined,
sibling: [],
breadcrumb: [],
children: [],
site: EMPTY_SITE
})
Defined in interfaces/delivery/v1/site/site.context.ts:9
Services
- [logging][./logging/]
- [info][./info/]
Interfaces
Delivery
Typescript definitions of the WCH Delivery APIs.
Index
External modules
- "index"
- "interfaces/delivery/v1/rendering/context/rendering.context"
- "interfaces/delivery/v1/site/site.context"
Logging
The logger interfaces allow to plug custom loggers via the LoggerFactory
. In addition they expose a simple logger interface, modelled after the standard console logger.
Delivery
Typescript definitions of the WCH Delivery APIs.
WchSdk
The SDK defines the plain JS WCH SDK APIs .
Properties
Methods
refresh()
: causes the currently displayed data to be refreshed
The SDK is available on the global window object
window.WchSdk
Cross Origin Eventing
The SDK supports WebMessaging to allow communication across frames via the postMessage functionality. Each message sent to the SDK needs to contain a type
and an id
field. The type is used to identify the meaning of the message, the id to allow the caller to correlate potential responses.
Responses to messages sent to the iframe (e.g. messages back from the SDK to the parent frame) can optionally use channelMessaging. If the first element of the transfer object contains a messagePort, this will be used for reply messages or notifications. Else these replies will be sent against the parent window, directly.
Supported Message Types
WchSdk.refresh
: refreshes the data currently displayed by the application. The message has no response.WchSdk.router.navigateByPath
: navigates to the specified path. Responds with aWchSdk.router.navigateByPathResponse
response. Takes:path
: path to navigate to
WchSdk.router.activeRoute.subscribe
: subscribes a listener for changes in the active route (i.e. navigations). The event will be responsed by a response containing a handle that can be used to unsubscribe. Whenever a navigation occurs, the SDK will send aWchSdk.router.activeRoute
message to the caller.WchSdk.router.route.subscribe
: subscribes a listener for changes for a given route. The event will be responsed by a response containing a handle that can be used to unsubscribe. Whenever the route changes, comes into existence or is deleted, the SDK will send aWchSdk.router.route
message to the caller. Takes:route
: a string or string array that describes the route to listen to. If the value is a string, then it must be the escaped path, starting with a slash but not ending with a slash. If it is a string array, each value represents the unescaped path segment, the segments to not contain slashes.
WchSdk.unsubscribe
: unsubscribes from a subscription given the subscription handlehandle
: the subscription handle
Supported Response Types
WchSdk.router.navigateByPathResponse
: sent as a response to aWchSdk.router.navigateByPath
message from the SDK to the caller. Replicates the caller message fields and in addition:success
: true if the navigation completed, else falseerror
: an optional error object
WchSdk.router.activeRoute.subscribeResponse
: sent as a response toWchSdk.router.activeRoute.subscribe
.handle
: handle to the subscription, can be used to unsubscribe
WchSdk.router.route.subscribeResponse
: sent as a response toWchSdk.router.route.subscribe
.handle
: handle to the subscription, can be used to unsubscribe
WchSdk.router.activeRoute
: sent from the SDK to the subscriber for modifications in the navigation.page
: The selected page. Will benull
if this is the last event (e.g. because of an application shutdown)
Examples
Listen for Navigation Events
This example shows how a parent frame can listen for navigation events of an SPA. The example uses channelMessaging to establish a direct communication channel from the SDK to the parent frame. Navigation events will be sent via this channel.
Note that the use of a channel is not required. If no channel is passed in, the navigation events will be sent directly to the parent window via postMessage.
The example doe NOT show how to unsubscribe.
/**
* Message sent to the SDK to subscribe for navigation notifications
*/
var msg = {
type: 'WchSdk.router.activeRoute.subscribe',
id: 'someid'
};
// use a message channel to receive the responses
var channel = new MessageChannel();
/** Perform the subscription, transfer one end of the channel to the SDK.
* Note that the second parameter is the origin of the iframe.
*/
myframe.contentWindow.postMessage(msg, "http://localhost:4200", [channel.port2]);
/**
* Listen for changes in the navigation
* We expect two types of callbacks here, one for each navigation event
* and a response sending the subscription handle, so we can unsubscribe later.
*/
channel.port1.addEventListener('message', msg => {
// check for the message type
const data = msg.data;
if (data.type === 'WchSdk.router.activeRoute') {
// log the active route
console.log('navigation in iframe', data.page.route);
} else
if (data.type === 'WchSdk.router.activeRoute.subscribeResponse') {
console.log('subscription handle', data.handle);
}
});
// start the bi-directional communication
channel.port1.start();
Messaging
Cross Origin Eventing
The SDK supports WebMessaging to allow communication across frames via the postMessage functionality. Each message sent to the SDK needs to contain a type
and an id
field. The type is used to identify the meaning of the message, the id to allow the caller to correlate potential responses.
Responses to messages sent to the iframe (e.g. messages back from the SDK to the parent frame) can optionally use channelMessaging. If the first element of the transfer object contains a messagePort, this will be used for reply messages or notifications. Else these replies will be sent against the parent window, directly.
Supported Message Types
WchSdk.refresh
: refreshes the data currently displayed by the application. The message has no response.WchSdk.router.navigateByPath
: navigates to the specified path. Responds with aWchSdk.router.navigateByPathResponse
response. Takes:path
: path to navigate to
WchSdk.router.activeRoute.subscribe
: subscribes a listener for changes in the active route (i.e. navigations). The event will be responsed by a response containing a handle that can be used to unsubscribe. Whenever a navigation occurs, the SDK will send aWchSdk.router.activeRoute
message to the caller.WchSdk.router.route.subscribe
: subscribes a listener for changes for a given route. The event will be responsed by a response containing a handle that can be used to unsubscribe. Whenever the route changes, comes into existence or is deleted, the SDK will send aWchSdk.router.route
message to the caller. Takes:route
: a string or string array that describes the route to listen to. If the value is a string, then it must be the escaped path, starting with a slash but not ending with a slash. If it is a string array, each value represents the unescaped path segment, the segments to not contain slashes.
WchSdk.unsubscribe
: unsubscribes from a subscription given the subscription handlehandle
: the subscription handle
Supported Response Types
WchSdk.router.navigateByPathResponse
: sent as a response to aWchSdk.router.navigateByPath
message from the SDK to the caller. Replicates the caller message fields and in addition:success
: true if the navigation completed, else falseerror
: an optional error object
WchSdk.router.activeRoute.subscribeResponse
: sent as a response toWchSdk.router.activeRoute.subscribe
.handle
: handle to the subscription, can be used to unsubscribe
WchSdk.router.route.subscribeResponse
: sent as a response toWchSdk.router.route.subscribe
.handle
: handle to the subscription, can be used to unsubscribe
WchSdk.router.activeRoute
: sent from the SDK to the subscriber for modifications in the navigation.page
: The selected page. Will benull
if this is the last event (e.g. because of an application shutdown)
Examples
Listen for Navigation Events
This example shows how a parent frame can listen for navigation events of an SPA. The example uses channelMessaging to establish a direct communication channel from the SDK to the parent frame. Navigation events will be sent via this channel.
Note that the use of a channel is not required. If no channel is passed in, the navigation events will be sent directly to the parent window via postMessage.
The example doe NOT show how to unsubscribe.
/**
* Message sent to the SDK to subscribe for navigation notifications
*/
var msg = {
type: 'WchSdk.router.activeRoute.subscribe',
id: 'someid'
};
// use a message channel to receive the responses
var channel = new MessageChannel();
/** Perform the subscription, transfer one end of the channel to the SDK.
* Note that the second parameter is the origin of the iframe.
*/
myframe.contentWindow.postMessage(msg, "http://localhost:4200", [channel.port2]);
/**
* Listen for changes in the navigation
* We expect two types of callbacks here, one for each navigation event
* and a response sending the subscription handle, so we can unsubscribe later.
*/
channel.port1.addEventListener('message', msg => {
// check for the message type
const data = msg.data;
if (data.type === 'WchSdk.router.activeRoute') {
// log the active route
console.log('navigation in iframe', data.page.route);
} else
if (data.type === 'WchSdk.router.activeRoute.subscribeResponse') {
console.log('subscription handle', data.handle);
}
});
// start the bi-directional communication
channel.port1.start();
WchSdkRouter
The SDK router allows to navigate to WCH pages or components.
Methods
navigateByPath(path: string): PromiseLike<boolean>
: navigates to a WCH component given its path. The path can be read from the site information in the RenderingContext. The return value indicates when this navigation has completed.activeRoute(): Observable<SitePage>
: returns the active route in form of a page referenceactiveRenderingContext(): Observable<RenderingContext>
: returns the active rendering context
WchSdkVersion
Defines version number and build date.
RenderingContext
Refer to the design document or the documentation for more details about the structure.
The basic structure of elements is described in the Authoring content section.