FEATURE: Extend plugin API to add multiple poster icons (#15311)

app/assets/javascripts/discourse/app/lib/plugin-api.js

@@ -97,7 +97,7 @@ import { downloadCalendar } from "discourse/lib/download-calendar";
 // based on Semantic Versioning 2.0.0. Please up the changelog at
 // docs/CHANGELOG-JAVASCRIPT-PLUGIN-API.md whenever you change the version
 // using the format described at https://keepachangelog.com/en/1.0.0/.
-const PLUGIN_API_VERSION = "1.0.0";
+const PLUGIN_API_VERSION = "1.1.0";
 
 // This helper prevents us from applying the same `modifyClass` over and over in test mode.
 function canModify(klass, type, resolverName, changes) {
@@ -331,12 +331,22 @@ class PluginApi {
   /**
    * addPosterIcon(callback)
    *
-   * This function can be used to add an icon with a link that will be displayed
+   * This function is an alias of addPosterIcons, which the latter has the ability
-   * beside a poster's name. The `callback` is called with the post's user custom
+   * to add multiple icons at once. Please refer to `addPosterIcons` for usage examples.
-   * fields and post attributes. An icon will be rendered if the callback returns
+   **/
-   * an object with the appropriate attributes.
+  addPosterIcon(cb) {
+    this.addPosterIcons(cb);
+  }
+
+  /**
+   * addPosterIcons(callback)
    *
-   * The returned object can have the following attributes:
+   * This function can be used to add one, or multiple icons, with a link that will
+   * be displayed beside a poster's name. The `callback` is called with the post's
+   * user custom fields and post attributes. One or multiple icons may be rendered
+   * when the callback returns an array of objects with the appropriate attributes.
+   *
+   * The returned object(s) each can have the following attributes:
    *
    *   icon        the font awesome icon to render
    *   emoji       an emoji icon to render
@@ -346,22 +356,35 @@ class PluginApi {
    *   text        (optional) text to display alongside the emoji or icon
    *
    * ```
-   * api.addPosterIcon((cfs, attrs) => {
+   * api.addPosterIcons((cfs, attrs) => {
    *   if (cfs.customer) {
    *     return { icon: 'user', className: 'customer', title: 'customer' };
    *   }
    * });
    * ```
+   * or
+   * * ```
+   * api.addPosterIcons((cfs, attrs) => {
+   *   return attrs.customers.map(({name}) => {
+   *     icon: 'user', className: 'customer', title: name
+   *   })
+   * });
+   * ```
    **/
-  addPosterIcon(cb) {
+  addPosterIcons(cb) {
     const site = this._lookupContainer("site:main");
     const loc = site && site.mobileView ? "before" : "after";
 
     decorateWidget(`poster-name:${loc}`, (dec) => {
       const attrs = dec.attrs;
-      const result = cb(attrs.userCustomFields || {}, attrs);
+      let results = cb(attrs.userCustomFields || {}, attrs);
 
-      if (result) {
+      if (results) {
+        if (!Array.isArray(results)) {
+          results = [results];
+        }
+
+        return results.map((result) => {
           let iconBody;
 
           if (result.icon) {
@@ -381,14 +404,22 @@ class PluginApi {
           }
 
           if (result.url) {
-          iconBody = dec.h("a", { attributes: { href: result.url } }, iconBody);
+            iconBody = dec.h(
+              "a",
+              { attributes: { href: result.url } },
+              iconBody
+            );
           }
 
           return dec.h(
             "span.poster-icon",
-          { className: result.className, attributes: { title: result.title } },
+            {
+              className: result.className,
+              attributes: { title: result.title },
+            },
             iconBody
           );
+        });
       }
     });
   }

docs/CHANGELOG-JAVASCRIPT-PLUGIN-API.md

@@ -7,6 +7,13 @@ in this file..
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [1.1.0] - 2021-12-15
+### Added
+- Adds `addPosterIcons`, which allows users to add multiple icons to a poster. The
+addition of this function also makes the existing `addPosterIcon` now an alias to this
+function. Users may now just use `addPosterIcons` for both one or many icons. This
+function allows users to now return many icons depending on an `attrs`.
+
 ## [1.0.0] - 2021-11-25
 ### Removed
 - Removes the `addComposerUploadProcessor` function, which is no longer used in