8. Simple Navigation

Punch List App: Next Steps

Let's see what we want to add to our punch List app next:

App Design: Construction punch List

Our Punch List app is now capable of displaying a list of "open" punches. The next feature we want to add is the ability to capture a new punch item. Therefore, we want to add a button to our main screen that takes the user to a screen where they can enter the details for the new punch item. When they save those details, the new punch list item needs to appear in the list on the main screen.

To take the user to a new screen in our app, we'll make use of the JourneyApps Navigation, specifically the navigate.link() method as this allows us to link one screen to another, and allows the user to navigate back and forth through our app, as you'll see shortly. The Navigation methods are available from your view JS code.

Add a Button

Below the object-list component in your main.view.xml, type button and select the auto-complete suggestion for a plain <button>. Now fill in a label for your button, something like 'Add New Item', and enter the name of the JS function that you want to call when the button is pressed, e.g.goToNew as seen below:

<button label="Add New Item" on-press="goToNew" validate="false" style="solid" />

Define the JS Function

Now we need to define the JS Function that is called when the user presses the button to navigate the user to a new view. So, in your main.js, underneath the resume() function, add the following code (make sure the name your function exactly as you have referenced it in the on-press attribute of your button)

function goToNew() {
    navigate.link('add_new');
}

The navigate.link() method has one required argument and that is the path of the view you want to link to as a string. The path of the view is used as the unique identifier of each view.

Add a New View

So, we've just added a navigate.link() method to a view called add_new, but that view does not exist yet because we haven't created it yet. So now we need to create this add_new view in our app. To add a new view you can click on the '+' icon in the views panel in the top left corner of the Views Workspace. When prompted to enter a name or path for the view, simply enter add_new. (Note, the argument that you pass into the navigate.link() function needs to match the name/path of the view you want to link to).

As soon as you hit Continue, you'll be taken to your newly created blank View:

Populate the Add New Item View

Now we have a view that we are going to use to create new punch list items, so let's populate it accordingly. Firstly, let's give the view a better title (it would have defaulted to the name/path of the view), then we will add a way for users to capture new punch list item objects.

Make sure you are working on the code of your newly created add_new view, to do this simply click on the name/path of the new view in the Views Panel on the left of the Views Workspace.

Change the Title of the View

To change the title of the view, simply update the text value inside of the <view title=""> attribute to something like: <view title="Add New Punch Item">.

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

    <!-- Variables go here: -->

    <!-- Components go here: -->

</view>

Initialize a New Object

Whenever we have a screen where we're creating a new object, we first need to initialize a blank/empty instance of the object from the init() function. Since we want users to create new punch list items, start by adding a variable to your View XML that will store the new punch list item underneath the <!-- Variables go here: -->:

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

And then initialize a new item object (as defined in our Data Model) on the JavaScript side in the init() function. This is done calling the create() method on the DB Model in question:

// 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
    view.item = DB.item.create();
}

Set a Default Value

We want our new punch list items to have a Status of "Open" by default (as defined in our Data Model), so let's take the opportunity to initialize the punch list item accordingly. Note, the status field in our item model is a single-choice type field, and the options for that field is specified using key|value pairs listed as options within the field. When we want to populate this field programmatically we will always be using keys, not the values.

// 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
    view.item = DB.item.create();
    view.item.status = "Open";
}

Add Input Components for punch List Item

In our Data Model, we specified that punch list items have photo and comments fields, along with the status field. In order to allow end users to capture this data we need to provide them with input components that will capture this data. The input components we're interested in are our capture-photo and text-input components. Let's add those to our view now underneath <!-- Components go here: -->:

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

<!-- Components go here: -->
<capture-photo bind="item.photo" required="false" />
<text-input bind="item.comments" required="false" />

Note that in the bind properties, we refer to the attributes of the item object stored in the variable containing our blank punch list item, therefore using the syntax item.comments and item.photo.

At this point the code of your add_new view should look this like. XML

add_new.xml

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

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

    <!-- Components go here: -->
    <capture-photo bind="item.photo" required="false" />
    <text-input bind="item.comments" required="false" />

</view>

add_new.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
    view.item = DB.item.create();
    view.item.status = "Open";
}

// 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:
}

We're not done yet! Head over to the next section where we'll finish this part of our punch List app.