AJAX

The Framework itself uses AJAX for many of its admin operations, some of which are generic so usable by other pages that require Site/Admin privileges. You can also add your own operations using the mechanisms described below.

Invoking an AJAX operation

AJAX operations are all invoked using RESTful URLS of the form

/ajax/operation/param1/param2…

where operation identifies the AJAX operation you want carried out using the parameters provided. Data can also be passed in using a form if you are doing a POST or PUT/PATCH: using the full range of HTTP operations is much easier with AJAX.

Adding your own operation

You add new AJAX operations by creating a class in the /class/ajax directory. The class should be mamed with the name of the operation that you are creating. For example if you want an AJAX operation /ajax/insert/… then you create a class called Insert. There is a template for these classes in the file sample.txt in the directory.

    class Sample extends \Framework\Ajax\Ajax
    {
/**
 * @var array If you want to use the permission checking functions. If you just want to control access
 *            then just put the list of contextname/rolename pairs in the result of requires.
 */
         private static $permissions = [];
/**
 * Return permission requirements. The version in the base class requires logins and adds nothing else.
 * If that is what you need then you can remove this method. This function is called from the base
 * class constructor when it does some permission checking.
 *
 * @return array
 */
        public function requires()
        {
            return [FALSE, [/* [contextname/rolename],... */]]; // see below
        }
/**
 * Carry out SAMPLE operation
 *
 * @return void
 */
        final public function handle() : void
        {
            /* Your code goes here */
        }
    }
            

Your AJAX function will usually generate some output such as JSON or a simple string, or else it may terminate with an HTTP error code. Twig is not enabled when handling AJAX as you are not normally generating whole pages. (It is possible to enable it if you need it, but this is unusual)

Useful Framework functions are $context->web()->sendJSON($result) and $context->web()->sendstring($value, $mime, $code)

When you invoke your function, the AJAX handler will find your class and invoke the handle method. The base class (class/framework/ajax/ajax.php provides you with some useful functions and a protcted variable that references the Context object: use $this->context

The base class constructor calls the function requires to set up access control checking for your operation. The result is an array on the folloing format

    [
        TRUE/FALSE, // a boolean value indicating if the user must be logged to use this operation
        [
            ['ContextName', 'RoleName'], // a (possibly empty) array of Roles that a logged in
            ....                         // user must have in order to invoke this operation.
        ]
    ]
            

If the ContextName/RoleName array has more than one element then the user must have all the Roles specified. If you wish to allow any of a set then you need to replace the ['ContextName', 'RoleName'], element with:

    [
        ['ContextName', 'RoleName'],
        ....
    ]
            

That is, you nest another array of pairs inside instead of the pair of strings. TBH, it is much easier to introduce a new Role that supports this function than it is to use this nested array approach! (But you can if you want to…)

Framework AJAX operations

The Framework has several AJAX operations that it uses itself, some of which are quite general purpose. Note that the majority of them by default require you to be logged in as a Site Administrator before they are available to you. You can see the code for these operations in the directory class/framework/ajax

If you want to make use of these Ajax operations then you can give permissions to other users using settings that are documented in class/support/ajax.php . Not all operations are available at the moment though. It is important that you think carefully about any potential security holes you may open when using these settings - a wrong setting can allow anyone to alter your your database.

bean

This allows various operations to be carried out on beans. It supports a variety of HTTP methods, and, if it exists, it calls the method canAJaxBean(Context $context, string $method) on the bean. This allows for checks to ensure that the operation is permitted, e.g. making sure only owners can delete beans or similar. You can see the code for this function at class/framework/ajax/bean.php .

POST

This creates a new bean of the specified type. It calls the static method add(Context $context) which should be defined in the model for the bean and return the new bean. If there is no such method then it throws a BadOperation exception;

            /ajax/bean/{bean name}
            

PUT/PATCH

This lets you update an individual field of a bean. You can specify which fields can be manipulated in the permission string in class/support/ajax.php. You cannot change the id field of a bean.

            /ajax/bean/{beanname}/{bean id}/{field name}
            

and the new value for the field is passed using a data field called value — this allows for larger amounts of data than can be contained in a URL.

DELETE

This deletes the identified bean. If it exists, it also calls the method delete() on the bean before it deletes it. This allows for any cleanup that you may wish to do.

            /ajax/bean/{bean name}/{bean id}