a2c4161477
* docs: process docs to include UX Stories requirement * docs: include note regarding different environments * Services init * Remove unused canny logos * docs: add ModalService diagram * docs: GIF of notification * docs: add ui-services page * docs: simplify ui services call out in the general services docs * docs: tips and tricks for UI services * docs: moar pages * docs: dialog gif * docs: services in summary/sidebar * docs: gif examples at top of dialog and notification pages * docs: add UIModal gif * docs: details for Dialog Service * docs: include usage information for ui modal service * docs: detailed information about our UI Notification Service * docs: services diagram * docs: remove unused links * docs: services example and image
3.5 KiB
Services
Overview
Services are a beefier version of commands. They provide a set of
operations, often tied to some shared state, and are made available to
extensions via the ServicesManager. Services are particularly well suited to
address cross-cutting concerns.
Each service should be:
- self-contained
- able to fail and/or be removed without breaking the application
- completely interchangeable with another module implementing the same interface
An Example
The simplest service return a new object that has a name property, and
methods/properties that give the service its functionality. The "Factory
Function" that creates the service is provided with the implementation (this is
slightly different for UI Services).
const _speak = () => {
console.warn('Speak is not implemented');
};
/**
* Factory function to create `HelloWorldService`
*
* @param {object} implementation
* @param {function} implementation.speak - Speak's implementation
* @returns HelloWorldService
*/
export default function createHelloWorldService({ speak }) {
return {
name: 'HelloWorldService',
speak: speak || _speak,
};
}
A service, once created, can be registered with the ServicesManager to make it
accessible to extensions. Similarly, the application code can access named
services from the ServicesManager.
// In the application
const speak = () => {
window.alert('HELLO WORLD');
};
const HelloWorldService = createHelloWorldService({ speak });
const servicesManager = new ServicesManager();
servicesManager.registerService(HelloWorldService);
// In an extension
const { HelloWorldService } = servicesManager.services;
if (HelloWorldService) {
HelloWorldService.speak();
}
A work in progress
Today, we only have maintained UI Services. You can read more about them below.
In practice, services are live, but the patterns and guidance for them may shift slightly as we begin to develop real-world features that utilize them.
UI Services
A typical web application will have components and state for common UI like modals, notifications, dialogs, etc. A UI service makes it possible to leverage these components from an extension.
We maintain the following UI Services:
You can read more about a specific service by selecting it in the above list, and more about UI services in general: here
Parting Words
Services are "concern-specific" code modules that can be consumed across layers. We try to minimize the coupling they introduce by authoring services that are able to fail or be removed. Related patterns that may reduce coupling include:
- Pub/Sub
- Commands