New Controls

Three new controls have been added to the Web framework in this release, aiming to close the difference gap between Web and the other project types.

WebSwitch is a toggle control that mobile developers will already be familiar with. It’s been available on iOS and Android for a while. It’s now available for web projects too, so if you’ve been approximating a toggle switch using a styled checkbox, you can finally retire that workaround.

WebColorPicker brings color selection to web apps in the same way DesktopColorPicker does for desktop. Drop it in from the Library, wire up the event and you have a color picker the Xojo way.

This is how WebColorPicker looks like in your browser:

The third new control adds barcode reading support. Your web app can now read barcodes directly from the user’s camera, from desktop or mobile browsers. This opens up a lot of practical use cases: Inventory systems, ticketing, product lookups, that previously would have pushed you toward a native mobile app.

Again, drop the Barcode control into your project and implement the events:

That’s it! Your web apps can scan a great variety of barcodes now. Including QR, Data Matrix, Aztec, PDF 417 and much more!

Icons on WebButtons

WebButton now has an Icon property. You can assign any WebPicture to it, or use one of the Bootstrap icons that are already bundled with the framework. It’s a small addition, but it makes a noticeable difference when building action-heavy interfaces where a label alone doesn’t communicate enough at a glance.

Add a button into your project:

Configure its Icon property in the Opening event:

Me.Icon = WebPicture.BootstrapIcon("key-fill")

If you don’t specify a color in BootstrapIcon, it will inherit the button caption color in this case. This is the easiest way to support Dark Mode with the new WebButton.Icon property, without doing any special tricks.

Here is how it looks like at runtime:

Dark Mode:

WebLabel: Semantic HTML and Proper Element Types

Two related changes landed for WebLabel in this release. The first is a correctness fix: the control was previously rendered using the HTML <label> element, which is semantically meant to label form inputs, not to display general text. That has been corrected.

The more interesting addition is that you can now choose which HTML element WebLabel renders as. If you want a label to be an <h1> or an <h2>, you can set that directly in the Inspector. This is useful not just for visual styling, but for accessibility tools and search engines that rely on page structure to understand content hierarchy.

Improving both, accessibility and making search engines happier, are some of our goals for 2026. You will continue seeing improvements in this sense.

WebTextArea Gets AddText

WebTextArea now has an AddText method, consistent with how the control works on Desktop and Mobile. If you’re writing code that targets multiple platforms, this kind of parity saves you from having to check which target you’re on, before appending text.

Scale Indicator on WebMapViewer

WebMapViewer now has a HasScaleIndicator property. When enabled, a small visual scale appears on the map showing real-world distance. It makes a difference in apps where users need spatial context. Field work, logistics or anything where “how far is that?” is a question users might actually ask.

Performance and Modernization Under the Hood

A few changes in this release won’t be immediately visible, but they improve things for everyone.

Bootstrap has been updated to v5.3.8 which fixes some issues introduced in v5.3.7 impacting Xojo. The TypeScript compiler has been updated to v5.9.3, and the compilation target has been bumped from ES6 to ES2020. Unused code in the Web Framework has been cleaned up to reduce the compiled bundle size.

Xojo has also removed its own internal usage of Modernizr. The library is still present for now so existing apps that rely on it won’t break, but it’s no longer used by the framework itself and will be removed in a future release.

If you’ve been meaning to audit your web app for performance, this is a good moment to look at SendEventsInBatches and LazyLoadDependencies on WebSession as well. Both now default to True on new projects, so if your existing app has them disabled, it’s worth trying them out. These properties have been around for a while already but were turned off by default.

API Consistency Cleanups

A few methods have been deprecated in favour of names that are consistent with the rest of the framework:

• WebApplication.AutoQuit → AllowAutoQuit
• WebListBox.ReloadData → ReloadFromDataSource
• WebRadioGroup.RemoveAllRows → RemoveAll, and RemoveRowAt → RemoveAt

Your existing code will still compile, but it’s worth updating these when you get a chance.

Wrapping Up

Between new controls, better HTML semantics, and a leaner runtime, 2026r1 is a worthwhile update for anyone building web apps with Xojo. Check out the full release notes for the complete list of changes.

Ricardo has always been curious about how things work. Growing up surrounded by computers he became interested in web technologies in the dial-up connections era. Xojo has been his secret weapon and language of preference since 2018. When he’s not online, chances are he will be scuba diving … or crocheting amigurumis. Find Ricardo on Twitter @piradoiv.

• Facebook
• X
• LinkedIn
• GitHub
• YouTube

Using a WebPopupMenu with a Keyboard

2024r4 comes with keyboard full support for WebPopupMenu. We’ve been gradually improving this control to allow your users to select a field using the arrow keys, for example. What’s new is being able to go directly to one of the item just by starting to type its name.

Memory Usage Improvements

Everyone does their best to avoid leaking memory but, sometimes, that’s just not enough.

Jérémie Leroy is known for the success of the mobile apps he makes with Xojo. When one of these successful app requires a Web Service, receiving 1000s of requests, it needs to be as lightweight as possible.

Thanks to his reports, the visual controls will be creating Tooltip and WebCSSClasses instances only when being used. For many projects this won’t make a difference, but having a Web project with hundreds of concurrent users will surely lead to less memory pressure, allowing to run Web apps in cheaper servers.

This task never ends. Upcoming releases will continue improving memory usage and performance.

WebMapViewer

The library we use to display maps, MapLibre, has been upgraded from 3.2.0 to 4.7.1, which will make much easier to implement some of the features we want to introduce in upcoming releases. Stay tuned!

This control also received 4 additional bug fixes. One of them was causing the Zoom to be modified, when updating another control property, for example.

Some New Features

While Web received mostly bug fixes this time, it also comes with some hidden gems.

Popover position can be adjusted now when displaying it. The positioning is relative to its parent control. Additionally, you can now use a WebPage as the parent control, instead of one of the page children, to place your Popover exactly where you need.

Last, but not least, my favorite new feature. We’ve added CallLater method to WebTimer. It works exactly the same as Timer.CallLater, but it’s Session aware. This means you will be able to access the Session from its callback, without having to do anything special.

Wrapping Up

We are saying goodbye to a 2024 packed with improvements for the Web target, with a release dedicated (more than usual) to bug fixing and to make everything more stable. Make sure to check Xojo 2024r4 Release Notes, so you don’t miss anything.

Thanks to everyone reporting bugs, making feature requests and collaborating in the forum!

Ricardo has always been curious about how things work. Growing up surrounded by computers he became interested in web technologies in the dial-up connections era. Xojo has been his secret weapon and language of preference since 2018. When he’s not online, chances are he will be scuba diving … or crocheting amigurumis. Find Ricardo on Twitter @piradoiv.

• Facebook
• X
• LinkedIn
• GitHub
• YouTube

A Quick Reminder About What Bootstrap Is

As I will be mentioning it during this post, let me take a moment to remind readers what Bootstrap is, and what are we using it for at Xojo.

Bootstrap is the library we use for the visual part of web applications made with Xojo. You can think about it as Gtk on Linux, or UIKit on iOS.

While there is a vast amount of alternative libraries, it’s been probably the most popular framework for the last decade. You can check the Bootstrap website for more information.

ColorGroup Named Colors

Until this release, the Named option when configuring a ColorGroup was not available on web projects. 2024r3 brings the ability to choose from the Web Basic colors, Web Extended colors and, what I find more interesting, Bootstrap colors, which also support dark mode out of the box.

As you can expect, if you drop a custom Bootstrap 5.3 theme with another set of colors, the IDE will automatically update in order to preview them.

Using Named Colors by Code

When a dynamic need arises, it is also possible to use Bootstrap Named colors programmatically, if you find it easier. Here is an example:

Var colorName As String

If paymentCardIsValid Then
  colorName = "success"
Else
  colorName = "danger"
End If

Rectangle1.BackgroundColor = ColorGroup.NamedColor(colorName)

Or in a WebCanvas.Paint event:

Var colorName As String = If(paymentCardIsValid, "success", "danger")
g.DrawingColor = ColorGroup.NamedColor(colorName)
g.FillRectangle(0, 0, g.Width, g.Height)

You can check the list of available colors in the Color section of the official Bootstrap documentation. Basic and Extended Web Colors will work as well.

Using Bootstrap CSS Classes

Bootstrap comes with a set of utility CSS classes for a variety of visual things. You probably won’t need them all, as the Xojo IDE will get you there in most of the cases, and we work hard improving the IDE to make it easier, release by release.

That said, if you are an advanced user, and you have previous experience working with Bootstrap, you may find it useful to add CSS classes directly from the Inspector.

Go to the Advanced tab, add some Bootstrap CSS classes, separated by spaces… and voilà!

Here is a demo:

We have included a new example, called “Applying Bootstrap CSS classes to controls”, that you can find under Platforms > Web. Please give it a try.

CSS Classes are not limited to Bootstrap, if you have added styles in the HTML Header section, you can use them as well.

You can also add and remove them using the new CSSClasses property, which is available in every WebUIControl subclass.

WebRectangle Got Some Love

You won’t need to setup the border color, border thickness or the corner size, for WebRectangle, in the Opening event anymore.

When designing web applications, I found myself using a lot of WebRectangle controls and, by default, they have a rounded border.

The side-effect is subtle, but now that you can control the border radius directly from the Inspector, the IDE preview will be closer to how it will look in the browser. And you are going to avoid writing a few lines of code!

In addition, some Bootstrap themes define a different Corner Size. Setting this property to “-1” will honor that Bootstrap theme’s default border radius.

Conclusion

As always, the release comes with much more than I can tell you about in one blog post. With over 30 Bug fixes and 9 Feature Requests implemented in the Web target alone, make sure to take a look at the Xojo 2024r3 Release Notes to see the whole picture.

Happy coding!

Ricardo has always been curious about how things work. Growing up surrounded by computers he became interested in web technologies in the dial-up connections era. Xojo has been his secret weapon and language of preference since 2018. When he’s not online, chances are he will be scuba diving … or crocheting amigurumis. Find Ricardo on Twitter @piradoiv.

• Facebook
• X
• LinkedIn
• GitHub
• YouTube

What’s New in Xojo 2024 Release 3

We’ve been working hard to bring you the best possible cross-platform development experience, and Xojo 2024 Release 3 delivers. Here are some of the highlights:

