4. Hello World app

In this section we will complete our "Hello World" app and test it on a device.

An App Consists of a Data Model and Views

As you've seen in the What is JourneyApps? page, building an app on JourneyApps involves the customization of two kinds of things:

• Data Model: This describes the data that your app makes use of (in more technical terms: object models with their fields and relationships)

• Views: This defines the layout and logic for the actual screens in your mobile app.

You will also have learned that customizing these two things are done using straightforward XML and JS.

In your Hello World app that you just created, you can access the Data Model and Views from the corresponding workspace in the Workspace Tabs.

Click on the Views workspace in the Workspace Tabs to access the views for your Hello World app. You should see something like this.

On the left of your screen you can see a Views panel listing all the views for your app. By default each app will have two views to begin with, one called "main" and one called "nav". The "main" view is the very first view that is rendered when the app is loaded, and the "nav" view is used to manage more advanced navigation (something for a later topic).

Each view is divided into two separate files, a .xml file, which is used to describe the layout of the view, and a .js file, which is used to describe the business logic for the view. By default, when you open a view to edit it both of these files will be opened for you, the xml in the left editor pane and the js in the right editor pane. This can be seen in the image above for the "main" view. OXIDE has opened the xml in the left editor pane and the js in the right editor pane.

Adding Components to Views

Let's go ahead and add some basic details to our Hello World app. For now we are just going to add some basic components, and we will add them to our "main" view. So, make sure you are on the "Views" workspace (to get here simply click on Views in the Workspace Tabs), then make sure you are on the "main" view (to do this select the "main" view from the Views panel on the left of the workspace).

We are going to add a heading and an info component to our "main" view xml to get us started.

In the "main" view xml, add a new line after <!-- Components go here: --> section, then type head and you should see something like this ...

What you see beneath your cursor is OXIDE's Auto-Complete functionality trying to help you. Hit return/enter to insert the highlighted auto-complete suggestion (in this case there was just one option). Now your code should look something like this ...

You will see that OXIDE has inserted the opening and closing tags for your heading component for you. All that is left to do is populate it with some text. Let's add the text 'Hello World' to the inside of the heading component. Now your code should look like this ...

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

    <!-- Variables go here: -->

    <!-- Component go here: -->
    <heading>Hello World</heading>
</view>

Excellent, now let's do the same for an info component. We are going to add the component underneath the heading component, we are going to use auto-complete to let OXIDE insert the xml tags for us, and once it is there we are going to populate it with some text, in this case the text 'This is my first app'.

So, start by typing inf, then use your arrow keys to highlight the info component in the auto-complete suggestions, not the info-table component. Once the suggestion is highlighted hit return/enter, and finally add the text 'This is my first app' inside of the info component. Now your code should look like this ...

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

    <!-- Variables go here: -->

    <!-- Component go here: -->
    <heading>Hello World</heading>
    <info>This is my first app</info>
</view>

Great, now let's test your app to see what it looks like.

Testing Your App: Link a Mobile Device or Test on Desktop

An important concept in JourneyApps is that you should test your app continuously while you are building it. Therefore, immediately go to the Test app action (bottom right corner of OXIDE) of your Hello World app and follow the instructions to either:

• Install the JourneyApps Container from the Play Store (Android) or App Store (iOS) and link your Hello World app to a mobile device.

• Download and install the JourneyApps Container for Windows or MacOS and test the app on Desktop.

The very first time you run 'Test app' you will be prompted to create a new app user, this is normal as no app user would exist for you yet. Simply hit continue and then you will be presented with instructions on how to test your app.

Ensure that you have downloaded and installed the JourneyApps Container for Desktop before proceeding. Once installed, click on the 'Or test on desktop' button in the Test app action (bottom right corner of OXIDE). If all went well the JourneyApps Container for desktop should launch and look something like this ...

And if you are also following along on your mobile device, it should look something like this ...

Add an Input Component

Now let's make the app a bit more interactive by adding an input component. We want to complete our Hello World app by making it ask the user to enter their name, and then have a button that will make the app display a greeting when it is pressed.

In a full-blown JourneyApps application, we would use the Data Model as we'll show you later, but for now, to keep things really simple, we'll simply use a local variable to store user input. To add a local variable, type var on a new line under the <!-- Variables go here: --> section in your View XML and hit return/enter to auto-complete as usual.

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

    <!-- Variables go here: -->
    <var name="" type="" />

    <!-- Component go here: -->
    <heading>Hello World</heading>
    <info>This is my first app</info>
</view>

We want to ask the user to enter their name, so type something like your_name for the name property, and then text for the type property. text indicates that we'll be storing text in this variable (we'll show you all the different data types later.)

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

    <!-- Variables go here: -->
    <var name="your_name" type="text" />

    <!-- Component go here: -->
    <heading>Hello World</heading>
    <info>This is my first app</info>
</view>

Important: Note that the order in which you insert XML is important — we will cover each of these in more details later, but your XML needs to be specified in the following order: parameters, variables, components. If you see an error message such as "Elements must be in this order: parameters, variables, components" or "This element is not expected" , it means that something has been inserted in the incorrect order in the XML.

