LogoLogo
What's NewDeveloper CommunitySupportStatus
  • 🚀Get Started
    • What is JourneyApps Platform?
    • Tutorial: Build your First App
      • 1. Introduction
      • 2. Create a new App
      • 3. OXIDE IDE Overview
      • 4. Hello World app
      • 5. The Data Model
      • 6. View Components
      • 7. Queries and Data Sync
      • 8. Simple Navigation
      • 9. View Stack
      • 10. Input Validation
      • 11. View Parameters
      • 12. Data Manipulation
      • 13. Responsive Apps
      • 14. Styling
      • 15. Lists
      • 16. GPS Capturing
      • 17. Relationships
      • 18. Multiple User Roles
      • 19. Deployment and Users
      • 20. Version Control
      • 21. CSV and APIs
      • 22. Conclusion
    • JourneyApps Platform Fundamentals
      • Creating a New App
        • Git-enabled Apps
      • What are Views?
      • What is the Data Model?
      • JourneyApps Syntax Basics
      • Access the Database (DB)
        • Manipulate DB Objects
        • Query DB Objects
      • View Navigation
        • Deep Linking
      • CloudCode Overview
      • OXIDE (Online IDE)
  • 💻Build your App
    • JourneyApps Syntax
      • Syntax Basics
      • Access the DB
      • View Navigation
      • Async & Await
      • TypeScript Apps (Beta)
        • runtime-build package
        • TypeScript App Troubleshooting
      • What's New in V4
        • Updating to the V4 API
    • Configure your Data Model
      • What is the data model?
      • Reference: model
        • field
        • belongs-to
        • has-many
        • index
      • Data Rules
        • Data Buckets
        • Sync Rules - Limit data synced to devices
        • Data ACLs - Limit access to data
        • Real-world example for Data Rules
        • ❔FAQs
        • Migrate to Data Rules
      • App Indexes
      • Webhooks
    • UI Components
      • All UI Components
        • actionSheet
        • Attachments
        • button
        • button-group
        • capture-coordinates
          • marker
          • marker-query
        • capture-file
        • capture-photo
        • capture-signature
        • card
          • accent
          • action
        • columns
          • column
        • component
        • context-menu
          • divider
          • item
        • CSV
        • date-input
        • datetime-input
        • dialog
          • body
        • display-3d-model
          • 📖display-3d-model Guides
            • Guide 1: Initialize and layout a 3D model in a view
            • Guide 2: Control playback position
            • Guide 3: Troubleshooting controls
        • display-coordinates
        • display-file
        • display-image
        • display-photo
        • display-signature
        • heading
        • html
          • HTML Advanced Topics
          • ❔HTML FAQs
          • 📖Guide: HTML & JourneyApps iFrame Client
        • icons
        • info
        • info-table
          • row
        • journey.photos (capture multiple photos)
        • JourneyPrinter (print PDFs)
        • grid
          • cell
          • 📖grid Examples
        • list
          • list-item
            • accent
            • asset
            • pills
              • pill
            • action
        • multiple-choice-checklist
        • navigation (Navigation drawer)
          • general-section
            • item
          • section
            • item
              • item
          • ❔navigation FAQs
        • notification
        • object-dropdown
        • object-list
          • action
        • object-repeat
        • object-table
          • action
          • column
            • action
            • edit-boolean
            • edit-date
            • edit-datetime
            • edit-integer
            • edit-number
            • edit-select
            • edit-text
            • edit-time
            • edit-typeahead
              • action
            • header-action
          • column-group
          • empty-action
          • 📖object-table Guides
            • Actions
            • Cell callouts
            • Column groups
            • Columns
            • Controlled object-table
            • Controls
            • Copy & paste data
            • Edit cells
            • Filters
            • Frozen columns
            • Fullscreen object-table
            • Mode
            • State
            • Styles
        • optionList
        • PhotonSync (transfer data offline)
        • power-bi
          • 📖Guide: PowerBI Embedding
        • scan-barcode
        • shortcut
        • sidebar
        • single-choice-dropdown
        • single-choice-radio
        • template
        • text-input
        • time-input
        • toggle
        • view
      • JS/TS Events
      • Show / Hide UI Components
      • View Templates
      • XML Fields (Attributes)
        • align-content
        • align-controls
        • align-label
        • bind
        • clear-button-visibility
        • control-order
        • disabled
        • error-message
        • icon-position
        • id
        • hide-if
        • modifier-text
        • label
        • label-case
        • label-color
        • on-change
        • on-press
        • placeholder
        • required
        • show-if
    • JS / TS APIs
      • Attachment
      • Bluetooth (Beta)
      • Broadcast
      • component
      • CSV
      • DB
      • HardwareBarcode
      • journey
        • journey.config
        • journey.container
        • journey.device
        • journey.diagnostics
        • journey.dialog
        • journey.files
        • journey.hardware
        • journey.photos
        • journey.runtime
        • journey.sensors
        • journey.viewStack
      • JourneyPrinter
      • KeyboardBarcode
      • LocalDB
      • NFC
      • OnlineDB
      • PhotonSync
      • SerialPort
      • ShortcutManager
      • TCPSocket
      • user
    • Extend your App with Custom Code
      • App packages
        • App packages overview
        • PDF report package
        • TypeScript library & unit tests
        • Manage External Dependencies
      • Custom HTML
    • Style & Customize your App
      • Style & configure UI components
        • Overview
        • Understand extendable themes
        • Use themes on a view
        • Theme specific components on a view
        • Examples
        • Debugging
        • ❔FAQs
      • Change your App Font
      • Custom Branding
        • Custom Container Features
        • Special Requirements for iOS Containers
    • Integrate your App
      • Backend integrations with CloudCode
      • Barcode Scanning
        • Barcode Scanning using Keyboard Emulation
        • Hardware Barcode Scanning
        • scan-barcode
      • Bluetooth Low Energy (BLE)
      • Broadcast API
      • HTTP requests (Fetch API)
      • JourneyApps Print (Android)
      • Maps and navigation
      • NFC
      • Opening external links/apps
      • Serial Port
      • TCP Sockets
    • Design Intuitive Apps
      • UX Guidelines
      • Write Effective Copy
  • 📱App Features
    • RealWear® Voice Control
      • Automatic Voice Commands
        • Automatic Voice Commands - Advanced
      • Manual Voice Commands
    • App, Runtime and Container Updates
    • Batch Operations (App)
    • Call JS/TS Functions from XML
    • Capture GPS Locations
    • Push Notifications
    • Translations
    • XML Format Strings
    • Webhooks (External)
  • 🌐CloudCode
    • CloudCode Overview
    • Trigger a CloudCode Task
      • Trigger CC with a Schedule
      • Trigger CC via a Webhook
      • Trigger CC from an App
      • Trigger CC from Another Task
      • Trigger CC via HTTP
    • Attachments in CloudCode
    • Timezones
    • Advanced CloudCode Topics
      • Access Multiple DBs in CloudCode Tasks
      • Batch API (CloudCode)
      • CloudCode Dependencies
      • Configure HTTPS in CloudCode
      • Deployment environment variables
      • Local CloudCode Development
      • PDF Reports using CloudCode
      • Shared CloudCode Tasks
      • Translations in CloudCode
  • 📥Backend API
    • Introduction
    • API Reference
      • Retrieve All Objects
      • Query Objects
      • Sort Results
      • Limit and Skip
      • Count Objects
      • Create a New Object
      • Retrieve a Single Object
      • Update a Single Object
      • Delete a Single Object
      • Batch Operations (v4 API)
      • Oplog API
      • Retrieve the App Data Model
      • Manage App Users and Sessions
      • Field Representation
      • Error Responses
    • API Limits
    • Update to the V4 API
  • ⚙️Technical
    • Data Synchronization Priority
    • Device Diagnostics
    • JSON1 Query Engine
    • Improve App Performance
    • Security Measures
    • Supported Platforms
      • Web Container
      • Windows Installer
    • Domain Whitelist
  • 🖥️OXIDE
    • Get started with OXIDE
      • OXIDE Overview
      • Components of OXIDE
    • Configure Testing Deployments
    • Edit and Manage Files
      • How to Navigate to a Function
      • Manage External Dependencies
    • Create and Manage App Containers
    • Debugging & Troubleshooting
      • Common Troubleshooting Pointers
      • App Diagnostics Reports
      • Build Logs
    • OXIDE Workspaces
      • OXIDE Trees
  • ❕Deprecated Features
    • Deprecated Features and Components