These updates and enhancements are designed to make your development experience more efficient, productive, and enjoyable. Whether you’re building a new application or updating an existing one, Xojo 2024 Release 3 provides you with the tools and capabilities you need to succeed.

Get Started

To learn more about Xojo 2024 Release 3 and to get started with the development process, please visit the Xojo 2024r3 Release Notes. The update can be downloaded right now, from the Xojo downloads page.

What’s Next?

We’re always working on new features, updates, and enhancements to our platform. If you have any suggestions or ideas, please don’t hesitate to add them to the Xojo tracker. We’re always looking for ways to improve and expand Xojo.

Thank you for being part of the Xojo community. We’re excited to see what you’ll create with Xojo 2024r3!

• Facebook
• X
• LinkedIn
• GitHub
• YouTube

Why would you need a WebDataSource, isn’t AddRow enough?

If you are making a quick prototype, or for small data sets that won’t grow too much, yes, you can absolutely place a WebListBox into your WebPage and fill it using AddRow. If your WebListBox displays a fixed, small amount of data, say around 500~1000 rows, WebDataSource can be overkill.

However, for data that comes from a large database, it’s a different story. You could waste precious server resources duplicating the same data you have in your database into your app’s memory. And even worse, the data would be duplicated in every Session seeing that WebListBox.

In this tutorial, this is the WebListBox we are going to build:

Let’s prepare a million records database to play with.

In this example we will use a humble SQLite database, but keep in mind a WebDataSource can be anything. For example you could display the result of calling an external API, or your hard drive filesystem.

The following SQL creates a table called “things”, with three columns: “foo”, “bar” and “baz” with one million rows:

CREATE TABLE things (
  id    INTEGER PRIMARY KEY AUTOINCREMENT,
  foo TEXT,
  bar TEXT,
  baz TEXT
);

-- Time to populate that table
WITH RECURSIVE cnt(x) AS 
(
   SELECT
      1 
   UNION ALL
   SELECT
      x + 1 
   FROM
      cnt LIMIT 1000000
)
INSERT INTO things (foo, bar, baz)
SELECT
    'foo_' || x AS foo,
    'bar_' || x  AS bar,
    'baz_' || x AS baz
FROM cnt;

-- Finally, let's create some indexes, so we can sort the columns quickly
CREATE INDEX "idx_foo" ON things (
    foo, id, bar, baz
);

CREATE INDEX "idx_bar" ON things (
    bar, id, foo, baz
);

CREATE INDEX "idx_baz" ON things (
    baz, id, foo, bar
);

VACUUM;

We just need to store this SQL as a string constant, for convenience. Let’s create one, called kDatabaseSetupSQLite in your Application class, and paste it above the SQL code.

First Time Setup

The first time we launch the application, we need to make sure our database file has been created and populated. It won’t take too much to generate the database, but we’ll try to do it just once anyway.

Create a new method in your App class, called DBFile, that returns a FolderItem, pointing to the place we want to store the DataBase. Make it Public, as we will use this method later from the Session. The contents:

Return SpecialFolder.Desktop.Child("test-db.sqlite")

Nothing fancy. Use another path if you want. It will be around ~200MB, just remember to delete it when you don’t need it anymore.

Let’s create another App method, called SetupDatabase. It will be in charge of creating and populating the database just once, so if you restart the server, the data will still be there:

Var db As New SQLiteDatabase
db.DatabaseFile = DBFile
db.WriteAheadLogging = True

// The file is already there, no need to build it again
If db.DatabaseFile.Exists Then
  Return
End If

db.CreateDatabase
db.Connect
db.ExecuteSQL(kDatabaseSetupSQLite)

Lastly, implement the App.Opening event and add a method call to SetupDatabase:

SetupDatabase

That should do the trick.

Preparing the Session

It’s recommended to have a Database instance for each Session. Add a new public Property to your Session class called Database of type SQLiteDatabase.

Then, add a handler for the Opening event with the following code:

Database = New SQLiteDatabase
Database.DatabaseFile = App.DBFile
Database.WriteAheadLogging = True
Database.Connect

Every time a user arrives to the web application, a new isolated SQLiteDatabase connection will be created.

Implementing the WebDataSource Interface

Since Xojo 2024r2, the amount of methods you need in order to implement WebDataSource has been reduced.

Create a new class called DatabaseDataSource. Then, in the inspector panel, select the WebDataSource interface:

This includes the three required methods: ColumnData, RowCount and RowData.

ColumnData
In this method, you need to return an array of WebListBoxColumnData. We have four columns in this example, here is the code:

Var result() As WebListBoxColumnData
result.Add(New WebListBoxColumnData("ID", "id"))
result.Add(New WebListBoxColumnData("Foo", "foo"))
result.Add(New WebListBoxColumnData("Bar", "bar"))
result.Add(New WebListBoxColumnData("Baz", "baz"))

Return result

RowCount
Xojo needs to know the amount of data your data source has. Returning an Integer is enough, but we will query our database.

Try
  Var rows As RowSet = Session.Database.SelectSQL("SELECT COUNT(*) AS counter FROM things")
  Return rows.Column("counter").IntegerValue
Catch DatabaseException
  Return 0
End Try

RowData
This is the place where you need to return the row contents. As you can see, there is a rowCount and a rowOffset parameter, meaning that we won’t need to return 1 million records. The control just loads a subset. The amount is dynamically calculated, and varies depending on the height of your WebListBox and the height of the rows.

A sortColumns parameter is also provided. If you allow your users to sort the columns, you need to use it to know the column and direction. Fortunately, this example has sortable columns. Here is the code to comply with the WebDataSource Interface:

Var sql As String = "SELECT id, foo, bar, baz FROM things"
If sortColumns <> "" Then
  sql = sql + " ORDER BY " + sortColumns
End If
sql = sql + " LIMIT " + rowOffset.ToString + ", " + rowCount.ToString

Var result() As WebListBoxRowData
Var rows As RowSet = Session.Database.SelectSQL(sql)

// This isn't needed, it's just to demonstrate how to use cell renderers
Var style As New WebStyle
style.Bold = True
style.BackgroundColor = Color.Teal
style.ForegroundColor = Color.White

For Each row As DatabaseRow In rows
  Var newRowData As New WebListBoxRowData
  newRowData.PrimaryKey = row.Column("id").IntegerValue
  newRowData.Value("id") = row.Column("id")
  newRowData.Value("foo") = row.Column("foo")
  newRowData.Value("bar") = New WebListBoxStyleRenderer(style, row.Column("bar"))
  newRowData.Value("baz") = row.Column("baz")
  result.Add(newRowData)
Next

Return result

Preparing the User Interface

You’ve reached the easiest part, building the interface takes less than a minute.

1. Drop a DatabaseDataSource control into your WebPage
2. Drop a WebListBox control into your WebPage
3. In the WebListBox Opening event, configure the DataSource

If you name your DataSource instance “MyDataSource”, this is the line of code required in the WebListBox Opening event:

Me.DataSource = MyDataSource

Here is a short video:

That’s It!

The WebListBox control, when combined with a WebDataSource, is a very robust and performant solution for displaying a large set of data.

Download the project:

Happy coding!

Ricardo has always been curious about how things work. Growing up surrounded by computers he became interested in web technologies in the dial-up connections era. Xojo has been his secret weapon and language of preference since 2018. When he’s not online, chances are he will be scuba diving … or crocheting amigurumis. Find Ricardo on Twitter @piradoiv.

• Facebook
• X
• LinkedIn
• GitHub
• YouTube

Control Sets

There are cases where you have a bunch of controls with the same functionality. Imagine you are coding a calculator and you’ve just added the WebButtons for each digit. It would be repetitive and error prone to add the same code to Pressed events, on each button when the only thing that changes is the numeric value.

A set of controls can be grouped, so you can think about them like if you were using an array. You can add event handlers to the group itself. Events will be enhanced with an “index” parameter, to help you decide what to do, depending on the element.

Create Tabs and Embed Controls at Runtime in WebTabPanel and WebPagePanel

Same as with Control Sets, this is something that was already present in Desktop projects and we wanted to include it for Web. From now on, you will be able to create and remove tabs and pages in WebTabPanel and WebPagePanel controls, respectively. Controls can also be added and removed at runtime, or move controls between tabs or pages whenever you need.

This opens a new world of possibilities for your applications, where you can provide your end users a way to have multiple contexts open at the same time.

WebListBox: Configurable Header and Row Height, Border and Line Style

You will be able to configure the height of WebListBox headers and rows with the same API you are used to using in your Desktop projects. You won’t need to tweak them with CSS anymore.

HasBorder and GridLineStyle has also been added to Web projects, allowing you to remove the outside border, display only vertical lines between the columns… or just remove them.

WebDataSource Interface

Speaking of WebListBox improvements, you’ll find that the WebDataSource is easier to implement. You won’t need to implement SortedPrimaryKeys and UnsortedPrimaryKeys methods anymore.

There are only three methods required now:

• ColumnData: Where you will define the amount of columns, names, and configure if they are sortable
• RowCount: So the control can now the amount of space it will need
• RowData: This is where you return an array of rows

WebListBox lazy load rows, meaning that it will only ask your DataSource for the amount of rows being displayed on screen. It will only fetch more when needed.

WebListBox Improvements When Using a WebDataSource

Using a WebListBox with a DataSource makes it possible to display very large amounts of data. Until now, you were able to display thousands of rows very quickly. This release improves the way Xojo uses your DataSource, without having to change a line of code in your projects.

Scrolling through the data will display the rows much faster than before. Just for comparison, 2024r1.1 was able to display 1 million rows in about 6 seconds in my computer. The same project, using 2024r2, can display them in less than 100ms.

But is not just the speed that has been improved. Its memory footprint has been dramatically reduced as well. Displaying 1 million records in 2024r1.1 used about 1 GB of RAM, where 2024r2 will use just a few MB instead.

I can’t imagine a use case where you need to display millions of rows and scroll through them. But if you find one, you will be able to implement it with Xojo

WebButtons Can be Resized Now

In order to make it easier to migrate your Web 1 projects, you will be able to modify the height of your WebButtons. The web framework will also take care to reduce the font size if needed when the button is smaller.

Individual Indicator for Each Segment of WebSegmentedButton

