Define a type

By the end of this page the plugin has a Stashed link type, and the inspector lists its fields.

Background

A plugin’s data is ECHO objects, and a type describes them. The app reads the type’s annotations to name an object, pick its icon, and decide whether a person can create one. Defining types and the Type guide cover types in full; this page uses only what PLEX needs.

Steps

1. Declare the type. Type.makeObject gives the schema a DXN and makes it an ECHO type. The annotations tell the app which field is the object’s label, which icon to show, and that the type is one a person creates (UserType). The fields are optional because a new object starts empty.

   src/types/StashedLink.ts

   import * as Schema from 'effect/Schema';
   
   import { Annotation, DXN, Obj, Type } from '@dxos/echo';
   
   export class StashedLink extends Type.makeObject<StashedLink>(
     DXN.make('com.example.type.stashedLink', '0.1.0'),
   )(
     Schema.Struct({
       title: Schema.optional(Schema.String.annotate({ title: 'Title' })),
       url: Schema.optional(Schema.String.annotate({ title: 'URL' })),
       note: Schema.optional(Schema.String.annotate({ title: 'Note' })),
       read: Schema.optional(Schema.Boolean.annotate({ title: 'Read' })),
     }).pipe(
       Annotation.LabelAnnotation.set(['title']),
       Annotation.IconAnnotation.set({
         icon: 'ph--tray-arrow-down--regular',
         hue: 'indigo',
       }),
       Annotation.UserType.set(),
     ),
   ) {}
   
   

2. Add a factory. make fills in defaults, so every caller creates a link the same way.

   src/types/StashedLink.ts

   import { Annotation, DXN, Obj, Type } from '@dxos/echo';
   
   export class StashedLink extends Type.makeObject<StashedLink>(
     DXN.make('com.example.type.stashedLink', '0.1.0'),
   )(
     Schema.Struct({
       title: Schema.optional(Schema.String.annotate({ title: 'Title' })),
       url: Schema.optional(Schema.String.annotate({ title: 'URL' })),
       note: Schema.optional(Schema.String.annotate({ title: 'Note' })),
       read: Schema.optional(Schema.Boolean.annotate({ title: 'Read' })),
     }).pipe(
       Annotation.LabelAnnotation.set(['title']),
       Annotation.IconAnnotation.set({
         icon: 'ph--tray-arrow-down--regular',
         hue: 'indigo',
       }),
       Annotation.UserType.set(),
     ),
   ) {}
   
   export const make = (
     props: Partial<Obj.MakeProps<typeof StashedLink>> = {},
   ): StashedLink =>
     Obj.make(StashedLink, {
       title: props.title,
       url: props.url,
       note: props.note ?? '',
       read: props.read ?? false,
     });
   
   

3. Register the type with the app. The schema module tells the app the type exists, so it can query, store and name objects of it.

   src/capabilities/schema.ts

   import { StashedLink } from '../types/StashedLink.ts';
   
   export default [StashedLink];
   
   

4. Name the type. The app labels a type with strings from the type’s own namespace, its typename. Add an entry for it to the translations, after the plugin’s own.

   src/translations.ts

   import { Type } from '@dxos/echo';
   import type * as Theme from '@dxos/react-ui/Theme';
   
   import { StashNamespace } from './namespace.ts';
   import { StashedLink } from './types/StashedLink.ts';
   
   export const translations = [
     {
       'en-US': {
         [StashNamespace.key]: {
           'plugin.name': 'Stash',
           'mark-read.label': 'Mark as read',
         },
         [Type.getTypename(StashedLink)]: {
           'typename.label': 'Stashed link',
           'typename.label_zero': 'Stashed links',
           'typename.label_one': 'Stashed link',
           'typename.label_other': 'Stashed links',
           'object-name.placeholder': 'New link',
           'add-object.label': 'Add link',
         },
   
   

5. Add the module to the manifest.

   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' },
           }),
       ),
   
   

6. See the type. Click Load dev plugin below, or Reload if your plugin is loaded already, and select Schema. It lists the Stashed link type with its fields.

   There is no way to create a link yet. Creating one runs an operation, and the next page adds operations.

What you can do now

• Declare a type with the annotations the app reads.
• Register the type so the app can store and name it.
• Name the type in the plugin’s translations.