overview
components
As a matter of course, the $setup and $run methods are the only requirements you need to implement an app, however, there is certain other functionality provided by the davinci platform that will not be available to the app without further protocols. In particular, apps on the platform can share data with each through the data bus, apps can be saved, and components can be copied and pasted into a blog. The functionality required to accomplish these goals is provided by the davinci components spec .
integrating components in an app
After you have a component designed and coded, you can use the components in a either a blog or a workspace. Components are available to a blog through a toolbox. Toolboxes are also available in an app, however, apps can provide additional functionality.
When a user uses a toolbox, the component is typically added to the blog or workspace through calling the $page.add method. This method will either append the component to a blog, or will insert it into the currently selected component, if there is one.
In the context of an app, there may a selected component that the user wants to insert the component into, for instance, if the user is viewing a channel and wants to insert a component into a message.
Sometimes, however, an app may wish to display a component within the app. The simple way to accomplish this is to set the target property on the components config, prior to adding the config.
config.target= "div-id";
$page.add(config);
The target property specifies the id of a div in which to render the component. In this case, the app needs to have a div with the given id, and the $page will render the component.
pasting components in an app
When a user copies a component and pastes it, the platform will call the $page.add method.
$page.add(config);
As noted above, typically this will append the component to the users current blog. In the context of the workspace, there may different scenarios you need to deal with.
If the user has a component that is currently selected, the component will be pasted into that component, if it is a container component.
One way to deal with this situation is for the app to register a listener to the $page.add call. You can do this by calling $page.on method. The following is a sample handler that is registered with the $page.add method.
$page.on('add', function (params) {
if (!Array.isArray(params)) params = [params];
let recurse = function (children) {
if (children == undefined) return;
for (let child of children) {
if (child.script == '/ctrls/component.js') add(child);
recurse(child.children);
}
}
recurse(params);
});
In this example, the app registers a listener for the $page.add event. When it is called, it receives the parameters that were passed to the $page.add method. Then it recurses through all configs in the params and checks for any config objects with a given script URL. (in this case, it is looking for components that are instantiated using the '/ctrls/component.js' library)
For any component that the app wishes to handle, it calls the add method. A sample is given below.
function add(config) {
if ($page.selection().length > 0 && 'children' in $page.selection()[0]) return;
if (('app' in config) && (config.app != '/lib/apps/stockcharts/v1.0.0/stockcharts.js'))
return;
if ($page.target() != undefined) return;
$('#' + guid + '-icon').addClass('_populated-icon');
config.app = '/lib/apps/stockcharts/v1.0.0/stockcharts.js';
config.target = 'div-id'
//do something
}
The add method checks a few conditions before doing anything. If there is a selected container component, indicated by $page.selection.length > 0 and 'children' in the selection, then the app does nothing. If $page.target is set to some component, the app does nothing. Otherwise, the app will handle component. It does this by setting the target on the config to the id of a div that the app is displaying.
Note that the app also adds the 'app' property on the config. This indicates that the app is handling the component. If the user saves their workspace, and the reloads it, the 'app' property indicates that the config is being handled and rendered by the indicated app.