There are situations where you want to mix different “indicators” (different colors) in a single WebSegmentedButton control. For example, pressing on one of the segments can be a destructive action, so you could use the Danger indicator. By default, segments will use the indicator you set in the Inspector panel, but you will be able now to individually override one of them.

Me.Indicator = WebUIControl.Indicators.Primary
Me.SegmentAt(1).Indicator = WebUIControl.Indicators.Danger
Me.SegmentAt(2).Indicator = WebUIControl.Indicators.Success

Having 4 segments, this will be the result of above example at runtime:

Outlined WebButton and WebSegmentedButton

Some GUIs could become overwhelming, when every button looks like a call to action. The new Outlined property, available in WebButton and WebSegmentedButton controls, can help with heavily loaded interfaces. Here is how it looks like:

Performance, Memory Leaks, Bug Fixes

Last, but not least, 2024r2 comes with great performance improvements. We’ve been improving the web server to handle even more requests per second. If you are using Xojo Web for exposing an API, it will be able to serve more requests in less time. For regular Xojo Web applications, it means it will be able to handle more events and reply to them faster.

Here is a comparison of the same project during the different releases of Xojo:

Latency has also been improved, Xojo is able already to reply in less than 2ms:

If you are still serving Web APIs with Web 1, this is a good opportunity to migrate:

That’s a Wrap!

As usual, I’d like to send a big thank you to everyone taking the time creating bug reports, feature requests and testing beta releases. This wouldn’t be possible without your support.

Ricardo has always been curious about how things work. Growing up surrounded by computers he became interested in web technologies in the dial-up connections era. Xojo has been his secret weapon and language of preference since 2018. When he’s not online, chances are he will be scuba diving … or crocheting amigurumis. Find Ricardo on Twitter @piradoiv.

• Facebook
• X
• LinkedIn
• GitHub
• YouTube

Popovers

Similar to WebDialogs, popovers give you the opportunity to improve your apps’ UX. They are ephemeral screens where you can place text and controls.

Unlike the WebDialog, which is always centered and prevents the user to interact with other controls, Popovers can be placed on specific controls, where that information matters.

Think about them as enhanced “contextual menus” but, instead of just plain text menus, you can add anything you like. Have you ever dreamed of adding a WebMapViewer into some sort of contextual menu? Now you can!

The API is very simple. Create a container, add some controls and that’s it, really. You will just have to create a new instance of that container and show it as a Popover, specifying the control it should be pointing to.

Let’s say you have a container, called “MyTextFieldContainer”, and you want to display it below a WebLabel called “MyLabel”. Here is the code:

Var c As New MyTextFieldContainer
c.ShowPopover(MyLabel)

By default, it will be shown below the specified control, but if you want to show it in a different place, you can use the new DisplaySides enumeration. As easy as this:

Var c As New TextFieldContainer
c.ShowPopover(MyLabel, WebContainer.DisplaySides.Top)

As you can see, Web Projects’ Popovers are just container instances that you will show dynamically. That gives you the opportunity to raise events, add custom computed properties or implement the Observer interface. If you are already familiar with Containers, you already know how to use Popovers. Learn more about Popovers.

Displaying contextual menus programmatically

Sometimes Popovers could be overkill for the task. If you just want to display a menu with some textual items inside, a contextual menu might be enough.

Imagine you have a WebTextLabel where you want to display the contextual menu whenever the user Presses on it. In its Opening event you could define the ContextualMenu:

Var menu As New WebMenuItem
menu.AddMenuItem("Foo")
menu.AddMenuItem("Bar")
menu.AddMenuItem("Baz")

Me.ContextualMenu = menu

Implement the WebLabel.Pressed event and add this code:

Me.ContextualMenu.PopUp

As easy as that.

New RemoveControl method

WebViews controls, like WebPage and WebContainer, now supports removing controls. This gives you the missing piece to create GUIs programmatically, as AddControl was already supported .

This can be useful when you are presenting a form to your end user with an unknown amount of fields.

For example, your user is filling the profile and you want to support having multiple contact fields. Some users will want to add 1 phone, others 2, and others would prefer to be contacted just by email.

Adding and removing controls dynamically gives you the opportunity to build this kind of features. Instead of adding a fixed amount of contact methods, you can adapt your app to what your user really needs.

Performance and memory usage improvements

We’re landing at my favorite part, improvements that nobody will see… unless you want to share your server monitoring stats, which is cool.

2024r1 comes with less Disk I/O usage. In my own benchmarks, Xojo Web is now able to serve about 1200 requests per second via the WebApplication.HandleURL event. That’s around a nice 20% more, compared to the previous version.

Also, thanks to Jeremie Leroy (one of our Xojo MVPs) and Bruno Fréchette, we’ve managed to identify and fix some memory leaks. In 2024r1, your web application will be doing a better job at cleaning up after processing requests.

Bug fixes

The list of fixes is big, you can inspect the whole list in the 2024r1 Release Notes page.

Web fixes by category:

• Compiler: 1
• IDE: 7
• Framework: 40

18 extra regressions were reported and fixed during the beta period. A huge thank you to everyone taking the time to test our releases and reporting issues before the final release becomes available.

Conclusion

We hope you are as excited as we are for this release. I’m personally looking forward to see what you’re building, please remember to mention us on your favorite social network so we all can see what you’re working on.

In the meantime, we are already working hard preparing our next release, 2024r2. Spoilers: You will love it!

Happy coding!

Ricardo has always been curious about how things work. Growing up surrounded by computers he became interested in web technologies in the dial-up connections era. Xojo has been his secret weapon and language of preference since 2018. When he’s not online, chances are he will be scuba diving … or crocheting amigurumis. Find Ricardo on Twitter @piradoiv.

Faster HandleURL Responses

With Xojo Web you can create APIs backing your Mobile or Desktop applications. Just by updating to Xojo 2023r4, your web services will get the benefit of much faster responses and the ability to handle many more requests per second.

Just to compare between different Xojo versions, we’ve created some benchmarks using Xojo Web 1 (with Xojo 2019r3.2) and some Xojo Web 2 releases, 2023r3.1 and the latest one, 2023r4.

Here are the results, returning plain text:

And the same test, but this time returning a string generated by JSONItem:

Xojo 2023r4 is capable of serving around 20x more requests per second compared to Web 1, and around 4x compared to Xojo 2023r3.1. And thanks to the reduced latency time, your API will return the contents much faster.

Faster Transfer Rates in Windows and Linux

While working on performance, we’ve found that applications deployed on Windows and Linux were serving large files much slower than those deployed on macOS servers.

William improved the low level code for sockets on those targets, allowing the server to transfer large files at a much faster speed. During my tests, I’ve seen 10x faster transfer rates.

But this doesn’t affect only our Web target! If you are using a ServerSocket with TCPSocket classes, your Console and Desktop applications will also benefit from these improved transfer rates.

Static Assets Cache Control

In this release, we’ve also improved how the framework interacts with the browser. When your user visits your web application for the first time, it will store all of the required JavaScript and CSS files.

This was already happening in previous releases but with a subtle difference. From now on, the browser won’t even need to check with the server if the file has changed since the last visit. This translates to faster load times for your users and less server load for you since the server won’t need to handle all those requests anymore.

Improved Compile Time

In this release, Xojo Web will compile your projects a few seconds faster. The first time you compile your project, it will cache the result of some processes that are only changing between Xojo releases.

Here is a comparison between 2023r3.1 and 2023r4, both are running a debug session of a blank project:

That’s around 3-4 seconds faster every time a project compiles.

Events Improvements

Some web controls were sending information from the browser to the server more frequently than needed. For example, a WebContainer.Scrolled event was being sent for every scrolled pixel, causing unnecessary server load.

We’ve been reviewing these controls and have made some improvements:

• WebCombobox
• WebContainer
• WebSearchField
• WebTextArea
• WebTextField
• WebUploader

All of them will continue communicating their state updates, but the framework will focus on delivering the latest value available.

For example, in a WebSearchField, if the user writes “hello”, the framework will send the first key press (“h”) as soon as it happens. The next event it will send will depend on how fast the user types, so it can be either “hel” or maybe directly “hello”. What is guaranteed is the TextChanged event will be fired for the final value (“hello” in this example).

New Experimental Option

WebSession has a new experimental option available, disabled by default. “Send Events in Batches”:

Turning it on will make our JavaScript framework group different event notifications in a single request. Projects that contain complex layouts that show and hide several controls at once may benefit from snappier GUIs.

As a side effect, it will also ensure the events arrive to the server in the correct order. Think about a login screen where the user has an email field, a password and a “Login” button with the Default setting turned on (to allow the user to trigger the Pressed event by pressing the Enter key). When sending the events in different requests, because of network latencies, the WebButton.Pressed event could arrive at the server before the last WebTextField.TextChanged.

We would love to hear your experiences when turning on this experimental option. If you find an issue, please report it.

Wrapping Up

As always, while Xojo 2023r4 comes with a lot of performance improvements, it also comes with bug fixes and feature requests. I want to again thank everyone who took the time to create new Bug reports and Feature Requests, and tested the pre-releases.

We’re looking forward to see what you build with it!

Ricardo has always been curious about how things work. Growing up surrounded by computers he became interested in web technologies in the dial-up connections era. Xojo has been his secret weapon and language of preference since 2018. When he’s not online, chances are he will be scuba diving … or crocheting amigurumis. Find Ricardo on Twitter @piradoiv.

• Facebook
• X
• LinkedIn
• GitHub
• YouTube

Some Background

Xojo has been using Google Maps Embed as our map renderer for a while. Google Maps is a really nice product, but an API key is required nowadays for almost anything. Noticeably, in Xojo’s Eddie’s Electronics web example, the map in the customer list was only displayed if you had a valid API key for Google Maps.

MapLibre is a robust Open Source mapping library alternative that Xojo is using under the hood now. With this update, you can create truly interactive maps with Xojo supporting multiple markers and customization.

While you can still use Google Maps Embed as the renderer, MapLibre is our preferred option and will be Xojo’s default going forward.

Map Tile Providers

When switching to another library, we wanted to make sure you, as a developer, have more control. WebMapViewer comes with a new property, StyleURL, pointing to an endpoint that returns a Style file.

Style files are JSON documents following the MapLibre Style Spec. The easiest way to create a customized map is to register in one of the providers that supports this format. These providers will give you a style URL that you can use with your map. Some of them:

