3.0: redesign the "pieces widgets" feature

In Apostrophe 2.x, we have “pieces widgets.” They look like this:

Users can insert pieces of the relevant type on any page in three ways:

• “All:” shows the most recent, or whatever the default sort order is. You can set a limit.
• “Individually:” you can pick them “by hand,” in the chooser interface.
• “By Tag:” you can display the pieces that have a certain tag. Otherwise very similar to “All.”

For 3.x we are discussing whether to keep each feature and what form they should take.

In a team discussion the following idea came forward:

• Individually: this would no longer be a built-in option.
• So the widget would be renamed piece-feed-widget-type, because it always displays a feed.
• By default you would just get a feed of the most recent (the default order).
• But you would be able to configure filters, to bring back things like “filter by tag.” You could list any schema fields of the piece you wanted filters for, and dropdowns would appear.

Example:

// in lib/modules/article-widgets/index.js
module.exports = {
  extend: '@apostrophecms/piece-type',
  fields: {
    add: {
      _tags: {
        type: 'join',
        // another piece type in this project
        withType: 'article-tag'
      }
      // other content fields go here
    }
  }
};

// in lib/modules/article-feed-widgets/index.js
// This assumes you have an `article` piece module too.

module.exports = {
  extend: 'piece-feed-widget-type',
  filters: {
    add: {
      _tags: {
        // Make the admin pick a tag when editing the widget. Or leave this off, allowing all to be displayed
        required: true
      }
    }
  }
};

Here are some advantages:

• The “individually” option is very different in kind from the other two. You’re not likely to switch your widget back and forth from “individually” to “all”.
• The “individually” option is also very easy to build yourself, it is the simplest widget to write: just put a join field in a new widget, and you’re done. That’s good for teaching Apostrophe. Of course we can include examples in demos.
• The “all” and “by tag” options were really very similar.
• You don’t get a “By Tags” choice for projects or piece types where tags aren’t important. 3.x has no messy general-purpose tags, if you want the effect of tags you add custom piece types and join with them (a better taxonomy).
• The developer can decide exactly which schema fields of the piece type are worth having filters for and they get this feature with no extra code. Not just “tags.” In 2.x, it is hard work to add an additional filter to apostrophe-pieces-widgets.

Here are some disadvantages:

• If the “individually” case is not so easy to build yourself, developers will find Apostrophe a little harder to set up.
• If users turn out to like switching between showing the 5 most recent and showing 5 handpicked pieces for the same widget (especially a singleton), then they will have to do more work to add the other kind of widget.

What do you think, everyone? It is important for us to hear from the community. We want to know how you use this feature today (or if you even use it at all) and how your experience will be improved or impacted by the proposed change.

Thanks!

cc @localghost443 @stuartromanek @falkodev @abea

[boutell]

We had some internal discussion and it seems no one else feels too strongly either way about keeping the two features together vs. breaking them apart. But I’ve really come round to the idea that they can be one widget in a good way. You only need one template to render it, and with the improvements to the language used that grew out of this community discussion, it will be easier for users to understand how and why they might use the automatic option.

So, it sounds like we’re leaning toward keeping them together, with UI improvements.

We’ll have a bit more internal discussion tomorrow and make a decision soon. Thanks for all the input!

[stuartromanek]

It sounds like most people commenting (everyone?) find the following statements true:

• ✅ feed and individually picked pieces are both useful capabilities
• ✅ the use of a feed vs individually picked serve different scenarios/functions

I could imagine two scenarios

Bundle both feed and individual post widgets with Apostrophe core

One widget becomes two widgets with clearer titles. Maybe leave some notes in one or both widgets that let a developers know one widget’s template can extend the other in the case of both widgets using the same format. What we lose in flexibility (convert an individually picked widget to a feed widget) we gain in surface-level clarity.

Making your own ‘individual’ piece widget is straight forward, but if we expect everyone to want it, why not ship it?

Leave both capabilities bundled as one widget

Maybe this was fine? Using a different UI to choose feed vs individual might be all the additional clarity editor’s need (even the ASCII drawings illustrate this more clearly than the obscured select element UI). Maybe there is a better default title than “(PIECE NAME) Widget” ?