B4J Tutorial [BANanoWebix]: Lesson 1 - Understanding the layout of a Webix SPA

Ola

Reference: Proof of Concept

A couple of days ago i started on about a proof of concept I am working on. A wrapper of the Webix framework to create BANano based apps.

What is Webix and Why?

Webix is an HTML5/CSS3-based UI toolkit that helps you build complex and dynamic web apps that are cross-browser and even cross-platform. That means your Webix-based apps will work consistently in virtually any modern browser on virtually any modern platform, including mobile devices. Webix provides a robust set of UI components that provide all the standard things you see in modern UIs including rich
form controls, grids, scrolling lists, calendars, charts, layout elements (tabs, accordions, etc.), and so on. Also, it provides a strong collection of more general-purpose functions that are frequently needed when developing SPAs.

BANano on the other hand is a library that enables one to build SPAs however one can use whatever UX framework they desire. Me in this case Webix.

Whilst there is UOENow, UOEBANano, BANanoJQM amongst some of the UX libs I have worked on for my BANano based apps and websites (and some just for fun), the reason behind Webix is merely simplicity, beauty and speed. For example, creating a form is as simple as creating this object:

{
"view": "form",
"elements": [
{
"view": "text",
"name": "firstname",
"label": "firstname",
"labelWidth": "100"
},
{
"view": "text",
"name": "lastname",
"label": "lastname",
"labelWidth": "100"
},
{
"view": "text",
"name": "birthdate",
"label": "birthdate",
"labelWidth": "100"
},
{
"view": "text",
"name": "gender",
"label": "gender",
"labelWidth": "100"
}
]
}

Understanding the layout of a Webix SPA

Webix provides a layout system that allows you to realize any organizational structure you want of your app. Below we create a layout that has rows and columns, some css and a button to click that shows a toast. This is depicted as...

I have included the row positions here for ease of referal, e.g. R1, R2, R3C3 etc.

To create something like this we need to create objects that will fit into a layout of our page. We will use BANanoWebix for that, a lib that we have created to help us work around our Webix projects.

The WebixElement

At the heart of every component in this webix library will be the WebixElement class. This is just the class we have created to help us do things a little faster. It works with Sets statements. Eg to set the width of the element object one uses SetWidth(x) etc etc.

WixElement

• SetGravity (g As Int) As WixElement
  set gravity
• SetView (v As String) As WixElement
  set view
• SetType (t As String) As WixElement
  set type
• SetHeight (h As Int) As WixElement
  set height
• SetWidth (w As Int) As WixElement
  set width
• SetCSS (cs As String) As WixElement
  set width
• SetAttr (attrName As String, attrValue As Object) As WixElement
  set an attribute
• SetHTMLAttr (attrName As String, attrValue As Object) As WixElement
  set a html attribute
• Item As Map
  return the object
• SetIcon (i As String) As WixElement
  set icon
• SetLabel (l As String) As WixElement
  set label
• SetClick (c As BANanoObject) As WixElement
  set click
• AddResizerToColumns As WixElement
  add resizer
• SetTemplate (t As String) As WixElement
  set template
• AddColumns (itm As Map)
  add item to a column
• AddRows (itm As Map)
  add item to a row
• AddItem (itm As Map)
  add on elements
• AddRow (wxEL As WixRow)
  add a row
• AddToRows (prt As WixElement)
  add to rows of parent
• AddToColumns (prt As WixElement)
  add to columns of parent
• AddColumn (wxEL As WixColumn)
  add a column
• SetOnContent (Prop As String, PropValue As String)
  update property when not blank
• SetOnCondition (Condition As Int, Prop As String, PropValue As Object)
  update property when size > 0

The most important of these properties of course is the "view" and the "type" and a little bit of the template for now.

SetView(x) for example will indicate what type of view an element will be e.g. text, date, select etc. The template set by SetTemplate can be text of HTML content to apply to the outside appearance of the Text to appear on the element.

So for our exercise, we create a variety of rows, add some columns to the rows and a button element. We also add a click event to the button to show a toast.

The WebixElement is built in such a way to be dynamic so that one can add additional methods and properties as we go along.

We have added some resizers on the columns on row 3 so that we can resize them, and this we are not even writing any HTML as yet. Cool.

 

