Lately I’ve been pushing more toward building my own components from the ground up in JavaScript + Xojo rather than just wrapping libraries already available. It’s not an easy proposition. You don’t take advantage of the years of work that may have been put in to those libraries, but you’re also less at the mercy of those developers when you want to build new things on top or customize existing code. I thought I’d take the opportunity to document the hours I spent on a new component that will be coming to GraffitiSuite for Xojo Web in the next release.

Planning

Arguably the hardest part. Like any development project, a good foundation is the best place to start. Each time I decide to begin work on a new component, the first thing I do is outline, generally, what I want it to look like and how I want it to behave. This process is usually fairly quick as we’re just talking about a rough outline that’s typed or written out quickly. In all, I spend about an hour on the rough draft, then work on other things for a little while my brain works the problem. When I’m not focusing on something is when I have my best ideas, so I let my subconscious take the wheel. Over time, I’ll update that rough draft any new ideas I have. It’s important to quickly jot down anything good so you don’t forget. Then, when I’m ready to complete the planning phase, I gather all of my notes and start filling in the blanks.

At this point, I begin working on the API. What functions will this component need in JavaScript? In Xojo? What properties will it need? What types are those properties? Some things, of course, are a question mark until I actually start implementing. This usually takes a couple of hours not including any time I may spend talking to customers/clients about what their needs from the component might be.

Time: 4 hours

Building

HTML

I start by building the sketched UI in HTML. I want to see how all of the pieces fit together, then I can translate that to JavaScript code later. This isn’t a big process as I don’t implement things like tooltips, animation, etc. I just need a starting point.

Time: 3 hours

JavaScript

I’ve been working with vanilla JavaScript lately, as I don’t want my components to rely on jQuery (which the whole world is trying to get away from). Since I need as much of my code as possible to be client-side, and I want to be OOP, everything is built in JavaScript classes complete with getters and setters for properties — which is a lot of repetitious code that doesn’t seem like it would take long, but it does. I also don’t build my JavaScript directly on the Xojo WebSDK anymore because I need it to be more portable and useful in more places than just Xojo.

The first step here is implementing my default values that I determined were needed in the planning phase as properties of the class. This is also where those getters and setters come in to play. I want a basic new instance of the class to be as feature complete as possible then allow customization by altering those properties at runtime. To accomplish this I create a defaults object that contains all those values, which also serves as a quick reference in code when I’m implementing everything later.

Next I start building the UI. Each of my classes has a render() method that is responsible for creating the HTMLElements and adding them to the document where they’re supposed to be. This has gotten a lot easier with vanilla JS in recent years, but it can still be pretty time-consuming. There’s a lot of back and forth testing during this phase to ensure that the appearance is correct, the defaults are honored, etc.

Once the UI is completed, I go back and implement all of those setters to make the necessary changes to the HTMLElements when their value has changed. This can take a bit of time depending on what that property accomplishes.

Finally, the meat of the component. Any logic gets built at this point such as showing/hiding elements based on events or properties, implementing event callers, filtering data, etc. This is usually the longest part and requires a lot of testing. If the logic of the component fails right out of the gate, the rest of the component can fail too.

Throughout this phase I test against a static HTML page, and correcting anything obvious as I go, try new things, fail at trying new things, and more.

Time: 51 hours

Xojo

Building the Xojo wrapper on my JavaScript class can be painful because it’s just so tedious sometimes. Creating Xojo classes (of which there are typically more than one) with all of their properties, methods, and event definitions to match the JavaScript API can be very mind-numbing, but it’s usually pretty quick, by comparison, if you resist the urge to just walk away for days on end. I also have to make sure that if there are child classes, they have a method to communicate with the parent class and that it functions properly as all of the changes sent to the JavaScript class will happen in the parent.

Time: 15 hours

Testing

Testing should, and does, take a very long time. At this point I recognize and correct not only bugs, but inconsistencies in the API. It’s at this point that all of the polish is added. Making the Xojo class(es) communicate effectively with the JavaScript class(es), ensuring that data types are being honored between the two, testing every feature as in-depth as I can. As many of us know, this is where we really see how well our planning phase went.

Time: 26 hours

Implementation

