Docs

Overview

Cloud Canal is a low-code framework that helps you turn static sites into fully functional web apps. It's not a site builder; instead, it serves as the "glue" between your components. It's also platform agnostic, meaning that it works with custom-coded stuff just as well as it works with site builders and other tools.

Getting started with Cloud Canal is super simple. This guide assumes that you already have a front end and back end built. What if you don't? Check out the Popular Tools section for some no-code frameworks to get you started. In particular, we recommend Webflow for front end development and Bubble if you need to build an API.

If you don't have a domain, you can get one at a registrar like Namecheap or Google Domains.

Signing Up

If you haven't done so already, the first step to using Cloud Canal is signing up (naturally). If you already have an account, feel free to skip to the next section. If not, navigate to the home page and select "Register" from the navbar. After filling in your info, you'll be redirected to the Domains page.

Registering a Domain

After you've signed up, you can begin registering your domains with Cloud Canal. Only API calls from registered domains are processed by the framework. This is to ensure that only domains that you've explicitly authorized have access to your connectors and thus your data. We'll discuss what a connector is in the next section.

Begin by navigating to the Domains page. Clicking on the "+" button will bring up the modal to add a new domain. If you don't currently have any domains registered, then this modal will appear automatically.

Enter the name of your domain without any subdomain. For example, enter "example.com" and NOT "www.example.com". Please note that Cloud Canal will only work with sites that use the HTTPS protocol for security purposes.

Creating a Connector

A connector is the link between your front end and any single API. It primarily consists of endpoints, and allows you to manage headers, query parameters, and cookies for those endpoints. Any of your registered domains can use one or more connectors you've set up.

Begin by navigating to the My Connectors page and hitting the "+" button. The page will refresh, showing a new connector with a generated ID as a name. Click "VIEW" next to it.

General

You'll be taken to the details page for the new connector. Here, you can rename the connector to something a little more memorable by clicking on its current name at the top of the screen.

You'll also have to assign a URL; this will act as the base URL for all the endpoint calls using this connector.

Endpoints

Before diving into the other subheadings on the page, lets skip ahead to the Endpoints section. Begin by hitting the "+" button next to "Endpoints". This will add a new endpoint to the connector.

You can choose the method of the request for the endpoint (GET, POST, etc.). The URL needs to be specified as well, and is combined with the base URL for the connector when making a call. For example, if you want to make a call to "https://www.vehicles.com/cars" and "https://www.vehicles.com/boats", you would set the connector's base URL to "https://www.vehicles.com/" and create two endpoints with the URLs as "cars" and "boats", respectively.

Note that if you'd like to make two different types of calls to the same endpoint URL, like a GET and a POST request, just add two separate endpoints with the same URL.

After adding one or more endpoints and saving the connector, Cloud Canal will generate unique IDs for them. You can optionally choose to prefix your IDs whenever you use them to make it more obvious which endpoint they represent. Only the value after the last underscore is important in identifying the endpoint. As an example, the two endpoint IDs below would reference the same endpoint.

anything_1570299745920x125511730199483700
1570299745920x125511730199483700

Headers

You can add headers to any of your endpoints by clicking the "+" button next to the "Headers" section. Begin by selecting which endpoint the header will apply to from the dropdown, or "ALL" if it should always be applied (such as an authorization header). Set the key and value. For the value, you can use parameters (except for functions).

Query Parameters

Query parameters follow exactly the same rules as headers above, but are instead appended to final URL used for the call. For example, a base URL of "https://www.example.com/", combined with an endpoint of "things/objects" and a query parameter of "id = 12345" will result in in a call being made to "https://www.example.com/things/objects?id=12345".

Cookies

Cookies follow exactly the same rules as headers and query parameters above, but are also specified as "Set" or "Clear". These are not submitted with any calls; instead, after a call to a corresponding endpoint is made, Cloud Canal will either set or clear a cookie in your user's browser. This can be extremely useful as a sort of "variable" in your web app.

One common use case is with authentication. If you had an endpoint for logging in, you could set a cookie to store the API token you receive back from the server in a cookie using a value parameter.

Loading the Script

On your website, add the script tag below to the head of each page you'd like to use a connector on. If your site doesn't already use jQuery, you'll have to reference it first.

<script src="https://cdnjs.cloudflare.com/ajax/libs/jquery/3.4.1/jquery.min.js"></script>
<script src="https://cdn.jsdelivr.net/gh/CloudCanal/CloudCanal@1/CloudCanal.min.js"></script>