[Mashiane]

The Page Code

As we are creating an SPA, we create a module that will contain the page of our app which will be fed to the "body" element. Remember, when we initialize BANano and execute BANano_Ready, the body of the page gets created automatically. We just need to feed this body and replace it with our content.

The WebixPage is the main object for us to create a page for our app and will be the basis for additional pages in our app should we add more. Adding another page is simple as creating its layout and just overwriting the "body" element of the already created page. With Webix, for each ui you create you can just specify the id of the housing container and everything will be set for you.

We created a code module and placed the code there and in BANano_Ready we call the Init method of this page.

'Initializes the pagae
Public Sub Init()
    Dim e As BANanoEvent
    'initialize the page, we want it to be a layout and the type should be wide
    pg.Initialize("mylay").SetView("layout").SetType("wide")
    
    'row 1, make it a header with Hello content and add it to the rows collection of the page
    Dim R1 As WixElement
    R1.Initialize("R1").SetType("header").SetTemplate("R1: Hello").AddToRows(pg.Page)
    '
    Dim R2 As WixElement
    R2.Initialize("R2").SetTemplate("R2: Greetings, human!").AddToRows(pg.Page)
    '
    Dim R3 As WixElement
    R3.Initialize("R3").SetGravity(2)
    ' create a column and add it to R3
    Dim R3C1 As WixElement
    R3C1.Initialize("R3C1").SetCSS("col1").SetTemplate("R3C1: Webix").AddToColumns(R3)
    '
    R3.AddResizerToColumns
    '
    Dim R3C2 As WixElement
    R3C2.Initialize("R3C2").SetCSS("col2").SetTemplate("R3C2: Is").AddToColumns(R3)
    '
    R3.AddResizerToColumns
    '
    Dim R3C3 As WixElement
    R3C3.Initialize("R3C3").SetCSS("col3").SetTemplate("R3C3: Cool").AddToColumns(R3)
    '
    R3.AddToRows(pg.Page)
    '
    Dim R4 As WixElement
    R4.Initialize("R4").SetType("header").SetTemplate("R4: Goodbye").AddToRows(pg.Page)
    '
    Dim r5 As WixElement
    r5.Initialize("R5").SetHeight(50)
    '
    Dim R5C1 As WixElement
    R5C1.Initialize("R5C1").SetTemplate("Fare thee well!").AddToColumns(r5)
    '
    Dim r5c2 As WixElement
    r5c2.Initialize("R5C2").SetView("button").SetWidth(150).SetType("iconButton").SetIcon("users").SetLabel("Click for fun")
    r5c2.SetClick(BANano.CallBack(Me,"r5c2_click",e))
    r5c2.AddToColumns(r5)
    '
    r5.AddToRows(pg.Page)
    'render the page
    pg.ui
End Sub

Sub r5c2_click(e As BANanoEvent)
    pg.ToastError("See?<br><br>Wasn't that fun?!")
End Sub

The rows for the page are kept in a Rows list inside our WebixElement and also Columns are defined as a list. We have created 5 rows here and in Row 3 we have added some columns and also on row 5 where we have our button.

For the button to be clicked, the "click" key of our object is set to a BANano Callback. This is rather different than using HandleEvents or On methods in BANano. One just sets the click object key and this things does all the addevent handlers for you.

When the button is clicked, we show a red toast. After all is done we call our pg.UI method to build the User Interface. This is basically a banano call to the internals of Webix to do its magic!

'render the page UX
Sub UI
    webix.RunMethod("ui",Page.item)
End Sub

This basically applies the object which is a b4j map to the "ui" method of our "webix" object.

WebixElement returns the object/map via the Item method.

Whilst normal based components e.g. WebixButton, WebixLabel, WebixHeader etc are available in the library, this intro was to take one deep into the origins of the base class that rules all others.

Ta!

 

[Mashiane]

Final Words

The publish folder for my demo here is Publish = "C:\xampp\htdocs" and this is where BANano builds the Webix project I have created here based on..

BANano.Initialize("BANano", AppName,1)

and on build

BANano.Build(Publish)

This is depicted as

So on each release of my app, I can just upload these to the webix folder on my webserver via FTP and have a website running.

Where to get BANanoWebix?

Get your own copy of the BANanoWebix library open source code here.