Developing Native Mobile Apps with CodeRAD

Codename One is a toolkit for Java and Kotlin developers who want to build native apps for both iOS and Android, but don’t want to have to maintain two separate codebases. It provides a cross-platform SDK for developing native mobile apps using a single codebase with 100% code reuse between iOS and Android.

Unlike Flutter, which uses Dart as programming language, Codename One apps are written in Java or Kotlin, giving you access to its well established and mature eco-system.

CodeRAD is a library for Codename One that facilitates rapid development of Codename One apps using established design patterns such as dependency injection and MVC (model-view-controller) . It includes foundation classes for developing models, views, and controllers, which dramatically increases code re-use and reduces application complexity. It also provides an XML-based declarative language for building views.

CodeRAD aims to increase developer productivity in building mobile applications by:

Another way of stating this is to say that CodeRAD aims provide second, and third order components to mobile app developers, as described in the following sections.

There are just a few fundamental concepts required to start using CodeRAD to accelerate your development.

The Entity sits at the core of CodeRAD. The Entity class is the base class of all model classes in CodeRAD. Each Entity has an EntityType which defines the properties that are available in an entity. Properties, in turn, may be "tagged" with zero or more Tags. These tags can be used to lookup properties on an entity in a more generic way than referring to the property itself.

We provide a set of existing tags in the schemas package that can be used as a common foundation by both models and views. These tags were adapted from the schema definitions at https://schema.org.

The concept of tags is a simple one, but they have powerful effect. If a view needs to render its model’s "phone number" (e.g. a contact list view), then it doesn’t need to know anything about the properties in the model. It is able to look up the phone number of the model by the Person.telephone tag:

As long as the model includes a property that is tagged with the Person.telephone tag, this will work. If the model doesn’t include this property, then this will simply return null.

The following diagram depicts how Tags can be used as a sort of "glue" layer between the View and the Model, and Action categories (discussed later under "Controllers") as a glue lasyer between the View and the Controller.

The "View" is the piece of the MVC pie that we are most interested in sharing and reusing. A View is a Component that includes support to "bind" to a view model (an Entity), such that when properties on the view model are changed, the "View" updates to reflect the change.

The recommended way to develop views is using RADL, Code RAD’s declarative markup language for creating visual components. RADL files are converted to Java view classes at compile time by CodeRAD’s annotation processor.

The following is a basic RADL file that simply displays "Hello World"

Views should be placed inside the common module in the src/main/rad/views directory, using Java package hierarchy conventions. E.g. If want your view to compile to the class com.example.MyView, then you would create your view file at src/main/rad/views/com/example/MyView.xml.

A single RADL file will generate multiple Java classes. For a given view file MyView.xml, it will generate the following classes:

Controllers serve two functions in CodeRAD:

Let’s take look under the hood to see how this "Hello World" app is producted.

The starting point for your app is the com.example.myapp.MyRADApp class, located in the common/src/main/java directory.

The contents are shown below:

This class overrides ApplicationController, and listens for the StartEvent, which is fired when the app starts, or is brought to the foreground.

The effective action performed by the event handler is the line:

This creates a new StartPageController and shows it.

The StartPagePageController class is a FormController subclass that is generated from the StartPage view at compile-time by the CodeRAD annotation processor.

The StartPage view is implemented as a RAD View using XML. It is located inside the common/src/main/rad/views directory.

The contents are shown below:

For this tutorial, I want to start from scratch, so let’s delete all of the contents from StartPage.xml, and replace it with the following:

Upon restarting the app in simulator, it should now look like:

Let’s go through this code line by line.

The Codename One simulator supports a "Hot Reload" feature that can dramatically improve productivity. Especially if you’re like me, and you like to experiment with the UI by trial and error.

Hot Reload is disabled by default, but you can enable it using the Tools > Hot Reload menu.

If the Reload Simulator option is checked, then the simulator will monitor the project source files for changes, and automatically recompile and reload the simulator as needed.

