The Blocs developer API provides a set of routines and protocols that can be used to interact with a custom Brics user interface, HTML output and various other aspects of the Blocs design environment.

Calls are made via a custom Bric’s Javascript functions, functions can be written in any JS format, jQuery 2, jQuery 3 etc.

All API calls are processed using the WebKit Message Handler and should pass a single set of data in the form of a JSON dictionary or a string. An API calls data value should be placed within the Post Message brackets.


UI Calls
When a custom Bric is selected, the sidebar will auto populate the UI values based on the Custom Brics current values. When a sidebar UI item is interacted with, the state of that item will be automatically updated, however, the following API calls allow you to manipulate other UI items and their values for that custom Bric. For example, checking a checkbox could result in adding another menu item to a drop down menu, unchecking it, could remove the additional item from the drop down.

User interface API Calls require a JSON dictionary that specifies the target UI item attribute and value.

setUIVal – Set the string value for a sidebar UI item.


setUIState – Set the state of a sidebar UI item, e.g. checkbox value true/false.


setUIEditable – Set whether a UI item is enabled/disabled.

Example: window.webkit.messageHandlers.setUIEditable.postMessage('{"attr":"my-name-data","editable":"true"}');

popUIMenu – Populate a drop down menu item with options.

window.webkit.messageHandlers.popUIMenu.postMessage('{"attr":"dropdown-data","items":"item 1,item 2,*seperator*,item 3", "value":"0"}');

Page Calls
There are times when you will need to add additional resources to a page that contains your custom Bric. The following API calls allow you to add additional page resources and control a pages export suffix.

resource – Add additional custom Bric resources to a page. Once added, these will show in the page attachments under page settings. JS, CSS and PHP files are currently supported. Attached JS files are placed in the export /js directory, CSS files are placed in the export /css directory and PHP files are placed in the export /includes directory. All resources referenced by your custom Bric, should be included in your custom Brics resources directory.


pageSuffix – Set the current page suffix, e.g. HTML, PHP.


Dom Changes
Custom Brics are manipulated outside of the main design environment, this method gives developers complete freedom to manipulate the custom Brics ‘DOM’ in any way, with any type of JS based language. After a function has made changes to the custom Brics DOM, it will need to call the sync protocol in order to synchronise the DOM changes to the custom Bric located on the main Blocs design canvas.

sync – After DOM manipulation has taken place, the sync API call will synchronise the changes to the main Blocs design canvas. There is no pre-processing or rendering during sync, it all happens instantly.


Feedback Calls
There are times when it’s important to feed information back to the user based on the changes they are making to a custom Bric. The following calls offer a variety of ways to do that.

notification – Show an in-app notification that doesn’t block full UI access. Each type of notification should have its own ID value as once a notification ID is dismissed by the user, it will not be displayed again if it is called.

window.webkit.messageHandlers.notification.postMessage('{"message":"Hey, this is a notification.","id":"my-bric-notification"}');

alert – Post an alert (blocks apps full UI until dismissed).

window.webkit.messageHandlers.alert.postMessage('This is a basic alert');

callbackAlert – Post an alert (blocks apps full UI until dismissed) that requires the user to make a choice. The user’s choice will be passed back to the function as a BOOL value.

window.webkit.messageHandlers.callbackAlert.postMessage('{"message":"Do you want to get a pizza?","function":"pizzaFunction"}');

openURL – Open a URL in the users web browser.


Miscellaneous calls used for developing.

debug – Post a debug message that will show in the developer console window.

window.webkit.messageHandlers.debug.postMessage('Hello World!');