• https://www.maptiler.com
• https://www.mapbox.com
• https://stadiamaps.com
• https://www.arcgis.com

By default, Xojo uses OpenStreetMap raster tiles which should be OK for development or little web applications.

But you aren’t limited to using third party providers anymore. In projects where privacy is important or when you don’t want to be worried about monthly limits or prices, you can use software installed on premises to serve your own map vector tiles!

Martin is Open Source, but you can also use a commercial solution like MapTiler Server.

Address Lookup

Same as with map tiles, by default your maps will be using a free to use Geocoding service, Nominatim. If you hit a limit or if, for example, you are working on a project with privacy limitations, you can install Nominatim on premises.

Using WebMapLocation.LookupProviderURL, you can point to your own Nominatim server.

Retrieving and Drawing Routes

Last, but not least, you can retrieve and render routes, using OpenStreetMap. No matter what map tile provider you are using, you can draw routes on the map. When you use the Directions mode, all you have to do is add locations to your map.

But if you need more control, switch your WebMapViewer to View mode and use the new methods for getting and drawing routes. When using the method to retrieve the route, you will obtain a MapRoute object with distance and duration information. You can also use this object for things like serializing it and storing the result in a database. This allows you to skip sending a new routing request to the service and just render it.

While driving will be the default, the transportType parameter supports Car, Bike and Walking.

Make sure to check the updated WebMapViewer in the Xojo programming documentation.

That’s a Wrap!

We are already working on new features for this control that will come in upcoming releases, and we can’t wait to see what you create with this new version of WebMapViewer.

Ricardo has always been curious about how things work. Growing up surrounded by computers he became interested in web technologies in the dial-up connections era. Xojo has been his secret weapon and language of preference since 2018. When he’s not online, chances are he will be scuba diving … or crocheting amigurumis. Find Ricardo on Twitter @piradoiv.

• Facebook
• X
• LinkedIn
• GitHub
• YouTube

Before we jump into the topic, it’s worth mentioning that this is new in Safari 17, but it is a W3C Standard that might work with other combinations of browser and operating system.

One of the biggest advantages of creating a web app is that users won’t need to update it manually. Once a new version is deployed, a browser refresh will be enough to update- which Xojo handles that automatically. If we are talking about a large company with hundreds of computers, it’s easy to see how having a web-based Intranet, for example, would reduce maintenance costs.

Step by step, browser vendors are allowing developers to access APIs that are traditionally reserved for native desktop or mobile developers.

Adding Icon Badges

When users add a web application to the Dock, developers have the opportunity to set a numerical badge. This helps let the user know the amount of items requiring attention.

Missed calls, unread message notifications or the minutes pending in a Pomodoro session. The meaning of the badge value is determined by you.

This Web API is pretty easy to use in Xojo. Add a few new public methods to the Session object, called SetBadge and ClearBadge, respectively.

SetBadge (amount As Integer)

Var js() As String

js.Add("if ('setAppBadge' in navigator) {")
js.Add("  navigator.setAppBadge(" + amount.ToString + ");")
js.Add("}")

ExecuteJavaScript(String.FromArray(js))

ClearBadge

Var js() As String

js.Add("if ('clearAppBadge' in navigator) {")
js.Add("  navigator.clearAppBadge();")
js.Add("}")

ExecuteJavaScript(String.FromArray(js))

That’s it. Whenever you need to display a badge for that user, call Session.SetBadge(42), for example.

Creating a Manifest File

While is not required, a web app manifest file will allow you to tweak the look and feel of the application when added to the Home / Dock.

In order to let the OS know there is a Manifest file, add a new HTML header. Go to App -> HTML Header and add this line:

<link rel="manifest" href="/manifest.json" />

Let’s fill in the contents. We have to handle that “/manifest.json” URL. Add a new Event Handler in the app object, select the “HandleURL” event.

This is an example of how to create that file:

Select Case request.Path
Case "manifest.json"
  Var manifest As New JSONItem
  manifest.Value("display") = "standalone" // Remove back/forward buttons
  manifest.Value("name") = "My Xojo Application"
  manifest.Value("short_name") = "Xojo App"

  response.MIMEType = "application/json"
  response.Status = 200
  response.Write(manifest.ToString)
  Return True
End Select

You can check the whole list of parameters available from this website:
Web app manifests

Debugging Web Apps

Hey! Where are my Developer Tools!?

You can’t directly debug a web app from the app itself. But if needed, you can still open Safari, press on the Develop menu and, from there, access a Developer Tools instance for any web app that is opened:

That’s All!

While a web app is far from a native desktop app, changes like this make the the gap a little smaller and the user experience a little better.

Happy coding!

Ricardo has always been curious about how things work. Growing up surrounded by computers he became interested in web technologies in the dial-up connections era. Xojo has been his secret weapon and language of preference since 2018. When he’s not online, chances are he will be scuba diving … or crocheting amigurumis. Find Ricardo on Twitter @piradoiv.

• Facebook
• X
• LinkedIn
• GitHub
• YouTube

Database Support

Xojo works with a wide variety of databases. SQLite is bundled with your Xojo license and is a great beginner database for desktop, web and mobile apps. Xojo includes direct support for SQLite, PostgreSQL and MySQL. Plus, you can use ODBC to connect to just about anything else, such as Oracle, MS-SQL Server, Microsoft Access, Firebird or even IBM iSeries.

Examples

To help you get started, there are many examples in the Examples/Databases folder included with the Xojo Download, including examples that connect to each of the supported databases. You can find a breakdown of the examples included in the Examples folder in the Xojo Programming Language Documentation.

Additionally, you can check out the Eddie’s Electronics sample app (located in Examples/Sample Applications/EddiesElectronics) to see how to share database code between Xojo desktop and Xojo web apps.

DBKit is an example project designed to make it easier to build desktop and web applications that are front-ends to databases. Specifically, DBKit makes it easy to connect a database table to the user interface controls on a layout. DBKit also handles a lot of the interface for you. You can read more about DBKit in the Xojo Documentation.

Read: Documentation

After you have reviewed the examples, the Database Overview in the Xojo Documentation will help with next steps. Remember, Xojo comes bundled with SQLite which is an excellent database for desktop, web and mobile apps. Read more about using SQLite in the Xojo Documentation and check out this SQLite Tutorial for more detail.

Watch: Videos

The Xojo YouTube channel has hundreds of videos on all things Xojo. Here are the most recent Xojo Database videos and playlists:

• Video: Connecting to a Database from Xojo
• Video: Updating a Database from Xojo
• Video: Querying a Database from Xojo
• Video: Managing the UI when Updating a Database
• Video: Using DBKit to easily connect databases to Xojo applications
• Playlist: Using Databases with Xojo – A growing, catch-all playlist for videos related to Xojo and databases.
• Playlist: Xojo and SQLite – SQLite comes bundled with Xojo and is a great database for beginners building desktop, web and mobile apps with Xojo.

Vendor Documentation

Lastly, you should always refer to the vendor-specific documentation for the database you are using to learn the specifics about how that database works, including SQL syntax.

• SQLite
• PostgreSQL
• MySQL
• Oracle Database
• Microsoft SQL Server

Xojo simplifies the development process, reduces complexity and empowers developers to create efficient and functional database applications with relative ease. The Xojo IDE is free to use for development and testing – design, develop, run and debug your app all without a license. Purchase a license when you are ready to compile your apps, licenses start at $149. Visit the Xojo Store to find the license right for your project.

If you have questions after you have reviewed these materials, the Xojo Forum is an accessible and essential resource for Xojo users of all levels. You can also contact Xojo directly with your questions.

• Facebook
• X
• LinkedIn
• GitHub
• YouTube

Dark Mode Support and Bootstrap 5

You can now create web applications with Xojo that respects users’ Dark Mode preference with Bootstrap 5.

There is a new WebSession.ColorMode property you can use. It will be set as Auto by default, meaning it will match the user’s OS appearance preference, but it can also be forced to Light or Dark. It can be changed at runtime and per session.

While not everyone likes Dark Mode, some of your end users will appreciate this. Due to medical circumstances, they might actually need it, so please consider adding support even if you don’t like dark interfaces.

If you want to enable Dark Mode in your previous projects, you will have to manually enable the setting in the Shared Build Settings section (which is turned on by default on new projects):

Color Groups can also be used nearly everywhere, and they will be used in the IDE preview when you toggle between Light and Dark Mode:

In order get Dark Mode support ready for Web, we had to upgrade our internal Bootstrap dependency from v4.6.1 to v5.3.0, which is a huge leap by itself. Bootstrap 5 comes with a refreshed color palette, new components, modernized existing controls and bug fixes. Please check our previous Bootstrap 5 is Coming to the Xojo Web Framework blog post.

If your application wasn’t using a custom Bootstrap Theme (bootstrap.min.css), everything should look more or less the same except for the subtle color palette differences and rounder buttons. Bootstrap 4 themes aren’t supported in Bootstrap 5, please replace it with a v5 theme if needed. Not every theme supports Dark Mode, but the one included in Xojo does.

If you are a theme builder, please check the Bootstrap’s Color Modes documentation. You can also find free Bootstrap 5 themes available at Bootswatch.

We also want to send a big thank you to our third party developers for their effort adapting their Open Source and Commercial plugins and controls to Bootstrap 5. You can learn about what they offer at the Xojo Extras Store and in the Open Source Projects page in the Xojo Documentation.

Accessibility

Navigating and using web applications with the keyboard makes everyone’s life easier. In Xojo 2023r2 we’ve upgraded WebPagination and WebBreadcrumb controls, which are composed of more than one focusable item. Your users will be able to properly use the tab key to go through them.

We plan to continue working on improving Accessibility. Please open a new Issue if you find anything that can help you and your end users.

WebListBox

DataTables, the internal dependency we use for bringing your tables to life, has been upgraded from v1.10.20 to v1.13.4. This recent version includes support for Bootstrap 5 and a few bug fixes that some users were facing in their web projects.

You can now disable your WebListBox by setting its Enabled property to False so your users won’t be able to interact with it. And also, if you were missing this feature that’s in the DesktopListBox, you can now add Variant tags to your columns, using the new WebListBox.ColumnTagAt.

Last but not least, this control comes with a visual Inline Editor, like in its Desktop counterpart:

WebChart

