3.0: redesign the "pieces widgets" feature

[boutell]

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

[thefrana]

If you provide good examples how to achieve current behaviour (eg. individual pick), I would go for proposed changes. I like to keep things simple.

[falkodev]

Yes, it makes sense to have something simple, yet extendable, and not to force the developer's choice. The disadvantages are not insurmountable, especially if we have examples as recalled by @lukeeno.

I only wonder about the name piece-feed-widget-type. Is it important to reinforce the fact it is a feed through the name as well? I would prefer piece-widget-type as it is simpler to remember and self-explanatory.

[boutell]

That is a good question about the name.

In a meeting it was suggested that "feed" is a good word to use because other CMSes use that word for a similar feature.

But, I am looking at Wordpress tutorials and I don't see this language used.

Here is a simple example of a custom widget for hand-picking several blog posts:

// in lib/modules/article-widget/index.js
module.exports = {
  label: 'Handpicked Articles',
  fields: {
    add: {
      _articles: {
        type: 'join',
        withType: 'article'
      }
    }
  }
}

In the widget.html you then have access to data.widget._articles.

The main advantages are:

• It is a great, easy example of how to use joins, which we can teach at the appropriate moment in the docs.
• It keeps the UX of the feed widget simple, there's no need for a toggle between "feed" and "handpicked" etc.

The main disadvantages are:

• A little more developer work when you want the handpicked option.
• Picture a singleton blog widget at the bottom of the home page, showing recent posts. One day you decide it should show handpicked posts. Now you have to change the template to use a different widget type.

Hmm. That seems like a real situation.

Honestly I feel torn at this point 😆 Although it is a little more complex to implement, there is value for the user in being able to make that change, maybe.

We do have sites with widgets like this on them today. Perhaps we should gather some UX data on how the widgets are being used, by analyzing the db.

[boutell]

After looking at some data I can say that our clients just about always use the "choose by hand" option, not "by tag" or "all".

[falkodev]

Always used the "individually" option too. But I feel the "5 most recent articles" use case is real. What do you suggest? Having the hand-picked behavior by default, and adding a code option to enable the "all" feature if needed?

[boutell]

Let’s take the case where feeds are a separate widget that does not support handpicking.

Then let’s say the developer did this:

// modules/article-feed-widget/index.js
module.exports = {
  extend: '@apostrophecms/piece-feed-widget',
  filters: {
    add: {
      _category: {
        label: 'Category'
      }
    }
  }
};

Then the widget editor would be like this:

+--------------------------------------------+
|   Article Feed                      <Save> |
|                                            |
|   Category: [ None (Show all) ]            |
|               Cats                         |
|               Dogs                         |
|                                            |
+--------------------------------------------+

If no filters are configured, the widget editor has no function and the widget should probably mark itself contextual so the feed just zaps into place without an empty modal.

We would allow them to pick any category, even one with zero articles so far, because you might very well set up the feed before creating the content. But, we can show counts so it's clear there won't be content yet.

[boutell]

If we decide to "keep the band together" by supporting both handpicking and feeds in a single widget, then it looks like this:

// modules/article-widget/index.js
module.exports = {
  extend: '@apostrophecms/piece-widget',
  filters: {
    add: {
      _category: {
        label: 'Category'
      }
    }
  }
};

Then the widget editor would be like this, depending on the radio button choice:

+--------------------------------------------+
|   Display Articles                  <Save> |
|                                            |
|   [ * ] Choose Automatically               |
|   [   ] Choose Individually                |
|                                            |
|   Category: [ None (Show all) ]            |
|               Cats                         |
|               Dogs                         |
|                                            |
+--------------------------------------------+

+--------------------------------------------+
|   Display Articles                  <Save> |
|                                            |
|   [   ] Choose Automatically               |
|   [ * ] Choose Individually                |
|                                            |
|   Search: _______________     <Browse...>  |
|           X Why Cats Are Cool              |
|           X Why Dogs Drool                 |
|                                            |
+--------------------------------------------+

Here the widget always has a modal since you have to choose whether to "choose automatically" or "choose individually."

Because the filters option provides so much flexibility, it is unlikely that a developer will need to hack in a third choice for their project.

[falkodev]

Ok to "keep the band together". But "Choose Automatically" is more "Choose Randomly" based on a category if the user chooses the "Cats" category for example. I guess the "automatic" choice scares the editor as the decision to display a piece is not theirs. Maybe that's why everybody chooses the "hand picking" option.

[boutell]

OK, but I'm not sure "Randomly" would be less scary 😆

It's also not really random. It's "most recently updated," with optional filtering. That is the default sort order of pieces, unless you change it.

So may be that should look like:

+--------------------------------------------+
|   Display Articles                  <Save> |
|                                            |
|   [ * ] Recent Articles                    |
|   [   ] Choose Individually                |
|                                            |
|   Category: [ None (Show all) ]            |
|               Cats                         |
|               Dogs                         |
|                                            |
+--------------------------------------------+