If you're using a site builder for your front end, it may already load jQuery for you. Webflow does this automatically, so you'll actually have to include the Cloud Canal script in the "Footer Code" instead. Otherwise, your site won't work as intended.

Adding Data Attributes

Cloud Canal uses data attributes to link elements on your website to your connectors. The remainder of the documentation after the "Getting Started" section is devoted to the details, but in general, attributes are associated with an event and trigger an action. Actions can include parameters such as values derived from cookies or query strings. Some additional data attributes are used for things such as arrays or even payment integration with Stripe.

If you have access to your site's code, then applying these attributes is straightforward. If you're using a site builder, then odds are there is some way of applying custom attributes to elements on the page you're designing. In Webflow, these can be found on the "Element Settings" tab on the right side of the designer, denoted with a cog icon.

If you have access to your site's code, then applying these attributes is straightforward. If you're using a site builder, then odds are there is some way of applying custom attributes to elements on the page you're designing. In Webflow, these can be found on the "Element Settings" tab on the right side of the designer, denoted with a cog icon.

Some attributes, most notably HTTP events and arrays, will need to be paired with an additional endpoint attribute so that Cloud Canal knows which endpoint they correspond with. Forms also need an endpoint attribute in order to send the data to the correct endpoint.

<form data-cc-endpoint="login_1234572034573x2734502348">
  <label for="username">Username</label>
  <input id="username" type="text" name="username" required>
  <label for="password">Password</label>
  <input id="password" type="password" name="password" required>
  <input type="submit" value="Log In">
</form>

If this all seems like a lot to take in at once, don't worry. The details of each attribute and when you need to include what are documented on this page. Just reference the section in question to find any options and requirements that apply.

Going Live

Cloud Canal starts you off on a free tier, where you can build your web app without paying a cent. Subscriptions in Cloud Canal are tied to domains, not connectors or users. If you have multiple domains using your connectors, you'll have to subscribe to a professional plan for each.

Billing in Cloud Canal is usage-based. Each domain costs a base monthly fee to operate and includes thousands of API calls. If your site exceeds the included call count, then additional calls will still work but will be charged a tiny fee. Refer to the pricing section for details.

Once you are done setting up your web app, you can upgrade your domain by navigating to the Domains page and clicking "MANAGE" next to the domain in question. Clicking on "UPGRADE" will open up a modal with a payment form. This is also a good time to see the Stripe attributes in action!

If you've made it this far, congratulations! You're done, and your web app is ready for production!

Events

Events are the most common data attribute used in Cloud Canal. They can be split into two main types: user events and HTTP events.

User events correspond to things directly done by the user on your site. This includes submitting a form, loading a page, clicking on something, and changing an input value.

HTTP events happen whenever a call is made to an endpoint. You can target the start of a call, a specific status code, or all status codes. HTTP event attributes must be accompanied by an endpoint attribute.

Form Submit

Submit a form to a specific endpoint by attaching an endpoint attribute to the <form> element. The form inputs will be parsed to JSON based on their name attributes and sent in the request body.

<form data-cc-endpoint="[endpointID]">
  ...
</form>

Page Load

This event will trigger when the page is loaded. It does not matter which element the attribute is on, but the order the calls are made in is the same as the order of the elements in the DOM if there are multiple load attributes.

data-cc-on-load="[action]"

Click

This event will trigger whenever the element it is attached to is clicked (or pressed). The most common element you'll want to use is a <button> or <a>, but any element will work.

data-cc-on-click="[action]"

Change

This event will trigger when the value of an input, such as a checkbox or text field, is changed.

data-cc-on-change="[action]"

HTTP Start

This event will trigger whenever the a request to the corresponding endpoint begins.

data-cc-http-start="[action]" data-cc-endpoint="[endpointID]"

HTTP Status

This event will trigger whenever the call to the corresponding endpoint returns with the specified status code. You can include multiple status attributes on the same element to address different status codes.

data-cc-http-[status]="[action]" data-cc-endpoint="[endpointID]"

HTTP Default

This event will trigger whenever the call to the corresponding endpoint returns and is not captured by an HTTP status attribute on the element. This means it can be used alongside HTTP status attributes or on its own, in which case it will fire every time the endpoint returns.

data-cc-http-default="[action]" data-cc-endpoint="[endpointID]"

The example below will show the image when the response to the endpoint is OK (200), and hide it otherwise.

<img src="..." data-cc-http-200="show" data-cc-http-default="hide" data-cc-endpoint="[endpointID]">

Actions

Actions are performed as a result of an event being triggered. You can list multiple actions for an event by separating them with double semicolons.