Depending on the control, this can be very fast or take quite a long time. Some components are just so complex that they’d take ages to build in the GraffitiSuite Demo, so I have to pick and choose what I want to draw the user’s attention to. Likewise, sometimes they’re so simple that there really isn’t much to the demo beyond a couple of buttons and labels. For this component, it’s one that’s so complex that showing off as much as I can is the route to take, but with limited ability for users to change what’s happening on the screen during the demo, so it was pretty quick to build.

Time: 2 hours

TLDR

Just one of the new components coming to GraffitiSuite for Xojo Web Edition in the next release took a total of 101 hours to complete from planning its feature set to creating the demo page in Xojo. I’m feeling even more exhausted just reading that number, but I know that I have a solid foundation for my product going forward. One that I wrote and will be able to easily maintain for use with Xojo or anywhere else I may have a need.

Anthony G. Cyphers is the Lead Developer and Sole Proprietor of GraffitiSuite Solutions and a Xojo MVP. He has been providing custom Xojo components and contract development since 2003.

Although Xojo for Android does not yet have full dark mode support, things continue to head in that direction. Previously your app would adjust its UI for light/dark if the Support Dark Mode property was turned on in the Android Build Settings. Starting in Xojo 2023r3, Color.TextColor and Color.FillColor also adjust their values when run in light mode or dark mode, making it easier for your custom drawing to also adapt.

MobileTextField gets a couple new additions. The ReturnPressed event is now called when, as the name suggests, return is pressed. The AllowSpellChecking property is now also available for MobileTextField and MobileTextArea.

In the Shared Build Settings Inspector there is now a Destination property as there is with other platforms.

Many Android devices have physical back buttons and all let you turn on global software controls that have a back button, but sometimes you want to have the back button clearly shown on the navigation toolbar. With Xojo 2023r3, the new HasBackButton property of MobileScreen can show a back button on the navigation toolbar.

To make it easier to write code that is applicable to both iOS and Android, but not other platforms, there is a new TargetMobile constant available for conditional compilation.

MobilePopupMenu is an all-new control for Android that makes it possible to simplify some of your user interfaces. It works similarly to a PopupMenu on Desktop or Web: when the user taps this control a list of items appears and they can choose one.

On the Advanced tab of the Android Build Settings there is a new Manifest section with a Permissions property. Here you can specify the names of Android permission constants that are needed by Declares or libraries. They are added to the AndroidManifest.xml file when the app is run/built.

MobileHTMLViewer got several enhancements. It now has various processing events, including: DocumentBegin, DocumentComplete, CancelLoad, Error, NewWindow, DocumentProgressChanged and TitleChanged.

And there is now support for running JavaScript using the ExecuteJavaScript method along with the JavaScriptResult and JavaScriptRequest events. ExecuteJavaScript is asynchronous and results appear in the JavaScriptResult event. To call the JavaScriptRequest event, use xojo.execute() in the JavaScript code. A method name and up to 5 parameters can be passed back to Xojo. Learn more in the Xojo Programming Documentation.

The last thing I want to highlight is the new Kotlin Declare. For advanced users, this adds the ability to create Android declares that can pass untouched calls via Alias (with the exception of required type/object handling) to the Kotlin compilation step. This is done by specifying Lib “Kotlin” or adding “:Kotlin” to the end of Lib. Here are a couple examples of what this can look like:

Declare Function AndroidVersion Lib "Kotlin" Alias "android.os.Build.VERSION.RELEASE" As CString

Declare Sub findAllAsync Lib "Object:ctrl:MobileHTMLViewer:Kotlin" Alias "findAllAsync(myfind.toString())" (myFind As CString)

Of course there were many bug fixes as well. Be sure to check out the full release notes for all the details.

Paul learned to program in BASIC at age 13 and has programmed in more languages than he remembers, with Xojo being an obvious favorite. When not working on Xojo, you can find him talking about retrocomputing at Goto 10 and on Mastodon @lefebvre@hachyderm.io.

In case you missed it, the previous article explains in detail what Cell Renderers are and how to use them. Anything you can imagine can be done inside your WebListView control cells. In order to do so, be prepared to write some JavaScript code. Today we will create a very basic example, a Custom Cell Renderer capable of showing Bootstrap Badges.

