Package: django-commands
[![PyPI version](https://badge.fury.io/py/django-commands.svg)](https://badge.fury.io/py/django-commands)## WhatDjango-commands is a reusable django app that helps idiot-proof andsimplify the process of writing client-side and server-sidecode for communicating via ajax. A command handler is a replacementfor the standard django view and is intended to deal strictly with ajaxrequests. Requests are actually sent as form data so that files and paramscan be sent together. Params will be json encoded, files will be left as is.## HowBy using a plugin-architecture and auto-discovery of modules acrossyour existing apps, django-commands removes the need to have the samesort of redundant boilerplate validation for views intended to handle ajax requests.Ultimately, it allows operations to be more driven by the businesslogic of the application and less bound to models like what is oftenseen today in CRUD scaffolding demos and the like. Note that it is NOT restful. Insteadit follows a pattern known as RPC (remote procedure call).## WhyAjax gets messy and resource-bound RESTful API routes are not alwaysthe best solution for applications with more complex business logic. Ratherthan struggling through the boilerplate view definition and basic validationof a request, django-commands allows you to focus solely on your business logicbecause you can be sure that anything that reaches your #handle method wasvalid in terms of parameter existence, parameter type, user authentication,and user permissions. It's only up to you to decide if it's valid based on yourbusiness rules.## Goals- Keep the implementation of a command handler simple, explicit, and elegant.- Should be no reason to have to venture outside of the command handler strategy for anyform posts or ajax procedures within an application.- Perform thorough validation of a request on front-end and back-end so thatdevelopers get immediate and telling feedback.- Developers should not have to write boilerplate JavaScript to get access to theircommands. We have enough information to generate a simple JS client.- Allow commands to take arbitrary amount of keys consisting of data ofthe following types and correctly upload them, pass thorough validation,and reach the handler in a directly usable format.- Blob- File- String- Float- Integer- Boolean- Object*- String Array- Float Array- Integer Array- Boolean Array- Object* Array_*For django-commands, object types consist of a standard JavaScript object thatmay combine any of the other types except for Blobs and Files. Currently thereis no specification for expressing nested types requirements, so specifying theobject type only guarantees you'll receive a dictionary in the command handler._## Be Aware- 'user' is a reserved parameter name. The user for a given request will be availableunder self.user inside of a command handler #handle method. Validators for 'user' canbe implemented and will be called appropriately.## Installation### Get the package```bashpip install django-commands```### Register as an installed application```python#settings.pyINSTALLED_APPS = ('commands',)```## Usage### Setup RoutesAdd this one line to your root urls.py. You can change the actual route if you want andthe correct endpoints will still be set inside the client-side code, just don't change thenamespace.```pythonurl(r'^commands/', include('commands.urls', namespace='commands')),```### Create Command HandlerInside your custom apps where you want to use commands, create a file `commands.py`Inside of that file you define your logic for all the commands you want available for that application. I've givena simple example below.```pythonfrom commands.base import *from commands.types import *from commands.decorators import *from .models import *class MyCommandHandler(CommandHandlerBase):# the name of the commandcommand_name = 'SOME_CANONICAL_COMMAND_NAME'# parameters that are required in order to be considered a valid command requestparams = [Param('number', Types.INTEGER),Param('message', Types.STRING),Param('counts', Types.INTEGER_ARRAY)]# request won't even make it to the handle method if they aren't authenticatedauth_required = True# request won't even make it to the handle method if they don't have the permissions listed.permissions = ['superuser']# if all validation based on the static fields passes, then this class is instantiated# and the request and the appropriate data is passed into the command_datadef handle(self, data):instance = MyModel.objects.get(number = data.number)instance.message = data.messageinstance.sum = sum(data.counts)instance.save()return self.success({'responseMessage': 'Woohoo! You win!'})# you can implement @validator decorated methods for some additional validation# prior to instantiation / reaching the #handle method. Here we check that number# is not negative@validator('number', 'The number parameter cannot be negative.')def validate_number(number):return number >= 0```### Include Static FilesJust add the following line to the header of whicheverpages you plan to be using ajax commands. The front-end scriptsassume that you are already using jQuery.```jinja2{% include 'commands/scripts.html' %}```### Use The Commands```JavaScript// this will make the front-end aware of all the available// commands that you've defined in commands.py files across// all of your apps. All available commands (based on user permissions// and authentication status will be populated into the global commands object.// note, this only needs to be done if you don't predefine the available commands (see below with AMD)commands.UpdateDefinition();// this will attempt to post the command to your handler,// but first it will do some checks to make sure you have// the required data parameters and that they are of the// right type. This validation occurs on the front end// and on the backend. This call without data won't work// for the command that we defined.commands.SOME_CANONICAL_COMMAND_NAME.fire();// defining legitimate datavar data = {number: 5, message: 'my message', counts: [5, 6, 7]};// if status==200 on the response (they called return self.success())var successHandler = function(data){alert(data.result.responseMessage); // alerts Woohoo! You Win!}// if status!=200 on the response (they called return self.error() or validation failed)var errorHandler = function(data){alert(data.error);}// making the actual call with data and callbackscommands.SOME_CANONICAL_COMMAND_NAME.fire(data, successHandler, errorHandler);// What if number was negative?errorHandler = function(data){alert(data.errors['number']);}data.number = -1;// This will alert: 'The number parameter cannot be negative.'commands.SOME_CANONICAL_COMMAND_NAME.fire(data, successHandler, errorHandler);```### AMDDjango commands also supports loading via AMD by following the universal module definition pattern. Note that you also preload the available commands on the page by using the ```{% commands %}``` template tag and setting it equal to a variable.In your base template:```jinja2{% load commands %}...<script>var MY_GLOBAL_VARIABLE = {% commands %};</script>```Then, in your requirejs configuration:```javascriptrequire.config({paths: {'commands': 'commands/commands'},//...config: {commands: {availableUrl: '/commands/available/',executionUrl: '/commands/',commands: MY_GLOBAL_VARIABLE.commands}},//...});```