Sijax is a Python/jQuery library that makes AJAX easy to use in web applications.
Flask-Sijax is available on PyPI and can be installed using easy_install:
or using pip:
pip install flask-sijax
Here’s an example of how Flask-Sijax is typically initialized and configured:
import os from flask import Flask import flask_sijax path = os.path.join('.', os.path.dirname(__file__), 'static/js/sijax/') app = Flask(__name__) app.config['SIJAX_STATIC_PATH'] = path app.config['SIJAX_JSON_URI'] = '/static/js/sijax/json2.js' flask_sijax.Sijax(app)
Flask-Sijax is configured via the standard Flask config API. Here are the available configuration options:
Don’t put anything else in that directory - it should be dedicated to Sijax for hosting the files.
Sijax uses JSON to pass data between the browser and server. This means that browsers either need to support JSON natively or get JSON support from the json2.js file. Such browsers include IE <= 7. If you’ve set a URI to json2.js and Sijax detects that the browser needs to load it, it will do so on demand. The URI could be relative or absolute.
Registering view functions with Flask is usually done using @app.route or @blueprint.route. Functions registered that way cannot provide Sijax functionality, because they cannot be accessed using a POST method by default (and Sijax uses POST requests).
To make a view function capable of handling Sijax requests, make it accessible via POST using @app.route('/url', methods=['GET', 'POST']) or use the @flask_sijax.route helper decorator like this:
# Initialization code for Flask and Flask-Sijax # See above.. # Functions registered with @app.route CANNOT use Sijax @app.route('/') def index(): return 'Index' # Functions registered with @flask_sijax.route can use Sijax @flask_sijax.route(app, '/hello') def hello(): # Every Sijax handler function (like this one) receives at least # one parameter automatically, much like Python passes `self` # to object methods. # The `obj_response` parameter is the function's way of talking # back to the browser def say_hi(obj_response): obj_response.alert('Hi there!') if g.sijax.is_sijax_request: # Sijax request detected - let Sijax handle it g.register_callback('say_hi', say_hi) return g.sijax.process_request() # Regular (non-Sijax request) - render the page template return _render_template()
Let’s assume _render_template() renders the following page:
Clicking on the link will fire a Sijax request (a special jQuery.ajax() request) to the server.
This request is detected on the server by g.sijax.is_sijax_request(), in which case you let Sijax handle the request.
All functions registered using g.sijax.register_callback() (see flask_sijax.Sijax.register_callback()) are exposed for calling from the browser.
Calling g.sijax.process_request() tells Sijax to execute the appropriate (previously registered) function and return the response to the browser.
To learn more on obj_response and what it provides, see sijax.response.BaseResponse.
The sijax.js file is part of the Sijax project, but can be mirrored to a directory of your choosing if you use the SIJAX_STATIC_PATH configuration option (see above). There is no need to download Sijax separately and extract the file from it manually.
Assuming you’ve used the above configuration here’s the HTML markup you need to add to your template:
Sijax.request('function_name', ['argument 1', 150, 'argument 3']);
provided the function has been defined and registered with Sijax on the server-side:
def function_name(obj_response, arg1, arg2, arg3): obj_response.alert('You called the function successfully!') g.sijax.register_callback('function_name', function_name)
To learn more on Sijax.request() see Client side API functions - Sijax.request().
Learn more on how it all fits together from the Examples.
The documentation for Sijax is very exhaustive and even though you’re using the Flask-Sijax extension, which hides some of the details for you, you can still learn a lot from it.
An alternative to flask.Flask.route() or flask.Blueprint.route() that always adds the POST method to the allowed endpoint request methods.
You should use this for all your view functions that would need to use Sijax.
We’re doing this because Sijax uses POST for data passing, which means that every endpoint that wants Sijax support would have to accept POST requests.
Registering functions that would use Sijax should happen like this:
@flask_sijax.route(app, '/') def index(): pass
If you remember to make your view functions accessible via POST like this, you can avoid using this decorator:
@app.route('/', methods=['GET', 'POST']) def index(): pass
Helper class that you’ll use to interact with Sijax.
This class tries to look like sijax.Sijax, although the API differs slightly in order to make things easier for you.
Executes a callback and returns the proper response.
Refer to sijax.Sijax.execute_callback() for more details.
This code is request-specific, be sure to put it on each page that needs to use Sijax.
Tells whether the current request is meant to be handled by Sijax.
Refer to sijax.Sijax.is_sijax_request for more details - this is a direct proxy to it.
Processes the Sijax request and returns the proper response.
Refer to sijax.Sijax.process_request() for more details.
Registers a single callback function.
Refer to sijax.Sijax.register_callback() for more details - this is a direct proxy to it.
Registers a single Comet callback function (see Comet Plugin).
Refer to sijax.plugin.comet.register_comet_callback() for more details - its signature differs slightly.
This method’s signature is the same, except that the first argument that sijax.plugin.comet.register_comet_callback() expects is the Sijax instance, and this method does that automatically, so you don’t have to do it.
Registers all functions from the object as Comet functions (see Comet Plugin).
This makes mass registration of functions a lot easier.
Refer to sijax.plugin.comet.register_comet_object() for more details -ts signature differs slightly.
This method’s signature is the same, except that the first argument that sijax.plugin.comet.register_comet_object() expects is the Sijax instance, and this method does that automatically, so you don’t have to do it.
Registers a new event handler.
Refer to sijax.Sijax.register_event() for more details - this is a direct proxy to it.
Registers all “public” callable attributes of the given object.
The object could be anything (module, class, class instance, etc.)
This makes mass registration of functions a lot easier.
Refer to sijax.Sijax.register_object() for more details - this is a direct proxy to it.
Registers an Upload function (see Upload Plugin) to handle a certain form.
Refer to sijax.plugin.upload.register_upload_callback() for more details.
This method passes some additional arguments to your handler functions - the flask.request.files object.
Your upload handler function’s signature should look like this:
def func(obj_response, files, form_values)
Changes the request URI from the automatically detected one.
The automatically detected URI is the relative URI of the current request, as detected by Flask/Werkzeug.
You can override the detected URI with another one (for the current request only), by using this function.