Next, we need to provide a way for the user to give us their input. In this case we just want to capture some text and so a text-input component will work well. We want to add a text-input component underneath the existing info component in the xml. So, add a new line after the info component and type text, highlight the text-input auto-complete suggestion and hit return/enter to insert the component.

By default the text-input component has a bind attribute and a required attribute, but we can specify some additional attributes as well. For now, just add a label attribute to the text-input component. The bind attribute tells the view where to store the input that the end users will enter into the component. bind needs to be set to a variable that is declared in the view. The label attribute is used to display a text label above the text-input component. Let's set the bind attribute to the name of the variable we declared, your_name, and the label attribute to 'Please enter your name'. Now your code should look like this ...

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

    <!-- Variables go here: -->
    <var name="your_name" type="text" />
    
    <!-- Component go here: -->
    <heading>Hello World</heading>
    <info>This is my first app</info>
    <text-input label="Please enter your name" bind="your_name" required="false" />

</view>

And your app should look like the this ...

Desktop

Mobile

Add a Button and Hook It Up With JavaScript

Finally, we are going to add a button, but this time we are going to use the visual editor. Open the command palette (ctrl+shift+p / cmd+shift+p), then type design and select the Open view in designer action. When prompted to select a View Model, choose the 'main' view. The visual editor should now be open.

Now, to add a new component using the visual editor, simply click on the + underneath the visualization of the text-input component, select the button component from the list, enter 'Press Me' as the Button Label when prompted and then hit 'Continue'.

Once added, go back to your main view xml by clicking on 'main' view in the View Panel on the left, this will open the main view xml in the left editor pane and the main view js in the right editor pane. Once there, you should see this, the visual editor has added a button component for you in the xml and also populated some of the xml attributes of the button component. You may have also noticed that the visual editor has created a new js function for you ...

Next up, let's add the necessary js code to return a dialog once the user presses our button. We are going to use a simple dialog JS component, and this component takes a string as an argument. Update your JS function to the following ...

function buttonPress() {
    // TODO implement
    dialog("Hello there, " + view.your_name);
}

All right, let's test it out! Open your app (either desktop or mobile), and see that it now looks and works like this ...

Desktop

Mobile

Hello World DONE!

Excellent, you have successfully completed your first JourneyApps 'Hello World' app. Below you will find the reference code for the 'main' view xml and js of this 'Hello World' app. If your app is not working like ours, or you broke it and cannot seem to fix it, simply copy and paste both the xml and the js over to your app and then try again.

main.xml

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

    <!-- Variables go here: -->
    <var name="your_name" type="text" />

    <!-- Component go here: -->
    <heading show-if="true" hide-if="false">Hello World</heading>
    <info>This is my first app</info>
    <text-input label="Please enter your name" bind="your_name" required="false" show-if="true" hide-if="false" />
    <button on-press="$:buttonPress()" label="Press Me" />

</view>

main.js

// This function is called when the app navigates to this view (using a link)
function init() {
    // initialize any data here that should be available when the view is shown
}

// This function is called when the user returns to this view from another view
function resume(from) {
    // from.back       (true/false) if true, the user pressed the "Back" button to return to this view
    // from.dismissed  (true/false) if true, the app dismissed to return to this view
    // from.path       contains the path of the view that the user returned from
    // if any data needs to be refreshed when the user returns to this view, you can do that here:
}


function buttonPress() {
    // TODO implement
    dialog("Hello there, " + view.your_name);
}

Automatic Saving, Deployment & Testing on Mobile Device

Note that whenever you type something into OXIDE, it will automatically be saved. There is no need to save anything explicitly. Furthermore, you may have noticed that every time you make a change, there is a Deployment process that gets kicked off, indicated by the progress bar that appears over the Footer. This is the OXIDE auto-deploy feature and is enabled by default. You can also trigger a deployment manually by hitting ctrl+s / cmd+s (Note you can turn off the auto-deploy feature from the command palette, ctr+shift+p / cmd+shift+p. This is often useful if you have a poor internet connection or when you are working on large blocks of code at a time. If you do turn it off, just remember to hit ctrl+s / cmd+s to manually deploy your code before trying to test it).

This means that your app is automatically being deployed to the Testing Environment (recall the Environments and Staged Deployment section on the What is JourneyApps? page) Your app will try to refresh itself automatically on the mobile or desktop device so that you can see the changes you're making (if it doesn't, press the "sync" button at the top right corner of the app).

What Kind of Device? All the applications that you develop on JourneyApps will work on iOS, Android, Windows, MacOS and Web right out of the box, without any additional development required. The applications are also responsive right out of the box, which means you can use the application on any form factor, phone, tablet, laptop and desktop. Write once, run everywhere. A list of supported platforms and minimum operating system version can be found here.

Container App + Over-the-Air Customizations: As you've seen in the What is JourneyApps? page, the JourneyApps Container that you install on your mobile or desktop device is simply an empty generic container. Once you link your device to an app, your app customizations are deployed to it over-the-air, and your app is dynamically rendered. This means that deploying new versions of your app to users is extremely easy and happens in an automated way.