Navigation Commands

Block commands pertaining to navigation.

Navigate Mode

Some blocks have a setting that allows you to specify how they will navigate to another page. This is the Navigate Mode. It has the following values, which correspond to some of the page commands below.

To simplify how this works, in the descriptions below lets assume the current navigation stack contains two pages already. PageA is at the root of the stack, that is the home page. Then the user navigated to PageB. Now we are going to use PageC as the new page to be navigated to.

Value	Description
Push	Pushes a new page onto the navigation stack. If the user presses the back button they will be brought back to PageB
Replace	Replaces the current page with the new page. If the user presses the back button they will be taken to PageA
Show	Replaces the entire navigation stack with the new page. There will be no back button for the user to press.

MapAddress

This command will attempt to open an address or coordinates in the device's native application (Google Maps, Apple Maps, etc.)

This cuts out the intermediary of opening an external browser page.

Property	Type	Description
Name	string	The name of the location as you want it to appear on the user's map application.
Address	string	The address to which you want the app to locate.
Latitude	double?	The latitude of a place to locate. Useless without also providing "Longitude".
Longitude	double?	The longitude of a place to locate. Useless without also providing "Latitude".

Examples

Using an address (recommended):

<Button Text="Map Address"
        Command="{Binding MapAddress}"
        CommandParameter="{Rock:MapAddressParameters Name='Whatever you want!', Address='27 Street 4059, Nazareth Israel'}">
</Button>

Using latitude/longitude:

<Button Text="Map Address"
        Command="{Binding MapAddress}"
        CommandParameter="{Rock:MapAddressParameters Name='Whatever you want!', Latitude='32.69', Longitude='35.30'}">
</Button>

The address example when the button is tapped.

OpenAppSettings

This command will open the device's settings application and take the user directly to the settings for your mobile application.

There are currently no parameters available to this command.

Examples

<Button Text="Tap"
        Command="{Binding OpenAppSettings}" />

OpenBrowser

This command allows you to open a web address using the built-in browser inside the application.

If you are opening a URL to your own Rock server and wish to ensure the user is logged in, you can pass an empty rckipid parameter and an impersonation token will be automatically generated.

Note that tokens generated with an empty parameter will use the settings defined in Rock's global attributes, which may be more open than your specific implementation needs. Consider your impersonation strategy and understand the risk that individuals can share their impersonated URL without realizing it. Alternatively, you can use the Lava filter PersonImpersonationToken.

The CommandParameter can either be a string, which contains the URL and query string parameters, or it can be a reference to an OpenBrowserParameters object which contains the following properties.

Property	Type	Description
Url	string	The URL to be opened. May contain query string parameters.
Parameters	List<Parameter>	Any additional query string parameters to be included with the URL.

Examples

<Button Text="Tap"
        Command="{Binding OpenBrowser}"
        CommandParameter="https://www.google.com/" />

<Button Text="Tap"
        Command="{Binding OpenBrowser}">
    <Button.CommandParameter>
        <Rock:OpenBrowserParameters Url="https://www.google.com/">
            <Rock:Parameter Name="q" Value="rockrms" />
        </Rock:OpenBrowserParameters>
    </Button.CommandParameter>
</Button>

OpenExternalBrowser

Similar to the OpenBrowser command, this one opens a URL in a browser window. The difference between the two is that this command uses the devices native web browser and opens the URL in that application. This means your user leaves your mobile app and gets sent over to Safari or Chrome.

If you are opening a URL to your own Rock server and wish to ensure the user is logged in, you can pass an empty rckipid parameter and an impersonation token will be automatically generated.

Note that tokens generated with an empty parameter will use the settings defined in Rock's global attributes, which may be more open than your specific implementation needs. Consider your impersonation strategy and understand the risk that individuals can share their impersonated URL without realizing it. Alternatively, you can use the Lava filter PersonImpersonationToken.

The CommandParameter can either be a string, which contains the URL and query string parameters, or it can be a reference to an OpenExternalBrowserParameters object which contains the following properties.

Property	Type	Description
Url	string	The URL to be opened. May contain query string parameters.
Parameters	List<Parameter>	Any additional query string parameters to be included with the URL.

Examples

<Button Text="Tap"
        Command="{Binding OpenExternalBrowser}"
        CommandParameter="https://www.google.com/" />

<Button Text="Tap"
        Command="{Binding OpenExternalBrowser}">
    <Button.CommandParameter>
        <Rock:OpenExternalBrowserParameters Url="https://www.google.com/">
            <Rock:Parameter Name="q" Value="rockrms" />
        </Rock:OpenExternalBrowserParameters>
    </Button.CommandParameter>
</Button>

PopPage

This command performs the reverse action of the PushPage command. In simple terms, this behaves just like the user tapping the back button in the navigation toolbar at the top. The current page is popped and removed from the stack and the previous page becomes visible. Think in terms of pushing a page that asks the user for confirmation on something and you want to have a Cancel button that goes back to the previous page.

One additional feature is that you can request that the previous page in the stack should be reloaded before it's displayed. This is accomplished by passing true to the CommandParameter.

Examples