If we think about it, in a nutshell, what we want to achieve is to inject this HTML (coming directly from Bootstrap’s docs) into our cells:

<span class="badge badge-pill badge-primary">Primary</span>

The first step is to create a new class in our Xojo project. Let’s call it BadgeColumn, for example. It will be a child of WebListboxCellRenderer Superclass.

Extending WebListBoxCellRenderer will allow our class to listen to some events that Xojo will emit, used to render our badges inside the table. There are three: Deserialize, JavascriptClassCode and Serialize.

We will ignore all of them for the moment, except JavascriptClassCode. But it is important to know that Serialize must return an instance of a JSONItem class, or you will get a NilObjectException, as soon as you add a new row using this renderer.

Let’s add this code to the Serialize event, we will come back to this event later:

Return New JSONItem

JavascriptClassCode event will be executed only once, no matter the amount of instances of our renderers we have. It must return a String containing a JavaScript class that extends XojoWeb.ListboxCellRenderer, containing a render() method inside (remember that JavaScript is case-sensitive).

In render(), we will simply replace the contents of the cell DOM element with the badge HTML code snippet provided by the Bootstrap docs that we just saw.

In order to keep it as readable as possible, what I prefer to do is to create a String Constant called “kJavascriptClass” (the name is arbitrary, use anything you want), with the JavaScript code inside:

class BadgeColumn extends XojoWeb.ListboxCellRenderer {
    render(controlID, row, data, rowIndex, columnIndex, cell) {
        cell.innerHTML = '<span class="badge badge-pill badge-primary">Primary</span>';
    }
}

Having our raw JavaScript as a String constant, our JavascriptClassCode event can just return it:

Return kJavascriptClass

Congratulations! That’s your first Cell Renderer. It won’t do a lot of things, but that’s the basic plumbing needed to start creating lots of them. With this new class, following the steps you’ve learned on the first part of this tutorial, you will be able to use it in your tables. Drop a WebListView into your WebPage and add a handler for the Opening event. Then add this code:

Me.AddRow("Hello, World!")
Me.CellValueAt(0, 0) = New BadgeColumn

It will add a row to the control, and then it will make use of our new Cell Renderer to replace the first cell of the first row. If you run your project, you will see a website that looks like the following screenshot:

While promising, you will notice the badge says “Primary” instead of the “Hello, World!” message we want. Looking at the render() method, within our Javascript, you will find “data” as one of the parameters it receives. It is a JSON object that comes from (I’m sure you’ve guessed it already) the Serialize event we saw a few paragraphs ago.

Edit the Serialize event handler. This time, instead of returning an empty JSONItem, we will fill it with some data.

Var json As New JSONItem
json.Value("content") = "Test"
json.Value("appearance") = "success"
Return json

Next, update your kJavascriptClass constant with the following snippet of code. Notice we are making use of the values we have in the data parameter, coming as a Javascript object:

class BadgeColumn extends XojoWeb.ListboxCellRenderer {
    render(controlID, row, data, rowIndex, columnIndex, cell) {
        cell.innerHTML = '<span class="badge badge-pill badge-' + data.appearance + '">' + data.content + '</span>';
    }
}

Running the web application again will make you smile a bit:

Nearly there! Now that we know how to communicate between Xojo and the cell that is running in our browser, we just need to find a way to create instances of these BadgeColumn classes, using real content.

My preference is to create a Constructor with the parameters I want, and some class properties. This is completely up to you.

Create a few properties for our BadgeColumn class:

• Content As String
• Appearance As String

Then a Constructor with the following parameters:

• content As String
• appearance As String

Inside our new Constructor, you will need to call its Superclass Constructor, wiring the internal properties of the instance with the parameters, as following:

Super.Constructor
Self.Content = content
Self.Appearance = appearance

The Serialize event handler can be updated now to make use of our new properties, instead hardcoded data:

Var json As New JSONItem
json.Value("content") = Content
json.Value("appearance") = Appearance
Return json

Finally, we need to update the Opening event we used in our ListBox. Just remember thtat BadgeColumn now needs to be instantiated with some parameters:

