Using the App API Call

Certain app attributes are used to get information from an app in your website and display that information as a field in the administration. An example scenario could be to associate certain profiles from the Directory app with a page to display their bios automatically on that page.

The attributes that use this functionality are:

Multiple Checkboxes using data from an App API call
Multi-Select Box using data from an App API call
Select Menu using data from an App API call

The data retrieved from the app API call is use to build checkboxes, a multi-select field or a select menu.

An example API call could be to get Gallery items to display on a page. Normally you would use a tag like {{ _api.gallery.itemFilter.templateKey('template-key') }} to make the API call. Making the same call with one of the attribute fields is a little different, but a lot of the steps are the same.

The following example will demonstrate how to set up an API call to return items from the Gallery App and how to use the results in a content layout or content template.

Step 1

First, you have to create a content template for the app that you are going to be making the call to. The API call uses the content template to build an array of data that is then used to build the appropriate checkbox, multi-select or select menu field.

Important: The data for the content template comes from the same variable that you would use in a normal API call.

The goal of the content template is to build an array of data where the key of each array value is the item id and the value is the text to display in the checkbox, multi-select or select menu.

Here is some sample code illustrating how to structure your content template. You use the set_api_attribute_value function to set the item id and text value.

{% for item in items %}
    {% do set_api_attribute_value(item.id, item.itemName) %}
{% endfor %}

In the example above, the items array contains all the gallery items (just like it would for a normal itemFilter API call).

Step 2

Second, create the attribute and give it a name. In this case we're going to select "Multi-Select Box using data from an App API call" for the Attribute type field.

The name of our attribute will be "Gallery Items" and the attribute layout key will be "galleryItems".

You will configure the API call in the API Configuration section. Choose which API you want to call by defining it in the API to call field. The format of the call should be app.apiType. Additionally, do not include any parameters in the field. These will be configured later.

In the example, a call is made to the Item Filter API for the Gallery app. The value entered in the "API to call" field will be:

gallery.itemFilter

After the API to call is defined, it's time to set up the API call parameters within the API call parameters field. At minimum, the field must include the templateKey parameter that refers to the template key of the content template you just created.

In our example the template key of the content template is 'api-item-filter' so the value we'll enter into the API call parameters field will be

templateKey=api-item-filter

Once the attribute field is setup you would assign it to an appropriate attribute group, just like you would with any other field.

Important: If after you create the attribute and then try to add or edit an item in the same app and part of the page is blank, you most likely have an error in your API content template.

Step 3

The third step is to integrate the value(s) chosen from the attribute in your content layouts or content templates.

Like any other attribute, the values chosen within the attribute get saved to the variable that you use in your content layouts and templates. However, values chosen from an attribute that is generated through an API call only save the ID of the item selected. The saved IDs aren't very useful unless they are matched up to something.

To actually get the data for the selected item(s) you would make another API call in your content template.

Following the example, using the numerical IDs of the chosen gallery items, a variable is created using the setApi method that uses the ID to filter the data returned by the API from the gallery. Set the call you want to make using the call parameter, using the same formatting as you used when creating the attribute's API call configuration. The attr parameter contains the attribute (in brackets) that you would like to filter the results by.

{% if galleryItems %}
    {% set items = _api.gallery.itemFilter.attr({'id': galleryItems}) %}
{% endif %}

In this example, the variable items contains the returned items that match the item IDs provided.

The variable now contains all the information about the returned items. You can use this data in your content layouts and templates like you would in any content template in the gallery.

{% if galleryItems %}
    {% set items = _api.gallery.itemFilter.attr({'id': galleryItems}) %}
{% endif %}

{% for item in items %}
    <p><a href="{{ item.url }}">{{ item.itemName }}</a></p>
{% endfor %}

If you need to work with each individual gallery item you could do something like the following code.

{% if galleryItems %}
    {% for itemId in galleryItems %}
        {% set item = _api.gallery.itemFilter.attr('id', itemId) %}
        {% if item %}
            <p><a href="{{ item.url }}">{{ item.itemName }}</a></p>
        {% endif %}
    {% endfor %}
{% endif %}

Other Examples

Below are some other examples of using the API fields.

Getting Categories

Sometimes, when you have a blog or a calendar, you might want to create a Block that lets you display recent posts or upcoming events. You may want to have the option to filter those blog posts or calendar events by a category.

To do that, you'll want to use the categoryNames API. That will get only the category names and the category ID.

For a blog, you will use blog.categoryNames. For the calendar, you'll use calendar.categoryNames. (You can use the same categoryNames API call for any app that uses categories. Just replace "blog" or "calendar" with the app that you're using. For example, for the Members app, you would use members.categoryName, or for the General App, you would use app.categoryNames.)

For the "API to call" field, you'll enter the API call. For example, blog.categoryNames or calendar.categoryNames.

For the "API call parameters" field, you'll need at a minimum the template reference. For example, if your template file is called "api-category-filter.twig" then you'd enter

templateKey=api-category-filter

Below is an example of how that template can be set up. Because we want the option to not select a category, we'll use the set_api_attribute_value function to add an initial select menu option with no category value.

Then, we loop through the categories and use the set_api_attribute_value function to set the category ID and category name for each select menu option.

{% do set_api_attribute_value('', '-- No category filter --') %}
{% for category in categories %}
    {% do set_api_attribute_value(category.id, category.categoryName) %}
{% endfor %}