Please login to access all of the features of the Community Site.

⚡ Commands

The .NET MAUI framework and the Rock Mobile application shell both utilize Commands to manage most actions and events. When a button is tapped, a Command executes. Typically, a Command is accessible via a Command property, although sometimes a view may support multiple Commands, in which case their names vary. Additionally, each Command can accept a parameter to fine-tune how it performs its task.

Since all Commands follow the same structure, you can use any Command anywhere. For instance, a Command configured for a button to open a browser window can also be assigned to a swipe gesture, enabling a browser to open when an individual swipes the screen.

Each Command has its own page in this section. Here’s how to set up a button to open a browser window when tapped:

<Button Text="Search"
    StyleClass="btn, btn-primary"
    Command="{Binding OpenBrowser}"
    CommandParameter="https://www.google.com/search?q=rockrms" />

Here, we bind the button's Command to the built-in OpenBrowser handler and pass the URL via the CommandParameter. Now, let’s add a textbox where an individual can enter a search term, using that term in the URL.

<Rock:FieldContainer>
    <Rock:TextBox Label="Search"
        x:Name="SearchTerm" />
</Rock:FieldContainer>

<Button Text="Search"
    StyleClass="btn, btn-primary"
    Command="{Binding OpenBrowser}">
    <Button.CommandParameter>
        <Rock:OpenBrowserParameters Url="https://www.google.com/search">
            <Rock:Parameter Name="q"
                Value="{Binding Text, Source={x:Reference SearchTerm}}" />
        </Rock:OpenBrowserParameters>
    </Button.CommandParameter>
</Button>

In this example, we create an inline object in XAML within the CommandParameter property of the button. The <Rock:OpenBrowserParameters> object sets the base URL, and the nested parameters are appended as query strings. We define a parameter q, which Google uses for the search term. By binding the textbox's value with {Binding Text, Source={x:Reference SearchTerm}}, we capture the input text from SearchTerm and insert it as the query value.

Now, we have a search button that opens a search results page using the text input without writing a single line of code!

Most Commands support a simplified form for CommandParameter. As seen in the OpenBrowser example, a static URL can be passed directly if no custom parameters are needed. Each Command specifies the forms its CommandParameter can accept.

Many Commands work within a block’s context (except for the Callback Command, which only functions in Content-derived blocks). While most Commands are accessible outside a block, such as in a flyout menu, some require page-specific context, like ShowActionPanel, which needs to know the page to overlay the panel.

Shorthand Syntax

Command parameter objects also support a shorthand form for XAML extensions, which simplifies the syntax. Here’s a comparison:

<Button Text="Scroll"
    Command="{Binding ScrollToVisible}">
    <Button.CommandParameter>
        <Rock:ScrollToVisibleParameters Anchor="{x:Reference myLabel}"
            Position="Start" />
    </Button.CommandParameter>
</Button>

Using the shorthand, this becomes:

<Button Text="Scroll"
    Command="{Binding ScrollToVisible}"
    CommandParameter="{Rock:ScrollToVisibleParameters Anchor={x:Reference myLabel}, Position=Start}" />

This condensed syntax is more succinct but doesn’t support arrays in parameters. When values contain commas, they should be enclosed in single quotes within the double-quoted property string.

<Button Text="Send"
    Command="{Binding SendSms}"
    CommandParameter="{Rock:SendSmsParameters Message='Hello, Dave.', Recipients=1558881234}" />

Running Several Commands

Use AggregateCommand when one tap should run more than one Command. A button has a single Command property, so on a button it’s the only option. On other views you can attach several TapGestureRecognizer elements instead, but the two don’t behave the same:

  • Order. AggregateCommand runs its Commands one at a time and waits for each to finish before starting the next. Separate gesture recognizers all start on the same tap without waiting, so a slower Command, like Callback or PushPage, can finish after one listed below it.
  • Repeats. A Command ignores new requests while it’s still running. With separate recognizers, a second use of the same Command on the same tap is dropped. AggregateCommand runs it again once the first one finishes.
  • Popups. AggregateCommand reads all of its Commands before running the first, so a ClosePopup that clears the binding context doesn’t cancel the Commands after it.

Separate recognizers are fine when the Commands are independent and order doesn’t matter, such as writing an interaction next to a navigation. Otherwise, use AggregateCommand:

<Button Text="Save"
    Command="{Binding AggregateCommand}">
    <Button.CommandParameter>
        <Rock:AggregateCommandParameters>
            <Rock:CommandReference Command="{Binding ShowToast}"
                CommandParameter="Saved" />
            <Rock:CommandReference Command="{Binding PopPage}" />
        </Rock:AggregateCommandParameters>
    </Button.CommandParameter>
</Button>

Nested Bindings

Complex binding scenarios often arise with nested action items like ShowCoverSheet, ShowActionPanel, and ShowPopup. These items may require additional BindingContext references to maintain functionality at deeper nesting levels, as demonstrated below:

<Button Text="Options"
    x:Name="ActionButton"
    Command="{Binding ShowActionPanel}">
    <Button.CommandParameter>
        <Rock:ShowActionPanelParameters Title="Options"
            CancelTitle="Cancel">
            <Rock:ActionPanelButton Title="Save and Continue"
                Command="{Binding BindingContext.AggregateCommand, Source={x:Reference ActionButton}}">
                <Rock:ActionPanelButton.CommandParameter>
                    <Rock:AggregateCommandParameters>
                        <Rock:CommandReference Command="{Binding BindingContext.ShowToast, Source={x:Reference ActionButton}}"
                            CommandParameter="Saved" />
                        <Rock:CommandReference Command="{Binding BindingContext.PushPage, Source={x:Reference ActionButton}}"
                            CommandParameter="2cda9cfc-4717-4455-bfc2-633735cda86f" />
                    </Rock:AggregateCommandParameters>
                </Rock:ActionPanelButton.CommandParameter>
            </Rock:ActionPanelButton>
        </Rock:ShowActionPanelParameters>
    </Button.CommandParameter>
</Button>

In this configuration, each binding reads its Command from the button’s BindingContext through x:Reference, so the Commands stay connected to the correct data context at each level.

Some blocks include a setting called Navigate Mode, which lets you control how navigation to another page should happen. The available options align with specific page navigation commands.

To keep things simple, let’s walk through an example: imagine the current navigation stack has two pages. PageA is the root or home page, and someone has navigated from there to PageB. Now, we want to navigate to a new page, PageC, and see how different Navigate Modes affect the stack.

ValueDescription
PushPushes a new page onto the navigation stack. If the user presses the back button they will be brought back to PageB
ReplaceReplaces the current page with the new page. If the user presses the back button they will be taken to PageA
ShowReplaces the entire navigation stack with the new page. There will be no back button for the user to press.