New online demos available.  

Ajax

This non-visual widget is used to send requests to the server and receive responses which can be used in other widgets. For example, it can be used to populate dropdown lists or image galleries, dynamically generate images on the server based on the other widget values, etc.

General information

  • type - ajax

Params

  • url - a URL which is used to accept requests.
  • method - an HTTP method like POST, GET, etc.
  • headers - a dictionary of HTTP headers sent along with the request (an object with the keys used as a header name and a value used as a header value).
  • request - a request body. Typically, you put here a JSON which consists references to other widgets (see examples below).
  • responseType - how to interpret the response received from the server:
    • text - a server returns a raw text string. The Ajax widget does not try to intepret it anyhow.
    • json - a server returns a JSON object. When you refer the response in your config, you can access its properties.
    • blob - a server returns a binary data. It makes sense using it along with some widgets which can work with binary data directly.
    • blob_url - a server returns a binary data, but it is converted to the Blob URL which can be used with HTML markup.
    • status_code - the response contains only the HTTP code.
  • lock - the widget name which should be locked while waiting the response. The editor will show a preloader on this widget (e.g. a static-image).
  • autoCompile - true - the request is sent every time it detects changes in the request (or other params). false - the request is sent only when you call the compile() method explicitly.
  • onSuccess - Function | Array<Function> - a function ("{{#function <expression>}}") or an array of functions which work after the successful request.
  • onError - Function | Array<Function> - a function or an array of functions which should work when the request fails;

Properties

You can use the following properties in the Dynamic Configs:

  • response - a server response, interpreted based on the responseType param. If autoCompile is true, it is automatically updates every time the widget gets a server response.

Methods

You can use the following methods in teh Dynamic Configs:

  • compile() - forces the widgets to "recompile" its params and therefore send a request to the server. It is a way to initiate a request when autoCompile is false.

Code examples

Auto update image

Let's assume you have an endpoint at http://localhost:4242/api/preview, where our PsdWebService is installed (i.e. an API which allows personalizing PSD file using Web API). You send a JSON where you specify what layers should be replaced by what values and it returns a URL to an image you want to set to the StaticImage widget.

For example, you want to re-generate it every time a user changes the option called name.

The config may look like this:

{
   "widgets": [{
       "name": "name",
       "type": "option",
       "params": {
            "type": "list",
            "title": "Name",
            "prompt": "Choose a name",
            "values": [
                { "title": "Jack" },
                { "title": "James" },
                { "title": "John" }
            ]
       }  
    },
    {
       "name": "image-request",
       "type": "ajax",
       "params": {
            "url": "http://localhost:4242/api/preview",
            "method": "POST",
            "lock": "preview",
            "responseType": "json",
            "request": {
                  "greeting": {
                       "type": "text",
                       "text": "Hello {{$['name']._.title}}"
                  }
            }
       }  
   },
   {
       "name": "preview",
       "type": "static-image",
       "params": {
            "imageUrl": "{{$['image-request'].response}}"
       }
   }]
}

For example, a user chooses "Jack". The widget detects the $['name'] widget change and sends the following POST request to http://localhost:4242/api/preview:

{
    "greeting": {
        "type": "text",
        "text": "Hello Jack"
    }
}

The server returns an URL to the image. The $['preview'] widget detects that the response from the server arrives and displays this URL (through the response property).

Generate an image when opening a step

Now, let's assume that you don't want to generate the image every time a user chooses a name. For example, the user selects options on the Step 1, but the image is used on the Step 2. You don't want to overburden the server by generating intermediate results which are never used.

In this scenario, you turn off the auto compilation (autoCompile: false) and manually call the compile() method of the Ajax widget when the user opens the Step 2.

You can do it as follows:

{
   "widgets": [{
       "name": "name",
       "type": "option",
       "params": {
            "type": "list",
            "title": "Name",
            "prompt": "Choose a name",
            "values": [
                { "title": "Jack" },
                { "title": "James" },
                { "title": "John" }
            ]
       }  
    },
    {
       "name": "image-request",
       "type": "ajax",
       "params": {
            "url": "http://localhost:4242/api/preview",
            "method": "POST",
            "lock": "preview",
            "responseType": "json",
            "request": {
                  "greeting": {
                       "type": "text",
                       "text": "Hello {{$['name']._.title}}"
                  }
            }
       }  
   },
   {
       "name": "preview",
       "type": "static-image",
       "params": {
            "imageUrl": "{{$['image-request'].response}}"
       }
   }],
   "steps": [
       {
           "title": "Step 1",
           "toolPanel": { "name": "name" },
           ...
       },
       {
           "title": "Step 2",
           "mainPanel": { "name": "preview" },
           "onActivate": ["{{#function $['pdf-request'].compile()}}"] 
       }
   ]
}