Forming a Response

For the system to work correctly, a server response must be formed using the Response class.

$response = new Response(Response::NORMAL, Response::ACTION_ALERT);

$response->data = array(...);

// Alternative way to add data
$response->addParam("status", false);

$response->addMessage("ALERT MESSAGE");

$response->send();

The first parameter in the constructor is the source from which the request came, the second is the event that needs to be triggered on the frontend.

Response Types

• Response::NORMAL - Returns content as plain text
• Response::JSON - Response will be in JSON format with the header Content-type: application/json
• Response::JSON_JS - Wraps the response in a <script> tag and calls the Jimbo handler
• Response::JSON_IFRAME - Wraps the response in a <script> tag and calls the Jimbo handler (used when sending a request inside an iframe)
• Response::JSON_P - Response will be in the format Jimbo.responseIframe(json) with the header Content-type: text/javascript

More details about Jimbo.js can be found in the Frontend Development documentation.

Action Types

• Response::ACTION_REDIRECT - Will redirect to the URL specified in the $response->url property
• Response::ACTION_ALERT - Displays a notification window with text (text is specified using addMessage, and the title through the $response->title property)
• Response::ACTION_FORM_ERROR - todo...
• Response::ACTION_RELOAD - Reloads the current page
• Response::ACTION_CALLBACK - todo...
• Response::ACTION_NOTIFICATION - Displays a pop-up informational notification
• Response::ACTION_DIALOG - todo...
• Response::ACTION_CONTENT - Returns the text from the $response->content property in its original form
• Response::ACTION_FILE - Returns to the user the file specified in the $response->path property
• Response::ACTION_LAMBDA - Used if a custom response format is needed (for example, reading a CSV file directly into the response)

Jimbo Plugin

If you are using the system plugin Jimbo, then request handler methods will by default have the first parameter Response &$response - this parameter should be used to form the response.

Handler methods in Jimbo start with the prefixes: onDisplay, onUpdate, onAjax, onJson:

public function onAjaxUpdate(Response &$response)
{
    if (empty($_POST['date'])) {
        throw new SystemException("Undefined date.");
    }

    $data = $this->_getPreparedUpdateItemsFromRequest();

    $res = $this->_update($data);

    if ($res) {   
        $msg = __("Data was successfully updated.");
        $response->addNotification($msg);
        $response->setAction(Response::ACTION_RELOAD);
    } else {
        $response->title = __("Are you play with me? :)");
        $response->addMessage("Master please, change something!");
        $response->setAction(Response::ACTION_ALERT);
    }

    return true;
}

When using handler methods, you don't need to execute the command:

$response->send();

Exceptions

When using Jimbo, all exceptions on the backend are sent to the frontend. All exception types inherited from SystemException support a third parameter in the constructor, which can contain either a label or an array that will be passed to the Response.

throw new SystemException(
    "Please select an item to batch remove!", 
    0, 
    "My Lord, Something went wrong."
);

$data = array(
    'action' => Response::ACTION_RELOAD
);

throw new SystemException(
    "Please select an item to batch remove!", 
    0, 
    $data
);

Events and jimbo.js

Common actions with the frontend are described in jimbo.js. The backend sends commands to the frontend using Action. For example, displaying forms, errors, redirects, etc.

When using the Jimbo plugin, responses from the backend are processed automatically. If you need to manually enable server response processing, you can simply pass the server response to the js method:

Jimbo.response(data);

Response::ACTION_FORM_ERROR

If you need to display an error on a form or on a specific field, for example, an incorrect field value:

$response->setAction(Response::ACTION_FORM_ERROR);

$response->fields = array(
    '.css-selector' => 'Error Message'
);

When using Jimbo, you can use the FieldException exception:

throw new FieldException($msg, $selector, $exp->getCode());

Sending a Static File

To send a file, you need to pass the Response::ACTION_FILE action and specify the path in the path attribute.

class DownloadPlugin extends DisplayPlugin
{
    public function onDisplayPlugin(Response &$response, $hash)
    {
        // filePath = ...
        if (!file_exists($filePath)) {
            throw new SystemException("Not found file: ".$filePath);
        }

        $response->setAction(Response::ACTION_FILE);
        $response->path = $filePath;

        return true;
    }

}

$response->setAction(Response::ACTION_FILE);
$response->path = $filePath;
$response->fileName = $realFileName;
$response->contentType = $mimeType;

Lambda

You can execute a post callback through the Response::ACTION_LAMBDA action, especially if you need to call the exit function:

$response->setAction(Response::ACTION_LAMBDA);

$response->lambda = function () use ($fileName, $fields, $columns, $rows) {
    header('Content-Type: text/csv; charset=utf-8');
    header('Content-Disposition: attachment; filename='.$fileName);

    $stream = fopen('php://output', 'w');

    fputcsv($stream, $columns);

    foreach ($rows as $sku => $row) {
        $data = array();

        foreach ($columns as $key => $caption) {
            $data[] = $row[$key];
        }

        fputcsv($stream, $data);
    }

    fclose($stream);
    exit();
};