Chart.js, the underlying library we use for WebChart, has been upgraded from v2.9.3 to v4.2.1. Again, we’ve done everything we could on our side so you don’t have to do anything.

The only exception is with the WebChart.OverrideOptions event. If you are currently using it, you’ll have to check the library documentation as the internal options JSON has changed.

You can expect the new DesktopChart features to be working on WebChart, like configuring how the lines look like (including the endpoints), background images or prefix and suffixes. Read New Additions to DesktopChart, MobileChart and WebChart to learn more.

Web SDK

If you are using third party controls, you will notice some of them now have a custom icon in the IDE Library. But even more important, they will use less memory at runtime.

Are you developing Open Source or Commercial Web SDK controls? Remember there is a dedicated Web SDK forum where you can ask any questions you may have.

IDE Performance and Improved CSS Support

Bootstrap 5 makes use of the latest CSS features. We took the opportunity to rethink our CSS parser and improve its performance at the same time. As a result, the IDE preview looks even closer to what you see in the browser, and we render everything faster.

Wrapping Up

Over 50 bug fixes and features were included just for Xojo Web in Xojo 2023r2. Please find a full list in the Release Notes. read more about Bootstrap 5 and updates to WebChart on the Xojo Programming Blog. We are looking forward to hearing your thoughts and seeing what you’re building with Xojo! See you in the forum!

Ricardo has always been curious about how things work. Growing up surrounded by computers he became interested in web technologies in the dial-up connections era. Xojo has been his secret weapon and language of preference since 2018. When he’s not online, chances are he will be scuba diving … or crocheting amigurumis. Find Ricardo on Twitter @piradoiv.

For most Xojo users, this update won’t require any changes at all to your existing projects. For those that create their own controls using the Web SDK, there will likely be a minor bit of work.

Dark Mode Support

The Web framework is currently the only Xojo framework that doesn’t support Dark Mode. Fortunately, Bootstrap 5 does. As with Desktop targets, users of your Web projects will be able to decide between the light and dark modes. For Web projects, there is now a Supports Dark Mode Build Setting that will be off by default for existing projects and on by default for new ones.

More Than Dark Mode

Visually, Bootstrap 5 comes with some subtle changes. For example the blue color it uses is still blue… but not that blue, helping to increase the contrast of your buttons.

You may notice that the buttons are a little bit rounder by default, following the latest design trends.

The look and feel of some input controls, like checkboxes and radio buttons, will be more similar between different browsers and operating systems.

Bootstrap 5 also includes new components and features, like Accordion and Offcanvas. These may find their way into future releases via the Web framework or from one of the third-party control developers.

Finally, Bootstrap 5 no longer depends on jQuery and it makes use of the latest CSS features which brings us to the next section.

Potential Migration Challenges

We’ve made it so most Xojo users won’t need to make any changes to their web projects. For example, we’ve adapted the Breadcrumb control to look like Bootstrap 4 by default. Generally speaking, if you are using the default theme and you aren’t using third-party controls, you won’t need to do anything special.

However, if you are currently using a custom Bootstrap 4 theme that uses a custom bootstrap.min.css file, it may not work properly. If you’ve downloaded the theme from a website such as Bootswatch, you can download an updated Bootstrap 5 compatible theme from the same site. Bootstrap 5 themes are actually easier to find than those for v4.

If you are still curious about Bootstrap 5 specifically, you can view the Bootstrap 5 Migration Guide where you can find an extensive list of changes and improvements since Bootstrap 4.6.

If you have any questions, please feel free to ask on the Forum.

Ricardo has always been curious about how things work. Growing up surrounded by computers he became interested in web technologies in the dial-up connections era. Xojo has been his secret weapon and language of preference since 2018. When he’s not online, chances are he will be scuba diving … or crocheting amigurumis. Find Ricardo on Twitter @piradoiv.

Brief introduction to the Atomic Design Methodology

If you haven’t heard about Atomic Design before, I really recommend that you dig a bit into this topic. With this way of methodology in mind, we will start building the smallest controls we can. Then, we will compose more complex controls reusing the smallest.

Keep in mind you don’t really need to blindly follow the Atoms, Molecules and Organisms proposed categories, and don’t overthink where to categorize them. As long as you can compose controls with other controls, that’s perfect. Adapt it to your own personal way of building software.

The idea resonates perfectly with Xojo and, while we will create a few web controls in this example, you can apply it to other targets like Desktop or Mobile.

Here is a video from Brad Frost, the person behind Atomic Design Methodology.

Containers to the rescue!

In this case, we won’t need to use any Web SDK control, CSS or JavaScript. We will be using just plain Xojo Web Containers for creating our Atoms and Molecules.

This is how Twitter’s navigation sidebar looks like:

We will create something similar. Using Atomic Design, let’s break it down it into a few new reusable controls:

Each Atom, Molecule and Organism will be a Container. In the above image, we have identified each of them.

• There is a “Navigation Link Icon”, an Atom, which will show one of the available Bootstrap Icons. As you notice in the Twitter example, if the link is active, the icon will be filled.
• For the label Atom, we can just use the WebLabel built-in control. There is no need to wrap it in a Container, in this case.
• The navigation link will be a Molecule, combining the icon and the label.
• The Active Link Indicator will move to the active link, using an animation.
• Finally, the Vertical Navigation Control will be the Organism, combining everything into one.

Navigation Link Icon

This Control is basically a Container, with an ImageViewer inside. Technically, this could be just an ImageViewer subclass, but using a WebContainer we can also specify its default width and height.

It will have two computed properties:

• Active As Boolean
• IconName As String

There will also be a private ShowIcon method. Whenever you change either the Active property or IconName, the computed property will call ShowIcon.

The magic is inside ShowIcon:

Var iconColor As Color = If(mActive, Color.Black, Color.LightGray)
Var icon As String = If(mActive, mIconName + "-fill", mIconName)
IconImageViewer.Picture = WebPicture.BootstrapIcon(icon, iconColor)

The icon color will be either LightGray or Black, depending if it’s active or not. There are also a lot of Bootstrap Icons with the “-fill” suffix so we’ll use them. This will force us to only use icons which have that suffix, but we will have to live with that.

The final trick is to use the Inspector Behavior and expose our Active and IconName computed properties. Right click on NavigationLinkIcon, then click on Inspector Behavior:

From there you can enable the checkboxes and define their default value:

Now that we have the Control ready, let’s see how it works on its own:

Neat! You can reuse this Atom everywhere, including other projects.

Navigation Link Control

Combining our fresh NavigationLinkIcon, a built-in WebLabel and exposing an API, we’ll create our NavigationLink Molecule.

Create a new Container and place the items inside. Then add some computed properties:

• Active
• Caption
• IconName

Whenever the property changes, just update the underlying control.

One trick, to make the control clickable, is to add a WebCanvas on top of the other controls. Implement its Pressed event and forward it as a new “Pressed” Event Definition.

If you want to show a pointer cursor when the user moves the mouse over your control, add this line of code into the container’s Opening event:

Me.Style.Cursor = WebStyle.Cursors.Pointer

This is how it looks like in the IDE:

Let’s quickly test it:

We are getting there.

Active Link Indicator

We have most of the Atoms and Molecules created already. The Navigation Link Indicator is so simple and so tied to the Sidebar, that I don’t think creating an individual Atom for it is worth the effort.

Using a WebRectangle, with a line of two of code in its Opening event, will be enough. This is completely up to you!

Vertical Navigation Control

Now it’s time to glue the Atoms and Molecules together to make our first Organism. Create a new Container called VerticalNavigation.

Drop a WebRectangle on it. Set its Left and Top to 0, and implement its Opening event with these lines of code:

Me.Style.BorderThickness = 0
Me.Style.AddTransition("top", 0.2)

That will remove the border that comes by default with this control. It will also tell the browser to animate the rectangle whenever we change the Top position.

The rectangle background color will be a light gray, but this is again up to you.

For the API we want to expose, add these Methods:

• AddLink(caption As String, icon As String, active As Boolean = False)
• HandleLinkPressed(sender As NavigationLink)
• SetActiveLink(index As Integer)

AddLink and SetActiveLink can be left Public, HandleLinkPressed will be a Private Method.

AddLink code:

// We will create a new NavigationLink instance
// and set the properties we're receiving.
Var link As New NavigationLink
link.Caption = caption
link.IconName = icon

// For its pressed event, we will handle it
// internally in the HandleLinkPressed method.
AddHandler link.Pressed, WeakAddressOf HandleLinkPressed

// We will place it programatically in  the container.
Const padding = 10
Var linkTop As Integer = mLinks.Count * (link.Height + padding)
link.EmbedWithin(Self, padding, linkTop, Self.Width - padding, link.Height)

// A reference for this NavigationLink will be
// needed later, so we will store it internally.
mLinks.Add(link)

// Finally, if the item is active, we will
// handle it just like if it's been pressed
// by the user.
If active Then
  SetActiveLink(mLinks.LastIndex)
End If

HandleLinkPressed code:

SetActiveLink(mLinks.IndexOf(sender))
RaiseEvent Pressed(sender)

And, finally, SetActiveLink:

// Here we will loop through the NavigationLink
// references we have and enable or disable the
// Active property, depending on the index
// comparison.
For i As Integer = 0 To mLinks.LastIndex
  mLinks(i).Active = i = index
Next

// Move the visual active indicator to the
// NavigationLink position.
ActiveLinkIndicator.Top = mLinks(index).Top

Final Result

Everything is ready, drop your VerticalNavigation somewhere in your WebPage and add a few links inside its Opening event:

// Setting the third parameter to "True" will set that link as Active.
Me.AddLink("Home", "house")
Me.AddLink("Explore", "binoculars", True)
Me.AddLink("Notifications", "bell")

You should see something similar to this:

Congratulations! You’ve built a vertical navigation, with nice transitions, using some Atomic Design principles.

Code repository: https://github.com/piradoiv/vertical-navigation-example
Download the project: vertical-navigation-example

Ricardo has always been curious about how things work. Growing up surrounded by computers he became interested in web technologies in the dial-up connections era. Xojo has been his secret weapon and language of preference since 2018. When he’s not online, chances are he will be scuba diving … or crocheting amigurumis. Find Ricardo on Twitter @piradoiv.

Opening in Desktop and Mobile Apps

