Extending

Actinium is easy to extend and much of its bootstrapping is hook-able.

For more information on the available hooks see: Actinium Hooks

Actinium SDK

Suppose you're creating a plugin and you want to share the functionality with other plugins. You can opt to extend the Actinium SDK by creating a namespace on the Actinium global.

Plugin

/src/app/MyPlugin/plugin.js

// Extend Actinium SDK 
Actinium.MyPlugin = require('./sdk');

MyPlugin SDK

/src/app/MyPlugin/sdk.js

const COLLECTION = 'SomeCollection';

const MyPluginSDK = {}; 

MyPluginSDK.create = async (req, options) => {
    
    // Get params from request object 
    let { params } = req; 
    
    // Run a hook so other plugins can do some thangs to the params
    await Actinium.Hook.run('some-collection-before-create', params, req, options);
    
    // Create the new object
    const obj = new Actinium.Object(COLLECTION);
    
    // Save the object
    let savedObj = await obj.save(params, options);
    
    if (!savedObj) { 
        return new Error('Unable to save SomeCollection object'); 
    }
    
    // Convert the Actinium.Object into a JavaScript Object. 
    savedObj = saveObj.toJSON(); 
    
    // Run a hook so other plugins can do some thangs 
    await Actinium.Hook.run('some-collection-created', savedObj, req, options);
    
    return savedObj;
};

module.exports = MyPluginSDK;

In the above example your Actinium extension will be available regardless of your plugin's active status. If you want your extension to only be available if your plugin is active you'll want to register a plugin-load hook and define it after validating that your plugin is active using Actinium.Plugin.isActive.

/src/app/MyPlugin/plugin.js

const SDK = require('./sdk'); 

const PLUGIN = {
    ID: 'MyPlugin',
    name: 'My Awesome Plugin',
    description: 'The name says it all bro',
    version: {
        actinium: '>=3.0.5',
        plugin: '0.0.1',
    },
};

Actinium.Plugin.register(PLUGIN);

Actinium.Hook.register('plugin-load', async ({ ID }) => {
    if (ID !== PLUGIN.ID) return;
    if (!Actinium.Plugin.isActive(ID)) return;
    
    Actinium.MyPlugin = SDK;
});

Note: In the above example your extension will not be available in the file scope.

Cloud Functions

Cloud functions are another way to extend Actinium functionality. Cloud functions are accessible to other plugins and the Actinium client SDK via Actinium.Cloud.run. You can define a cloud function in a plugin.js file. A typical cloud function may look like:

/src/app/MyPlugin/plugin.js

const SDK = require('./sdk'); 
const { CloudRunOptions } = require(`${ACTINIUM_DIR}/lib/utils`);

const PLUGIN = {
    ID: 'MyPlugin',
    name: 'My Awesome Plugin',
    description: 'The name says it all bro',
    version: {
        actinium: '>=3.0.5',
        plugin: '0.0.1',
    },
};

Actinium.Plugin.register(PLUGIN);

Actinium.Cloud.define('my-plugin-create', req => {
    const options = CloudRunOptions(req); 
    return SDK.create(req, options); 
});

If your cloud function requires capabilities or roles be sure to create the options object via the CloudRunOptions helper.

Client Side Usage

Usage: Reactium ~ services.js

import Actinium from 'appdir/api'; 

const create = params => Actinium.Cloud.run('my-plugin-create', params);

export default {
    create,
};

Other Plugin Usage

Usage: Actinium ~ plugin.js

const { CloudRunOptions } = require(`${ACTINIUM_DIR}/lib/utils`);

Actinium.Cloud.define('some-other-plugin', async req => {
    const options = CloudRunOptions(req);
    const params = { someparam: 'somevalue' };
    const newObj = await Actinium.Cloud.run('my-plugin-create', params, options); 
    
    // do something else like transform the newObj with a hook 
    await Actinium.Hook.run('some-other-plugin-hook', newObj, req, options); 
    
    return newObj;  
};

Express Middleware

You can extend the underlying Express app by registering middleware that will be loaded on start-up. Register middleware using the Actinium.Middleware.register function.

const express = require('express');
const { myPluginMiddleware } = require('./sdk'); 

Actinium.Middleware.register('my-plugin-mw', app => {
    // custom middleware 
    app.use(myPluginMiddleware()); 
    
    // custom route handler
    const router = express.Router();
    
    router.use('/some/route/*', (req, res, next) => {
        console.log('Log something'); 
        res.send('Send something to browser'); 
    });
    
    // mount the router on app
    app.use(router);
});

For more information on middleware see: Express Middleware