Infinity Dashboard Custom Module Documentation



REQUIRED — Knowledge of how to program in Javascript. is required to create a custom module.

Creating a custom Infinity Dashboard module.

What is a custom module, and what can it do?

A custom module is a bundled set of files in a specific format that can be loaded and ran using Infinity Dashboard. A module has infinite number possibilities on what it can do, so long as it can return its data into a single string value. Some examples of some of the bundled modules are:

Getting started

Infinity Dashboard modules are written in Javascript and executed using Node.js v8.11.1.

As a module developer you have full access to the Node.js API methods and npm modules.

You should have some knowledge of programming Javascript before beginning.

Installing a custom module

Custom modules can be installed via the Custom Modules section in Infinity Dashboard, or by copying your module into the ~/Library/Application Support/com.fiplab.infinitydashboard/Modules directory.

When this guide references Installing a Module it is referring to using one of the above methods.

Module structure

A basic Infinity Dashboard module is made up of 3 main files:

<#Module Name#>.infinitymodule
  - package.json
  - main.js
<#Module Name#>.infinitymodule
This is a folder that has the .infinitymodule extension and contains all the resources, code, and node_modules for the module. The folder can be named anything.
package.json
The module description file in JSON Format. This file contains all the information Infinity Dashboard needs to know about your module such as: Display Name, Author, Version, User Configuration, whether the module supports notifications, etc. See the full documentation here.
main.js
The main entry point script for your module. When Infinity Dashboard goes to run your module this is the file that will be ran first.

package.json Documentation

The package.json while simple can be very complex, therefore the full documentation is available by going clicking the link below:

Read the full Package.json documentation

Globally accessible node modules

To make things easier we’ve bundled a few node modules that are globally accessible via require.

Using third party node modules

You can also use npm to install any additional node modules your module want to use. Make sure to install the additional node modules using the --save flag in your infinitymodule directory.

FIPLAB module API

Each module has access to the fiplab module API which manages the following:

To use the API simply paste the following into your module

const fiplab = require('fiplab');

Accessing the user configured values

The fiplab.arguments property is an Object that contains the values for the user_options values. The key of each property is the name field that was set in the package.json.

The value of the key will be in the format specified in the type field of the option. Date values will be returned a string in the following format yyyy-MM-dd HH:mm.

For more information on configuring the user_options value, read the package.json documentation.

# Access a specific value by using fiplab.arguments.<#KeyName#>
const apiKey = fiplab.arguments.apiKey;

Returning results for your module

In order to have Infinity Dashboard display the results for your module you need to run fiplab.exit when your module is finished. Calling this will force the module to exit, and the result will be displayed to the user. If your module fails to return a result Infinity Dashboard will attempt to re-run your module 3 times before giving up. Don’t run any code after using fiplab.exit because it may not be ran.

# For a successful result pass true in the second argument
fiplab.exit('Hello World', true);
# For a failed result pass false in the second argument
fiplab.exit('The error string', false);
# Change the color of the result in Infinity Dashboard
let returnOptions = {
    # 6 Digit hex strings are currently only supported
    'color': '#FD3641'
};

fiplab.exit('Woah, that is fancy!', true, returnOptions);
# Specify a URL that opens when the user clicks on the result
# In Infinity Dashboard
let returnOptions = {
    'onclick': 'http://fiplab.com'
};

fiplab.exit('Check this out!', true, returnOptions);

Displaying a notification to the user

In order to use this function make sure you’ve set the hasNotifications package property to true.

# Create a notification object
# The ID should be unique to this specific notification
# This allows Infinity Dashboard to prevent displaying multiple 
# of the same notification to the user

let notification = {
    id: 'my-unique-id-for-this-notification',
    message: 'The message to display to the user'
};

# Trigger the notification
fiplab.notify(notification);

Using the built-in database

The FIPLAB module setups a simple JSON based database adapter named lowdb.

# Access the bundled database property
let db = fiplab.db;

# Setup the defaults
db.defaults({ posts: [], user: {}, count: 0 })
  .write()

# Add a post
db.get('posts')
  .push({ id: 1, title: 'this is awesome'})
  .write()

# Set a user using Lodash shorthand syntax
db.set('user.name', 'typicode')
  .write()
  
# Increment count
db.update('count', n => n + 1)
  .write()

Read the database documentation here

Debugging your module

You can debug your module much like you would any other javascript script. The only different is that the console is displayed in the Logs section of the installed module instead of elsewhere.

The FIPLAB module overrides the following console methods: error, log, warn, info. Using any of these methods will allow your log methods to show up in the Logs section of the module.

Javascript errors will also be displayed in the Logs section.

Providing documentation for your module

Adding documentation for your module is as simple as including a README file in your module. Infinity Dashboard supports 3 types of files:

Placing a README.html file in your module’s directory will enable the Help tab in the module editor and will display the contents of the file to the user.

Simple Hello World module

# Access the fiplab module
const fiplab = require('fiplab');

# Something to return to the user
let returnString = 'Hello World';

# Let the module know we're done running and display the output
# to the user.
fiplab.exit(returnString, true);

Tutorial

Read the Hello World tutorial