Getting started

Welcome to Kelp. We’ll be building a simple app, and by doing so learn the fundamentals of using Kelp.

For example, maybe you want to build a simple stock screening app. You will need a list of stocks. We can use free API to pull a list S&P 500 companies. You can easily substitute it later with your own portfolio of stocks by pulling it from Google Spreadsheets for example. You will also need to connect to a market data provider to retrieve current price and other indicators for the stocks in your list. And you will need historical data to display on a chart. We can use IEX Cloud free tier API for that. Lets get started!

Create new app#

Go to https://public.kelp.app/ and login to Kelp. Please Sign Up if you don't have an account yet.

When you login the first page you see is My Apps. This is where your private apps are stored. Click New App button at the top to create your first app.

note

When starting with a new app you're immediately switched to the developer mode. There are also design and user modes. You can easily switch between them by using mode buttons on the top right side of the screen. Learn more about navigating Kelp User Interface.

Connect to data source#

Right-click anywhere on the canvas to open Components Library dialog. Look up HTTP component and place it on the canvas. HTTP Component allows you to make requests to any RESTful API.

We will be getting our list of stocks from here: https://datahub.io/core/s-and-p-500-companies/. We just need to provide URL string to the url input port of the HTTP component. Again, right click on the canvas, lookup String component, and add it to the app schema.

tip

String component is a constant of type string. It will emit its contents as soon as its initialized. Constants are typically the origin of events in Kelp app.

To set the value of the String constant open component's settings dialog by pressing space bar on the selected String node. Alternatively, you can simply paste the string anywhere on the canvas. Kelp will recognize you want to add a string and place a new String component on the canvas for you. Sweet!

Use this direct link to the JSON file:

https://datahub.io/core/s-and-p-500-companies/r/0.json

Next, we need a way to display the results of our HTTP request. The simplest way to see the output of any Kelp component is through the Log widget. Log widget displays anything it receives on its input as is without any changes. Look up and add Log widget.

Note: Widgets in Kelp are similar to components but with an ability to render the content in their unique way. You can place them on the screen layout in the design mode and create the user interface of your app.

Now simply connect output port of the String component to url port of the HTTP component. And response port of the HTTP component to the data port of the Log widget. Click the Restart button (at the right hand side of the top bar) to run the app.

Great job! We can now use the retrieved dataset to get the stock symbols. But first, lets display it on the app screen in a more user friendly way.

Move Log widget out of the way by dragging it to the side. No need to disconnect it. Add Table widget from the library and connect it to the response port of the HTTP component.

Transform data#

If you now Restart the app and open Preview dialog of the Table widget (select it and click space bar), you will see an empty table.

Why? The reason is that the Table widget receives the data in a format it doesn't understand. The Table widget expects the data as an array of objects.

[    {        "Name": "3M Company",        "Sector": "Industrials",        "Symbol": "MMM"    },    {        "Name": "A.O. Smith Corp",        "Sector": "Industrials",        "Symbol": "AOS"    }]

But HTTP component returns the data in the following format:

