Rethink data model + navigation: make it more hierarchical?

[jacobobryant]

There are three main types of documents: sites, lists (newsletters), and posts. Currently Platypub's schema does not model any relationships between these. When a site is rendered, all the documents are passed to the theme code, which is responsible for deciding which posts and lists should be included on the current site. The default theme does this by looking at the :site/tag, :list/tags and :post/tags attributes. e.g. you'd set it to example-site on your site, then you'd add example-site to the list's tags and the posts' tags.

This makes things flexible. You could share a single post between multiple sites, for example. However I'm not really sure if that will ever actually be needed. If we added a :post/site and a :list/site attribute--i.e. make it so every post belongs to a single, specific site, and same for lists--would anything actually be lost?

Regardless, we probably want to restructure the UI so that lists and posts are grouped under a specific site by default. If we decide to continue with the flexible data model, then we can have a way to break out of that UI model.

Maybe we add the :post/site and :list/site attributes and just let it be an optional field. Or allow a special value like :system or :none. Or even just... make a another site for any "orphaned" posts and lists and just don't publish it.

So yeah I think I'm leaning towards making posts and lists be children of sites. If anyone can actually think of any scenarios where you wouldn't want that kind of relationship, please comment.

[jeffp42ker]

The flexibility of having no strict hierarchy is nice, I think. Posts hold the actual content with sites and lists providing means of dissemination. Sites provide stationary references to content while lists involve a more dynamic time element and may bundle posts into a newsletter based on tags.

Sharing a post across sites might be useful when the post involves the joint effort of multiple groups with distinct identities and sites. Perhaps the content can be cross-linked across sites to highlight and reinforce the combined efforts.

I agree :post/site and :list/site attributes are helpful to ensure content is anchored to a site, as long as it doesn't feel like a strict coupling and alternates can be added.

BTW, I'm already feeling the need to support an event model around posts:

• pre-event announcement
• pre-event status changes (rain delay or postponement, new location etc)
• post-event recap as the main content for those interested or unable to attend.
• post-event announcement of follow-up event, if it's a recurring thing. This might mean creating a set of related posts that get displayed and disseminated based on how their time attributes relate to the current time or status.

[jacobobryant]

My original thoughts around having posts be independent from sites and lists may have been influenced by thinking of Platypub sort of as an aggregator for all your personal content across the web. E.g. at some point maybe we integrations that pulls in all your tweets + hacker news comments + etc, so you could render them on your site/in an rss feed or something...

Maybe we should have :post/sites and :list/sites attributes which accept multiple values, for the sake of flexibility--worst-case scenario, no one actually uses multiple values. At least the flexibility will be there if someone does want it. And you can always leave it empty.

I'm thinking for the UI we could have multiple views. Something like:

My Site
├── Posts
└── Newsletters
All Newsletters
All Posts

If you go to My Site -> Posts and hit "new post" from there, then the :post/sites field would be set to "My Site" by default. It'd also show up under All Posts though. There'd be a multi-select input so you can add or remove sites. If you remove all the sites, then the post would only be visible under All Posts.

BTW, I'm already feeling the need to support an event model around posts:

Hm, so events as in physical/zoom events right? Are you thinking of using Platypub as an alternative to meetup.com or eventbrite?

[jeffp42ker]

Hm, so events as in physical/zoom events right? Are you thinking of using Platypub as an alternative to meetup.com or eventbrite?

I'm writing posts promoting awareness of recurring/bespoke physical community events: getting the word out beforehand and doing a write-up afterwards; nothing as involved as meetup or eventbrite.

The goal is to show a chronological list of events with the current/next event highlighted like a much sparser version of https://wfmu.org/#schedule-playing-today (load the page before going to the anchor to see the yellow highlighting) so people can decided to join at the last minute.

Event start time and event schedule status attributes may be all that's needed really. I'm finding it's fine to just prepend the follow-up in the original post,

[jacobobryant]

Ah got it. Perhaps it'd be helpful to support custom schema for posts instead of just for sites? Then you could write a custom theme that says "posts should additionally have a event start time field of type instant and a schedule status field of type enum with possible values ..."