data-cc-[event]="[action1];;[action2];;[action3]"

Show

Show the element. This action works by setting the display property of the element to block.

data-cc-[event]="show"

Hide

Hide the element. This action works by setting the display property of the element to none.

data-cc-[event]="hide"

Value

Insert the value into the element. This action depends on which element it is applied to:

  • <input>: sets the value attribute
  • <select>: sets the value attribute
  • <textarea>: sets the value attribute
  • <img>: sets the src attribute
  • other: sets the text
data-cc-[event]="value:[value]"

HREF

Apply the value as an HREF attribute to the element. This action is particularly useful for dynamic links, especially within arrays.

data-cc-[event]="href:[URL]"

Endpoint

Make a call to the specified endpoint. This action is particularly useful for chaining API calls together.

If you need to submit data along with this call, you can create a form with the same endpoint attribute and fill it with input elements containing the data. If necessary, the form can be hidden an the data will still be submitted.

data-cc-[event]="endpoint:[endpointID]"

Redirect

Redirect the user's browser to the specified URL.

data-cc-[event]="redirect:[URL]"

Array: Add

Add an item to the array, specified by endpoint. The structure of the item will be identical to the array's template.

data-cc-[event]="array-add:[endpointID]"

Array: Remove

Remove the specified instance in the array. This action has two possible values:

  • true: Removes the closest parent array instance. Useful if the triggering element is inside the array template.
  • [endpointID]: Removes the last instance in the array with this endpoint ID.
data-cc-[event]="array-remove:true"
data-cc-[event]="array-remove:[endpointID]"

Select: Options

Set the options for a <select> element. It is meant to be used with API calls in order to generate lists of options dynamically, so will often be used together with an endpoint attribute. This action has three components:

  • [array]: The array object, typically represented with a value parameter.
  • [text]: The name of the array object's property representing the text displayed in the option.
  • [value]: The name of the array object's property representing the value of the option.
data-cc-[event]="options:[array]:[text]:[value]"

Parameters

Parameters can be used in actions or connectors in order to access dynamic data. They are wrapped in double curly braces.

Value

Insert the value found at the response given the path. This parameter only works with HTTP events.

{{[path.to.value]}}

For example, an HTTP request returns the following response:

"car": {
  "color": "blue",
  "passengers": "5",
  ...
}

In order to get the value of "passengers", we use the parameter below. It will be replaced with "5".

{{car.passengers}}

You can also target the root of the response by using an asterisk.

{{*}}

Query

Insert the query parameter value with the specified key.

{{query:[key]}}

For example, if the URL on the page is currently "www.example.com/cars?id=12345", the following query parameter will be replaced with "12345":

{{query:id}}

Function

Execute the function and insert the return value, if applicable. This parameter can be used to run custom code and doesn't necessarily have to return a value to insert.

{{fcn:[code]}}

You can either write the code inline or reference an existing function. The existing function can be one that you've embedded or a a built-in function available in JavaScript, jQuery, or Cloud Canal. For reference, the code is ran through the JS eval() function.

Inline code:

{{fcn: 3+3 }} //returns 6

Referenced function:

{{fcn: myFunction() }}

Cloud Canal built-in functions and references:

setCookie(name, value)
getCookie(name)
insertResponse(element, value)
response //references the returned response of the HTTP request
element //references the element to which the current attribute is attached

An example that redirects the user to the www.example.com if a username cookie is not found, or else inserts the username into the element:

{{fcn: if(!getCookie("username")) { "redirect:www.example.com"; } else { insertResponse(element, getCookie("username")); } }}

NB: when using a function, please ensure you place spaces between curly braces that are not meant to wrap the function. Otherwise they may be mistaken for the end of the function, since Cloud Canal uses double curly braces to determine where parameters begin and end.

Nested parameters are not currently supported.

This is the only parameter type which will not work in a connector; you cannot use it in headers, query parameters or cookies on the server side for security reasons. It will only work in attributes on your site.

Arrays

Cloud Canal's array functionality lets you work with collections of data.

Template

The array attribute lets you reference a list of items by creating a template which is then dynamically copied and filled out depending on the data passed to it. It must be used alongside an endpoint attribute, and will require a value parameter to get the array object from the response.

data-cc-array="{{path.to.array}}" data-cc-endpoint="[endpointID]"

For example, imagine you have an endpoint that returns a list of cars. The response is structured a follows:

"cars": [
  { "make": "chryser", "model"="300", "color"="black", "year"="2012" },
  { "make": "ford", "model"="focus", "color"="blue", "year"="2018" },
  { "make": "honda", "model"="civic", "color"="grey", "year"="2001" },
  ...
]

You would begin by creating a <div> to serve as a template with the following attributes:

<div data-cc-array="{{cars}}" data-cc-endpoint="get-cars_12491274812x1023812081"></div>

In the next section, we'll continue this example by populating it with data from the array.

Elements

Array elements allow you to access data within the array. They are scoped to the array and not the root of the response, but otherwise execute actions just like events do. You apply array element attributes to elements inside the array template.

data-cc-array-element="[action]"

Continuing the example from the previous section, we can access the "make" of of the car and put the response as text in a <div> as follows:

<div data-cc-array-element="value:{{make}}"></div>

Notice that the value parameter above is not scoped from the root of the response, i.e. it's {{make}}, not {{cars.make}}. We've also been using the <div> tag in our examples, but you can use any element you wish.

To complete the example, our template element may look something like this:

<div data-cc-array="{{cars}}" data-cc-endpoint="get-cars_12491274812x1023812081">
  Make: <div data-cc-array-element="value:{{make}}"></div>
  Model: <div data-cc-array-element="value:{{model}}"></div>
  Color: <div data-cc-array-element="value:{{color}}"></div>
  Year: <div data-cc-array-element="value:{{year}}"></div>
</div>

You could then style the above any way you wish. Cloud Canal will automatically instantiate it as many times as there are objects in the array and fill out each template.

Stripe

In order to make accepting payments easier, Cloud Canal includes attributes specifically for working with Stripe.

Form

The basic element for working with Cloud Canal and stripe is the <form>. Marking a form with the Stripe attribute will cause Cloud Canal to automatically load stripe.js on that page. The endpoint attribute should point towards a connector endpoint you've set up to process the payment, which would include steps like creating a customer and signing them up to a subscription. Refer to Stripe's documentation for more details.

<form data-cc-stripe="form:[Stripe_publishable_key]" data-cc-endpoint="[endpointID]"></form>

The first thing you'll need to do is sign up for Stripe. Once complete, you'll be taken to your dashboard, where you'll find the public key for your account. This key is safe to share with others. Ensure you don't accidentally copy the private key. You'll need to include the public key in the Stripe attribute. In the testing phase, it'll look something like this:

data-cc-stripe="form:pk_test_iYIGYUGi786utf4d4DFu"

Card

This element allows you to collect credit card details from your customers. Refer to the documentation. You can optionally pass styling information as well per Stripe's guidelines.

<div data-cc-stripe="card"></div>
<div data-cc-stripe="card:[style_info]"></div>

The example below creates a card element with some custom styling applied.

<div data-cc-stripe="card:{"base":{"fontSize":"16px", "color":"#1a1b1f", "fontFamily":"Arial"}}"></div>

Inputs

If you need to capture additional information from the user, you can do so by marking inputs with the corresponding information type. For a full list of supported information, take a look at the tokenData parameter.

<input type="..." data-cc-stripe="[tokenData_type]">

For example, the input below would be used to collect the user's name.

<input type="text" data-cc-stripe="name">

Errors

Errors that occur during payment processing can be captured and displayed back to the user.

<div data-cc-stripe="errors"></div>

Misc

Cloud Canal includes other attributes which don't fit into the categories above but are otherwise handy or even crucial to the operation of the framework.

Endpoint

This attribute denotes an endpoint in one of your connectors. It does not do anything on its own but is necessary for the use of many other attributes, such as HTTP events or arrays. It lets Cloud Canal know where the framework should be sending or pulling data from.

data-cc-endpoint="[endpointID]"

You can link multiple elements on a page to the same endpoint. These will all send and receive data with a single request. If you want to use the same endpoint multiple times on the same page but want to group interactions, you can prefix an endpoint ID with a number.

data-cc-endpoint="[instance]:[endpointID]"

Elements are only considered grouped when both their endpoint AND instance number is the same. To have an element associate with every instance of a certain endpoint (regardless of prefix number), simply use it without a prefix.

The concept of endpoint prefixing applies wherever an endpoint can be specified, including in events.

Loader

This is a convenience attribute and can be used for loaders for endpoint calls. It may take a few seconds to execute a call depending on the amount of data to be transferred, so applying this to a loader div is one way to convey to your users that something is happening.

It is equivalent to using the show action in an HTTP start attribute, followed by a hide action in an HTTP default or HTTP status attribute.

data-cc-loader="true" data-cc-endpoint="[endpointID]"