Me.AddRow("")
Me.CellValueAt(0, 0) = New BadgeColumn("Hello, World!", "warning")

Run the application again and see what happens:

Whoops! That doesn’t looks right, does it? We are missing one important step.

The communication between Xojo and the control that lives inside JavaScript is bidirectional. This way, “Data” can be modified while running in your browser, and it will be sent back to Xojo. In order to fix our issue, we just have to take care of the Deserialize event handler we’ve completely ignored until now, with the following code:

Content = js.Value("content")
Appearance = js.Value("appearance")

This will recreate our instance using fresh data coming from JavaScript. Run the project again and voilà!, your table looks perfect now:

This is not the end, but the beginning of your journey. With this little recipe you already have a lot of knowledge and hours of fun ahead, building your Cell Renderers. Once you feel comfortable, the next step I recommend is to learn how to emit custom cell actions from your JavaScript that you can handle from the CustomCellAction event of your WebListBox controls. In order to see how this works, check some of the examples coming with Xojo, under Web > WebSDK > WebListBox Cell Renderers. The open source repository we saw in the previous article, xojo-web-cell-renderers, also makes use of this event in some of the included Cell Renderers.

Conclusion

While we had to get our hands dirty with JavaScript, it’s really fun to create Cell Renderers for our Xojo projects. They are super easy to share and reuse, and will make your tables look so much better. The source code for this example project can be downloaded here.

I hope you find this tutorial useful, if you have any question, please feel free to ask them in the forum.

Ricardo Cruz helps companies with large websites to optimise and secure them, making them reliable and ensuring they are always online. He uses Xojo for building internal tools, but he is starting to explore the desktop software market, with apps like Today and Beauty Shot. As a hobby, during his free time, Ricardo has been teaching Scuba Diving for more than 10 years.

In this example, I’ll show you a JavaScript that calculates the difference between two geo coordinates given by longitude and latitude. We will design a GUI with 4 Textfields. Two fields contains the longitude and latitude of the first coordinate, two other fields store the longitude and latitude of the second coordinate. Furthermore we need a label that shows the result of the calculation and a button to start it. Then we look at the JavaScript code.

For the calculation we need the longitude and latitude in the unit radiance. Because that we need a function that converts between angle and radiance since we have the coordinates in the unit angle. The formula for the calculation is y = x * Pi / 180. 

A JavaScript function for that looks like this:

function DegToRad( deg ) {         
        return deg * Math.PI / 180; 
}

The keyword “function” starts a function definition, followed by the function name. The parameters are written with brackets, just like in Xojo, but without data type. The calculation for the function body is surrounded by curly brackets. Math.Pi is a built-in constant that defines Pi, so we use it here to do the math. 

Then we can write the function for the distance calculation:

function distance( lat1, lon1, lat2, lon2 ) {                

       var R = 6371; // The earth's radius in km

       lat1 = DegToRad(lat1);
       lat2 = DegToRad(lat2);
       lon1 = DegToRad(lon1);
       lon2 = DegToRad(lon2);
  
       var x = (lon2 - lon1) * Math.cos((lat1+lat2) / 2);
       var y = (lat2 - lat1);
       var d = Math.sqrt(x*x + y*y) * R;
       return d;
 
}
 

We have a function with four input parameters. That are the latitudes and longitudes of the coordinates. For each of these values we call the converting function and save the returned value in the variable again. Because these variables are defined as parameters of the function, we don’t need to declare them again. Moreover JavaScript has dynamic data types and internally uses doubles for all numbers. Because of this we don’t need to define them. All other variables (R, x, y and d) are explicitly declared with the keyword “var”. When using variables, we must pay attention to the fact that JavaScript is a case-sensitive language. A and a would be two different variables!

This JavaScript function is perfect for our use. Now we want to look at the possibilities to embedded it to our program.  At first we want to evaluate the JavaScript. Because that we create a new instance of the JavaScriptEngineMBS class and evaluate the JavaScript with the “Evaluate function”. In the parameter of the function we set our JavaScript as a string. Additionally, we append the call of the function in JavaScript syntax. 

	Dim js As New JavaScriptEngineMBS

	Dim r as Variant = js.Evaluate("function DegToRad( deg )  { return deg * Math.PI / 180 ; } function 	distance( lat1, lon1, lat2, lon2 ) { var R = 6371 ; lat1 = DegToRad(lat1); lat2 = DegToRad(lat2); lon1 = DegToRad(lon1); lon2 = DegToRad(lon2); var x = (lon2 - lon1) * Math.cos((lat1 + lat2) / 2); var y = (lat2 - lat1); var d = Math.sqrt(x * x + y * y) * R ; return d ; } distance( 50.73743, 7.0982068, 50.61, 7.2025);")