The Reload Current Form option is the same as the Reload Simulator option except that it will automatically load the current form when the simulator reloads. When using this option, you will lose the navigation context (e.g. the parent controller will be the ApplicationController) and data, when the simulator reloads.

The remainder of this tutorial will assume that you have Hot Reload enabled

Keep the simulator running, and open the CSS style stylesheet for the project, located at common/src/main/css/theme.css.

Add the following snippet to the theme.css file:

Within a second or two after you save the file, you should notice that the "Hello World" label in the simulator has turned blue.

This is because the Label component’s default UIID is "Label", so it adopts styles defined for the selector "Label" in the stylesheet.

The above stylesheet change will change the color of all labels to blue. What if we want to change only the color of this label without affecting the other labels in the app? There are two ways to do this. The first way is to override the fgColor style inline on the <label> tag itself.

So far we’ve only used the <label> tag, which corresponds to the Label component. You are not limited to <label>, nor are you limited to any particular subset of "supported" components. You can use any Component in your XML files that you could use with Java or Kotlin directly. You can even use your own custom components.

The tag name will be the same as the simple class name of the component you want to use. By convention, the tag names begin with a lowercase letter. E.g. The TextField class would correspond to the <textField> tag.

For fun, let’s try adding a few of the core Codename One components to our form to spice it up a bit.

After changing the contents of your StartPage.xml file to the above, and saving it, you should see the following result in the simulator:

CodeRAD is built around the Model-View-Controller (MVC) philosophy which asserts that the View logic (i.e. how the app looks) should be separated from the Controller logic (i.e. what the app does with user input). Actions form the cornerstone of how CodeRAD keeps these concerns separate. They provide a sort of communication channel between the controller and the view, kind of like a set of Walkie-talkies.

To go with the Walkie-talkie metaphor for a bit, A View will broadcast on a few frequencies that are predefined by the View. It might broadcast on 96.9MHz when the "Help" button is pressed, and 92.3MHz when text is entered into its username text field.

Before displaying a View, the Controller will prepare a set of one-way Walkie-talkies at a particular frequency. It passes one of the handset’s to the view - the one that sends. It retains the other handset for itself - the one that receives.

When the view is instantiated, it will look through all of the walkie-talkie handsets that were provided and see if any are set to a frequency that it wants to broadcast on. If it finds a match, it will use it to broadcast relevant events. To continue with the example, if finds a handset that is tuned to 96.9MHz, it will send a message to this handset whenever the "Help" button is pressed.

When the controller receives the message in the corresponding hand-set of this walkie-talkie, it can respond by performing some action.

The view can also use the set of Walkie-talkies that it receives to affect how it renders itself. For example, if, when it is instantiated, it doesn’t find any handsets tuned to 96.9MHz, it may "choose" just to not render the "Help" button at all, since nobody is listening.

Additionally, the Controller might attach some additional instructions to the handset that it provides to the view. The view can then use these instructions to customize how it renders itself, or how to use the handset. For example, the handset might come with a note attached that says "Please use this icon if you attach the handset to a button", or "Please use this text for the label", or "Please disable the button under this condition".

In the above metaphor, the frequency represents an instance of the ActionNode.Category class, and the walkie-talkies represent an instance of the ActionNode class. The View declares which Categories it supports, how it will interpret them. The Controller defines Actions and registers them with the view in the prescribed categories. When the View is instantiated, it looks for these actions, and will use them to affect how it renders itself. Typically actions are manifested in the View as a button or menu item, but not necessarily. EntityListView, for example, supports the LIST_REFRESH_ACTION and LIST_LOAD_MORE_ACTION categories which will broadcast events when the list model should be refreshed, or when more entries should be loaded at the end of the list. They don’t manifest in any particular button or menu.

Whereas the <button> tag will create a single button, which can be optionally "bound" to a single action, the <buttons> renders multiple buttons to the view according to the actions that it finds in a given category. Let’s change the example from the previous section display a menu of buttons. We will:

And add the following to the initControllerActions() method of your controller class:

If all goes well, the simulator should reload to resemble the following screenshot:

