Navigation Commands

Block commands pertaining to navigation.

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.

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. Optionally 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. Optionally 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 tapped 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 &amp;).

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 &amp;).

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 &amp;).

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>