• First, the App Opening event will be fired first.
• Next, the Opening event on every control of the default Window assigned to the App project. In this case, it will follow the same order in which the controls were added to the Window in the Layout Editor. It is possible to change that order using the Order buttons in the Command Bar in the Layout Editor.
• Last, the Opening event will be fired on the default Window containing the controls.

Closing in Desktop Apps

When a Window is closed in a Desktop app, the Closing event will be fired following this order:

• First, the Closing event will be raised on every control added to the Window, following the same order used when adding the controls to the Window in the Layout Editor. It is possible to change that order using the Order buttons in the Layout Editor toolbar.
• Next, the Closing event will be raised in the Window itself.
• Last, the Closing event will be raised in the App object of the Desktop app when the user quits the application.

Opening in Web Apps

This is the event firing order for Xojo Web apps:

• First, the Opening event will be raised in the WebApp object.
• Next, the Opening event in the WebSession object.
• Next, the Opening event on every control added to the by default WebPage set in the WebApp object. In this case, it will follow the same order used when adding the controls to the web page in the Layout Editor. (It is possible to change that order using the Order buttons in the Layout Editor toolbar.)
• Next, the Opening event will be raised on the default web page itself.
• Next, the app will start to raise the Shown event on every one of the webpage controls following the same order used when they have been added to the page. (It is possible to change that order using the Order buttons in the Layout Editor toolbar.)
• Last, the Shown event will be raised in the default webpage.

Closing in Web Apps

Regarding the Closing and Closed events, the Web App will follow this order:

• First, the Closing event will be raised in the WebSession object.
• Next, the Closed event will be raised on every one of the default webpages (or the pages shown), following the same order used when adding the controls to the page in the Layout Editor. (It is possible to change that order using the Order buttons in the Layout Editor toolbar.)
• Last, the Closed event will be fired in the webpage itself.

Summary

As you can see, Xojo follows the firing same regardless of the target you choose for your project – Desktop, Web or Mobile apps. Obviously, Web apps do change a bit, because they deal with the WebSession object and also with the Shown event in addition to the Opening event. In Web projects, the Opening event happens on the server side, while the Shown event happens in the client (browser) side.

See related video at the Xojo Programming Language YouTube Channel.

Javier Menendez is an engineer at Xojo and has been using Xojo since 1998. He lives in Castellón, Spain and hosts regular Xojo hangouts en español. Ask Javier questions on Twitter at @XojoES or on the Xojo Forum.

• Facebook
• X
• LinkedIn
• GitHub
• YouTube

For most Xojo users, this update won’t require any changes at all to your existing projects. For those that create their own controls using the Web SDK, there will likely be a minor bit of work.

Dark Mode Support

The Web framework is currently the only Xojo framework that doesn’t support Dark Mode. Fortunately, Bootstrap 5 does. As with Desktop targets, users of your web projects will be able to decide between the light and dark modes. We plan for this to work identically to the way it works for your Desktop projects now. There will be a Supports Dark Mode Build Setting that will be off by default for existing projects and on by default for new ones.

More than Dark Mode

Visually, Bootstrap 5 comes with some subtle changes. For example the blue color it uses is still blue… but not that blue, helping to increase the contrast of your buttons.

You may notice that the buttons are a little bit rounder by default, following the latest design trends.

The look and feel of some input controls, like checkboxes and radio buttons, will be more similar between different browsers and operating systems.

Bootstrap 5 also includes new components and features, like Accordion and Offcanvas. These may find their way into future releases via the Web framework or from one of the third-party control developers.

Finally, Bootstrap 5 no longer depends on jQuery and it makes use of the latest CSS features which brings us to the next section.

Potential Migration Challenges

We’ve made it so most Xojo users won’t need to make any changes to their web projects. For example, we’ve adapted the Breadcrumb control to look like Bootstrap 4 by default. Generally speaking, if you are using the default theme and you aren’t using third-party controls, you won’t need to do anything special.

However, if you are currently using a custom Bootstrap 4 theme that uses a custom bootstrap.min.css file, it may not work properly. If you’ve downloaded the theme from a website such as Bootswatch, you can download an updated Bootstrap 5 compatible theme from the same site. Bootstrap 5 themes are actually easier to find than those for v4.

We are announcing this change to v5 in advance to allow third-party library developers the time to adapt their code and make use of the new Bootstrap 5 HTML and JavaScript API. If you rely upon any third-party controls for your web projects, you will need to upgrade them when new Bootstrap 5-compatible versions become available.

To make the migration as smooth as possible for everyone, we will continue including jQuery and provide independent betas, prior to releasing a version of Xojo with Bootstrap 5.

In the Bootstrap 5 Migration Guide you can find an extensive list of changes and improvements since Bootstrap 4.6.

If you have any questions, please feel free to ask on the Forum. Users attending the Xojo Developer Conference can also meet and talk in person with Xojo engineers, about this or any other topic.

The Web SDK can help, giving you the opportunity to build anything. In 2022r4 we are adding more examples, to help you start building your custom controls.

Here is the list of the new examples we’ve added in this release.

Custom Button

This is a highly configurable custom button, where you can set any width, height and the border radius.

It is probably the simplest control you can create, but it will help you to practice. This example also demonstrates everything you will need to draw your controls in the Xojo IDE layout editor.

There are plenty of comments in every SDK event to help you get started.

Custom Select

This is an alternative to the WebPopupMenu control, built from scratch using the Web SDK. It also makes use of the DrawControlInLayoutEditor event and contains plenty of comments.

It uses the same techniques we are using for the first example, in a more complex control.

Bootstrap Toast

While in the other examples we are using plain JavaScript, this one demonstrates how to use TypeScript for coding your controls. TypeScript is the language we use to compile our own web controls, and what we also recommend to build them.

As this control needs a folder structure, you can find this example in this path:

Extras > WebSDK > Examples > Bootstrap Toast

This is a special control, as it doesn’t works like the other visual controls. Like a WebDialog, you will need to drop the control into your WebPage. Whenever you want to display a Toast, you’ll have to call a method.

Conclusion

Building your own controls will open a new world of possibilities. If you want to start with your first one, I recommend you to try to recreate the Custom Button example from scratch, with your own code.

In the Web SDK folder, you can also find the WebSDK Docs PDF document, that will help you to understand better what each event does, when and why.

Are you planning to create your own custom controls? Let us know in the forum!

Ricardo has always been curious about how things work. Growing up surrounded by computers he became interested in web technologies in the dial-up connections era. Xojo has been his secret weapon and language of preference since 2018. When he’s not online, chances are he will be scuba diving … or crocheting amigurumis. Find Ricardo on Twitter @piradoiv.

Xojo Web is an excellent way to expose the features of your electronics projects without having to attach any screen to them. It’s never been easier to build a Web GUI for your smart clocks, drones, POS, domotics, robots or just some automation services. Thinking about building a solar powered server to automate your tweets? Why not!

If you prefer, you can just expose a Web API instead that can be remotely consumed from another device.

What Raspberry Pi boards support ARM 64-bit Linux OS?

• Raspberry Pi Zero 2
• Raspberry Pi 3
• Raspberry Pi 4
• Raspberry Pi 400

Preparing your Raspberry Pi

The easiest way to get your operating system ready is by using the Raspberry Pi Imager.

At the moment of writing this article, it selects the 32-bit flavor by default. If you have one of the supported boards, go ahead and try Raspberry Pi OS (64-bit) or Raspberry Pi OS Lite (64-bit). The later won’t include any desktop environment, you’ll have to access by SSH.

Select your SD Card storage and press on Write. Optionally, if you want to set a hostname for your board, enable SSH, or even configure your Wifi, press on the gears icon.

In just a few minutes you will have a ready to boot SD card for your Raspberry Pi.

Remotely debugging your projects

This is one of my favorite features of Xojo.

In your Xojo installation Extras folder, you will find a “Remote Debugger Console” and “Remote Debugger Desktop”, that also works for your Linux 64-bit OS.

Depending on which flavor of Linux you’ve selected in the previous step, send the Console or Desktop ZIP to your board, run it and configure the settings.

Inside Xojo, go to Preferences and press on the Debugging tab.

That’s it. Now you will be able to remotely run and debug your applications. Add a few breakpoints and the execution will stop as soon as it reaches it, allowing you to explore the current state.

Deploying the final version

Once you’re ready to build the final version of your application, all the wires attached and components soldered, the last step is to “Deploy” your application.

There is a tutorial covering this step in detail: Deploying Web Apps on Linux.

If you create a Raspberry Pi project, please make sure you open a Forum thread. The Xojo community loves seeing this kind of projects!

What will you build?

Ricardo has always been curious about how things work. Growing up surrounded by computers he became interested in web technologies in the dial-up connections era. Xojo has been his secret weapon and language of preference since 2018. When he’s not online, chances are he will be scuba diving … or crocheting amigurumis. Find Ricardo on Twitter @piradoiv.

I first made a desktop Secret Santa app back in 2015 for an event with friends. We were tired of drawing names out of a hat and having couples being paired together. The app I created solved that problem because couples were excluded from offering a gift to each other. And we didn’t need a hat!

In November of 2018, I had the idea of making a Secret Santa iOS app so that anyone with an iPhone or iPad could benefit from the same features I had been enjoying for the past 3 years.

The app would need to be easy to use, avoid couples getting matched with each other, send notifications by email without letting the organizer know which pairs were matched, and of course make sure no name would be assigned twice.

After just 8 days of development, the app was ready to ship and sent to the App Store.

Within 5 days, the app had been downloaded from 35 different countries and was my fastest app to reach 1000 downloads!

Having the app translated to English, French, Italian, and Spanish in the initial release helped to reach more users.

Version 1.1 of the app was released a few days later with German and Portuguese translations.

That’s when I realized that Secret Santa is something extremely common in Latin America. Many families draw names for Christmas so that they can give and receive one big gift instead of smaller trivial gifts for each family member.

Most updates of the app came with new localizations, which really helped in realizing more and more downloads. After 3 years of updates, the app is now available in 32 languages.

A high quantity of downloads also meant that I received a lot of feedback from users. Many users were happy with the current features, but I started getting feature requests to send the gift pairs by SMS or WhatsApp instead of by email. We all have a parent or grand-parent who isn’t tech-savvy and doesn’t have an email address.

Leveraging the biggest advantage of Xojo – Sharing code across platforms

