afrux/forum-widgets-core

Core Extension for Managing Forum Widgets

Fund package maintenance!
Other

Installs: 14 618

Dependents: 29

Suggesters: 0

Security: 0

Stars: 15

Watchers: 1

Forks: 4

Open Issues: 11

Language:TypeScript

Type:flarum-extension

v0.1.7 2022-03-03 19:50 UTC

This package is auto-updated.

Last update: 2024-03-19 22:26:40 UTC


README

icon

Forum Widgets

License Latest Stable Version Total Downloads donate

Flarum Core Extension for Managing Forum Widgets.
animated_screenshot
forum screenshot

Installation

Remember that this is just a forum widgets editor, it doesn't actually come with any widgets.

Install with composer:

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

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

Updating

composer update afrux/forum-widgets-core:"*"
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"
},
  1. 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="Afrux-OnlineUsersWidget-users">
        // ...
      </div>
    );
  }
}
  1. Register your widget in the admin and forum frontends:
  • 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');
};
  • 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);
});
  1. 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