diff --git a/docs/latest/services/index.md b/docs/latest/services/index.md index 15064f3a7..c8b35f6b2 100644 --- a/docs/latest/services/index.md +++ b/docs/latest/services/index.md @@ -1,9 +1,10 @@ -# Services +# Services Overview -- [Overview](#/) -- [Anatomy](#/) -- [UI Services](#/) -- [Parting Words](#/) +- [Overview](#overview) +- [Kinds of Services](#kinds-of-services) + - [Services (default)](#services--default-) + - [UI Services](#ui-services) +- [Related Patterns](#related-patterns) ## Overview @@ -12,76 +13,24 @@ 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][cross-cutting-concerns]. -
- - UI Services Diagram - -
Diagram showing relationship between React Context and UI Service
-
- 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 +## Kinds of Services -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). +Depending on the kind of service, we follow slightly different conventions. For +example, a UI service often receives its implementation from a React Context +Provider. You can read more about the different kinds of services and what makes +them different below: -```js -const _speak = () => { - console.warn('Speak is not implemented'); -}; +### Services (default) -/** - * 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`. - -```js -// 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 +### 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 @@ -89,14 +38,14 @@ these components from an extension. We maintain the following UI Services: -- [UIDialogService](./ui/ui-dialog-service.md) -- [UIModalService](./ui/ui-modal-service.md) -- [UINotificationService](./ui/ui-notification-service.md) +- [UIDialogService](./ui-dialog-service.md) +- [UIModalService](./ui-modal-service.md) +- [UINotificationService](./ui-notification-service.md) You can read more about a specific service by selecting it in the above list, -and more about [UI services in general: here](./ui/index.md) +and more about [UI services in general: here](./ui.md) -## Parting Words +## Related Patterns 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 diff --git a/docs/latest/services/service.md b/docs/latest/services/service.md new file mode 100644 index 000000000..f6dae7d71 --- /dev/null +++ b/docs/latest/services/service.md @@ -0,0 +1,57 @@ +# Services + +
+ + UI Services Diagram + +
Diagram showing relationship between React Context and UI Service
+
+ +## 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). + +```js +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`. + +```js +// 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(); +} +``` diff --git a/docs/latest/services/ui/ui-dialog-service.md b/docs/latest/services/ui-dialog-service.md similarity index 100% rename from docs/latest/services/ui/ui-dialog-service.md rename to docs/latest/services/ui-dialog-service.md diff --git a/docs/latest/services/ui/ui-modal-service.md b/docs/latest/services/ui-modal-service.md similarity index 100% rename from docs/latest/services/ui/ui-modal-service.md rename to docs/latest/services/ui-modal-service.md diff --git a/docs/latest/services/ui/ui-notification-service.md b/docs/latest/services/ui-notification-service.md similarity index 100% rename from docs/latest/services/ui/ui-notification-service.md rename to docs/latest/services/ui-notification-service.md diff --git a/docs/latest/services/ui/index.md b/docs/latest/services/ui.md similarity index 100% rename from docs/latest/services/ui/index.md rename to docs/latest/services/ui.md