It’s time to grow beyond our single-form playpen, and step into the world of multi-form apps. Let’s create another view in the same folder as StartPage.xml. We’ll name this AboutPage.xml. If you’re using IntelliJ, like me, you can create this file by right clicking the "myapp" directory in the project inspector, and select New > File as shown here:

Then enter "AboutPage.xml" in the dialog:

And press Enter

Add the following placeholder contents to the newly created AboutPage.xml file:

Finally, let’s add a button to our original view, StartPage.xml as follows:

When the simulator reloads, you should now see this button:

Click on this button, and it should take you to the "About Us" view we just created.

Notice that the About Us form includes a Back button that returns you to the Start Page. This is just one of the nice features that you get for free by using CodeRAD. There is a lot of power packed into the rad-href attribute. In this case we specified that we wanted to link to the AboutPage view using the "#AboutPage" URL, it enables other URL types as well. To learn more about the rad-href attribute, see (TODO section of manual on rad-href).

So far we’ve been working only with the V and C portions of MVC. In this section, I introduce the final pillar in the trinity: the Model. Model objects store the data of the application. In CodeRAD, model objects implement the com.codename1.rad.models.Entity interface. We’re going to skip the conceptual discussion of Models in this tutorial, and dive directly into an example so you can see how they work. After we’ve played with some models, we’ll circle back and discuss the theories and concepts in greater depth.

Most apps need a model to encapsulate the currently logged-in user. Let’s create model named UserProfile for this purpose.

Create a new package named "com.example.myapp.models". In IntelliJ, you can achieve this by right clicking on the com.example.myapp node in the project inspector (inside the src/main/java directory of the common module), and select New > Package, as shown here:

Then enter "models" for the package name in the dialog:

Now create a new Java interface inside this package named "UserProfile".

Next, let’s create a view that allows us to view and edit a UserProfile.

In the same directory as the StartPage.xml file, create a new file named UserProfilePage.xml with the following contents:

This view looks very similar to the StartPage and AboutPage views we created before, but it introduces a couple of new elements:

Before we fire up the simulator, we also need to add a link to our new form so we can test it out. Add a button to the StartPage view that links to our UserProfilePage:

Now fire up the simulator and click on the User Profile button we added. YOu should see something like the this:

This is a little boring right now because we haven’t specified a UserProfile object to use as the model for this view, so it just creates a new (empty) instance of UserProfile and uses that. Let’s remedy that by instantiating a UserProfile in our controller, and then use that profile as the view for our profile.

Open the RADApp class and implement the following method:

Most of this snippet should be straight forward. I’ll comment on two aspects here:

Now, we will make a couple of changes to the StartPage view to inject this profile into the UserProfile view.

First, we need to add UserProfile to the imports of StartPage.

Next, add the following tag somewhere in the root of the StartPage.xml file:

This declares a "variable" named profile in our view with the value of the UserProfile lookup. This is roughly equivalent to the java:

Finally, change the <button> tag in the StartPage that we used to link to the UserProfile page to indicate that it should use the profile as the model for the UserProfilePage:

The active ingredient we added here was the "{profile}" suffix to the URL. This references the <var name="profile"…​> tag we added earlier.

When we’re done, the StartPage.xml contents will look like:

Now, we we click on the User Profile button, it should display the details of the profile we created:

CodeRAD models are designed to allow for easy binding to other models and to user interface components. We’ve already seen how the <radLabel> tag can be bound to a model property using the tag attribute, but you aren’t limited to static labels. There are radXXX components for many of the fundamental Codename One components. E.g. <radTextField>, <radTextArea>, <radSpanLabel>, and many more. Later on, you’ll also learn how to build your own binding components, but for now, let’s have a little bit of fun with the standard ones.

To demonstrate that you can bind more than one component to the same property, let’s add a <radTextField> that binds to the email property just below the existing <radLabel>.

You’ll notice that as you type in the email text field, the value of the email label also changes. This is because they are bound to the same property of the same model.

We can even go a step further. It is possible to bind any any property to the result of an arbitrary Java expression so that the property will be updated whenever the model is changed.