In some cases you can get by with tags. e.g. for the event schedule status you could add a tag of upcoming, finished etc. of course that wouldn't handle non-boolean attributes like event start time, unless you included a really creative tag like start-time:2022-06-21T12:00:00 🙂. In this case sounds like custom schema would be better.

I haven't given this the requisite hammock time yet, but it might be in-scope at some point to allow entirely custom document types, like standalone event documents, instead of just post documents with custom attributes.

[tbrooke]

May be a little off topic but I am more concerned about various types of posts - which may be do able with tags now -- so ie events could be displayed on a calendar page or posts could serve as text for a static page -This is getting into CMS territory - maybe even have an option for a menu/submenu tag for a post -- ie my About post becomes my ABout page from the top level menu - About/Tom generates a sub menu

[jacobobryant]

Hmmm... yeah I'm thinking having the theme define a custom schema for posts would be best. (and maybe rename "posts" to the more general "items"). The theme could then define multiple types of items, e.g. events vs posts. Already we have two types, posts and pages, that are currently mixed together. The Platypub UI could have separate navigation sections for each type of item. Maybe something like this, to extend the example above:

My Site
├── Pages
├── Posts
└── Newsletters
Another Site
├── Events
├── Posts
└── Newsletters
All Events
All Pages
All Posts
All Newsletters

[jeffp42ker]

In modeling Events, does it make sense to adopt ICS VEVENT field names? An "Add Event to Calendar" button might be a nice addition at some point.

{
   :event/uid :uuid
   :event/summary :string
   :event/description :string
   :event/location :string
   :event/dtstamp inst?
   :event/dtstart inst?
   :event/dtend inst?
   :event/status [:enum :scheduled :cancelled :postponed]
}

[jacobobryant]

Yeah, that would probably be reasonable. We might just leave that to the themes rather than putting schema for events in Platypub's schema.clj file. (i.e. if we enable custom schema for posts, like the custom schema we currently support for sites.)

In general I think we'll want to be conservative with the document types we bake into Platypub, probably leave it at Posts and Pages for a while. Then if a lot of themes end up using a certain additional type of document (like Events) we could think about if it makes sense to pull the schema into "core."

Another hammock thought: going the opposite direction, maybe all document types should be "custom" and defined by themes. The default theme could define Posts and Pages, which would then be a de facto standard for other themes. (This is getting into SOLID Project territory.)

[tbrooke]

It makes sense to me to just have a document type with a generic schema and just have one of the attributes be a type so you could label it a post, page, event whatever then leave it up to the Theme to deal with it - I am not sure ho you would deal with the situation where items have different numbers of attributes

[jeffp42ker]

I looked into applying custom-schema.edn to posts by following the site implementation.

The issue is that posts are only associated with themes by matching tags to sites, so post tags need to be supplied for any custom schema to be known. A default site selection for a new post could resolve this, as has been suggested.

A post can potentially be associated with more than one site through tags so custom-schema definitions from more than one theme may get included for a post. We'd need to show which custom-schema fields in a post are relevant for which themes it seems.

[jacobobryant]

Oh yeah, forgot about that. I'm still feeling good about the :post/sites idea I described above, so I think we should go ahead and do that. After that's done we could add custom schema for posts. I'll make a couple issues for these.

A post can potentially be associated with more than one site through tags so custom-schema definitions from more than one theme may get included for a post. We'd need to show which custom-schema fields in a post are relevant for which themes it seems.

Maybe we should make fields visible based on your navigation context? e.g. say you have a post ("Some Post") under "Site A" and "Site B", both with different themes that define different post schema. If your navigation context is "Site A" -> "Posts" -> "Some Post", then we show the schema for Site A's theme but not the schema for Site B's theme, and vice versa. If the context is "All Posts" -> "Some Post", then we should schema for both themes.

[jacobobryant]

Just added five new issues: #39, #40, #41, #42, #43. In particular #43 has some unresolved questions.