Hi Fam
Download
One app, a dozen lessons: reading the SithasoDaisy5 SQLite Address Book
Most sample apps teach you one thing: how to insert a row. You copy the insert, you change the table name, and you move on. Then you try to build something real and discover that the hard parts were never the insert — they were the lookups, the validation, the report, the dashboard, the thing that keeps your build from deleting the database.
This address book is worth reading slowly for exactly that reason. It is small enough to hold in your head — four pages, three tables, four libraries — but it carries most of the patterns a working web app needs. It is less a demo than a pattern catalogue with a UI attached.
Everything below is drawn from the actual project source, so you can open the modules side by side.
1. What the app is
Four pages, reachable from a slide-out drawer:
• Dashboard — three counter cards, a gender pie chart, a letter-distribution column chart.
• Contacts — the full record: name, mobile, telephone, email, category, gender, address, province, postal code.
• Categories — a lookup table with a colour per category.
• Provinces — a plain lookup table.
The data lives in SQLite, served by
sithasobase, a small PHP REST layer (sithasobase/php/api.php) that maps table names to endpoints. The UI is
SithasoDaisy5 (daisyUI + Tailwind components) driven from
BANano, which transpiles your B4J code into JavaScript. The B4J project itself is JavaFX only because that is the host that compiles the app and opens your browser; nothing B4J-flavoured ever reaches the client.
Four libraries do all the work: banano, sithasodaisy5, plus jcore and jfx for the host.
2. The two-phase lifecycle (the part that trips up desktop developers)
If you come from B4J desktop, you expect AppStart to be where your app begins. In BANano it is where your app is built. The code you want to run — the code that touches the DOM — starts in BANano_Ready.
Sub AppStart (Form1 As Form, Args() As String)
BANano.Initialize("BANano", AppName, DateTime.now, AppName)
BANano.Header.Title = AppTitle
...
BANano.Build(Publish)
End Sub
Sub BANano_Ready
Dim env As Map = BANano.Await(BANano.GetFileAsJSON("./assets/env.json?" & DateTime.Now, bfo))
ApiKey = env.Get("apikey")
ServerURL = env.Get("apiurl")
...
pgIndex.Initialize
End Sub
AppStart configures the header, the PWA icons, the transpiler options, then calls Build.
BANano_Ready is the first frame of your application's life in the browser.
Two things in BANano_Ready are worth stealing outright. It reads configuration from a file, not from the build. env.json holds the API URL, host, driver, and key. Republish to a different server and you edit one JSON file instead of recompiling. It builds a version gate. env.json carries a version string. If it no longer matches the compiled Version, the app reloads itself:
If AppVersion <> "" Then
If Version <> AppVersion Then
BANano.Location.Reload(True)
Return
End If
End If
That is a two-line answer to "why are my users seeing last week's JavaScript?" — the question every web developer eventually asks.
3. The shell: a layout, a drawer, and a naming convention
baselayout.bjl is where the furniture lives: a drawer, a navbar that owns the hamburger, a pageview container for content, a right drawer and a bottom drawer you can open later if you need them.
pgIndex.Initialize wires it up:
BANano.Await(App.Initialize(Me))
BANano.LoadLayoutAppend(App.Here, "baselayout")
appnavbar.Title = "My Address Book"
BANano.Await(AddDatabaseSchemas)
BANano.Await(App.UsesFontAwesome)
BANano.Await(App.UsesExcel)
BANano.Await(App.UsesColorWheel)
Note the Uses* calls. Font Awesome, ExcelJS, the colour wheel, the date picker and the chart library are not in the initial download — they are fetched on demand by UsesFontAwesome, UsesExcel, UsesColorWheel, UsesInfoBox, UsesToastChart. Load what your shell needs up front, load the rest when a page asks for it.
Navigation needs no router. The menu items carry a composite key and the click handler splits it:
Sub CreateDrawerMenu
drawermenu.AddItemChild("", "contacts-dashboard", "./assets/gauge-high-solid.svg", "Dashboard")
drawermenu.AddItemChild("", "contacts-list", "./assets/users-solid-full.svg", "Contacts")
End Sub
Private Sub drawermenu_ItemClick (item As String)
Dim sprefix As String = App.UI.MvField(item, 1, "-")
Dim ssuffix As String = App.UI.MvField(item, 2, "-")
Select Case sprefix
Case "contacts"
Select Case ssuffix
Case "list"
pgContacts.Action = "L"
pgContacts.Show(App)
Return
End Select
End Select
End Sub
page-action as a string, MvField to take it apart, a Select Case to dispatch. It costs nothing, it is readable, and it is honest about what a router is: a lookup from a name to a function.
4. Define the schema once
Every page needs to know the shape of the tables. The app declares that in one place, in `pgIndex`:
Sub AddDatabaseSchemas
App.AddDataModel("categories", "id", False)
App.AddDataModelStrings("categories", Array("id","name","color"))
App.AddDataModel("contacts", "id", False)
App.AddDataModelStrings("contacts", Array("id","fullname","letter","mobile", ...))
End Sub
Every page then simply says:
db.SetSchemaFromDataModel(App.DataModels)
One definition, reused by every read, write, count and raw query. When you add a column, you add it here and every page knows about it. This is the single highest-leverage line in the whole project. This can also be configured to be read from the database itself without manual intervention and for demonstration purposes has been left.
5. The list page anatomy
Categories and Provinces are the same page wearing different column names. Once you can read one, you can read all three list pages — and you can generate the fourth. Every one of them starts with the same five beats:
Public Sub Show(MainApp As SDUI5App)
App = MainApp
App.PagePause
pgIndex.PageViewPaddingTo10px
App.PageViewToFullScreenHeight(Array("appnavbar"))
BANano.LoadLayout(App.PageView, "categoriesview")
BANano.Await(BuildCategoriesTable)
BANano.Await(BuildCategoriesModal)
BANano.Await(MountCategories(False))
App.PageResume
End Sub
Load the layout. Build the table. Build the modal. Mount the data. Resume.
`App.PagePause` and `App.PageResume` bracket the work with a spinner. `BANano.Await` is not decoration: your B4J `Sub` becomes JavaScript, and JavaScript does not block. Every call that crosses the network or waits for the DOM must be awaited, or the next line runs before the first one finishes. If a page "sometimes shows empty data", you are missing an `Await`.
The table is the product. The app does not treat it as a grid of strings; it configures behaviour:
tblCategories.HasAlphaChooser = False
tblCategories.HasColumnChooser = False
tblCategories.HasEdit = True
tblCategories.HasClone = True
tblCategories.HasDelete = True
tblCategories.BackTooltip = "Go back to Dashboard"
tblCategories.AddColumnColor("color", "Color", "name")
tblCategories.AddDesignerColums
tblCategories.UpdateColumnVisibility
tblCategories.MoveBackButton
On Contacts the same idea goes further: `AddColumnAvatarPlaceholder` for the initials bubble, `AddColumnTitleSubTitle("fullname", "Full Name", "mobile")` to stack a name over a number, `AddColumnEmail` to make the address a mailto link, `HasAlphaChooser = True` with `AlphaChooserColumn = "fullname"`, and `SetColumnHidden` for the fields that exist but rarely need to be seen.
Pagination state survives a round trip. Before any edit, delete or clone the page calls `tblCategories.SaveLastAccessedPage`, and after reloading it calls `ShowLastAccessedPage`. The user stays where they were. That one detail is the difference between an app that feels considered and one that feels like a demo.
#SharingTheGoodness