As an example, let’s add a button that is enabled only when the model’s email property is non-empty:

You will notice, now, that if you delete the content of the email text field on the form, the Save button becomes disabled. If you start typing again, the button will become enabled again.

In this example we bound the enabled property of Button so that it would be updated whenever the model is changed. You aren’t limited to the enabled property though. You can bind on any property you like. You can even bind on sub-properties, e.g.:

In the above example, the button text will be red when the email field is empty, and black otherwise.

By default, changes to bound properties take effect immediately upon property change. For example, if you bind the visible property of a label, then it will instantly appear when the value changes to true, and instantly disappear when the value changes to false. Interfaces feel better when changes are animated.

The rad-transition attribute allows you to specify how transitions are handled on property bindings. Attributes that work particularly well with transitions are ones that change the size or layout of a component.

The following example binds the "layout" attribute on a container so that if the user enters "flow" into the text field, the layout will change to a FlowLayout, and for any other value, the layout will be BoxLayout.Y:

If you run the above example, it will begin with rendering the labels vertically in a BoxLayout.Y layout as shown below:

If you type the word "flow" into the textfield, it will instantly (upon the "w" keystroke) start animating a change to a flow layout, the final result shown below:

So far our examples have involved only views of single models. Most apps involve list views where multiple models are rendered on a single view. E.g. In mail apps that include a list of messages, each row of the list corresponds to a distinct message model. CodeRAD’s <entityList> tag provides rich support for these kinds of views.

To demonstrate this, let’s create a view with an entityList. The contents of this view are as follows:

This defines a view with single entityList. The provider attribute specifies the class will provide data to this view. We need to implement this class and add a lookup to an instance of it in the controller.

The following is a sample provider implementation:

Our provider extends AbstractEntityListProvider and needs to implement at least the getEntities() method. For most real-world use-cases you’ll need to override the createRequest() method, but we’ll reserve discussion of that for later.

getEntities() is triggered whenever the entity list is requesting data. The request parameter may include details about which entities the list would like to receive. Out of the box, there two basic request types: REFRESH and LOAD_MORE. A REFRESH request is triggered when the list if first displayed, and whenever the user does a "Pull to refresh" action on the list view. A LOAD_MORE request is triggered when the user scrolls to the bottom of the list.

You can use the Request.setNextRequest() method to provide details about the current cursor position, so that the next LOAD_MORE request will know where to "start".

One last thing, before we fire up the simulator: We need to add a lookup to an instance of our provider. The best place to register lookups is in the onStartController() method of the controller. In your MyRadApp's onStartController() method, add the following:

Now, when you launch the simulator, you will see something like the following:

Earlier, in Form Navigation, we learned how to navigate between forms using a button tag with the rad-href attribute. When developing for tablet and desktop, you may want to navigate to a different view within the same form; sort of like using frames in HTML. A mail app will often have a list of messages on the left side of the screen, and details of the currently selected message on the right, as shown in the Gmail app screenshot below:

In our previous examples with rad-href, we specified which view we wanted to navigate to, but we didn’t specify where we wanted the view to be displayed. By default, it navigates to a new form whose FormController is a child of the current FormController. The full syntax of rad-href supports targeting the view to a different location in both the view hierarchy and the controller hierarchy.

Suppose we wanted our view to be displayed inside a Sheet instead of a new form. Then we could do something like:

Alternatively, suppose we wanted to display the view inside a Container within the current form. Then we could do:

In the above example, when the user presses the button, it will load the AboutPage view into the TargetFrame container.

Change the contents of the StartPage view to:

Launch the simulator, and enable the Desktop skin by selecting the Skin > Desktop.skin menu item as shown below.

Then the app should appear something like the followign screenshot:

Click on the My Profile link on the left, and you should see the user profile page appear on the right, as shown below.

If you click on the About Page in Sheet button, it will load the AboutPage view inside a sheet as shown here.

You can also control the position of where the sheet will be shown by using one sheet-top, sheet-left, sheet-right, or sheet-center instead of the sheet option that we used in this example.

