init plugins documentation

docs/index.rst

@@ -57,6 +57,7 @@ Plugin System
     :maxdepth: 2
 
     plugins/create
+    plugins/hooks
     plugins/resources
 
 Widgets System

docs/plugins/create.rst

@@ -1,11 +1,120 @@
 Writing Plugins for NodeBB
 ==========================
 
+So you want to write a plugin for NodeBB, that's fantastic! There are a couple of things you need to know before starting that will help you out.
 
-testing
+Like WordPress, NodeBB's plugins are built on top of a hook system in NodeBB. This system exposes parts of NodeBB to plugin creators in a controlled way, and allows them to alter content while it passes through, or execute certain behaviours when triggered.
 
+The complete list of hooks built into NodeBB can be found at [[List of Hooks]]
 
-testing
+Filters and Actions
--------
+------------------
 
-testing
+There are two types of hooks: **filters** and **actions**.
+
+*Filters* act on content, and can be useful if you want to alter certain pieces of content as it passes through NodeBB. For example, a filter may be used to alter posts so that any occurrences of "apple" gets changed to "orange". Likewise, filters may be used to beautify content (i.e. code filters), or remove offensive words (profanity filters).
+
+*Actions* are executed at certain points of NodeBB, and are useful if you'd like to *do* something after a certain trigger. For example, an action hook can be used to notify an admin if a certain user has posted. Other uses include analytics recording, or automatic welcome posts on new user registration.
+
+When you are writing your plugin, make sure a hook exists where you'd like something to happen. If a hook isn't present, [file an issue](https://github.com/designcreateplay/NodeBB/issues) and we'll include it in the next version of NodeBB.
+
+plugin.json
+------------------
+
+Each plugin package contains a configuration file called ``plugin.json``. Here is a sample:
+
+.. code:: json
+
+    {
+        "id": "my-plugin",
+        "name": "My Awesome Plugin",
+        "description": "Your plugin's description",
+        "url": "Absolute URL to your plugin or a Github repository",
+        "library": "./my-plugin.js",
+        "staticDir": "/assets",
+        "less": [
+            "assets/style.less"
+        ],
+        "hooks": [
+            { "hook": "filter:post.save", "method": "filter", "callbacked": true },
+            { "hook": "action:post.save", "method": "emailme" }
+        ]
+    }
+
+The ``id`` property is a unique name that identifies the plugin.
+
+The ``library`` property is a relative path to the library in your package. It is automatically loaded by NodeBB (if the plugin is activated).
+
+The ``staticDir`` property is a path (relative to your plugin's root) to a directory that NodeBB will expose to the public at the route ``/plugins/{YOUR-PLUGIN-ID}``.
+
+The ``less`` property contains an array of paths (relative to your plugin's directory), that will be precompiled into the CSS served by NodeBB.
+
+The ``css`` property contains an array of paths (relative to your plugin's ``staticDir``) that will be served to the end user as a stylesheet. In the example above, the ``style.css`` would end up accessible at: ``/plugins/my-plugin/public/style.css``, and would be located in the ``public`` directory in your plugin's root. **Note**: The ``css`` property is not recommended, as it may be deprecated in the future. Use ``less`` instead.
+
+The ``hooks`` property is an array containing objects that tell NodeBB which hooks are used by your plugin, and what method in your library to invoke when that hook is called. Each object contains the following properties (those with a * are required):
+
+* ``hook``*, the name of the NodeBB hook
+* ``method``*, the method called in your plugin
+* ``callbacked``, whether or not the hook expects a callback (true), or a return (false). Only used for filters. (Default: false)
+* ``priority``, the relative priority of the method when it is eventually called (default: 10)
+
+Writing the plugin library
+------------------
+
+The core of your plugin is your library file, which gets automatically included by NodeBB if your plugin is activated.
+
+Each method you write into your library takes a certain number of arguments, depending on how it is called:
+
+* Filters send a single argument through to your method, although asynchronous methods can also accept a callback (if specified in ``plugin.json``).
+* Actions send a number of arguments (the exact number depends how the hook is implemented). These arguments are listed in [[List of Hooks]].
+
+Example library method
+------------------
+
+If we were to write method that listened for the ``action:post.save`` hook, we'd add the following line to the ``hooks`` portion of our ``plugin.json`` file:
+
+.. code:: json
+
+    { "hook": "action:post.save", "method": "myMethod" }
+
+Our library would be written like so:
+
+.. code:: javascript
+
+    var MyPlugin = {
+            myMethod: function(postData) {
+                // do something with postData here
+            }
+        };
+
+Using NodeBB libraries to enhance your plugin
+------------------
+
+Occasionally, you may need to use NodeBB's libraries. For example, to verify that a user exists, you would need to call the ``exists`` method in the ``User`` class. To allow your plugin to access these NodeBB classes, use ``module.parent.require``:
+
+.. code:: javascript
+
+    var User = module.parent.require('./user');
+    User.exists('foobar', function(err, exists) {
+        // ...
+    });
+
+Installing the plugin
+------------------
+
+In almost all cases, your plugin should be published in [npm](https://npmjs.org/), and your package's name should be prefixed "nodebb-plugin-". This will allow users to install plugins directly into their instances by running ``npm install``.
+
+When installed via npm, your plugin **must** be prefixed with "nodebb-plugin-", or else it will not be found by NodeBB.
+
+As of v0.0.5, "installing" a plugin by placing it in the ``/plugins`` folder is still supported, but keep in mind that the package ``id`` and its folder name must match exactly, or else NodeBB will not be able to load the plugin. *This feature may be deprecated in later versions of NodeBB*.
+
+Testing
+------------------
+
+Run NodeBB in development mode:
+
+.. code::
+
+    ./nodebb dev
+
+This will expose the plugin debug logs, allowing you to see if your plugin is loaded, and its hooks registered. Activate your plugin from the administration panel, and test it out.

docs/plugins/hooks.rst

@@ -0,0 +1,186 @@
+List of Hooks
+=============
+
+The following is a list of all hooks present in NodeBB. This list is intended to guide developers who are looking to write plugins for NodeBB. For more information, please consult [[Writing Plugins for NodeBB]].
+
+There are two types of hooks, **filters**, and **actions**. Filters take an input (provided as a single argument), parse it in some way, and return the changed value. Actions take multiple inputs, and execute actions based on the inputs received. Actions do not return anything.
+
+**Important**: This list is by no means exhaustive. Hooks are added on an as-needed basis (or if we can see a potential use case ahead of time), and all requests to add new hooks to NodeBB should be sent to us via the [issue tracker](https://github.com/designcreateplay/NodeBB/issues).
+
+
+Filters
+----------
+
+``filter:admin.header_build``
+^^^^^^^^^^^^^^^^^^^^^
+
+Allows plugins to create new navigation links in the ACP
+
+`filter:post.save`
+^^^^^^^^^^^^^^^^^^^^^
+
+**Argument(s)**: A post's content (markdown text)
+
+Executed whenever a post is created or edited, but before it is saved into the database.
+
+`filter:post.get`
+^^^^^^^^^^^^^^^^^^^^^
+
+**Argument(s)**: A post object (javascript Object)
+
+Executed whenever a post is retrieved, but before being sent to the client.
+
+`filter:header.build`
+^^^^^^^^^^^^^^^^^^^^^
+
+**Allows plugins to add new navigation links to NodeBB**
+
+[View commit for more details](https://github.com/designcreateplay/NodeBB/commit/a63732027f9ba0bd54254c3b5c83f2a63f1ad531)
+
+`filter:post.parse`
+^^^^^^^^^^^^^^^^^^^^^
+
+**Argument(s)**: A post or signature's raw text (String)
+
+Executed when a post or signature needs to be parsed from raw text to HTML (for output to client). This is useful if you'd like to use a parser to prettify posts, such as [Markdown](http://daringfireball.net/projects/markdown/), or [BBCode](http://www.bbcode.org/).
+
+`filter:posts.custom_profile_info`
+^^^^^^^^^^^^^^^^^^^^^
+
+**Allows plugins to add custom profile information in the topic view's author post block**
+
+[View commit for more details](https://github.com/designcreateplay/NodeBB/commit/bf677522a93ec4c48f6b0fa27ab1388f9eedba4c)
+
+`filter:register.check`
+^^^^^^^^^^^^^^^^^^^^^
+
+**Allows plugins to run checks on information and deny registration if necessary.**
+
+[View commit for more details](https://github.com/designcreateplay/NodeBB/commit/cd4a204f999d5ef5bac4557f03d4c15abebfdce3)
+
+`filter:scripts.get`
+^^^^^^^^^^^^^^^^^^^^^
+
+**Allows to add client-side JS to the header and queue up for minification on production**
+
+[View commit for more details](https://github.com/designcreateplay/NodeBB/commit/5357ad61db6c15bc25a7e836548a02fadd72e6b3)
+
+`filter:uploadImage`
+^^^^^^^^^^^^^^^^^^^^^
+
+`filter:uploadFile`
+^^^^^^^^^^^^^^^^^^^^^
+
+`filter:widgets.getAreas`
+^^^^^^^^^^^^^^^^^^^^^
+
+`filter:widgets.getWidgets`
+^^^^^^^^^^^^^^^^^^^^^
+
+`filter:search.query`
+^^^^^^^^^^^^^^^^^^^^^
+
+`filter:post.parse`
+^^^^^^^^^^^^^^^^^^^^^
+
+`filter:messaging.parse`
+^^^^^^^^^^^^^^^^^^^^^
+
+`filter:sounds.get`
+^^^^^^^^^^^^^^^^^^^^^
+
+`filter:post.getPosts`
+^^^^^^^^^^^^^^^^^^^^^
+
+`filter:post.getFields`
+^^^^^^^^^^^^^^^^^^^^^
+
+`filter:auth.init`
+^^^^^^^^^^^^^^^^^^^^^
+
+`filter:composer.help`
+^^^^^^^^^^^^^^^^^^^^^
+
+`filter:topic.thread_tools`
+^^^^^^^^^^^^^^^^^^^^^
+
+`filter:user.create`
+^^^^^^^^^^^^^^^^^^^^^
+
+`filter:widget.render`
+^^^^^^^^^^^^^^^^^^^^^
+
+
+
+Actions
+----------
+
+`action:app.load`
+^^^^^^^^^^^^^^^^^^^^^
+
+**Argument(s)**: None
+
+Executed when NodeBB is loaded, used to kickstart scripts in plugins (i.e. cron jobs, etc)
+
+`action:page.load`
+^^^^^^^^^^^^^^^^^^^^^
+
+**Argument(s)**: An object containing the following properties:
+
+* `template` - The template loaded
+* `url` - Path to the page (relative to the site's base url)
+
+`action:plugin.activate`
+^^^^^^^^^^^^^^^^^^^^^
+
+**Argument(s)**: A String containing the plugin's `id` (e.g. `nodebb-plugin-markdown`)
+
+Executed whenever a plugin is activated via the admin panel.
+
+**Important**: Be sure to check the `id` that is sent in with this hook, otherwise your plugin will fire its registered hook method, even if your plugin was not the one that was activated.
+
+`action:plugin.deactivate`
+^^^^^^^^^^^^^^^^^^^^^
+
+**Argument(s)**: A String containing the plugin's `id` (e.g. `nodebb-plugin-markdown`)
+
+Executed whenever a plugin is deactivated via the admin panel.
+
+**Important**: Be sure to check the `id` that is sent in with this hook, otherwise your plugin will fire its registered hook method, even if your plugin was not the one that was deactivated.
+
+`action:post.save`
+^^^^^^^^^^^^^^^^^^^^^
+
+**Argument(s)**: A post object (javascript Object)
+
+Executed whenever a post is created or edited, after it is saved into the database.
+
+`action:email.send`
+^^^^^^^^^^^^^^^^^^^^^
+
+`action:post.setField`
+^^^^^^^^^^^^^^^^^^^^^
+
+`action:topic.edit`
+^^^^^^^^^^^^^^^^^^^^^
+
+`action:post.edit`
+^^^^^^^^^^^^^^^^^^^^^
+
+`action:post.delete`
+^^^^^^^^^^^^^^^^^^^^^
+
+`action:post.restore`
+^^^^^^^^^^^^^^^^^^^^^
+
+`action:config.set`
+^^^^^^^^^^^^^^^^^^^^^
+
+`action:topic.save`
+^^^^^^^^^^^^^^^^^^^^^
+
+`action:user.create`
+^^^^^^^^^^^^^^^^^^^^^
+
+`action:topic.delete`
+^^^^^^^^^^^^^^^^^^^^^