Bannerflow

Enables development of custom widgets for the Bannerflow platform within your favourite, local IDE. This is not currently a fully featured alternative to Bannerflow's Monaco based online dev environment and it may never be but it does offer some advantages, especially when working on large widgets with complex logic.

Pros

1. Work in you preferred IDE.
2. Version your widget code as you would a standard dev project.
3. Work on your widgets while offline
4. Better, more flexible use of screen space while coding.

Cons

1. Platform based elements such as image and font libraries are not available and must be fudged.
2. Finished code must be manually copied across to a Bannerflow widget.
3. Not all the properties, methods and objects available in the online editor are included.

Usage

Install globally with NPM

npm i -g bannerflow-cli

Then run the following commands

mkdir my-widget
cd my-widget
bannerflow
npm i
npm start

This will create a project structure within my-widget. In the included /src folder you will find a Typescript, CSS and HTML file that mimic the structure of a widget in the online editor.
The preview will show a blank widget and a sidebar with your placeholder properties and custom events. Clicking the widget brings up the transformation rectangle allowing you to resize the widget as well as drag it around to change its position.

The CSS and HTML files in /src are identical to their online counterparts but the Typescript file contains some additional code for setting up properties, custom events and layout config.

import {Widget, WidgetEvent} from "bannerflow-env";

//Initialise the emulated Widget.properties values
Widget.init({
        widgetId: "foo"
    },
    [
        {
            key: 'my-event',
            data: {
                count: 10
            },
            duration: 5
        }
    ]);

/*
From here on the code should match the Bannerflow dev environment exactly
Code should be able to copy/pasted back and forth without errors or manual changes
 */
Widget.on(WidgetEvent.PropertyChanged, ()=>{
    console.log('Properties changed');
    const el = document.getElementById('foo') as HTMLDivElement;
    el.innerText = Widget.properties.widgetId;
});

Widget.on(WidgetEvent.Resize, ()=>{
    console.log('Widget Resized')
})

Widget.onCustomEvent('my-event', (evt)=>{
    console.log(`Custom Event ${evt.key} | count:${evt.data.count} | duration:${evt.duration}`);
});

The first line imports dependencies that mimic the Widget and WidgetEvent objects required to build Bannerflow widgets.

The call to Widget.init() is where you set up your properties, custom events initial layout.

After that the code mimics that which you would write in the online editor. Develop your logic here then copy it into a blank widget on the Bannerflow platform to use it in your projects there.

Fonts

The platform based font library is not available within this environment. If you want to use a specific font during development you can do so by placing the font file in to the /fonts directory and setting a special property that instruct the bundler to include it.

Widget.init({
    aFont: Widget.FontLib,
});

Setting the aFont property to Widget.FontLib instructs the bundler to use the font file in /fonts. This allows you to specify the font in a way that will transfer directly to the online editor when you are ready to deploy.

Widget.on(WidgetEvent.PropertyChanged, async () => {
    await Widget.properties.aFont.createFontFace();
    document.body.style.fontFamily = Widget.properties.aFont.id;
});

Images

The platform based image library is not available within this environment. To use images in your widget add them to the /images directory and reference them from a property.

Widget.init({
    someImage: `images/aTestImage.jpg`
});

you can then use the property in your code in a way that will transfer directly to the online editor when you are ready to deploy e.g...

el.style.backgroundImage = `url("${Widget.properties.someImage}")`;

Custom Events

If your widget needs to listen for a custom event you can add a matching trigger to test this by passing an Array as the second argument to Widget.init().
Each item in the Array describes a custom event and these will be displayed in the right toolbar below the properties along with a button to dispatch them as required.

Widget.init({
        labelProperty: 'HELLO',
    },
    [
        {
            key: 'change-size',
            data:{
                count: 10,
                duration:5
            }
        }
    ]
);

The above example will setup a trigger for the custom event change-size which can be listened for in your code in the standard way. The provided data Object will be delivered as the payload on the received event

Widget.onCustomEvent('change-size', (data)=>{
    console.log(data);
})

Initial Layout

By default your widget will load with a width and height of 200px and it will be positioned at the top left of the browser window. If you would prefer a different initial size or position you can pass a third argument to Widget.init() that specifies one or more of top, bottom, left or right in px. Any values you supply will be used as the defaults when refreshing the display.

Widget.init(
    {labelProperty: 'HELLO',},
    [{key: 'change-size'}],
    {
        top: 50,
        left: 120,
        width: 500,
        height: 75
    }
);

Available API Members

The project exposes replicas of the available API calls but currently only a subset are available.
Eventually all those that are applicable to single widget development will be included but at this point you are able to use th efollowing.

Widget

| Member | Details | |-------------------------------------------------|------------------------------------------------------------------------| | Widget.on() | Can be called with the subset of WidgetEvent properties listed below. | | Widget.onCustomEvent() | See the Custom Events section for details on how to add custom events |

WidgetEvent

| Member | Details | |-------------------|--------------------------------------------------------------------------------------------------------| | PropertyChanged | Trigger the callback with the data object specified | | Resize | Triggers the callback when the widget initialises and when it is resized via the boundiong box handles | | Click | Triggered when the widget is clicked |

Roadmap

As it stands this is very much a work in progress and contains just the bare minimum to get me, the developer, working in the way I needed to work. The next steps all revolve around achieving a closer and closer match with the online editor environment as well as implementing some additional benefits that the local environment can offer. Future development will focus on...

Bannerflow objects and properties

Implement remaining Bannerflow objects such as Timeline, Creative etc

SASS and Typscript bundling

Allowing the use of SASS and the ability to import external modules into your main widget file. These would then bundle together into single files ready for deployment