Up until now, we haven’t created any custom controllers for our views, other than the application controller (the MyRadApp class). Since all events propagate up the controller hierarchy, it is possible just to handle all of the events in the application controller, as we’ve been doing. Keeping all of our logic inside a single application-wide controller has some benefits for small, example apps, but for most real-world apps, you’ll want to be intentional about your application’s architecture.

Best practice is to create a ViewController for each view, which will be responsible for handling application logic pertaining to that view. This practice will promote better modularity, which will make it easier to maintain your code, and to reuse components in other projects.

You can assign a custom view controller to a view by adding a view-controller attribute to the root element of your view. E.g.

Let’s expand this to a complete example.

In our sample app project, create a new package in the common/src/main/java directory named com.example.myapp.controllers, and create a new Java class in this package named "StartPageViewController.java" with the following contents:

Now, change the StartPage.xml template to the following content:

Now try running the example in the simulator.

Our button is conspicuously missing from this form. This is because it is bound to the HELLO_CLICKED action category, but our controller hasn’t added any actions to this category yet. Let’s add an action to our view controller now.

The simulator should automatically reload upon saving the controller file, and the "Hello" button should appear. Click "Hello" to confirm that our ToastBar info message appears as shown below:

Since RAD views are Components themselves, they can be used inside other views, just like other components are. To demonstrate this, let’s create create a form to allow users to enter contact information such as name, email, billing address, and shipping address. Since the billing address and shipping address will likely use the same fields, we’ll create a AddressView view and use it from the main form.

Create a new view in the same package as our existing views named AddressForm.xml with the following contents:

Now create another view called ContactForm.xml in the same directory with the following contents.

And finally, modify the actionPerformed() method of the MyRADApp class to display the contact form we just created on start:

If you fire up the simulator, the app should look something like the following screenshot:

Notice that the contact form includes two embedded address forms. One for the billing address and the other for the shipping address. Let’s walk through the ContactForm.xml source to see what is happening here.

You’ve seen most of the tags before in previous examples. The new part that I’d like to highlight here are the two <addressForm> tags:

These create instances of the AddressForm view that we defined in the AddressForm.xml`file. The `view-model attribute is necessary to specify the view model that should be used for the address form. The value "new" is a special value that indicates that the view should create a new view model for itself. If this were omitted, it would attempt to use the view model of the current view which we don’t want here, because the model for the ContactForm isn’t compatible with the model for the AddressForm.

This is roughly equivalent to:

With our current contact form, the AddressForm view models aren’t connected to the ContactForm view model, which isn’t idea. Let’s improve this by defining tags for billingAddress and shippingAddress in the ContactForm view model:

Now, change the view-model attribute of the <addressForm> tags to use the shippingAddress and billingAddress properties respectively:

Notice that I used the explicit getBillingAddress() and getShippingAddress() methods on the ContactForm view model. I could also have used the more generic getEntity(TAG) method:

Both are fine here, but I chose to use the explicit getters as it is more succinct and easier to understand.

Later on you’ll learn another, more succinct, way to access properties of the view model using RAD property macros. E.g. The following is also equivalent:

Since you can use any component (i.e. com.codename1.ui.Component subclass) in your views, it follows that you can also develop your own components and use them in your views. You’ve already seen a special case of this in Views within Views, where we used a view that we created from another view.

The only thing you may need to do in order to use your custom component from a view is add an import statement for your component’s class.

If your component has a no-arg constructor, then it should just work. If it doesn’t have a no-arg constructor, or it has some special requirements for how it is used, then you may need to also implement a ComponentBuilder for your component. Later on, I’ll also show you how to use dependency injection to have certain properties and arguments automatically "injected" into your component at runtime.

To demonstrate this, create a Java class named HelloComponent in the package com.example.myapp.components, with the following content:

No open the contact form from the previous example and add an import statement for our new package:

If you save the file, it will automatically recompile the XML schema so that the <helloComponent> tag will be available for type hinting/autocompletion in a few moments.

