Getting the linked region for a layout via the API

Developer Experience
1

Hi xibo community,

I just started with the API and this is probably an easy question.
I have created a layout with a given region via the web interface and now I try to retrieve it via the API.

For the layouts there is the “layoutSearch” API which returns a list of “Layout” instances.
The thing is that the “layoutSearch” offers the capability to search for layouts with a given region (via the embed parameter), however the “Layout” class itself does not list the linked region as an attribute.

Further the “Region” class does have a link to its linked layout, so a more cumbersome way would be to list all the regions and connect them internally. However I did not find an API for listing all regions.

So how can I get the region for my layout?

2

Hi and welcome

If you use the embed=regions parameter on the Layout Search call, then all of your regions will be present on a regions property of the returned Layout.

Regions are only ever children of a Layout, so we haven’t modelled a separate call to get those, they can only be retrieved through the Layout.

Does that help?

Thanks,
Dan

3

Hi Dan,

thanks for the welcome :slight_smile:.

I tried your recommendation, but I didn’t get any difference in the results.

Here some details (I generated php code out of your swagger.json file):

This is the code I have:

$api = new Swagger\Client\Api\LayoutApi();
$config->setAccessToken("...");
$layouts = $api->layoutSearch(null, null, null, null, null, null, null, null, null, null, "regions", null);
print_r($layouts[1]); // I got some test layouts and this does have an empty region.

And this is the result of the print_r statement:

Swagger\Client\Model\Layout Object
(
    [container:protected] => Array
        (
            [layout_id] => 4
            [owner_id] => 1
            [campaign_id] => 3
            [parent_id] => 
            [published_status_id] => 2
            [published_status] => Draft
            [published_date] => 
            [background_image_id] => 
            [schema_version] => 3
            [layout] => MyLayout
            [description] => 
            [background_color] => #000
            [created_dt] => 2020-05-05 20:48:33
            [modified_dt] => 2020-05-05 20:50:00
            [status] => 4
            [retired] => 0
            [backgroundz_index] => 0
            [width] => 1920
            [height] => 1080
            [display_order] => 
            [duration] => 0
            [status_message] => Array
            [enable_stat] => 1
            [auto_apply_transitions] => 1
        )
)

So as you can see, there is no additional region property.

I added a debug statement in the ClientApi.php file and this is the URL which is send to my server:
http://localhost/api/layout?embed=regions

Do you have any idea?

4

Hi Dan,

I digged a bit into the code and here what I found:

When I call the url in my browser like this: “http://localhost/api/layout?embed=regions&access token=…”
Then the regions are included.

Further in the generated code, when I there add a printout of the response of the “callAPI” method:
// LayoutAPI.php line 1146

        list($response, $statusCode, $httpHeader) = $this->apiClient->callApi(
            $resourcePath,
            'GET',
            $queryParams,
            $httpBody,
            $headerParams,
            '\Swagger\Client\Model\Layout[]',
            '/layout'
        );
        echo "Response: " .$response;

The regions are in as well.
In the next line there is the deserializer:

$this->apiClient->getSerializer()->deserialize($response, ‘\Swagger\Client\Model\Layout’, $httpHeader);

And in there the region information gets lost and the returned Layout instance does not have the region attached.

So I guess that during the creation of the Model/Layout instance something might not be correct.
I will continue checking this, however any suggestion would be appreciated. :slight_smile:

Potentially the problem is that the Model/Layout class does not have any region attribute, so the deserializer does not know how to map this and discards it?

5

Update:

Hi Dan,

I found the error. It was a missing declaration of the regions attribute in the Model/Layout class.
When I edit the definition of the Layout class in the swagger.json file and regenerate the code, the created Layout class does have the region as attributes listed.

When I do my call using the API:

$layouts = $api->layoutSearch(null, null, null, null, null, null, null, null, null, null, array(“regions”), null);

The resulting layout instance holds the regions:

{
“layoutId”: 1,
“ownerId”: 1,
“campaignId”: 1,
“publishedStatusId”: 2,
“publishedStatus”: “Draft”,
“schemaVersion”: 3,
“layout”: “Default Layout”,
“description”: “”,
“backgroundColor”: “#000000”,
“createdDt”: “2020-04-29 10:17:20”,
“modifiedDt”: “2020-05-07 08:05:52”,
“status”: 1,
“retired”: 0,
“backgroundzIndex”: 0,
“width”: 1920,
“height”: 1080,
“regions”: [
{
“regionId”: 1,
“layoutId”: 1,
“ownerId”: 1,
“name”: “1”,
“width”: 1920,
“height”: 936,
“top”: 0,
“left”: 0,
“zIndex”: 0,
“regionOptions”: ,
“permissions”: ,
“duration”: 15
},
{
“regionId”: 2,
“layoutId”: 1,
“ownerId”: 1,
“name”: “2”,
“width”: 432,
“height”: 129,
“top”: 941,
“left”: 1470,
“zIndex”: 0,
“regionOptions”: ,
“permissions”: ,
“duration”: 10
}
],
“duration”: 15,
“enableStat”: 0,
“autoApplyTransitions”: 0
}

This is the change I did in the swagger.json file (around line 11910):

“regions”: {
“description”: “An array of regions assigned to this Layout”,
“type”: “array”,

"items": {
    "$ref": "#/definitions/Region"
}

},

So you might want to update the swagger.json file at https://xibo.org.uk/manual/swagger.json, too.
Thinking about what else is meant to be embeddable using the layoutSearch API I presume that the other options are missing in the Layout swagger definition, too (e. g. playlists).

Shall I raise an issue in github, or do you want to take care of this?

Cheers,

Trallala :slight_smile:

6

Thank you for the detailed diagnosis there - that is very useful indeed and i’m pleased you solved the issue.

Issue created:

You’re right that we may well have other cases of this were embed is used elsewhere. We will try and do a review of that too!

Thanks!