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
  • Overview
  • Purpose of a Navigation System
  • navigation anatomy
  • Navigation drawer branding
  • Standard Attributes
  • logo
  • Advanced Attributes
  • from-js
  • id
  • indicator
  • sections
  • show-if and hide-if
  • style-header-background
  • style-section-case
  • style-section-color
  • Component Methods
  • show
  • hide
  • setActive
  • setOpen
  • setCollapsed
  1. Build your App
  2. UI Components
  3. All UI Components

navigation (Navigation drawer)

Previousmultiple-choice-checklistNextgeneral-section

Last updated 6 months ago

Overview

The navigation drawer is a somewhat omnipresent element that slides in from the left, by means of toggling the hamburger icon located at the top left of the title bar. The hamburger icon is present on any view that is listed in the drawer. These items should reflect the high level views in your app. The hamburger icon will be replaced by either a back or close icon on views that aren’t listed in the drawer - these views are seen as deeper levels within the app’s hierarchy.

The navigation drawer should be reserved for global items. Even though items can be built and displayed dynamically, they should be kept as static as possible per user role. This is analogous to a map not changing while it's in use.

See the for the context-menu component for listing items that are specific to a view.

Purpose of a Navigation System

A successful navigation system serves as a map, in that it:

  • provides an overview of the content included in an app

  • reinforces the relationship between different sections of content, and

  • acts as a “You are here” sign, indicating how the user’s current screen fits into the bigger picture

First time users might feel lost without it, as they won’t know what to expect of an app. It can also save returning users a lot of time by optimizing frequently used flows.

navigation anatomy

Navigation drawer branding

The header will become collapsable and the logo replaced by the name of the app when either

  • the content in the drawer is longer than the height of the drawer,

  • the screen height is less than the drawer’s height

Standard Attributes

logo

Optional

Type: string

Default: unset

Specify the brand logo to be displayed in the navigation drawer. String or $:function() that returns a string.

<navigation logo="images/deep_c_corp.png">
    <!-- Navigation sections -->
</navigation>

logo best practices

It's recommended to use a crisp PNG or an SVG for the logo. When using a PNG, the image should:

  • be at least 224px in width or 136px in height

  • not contain any padding

  • have a transparent background

Advanced Attributes

from-js

Optional

<!-- XML -->
<navigation from-js="$:buildNavFromJS()"/>
// JS
function buildNavFromJS() {
    return component.navigation({
        sections: buildSectionsFromJS()
    });
}

function buildSectionsFromJS() {
    // Logic to build an array of component.navigationSection objects
}

id

indicator

Optional

Default: The global indicator will by default only show if there are other indicators in the drawer. The style of the global indicator is derived using the following, for instance if all indicators are of type number the global indicator will be the sum of these.

Indicators can be used to draw the user’s attention to the status of an item or the navigation drawer globally. An example is showing a certain amount of unread messages. Indicators can contain either numbers, text or be empty. The color can also be customized.

An indicator can be placed either of the following elements of the navigation component:

  1. Globally. The indicator will appear with the hamburger menu, overriding an item indicator that by default shows here (see next bullet).

  2. On an item. When an item indicator is present, in addition to displaying with the corresponding item, an additional indicator will also display with the hamburger icon (unless a global indicator is defined).

<navigation indicator="$:buildIndicator()" >
    <!-- Navigation sections -->
</navigation>
function buildIndicator() {
    // You logic here
    return {value: 1, color:"positive"};
}
<navigation >
    <section >
        <item label="Reports" view="reports" indicator="true">
            <item label="Actions" view="action"  indicator="$:getActionsIndictor()"/>
        </item>
    </section>
</navigation>
function getActionsIndictor() {
    // You logic here
    return {value: 'Pending' , color:"#ffa500"};
}

Valid values for indicator:

  • "true" | "false"

  • true | false

  • number

  • { value: true },

  • { value: 4 },

  • { value: true, color: "#c0FFEE" },

The color attribute can be a named color or #HEX value and will be the app's info color by default.

