API Calls

Introduction

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.

Example:
window.webkit.messageHandlers.API_CALL.postMessage("VALUE");

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 value for a sidebar UI item. All values should be passed as strings, including integers and bools.

Dropdown Example:
window.webkit.messageHandlers.setUIVal.postMessage('{"attr":"dropdown-data","value":"1","sync":"false"}');

Checkbox Example:
window.webkit.messageHandlers.setUIVal.postMessage('{"attr":"checkbox-data","value":"1","sync":"false"}');

Input Field Example:
window.webkit.messageHandlers.setUIVal.postMessage('{"attr":"field-data","value":"Hello World","sync":"false"}');

Aligment Control Example:
window.webkit.messageHandlers.setUIVal.postMessage('{"attr":"align-data","value":"2","sync":"false"}');

setUIState – Set the state (enabled / disabled) of a sidebar UI item.

Example:
window.webkit.messageHandlers.setUIState.postMessage('{"attr":"my-name-data","enable":"false"}');

setUIEditable – Set whether a UI items content can be edited.

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

setUIHidden – Set whether a UI item is hidden.

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

popUIMenu – Populate a drop down menu item with options.

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

Project Calls

There are times when you will need to add additional resources to a project that contains your custom Bric. The following API calls allow you to add additional project resources.

projectResource – Add additional custom Bric resources to a project. Once added, these will show in the project attachments under project settings. JS, CSS, PHP and HTML files are currently supported, as well as directories. 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. Within a pages code the CSS resources will be placed before the closing head tag and JS resources will be placed before the closing body tag. All additional resources referenced by your custom Bric, should be included in your custom Brics resources directory.

Example:
window.webkit.messageHandlers.projectResource.postMessage('{"action":"add","name":"my-brics-assets-folder"}');

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.

Example:
window.webkit.messageHandlers.resource.postMessage('{"action":"add","name":"my-custom-resource.js"}');

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

Example:
window.webkit.messageHandlers.pageSuffix.postMessage("php");

Template Calls

There are times when you may need to include user defined values within additional files that are included with the exported site. The following API call allows you to do this.

storeCustomBricTemplateVal – Store a user defined value that will be included within a custom Bric template file. Template files can be CSS, JS, JSON and PHP and should be added to the custom Bric contents in a directory named templates.

Example:
window.webkit.messageHandlers.storeCustomBricTemplateVal.postMessage('{"attr":"my-attr","value":"Hello World","template":"custom-bric-js.js","force-newfile":"no"}');

Key Values:
The storeCustomBricTemplateVal API call should include the following key values:

attr – The attribute value is used to identify the areas that will be replaced in the template file upon export. When this attribute is used within a template file, it should be wrapped in % e.g. %my-attr%.
value – The value that will replace the attribute in the template file.
template – The template file name. This file should be located in a directory named templates within your Brics contents.
force-newfile – If two Brics with different values write to the same template file and this is set to YES, another template file will be created e.g custom-bric-js-1.js.

Short codes
It’s also worth noting that short codes can also be used in template files.

DOM Changes

Custom Brics are manipulated outside of the main design environment, this method gives developers complete freedom to manipulate the custom Brics ‘DOM’ (Document Object Model) 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. It’s also important to consider that the sync protocol will also create an undo state in the current document, so only use this call if changes have been made, otherwise unnecessary undo states will be created.

Example:
window.webkit.messageHandlers.sync.postMessage("changes");

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.

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

It’s also possible to reset a notification using the reset attribute, the ID attribute can be used to submit a single ID or an array of notification ID’s.

Example:
window.webkit.messageHandlers.notification.postMessage('{"reset":"true","id":"my-bric-notification-1,my-bric-notification-2"}');

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

Example:
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 users choice will be passed back to the function as a BOOL value.

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

openURL – Open a URL in the users web browser.

Example:
window.webkit.messageHandlers.openURL.postMessage('https://blocsapp.com/');

Misc

Miscellaneous calls used for developing.

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

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