Then we have the result of the variable. The result is of type variant with an embedded double value. If we want the result as a string, we call the “EvaluateToString” function in place of the “Evaluate” function with the same parameters and the plugin performs toString operation in JavaScript if needed. 

It would be very annoying if we have to change the string of the JavaScript for each query by hand. Furthermore we want to calculate the difference between the coordinates that are set in the text fields and not between fix coordinates. One possibility to do this is to set global properties in JavaScript environment with the MBS Plugin functions.

Before we call one of the evaluation functions we set the variables like that: 

js.GlobalProperty("lat1") = LatitudeA.Text
js.GlobalProperty("lat2") = LatitudeB.Text
js.GlobalProperty("lon1") = LongitudeA.Text
js.GlobalProperty("lon2") = LongitudeB.Text

Then we replace the constant values in the function call, with our variables : 

distance( lat1, lon1, lat2, lon2 )

If we want to avoid setting this huge part of script in every evaluation function, we can add the DagToRad function and the distance function to the environment of the JavaScript. Then we only need to call the distance function with the right parameters. That is easier for debugging, too. Here the final example code:

Dim lat1 As String = LatitudeA.Text
Dim lat2 As String = LatitudeB.Text
Dim lon1 As String = LongitudeA.Text
Dim lon2 As String = LongitudeB.Text
Dim r As Variant 
 
Dim js As New JavaScriptEngineMBS