indicator best practices

  • Use an indicator if:

    • it is important for the user to be aware of an item's status, even when busy with another task

    • it is beneficial to draw the user's attention away from their current task

  • color attribute: Stick to predefined app colors, to ensure a coherent palette when displayed together.

  • value attribute: When displaying text, use short clear words, like "Pending".

sections

Optional

Build navigation sections from JavaScript/TypeScript, using a function that returns an array of component.navigationSection objects.

Sections built using the sections attribute will be appended after the sections specified in XML.

<navigation sections="$:buildSectionsFromJS()" >
    <section>
    <!-- Other navigation items -->
    </section>
    <!-- Section build from JS will be appended here -->
</navigation>
function buildSectionsFromJS() {
    return [
        component.navigationSection({
            label: "General",
            items: [
                component.navigationItem({
                    label: "Sites",
                    view: "sites",
                    collapsable: true
                }
            )]
        })
    ];
}

show-if and hide-if

style-header-background

Optional

Type: string - can be a named color or #HEX value

Default: unset

Specify the background color of the navigation drawer.

<navigation style-header-background="#C0ffEE">
    <!-- Navigation sections -->
</navigation>

For named colors the corresponding named font-color will be used for the hamburger menu icon color and app name color. For #HEX values, the icon and font colors are set to white or dark grey, after performing a contrast check.

style-section-case

Optional

Type: uppercase | lowercase |sentence-case | title-case | none

Default: uppercase

Configure the letter case of section labels.

style-section-color

Optional

Type: string - can be a named color or #HEX value

Default: primary

Specify the font color of section labels.

<navigation style-section-color="#1A1A1A">
    <!-- Navigation sections -->
</navigation>

Component Methods

show

component.getNavigation().show()

Programmatically open the navigation drawer, under the following conditions:

  • The active view is listed in the navigation drawer.

  • The hamburger menu is visible, i.e. the view is the only view on the stack.

hide

component.getNavigation().hide()

Hide the navigation drawer programmatically. This operation follows the same conditions as listed above.

setActive

component.getNavigation().setActive({id:'myId'})

When using a generic view that displays differently based on the view parameter values. It is a common pattern to have multiple navigation items listed in the drawer that all refer to the same view path.

In this case, the drawer will not distinguish between which of those items corresponds to the active view.

In this case it is required to manually set the active view, using id="myId" and component.getNavigation().setActive({id:'myId'}) in init().

<!-- XML -->
<item id="$:getItemId()" label="Site" view="site" args="$:getSiteArgs()"/>
// JS
function getSiteArgs() {
    return [ user, view.currentSite ];
}

function getItemId() {
    return view.currentSite.id + '';
}

Site view code

<!-- XML -->
<view title="Site: {currentSite}">
    <!-- Parameters go here: -->
    <param name="currentUser" type="user" />
    <param name="currentSite" type="site" />

    <!-- Variables go here: -->
    <!-- Components go here: -->
</view>
// JS
function init() {
    component.getNavigation().setActive({id: getItemId()});
}
function resume(from) {}

Breaking change

In version 4.57.2 of the JourneyApps Runtime, component.getNavigation().byId('myId').setActive() was changed to component.getNavigation().setActive({id:'myId'}).

Please update all affected view code.

setOpen

component.getNavigation().setOpen({id:'myId'})

Programmatically toggle a collapsable <section/> or <item/> to an open state. This will persist across view transitions.

Use case: Open a section after a user has performed a particular task or action.

setCollapsed

component.getNavigation().setCollapsed({id:'myId'})

Programmatically toggle a collapsable <section/> or <item/> to a collapsed state. Similar to setOpen this will, persist across view transitions.

Use case: Collapse all items in the drawer except for a particular set of items, focussing the user attention.

Brand

The top part of the navigation drawer, also referred to as the header, is reserved for customer or app branding. Here you can add a and set the to give the navigation drawer a customized look.

Construct a navigation component from JavaScript/TypeScript using a that returns a component.navigation object.

The following component methods are available when an is assigned to the component and component.getNavigation({id:'my-id'}).xxx is called from JS/TS:

💻
Section
Items
General Section
$:function
id
show-if
hide-if
id
Drawer branding
logo
Indicator
logo
background color
reference documentation
Item indicator example