From 2018 until 2022, I had become used to updating the Secret Santa app itself to add new features and new translations while also fixing bugs. This year, I received a message from an unhappy user stating that they really need a wishlist feature and downloaded my app thinking it already had one.

A valid wishlist feature needed to be accessible to anyone with an Internet connection, whether they used a computer, an iPhone, or an Android device.

Using Xojo Web and a coding language I already knew was the obvious choice for this task. Sharing important bits of code from my main iOS project to the web wishlist project was as easy as copy and paste.

As with any Xojo project, copying classes from one project to the other was a real time saver, especially for the API layer required to communicate between Xojo and the online database that holds all the Secret Santa data.

The main difficulty working on a web project came from the UI. Not that Xojo Web’s UI is difficult, but I am so used to designing mobile apps that my brain didn’t know where to start.

I knew I wanted to display two columns of data:

• The user’s wishlist
• The wishlist from the person they are offering a gift to

The layout had to be responsive to be accessible on both mobile and desktop devices.

Graffitisuite from Anthony Cyphers came to mind, and within a few minutes of reviewing the online demo, I was convinced to use GraffitiKanban web control. I am a big fan of Trello for organizing my work, displaying cards in labeled columns. That’s exactly what I needed for the wishlist feature.

GraffitiKanban is “responsive” (Web Design term), meaning the display changes to adapt to smaller screens such as mobile devices.

GraffitiSuite also offers a wide variety of UI elements that made me save a lot of time.

7 days after the initial feature request, the wishlist feature was available to all.

Wishlist on a desktop browser:

Wishlist on a mobile browser:

Deploying the app to Xojo Cloud was extremely easy.

A single button press in Xojo, a subdomain DNS record, 2 minutes of configuration in Cloudflare, and the web app was up, running, and accessible through HTTPS.

Customer use of the wishlist feature has blown-up more than I ever would have expected. So far 30,000 gift ideas have been added to the wishlist (and counting).

The next feature request

With an app that sees 60,000 new users per month, I receive a lot of feature requests. Most recently, I received a one star review on the app store because my app isn’t accessible to the Visually Impared. When VoiceOver is activated, all it says is “button”, “button”, “button”, with no explanation.

Adding voice-over capabilities in Xojo is simple. The MobileUIControl class has two String properties, AccessibilityHint and AccessibilityLabel.

But it actually is a lengthy task to check each control on each screen and make sure that the translations are correct.

VoiceOver support will soon be released in English and French, but all other localizations will be only ready next year. It is currently a bad time to get 30 different translators to work on the project under such short notice.

Xojo has enabled me to create a business out of developing iOS apps for the App Store. Including all of my apps, I have had over 6.5 million downloads and counting. Secret Santa is a prime example of what is possible and how you can leverage your Xojo skills to expand to other platforms when you need to. I look forward to what’s to come and will be at XDC London to learn more about the future.

If you are organizing a Secret Santa event or just curious to see the app, download Secret Santa on the App Store.

Jérémie Leroy has been using Xojo since 2008, he won two Xojo Design Awards in the iOS App category and has released over 13 iOS apps made with Xojo on the App Store. He also released iOSDesignExtensions on Github to help style and polish your Xojo made iOS apps.

Place a WebCheckbox into your WebPage. Add the Opening Event Handler to your checkbox.

Inside, paste this code:

Me.ExecuteJavaScript("document.getElementById('" + Me.ControlID + "').classList.add('custom-switch');")
Me.Style.Value("padding-left") = "32px" // Adjust if needed

Run the project. Enjoy!

If you like this control, consider creating a WebCheckbox subclass so you can easily reuse it.

Ricardo has always been curious about how things work. Growing up surrounded by computers he became interested in web technologies in the dial-up connections era. Xojo has been his secret weapon and language of preference since 2018. When he’s not online, chances are he will be scuba diving … or crocheting amigurumis. Find Ricardo on Twitter @piradoiv.

Both server and frontend will have less memory footprint now. The team has been working on finding and fixing memory leaks, and optimizing how the framework cleans up the controls, when pages aren’t visible anymore.

Paul and Travis made IDE improvements to load projects much faster. If you have a large Web project, you will surely notice the difference.

The WebListBox component got most of the improvements. Visually, you will notice less flickering. Internally, it will make less requests to the web server to display its data. We will continue optimizing its performance release after release. Interacting with this control is now more natural and accessible, as we’ve made it more compatible with the different OSs and devices. And just like WebListBox, almost every other control received one or more bug fixes. Check the Release Notes for a detailed list.

I would like to finish this post with a huge thank you to every user that has helped directly or indirectly creating Issues, attaching a sample project, posting on the Forum and testing the beta releases.

The community is the best feature of Xojo

Ricardo has always been curious about how things work. Growing up surrounded by computers and became interested in web technologies since the dial-up connections era. Xojo has been his secret weapon and language of preference since 2018. When he’s not online, chances are he will be scuba diving … or crocheting amigurumis. Find Ricardo on Twitter @piradoiv.

To start, create a Web project, select WebPage1 in the Navigator and drop a WebButton from the Library onto the upper-center of the page in the Layout Editor. In the associated Inspector Panel for the button change the following property:

• Caption: Create PDF

Next, add the Pressed Event Handler to it and type the following snippet of code in the associated Code Editor:

// Nothing really interesting here
// Create a new PDFDocument instance
// and assign its Graphic context to
// a variable
Var d As New PDFDocument
Var g As Graphics = d.Graphics

// The content of the PDF
// not that much, but it works for the
// main topic we are interested in
g.DrawText("Really simple PDF content", 20, 20)

// Here is where the **important** thing starts
// Creating a new WebFile instance and assigning it
// to the wf property added to the WebPage1 page
wf = New WebFile

// This is the thing: the PDFDocument.ToData method
// returns as a MemoryBlock (Direct conversion to String)
// the inner contents of the PDF document at this point
// so assign that to the "data" property of the
// WebFile instance
wf.Data = d.ToData

// It's important to set the right MIMEType for the file
// in this case, it's a PDF file
wf.MIMEType = "application/pdf"

// We assign the file name…
wf.Filename = "SamplePDF.pdf"

// …and set the ForceDownload to true…
wf.ForceDownload = True

// …so the file is, in effect, downloaded when calling
// the Download method on our WebFile instance
Call wf.Download

// Because we want to display the PDF file in an HTMLViewer
// set the ForceDownload property back to False
wf.ForceDownload = False

// And, finally, preview the PDF Document loading it in the
// HTMLviewer added to the WebPage1 page
HTMLViewer1.LoadURL(wf.URL)

As you can see here, this simple fragment of code is in charge of creating a sample PDF document, downloading it and also previewing it in an HTMLViewer instance. Now, add an HTMLViewer control to the WebPage1 page.

Select the WebPage1 item in the Navigator again so it is visible in the Layout Editor. Next, drag the HTMLViewer control from the Library and drop it below the WebButton added in the previous step.

With the HTMLViewer1 control selected in the Layout Editor, click on the four lock icons under the Locking section from the associated Inspector Panel so they are closed.

Finally, add the expected WebFile property to the WebPage1 page using the following values in the associated Inspector Panel:

• Name: wf
• Data Type: WebFile
• Scope: Private

You’ll probably want to move this property to the Session object in your Web projects so every connected user to the app can handle their own generated PDF documents.

And… that’s all! Run the project, click the button and see how it works.

Have fun!

Javier Menendez is an engineer at Xojo and has been using Xojo since 1998. He lives in Castellón, Spain and hosts regular Xojo hangouts en español. Ask Javier questions on Twitter at @XojoES or on the Xojo Forum.

• Facebook
• X
• LinkedIn
• GitHub
• YouTube

You can see that the DatePicker is rendering the date in M/D/Y format, but here in New Zealand (and a lot of other places) we use D/M/Y as seen in the Locale.Current text field.

I then looked at WorldTimeServer.com and I can see that this site that is dedicated to dates and times is also rendering dates in M/D/Y format.

This led me to believe that my browser wasn’t giving the correct language code to these sites. I did a little digging and found that my browser has a Languages setting and mine was defaulting to English (United States). And the United States, unlike New Zealand, uses M/D/Y.

To fix this I added my language to the browser and set it to be the first in the list.

Now WorldTimeServer.com renders dates in D/M/Y format.

And the DatePicker in my Xojo project now renders correctly as well.

And I didn’t change a single line of code in my Xojo project to fix it!

Wayne Golding has been a Xojo developer since 2005 and is a Xojo MVP. He operates the IT Company Axis Direct Ltd which primarily develops applications using Xojo that integrate with Xero www.xero.com. Wayne’s hobby is robotics where he uses Xojo to build applications for his Raspberry Pi, often implementing IoT for remote control.

In order to avoid this you can use the following code snippet to block the back button and keep the current webpage displayed. It will reload the current webpage, so you probably will want to combine this technique with the use of cookies to keep track of the data you save and retrieve for the user.

The first step to implement this is adding a value to the HashTag property for the Session object in the Opening Event Handler of the webpage. For example:

Session.HashTag = "#"

Next, select the App object and type the following snippet of code under the HTML Header section in the associated Inspector Panel:

<script>
window.addEventListener('popstate', function(event) {
	history.pushState(null, null, window.location.pathname);
	history.pushState(null, null, window.location.pathname);
	}, false);
</script>

That’s all! You can also watch this simple “how to” in a 2 minute video (in English)  (video in Spanish). Questions? Ask me on Twitter @XojoES or on the Xojo Forum.

If you haven’t heard of Docker, go ahead and read their excellent Documentation: Docker – Overview.

I’m just going to quote some basics from the Overview to give a brief introduction of Docker, Docker image and Docker container:

Docker is an open platform for developing, shipping, and running applications. It provides the ability to package and run an application in a loosely isolated environment called a container. The isolation and security allow you to run many containers simultaneously on a given host. Containers are lightweight and contain everything needed to run the application, so you do not need to rely on what is currently installed on the host. You can easily share containers while you work, and be sure that everyone you share with gets the same container that works in the same way.

A Docker image is a read-only template with instructions for creating a Docker container. Often, an image is based on another image, with some additional customization. To build your own image, you create a Dockerfile with a simple syntax for defining the steps needed to create the image and run it.

A Docker container is a runnable instance of an image. You can create, start, stop, move, or delete a container. By default, a container is relatively well isolated from other containers and its host machine. You can control how isolated a container’s network, storage, or other underlying subsystems are from other containers or from the host machine. A container is defined by its image as well as any configuration options you provide to it when you create or start it.

