DIY Plugin Development

  • Description
    These Guides are from @SVS.
    @SVS tested this code but just in case:
    USE AT OWN RISK. THIS MAY CORRUPT YOUR SYSTEM AND YOU CAN LOSE DATA.


    This tutorial aims to give you some knowledge how to make plugins for OMV 0.5.xx.
    I recommend to do development on a virtual system.
    I recommend that you have knowledge of the following: javascript, php, shell scripts


    • Part 1: GUI (Web interface)
    • Part 2: config.xml and RPC
    • Part 3: Modules and Shell Scripts
  • Part 1: GUI (Web interface)


    The GUI base system (Ext JS 4.2.x) uses JavaScript files to construct the graphical view of the pages.


    Check out the OMV types at http://docs.openmediavault.org/group__webgui.html
    Check out the full Ext JS API at http://docs.sencha.com/extjs/4.2.0/#!/api


    The backend automatically scans the following folders (and their subfolders) for JavaScript files (.js).


    Code
    /var/www/openmediavault/js/omv/module/admin/
    /var/www/openmediavault/js/omv/module/user/
    /var/www/openmediavault/js/omv/module/public/


    Maybe you already guessed that the stuff in the admin folder is only available to the admin and stuff in the user folder is available to the user (Yes, users can also login to the web interface). So if you are making a plugin that is intended for users then put it in the users folder.


    STEP 1: Start by making a separate folder for your own plugin.


    Code
    /var/www/openmediavault/js/omv/module/admin/service/example



    STEP 2: A node is a single object in the navigation view (folder/tree view on the left).


    Each node is declared in a separate JavaScript file. Now make a file called Example.js with the following code:


    Place the file in the folder you created in step one and go to the GUI to see if it showed up. If you already are in the GUI refresh the page to update the changes. Under Services folder you should now have an ftp icon with the text “Example” next to it.


    With never versions of OpenMediaVault you need to purge the internal cache of Javascript files. This can be achieved by running source /usr/share/openmediavault/scripts/helper-functions && omv_purge_internal_cache on the server.


    A quick note about translations. As you can see above the text option is wrapped in _(). _ is a function that translates text and takes a string as first parameter. This means that text that you want translated in the future should be wrapped in _() and text that you don't, you just write as normally.


    STEP 3: A node has “main view” that is called a workspace.


    There are different class types derived from the workspace class. In this example we will extend the class OMV.workspace.form.Panel. Couple of features of this class:

    • It has built in Save and Reset buttons.
    • It can be used as a tab.

    Make a file called Settings.js and enter the following code into it. Read the comments and try to understand what's happening.


    Now put this in the same folder as the Example.js.



    STEP 4: In order to make the GUI error free we need to make an RPC Service for the form.


    This is not explained as it is part of the next tutorial. Create a file called example.inc and write the following code into the file.


    Put the file in the following folder /usr/share/openmediavault/engined/rpc. Then open the terminal and run the following command: service openmediavault-engined restart.


    That's it for the RPC for now. We will continue to work on it in the next tutorial.


    Go the the web interface and click on your service. Now you should see the a view with the Save and Reset buttons on top, a fieldset with the title "General" that contains a check box and field where you can enter only numbers.


    You could now try to make changes to the layout. For example, try adding a text field (hint, xtype: “textfield”).


    If you get an error message “RPC service not found (name=Example)” there is something wrong with the example.inc file. Go through STEP 4 again.


    Useful Links:
    http://docs.openmediavault.org/group__webgui.html
    http://docs.sencha.com/extjs/4.2.0/#!/api
    http://jsfiddle.net/ (Useful for checking errors in your JavaScript code. Apply the ExtJS library from the top left and click JSHint to validate code)

  • Part 2: config.xml and RPC


    In order to store the settings of your plugin a file called config.xml has to modified. The config.xml file contains all parameters that the web GUI holds. The structure is similar to the www folder structure. The configuration file is located in /etc/openmediavault/config.xml. There's also a template located in /usr/share/openmediavault/templates/config.xml.


    First you should make a copy of your config.xml just in case you make an error in your script. Do this by running cp /etc/openmediavault/config.xml /etc/openmediavault/config.xml.backup. If you need to restore the backup run cp /etc/openmediavault/config.xml.backup /etc/openmediavault/config.xml.


    The easiest way to insert your plugin parameters in the configuration file is to make a shell script. Shell scripts are also used in the Debian packages. This means that if you're making an actual plugin there is no point using anything else than a shell script. OpenMediaVault has helper functions that makes it easier to set the initial configuration for a plugin.


    Start by creating a new file called postinst. Insert the following code in to the file.


    This script normally has to be run as root with the following command /bin/sh postinst configure


    You should also make a file called postrm. This is used to clear the entries if the user purges the plugin. This is also useful if you make a mistake. You can delete the entries to the config.xml with the following script.


    Now you can delete your configurations with the following command /bin/sh postrm purge.



    The RPC = Remote Procedure Call


    It should be noted that this guide uses the PSR-2 standard for PHP code. The PSR-2 standard is used by the OpenMediaVault Plugin Developers and the specification can be found here. The official OpenMediaVault code and plugins is written with the guidelines stated here. As usual, write all code so that it looks like only one developer has written the code. The more alike the plugins are written the easier it is to understand how plugins work and contribute to them.


    On the server side there are mulitple files ending with .inc, those are PHP files. The RPC files are the link between the web GUI and config.xml. The RPC files are located in the following folder /usr/share/openmediavault/engined/rpc.


    In the first part of the tutorial we created the RPC file called example.inc. There are a couple of empty functions (getSettings and setSettings) in that file that needs to be completed. Below is the complete code for the RPC file. Check the comments for more information.


    After you have move the new version of the RPC file to the correct folder you have to restart the omv-engined with the following command in the terminal: service openmediavault-engined restart.


    Now you can test it out by modifying your settings in the web interface and saving them. The settings should now stay in the configuration if you click the Save button at the top of the screen. If you have problems with the settings not being stored then double check that your shell script and RPC have same variable names.

  • Part 3: Modules and Shell Scripts


    Modules are used to monitor and execute changes made to your plugins configuration. Modules start and stop services (like SSH, FTP etc.) and they also update the status (running/stopped) of the service in the web interface. If your plugin does not control any services then you can execute the shell scripts from the RPC (see how to execute a shell script from the example module below). As the previous part of the tutorial said, files ending with .inc are actually PHP files. The same applies for modules. Modules are located in the following folder /usr/share/openmediavault/engined/module.


    To create a module start by creating a file called example.inc. Put the following code in the file and check out the comments for more info.


    Put the file in to the module folder /usr/share/openmediavault/engined/module. In order for the module to load, restart omv-engined with service openmediavault-engined restart.


    Generating the configuration with shell scripts


    Shell scripts are the final link for your plugin. They are needed to update the configuration files of the actual software that the plugin controls. When configuration changes are applied, the module executes the shell command omv-mkconf example (this does depend on what your module contains though). Before this works we have to create the shell script example.


    The following script reads the settings from the config.xml and writes to a file. As you can see we are using the helper-functions that OMV provides. Check the helper-functions file for even more functions.


    Put the file in the /usr/share/openmediavault/mkconf directory. Remember to check the file permissions for your shell script. You can use the following command to set the correct permissions on the file chmod 755 example.


    When you apply changes the script is called and it writes the information to the file /tmp/example.conf. If the file doesn't exist it is created by the script.


    This is the last part of the tutorial for OMV plugins. Now you should have a basic understanding about the files and code considering plugin development. How to make a Debian package is not included in this tutorial.


    If you want to know how to implement a feature of the OMV core in to your plugin you can always check the original code. You should know where to look.

    Thank you very much @SVS for this 3 part Guide!

Participate now!

Don’t have an account yet? Register yourself now and be a part of our community!