Give feedback for the page

BLOCKSHello World Tutorial

In this exercise, we'll learn how to use the Before Publish or Fire Event Handler Type (ET) to mutate (add and remove attributes from) a message body.

The goal is to add an attribute to a message called hello with a value of world.

First, we'll walk through the initial block setup via the admin portal.

  1. Login to the admin portal.

    The Admin homepage screen is displayed. Let's create a new sandbox app called BLOCKS Tutorials.

  2. Locate the Create New App dialog.

    Locating Create New App
  3. Enter BLOCKS Tutorials in the Enter a New App Name field.
  4. Click Create New App.

    You should receive an App Created Successfully notification at the top of the page.

  5. Scroll down the page until you find the newly created BLOCKS Tutorials App.
  6. Click on BLOCKS Tutorials.
  7. Click on Demo Keyset.
  8. Enable BLOCKS under Application Add-ons.
  9. Click Save Changes.
 
If you do not see an option for BLOCKS please contact support@pubnub.com to request access.

Now that we've created the app, let's create our first Block, Hello World inside of it.

  1. Click BLOCKS on the left menu.

    Click Blocks

    The BLOCKS screen is displayed. Let's create our first block, Hello World.

  2. Locate the Create New Block dialog.

    Locating Create New Block
  3. Enter Hello World in the Enter a New App Name field.
  4. Click Create New Block.

You should receive a New Block Successfully Created notification at the top of the page.

Now that we have created our first block, we need to write our first Event Handler (EH).

In the paradigm of a Programmable Network, the EH is the entity which contains the program, or logic, that runs against the message.

In the next steps, we're going to setup the EH attributes.

  1. Click the + Create button to create a new EH.

    Create New EH

    The Create a New Event Handler dialog appears.

    Create New Event Handler Dialog
  2. For Event Handler name, enter Mutate Message.
  3. For Channel name, enter hello_world.
  4. For Select an event, select Before Publish.
  5. Click Create.

    The Hello World Block editor appears, with the Mutate Message EH editor in focus.

    When a new EH is created, the system creates a default template function:

    export default (request) => {
        console.log(request); // Log the request envelope passed
        return request.ok(); // Return a promise when you're done
    };

    With the following characteristics:

    • The function name is process.
    • The parameter is named request, and it consists of the PubNub message envelope object.
    • The body of the function contains a logger line.
    • The body of the function ends by returning the request unmutated as a promise resolution.
     
    Returning request.ok() is the equivalent to returning Promise.resolve(request).

    Keep in mind that this EH will run each time the message enters the PubNub Data Stream Network, but before its further replicated and distributed to subscribers, because it's type is Before Publish.

    Currently, it won't do much other than log out the request and pass it through, but regardless, let's test it:

  6. Click the Save button (disk icon).

    Save Button
  7. Click Start block.

    Start Block

    The block will go from pending to running. You should see this status in the bottom log panel.

    Pending Running

    Once running, let's test this functionality using the built-in test console.

  8. {
        "foo": "bar"
    }
  9. Click Publish.

    By clicking Publish, you are sending a message with the payload defined in the payload field, to the channel defined in the channel field.

    From the test console, we see two things:

    1. The final published message with a pink label.
    2. The console log output with a green label.
    Test Payload

    To make it more exciting, let's instruct BLOCKS to augment a hello attribute with the value of world to each message transiting through this channel.

  10. export default (request) => {
        request.message.hello = "world!"; // augment hello = world
        return request.ok(); // Return a promise when you're done
    }

    We are now code-complete for Hello World, so let's give it a test drive!

  11. Click Save.
  12. Click Stop block.
  13. Click Start block.

    The block will go from stopped to running. You should see this status in the bottom log panel.

    Once running, let's once again test this functionality using the built-in test console.

  14. {
        "foo": "bar"
    }
  15. Click Publish.

    From the test console, we see two things:

    1. The final published message with a pink label (now with hello = world!)
    2. The console log output with a green label.
    Argument Message

    You can see from the above examples that the built-in test console is convenient, but sometimes, you may want to use the production developer console instead. To use the production developer console:

  16. Open a new tab to the PubNub Developer console located at PubNub Console
  17. Set the channel to hello_world.
  18. Set the publish and subscribe keys to the values you selected when creating the Block in step 5.
  19. Click Subscribe.
  20. Publish the default {foo:bar} object.

    Just like using the built-in BLOCKS console, we see the effects of our block through the production developer console.

    Console Out

    When you click Publish on either console, you're seeing the same production output your client will see.

    Now, that's pretty awesome! you must be thinking.

    But what if we wanted to make this a 100% Hello World app – and have it remove the foo:hey key/value pair from the message being published? It's simple – we'll just use the native Javascript delete command to remove a text attribute, in this case, hello.

  21. Go back into the BLOCKS GUI, and add a delete keyword to remove the foo attribute, right before the return call.

    export default (request) => {
        request.message.hello = "world!"; // augment hello = world
        delete request.message.foo; // delete the foo attribute
        return request.ok(); // Return a promise when you're done
    };
  22. Click Save.
  23. Click Stop block.
  24. Click Start block.

    The block will go from stopped to running. You should see this status in the bottom log panel.

    Once running, let's once again test this functionality using the built-in test console.

  25. {
        "foo": "bar"
    }
  26. Click Publish.

    After a few moments, the after the running message is displayed, perform another test publish from the debug console of your choice with the message {foo:bar}.

    You should see the foo attribute has been deleted; Voila!

    Final Out

    A true, undeniable BLOCKS Hello World!