14. Styling

General

One of the core value propositions of JourneyApps is that it makes developing custom applications for industrial use cases a lot easier, faster and predictable, and this is due to the fact that the platform takes care of a lot of the heavy lifting for us as developers. It allows us as developers to focus on the data structure, workflows and business logic, whilst not having to care about hosting, cross-platform support and inconsistent UI. UX customization is then also one of the few and "most significant" limitations of applications developed on JourneyApps.

That said, there is still plenty that you can customize, and nothing is stopping you from developing beautiful, easy to use and, most importantly, intuitive applications. Next up we will explore some basic styling you can add to your apps to give them a more personal flair.

Further reading: Advanced Styling and Configuration

See the Component Styling and Configuration section for further information about advanced styling capabilities in JourneyApps.

Color Themes and Dark Mode

Every app that you develop has its own default color themes, one for Light Mode and one for Dark Mode. The color theme manages the default appearance of several of the JourneyApps view components, however you can also override these defaults on the component itself in the view.

Let's go ahead and customize the color themes for our Punch List App. To update the color themes we will use a special OXIDE Panel called the Theme panel. So, access your command palette (ctrl+shift+p / cmd+shift+p) and type Theme and look for a Panel called Theme, like so:

Once selected, you should see the Theme panel on the left of your screen, like this.

Now let's take a closer look at the theme panel. Right at the top of the panel is a Theme switcher which allows you to configure the color themes for both the light and dark themes. By default these will be very similar to begin. For each theme there are several standard named colors, e.g. primary, secondary, positive, negative, info, warning and label, and each of these named colors are used by default in several different places in your app. For example, the primary named color is used as the default color for your buttons. Let's go ahead and chance this color now, for both the light and dark theme. (Note, some of the standard named colors have 2 different color values associated with them, as is the case with primary. For those named colors the first color value represents the background-color and the second color value represents the text-color.)

So, let's update the our light theme with the following values:

  • primary: #722f37 (a nice wine red)

  • secondary: #2f5a72 (a complimentary blue)

  • positive: #37722f (a desaturated lime green)

And our dark theme with the following values:

  • primary: #2f5a72 (a complimentary blue)

  • secondary: #72482f (a complimentary brownish orange, which resembles severely burnt and unsalvageable salmon)

  • positive: #2f7269 (a very dark desaturated cyan)

Like this:

Test on Device

To toggle between Light and Dark mode, simply click on the hamburger menu in the top left corner of the Main view, this will open the navigation drawer from where you will be able to toggle between Light and Dark mode.

Now, your app should look like this, with different colored buttons and a selected item indicator in Light and Dark mode.

Assets: Icons, Static Images and HTML

Next up, let's take a look at the assets that your application can include. If you head over to the Assets workspace you will see a folder structure on the left with three subfolders, one for each type of asset that your application can include, namely: icons, images and html.

To add assets to any of these simply locate the relevant file on your desktop and drag it into the correct subfolder on the left of the screen. You will see that I have added several files into my app's Assets folders (links to the example files below - Deep C Corp is our fictitious company whose branding we will be using)

Example App Assets

Add Icons and Images to the App

Now that we have uploaded some icons and images to our Assets folders, let's use them in the app. It is definitely great to be able to use custom icons for various parts of your app (we will use ours in the <sidebar> component we will be adding later), but often times a standard icon library will get you 80-90% of what you need. For that reason JourneyApps has two built-in icon libraries, Font-Awesome and Ionicons (note the specific versions).

So, let's add some of the static images we added to our Main view and also use some Font-Awesome icons on our buttons throughout the application. Let's start with the main.view.xml file and add a <display-image> component as the very first view component, after the variables of course. We wil use one of the welcome images we uploaded for this part. Like so

<!-- Components go here: -->

<display-image src="images/img-welcome-light.png" />
<heading>Welcome to the Punch List App</heading>

<info>A list of all the punches that have not yet been taken care of are shown below</info>

Next up, let's add some icons to the buttons on our main.view.xml. In every <button> component you need to first add an icon="" attribute and then we will specify the icons we want to use. For View, Delete and Add I am going to use the Font Awesome clipboard, trash and plus respectively. Like so.

<button label="View Selected Item" icon="fa-clipboard" on-press="viewItem" validate="true" style="solid" />
<button label="Delete Selected Item" icon="fa-trash" on-press="deleteItem" validate="true" style="solid" />
<button label="Add New Item" icon="fa-plus" on-press="goToNew" validate="false" style="solid" />

Test on Device

Let's see what it looks like and your app should now look like this.

It's already looking better, but we can improve it some more. Let's add the branding/logo for our fictitious company 'Deep C Corp', move some of the components around to better use the available columns with the branding image, and also introduce the <button-group> component. So, still in the main.view.xml, add another <display-image> component, binding this one to the images/deep-c-corp-main-logo.png. Then, above the our three <button> components, add a <button-group> component and move the existing three buttons into the <button-group>. Now, to use the column space nicely, we are going to have the main logo on the left, and everything else on the right of the screen. Like so.

