BETA
My accountGet started
Jul 192021
Total.js Platform
3 min read

Tutorial series - #4 Operations & Tasks

What are Total.js operations and tasks, how to declare them and how to use them properly.

Tutorial series - #4 Operations & Tasks

Operations and Tasks are Total's features which can be used in many different cases. Operation is something like global function in your app but with some extra functionality. Task has multiple smaller functions which can be called separatly from that task or even outside of that task. You can even chain them inside single task to create complex recursive flows.

Operations

Operations are global functions with some extra functionality. They are often used as alternative way to handle client requests or used as wrappers.

Declare:

Operations are usually stored in operations directory inside root of your application. To declare new operation you need to use global function NEWOPERATION(). Function takes two required and four optional arguments:

  • *Name - Operation name.
  • *Handler - Function with $ that will be executed when operation is called .
  • Repeat - Repeat count of this operation.
  • Stop - If operation was successful, don't run next operations (used with multioperation).
  • Bind error - If operation throws error, framework will bind this as response error.
  • Query schema - Used for converting query string values to specific data type. Parser is using CONVERT() on background. Converted values are stored in $.filter object.

To make operation successful use one of these functions $.success(), $.done() or $.callback().

To make operation un-successful (throw error in callback) you can use $.invalid().

*Required

Usage:

After declaring your operation you can simply execute it with OPERATION(). Function has two required and three optional arguments:

  • *Name - Name of operation to run.
  • Value - Value that will be passed to operation which can be accessed through $.value.
  • *Callback - Function will be called after operation is finished. Function has error and response argument.
  • Controller - Field for passing controller instance.

*Required

You can also call operation directly from your ROUTE():

Multioperation:

To run multiple operations in your code you can use global function RUN(). This function has two required and four optional arguments:

RUN() function support multiple declaration syntaxes for operations:

  • *Names - Names of operations to run (see code bellow).
  • Value - Value that will be passed to operation which can be accessed through $.value in each operation.
  • *Callback - Function will be called after last operation is finished. Function has error and response argument.
  • Controller - Field for passing controller instance.
  • Response name - Name of operation

*Required

Response value in your callback function will be an object of all operation's responses. If you want only specific response you can name of that operation as fourth argument:

This code bellow is equivalent of RUN()'s multioperation that is above but its targeted for ROUTE():

After user hits GET /operations/ route, operations first, second and third will be executed and user will get response (or error) from second operation because it has (response).

Tasks

Tasks are very versatile because they can execute infinitely between themself. Tasks are great solution for your simple or complex processes.

Declare:

All tasks are usually stored in tasks directory inside root of your Total.js application. To declare new operation use global function NEWTASK():

  • *Name - Name of new task.
  • *Registration delegate - Function with push argument that is used for adding more "steps" to your task.

*Required

Useful $ methods for tasks:

  • $.end(value) - Ends task and execute callback declared with TASK().
  • $.end2(value) - Return $.end(value) wrapped in function (use this as callback function).
  • $.next(step) - Call next task "step".
  • $.next2(step) - Return $.next(step) wrapped in function (use this as callback function).
  • $.success() and $.invalid() are also valid methods in task builder.

Usage:

To execute your tasks use global function TASK():

  • *Name - Task name and "step" name separated with / ('Add/init' for example).
  • *Callback - Callback function with error and response objects (depends on task's result). Callback is called after executing $.end() method in your task.
  • Instance - Controller or $
  • Value - Data that will be passed to task

*Required