Add the helloMessage attribute to set the message in our component. Notice that IntelliJ provides type hints for this property also. It automatically picks up all the setters and getters for your class and converts them into XML attributes.

Let’s add an instance that says "Hello Steve":

The result:

To get started, go to https://start.codenameone.com, and select "Code RAD (MVC) Starter Project" from the Templates menu.

For the package name, change it to "com.example.tweetapp", and also change the Main Class to "Tweetapp".

The press the Download button.

After a few seconds you should be prompted to download the project as a ZIP file. Save this zip file somewhere on your local drive, extract it, then open it in IntelliJ IDEA.

Once the project is opened, press the icon on the toolbar to run the project in the Codename One simulator.

The flow-chart above shows five forms that we will be recreating:

We’ll begin by making empty views for each of these forms.

First let’s create a new package for our views. Expand the common/src/main/rad/views/com/example/tweetapp nodes in the project inspector on the left. Then right-click the tweetapp node and select New > Directory

Enter "views" for the folder name, and press Enter.

Then right-click on this new views directory node, and select New > File:

Enter "WelcomePage.xml", in the prompt, and press Enter.

Now, open the WelcomePage.xml file, and change the contents to the following:

Before proceeding, let’s try running the project in the simulator to make sure that it compiles OK. Running the project will also run the CodeRAD annotation processor which will generate Java classes from our WelcomePage view so that they will be available for type hinting and auto-complete in IntelliJ.

Press the button on the toolbar. It may take a while to run the first time as it might have to download dependencies. Subsequent runs should only take a few seconds.

If all goes well, you should see the simulator pop up with a "Hi World" app as shown here:

Notice that this isn’t showing our WelcomePage yet. It is showing the default StartPage template from the template.

Let’s modify the ApplicationController so that it shows our WelcomePage view as the default view.

The ApplicationController class for this application is defined in the TweetApp class inside the com.example.tweetapp package (inside the src/main/java directory).

Open this file and find the actionPerformed() method. It should look something like the following listing:

Let’s change the new StartPageController(this).show() call to

Now, if you restart the simulator, it should show our WelcomePage view.

The Codename One simulator has a Hot Reload feature that can dramatically improve your development experience by reducing the turnaround time for testing changes to your source code. See Hot Reload for more information about this feature.

For most of this tutorial, I will be using the Reload Current Form setting of Hot reload so that the simulator will automatically reload the current form after I make changes to the source.

Our welcome page is currently just a placeholder that says "Welcome". Let’s change it to resemble the Twitter welcome page as shown below:

In order to replicate this content and structure, add the following to the WelcomePage.xml file:

Nothing fancy here. I’m just trying to roughly replicate how the form is laid out using Codename One’s layout managers. Now reload the simulator (if you have Hot Reload enabled, then the simulator will reload automatically), and you’ll see something that looks like:

Now that the structure is there, let’s work on the style.

Let’s start with the Create Account button. According a web search, the Twitter Blue color is #1DA1F2, so let’s make the button background this Twitter Blue and the foreground color white. We’ll do this by creating a UIID named TwitterButton in our stylesheet.

When you click on Create account in the Twitter app, it brings you to the Signup Page which looks like:

Create a new file named "SignupPage.xml" in the same directory as the WelcomePage.xml file.

Then add the following contents:

This is just a basic set of components to replicate the contents of the form. It doesn’t include any special styling yet. There are a couple of things worth noting here:

In the WelcomePage we hid the title bar using <title hidden="true"/>. Since this form has a back button, however, I’d like to use the default title bar so that we can get the back functionality for free.

The <title> is a special tag that test the title of the form. If you provide string contents, then those will be used as the title. If you provide a child component, as we’ve done here, it will use that component in the title position. In this case we want our icon to be placed in the title position.

The <right> tag is an alias for a container with FlowLayout and aligned to the right.

The Login page is quite similar to the signup page so I’ll skip details that were covered in the creation of the Signup page.

Create a view in the same folder as the SignupPage named "LoginPage.xml", with the following contents: