Tutorial: LiveCode Integration

Even though we are updating Appli collection of low code actions, there are times when you might need features we haven’t yet covered. In these cases, Appli allows you to create custom code using LiveCode language.

The custom code action allows you to write LiveCode scripts that interact with Appli’s variables and elements. You can also access tables using LiveCloud API which is the database technology behind Appli.

In this brief tutorial, we’re going to build a small application to display cool facts from history. We’ll use a LiveCode based script to access a Web API that provides us with facts and then use Appli to present those facts to the user. By the end of this tutorial, you’ll know how to leverage LiveCode integration and how to pass data back and forth between Appli and LiveCode.

An introduction to Web APIs

Much of our day to day digital lives are powered by Web APIs. They provide the infrastructure that allows most web services and apps to work. In essence, they provide a way for an app or service to access the features provided by a server.

For example: When you use Appli to save a database record to the cloud, Appli makes a Web API request to our cloud servers to store the data.

Most Web APIs are powered by the same technologies that make the web work. They are accessible via URLs and the HTTP protocol. The most common format used to exchange data with a server is called JSON.

For this tutorial we’ll access a Web API called On this day which is provided by Wikipedia. This API received a day and a month and returns cool historical facts that happened on the same day and month.

You can see it right now on your web browser. Just navigate to:

https://api.wikimedia.org/feed/v1/wikipedia/en/onthisday/all/04/03 and you’ll see a JSON response that contains historical events that happened on the 3rd of April. The last two numbers there are month and day.

JSON might seem strange if you never seen it before, but it is an easy format for computers to understand. Our sample app will pick the current day and month, make a request to that API, and then show the results to the user.

The On this day API returns a collection of items divided into three categories: selected, births, and deaths. So for any combination of day and month, it will tell us selected historical events, notable births and deaths as well.

Our sample app will only show the selected events. We’ll build it in a way that it shows the first historical event in the returned collection (the API might return more than one event).

Building the user interface

We’ll use two fields, one for the data and another one for the historical fact. We’ll also add a button to open the Wikipedia page with the relevant entry on the user’s default browser. This is how our user interface looks:

• A text element called Date Header.
• A text element called Historical Content.
• A button element called Open Page.

Initial setup

Before we work with LiveCode custom code, we’ll create a mock version of our app just to illustrate how it should work. Later, we’ll replace the mock part of it with the actual request.

The objective is to display a historical fact when the application launches, so our low code actions will go on the OpenScreen event for the screen. That event is triggered as soon as the screen is displayed.

Our script picks the current date and month and set two variables: current_day and current_month. Then it sets the page_link, historical_fact, and date_header variables to empty. These variables are going to be used in the custom code script to return data back to Appli.

Our mock (which is just jargon for fake) code comes afterwards and fills the variables page_link date_header and historical_fact with hardcoded values.

After that we use those variables to insert data into the elements in the user interface.

The button action just launches the browser pointed at the content of page_link.

Switching to play mode, we can see our app working even if the mocked data. Time to make the actual request work and make our app real.

Using the custom code editor

The custom code editor lives in the footer. It is the icon with the clipboard and angle brackets. Click it to open the interface.

You can have as many custom code scripts as you want. You can give them names and then from Appli you can trigger them by the name you set.

Appli will execute the first function found in the custom code script. You can have more than one handler there, but the first one is the one that is executed.

There will be only one function in our script and we’ll call it makeRequest. We’ll use the same name for our custom code. Click the plus icon on the tab bar to add a new script. Name it makeRequest. To rename the custom code, double click on the name on its tab.

This is our LiveCode script:

function makeRequest
  put URL ("https://api.wikimedia.org/feed/v1/wikipedia/en/onthisday/all/" & current_month & "/" & current_day ) into tResponse
  put jsonToArray(tResponse) into tDataA
  
  put tDataA["selected"][1]["text"] into historical_fact
  put tDataA["selected"][1]["year"] into tYear
  put current_day & "/" & current_month & "/" & tYear into date_header
  put tDataA["selected"][1]["pages"][1]["content_urls"]["desktop"]["page"] into page_link
end makeRequest

Explaining LiveCode code is beyond the scope of this documentation, but you can read more about it on their own user guide.

Those among you that know both LiveCode and Appli might be looking funny at the script. Yes, you’re seeing it right, you can access and use Appli’s variables as if they were LiveCode variables. Our backend system takes care of it. You can read from them and write to them and Appli will make sure it works.

Calling the custom code from Appli

So we can replace all that mock section in OpenScreen with a call to code and configure the parameter to the name of our function makeRequest.

If you switch to play mode now, you’ll see real historical facts.

Final words and next steps

LiveCode integration allows you to make more complex apps by leveraging the ease of use of Appli development workflow combined with the powerful features of LiveCode, thus being able to create apps that wouldn’t be possible by just using low code and no code.

By using LiveCloud APIs, you can read and write to tables in Appli. Some next steps you might want to attempt on your own are:

• Can you write the historical facts to a table instead of variables?
• Can you display more than one fact using a layout?

This chapter was last updated on Wed 3 Apr 2024 17:18:13 BST