You can connect your blocks to an external API and then use dynamic data to build a custom design. This will work similarly to Repeater Builder, but instead of using the site’s internal data, you can connect to an external site.
Also, the request can be static (will be processed on each page reload) or Dynamic (you can connect it to Form Submit, ajax loading, any element on page or Interaction Layers)
We added two API Connector options: server side and client side.
Server-side API Connector
To use this type, you need to enable Dynamic/Repeater Output in Element block
Then, you can connect any API. To do this, add API data and click on the fetch button. Data will be fetched and stored in a block.
You must be familiar with how API is working, but don’t worry, even if you don’t understand what is HEADER, BODY, method in API Connection, you still can use many API URLs that don’t require any authorization or extra options. For example, all WordPress sites have enabled REST API but default, and you can put next link
https://site.com/wp-json/wp/v2/product?per_page=25Add next part to your site link to get the latest 25 products
/wp-json/wp/v2/product?per_page=25you can also get specific post with ID
/wp-json/wp/v2/posts/25Greenshift automatically converts JSON format into more structured output and retrieves all attached featured images for posts. In this way, you can get items from external WordPress sites and show them on your site.
This block is working as a constructor. You can put anything inside your block, which will be used as repeated items. For example, you want to get the latest posts with images and titles, so your structure will be next. As you see, we wrapped the item in DIV and added an image and text element. This will group each returned item into a separate block.
Your API can also return only a single item (without an array), so you must enable the Single Item option in API Connector if this is the case. Also, if your API returns a complex array, you can get only a specific field for a response; for this, use the Response field (you can also use array values like field[subfield][0][subsub]
To understand which data is returned from your API, you can also use the Test API function; there is a special panel for this.
Note that Tester Data doesn’t support Dynamic placeholders, so test your API without them first.
I recommend designing a single item without dynamic data, then putting it inside the Dynamic block and connecting the API. Anyway, you can always click on the edit Icon in the block to access the constructor of a single item
Now, click on items in a single item area and connect static data to dynamic. For this, enable the dynamic option in each field mapped with API data and select Repeater data as source, then select which field you want to map. All available fields from API will be visible as Repeater Field.
You can have also nested arrays in your data, you also can get them, for this, add another Dynamic or Repeater block inside, also connect it to Repeater source and field where you nested array is saved. You can also use array-like values for repeater field, like field[subfield]
Dynamic placeholders for Server Side API
API Connector supports Dynamic Placeholders in all fields (link, body, header). This means you can have dynamic requests based on your dynamic site options. For example, you can retrieve User meta field {{USER_META:field}} and put this placeholder in body area, this will send request with dynamic data of current user of your site.
Placeholders have self-explanatory names. But there are a few specific ones; please continue to read.
Dynamic Ajax Loading
By default, API Connector requests endpoints on page loading, but you can enable the Ajax option. In this case, it will be loaded on specific interactions.
For example, you can use it on Form Submit. There are special placeholders to use dynamic requests.
Form Submit trigger
You can add a form with the Form Element block, but any other form plugin will work also.
So, enable the Form trigger. I used the selector “.submitform” which means I will use the form with the class “submitform”
Now, add Form Element on the page and add class submitform to it. Add Input with name “name” and id “name”. Now, in your API fields, you can use placeholder {{FORM:name|test}}
This will dynamically add the value from Input “name” to your API request. If this field is not available, it will use fallback “text.” In this way, you can create filters or dynamic API requests on your site based on user input in the form.
Dynamic AJAX loading and Interaction Layers
You can also enable the Custom Interaction trigger for more control over triggers.
Copy provided ID. Now, use the Interaction layer and select any trigger. Add “Dynamic API Call” as an action and put the copied ID. Now, the API call will be controlled by your custom trigger.
For example, you can call an external API request when the user clicks a button or reaches the scroll position.
Another prevalent scenario is to create intervals with API calls. For this, we added a Loop trigger in interaction layers. Use it and add an interval and the number of calls. I recommend adding an interval bigger than 4-5 seconds so the API can return data before the subsequent call runs.
API connector also stores the index of calls on the page. You can use it with a combination with placeholder {{INCREMENT:1}}
For example, you can use the offset parameter in the WordPress REST API link. Like
https://woocommerce.greenshiftwp.com/wp-json/wp/v2/product?per_page=1&offset=1Now, we can modify it to next.
https://woocommerce.greenshiftwp.com/wp-json/wp/v2/product?per_page=1&offset={{INCREMENT:1}}Now, on each new sequential call on the page, the offset parameter will increase by 1. So, on the first loading, it will be offset=0, on the second offset=1, etc.
This can be used to get dynamic data individually instead of all together.
Another functional placeholder can be {{RANDOM:0-100}}, which means that a random value between 0 and 100 will be used for each call. Or {{RANDOM:blue|grey|yellow}}, which means one of the provided values will be used on each call.
Custom Preloader and animation for dynamically added items
You can use also custom preloader. For this, create any block and add class to it. Then, use this class in custom selector option
On loading state, this selector will have .active class. You can use it to add animation to preloader. For this, put any block inside custom loader block. Enable Animation in it and use option to activate animation on .active class
A similar approach can be used for newly added items for result output. You can use class .result-loaded with animation presets
Also, the container where results are added has class .loading – while loading and .loaded and .active – after adding results. You can use them to add extra conditions.
Pagination in ajax responses
You can also have pagination when you use dynamic ajax. For this, create a block and add a unique class to it. Then, add this class in option of Connector
Then put any button inside this container and add Animation preset with .active class trigger the same as we did for custom preloader. Please, note that this feature will work if your API pagination is using “page” parameter to get page number
WordPress Authentification
For specific operations, you may need to have WP authentication, this is where usually many fails, because there is no good documentation how it works. One day, it took me also few hours to understand how it works, so I want to save your time.
When you do WP API connections that require authentications, like Submiting Post to database, you must use WordPress App Password. It’s not the same as your real password. You must create Application Password in admin panel in Profile page
Once you added and copied this password, you must encode the pair to use it in the Authentification header. For this, put your details in this way
UserName:Password
and encode this on site. After encoding, you will get a long piece of text. This text you must use in the Head part of API in this format
This field has Autocomplete, so select key as “Authorization” and the Value as “Basic yourEncodedCode”
Where you must put the code that you got from the previous step. Don’t forget to put space between code and Basic
Client Side API Connector
The server side uses WordPress’s Rest API and does all the jobs on your server. It can also use dynamic data stored on your site.
The client-side API uses only the Javascript fetch function and performs tasks only in the browser. It has no connection to the WordPress database. At the same time, as it’s a 100% front-end solution, it has more options to interact with elements on the page.
Attention. Client-side APIs are always public, so users can see your API keys. Use them only for public APIs or on restricted parts of your site. If you need to hide all processing and keys, the Server-Side type is better.
Similar to Server Side API, you can also create a custom design for retrieved results, but Selector Maping does this. For this, you add a special, unique class to each item that you want to connect to the results and provide a key to the results that will be mapped. Let’s dive into the details.
The Client Side works from Interaction Layers, so you must add any block with interaction layers. For example, I added a Form element with two inputs and a Button. When the button is clicked, I want to take the value from my inputs and send it to the request.
I added a special class “search-input-api” to the first input and “color-select-api” to select. Now, I added an interaction layer to the button and enabled click as a trigger and API Connector as an action.
See that I used {{VALUE:.search-input-api}} as part of URL. It’s a dynamic placeholder that makes a dynamic replacement. In this case, it’s replaced by a value from the .search-input-API field on the frontend. Click on “Dynamic Placeholders” link in Body field to see list of available placeholders, you can use them in any of field. Let’s review them
Dynamic Placeholders for Client Side API
{{TEXT:.selector}} – will use text from selector. Difference from VALUE is that VALUE will get value from input field, while TEXT can be used to get any text value from any element on page
{{VALUE:.selector}} – works only for form element inputs
{{COOKIE:cookie_name}} – takes cookie by key
{{STORAGE:storage_name}} takes storage value by key
{{ATTR:attribute_name|selector}} – can take special attribute value instead of value. For example, you have <div data-src=”https://link.com” class=”mylink”>My link</a>. And you want to get data-src value. Use {{ATTR:data-src|.mylink}}
{{SESSION_ID}} – on each page loading, API connector can have special ID that you can use for API. This is required, for example, for chat-like API requests when you need ongoing requests that is stored as one chat
{{FORMDATA:.selector}} – this will use FormData API so practically, you can send all fields of specific form to your API if it’s supporting FormData
Result template for Client Side API
With Interaction Layers, you can send requests and design their returned values. For this, create two blocks, it is better to use DIV and add classes. One will be a block where we store our output results design, and one will be used as a container where we will send results to show them after retrieval.
So, on block where we store results design, it should be on page but must be hidden. Script will use this block as source to build constructor for results. Add special class in block so it will be hidden on frontend
Now, put any kind of static blocks inside it and style them as you want. Values that you use will also be used as Fallback values in case the API request doesn’t have value for a specific key. Put unique classes to all elements that you plan to have dynamic value replacement from API
For Result Container, you can use any block, there is no special requirement for this. It will be used to show results, so put it somewhere near your button.
Put both selectors to proper fields in Connector API.
Next part is to map all our fields to API results. For this, you must add selector of field that you want to map and key from API. Value from API will replace value of element. If it’s link, then it will be added to href attribute. If it’s image or video, then it will be added to src attribute. For other scenarios, text value will be replaced
There is also Test API panel, so test what is returned in your API (do this without placeholders first). When API is tested, you can also see them in Auto Complete when you select key. You can also use array like values. For example, data is
{urls:
{
"small": ...,
"big": ...
}
}as you see, it’s not saved directly in “URLs” key. But you can use urls[small] to retrieve such values.
Custom Loader
Client Side doesn’t have default loader icon, so you need to add it if you want to show some animation when API is loading. For this create any block, add unique class. Use this class in custom loader option. Put anything you want inside. For example, rotating icon. When API is loaded, this block will have class “.active”. You can use Animation preset to show block on .active class as explained before.
Animation for result appearance
As well as in Server Side API, when result container is loading, it has class loading, when it’s ready, it has class .active and .loaded. So, you can use Animation presets and on .active class condition
Interactions in results
You can add also interaction layers inside Result blocks. They will be executed after results are ready on page
Hook for developers
You can use also special JS hook for Client Side API
document.addEventListener("GSPB_API_RESPONSE", (event) => {
const { resultElem, responseData } = event.detail;
console.log("Received API response:", responseData);
console.log("Result Element:", resultElem);
});Chat Type and Streaming responses
When you use the Client Side, you can also enable Chat mode and streaming. Chat mode allows you to send ongoing requests related to previous requests. It’s usually used in Chats when you need to send previous discussions to the AI model so the agent can understand the context.
I will explain an example of building chat with OPEN AI API.
If you check their documentation you will see that you need to send an object with roles, something like this.
"messages": [
{
"role": "developer",
"content": "You are a helpful assistant."
},
{
"role": "user",
"content": "Hello!"
},
{
"role": "assistant",
"content": "How are you?"
}
]So, on each user input, you need to attach new.
{
"role": "user",
"content": "Hello!"
},Then, get a response from the model, and next time, attach this response to chat with the role “assistant”.
Quite a complex task, but Greenshift will do it for you
So, at first, you need to add initial data for the body, it will be
{
"model": "gpt-4o",
"messages": [
{
"role": "system",
"content": [
{
"type": "text",
"text": "You are a helpful assistant that can answer questions and help with tasks."
}
]
}
]
}Here, we define the messages object and add the initial system role.
We need to provide a key from the body where ongoing inputs will be stored. It’s our Append Field because each new user request will add a new item in this key. In our case, it’s “messages”
Now, I need to provide a User Message JSON format
{
"role": "user",
"content": [
{
"type": "text",
"text": "{{VALUE:.search-input-api}}"
}
]
}See that I used {{VALUE:search-input-api}} It’s a special placeholder that shows the plugin to get value from .search-input-api element from the page and use its value to add the object to messages
I will need to get a response from the system and save it for assistant messages. So I used
{
"role": "assistant",
"content": [
{
"type": "text",
"text": "{{RESPONSE}}"
}
]
}{{RESPONSE}} is a placeholder that will be dynamically replaced by the response data of Assistant from a previous API call. You also need to add a specific field where the Assistant response text is saved because usually, the Response has many keys. In open AI, the response is added in the next format
See, it’s too much extra data here, but we need to get value only from the first item in “choices”, so our field is choices[0][message]
That’s all. But we need to use also Interaction layers to improve Chat style. For example, we need on each click of Sending button, we add user input value to our chat container. Hopefully, Interaction Layer has everything for this kind of functions. You can download everything from our library and use as base for your custom chats.
Streaming
Your responses can also be streamed. Streaming allows you to get results from the server immediately, chunk by chunk, and show them on the page. In this way, the user does not need to wait for the full answer to show up on the page because the results will be added faster and typed on the page. Usually, chats use streaming.
You don’t need to worry how it’s made, Greenshift will take care of everything for you.
When you use custom response template, each element that you add for mapping will have “loading” class before getting data and “loaded”, “active” class if value will be retrieved while streaming. You can use it to show or hide specific items depending on fact if there is data in the streaming response.
API Presets
There are few integrated API presets, that you can use for practical tasks.
Click on API Presets link for this.
Currently we added two ready presets:
WordPress Site Latest Items
This is for easier generation of WordPress REST link. Put there any WordPress site and select post type to show. Now, you can get items from external site
Google Sheet/CSV
You can use Google Sheet link or csv link as source. Plugin will automatically convert data to be API source.
It’s possible to convert each row as item and each column as item
Examples
Please check our library for three examples of API Connector