NEMO plugin development

This page aims to provide guidelines and best practices for developing plugins and contributing to NEMO's codebase

Plugin Development

NEMO is built on top of Django (2.2 at the time of this writing) and thus can be extended with the use of plugins, which are known in Django terms as App. In Django terms, NEMO is the Project to which you can add functionality by writing Apps

Getting started

• follow the instructions on NEMO's Development Setup
• clone or fork NEMO's repository on your computer.
• open the terminal tab within PyCharm (or open your own command line outside of PyCharm)
• create a new app folder for your app using mkdir NEMO/apps/<app_name> where <app_name> is the name of your app
• execute the following command:
  python manage.py startapp <app_name> NEMO/apps/<app_name> --template=resources/conf/app_template.zip --extension py,html
• in your settings.py file, add 'NEMO.apps.<app_name>' in your INSTALLED_APPS setting

That's the minimal configuration to start your own NEMO plugin!!

Plugin URLs

If you name your plugin "NEMO_*" its URLs will be automatically included, and you can simply add a new dashboard icon to take users directly to your plugin pages!

If your plugin name doesn't start with "NEMO_*" then NEMO's code will need to be changed to add the urls. For that you will need a fork of NEMO. In your NEMO forked repository urls.py (NEMO/urls.py) add the following:

if apps.is_installed("NEMO.apps.<app_name>"):
    urlpatterns += [path('<app_path>', include('NEMO.apps.<app_name>.urls'))]

where <app_path> is the path you want to organize your app urls under.

That's it! you can now start NEMO and navigate to /<app_path> and see your first plugin page!

Overriding NEMO's pages and static files

In your app/plugin, you can override NEMO's template files and static files. For example, if you wanted to override nemo.css, you can simply copy the file onto your NEMO/apps/<app_name>/static folder, change anything you want, and it will replace the original file when deployed. Make sure your app is set BEFORE NEMO in your INSTALLED_APPS setting.

The same can be done for any .html files, by replacing them in the templates folder of your app.

for more information, see Overriding templates in Django

Deploying your plugin

Your plugin can be taken out of the apps folder and copied into its own folder.

Plugin example: Dark NEMO!

Here is a step by step guide on how to create a dark NEMO plugin:

Creating the app

• mkdir NEMO/apps/NEMO_dark
• python manage.py startapp NEMO_dark NEMO/apps/NEMO_dark --template=resources/conf/app_template.zip --extension py,html
• copy NEMO's css file into NEMO/apps/NEMO_dark/static
• add the following at the top of the file:

body, .navbar, .navbar-text, .navbar-brand, .navbar-default .navbar-nav > li > a {
    background: black;
    color: white !important;
}

• delete everything else in the NEMO_dark folder: templates, migrations, and all .py files. You should have the following structure:

NEMO_dark/
    static/
        nemo.css
    __init__.py

• add 'NEMO.apps.NEMO_dark', to your INSTALLED_APPS setting in settings.py
• launch NEMO and voilà! NEMO went dark!

Packaging the app/plugin/package

• create a directory outside of NEMO's codebase and name it NEMO_dark
• move the folder NEMO/apps/NEMO_dark into the new NEMO_dark folder
• you should now have the following structure:

NEMO_dark/
    NEMO_dark/
        static/
            nemo.css
        __init__.py

• add a setup.py file with the following content:

from setuptools import setup, find_namespace_packages

setup(
	name='NEMO_dark',
	version='1.0.0',
	packages=find_namespace_packages(),
	include_package_data=True,
)

• add a MANIFEST.in file with the following content:

recursive-include NEMO_dark/static *

• the new folder structure should look like:

NEMO_dark/
    NEMO_dark/
        static/
            nemo.css
        __init__.py
    setup.py
    MANIFEST.in

• if you are using the same python environment for NEMO, install NEMO_dark by using pip install NEMO_dark
• if you are using a virtual environment for NEMO, go to NEMO's root folder and install NEMO_dark by using pip install ../NEMO_dark assuming your virtual environment is setup at the NEMO's root folder, and assuming the folder NEMO_dark is in the same folder as NEMO's root folder
• now that NEMO_dark is installed, make sure it is present in your INSTALLED_APPS setting and before NEMO.

Releasing NEMO_dark

You could now release your NEMO_dark plugin on PyPI, or make it into a dist file and host it somewhere.
Find out more about releasing on PyPI by going to https://pypi.org/
Find out more about packaging by following Django Tutorial

More examples

2 plugin examples can be found within NEMO itself, in the NEMO/apps folder:

• kiosk is a plugin with a completely separate set of pages to be used on tablets with a badge reader, allowing users to enable/disable tools in labs via interlocks.
• area_access is a somewhat similar plugin, meant to also be used on tablets with a badge reader, allowing users to get in and out of areas, unlocking the doors through interlocks.