Powered by GitBook
On this page
  • Parameters & Arguments
  • Accessing Parameters from the View
  • Linking to a View with an Argument
  • Create the New View and Specify a Parameter
  • Add Some Components
  • Executing JS in the View
  • Test on Mobile Device
  1. Get Started
  2. Tutorial: Build your First App

11. View Parameters

Previous10. Input ValidationNext12. Data Manipulation

Last updated 2 years ago

Parameters & Arguments

When it comes to the new view we want to create to allow users to view the details of an existing punch list item, we clearly have to pass some data to the view when we link to it — namely, the specific punch list item that the user wants to view. In contrast, we didn't have to pass any data to our "Add New Item" view when we linked to it, because it simply creates a new punch list item whenever the user opens it. For the purpose of passing data to a view, JourneyApps uses standard concepts similar to other programming environments:

  • A view specifies its Parameters — the data that it requires you to pass to it. A view can have multiple parameters.

  • When you link to a view that expects a parameter, and then pass it a specific object (e.g. a punch list item), that specific object is known as an Argument.

A hypothetical example of this is shown in the diagram below, in the context of some concepts that you are already familiar with, such as Links and Variables:

Looking at the diagram:

  • View B expects two parameters — both of type person.

  • When we link to View B from View A, we pass in two arguments — objects of type person

  • There are two outgoing links from View B — to View C and View D respectively.

  • View C and View D each expect one parameter.

