You cannot select more than 25 topics
Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
79 lines
3.1 KiB
ReStructuredText
79 lines
3.1 KiB
ReStructuredText
Writing Widgets for NodeBB
|
|
==========================
|
|
|
|
See the original `blog post <http://blog.nodebb.org/widgets-system/>`_ for a high level overview and screenshots of the widget system.
|
|
|
|
Embedding HTML and JavaScript
|
|
-----------------------------
|
|
|
|
You don't need to be a developer to figure this out. Head over to the Themes control panel and click on the Widgets tab. Create a new HTML widget by dragging and dropping the widget onto whatever template you want.
|
|
|
|
Copy and paste HTML or JavaScript into the widget and hit save - you're done!
|
|
|
|
You can optionally give your widget a container by dragging and dropping from the containers section onto your selected widget.
|
|
|
|
If you're looking for some sample scripts, head over to our `plugins section <http://community.nodebb.org/category/7/nodebb-plugins>`_ and look for any topic labelled ``nodebb-script-xyz``. Don't forget to submit your scripts and ideas as well!
|
|
|
|
|
|
Creating Widgets
|
|
-----------------------------
|
|
|
|
You can define widgets in both plugins and themes. If you're building a plugin which simply delivers a widget (or collection of widgets), we strongly suggest you follow the ``nodebb-widget-xyz`` nomenclature instead when publishing.
|
|
|
|
Registering your widget
|
|
^^^^^^^^^^^^^^^^^^^^^^^^^^^
|
|
|
|
Listen to this hook to register your widget:
|
|
|
|
.. code:: json
|
|
|
|
"hook": "filter:widgets.getWidgets", "method": "defineWidgets", "callbacked": true
|
|
|
|
Pass this back in the array:
|
|
|
|
.. code:: json
|
|
{
|
|
widget: "widget_namespace",
|
|
name: "My Widget",
|
|
description: "Short description of what it does.",
|
|
content: "<input type=\"text\" name=\"myKey\" class=\"form-control\" />"
|
|
}
|
|
|
|
|
|
``Content`` defines the form that is displayed to customize your widget in the admin panel.
|
|
|
|
Listening to your widget
|
|
^^^^^^^^^^^^^^^^^^^^^^^^^^^
|
|
|
|
NodeBB core will call your widget on the appropriate page load by way of the hooks system. The hook will be named after your widget's namespace (see previous example) - like so: ``filter:widget.render:widget_namespace``
|
|
|
|
This will pass in an object with the following useful properties:
|
|
|
|
* ``obj.area`` - will have ``location``, ``template``, ``url``
|
|
* ``obj.data`` - will have your admin-defined data; in the example from the previous section you will be exposed an ``obj.data.myKey``
|
|
|
|
Defining Widget Areas in Themes
|
|
------------------------------------
|
|
|
|
A Widget Area is characterized by a template and a location. Themes can share widgets if they define the same Widget Areas. If an admin switches themes, widgets that were previously defined in a Widget Area incompatible with the new theme are saved.
|
|
|
|
Listen to this hook to register your Widget Area:
|
|
|
|
.. code:: json
|
|
|
|
"hook": "filter:widgets.getAreas", "method": "defineWidgetAreas", "callbacked": true
|
|
|
|
Pass this back in the array:
|
|
|
|
.. code:: json
|
|
|
|
{
|
|
name: "Category Sidebar",
|
|
template: "category.tpl",
|
|
location: "sidebar"
|
|
}
|
|
|
|
|
|
And that's all. You can define as many Widget Areas in your theme as you wish. If you're still stuck, have a look at `this commit <https://github.com/designcreateplay/nodebb-theme-cerulean/commit/50e49a9da5a89484fa8001bbda2e613b69f18e86>`_ which upgraded the Cerulean theme to use the widget system.
|
|
|