Create your own block



Blocks and iframes.🔗


Blocks are the way in which we can add Javascript or Web applications to our pages. To create a block, you add your code inside a sandboxed iframe that is inserted into your page. This approach to using iframes to insert third party javascript is the prefered choice for several platforms. If you have used any online javascript playground, probably you have already created something similar to a Nitoku block.

Sandboxed iframes are issolated from the page, therefore the code that you include on the block ( the iframe ) can't affect the page. This is very important and protect users from buggy or malicious code.

Unfortunatelly this safety comes at a cost, iframes can't access directly to page information, neither can change their size or permissions. That is okay for a simple javascript playground but in our platform we want blocks to be able to do more, e.g. read their setting data, request the CSS style, save data for later use. To enable this extended functionality, blocks use the native browser Window.postMessage() method to communicate with Nitoku main app. Those messages are defined on the block API, using those messeges, iframes are able to access platform functionality in a safe way.



Creating the block page.🔗


Go to the resources table on your pages or one of your teams. There create a new page, be sure that the name for your page only have alphanumeric characters.

In the example below we have named our page "blockTest". After you create the page you need to make the page a block page, click on the "Change to Block Page" button to do this.




Understanding the default block code.🔗


At the bottom of your block page you will find the source code of your new block page. Click on the edit button and let's go through the code to understand how it works.

First, you will find the license for your script, see an example below. By default the default script includes a MIT license, fell free to change the license to your preffered license type.



Copyright 2020 @aptesis.public

Permission is hereby granted, free of charge, to any person obtaining a copy of 
this software and associated documentation files (the "Software"), to deal in the 
Software without restriction, including without limitation the rights to use, copy, 
modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, 
and to permit persons to whom the Software is furnished to do so, subject to the
following conditions:

The above copyright notice and this permission notice shall be included in all copies
or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, 
INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A 
PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT 
HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION 
OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE 
SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

After the license we will find some utility functions that help us manage some of the limitations of using iframes, these functions are not mandatory, but they will help us to overcome some of the limitations of working with iframes. The two main objectives of the functions below are; first, provide some functionality to open links and second reset the height of the iframe when nessesary.

Links management

If we click on a link inside the iframe, by default links will be opened inside of the iframe and we probably don't want this, what we probably want is to open the link for the whole window. To open links for the whole window on this default script we listen to any click on the links of the block. Then, after a user click a link, the block will request that link to be open by the main application sending the postMsg.service = 'open-link'; message to Nitoku main app.

iFrame Height management

This default script checks for the iframe height every second, and if it finds that the height of the iframe has changed, it will ask the main app to adjust the iframe height sending a postMsg.service = 'set-height'; message to the main application.

Geting block configuration data

As we can see on the clip below, our block has access to the data inside the markdown block definition as well as any update the the user makes to this data.


The block is listening to the message if(e.data.service === "get-data" || e.data.service === "data-update"){ to access the data that was included on the markdown definition. As the block, receives the message it will act on the iframe's DOM to display the data as necessary. Please see below how our default block receives the data of the markdown block and then update the html element inside the iframe accordingly.


Finally, at the botton of the script we have some loading methods to execute our script after the iframe has been loaded into the page.


A practical example, understanding the carousel block's source code.🔗


The carousel block is a simple block that use the slick Javascript library from Ken Wheeler. Slick is a responsive carousel jQuery plugin that supports multiple breakpoints, CSS3 transitions, touch events/swiping and more.

The configuration data for each block is specific to that particular block and is usually described on the block page, in the case of the carousel the code of the block and the description of the block configuration is at : https://www.nitoku.com/@nitoku.public/carousel.


Let's see how the carousel block has been inplemented. First, as we can see on the code below, necesary CSS files and Javascript files have been added to the head element of the iframe.


Second we receive the links and setting parameters. We have some code to parse the data that was set for the block on the markdown definition, but the key code is below, where we add the links to the carousel elements and then launch the slick library to display the carusel itself.



Advanced API uses.🔗


Managing block dialogs


Using messages metadata




Follow the link below for details of each function on the Block API.