Merge pull request #375 from SockDrawer/advertise-capabilities-#345

Advertise capabilities #345

docs/Development/Providers/index.md

@@ -59,6 +59,19 @@ A function must be exposed named `activate`. This function will be given no para
 
 A function must be exposed named `deactivate`. This function will be given no parameters. It should call `deactivate` on all registered plugins. It must return a promise that will resolve if and when the forum object is succesfully deactivated.
 
+### supports
+
+A function must be exposed named `supports`. This function will be given either a functionality string or an array of functionality strings. It should return true if the forum supports the requested functionality, or false otherwise.
+
+A functionality string is a string that obeys the following rules:
+- The string contains up to ten tokens
+- These tokens are separated by periods
+- Each token is considered a hierarchical list of capabilities; tokens to the right are considered sub-capabilities of tokens to the left
+
+This method must return false if any token in the string is not supported. For example, if the forum supports users but not avatars, it may accept `Users` but must reject `Users.Avatars`.
+
+If an array of functionality strings is supplied, this method must reject if any of them are unsupported.
+
 ## Objects
 
 The following pages have more detail about the types of objects a Forum can instantiate:

docs/Development/plugin creation.md

@@ -1,3 +1,45 @@
 # Plugin Creation
 
-Coming soon: Plugin creation instructions for Sockbot 3.0! 
+Coming soon: Plugin creation instructions for Sockbot 3.0! 
+
+
+## Topic: Cross-Platform Support
+
+When creating a plugin that can work across platforms, it can be helpful to use the `Forum.supports()` function to query for specific capabilities your plugin needs.
+
+A plugin should refuse to activate on a platform that does not support key functionalty. If extra functionality is unsupported, it can be disabled at activation time. Plugins should use the `Formatting` capability key to determine what sort of output to produce and adjust to the platform.
+
+### Known Capabilities
+
+- Chats
+- PMs
+- Users
+    - Avatars
+    - Follow
+    - URL
+    - Seen
+    - PostCount
+- Posts
+    - Edit
+    - Delete
+    - Bookmark
+    - Vote
+    - URL
+- Topics
+    - URL
+    - Watch
+    - Mute
+- Categories
+    - Management
+- Notifications
+    - URL
+- Formatting
+    - Markup
+        - Markdown
+        - BBCode
+        - HTML
+    - Multiline
+    - Colors
+    - Links
+    - Images
+    - Spoilers

providers/nodebb/index.js

@@ -391,6 +391,34 @@ class Forum extends EventEmitter {
         return new Promise(promiser)
             .then(() => this);
     }
+
+    supports(supportString) {
+        const supported = [
+            'Chats',
+            'Users', 'Users.Avatars', 'Users.Follow', 'Users.URL', 'Users.Seen', 'Users.PostCount',
+            'Posts', 'Posts.Edit', 'Posts.Vote', 'Posts.Delete', 'Posts.Bookmark', 'Posts.URL',
+            'Topics', 'Topics.URL', 'Topics.Watch', 'Topics.Mute',
+            'Categories',
+            'Notifications', 'Notifications.URL',
+            'Formatting', 'Formatting.Markup', 'Formatting.Markup.Markdown',
+            'Formatting.Multiline', 'Formatting.Links', 'Formatting.Images', 'Formatting.Spoilers'
+        ];
+
+        let support = false;
+
+        if (Array.isArray(supportString)) {
+            support = supportString.reduce((value, item) => {
+                return value && this.supports(item);
+            }, true);
+            return support;
+        }
+
+        if (supported.indexOf(supportString) > -1) {
+            support = true;
+        }
+
+        return support;
+    }
 
     /**
      * Emit a websocket event

test/providers/nodebb/indexTest.js

@@ -857,6 +857,56 @@ describe('providers/nodebb', () => {
             return forum.deactivate().should.be.rejected;
         });
     });
+    describe('supports', () => {
+        let forum = null,
+            sandbox = null;
+
+        beforeEach(() => {
+            sandbox = sinon.sandbox.create();
+            forum = new Forum({
+                core: {}
+            });
+            sandbox.stub(forum.Notification, 'deactivate');
+            sandbox.stub(forum.Chat, 'deactivate');
+        });
+        afterEach(() => sandbox.restore());
+
+        it('must expose a method named supports', () => {
+            forum.supports.should.be.a('function');
+        });
+
+        it('must return false if a capability is unsupported', () => {
+            forum.supports('Jack').should.be.false;
+            forum.supports('PMs').should.be.false;
+        });
+
+        it('must return true if a capability is supported', () => {
+            forum.supports('Chats').should.be.true;
+            forum.supports('Users').should.be.true;
+            forum.supports('Posts').should.be.true;
+            forum.supports('Topics').should.be.true;
+            forum.supports('Categories').should.be.true;
+            forum.supports('Notifications').should.be.true;
+            forum.supports('Formatting').should.be.true;
+        });
+
+        it('must return false if a sub-capability is not supported', () => {
+            forum.supports('Jack.Skellington').should.be.false;
+            forum.supports('Chats.WithJackSkellington').should.be.false;
+        });
+
+        it('must return true if a sub-capability is supported', () => {
+            forum.supports('Users.Avatars').should.be.true;
+        });
+
+        it('should return true if all items in an array are supported', () => {
+            forum.supports(['Users', 'Chats']).should.be.true;
+        });
+
+        it('must return false if any items in an array are not supported', () => {
+            forum.supports(['Users', 'Chats', 'Halloween']).should.be.false;
+        });
+    });
     describe('_emit', () => {
         let forum = null;
         beforeEach(() => {