Using Your Local Ruby Environment to Deploy Blockspring Functions

Exploring the Components of a Blockspring Function

In this step, we'll learn what makes a Blockspring function work, which sets us up to test and create functions locally.

When you ran the blockspring new command, the CLI tool populated your function's directory with two basic files, blockspring.json and block.rb. Check out the first file, blockspring.json:

$ cat blockspring.json
{
  "title": "Best function ever",
  "description": "",
  "parameters": [
    {
      "type": "text",
      "label": "First Name",
      "name": "first_name",
      "help_text": "Enter your first name.",
      "default": "Paul"
    },
    {
      "type": "number",
      "label": "Age",
      "name": "age",
      "help_text": "Enter your age.",
      "default": 26
    }
  ],
  "is_public": true,
  "is_open_source": true,
  "language": "rb"
}

blockspring.json is a configuration file which populates everything you see on your function's homepage. Title and description (can be a markdown string) are easy to set here.

In the last step you executed your function from the form on its homepage. The inputs for this form are populated from the parameters array in blockspring.json. Each object in the array should have the following keys:

  • type: This determines the type of form input rendered for your parameter. For a list of available types, visit the Input Types reference page.
  • label: This determines the label for your parameter's form input. It can be a string with spaces.
  • name: Parameters are passed into our code with request.params, which we'll see explain later on in this page. The name of a parameter must match how we're calling it in our code.
  • help_text: This is a short string which helps a user understand what input to provide on our function's form.
  • default: This populates our function's homepage form with a default value.

Visit the blockspring.json reference page for more info. Now let's look at the second file, block.rb:

$ cat block.rb
require 'blockspring'

block = lambda do |request, response|
        name = "Hi! My name is " + request.params["first_name"]
        age = " and my age is " + request.params["age"].to_s

        response.addOutput("intro", name + age)
        response.end()
end

Blockspring.define(block)

block.rb is the Ruby code that gets executed when your function is called. Here are the main things to know:

  • require 'blockspring': The Blockspring gem for Ruby comes with the helpers you need to define and run functions locally. You'll install this in the next step.
  • request.params: All inputs passed into your function are found here. Note that first_name in request.params["first_name"] matches exactly with this parameter's name key in blockspring.json file.
  • response.addOutput: Add function outputs using this helper function. It takes two arguments, the first is a key name for your output, and the second is an output value.
  • response.end: Call this when you want to end function execution. Optionally add a return (not shown here).
  • Blockspring.define: Supply the name of your function, in this case block to this helper to define it. Using Blockspring.define lets Blockspring know what to execute each time the function is called.

The Blockspring gem for Ruby comes with a rich API. For more information, check out the API reference manual.