Making Packs that leverage the new subitems feature

Yesterday a Pack developer wrote in with the following question:

I am interested to learn, now that Subitems has been released, how can I leverage this in my packs? Is there any documentation available for Pack developers on how we can use subitems?

What a great question! Subitems are amazing, but like make Coda features whether or not to use them is up the Doc maker, not the Pack maker. But there are a few things you can do as a Pack maker to leverage this new capability.


:one: Add a parent column

If the rows of your sync table have a parent-child relationship, include a parent column in your table using a reference schema. A reference schema is how a Pack can add a Relation column to the sync table, pointing to a row or rows in a different table, or the same table.

Creating a schema that references itself is a sort of chicken-and-egg problem, but there is some sample code that shows you how to work around it. While that approach involves creating the reference schema manually, an alternate approach it to tack on the property containing the reference schema after the base schema has been defined.

// Define base schema.
const PokemonSchema: coda.GenericObjectSchema = coda.makeObjectSchema({
  properties: {
    id: { type: coda.ValueType.String, required: true, },
    name: { type: coda.ValueType.String, required: true, },
    number: { type: coda.ValueType.Number },
    image: { 
      type: coda.ValueType.String, 
      codaType: coda.ValueHintType.ImageReference,
    },
  },
  displayProperty: "name",
  idProperty: "id",
  featuredProperties: ["number", "image"],
});

// Add on the evolvesFrom property containing the self-referencing schema.
PokemonSchema.properties.evolvesFrom = 
  coda.makeReferenceSchemaFromObjectSchema(PokemonSchema, "Pokemon");
PokemonSchema.featuredProperties.push("evolvesFrom");

Once the parent column is in your sync table, users can use it when setting up subitems.


:two: Add a drag-and-drop template

While your sync table itself can’t specify that subitems should be used, you can bundle a template with your Pack that makes it easy for a users to get there. To bundle a template with a Pack:

  1. Create a doc to act as the template.
    Note: this should be a regular doc, not a “Template”, confusingly.
  2. Install the Pack, add the sync table to the doc, and set it up using subitems.
  3. Publish the doc. You can turn off discoverability, since it probably don’t make sense to feature it in the Gallery.
  4. Edit your Pack’s listing page add add the published doc’s URL in the “Featured docs” section.

The end result is that this template will show up in the Pack’s side panel, and users can drag and drop it into their doc.


If you have any questions, or ideas on how to use subitems with Packs, let us know!

12 Likes

@Eric_Koleda,
we have been using this technique to ‘deploy’ packs to our clients.

BUT THERE IS A PROBLEM !

its not reliable!
every now and then the ‘featured document’ template is NOT shown
when the user adds the pack to their document.

this totally farts-up the entire process
since we DEPEND upon that document to provide the framework for the pack

its intermittent; the worst kind of bug to fix
but its IMPORTANT imho

Max

Oh, that’s no good. I haven’t seen that happen before, but if it’s intermittent then that would make sense. Good caveat I guess!