INTRODUCTION

Welcome to the Blocs API documentation. This document is a work in progress and will be continuously updated. It covers all of the basic features of the Blocs API.

What is the Blocs API?

Since the release of version 1.3, Blocs has supported the ability to install 3rd party extensions. The Blocs API is the foundation in which Blocs extensions are build on allowing developers to add additional features such as custom bloc sets and styles.

EXTENSION TYPES

There are two types of extension for Blocs, style and bloc set extensions, style extensions are simple Javascript based files that inject custom styles into the Blocs environment allowing you to use them on objects such as images and buttons. Bloc set extensions let you create custom bloc layouts that are added to the bloc bar and can be used in your page designs just like any other pre made bloc.

Style Extensions

When creating style extensions it's important you try to make them as dynamic as possible, take into consideration how the Bootstrap framework is designed with regard to the re-use of classes. For example, if you create a button style extension avoid setting it's background colour in the actual class as this is handled separately by the Blocs colour controller. Try to make your style extensions neutral so they can be combined with other classes to create different variations based around your custom style.

It is possible to add rules such as margin, padding and absolute positioning but always consider that from within Blocs you wont be able to refine these details as you work.

Bloc set Extensions

When creating bloc set extensions, it's important you consider the editing controls that are currently available within Blocs. If an object is not already available in Blocs as a Bric then it's unlikely that you will be able to edit it within Blocs, however it is possible to add non supported objects, just consider whether they need to be edited in app.

BEX FILES

Blocs extensions come in the .bex file format, BEX files are primarily written in Javascript and then compiled to BEX using the DevTools from Blocs application.

AVAILABLE CALLS

Blocs currently supports the following API calls:

  • addButtonStyle( name, class ); - Custom button style.
  • addImageStyle( name, class ); - Custom image style.
  • addTextStyle( name, class ); - Custom text and icon style.
  • addBackgroundStyle( name, class ); - Custom bloc background style.
  • addBlocSet( setName, icon ); - Custom bloc set.
  • addBlocOptions( setName , htmlArray, imageArray); - Custom bloc option to set.

STYLE EXTENSIONS

Building style extensions for Blocs is pretty straight forward, the entire extension is written in Javascript/CSS and then compiled to .bex using the DevTools.

Extension Structure

The basic structure of a style extension is a single Javascript file that contains all of the style API calls you wish to make for that extension.

Style Extension Example

Here is a style extension example of a custom button style. You will notice the first variable we set is the style name and the second is a full css class.

addButtonStyle('High Gloss', '.btn-hi-gloss{box-shadow:inset 0 1px 0 rgba(255,255,255,.6),inset 0 20px 0 rgba(255,255,255,.2),inset 0 0 6px rgba(255,255,255,.5), 0 2px 3px rgba(0,0,0,.15);}');

You can add as many style calls to a single extension as you like, it's also possible to mix them allowing you to create extensions that add multiple new styles to different types of objects all from one file.

addButtonStyle('High Gloss', '.btn-hi-gloss{box-shadow:inset 0 1px 0 rgba(255,255,255,.6),inset 0 20px 0 rgba(255,255,255,.2),inset 0 0 6px rgba(255,255,255,.5), 0 2px 3px rgba(0,0,0,.15);}');
                
addImageStyle('deep-shadow', '.img-deep-shadow{box-shadow:inset 0 1px 0 rgba(255,255,255,.6),inset 0 20px 0 rgba(255,255,255,.2),inset 0 0 6px rgba(255,255,255,.5), 0 2px 3px rgba(0,0,0,.15);}');

Once your style extension is written, you will need to first compile it to the .bex extension file format in order to use it with Blocs. You can read more about compiling to BEX here.

BLOC SET EXTENSIONS

Building a custom bloc set is a little more complex compared to creating a style extension. As well as a Javascript file, a custom bloc set also requires user interface image assets that will need to be included when compiling to BEX.

Extension Structure

The basic structure of a bloc set extension starts with a parent directory that has the custom bloc set name, inside this directory you will need to create a child directory named images and a Javascript file named core.js. All custom bloc set user interface images will go into the images directory and the Blocs extension programing will go in the core.js file

Writing Bloc Set Layouts

When writing a bloc set layout you use a kind of shorthand version of HTML to create the code rather than full HTML. For example, rather than writing the following.

<div class="row">
    <div class="col-md-12">
         <h3>
            My Title
         </h3>
    </div>
</div>

We can just use:

row + col12 + header(3,'My Title') + ctag

This makes writing custom layouts for Blocs much faster and also makes working with the HTML arrays that the addBlocOptions(); call requires a lot more manageable. You can view all the available HTML shortcodes here.

Core.js Example

Here is a basic core.js example of a simple two option custom Bloc set. You will notice first we set up the sets name as a variable and then create the HTML and image asset arrays. This data is then all fed into the API calls at the end of the script.

var setName = "customBlocSet";

var htmlArray = [
    "row+col12+img+header(2,'My Title')+para(ipsum)+ctag",
    "row+col6+img+header(3,'My Title')+para(ipsum)+ctag+col6+img+header(3,'My Title')+para(ipsum)+ctag"
    ];

var imageArray = ["images/bloc-1.png","images/bloc-1.png"];


addBlocSet(setName,'images/icon.png'); // Create Bloc set parent
addBlocOptions(setName, htmlArray, imageArray); // Add option children to set parent

User Interface Image Assets

A custom bloc set requires a number of image assets to be included when compiling to BEX. All assets should be in the PNG file format, you will need to include the following image assets. Please note, for every bloc set option you must include a high and low resolution image asset.


  • icon.png - Bloc bar tab icon (12x12px).
  • optionAssetOne.png - Low res option asset thumb (180x110px).
  • optionAssetOne@2x.png - High res option asset thumb (360x220px).

Style Guide

It's important that the graphics you use in your custom Bloc sets adhere to the general aesthetics of the Blocs application with regard to colour usage and overall design. In the Blocs EDK you will find a colour guide along with icon and button templates that you can use as the base for your designs. Please take care to make your custom interface graphics as sexy as the rest of Blocs.


Once your Bloc set extension is written and you have all of your assets created, you will need to first compile it to the .bex extension file format in order to use it with Blocs. You can read more about compiling to BEX here.

BLOCS EDK

Full EDK coming soon.

COMPILING

Once your extension is ready you can compile it using the DevTools in the Blocs application. These tools can be found in the main menu under Help > Dev Tools > Compile Extension.

When you select to compile an extension you will be asked to select the file you wish to compile. If you are compiling a style extension you should select the javascript file that contains your extension code, if you are compiling a custom bloc set you should select the parent directly of your custom bloc sets core.js file.

After selection Blocs will compile your extension and place the .bex file at the same level as the file or folder you submitted to compile.

INSTALLING

To install an extension into Blocs, open the Blocs app and then double click on the .bex file you wish to install. After installation is complete you will be notified that your extension can now be used. When you next open the Blocs main design window you should find your style extensions under the style group you applied them too and your custom bloc sets in the bloc bar under there own tab icon.