There could be an option to change the wording of "Recent Articles" to something else if your piece type has an unusual sort order, like "Upcoming Events" for instance.

It's also not out of the question to add a "sort" option that the user can control, now or in the future.

[falkodev]

"Randomly" is not less scary. I think it is what people have in mind when they see "Automatically". I like "Recent articles".

[notebk]

I personally use both individually and recent (depending on the page and if there's relevant content). Custom filtering is attractive though, so if I'd have to choose between features, I'd rather have custom filtering and deal with the individual widget myself

[myovchev]

I am too new to Apostrophe (4 weeks prototyping with apos) and my work so far doesn't involve any widgets development/usage (I'm working extensively with pieces, show/indexPage,custom pieces routes and custom headless routes). However, I could try to predict my feelings about the pieces widgets scenario that you describe.

From what I see the general question is 'individually' vs 'no-individually' option by default. From user (editor) perspective, individual pieces and feed is completely separate scenarios, something like 'editor choice' vs 'featured' sections. Experienced editors would always go with a generic control (tags), individually picking entities is extremely situational. From developer perspective - in case it's easy enough for me to produce a "pick items widget" I'd like to keep feeds and individual widget types separate and I don't mind to do the latter myself.

The summary - your decision to remove the 'individual' option from core pieces widget sounds extremely reasonable to me.

The only confusing thing I see in your description above is The "individually" option is also very easy to build yourself in advantages vs If the "individually" case is not so easy to build yourself, developers will find Apostrophe a little harder to set up in disadvantages - which one it is in the end :)

[boutell]

Thanks for your input Miro!

Yes, it is a little confusing the way I worded that.

More accurate would be "although the 'individually' option is easy to build it is not zero effort like before".

On Sat, Sep 5, 2020 at 10:03 AM Miro Yovchev notifications@github.com wrote:

I am too new to Apostrophe (4 weeks prototyping with apos) and my work so far doesn't involve any widgets development/usage (I'm working extensively with pieces, show/indexPage,custom pieces routes and custom headless routes). However, I could try to predict my feelings about the pieces widgets scenario that you describe.

From what I see the general question is 'individually' vs 'no-individually' option by default. From user (editor) perspective, individual pieces and feed is completely separate scenarios, something like 'editor choice' vs 'featured' sections. Experienced editors would always go with a generic control (tags), individually picking entities is extremely situational. From developer perspective - in case it's easy enough for me to produce a "pick items widget" I'd like to keep feeds and individual widget types separate and I don't mind to do the latter myself.

The summary - your decision to remove the 'individual' option from core pieces widget sounds extremely reasonable to me.

The only confusing thing I see in your description above is The "individually" option is also very easy to build yourself in advantages vs If the "individually" case is not so easy to build yourself, developers will find Apostrophe a little harder to set up in disadvantages - which one it is in the end :)

— You are receiving this because you authored the thread. Reply to this email directly, view it on GitHub https://github.com/apostrophecms/apostrophe/issues/2366#issuecomment-687615796, or unsubscribe https://github.com/notifications/unsubscribe-auth/AAAH27O6LTX3FD2QXUDO5LLSEJAMRANCNFSM4QVAHZSQ .

--

THOMAS BOUTELL | CHIEF TECHNOLOGY OFFICER APOSTROPHECMS | apostrophecms.com | he/him/his

[boutell]

Our own clients, including experienced users, tend to use "choose individually" almost exclusively according to the data I've gathered so far.

[myovchev]

@boutell Like mixing both feed/individual? My point was 'individual' sounds like a different feature to me compared to 'feed'. In my head pieces are very dynamic content and almost never with "personality" (just bunch of items) unlike pages. But I can agree it is a context specific. Additionally I lack real world experience and my logic could differ from the reality of large content apps driven by your customers :)

About the zero effort, I went into apos very fast just looking at the docs and the demo app. I guess zero effort vs a minute effort via demo snippet in the docs is perfectly fine :) However, again it is a subjective opinion from an apos newbie.

[pietro-rutzen]

In my experience in my projects so far, pieces-widgets are mostly used "individually" and only in edge cases as "all" (in my use cases the out-of-the-box default behaviour is often a step further from having the individual picker set up). For me the less developer involvement with content editing the better.

Apos does a great job at that in most times and I belive wrapping up towards "choosing automatically" and "choosing individually" is really a good choice.

Also, I think the current naming convention on pieces-widgets really helps new developers worldwide as opposed to piece-feed that feels a little more confusing at first sight. Taking myself as an example (and I believe many people are like that too), english is not my primary language, code is. So the more intuitive the understanding of what is going on, the better.

[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" ?

[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!

[stale[bot]]

This issue has been automatically marked as stale because it has not had recent activity. It will be closed if no further activity occurs. Thank you for your contributions.

[abea]

Ultimately piece widgets were left of of Apostrophe 3 since they can be fairly easily reproduced with a single relationship field. The tag filtering feature was not a factor since tags are not a core feature in Apostrophe 3.