A Docker Registry is a stateless, highly scalable server side application that stores and lets you distribute Docker images.

Why use Docker with a Xojo Web App?

You can package your Xojo Web Apps in a Docker Image. That allows you to run an instance of your applications easily in a Docker Container. Docker provides the infrastructure to host the apps, start/stop them, switch between image versions – and much more.

The Docker Images containing your Xojo Web Apps can be copied to other machines. This might be some Linux or macOS machine (Windows seems to be a bit more tricky), a Cloud Service – or even a Synology NAS. You then can import the Images on the Docker environment of those machines, and serve your apps from there.

If you’re pushing the Docker Images to a Registry (e.g. Docker Hub), it gets even more convenient. Docker Hub is a service provided by Docker for finding and sharing container images with your team or the public. So you’ll build the Docker Image with your Xojo Web App, push it to the Registry. After that, you (or your team, or everyone) can just pull the Images to their Docker infrastructure and run them in a Container.

How to build a Docker Image containing a Xojo Web App?

One could answer obviously: it depends. But let me try to explain the basic required steps. For this example we’re going to use a macOS machine to build the Xojo Web App and Docker Image. Then we’ll deploy and run a Docker Container on the local developer machine and on a Synology NAS.

Requirements

• Xojo with a license allowing you to build a Xojo Web App for Target Linux (Intel, 64Bit).

Docker Desktop installed on the macOS developer machine. Download and install it from here: Docker for macOS. After that you should have the Docker GUI up and running. And in Terminal.app you should have the command line tools available. You can double check this by entering this command:

docker version

• We’re going to build a Docker Image based on Ubuntu (Linux). To run a Docker Container with this image, we obviously need a machine supporting this. Both macOS and the Synology NAS will work just fine.

Are you ready and set up? So let’s go and try this.

Build a Xojo Web App

Open a Xojo Project with a Web Application. I’m going to use a CRC Calculator I’ve written. Debug-Run it locally to make sure the Web App works as expected.

Once we’re ready to build we should think of what we’re going to need for the Docker Image. Check the following properties in your Xojo Project:

• The most obvious one: Tick the “Build Target: Linux, x86-64Bit”. Since our Docker Image will run Ubuntu / Linux-64Bit, we need the Xojo Web App to run in such an environment.

• Then in “Build Settings – Shared”, set the “Build – Port: 80“. In fact it doesn’t really matter which Port you’re choosing. All that is important for now is that you know which one it is.

• That’s about all we need to do within the Xojo IDE – so let’s hit “Build”.

We now have the built Web App ready. Next step is to package it in a Docker Image.

Dockerfile

Open the Web App’s Build Folder in Finder. Next we need to write the instructions to get it in a Docker Image. Open your favourite Text Editor. Create a Text-File with Filename: Dockerfile (no file extension). Save it in the Build folder (next to the application’s executable file). The Content we’re saving in Dockerfile is:

#BASE IMAGE
FROM ubuntu:20.04

#INSTALL REQUIRED LIBRARIES
ENV DEBIAN_FRONTEND noninteractive
RUN apt-get update && apt-get install -y libunwind8 libglib2.0

#ADD APPLICATION TO DOCKER IMAGE
ADD / /app/

#EXPOSE PORT AND RUN APPLICATION
EXPOSE 80
WORKDIR /app
CMD /app/CRCCalculatorWeb

This describes how Docker is going to create the Docker Image. Let’s briefly explain the steps of this Dockerfile:

• We’re going to use Ubuntu 20.04 as a base image. That about the same as saying: “Let’s set up an environment running Ubuntu 20.04 first.”

• We then set an environment variable allowing to install updates without user interaction. Then the system gets updated, and required Libraries installed (libunwind8, libglib2.0).

• The whole Content of the Build Folder (or in other words: everything next to the Dockerfile – that’s basically our Xojo Web App) is being copied into the image to the location /app

• Expose 80: Do you remember? That’s the “Build Port” we’ve set in the Xojo IDE. So this tells that when running this Image as a Container Instance later we can attach to this “virtual port”. It doesn’t matter if several applications in different Images/Containers use the same port. That’s because when running an Instance, we can later configure the running Instance to map the Ports, e.g.: “8088 (external) -> 80 (internal)”. So a second Web App Instance or App could use e.g.”8089 (external) -> 80 (internal)”. That’s why for our own convenience we can use Port 80 for every of our Xojo Web Apps’s Docker Image.

• Finally, the instructions tell where the working directory is, and with the last command the Xojo Web App is being launched.

Alright – everything is ready so that we can now create the Docker Image.

Docker Image

Open Terminal.app and change directory to the Build Folder of the Web App:

cd /path/to/your/xojo-webapp-project/Builds\ -\ CRCCalculatorWeb/Linux\ 64\ bit/CRCCalculatorWeb

You’re now in the folder with the Dockerfile and your Web App.

A Docker Image always needs a Tag. Such a Tag looks like this:

jotools/crccalculator:1.0.0-dev

The parts are: (company-name)/(product-name):(version-label-tag)

So… let’s build the Docker Image – enter this in Terminal:

docker build -t jotools/crccalculator:1.0.0-dev .

What this does is: Build a Docker Image with Tag ___ from “this current directory” (the dot at the end).

Side-Note: If you’re re-building an Image with the same Tag of an already existing Image, it gets overwritten. You could also first remove an existing image like this:

docker image rm jotools/crccalculator:1.0.0-dev

You can now launch the Docker Desktop .app and find your Image there:

If you prefer to see the image using the command line:

docker image ls

Run Docker Container

Let’s now take the Image and run a new Docker Container using that Image. We will configure the Docker Container Instance to use the local Port 8088. In Docker Desktop GUI:

• Select the Image, click on the Button “Run”

• Expand the optional settings, enter a Container Name of your choice and Map the “LocalPort: 8088” to “Container Port: 80”

• Then… click on “Run”

And that’s it – we have the Container up and running:

If you prefer the command line:

docker run -d --publish=8088:80 --name crccalculator jotools/crccalculator:1.0.0-dev

Let’s access our Xojo built Web App running in the local Docker Container using Safari:

Side-Note: If you just want to try this example project then you can pull the image like this in Terminal.app:

docker pull jotools/crccalculator:1.0.0

Export Docker Image

The easiest way is to push the Image to a Registry such as Docker Hub. That obviously requires a registration – so we won’t cover this here and now.

Let’s export the Image using Terminal.app.

You should still be in the Build – directory of the Xojo Web App. If not, change to that folder.

Then export the Docker Image to a file like this:

docker save jotools/crccalculator:1.0.0-dev | gzip > ./CRCCalculatorWeb.dockerimage.tgz

This command is saving the Image/Tag to a .tgz located in the current directory.

Run Docker Image on a Synology NAS

If you have a Synology NAS supporting Docker – this is how you can run the exported Image on your NAS:

• First of course: Install the Synology Docker Package

• Copy the exported CRCCalculatorWeb.dockerimage.tgz to a Share on the NAS

• Launch the Docker .app on the NAS

• Under “Images”: Add -> From File -> (choose your CRCCalculatorWeb.dockerimage.tgz)

• Select the imported Image, click on “Run”

• Enter a Containername of your choice:

• Click the Button “Advanced Settings”: Same story here – Map the Local<->Container Port. In this example: Local 8099 <-> Container 80

• Finish the assistant. The Container should now be up and running:

Let’s access our Xojo built Web App running in the Docker Container of the Synology NAS using Safari:

What next?

There are a lot of features and possibilities which we won’t cover here. Let’s just pick a couple and briefly explain without going into detail. You’ll find excellent documentation on Docker’s Website if you want or need to dig in further.

Docker and Persisted Storage

Note that this example has no persisted storage. Which means that you can save files within a Container – but once you stop or remove the Container (e.g. to run a new Container with a newer Image version) the created data is gone. That’s a good thing – as a Container will always behave the same when deployed, not being cluttered with data that has come from somewhere.

If your Web App requires to store data on the filesystem you should add a Volume. In the Dockerfile add a line like this:

VOLUME /data

You then can have your WebApp save data to the folder /data.

If you run a Container from such an Image – have a look at the Advanced Settings. Since the Image exposes a Volume, you can choose a local folder (on the machine where Docker is serving the Container) to be attached to /data. Same story on the Synology NAS.

Once you remove the Docker Container, the Data will still be there. So you can run another Container (e.g. with a newer version of your app), attach the same/existing data-folder. That way you can continue and keep existing data.

Environment Variables

Especially if you’re going to Deploy the Docker Image on various environments, you might want some “settings”. One approach is to use Environment Variables in the Dockerfile:

ENV MY_CUSTOM_SETTING=4430

Again in the Advanced options when running a Container you can override these Environment Variables to fit your needs.

Build Automation

If you’re building regularly and don’t want to enter commands in the command line after every build you could think about a Post Build Script which builds the Docker Image and optionally even pushes it to a Registry (e.g. Docker Hub).

An example is available here: Example Project – Xojo Web App 2 Docker

Docker Registry

The easiest way is to distribute a local Docker Image is to use a Registry such as Docker Hub. That obviously requires a registration and your Docker Client to be signed in. You can then push the Docker Image to the Registry, and pull it from there on the Docker Clients.

docker push jotools/crccalculator:1.0.0-dev

docker pull jotools/crccalculator:1.0.0-dev

Restart policy

In order to automatically launch a Docker Container after a reboot (of the host machine; of the Docker daemon): see Docker’s Restart Policy Documentation. 

This command changes the restart policy for an already running container named crccalculator:

docker update --restart unless-stopped crccalculator

And this command will ensure all currently running containers will be restarted unless stopped:

docker update --restart unless-stopped $(docker ps -q)

That’s all Folks!

I hope this brief introduction of how a Xojo built Web Application can be used with Docker has been helpful to some, food for thought to others.

I wish you all the best and I’m curious if the Xojo Forum will get new posts in the near future with Docker Hub Links to interesting Xojo Web Apps which you do provide to the community.

Jürg Otter is a long term user of Xojo and working for CM Informatik AG. Their Application CMI LehrerOffice is a Xojo Design Award Winner 2018. In his leisure time Jürg provides some bits and pieces for Xojo Developers.