js.AddFunction "DegToRad", "function( deg ) { return deg * Math.PI / 180 ;}"  js.AddFunction "distance", "function( lat1, lon1, lat2, lon2 ) { lat1 = DegToRad(lat1); lat2 = DegToRad(lat2); lon1 = DegToRad(lon1); lon2 = DegToRad(lon2); var R = 6371; var x = (lon2-lon1) * Math.cos((lat1+lat2)/2); var y = (lat2-lat1); var d = Math.sqrt(x*x + y*y) * R; return d; }"
 r = js.CallFunction("distance", lat1, lon1, lat2, lon2)
 Result.Text = str(r, “####.##") 

Once the JavaScriptEngineMBS object is initialized, you can store it in a window property and reuse it several times to do more calculations. A great use for this JavaScript is to do calculations in your applications to match the hash/signature algorithm used by a web service to authenticate. If you get a JavaScript snippet, you can just run it, if required dependencies are provided. And you may find it useful to perform JavaScript server side for your Xojo web apps.

I hope that you like our new JavaScript functions. I wish you lots of fun with them. If you have any questions, please do not hesitate to contact us. 

Stefanie Juchmes studies Computer Science at the University of Bonn. She came in touch with Xojo due to the work of her brother-in-law and got a junior developer position in early 2019 at Monkeybread Software. You may have also read her articles in Xojo Developer Magazine. 

However, by using a little JavaScript you can easily add this capability to Xojo.

In order to follow this tutorial, create a new Web project and add a new WebCanvas control from the Library to the default Web Page added to the project: WebPage1. With the WebCanvas selected in the Navigator, change its name to cCanvas using the Inspector and add the Paint Event Handler to it using the Insert > Event Handler option from the menu. Use the following code to draw a black colored rectangle:

g.FillRect 0, 0, g.Width, g.Height

Obviously, you can draw anything you want in the WebCanvas or even paint a picture on it. The achieved result will be the same. For example, we can draw a picture added to our project (with the filename “landscape”), using this line of code in the Paint event of our cCanvas instance:

g.DrawPicture landscape, 0, 0, g.Width, g.Height

Retrieving the WebCanvas image data

The first interesting step is retrieving the underlying image represented by the WebCanvas and that is something we can get using a fragment of JavaScript code executed from the Xojo side. This is the process we will execute from the Action Event Handler of a WebButton added to the WebPage1 from the Library. In fact, this will be the button in charge of calling the process to save the image as a picture file on the user disk.

Once the WebButton has been added to the WebPage from the Library, put the following code in its Action Event Handler:

Dim js() As String
js.Append "var canvas = document.getElementById('" + cCanvas.ControlID + "_canvas');" // We get the item reference based on its ID
js.Append "var img = canvas.toDataURL(""image/png;base64;"");" // We access to the image data, encoded as a base64 string
js.Append "document.location.hash=img" // We assign that data to the document Hash property, so we can retrieve it from the Xojo side

Dim execute As String = Join(js,"")

ExecuteJavaScript execute // Finally, we execute the JavaScript code

As you can see, the first line of the JavaScript code is in charge of retrieving the cCanvas reference from the DOM (document object model) of the Web Page. For that, we use the ControlID property on our WebCanvas instance, adding the “canvas” appended by Xojo to all these kind of objects when generating the source code for the page.

Once we get the reference to our Canvas instance, the following line of code retrieves the picture content itself and assigns it to the img variable. The trick here is that we retrieve that information in its URL format and, thus, encoded as Base64 data that we can assign to other document properties without losing its original meaning.

Then, we assign the data to the document Hash property. This is the property that allows us to jump to other page sections previously tagged. However, we will use this property as a temporary storage container for passing the data between the HTML/JavaScript side of the web page and the Xojo side of our code. Why we do this? Well, because we can add the HashTagChanged Event Handler to the Session object so it will fire every time we change the value of the Hash property and we will be able to retrieve the data from that property.

Retrieving the image, from the Xojo side

So, the next step is adding the HashTagChanged event to the Session object of our example project, writing the following snippet of code in the associated Code Editor:

Dim data As String = DecodeBase64(Hashtag.NthField(",",2) ) // We retrieve the information saved in the Hash, but just the relevant data for the image and not the URL part.
wp = New WebPicture(data,"My_Picture.png") // We create a new WebPicture instance using the previously retrieved image data in the constructor, and giving a default file name for the image
wp.ForceDownload = True // We want to force the file download instead of showing it
ShowURL wp.URL // and finally we start the file download process.

Hashtag = "" // Let's empty the hash property, just to make sure that the event will fire even if the WebCanvas doesn't change its contents

As you can see, in the first line of code we retrieve the image data. We do that using the NthField command because we are only interested in the image data and not in the URL information that precedes it. In addition, we decode the previously encoded data as Base64, so we really get the bytes of the image in PNG format.

Once we get the picture data, we can use any of the available constructors for the WebPicture class; in this case the one that lets us create a new image from the passed data. In addition, we use this class because it is a subclass of WebFile, and that means that it is simpler to force the download as an image file instead of showing its contents in a new web page.

In fact, this is what we achieve setting the ForceDownload property to True, so when in the following line we use ShowURL we will be forcing the download of the file instead of displaying the image as a new page in the browser. Goal achieved!

Download persistence

You probably noted that the wp variable is not declared in the previous fragment of code. This is because we need to make sure that the object it points to is in scope during the file downloading process and won’t get destroyed once we exit the Event Handler (we would want a message error from the web browser in that case). The solution is pretty easy – we only need to add a new property to our Session object, using the following values:

• Name: wp
• Type: WebPicture
• Scope: Private

Now, every time you run the app web and click the button, you’ll see how the web browser downloads the WebCanvas image as a PNG file to disk.

To summarize, in this tutorial we have seen a way to “communicate” between the data generated executing JavaScript code in our web app so we can retrieve and use it from the Xojo side of our Web App; in this case applied to the retrieval and saving of the underlying picture represented by a WebCanvas object.

*Watch a video of this Tutorial in Spanish

*Read this Tutorial in Spanish

Javier Rodri­guez has been the Xojo Spanish Evangelist since 2008, he’s also a Developer, Consultant and Trainer who has be using Xojo since 1998. He manages AprendeXojo.com and is the developer behind the GuancheMOS plug-in for Xojo Developers, Markdown Parser for Xojo, HTMLColorizer for Xojo and the Snippery app, among others