<?xml version="1.0" encoding="UTF-8"?>
<view title="Punch List">
    <!-- Parameters go here: -->

    <!-- Variables go here: -->
    <var name="selected_item" type="item" />
    <var name="open_punches" type="query:item" />

    <!-- Components go here: -->


    <columns>
        <column>
            <display-image src="images/deep-c-corp-main-logo.png" />
        </column>
        <column>
            <display-image src="images/img-welcome-light.png" />
            <heading>Welcome to the Punch List App</heading>

            <info>A list of all the punches that have not yet been taken care of are shown below</info>
            <object-list label="Open Punches" query="open_punches" bind="selected_item" empty-message="There are no open punches at the moment." required="true" />

            <button-group>
                <button label="View Selected Item" icon="fa-clipboard" on-press="viewItem" validate="true" style="solid" />
                <button label="Delete Selected Item" icon="fa-trash" on-press="deleteItem" validate="true" style="solid" />
                <button label="Add New Item" icon="fa-plus" on-press="goToNew" validate="false" style="solid" />
            </button-group>
        </column>
    </columns>

</view>

Test again and your app should now look like this.

It's looking a lot better now, so let's keep going.

Button Styling

Buttons in JourneyApps can be styled in a variety of different ways, see the Syntax Reference for more details. You have already seen that you can change the color and specify an icon, but you can also do things like choose the position of the icon and choose whether the background color should be a solid color or an outline. Next we will incorporate some of this in our app, so let's head to our View Item view and update the buttons with some more styling.

So, on your view_item.view.xml, move the two buttons into a <button-group> and give each an icon attribute and an icon-position attribute, then update those attributes to the following (notice the order of my buttons inside the button-group):

<button-group>
    <button label="Go back" icon="fa-arrow-left" icon-position="left" on-press="dismiss" validate="false" style="solid" />
    <button label="Mark as Closed" icon="fa-check" icon-position="right" on-press="markClosed" validate="false" style="solid" />
</button-group>

Now let's change the style and color of these two buttons. I want the Go back button to be less prominent, so I will use an outline instead of a solid color, and I want to use a different color for my Mark as Closed button, the secondary color (to do this I need to specify a color attribute on the button). So update the buttons to the following:

<button-group>
    <button label="Go back" icon="fa-arrow-left" icon-position="left" on-press="dismiss" validate="false" style="outline" />
    <button label="Mark as Closed" color="secondary" icon="fa-check" icon-position="right" on-press="markClosed" validate="false" style="solid" />
</button-group>

Test on Device

The View Item view should now look like this.

Add a Sidebar with Icons

Now that we know how icons work, let's also add a sidebar to some of the views in our app. Our app doesn't have long linear processes like the field ticket screenshot that you saw in the Responsive Apps section of the tutorial, so adding a sidebar to the punch List app won't be a very good example, but it will give you an idea of how sidebars work. The closest we have to a linear process in our app is the two-step process of viewing a punch and then marking it as "Complete". We'll be using the below three icons for this purpose. You can save & upload them to your Assets Workpsace, should you wish:

In the XML for your view_item view, above the <heading> tag, type sidebar and insert the auto-complete suggestion for . This will give you:

<?xml version="1.0" encoding="UTF-8"?>
<view title="View Punch Item">
    <!-- Parameters go here: -->
    <param name="item" type="item" />

    <!-- Variables go here: -->

    <!-- Components go here: -->
    <sidebar>
        <item state="active" icon=""></item>
        <item state="disabled" icon=""></item>
    </sidebar>
    <heading>{item.comments}</heading>
    <columns>
        <column>
            <info-table>
                <row label="Item Comments" bind="item.comments" />
                <row label="Item Status" bind="item.status" />
                <row label="Current Time" value="{$:showTime()}" />
            </info-table>
        </column>
        <column>
            <display-photo bind="item.photo" />
        </column>
    </columns>

    <button-group>
        <button label="Go back" icon="fa-arrow-left" icon-position="left" on-press="dismiss" validate="false" style="outline" />
        <button label="Mark as Closed" color="secondary" icon="fa-check" icon-position="right" on-press="markClosed" validate="false" style="solid" />
    </button-group>

</view>

You'll notice that sidebar <item> components have a state="" where the first item defaults to active and the second to disabled. Sidebar items can have one of three possible states:

  • active: The sidebar item is highlighted

  • normal: The sidebar item is shown normally

  • disabled: The sidebar item is greyed out

Let's go ahead and populate our <sidebar> with some data. We want a sidebar with three items. The first will represent our Main view or starting point, the second will represent the View Item step and the third our Item Completed step. So, in your view_item.view.xml update the <sidebar> as follows:

<sidebar>
    <item state="normal" icon="icons/home.png">Home</item>
    <item state="active" icon="icons/clipboard-list.png">View Item</item>
    <item state="disabled" icon="icons/clipboard-list-complete.png">Item Closed</item>
</sidebar>

Next up, let's add some more styling by using our color themes to color the icons with the primary named colo. Like so:

