Introduction

Howdy , while working on a Flarum theme I wanted to install some of the existing widgets in the community and customise them for that theme to spice it up a little, unfortunately the fact that every widget adds itself into the layout in its own way with its own custom structure and CSS classes, helps neither the admin of the forum to manage them, nor the theme designer to customise them. So I decided to build this little package to normalise things a bit and focus the role of placing the widgets and managing them here, while the actual widgets can be separate extensions focusing on what they actually provide.

This is still a relatively simple package however, right now it allows extension developers to register a widget per extension and select a default location out of 5, and allows the admin to override that and move them around. This already helps a ton by normalising the design of the widgets and giving a certain amount of control.

I also created 4 simple widgets that can currently be used, links are in the installation section below.

Future Goals

• Options to override widget titles, icons and descriptions.
• Support multi widgets (widgets that can be added multiple times, such as HTML widgets perhaps).
• Allow widgets to be shown in more pages than the index (this might require Flarum 2.0).
• Add more sections to insert widgets (might also require Flarum 2.0).
• More widgets ? The community can also do that, this is the whole point.

Suggestions should be posted here and/or the github repository!

Installation

Remember that this is just a forum widgets editor, it doesn't actually come with any widgets, if you wish to install it with the existing widgets listed below in one go, you can use the bundle:

$ composer require afrux/forum-widgets-bundle:"*"

When updating the bundle:

composer update afrux/forum-widgets-bundle --with-dependencies

Otherwise you can just install this package alone:

composer require afrux/forum-widgets-core:"*"

Here is a list of currently compatible widgets you can install:

• Online Users
• Forum Stats
• Top Posters
• News Fader

Updating

composer update afrux/forum-widgets-core --with-dependencies
php flarum migrate
php flarum cache:clear

Extend

Extension developers wanting to create widgets with this small framework, the following explains how you can register a new widget, for now you should only register one widget per extension.

1. Require this extension in your extension's composer.json:

   "require": {
     "flarum/core": "^1.0.0",
     "afrux/forum-widgets-core": "^0.1.0"
   },

2. Create your widget's component in common/components by extending the base Widget component provided with this package.

   import Widget from 'flarum/extensions/afrux-forum-widgets-core/common/components/Widget';
   
   export default class MyWidget extends Widget {
     className() {
       // Custom class name.// You can also use the class "AfruxWidgets-Widget--flat" for a flat widget (not contained in a block).
       // Please avoid strong custom styling so that it looks consistent in other themes.
       return 'MyWidget';
     }
   
     icon() {
       // Widget icon.
       return 'fas fa-cirlce';
     }
   
     title() {
       // Widget title.
       // Can return empty for a titleless widget.
       return app.translator.trans('afrux-online-users-widget.forum.widget.title');
     }
   
     content() {
       return (
         <div className="MyWidget-content">
           // ...
         </div>
       );
     }
   }

3. Register your widget in the admin and forum frontends:

4. Create a new registerWidget.js file in common:

   import Widgets from 'flarum/extensions/afrux-forum-widgets-core/common/extend/Widgets';
   
   import MyWidget from './components/MyWidget';
   
   export default function(app) {
     (new Widgets).add({
       key: 'onlineUsers',
       component: MyWidget,
       
       // Can be a callback that returns a boolean value.
       // example: () => app.forum.attribute('myCustomExtension.mySetting')
       isDisabled: false,
       
       // Is this a one time use widget ? leave true if you don't know.
       isUnique: true,
       
       // The following values are default values that can be changed by the admin.
       placement: 'end',
       position: 1,
     }).extend(app, 'my-extension-id');
   };

5. Register the widget in both frontends admin/index.js & forum/index.js:

   import registerWidget from '../common/registerWidget';
   
   app.initializers.add('my-extension-id', () => {
     registerWidget(app);
   });

6. If you are using typescript, you can add the typings of this package by adding this to the paths key in your tsconfig.json file:

   "flarum/extensions/afrux-forum-widgets-core/*": ["../vendor/afrux/forum-widgets-core/js/dist-typings/*"]

You can also checkout other example widgets in the Afrux github org.

Links

• Packagist
• GitHub
• Discuss