Velo Tutorial: Sending Messages with the Realtime API

As you can see, the file contains one function. We call that function from the admin page to publish messages that are received by subscribers on the home page. The function simply takes in some information and packages it up so it can be sent using the Realtime API.

When calling the publish() function from the Realtime API we need to provide it with where we want to publish and what we want to publish. So we take the name and resourceId (if there is one) that were passed into the publishMessage() function and package it up as a Channel object. We also take the information that we want to publish and package it in an object to be sent as the payload. Here we send the textual message, the color that we want the message to be displayed in, and the time the message was sent.

First, we use the default() function to set the default permissions for all channels and channel resources. In our case, we set the default permissions to allow anyone to read. We do so by returning the permissions policy from the callback function passed when calling default().

In our site, we have a "visitors" channel that we subscribe non-members to. Since we don't specify specific permissions for that channel, it receives the default permissions and anyone can subscribe to it.

Next, we create a Channel object to represent our "member" channel and use the add() function to add permissions for it. Since we don't specify specific permissions for each resource in the "members" channel, all the resources inherit the permissions we define here.

Here again, we specify the permissions by returning them from a callback function. In this case, we check if the user trying to subscribe to a "member" channel is a site member or the site admin. If so, we grant them read permissions. If not, we deny them read permissions.

Finally, we define the realtime_check_permission() function. This is the function that gets called each time someone tries subscribing to a channel or channel resource. It gets passed which channel someone is trying to subscribe to and who it is that is trying to subscribe. It returns the permissions that are granted to that subscriber for that channel.

For example, when user "MsUser" tries to subscribe to channel "SomeChannel" the realtime_check_permission() function is called. The channel argument contains a Channel object corresponding to "SomeChannel" and the subscriber argument contains a User object corresponding to "MsUser". In the implementation of this function you can take into account who the user is and what channel they are trying to subscribe to. Then you return a ChannelPermissions object that defines what permissions you've granted "MsUser" on "SomeChannel".

Technically, this is the only function we need to implement in order to define realtime permissions. We could have crammed all of our permissions logic into the realtime_check_permission() function. Instead, we've used the permissions router, which leads to neater code.

Then we get all the channels that were selected by the admin from the checkbox group's value property. For each selected channel, we find the channel's name and resource ID and use it to publish using the function we defined in the backend realtime.jsw file. In addition to the channel information, we also pass the publishMessage() function the message entered by the admin and the color the admin chose.

Before we take a deep dive into the intializeMember() function, let's take a look at the simpler subscribeToVisitorChannel() function.

First, we create a Channel object to represent the "visitors" channel. Notice that we only use a name and not a resourceId because we don't have multiple visitor alert types.

Then we call the subscribe() function from the Realtime API. The subscribe() function takes two arguments. The first is a Channel object and the second is a callback function to call each time a message has been published on that channel. So in this call to the subscribe() function, each time a message is published to the "visitors" channel we want to call the showBreakingNews() function to handle the incoming message.

Now let's take a look at how the showBreakingNews() function works.

First, we take the received payload and format it in the style we want for our breaking news alert. Remember from our discussion of the backend code that the payload contains a message, color, and time. Here we use the html property of a text element so we can change the color of the alert using the style attribute and populate the time and message as stylized text.

First, we create an array named subscriptions, that will hold the member's subscriptions. We use this array to keep the current state of the member's subscriptions. Each time the member subscribes to or unsubscribes from a channel we update this array.

Next, we show the settings icon using the show() function. Remember, that is how site members open the subscription lightbox to set which alerts they want to subscribe to.

Then, we get the list of channels the member has subscribed to using the getSubscriptions() function. Remember, these are stored in the Subscriptions collection. Once we get the list of channels we call the subscribeToMemberChannels() function to subscribe the member to each of those channels.

Finally, we define what happens when the settings icon is clicked using the onClick() function. When it's clicked we open the subscriptions lightbox. We also define here what happens when the lightbox is closed. In our case, when the lightbox closes it returns to the page a list of channels that the member added and a list of channels that the member removed. So we call a couple of functions to subscribe the member to the added channels and unsubscribe the member from the removed channels.

Remember, the Subscriptions collection has a field name types that is a reference to all the subscription types a member is subscribed to. Here, we use the queryReferenced() function to get those referenced items based on the current member's ID.

If the function runs successfully, we know we are dealing with a member that we have already added to our collection. However, if the function's returned promise is rejected, we are assuming that the rejection is caused by the current member being a new member without a corresponding item in the Subscriptions collection. In that case, we insert a new item into the collection where the item's _id is the current member's ID and return an empty array because a new member does not have any saved subscriptions.

For each channel in the list passed to the function, we create a Channel object and call the realtime subscribe() function to subscribe the member to the channel. Just as we did above, we pass the showBreakingNews() function as the callback function to be called when a message is received on the channel.

If the subscription is successful, we store the channel information in the subscriptions array.

For each ID of a removed subscription, we find the corresponding object in the subscriptions array and the index of where it resides in the array. We use the object data to call the realtime unsubscribe() function. If the unsubscribe is successful, we use the index to remove the items from the subscriptions array.