Accessing Parameters from the View

Inside your View XML and JavaScript, parameters are accessed in exactly the same way as variables. In other words, you can bind input components to them and access them from the JavaScript using the view. notation. Once on the specific view they act exactly the same way as view variables.

Linking to a View with an Argument

In OXIDE, open up the Main View of the punch List app again (to do this, make sure you are on the Views Workspace, and then select the main view from the Views Panel on the left). Let's add a "View Selected Item" button before our existing "Add New Item" button, and specify that it will call a JS function named viewItem.

<!-- Components go here: -->
<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="false" />

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

Now let's define our viewItem() function. We want this function to take the item the user has selected and pass it to the view_item view, which we will create after this step. You may remember we originally defined our <object-list> with a bind attribute and we set that to selected_item to store the object that the user clicks on in the list in the view variable called selected_item. We can now use that variable in our new function.

So, in your main.js, add the viewItem() function as follows (Note: Unlike in the XML, the order in which you specify functions in JS does not matter).

function viewItem() {
    navigate.link('view_item', view.selected_item);
}

To do this, we will force the user to select an item before they press the button to view the selected item. So, we update the required attribute of our <object-list> to "true" and we also update the validate attribute of our View Selected Item <button> to "true". Like this.

<?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: -->
    <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 label="View Selected Item" on-press="viewItem" validate="true" style="solid" />
    <button label="Add New Item" on-press="goToNew" validate="false" style="solid" />
</view>

By only updating the validate attribute of the View Selected Item button, it means that when the users presses the Add New Item button the input validation will not run, and this is correct. We do not need the user to first select an existing item before we allow them to add a new one.

Create the New View and Specify a Parameter

Now create a new view and specify the name/path to be view_item.

Once you hit Continue you will be taken to your new view. Again, let's start by updating the title of the view to something more appropriate, in this case "View Punch Item".

<view title="View Punch Item">

This view needs to accept an item parameter. Under the <!-- Parameters go here: --> section of the View XML, type param and insert the auto-complete suggestion for <param>. Then fill in a name for the parameter and specify the type as item as seen below:

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

