# 8. Simple Navigation

### Punch List App: Next Steps

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

{% hint style="info" %}
**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.
{% endhint %}

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:

![](https://2865107717-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F9TCHLR67eLHBOjPvHhud%2Fuploads%2Fgit-blob-8844368b2da3640dcd156bc1239b42191a738808%2Foxide-pl-main-button-ac.png?alt=media)

```xml
<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)

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

![](https://2865107717-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F9TCHLR67eLHBOjPvHhud%2Fuploads%2Fgit-blob-6fd897ee14559aa22f21fb44fc620632e81d3e4e%2Foxide-pl-main-link-add-new.png?alt=media)

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).

![](https://2865107717-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F9TCHLR67eLHBOjPvHhud%2Fuploads%2Fgit-blob-ff2d0852b18248df69a8a02c91620e84b3e0296d%2Foxide-pl-main-new-view.png?alt=media)

![](https://2865107717-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F9TCHLR67eLHBOjPvHhud%2Fuploads%2Fgit-blob-93c64162b3af4aac4ed9ef3f6095c8dbdadc4d6c%2Foxide-pl-main-create-view.png?alt=media)

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

![](https://2865107717-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F9TCHLR67eLHBOjPvHhud%2Fuploads%2Fgit-blob-a6fb9d5b654276a4a453d6525e0517e8243fb08e%2Foxide-pl-add-new.png?alt=media)

### 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.

![](https://2865107717-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F9TCHLR67eLHBOjPvHhud%2Fuploads%2Fgit-blob-de723fa5919a3e508629c468bd4cd75ebe48f72a%2Foxide-pl-add-new-active.png?alt=media)

### 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
<?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: -->`:

```xml
<!-- 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:

```javascript
// 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`.

```javascript
// 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: -->`:

```xml
<!-- 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**

{% code title="add\_new\.xml" %}

```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>
```

{% endcode %}

{% code title="add\_new\.js" %}

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

{% endcode %}

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