<Button Text="Tap"
        Command="{Binding PopPage}" />

<Button Text="Tap"
        Command="{Binding PopPage}"
        CommandParameter="true" />

PushPage

This command pushes a new page onto the navigation stack. This type of navigation allows the user to use the back button to return to the page that pushed the new page.

If the CommandParameter is a string, then it is expected to contain a page's GUID value and, optionally, a set of query string parameters. The first parameter is separated by a ? and any additional parameters are separated by &. Since these query string parameters are inside an XML document, you must escape them (for example, your & must become &).

If you are using data binding you can also bind the CommandParameter to a true GUID value, in which case it must be the GUID of a valid page.

Finally, if you need advanced parameter usage you can use a PushPageParameters object.

Property	Type	Description
PageGuid	Guid	The Guid identifier of the page to be pushed onto the navigation stack.
Parameters	List<Parameter>	Any additional query string parameters to be passed to the page.
WaitForReady	bool	Waits until the page is loaded before displaying it. (Defaults to false.)

Examples

<Button Text="Tap"
        Command="{Binding PushPage}"
        CommandParameter="e4d80e57-da60-4822-bc22-c071f02958e8" />

<Button Text="Tap"
        Command="{Binding PushPage}"
        CommandParameter="e4d80e57-da60-4822-bc22-c071f02958e8?GroupId=18&amp;Mode=Edit" />

<Button Text="Tap"
        Command="{Binding PushPage}">
    <Button.CommandParameter>
        <Rock:PushPageParameters PageGuid="e4d80e57-da60-4822-bc22-c071f02958e8">
            <Rock:Parameter Name="GroupId" Value="18" />
            <Rock:Parameter Name="Mode" Value="Edit" />
        </Rock:PushPageParameters>
    </Button.CommandParameter>
</Button>

ReplacePage

This command replaces the current page with a new page. This differs from the PushPage command. Using the ReplacePage command, if the user then taps the back button then they will be taken back to the page they were on before the page that called the ReplacePage command.

If the CommandParameter is a string, then it is expected to contain a page's GUID value and, optionally, a set of query string parameters. The first parameter is separated by a ? and any additional parameters are separated by &. Since these query string parameters are inside an XML document, you must escape them (for example, your & must become &).

If you are using data binding you can also bind the CommandParameter to a true GUID value, in which case it must be the GUID of a valid page.

Finally, if you need advanced parameter usage you can use a PushPageParameters object.

Property	Type	Description
PageGuid	Guid	The Guid identifier of the page to be used to replace the current page.
Parameters	List<Parameter>	Any additional query string parameters to be passed to the page.
WaitForReady	bool	Waits until the page is loaded before displaying it. (Defaults to false.)

Examples

<Button Text="Tap"
        Command="{Binding ReplacePage}"
        CommandParameter="e4d80e57-da60-4822-bc22-c071f02958e8" />

<Button Text="Tap"
        Command="{Binding ReplacePage}"
        CommandParameter="e4d80e57-da60-4822-bc22-c071f02958e8?GroupId=18&amp;Mode=Edit" />

<Button Text="Tap"
        Command="{Binding ReplacePage}">
    <Button.CommandParameter>
        <Rock:ReplacePageParameters PageGuid="e4d80e57-da60-4822-bc22-c071f02958e8">
            <Rock:Parameter Name="GroupId" Value="18" />
            <Rock:Parameter Name="Mode" Value="Edit" />
        </Rock:ReplacePageParameters />
    </Button.CommandParameter>
</Button>

ShowPage

This command replaces the entire navigation stack with a new page. This means there will be no back button to return to any previous page.

If the CommandParameter is a string, then it is expected to contain a page's GUID value and, optionally, a set of query string parameters. The first parameter is separated by a ? and any additional parameters are separated by &. Since these query string parameters are inside an XML document, you must escape them (for example, your & must become &).

If you are using data binding you can also bind the CommandParameter to a true GUID value, in which case it must be the GUID of a valid page.

Finally, if you need advanced parameter usage you can use a PushPageParameters object.

Property	Type	Description
PageGuid	Guid	The Guid identifier of the page to be used as the new page.
Parameters	List<Parameter>	Any additional query string parameters to be passed to the page.
WaitForReady	bool	Waits until the page is loaded before displaying it. (Defaults to false.)

Examples

<Button Text="Tap"
        Command="{Binding ShowPage}"
        CommandParameter="e4d80e57-da60-4822-bc22-c071f02958e8" />

<Button Text="Tap"
        Command="{Binding ShowPage}"
        CommandParameter="e4d80e57-da60-4822-bc22-c071f02958e8?GroupId=18&amp;Mode=Edit" />

<Button Text="Tap"
        Command="{Binding ShowPage}">
    <Button.CommandParameter>
        <Rock:ShowPageParameters PageGuid="e4d80e57-da60-4822-bc22-c071f02958e8">
            <Rock:Parameter Name="GroupId" Value="18" />
            <Rock:Parameter Name="Mode" Value="Edit" />
        </Rock:ShowPageParameters />
    </Button.CommandParameter>
</Button>