Plugin Creation Tutorial

#Plugin Creation

Creating plugins in ScribeUI is easy, this page should help understand how to create a new functionnality.

Plugin creation requires ScribeUI v0.4 or higher.

###Getting started

Let's create a small Hello World plugins with a few basic functionalities.

All plugins should have their own individual folder in the application/plugins directory. For our plugin, let's create a directory named HelloWorld. Inside that folder, you must create a file named _init_.py

This file will be imported as a module in the ScribeUI application. All the python files you wish to be available in your plugin should be imported in the _init_.py

In our case, next to the _init_.py file, we will create helloworld.py in which all of our code will go. In your _init_.py, add the following line:

from helloworld import *

ScribeUI plugins are in fact Flask Blueprints loaded dynamically when the application is loaded. As such, helloworld.py need to at least import the following modules:

from flask import Flask, Blueprint, render_template, url_for

Then, for ScribeUI to recognize your plugin, you need the following variable, named plugin:

plugin = Blueprint('HelloWorld', __name__, static_folder='static', template_folder='templates')

The static_folder parameter defines the path relative where all your resources will be located. In that example, all images, javascript or css files are located in the application/plugins/myPlugin/static folder. In the same spirit, all the templates will be located in the application/plugins/myPlugin/templates directory.

The different values the Blueprint function can accept are more detailed in the Flask documentation.

At this point, application/plugins/HelloWorld directory should look like this:

HelloWorld/
    __init__.py
    helloworld.py
    static/
    templates/

And at that point, ScribeUI loads your module without any problems. But it doesn't do anything yet.

###Adding some new Javascript and CSS to ScribeUI

First, we will create a simple javascript file that opens a jquery-ui dialog saying "Hello, World!"

In your static folder, create a js directory, in which you will add a helloworld.js file with the following code:

jQuery(function() { $(document).ready(function(){
    var helloDialog = $('<div class="hello-world">Hello, World!</div>');
    $('body').append(helloDialog);
    helloDialog.dialog({                                              
        modal:false
    }).dialog('open');                                                
})});

This code should be pretty straightforward if you are familiar with JQueryUI.

Next, this javascript file should be included in the scribeui main page. To do that, add the following function to your helloworld.py page:

 def getJsFiles():                       
    return url_for('HelloWorld.static',filename='js/helloworld.js')

If you ever need to get several js files added, do it by returning an array, like this: [url_for(...),url_for(...)]

When you edit a python file, the changes probably won't be picked up by mod_wsgi immediately. To see your changes, you should restart apache.

Now, if you refresh ScribeUI, you should see a dialog popping with your hello world message.

If you wish to add some CSS, you do it in a similar way to the javascript, but the function to add to your python file is the following:

 def getCssFiles():
    return url_for('HelloWorld.static',filename='myCssFile.css')

Server-side functions

If you need to execute something server-side, the best way to go is to create a flask page with routing, and calling it with ajax. Flask has some nice advanced functionalities in that regards, for example its jinja2 templating system can be really useful.

We are going to edit our hello world plugin by formatting a bit of json with templates and getting it with javascript.

First, let's create a small json file, named helloworlds.json:

{
    "helloworld": [
        {
            "language": "English",
            "message": "Helloworld"
        },
        {
            "language": "French",
            "message": "Bonjour monde"
        },
        {
            "language": "Spanish",
            "message": "Hola mundo"
        }
    ]
}

Now in the templates directory, create this basic template, called helloworld.html:

<table><tr><th>Language</th><th>Message</th></tr>                     
{% for d in data %}                                                    
    <tr><td>{{ d['language'] }}</td><td>{{ d['message']}}</td></tr>
{% endfor %}                     
</table>                                               

And finally, your python file will look like this:

from flask import Flask, Blueprint, render_template, url_for, current_app
import simplejson

plugin = Blueprint('HelloWorld', __name__, static_folder='static', template_folder='templates')

def getJsFiles():
    return url_for('HelloWorld.static',filename='js/helloworld.js')

@plugin.route('/')
def printHelloWorld():
    data = simplejson.loads('helloworlds.json')
    return render_template('helloworld.html', data=data['helloworld'])

The @plugin.route function indicate the path that the appliation will use to access the function. The render_template function defines which template to render, along with defining the data variable, which is then available to the template.

You should be able to access this page from your browser after restarting apache, the path should look like this:

http://localhost/ScribeUI/plugins/HelloWorld/

And the table should appear. All plugins routes are prefixes with plugins/pluginname.

Now, let's edit our javascript script to show the template in our popup:

jQuery(function() { $(document).ready(function(){
        $.ajax({url:"plugins/HelloWorld/",success:function(result){
                var helloDialog = $('<div class="hello-world">'+result+'</div>');
                $('body').append(helloDialog);
                helloDialog.dialog({
                        modal:false
                }).dialog('open');
        }});
})});