{    "data": [        {            "Name": "3M Company",            "Sector": "Industrials",            "Symbol": "MMM"        },        // ...        {            "Name": "Zoetis",            "Sector": "Health Care",            "Symbol": "ZTS"        }    ],    "meta": {        "request": {            "url": "https://datahub.io/core/s-and-p-500-companies/r/0.json"        },        "response": {            "status": 200,            "statusText": "OK",            "headers": {                "content-type": "application/json",                "last-modified": "Sun, 23 Aug 2020 01:05:42 GMT"            }        }    }}

We need to extract the value of the data property. To do that Kelp supports Data Transformations on the connections between the component ports.

tip

Kelp supports several query languages for data transformations. Choose the one that is more appropriate for the task. Learn more about Data Transformations and the supported query languages.

Click on the connection between HTTP component and Table widget and press the space bar to open the Transformation dialog. Select JMESpath query language and enter data in the middle text area. This query will extract and pass on the value of data path from all the events passing through this connection. Lets agree that all transformations in this guide will be using JMESpath query language unless explicitly pointed otherwise.

Hit Ok. Now you can Restart the app and open the preview dialog of the Table widget. You should see a nicely formatted list of S&P 500 companies.

Design layout#

To create the end user view we need to design the layout of the app by arranging our widgets on it. To open the design mode, click on the Design Mode button at the top of the development toolbar, and then click on the Widgets Panel button to open up a panel with a list of all widgets initialized in our app. Drag and drop the Table widget and position it on the screen.

Switch to the user mode to preview the final result.

Congratulations! You now have passed all the major stages of making an app in Kelp. Next, we will make it bit more interactive and show you how to combine data from multiple data sources.

Connect to secured data source#

We will be using IEX Cloud API to retrieve additional company information. IEX Cloud is a great source of the essential financial data, and offers a free access to a sandbox style environment. Before you proceed, register at https://iexcloud.io/. Make sure you turn on the "Sandbox Testing" mode, and grab your free API Key.

To be able to connect to a secured IEX Cloud API resource you need to configure a Secured Connection record in your Kelp account, and store there your IEX Cloud publishable token. This record will be used by Kelp to allow only your Kelp app to connect to the IEX Cloud API and only when you using your app. No other user or app will have access to it.

Quick steps to create new Secured Connection:

Go to Home > Settings > Connections page.
Click Add Connection button, then Create New and select API Key authentication scheme.
Fill in the following details and Submit the form.

Connection name: My IEX Cloud sandboxSchema: API KeyKey value: <*your IEX Cloud publishable token*>Placement: queryParam name: tokenParam value: {token}

Go back to your app. Add another HTTP component with the following configuration:

Path parameter processing: Path parameters
Request method: GET
Leave other fields with default values.

Connect new String component to url port with the following value. This endpoint returns the results anytime of the day (see Previous Day Price endpoint documentation for more details).

https://sandbox.iexapis.com/stable/stock/{symbol}/previous

As you can see {symbol} is a parameter inside URL path. This parameter will be replaced with the value that HTTP component is expecting on its params port. We need to send to this port the symbol of the selected company in our Table widget. To test it add a temporary JSON constant with the following value and connect it to the params port of the HTTP component:

{ "symbol": "MMM" }

Before making the request we need to provide credentials details. Add Credentials Configuration component and configure it to use your IEX Cloud connection you set up earlier.

Restart the app and check the response output. If you generated IEX Cloud keys and configured Secured Connection correctly you should see the response from the endpoint.

Add interaction#

Let’s make this app interactive, by selecting a row in the table and displaying more details for the corresponding company.

Remove temporary JSON constant and connect Table selection output to the params port of the HTTP component with the following JMESpath transformation:

{symbol: [0].Symbol}

On the other side of the HTTP component add Metric Card widget, connect its data port to the response port of the HTTP component, and set the following transformation:

data |[    {       name: 'Latest price',       value: close    },    {       name: 'Volume',       value: volume    },    {       name: 'Open price',       value: open    },    {       name: 'Intraday high',       value: high    },    {       name: 'Intraday low',       value: low    }  ]

This transformation generates a list of metrics to display on Metric Card widget by filling in the values from the response of the HTTP request. See Metric Card widget for more details

Restart the app, then open Table widget preview dialog and click on any row to make a selection. You should see the Metric Card widget updated with details.

Add data visualization#

Following the same pattern we will retrieve the historical prices data for the selected stock symbol and render it on a chart.

Add another HTTP component and point it to the URL of the Historical Prices endpoint:

https://sandbox.iexapis.com/stable/stock/{symbol}/chart/{range}

Connect Table output to the params port with the following transformation.

{ symbol: [0].Symbol, range: '6m' }

Notice that we use 2 parameters to substitute in the URL path: symbol and range. You can play with different values of the range parameter to achieve the desired results.

You can reuse the same Credentials Configuration component by simple connecting its output to the credentials port of this HTTP component.

To add the chart we will be using Vega Chart widget. And for simplicity we will specify the configuration of our chart using Vega-Lite specification. We will need Vega-Lite Adapter component to convert Vega-Lite spec.

tip

VEGA and its lighter version VEGA-LITE are declarative languages for creating beautiful charts and data visualizations. Learn more about VEGA at https://vega.github.io/vega/

Connect the response output of HTTP component to the data input of the Vega-Lite Adapter component. Dont forget to apply transformation on the connection between them! In this case use data as query to unwrap the incoming array.

Use the following Vega-Lite chart configuration to pass to the vega-lite-spec port of the Vega-Lite Adapter component as JSON constant.

{    "$schema": "https://vega.github.io/schema/vega-lite/v4.json",    "description": "stock price over time.",    "mark": "line",    "encoding": {        "x": {            "field": "date",            "type": "temporal"        },        "y": {            "field": "close",            "type": "quantitative"        }    }}

Now lets finish by switching to the Design mode and updating the final layout of our app. Feel free to experiment with the layout anyway you like it.

When you done, switch to user mode and test your app. Once its ready for prime time, click the Share button at the top of the screen to publish it and share with your team to use in a production mode.

That's it! You've built a quick app that pulls the data from two sources, visualizing it and enables a simple interaction. Now you can go and build your own apps!

Need help?#

If you need help or have any questions join our Kelp community on Slack, or reach out to our support team.