<sidebar>
    <item state="normal" icon-color="primary" icon="icons/home.png">Home</item>
    <item state="active" icon-color="primary" icon="icons/clipboard-list.png">View Item</item>
    <item state="disabled" icon-color="primary" icon="icons/clipboard-list-complete.png">Item Closed</item>
</sidebar>

Next, let's allow the user to navigate all the way home by clicking on Home in the sidebar. To do this we need to specify an on-press action for the sidebar item in question. Like this.

<sidebar>
    <item state="normal" icon-color="primary" icon="icons/home.png" on-press="$:navigate.dismiss('main')">Home</item>
    <item state="active" icon-color="primary" icon="icons/clipboard-list.png">View Item</item>
    <item state="disabled" icon-color="primary" icon="icons/clipboard-list-complete.png">Item Closed</item>
</sidebar>

Finally, let's make the sidebar available on mobile phones by adding a visible-on-mobile="true" to the sidebar component. Like this.

<sidebar visible-on-mobile="true">
    <item state="normal" icon-color="primary" icon="icons/home.png" on-press="$:navigate.dismiss('main')">Home</item>
    <item state="active" icon-color="primary" icon="icons/clipboard-list.png">View Item</item>
    <item state="disabled" icon-color="primary" icon="icons/clipboard-list-complete.png">Item Closed</item>
</sidebar>

Now we can copy the code for the sidebar to the Completed Item and update the state values for the various sidebar items view to finish this part of the tutorial. So head over to the Completed Item view and update the completed_item.view.xml to the following:

<?xml version="1.0" encoding="UTF-8"?>
<view title="Completed Punch Item">
    <!-- Parameters go here: -->
    <param name="item" type="item" />
    <!-- Variables go here: -->

    <!-- Components go here: -->
    <sidebar visible-on-mobile="true">
        <item state="normal" icon-color="primary" icon="icons/home.png" on-press="$:navigate.dismiss('main')">Home</item>
        <item state="normal" icon-color="primary" icon="icons/clipboard-list.png">View Item</item>
        <item state="active" icon-color="primary" icon="icons/clipboard-list-complete.png">Item Closed</item>
    </sidebar>
    <heading>Item Completed!</heading>
    <info>This item is now completed and will no longer show up in the list of Open Snags</info>

    <button label="Go Home" on-press="goHome" validate="false" style="solid" />
</view>

Test on Device

Let's see the sidebar in action. Your app should now look like this.

HTML

JourneyApps offers an html UI Component that allows you to embed HTML snippets or pages into your apps. This is mostly useful for two purposes:

  • Embedding HTML content, like terms and conditions etc. into an app

  • Extending the functionality offered "natively" by JourneyApps. For example, you could embed an HTML page that offers some level of interactiveness to create user interface elements or experiences that are not possible to implement natively in JourneyApps. (see the reference documentation for more details)

The <html/> component can display HTML content from two types of sources:

  • A local HTML file that is embedded inside your app (HTML files can be uploaded to your app using the Assets Workspace in OXIDE) — specify a local path to the HTML file in the src="" attribute

  • A remote HTML page — specify an https:// URL in the src="" attribute

Let's add some HTML to our app [OPTIONAL]

The following section walks you through the process of creating some basic static HTML and adding that to your app. It can be useful for some very specific styling requirements, but it's generally easier to style your app using the before mentioned methods.

First, you need to create a new .html file on your computer. The easiest will be to use a text editor and save the file with the following filename blue-line.html (note the file extension). Use the below code for the contents and once saved, upload the blue-line.html file to your Assets workspace.

<!DOCTYPE html>
<html>
<head>
	<title></title>
</head>
<body style="margin: 0px">
		<table style="width: 100%">
	        <tbody>
	          <tr style="height: 8px">
	            <td style="background-color:#1870ca; width: 7%"></td>
	            <td></td>
	          </tr>
	          <tr style="height: 8px"></tr>
	          <tr style="height: 8px"></tr>
	        </tbody>
      </table>
	</body>
</html>

Now let's add it to the Main view. So, in main.view.xml add a <html> component (add it as the very first view component outside of the columns but after the variables) and specify the src="html/blue-line.html". You will also need to specify the height manually in this example as the default minimum height would be too much for our example HTML. (Note the show-fullscreen-button="false")

<!-- Components go here: -->
<html src="html/blue-line.html" show-fullscreen-button="false" height="15px"/>

Your app should now look like this.

As you can see, the length of the blue line is different on the phone vs the desktop. That is being specified in the HTML itself. Let's go and update it now. It's currently using a 7% width, but let's change it to 25% for good measure. So, head over to the Assets Workspace and select the blue-line.html file. Like this.

Now, let's change the width % to 25%. Like this.

Now your app will look like this.

We have now touched on all the basic styling elements of JourneyApps applications. Next up we are going to revamp our main view with a more powerful <list/> component.

Further reading: Advanced Styling and Configuration

See the Component Styling and Configuration section for further information about advanced styling capabilities in JourneyApps.

Last updated