Skip to content

Coding a new plugin

Jump to bottom
Johnathan Andersen edited this page Jan 10, 2019 · 20 revisions

Plugin requirements

If you want to create your own plugin, this isn't too hard! All your plugin needs to do is implement the following interface in PHP:

interface iPlugin {
    public function getIndex();
    public function getName();
    public function isActive($config);
    public function getResources($config);
    public function getImage($config, $device);
    public function getDeviceType($device);
}

You then need to add an instance of your plugin to the plugins array defined in the web/plugin_dependencies/iPlugin.php file. When you've implemented all this, place your plugin in the web/plugins/ directory. Any settings relevant to your plugin (such as whether it is active) can be added to the web/config/settings.cfg file. Be sure to also add sane defaults to web/config/settings.cfg.example so that other will be able to figure out how to use your plugin!

For a step-by-step example of creating a new plugin, see the xkcd plugin case study article.

Required Plugin functions

There are a few functions that are required for a plugin. These functions will be used to fill menus in the device manager website and to provide a conduit for information to flow from your data content source to the wall-ink devices. For instance, if you were implementing a weather station plugin, the device manager might allow you to choose a size screen, the orientation of the screen, and what city's weather to display. Your plugin would also have to include code to gather weather information from some source, and then draw a compatible image of the correct format to be delivered to a wall-ink device.

getIndex()

This function needs to return a non-negative integer that is not the same as the integer returned by any of the other plugins. A single or double-digit number is fine, just check first that you won't be colliding with other plugins.

This non-negative integer will be used by the device manager database to keep track of which wall-ink device is associated with which plugin.

getName()

This function returns a string containing the name of your plugin. For example, you might use return 'Exchange';

This string is used in the device manager in the drop-down list of plugins to choose from.

isActive($config)

This function returns either the string "true" or the string "false".

This is an aid for performance and debugging purposes to turn plugins on and off. There may be unexpected results if devices exist in the device manager database for a particular plugin, and that plugin is either inactive or removed.

getResources($config)

This function returns an array with resource IDs (a unique ID corresponding to a scheduleable resource) as the keys and resource names as the values.

This array of resources is used to fill the drop down menu in the device manager when selecting which resource will be associated with a particular wall-ink device.

getImage($config, $device)

This function takes in some information about a wall-ink device, and returns the file directory of the image that will be sent to the screen. The image needs to be made in a very specific format. If you're implementing a scheduling plugin, you'll probably be able to copy/paste an existing plugin's getImage function. If you run into difficulties, please contact one of the project's developers.

getDeviceType($device)

This function takes in some information about a wall-ink device, and returns some HTML that will be displayed on the edit_device page to help an admin choose what type of device it is (the name of this function is a little confusing). If you're implementing a scheduling plugin, you'll should be able to simply copy/paste an existing plugin's getDeviceType function. Otherwise, you'll need to write your own. A few details on that:

  • Specifically, your function should return a string containing an HTML fieldset. The name should be set to "new_device_type".
  • There is a js associative array called defaults containing default values for the device type. You'll want to set a default device type by adding a member to the array with the pluginIndex as the key and the default value as the value.
  • In order for this default value to work when switching plugins, you need to give each input tag an id formatted as follows: "type_" + deviceType + "_" + pluginIndex. For example, if your pluginIndex is 8 and your deviceType is 4, you'll give it the id "type_4_8".
  • This system of setting defaults has not been tested with any input type other than radio buttons, but this could probably be implemented if the feature were to be requested.
  • Sorry this was a little bit messy. The whole plugin functionality was added after most of the project was already written, but we did our best to shoehorn it into things without making it too hard to use.

If you run into difficulties, please contact one of the project's developers.

Creating a new plugin case study

Watch step-by-step as a new plugin is created by altering a couple of existing plugins to create a new plugin to display xkcd comics using the xkcd api. The article includes a check-list of everything necessary to create a new plugin from start to finish.

Scheduler plugin functions

If a new plugin is to use the existing scheduler plugin code, two existing functions are available to speed up the process.

schedulingGetDeviceType($device, $pluginIndex)

This function is used in the device manager website's edit_device page to generate the part of the form that allows a user to select which layout a particular device will use. It returns a string containing the necessary HTML code.

schedulingGetImage($config, $device, $schedule, $displayUrl, $qrCodeString)

This function takes input about a particular wall-ink device and the schedule it is to display and uses compile C++ code to draw a compatible wall-ink device image. For the most part, the use of this function can be a "copy" "paste" of other like plugins, as long as a valid getSchedule function has been created for your scheduling software. See the exampleSchedulerPlugin, the Booked plugin and the Google plugin for example code.

getSchedule($config, $resourceId)

The getSchedule function is left to the plugin developer, but several examples can be browsed in the existing plugins. See the exampleSchedulerPlugin, the Booked plugin and the Google plugin for example code.

The private getSchedule plugin function will gather data from your scheduling software and format it in a specific manner that will be used to generate images that a wall-ink device can display. The schedule returned from your getSchedule() function will be passed into the scheduleGetImage() function to automatically create images as seen below.

The assumption of the engine that creates the images as seen above, is that the schedule returned by getSchedule() is just for the current date. There is currently no implementation of schedule images that cover multiple days, or a week or a month, just the current day.

This getSchedule() function must return a string formatted like the one below:

EB Team Room #224
Team 23 Meeting
2018-10-23 08:00:00
2018-10-23 10:00:00
Math Study Group
2018-10-23 11:00:00
2018-10-23 12:00:00
Physics Study Group
2018-10-23 12:00:00
2018-10-23 14:00:00
Farm Robot Group
2018-10-23 14:30:00
2018-10-23 16:00:00
Hybrid Rocket Project
2018-10-23 16:00:00
2018-10-23 18:00:00

The first line is the name of the room or resource being scheduled. This line is followed by information about any number of events, meetings, or other reservations for an entire day. Each reservation is formatted in the following way:

  • Line 1: The name of the reservation
  • Line 2: The beginning time/date of the reservation, in the format shown above
  • Line 3: The ending time/date of the reservation, in the format shown above

There are several different layouts for a day's schedule, but in general they typically have common elements such as the name of the current event, and one or two future events, and a picture representing what times are scheduled throughout the day.

Clone this wiki locally