Introduction to Custom Feeds

Introduction

This tutorial will show you how to create some relatively simple custom feeds to use in Feed Lists and Feed Item Views of your applications.  Custom Feeds can be used to retrieve information from legacy data sources and/or transform data from any source into presentable information.

The ‘Hello World Feed’ examples are here to give you the basic structure of a Custom Feed.

Prerequisites

Before starting to use JavaScript code in your application, you need to install Umajin App Creator and it may be helpful to set up a JavaScript code environment as well.  Try the Visual Studio Code Setup tutorial which will help you to install a code environment and add a JavaScript debugger for when your code isn’t working.

Hello World 1

This example simply creates a very simple feed with four records and only one field (message) which does not use any parameters… it’s literally just a hard-coded JSON formatted string, which is passed to the dynamic component where this feed is applied.

We will assume that you are starting from scratch, if you have already completed the Custom Actions tutorial then you could open the Hello World app you created, use the menu in Umajin App Creator to open VS Code to the right project and skip to Step 3.

  1. Open your code environment.  This is easy if you have set up Visual Studio Code.

    • Open the app project you want to add JavaScript in to.  You could create a new project for this tutorial and call it something like ‘Hello World App’.
    • Go to the File menu in Umajin App Creator.
    • Click the “Open with Visual Studio Code” menu item.  This loads up and opens the Visual Studio Code environment, points it at the /scripts directory in your project’s Resources Folder and adds all the configuration files needed for you to use JavaScript in your app.
  2. Create a new File, it doesn’t matter what you call this file as long as the extension is ‘.js’.  E.g. ‘helloworld.js’
  3. Copy the code below into the text area when the file opens.
  4. Save the file.
  5. Go back to Umajin App Creator and click on a Page (or create a new page).
  6. Create a new Feed List Component and add ‘helloWorldFeed1’ Feed ID under Data Binding.  Follow the help tutorial on ‘Setting up a feed list’ here for more details on how to connect the Master and map the field.
  7. Once you have added a suitable Master and mapped the ‘message’ field in the feed to a Text component, you should have a Feed List that shows all the messages in the feed.

You have now created your first custom feed in Umajin App Creator and can use this sequence of steps to create any feed you like.

Hello World Feed 2

Using the same Hello World project, you can create a new feed; let’s call it ‘helloWorld2’ in VS Code and then map that to the same Feed List above – you will have to add 2 Text Components to the Master and re-map the fields of the Feed to see all the information.

This custom JavaScript creates a somewhat contrived feed that consists of an index, a message (created by the concatenation of a custom feed parameter and the index) and a ‘size’ which is calculated by multiplying the index by 10.  This shows the ability to present calculated and reformatted data in a custom feed, as well as using custom feed parameters with the feed.

You can add any message you like in the ‘Custom Feed Parameter’ property to have it display the message as part of the feed.  For example, if we use the above parameter then the result should be similar to the below image.

Now you could try changing the way the feed is created in JavaScript or go on to the example below.

Local Database Feed Example

Usually a custom feed will be used either where the data needs to come from a REST API call or other data store and then manipulated, or the data calculated for presentation purposes.  In this example we will use a local database that we will create with database schema commands such as cacheDbOpen, cacheDbExec and cacheDbClose.

You will need to put the above action into the On Page Load event of the page where you want to show the information so that the database is able to be created/cleared.

Of course, you could also put it into a splash (or start) page event if you want the data to be persistent for the current session or, if you want the data to persist across sessions, call the setupDatabase function from JavaScript – only if it’s not already created.

Note: This is a demo which has no input cleaning for the parameters.  In a production system, never allow input from a user to be appended directly to an SQL query – this behavior opens the app to SQL Injection attacks. 

Now you can add the feed to a Feed List component as you have in the above tutorials; remember to set a master with enough Text Components to show the data and to map the fields to the components.

Use the Custom Feed Parameter to drive what is displayed in the feed.  “Texas,NAME” will show the records of people from Texas in Name descending (A to Z) order.  The result of this parameter is shown below.

Custom Feeds are incredibly powerful for presentation of data from any source that is available.  Information can be manipulated and reformatted before display in Feed Lists, Animated Feeds and Feed Item Views within your applications.