</view>

Add Some Components

<?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: -->
    <info-table>
        <row label="Item Comments" bind="item.comments" />
        <row label="Item Status" bind="item.status" />
    </info-table>

    <display-photo bind="item.photo" />
    
    <button label="Go back" on-press="dismiss" validate="false" style="solid" />
</view>

A couple of things to note.

  • Firstly, our button is hooked up to a JS function called dismiss. This function is a built-in function and does not have to be redefined. This means you can use it, like this, directly in your XML and it will execute the dismiss navigation action - saving all unsaved changes to view variables and then removing the current view from the stack

  • Secondly, inside the <info-table> component we have nested <row> sub-components. You may have noticed that similarly to when we had input components, the row display sub-component has a bind attribute which we used to bind directly to view variable's fields. This is very useful for quickly and easily displaying data that is stored in any view variable. However, you can also display information dynamically using XML string interpolation inside any XML component that knows how to display text values, for example a <heading> component.

So let's do that now. Let's add a <heading> component and make it display the contents of the comments field of our item variable. Still in the View XML in the view_item.view.xml file, add the following above the <info-table>.

<heading>{item.comments}</heading>

Executing JS in the View

So, still in the View XML in the view_item.view.xml file, update your <info-table> to include the following new row.

<row label="Current Time" value="{$:showTime()}" />

Note that this time we replaced the bind attribute with a value attribute. bind is used to display the contents of variables directly, value is used to display text, both static and dynamic. We also used a new syntax notation inside the curly braces, and that is the $: notation. The $: notation inside a pair of curly braces {} tells the XML that you will be executing JS code inside those {}'s. You can execute raw JS code or call a function that you have defined elsewhere. In our case we are calling a function called showTime - which we still need to define. (Note: If you execute raw JS code you need to remember to escape any XML characters, for example > --> &gt;, <= --> &lte;, && --> &amp;&amp;, etc.)

Your View XML should now look like this.

<?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: -->
    <heading>{item.comments}</heading>
    <info-table>
        <row label="Item Comments" bind="item.comments" />
        <row label="Item Status" bind="item.status" />
        <row label="Current Time" value="{$:showTime()}" />
    </info-table>

    <display-photo bind="item.photo" />
    
    <button label="Go back" on-press="dismiss" validate="false" style="solid" />
</view>

Next, let's create the corresponding JS function and then we will review what we have just done. So, in your View JS in the view_item.js file, add the following new showTime() function.

function showTime() {
    var now = new Date(); // standard JS function to get the current date and time
    return now.toLocaleString(); // changes the DateTime object into a string according to local conventions
}

Note, the reason we used the toLocaleString() method before returning the value is because our XML is expecting text and so we need to convert the result we want to return into a string first before we return it.

At this point, the code in your view_item view should look like this:

Test on Mobile Device

Let's test it out! Your app should now look like this:

This function will take the object that is stored in view.selected_item and pass it to the view_item view. But what if the user hasn't selected an item yet? In that case view.selected_item would be null and we would be passing nothing to our view_item view. We can't have that, so let's add some validations to stop that from happening. We can do this with JS validations, or with simple XML input validations, as we learned in . Let's just use simple input validations.

Now let's add some view components to display the details of our punch item. A new component that we will be using here is the (which allows displaying a 2-column table and is perfect for displaying data from the database). We will also be using the component to display the photo that we captured. Finally, we need a button that will take us back to the main view.

Note that item.comments is wrapped in curly braces. Remember for default display values from the "The Data Model" section of the tutorial? Displaying the value of a variable or parameter within the View XML uses in JourneyApps. In fact, almost anywhere where you are using text in your View XML you can render the text dynamically using XML string interpolation, using values stored in variables or even the returned results of JS functions. So let's try that now. Let's add another row to our <info-table>, and in this one we are going to display the returned results of a new JS function called showTime().

🚀
Section 10 - Input Validations
info-table
display-photo
the same syntax
Display Format