Extend the App Graph

By the end of this page each space has a Stashed links section under Content in the navigation tree, and every link has Mark as read on its toolbar and in its menu in the tree.

Background

A PLEX app draws its navigation tree, toolbars and menus from one graph, App Graph. In Composer that is the tree on the left, the object toolbar and the context menus. Its nodes are the things a person can open, and its action nodes are what they can do to them. Plugins add to the graph with builder extensions: functions that match a node and return its children or its actions. The app runs them only for the nodes a person expands. App Graph explains the model.

Steps

1. Start the module’s file. The extensions on this page go in capabilities/app-graph-builder.ts, with these imports.

   src/capabilities/app-graph-builder.ts

   import * as Effect from 'effect/Effect';
   
   import * as Capability from '@dxos/app-framework/Capability';
   import * as AppGraphBuilder from '@dxos/app-graph/AppGraphBuilder';
   import * as AppCapabilities from '@dxos/app-toolkit/AppCapabilities';
   import * as AppNodeMatcher from '@dxos/app-toolkit/AppNodeMatcher';
   import * as GraphPath from '@dxos/app-toolkit/GraphPath';
   import * as TypeSection from '@dxos/app-toolkit/TypeSection';
   import * as Operation from '@dxos/compute/Operation';
   import { Obj, Ref } from '@dxos/echo';
   
   import { StashNamespace } from '../namespace.ts';
   import { StashedLink } from '../types/StashedLink.ts';
   import { MarkRead } from '../types/StashedLinkOperation.ts';
   
   

2. Add a section for the type. The navigation tree groups each space’s sections under headings such as Content and System. TypeSection.createTypeSectionExtension builds the usual section for an object type: it matches the group you pass, lists the space’s links under a Stashed links heading named and coloured from the type’s annotations, and hides the heading when the space has none. urlKey gives each link an address in the app’s URL, which is how Composer opens one when a person clicks it.

   src/capabilities/app-graph-builder.ts

   /** A "Stashed links" section in each space's Content group, once it has one. */
   const section = TypeSection.createTypeSectionExtension(StashedLink, {
     match: AppNodeMatcher.whenNavTreeGroup(GraphPath.GroupTypes.content),
     groupSegment: GraphPath.GroupSegments.content,
     // The link's address in Composer's URL: `/w/<space>/stash/<id>`.
     urlKey: 'stash',
   });
   
   

3. Attach the operation as an action. createTypeExtension matches every node whose object is a link, and this extension returns an action instead of children. Its disposition says where it shows: toolbar puts it on the link’s toolbar, and list-item in the link’s menu in the navigation tree. The command palette lists it either way. Its data invokes Mark as read from Add an operation with a reference to the link, in the link’s space.

   src/capabilities/app-graph-builder.ts

   /** An action on every link, on its toolbar and its menu in the tree. */
   const stashedLinkActions = AppGraphBuilder.createTypeExtension({
     id: 'stashedLinkActions',
     type: StashedLink,
     actions: (link) =>
       Effect.succeed([
         {
           id: 'markRead',
           data: () =>
             Operation.invoke(
               MarkRead,
               { link: Ref.make(link) },
               { spaceId: Obj.getDatabase(link)?.spaceId },
             ),
           properties: {
             label: ['mark-read.label', { ns: StashNamespace.key }],
             icon: 'ph--check-circle--regular',
             disposition: ['toolbar', 'list-item'],
           },
         },
       ]),
   });
   
   

4. Contribute the extensions. The module builds both and contributes them together as the App Graph builder capability.

   src/capabilities/app-graph-builder.ts

   export default Capability.makeModule(
     Effect.fnUntraced(function* () {
       const extensions = yield* Effect.all([section, stashedLinkActions]);
       return Capability.contribute(
         AppCapabilities.AppGraphBuilder,
         extensions.flat(),
       );
     }),
   );
   
   

5. Add the module to the manifest. The App Graph maker activates the module when the app is idle after startup.

   dx.config.ts

   import * as AppCapability from '@dxos/app-toolkit/AppCapability';
   import * as AppSurface from '@dxos/app-toolkit/AppSurface';
   import * as SpaceCapability from '@dxos/plugin-space/SpaceCapability';
   
   import { StashNamespace } from './src/namespace.ts';
   
   const config: Plugin.PluginConfig = Plugin.config({
     plugin: {
       key: StashNamespace.key,
       name: 'Stash',
       author: 'Example',
       description:
         'A reading list: save links with a note, and mark them as read.',
       icon: { key: 'ph--tray-arrow-down--regular', hue: 'indigo' },
       tags: ['labs'],
     },
     modules: [
       AppCapability.translations(
         () => import('./src/translations.ts', { with: { type: 'module-url' } }),
       ),
       AppCapability.schema(
         () =>
           import('./src/capabilities/schema.ts', {
             with: { type: 'module-url' },
           }),
       ),
       AppCapability.operationHandler(
         () =>
           import('./src/capabilities/operation-handler.ts', {
             with: { type: 'module-url' },
           }),
       ),
       SpaceCapability.createObject(
         () =>
           import('./src/capabilities/create-object.ts', {
             with: { type: 'module-url' },
           }),
       ),
       AppCapability.appGraphBuilder(
         () =>
           import('./src/capabilities/app-graph-builder.ts', {
             with: { type: 'module-url' },
           }),
       ),
   
   

6. See the result. Load or reload your plugin below, create a sample link with New, and select App Graph. The inspector shows the branches of the graph, as Composer builds it, that lead to what your plugin added, and marks those nodes.

   A Stashed links section appears in the space’s Content group, with the link under it, and Mark as read is the link’s action.

What you can do now

• Add a section for a type to a group in the navigation tree, with an address for each object.
• Attach an operation to a type’s nodes as an action.

Next, Add a surface gives a link a view to open.