Utility Commands

Block commands that provide advanced functionality.

AddEventToCalendar

You finally did it. You built that (almost) perfect calendar event detail page. It looks pretty, it shows all the information. You even got the time zone right! If only you could have that "Add to Calendar" button like everybody else.

Well now your calendar event detail page can be perfect. This command allows you to specify all the details of a one-time event and add it to the user's default calendar.

The first time this command (or any other that accesses the calendar) is used it will prompt the user to allow access to their calendars.

Parameters

Property

Type

Description

StartDateTime

DateTime

The start date and time of the event. If you provide any time zone information here it will be ignored.

EndDateTime

DateTime

The end date and time of the event. If you leave this blank then the time information from the StartDateTime will be dropped and it will become an all day event.

Title

string

The title (or name) of the event. Space is often limited when displaying the title so remember to keep it short.

Notes

string

Additional notes about the event. Think of this as the details when opened information.

Location

string

The location of the event. This can technically be anything you like such as "Main Auditorium", but if you put in an actual address then devices will usually make it link to the maps application.

Url

string

A URL that the user can follow to get more information about the event.

TimeZoneId

string

The IANA time zone identifier that the StartDateTime and EndDateTime are in. For example, "America/Phoenix".

AlarmInMinutes

int

If set then an alarm will be added to the event that triggers this many minutes before the event happens.

The following properties are required at a bare minimum:

  • StartDateTime

  • Title

  • TimeZoneId

Example

<Button Text="Add to Calendar" Command="{Binding AddEventToCalendar}">
<Button.CommandParameters>
<Rock:AddEventToCalendarParameters Title="Rock Solid Finances Class"
StartDateTime="2021-07-04 18:30:00"
EndDateTime="2021-07-04 20:00:00"
Location="3120 W Cholla St, Phoenix AZ, 85029-4113"
Url="https://www.rocksolidchurchdemo.com/page/414?EventOccurrenceId=3"
TimeZoneId="America/Phoenix" />
</Button.CommandParameters>
</Button>

AggregateCommand

This is a special use command. It allows you to chain multiple commands together. A common usage of this would be to combine the SetContext and ReplacePage commands to change an Entity context and then reload the current page.

You specify the child commands to execute by using an instance of the AggregateCommandParameters object.

Property

Type

Description

Commands

ICollection<CommandReference>

The collection of commands that will be executed. This is the default property so you don't need to explicitly specify it.

The CommandReference object is defined like a normal command reference:

Property

Type

Description

Command

ICommand

The command to be executed.

CommandParameter

object

The parameter to be passed to the command.

Examples

<Button Text="Tap"
Command="{Binding AggregateCommand}">
<Button.CommandParameter>
<Rock:AggregateCommandParameters>
<Rock:CommandReference Command="{Binding SetContext}">
<Rock:CommandReference.CommandParameter>
<Rock:SetContextParameters Name="Campus"
Value="0a3a20eb-c4a8-44fe-9daf-d22b88fae377" />
</Rock:CommandReference.CommandParameter>
</Rock:CommandReference>
<Rock:CommandReference Command="{Binding ReplacePage}"
CommandParameter="b06173ed-aa2f-43d8-bd38-eb5becca1cbe" />
</Rock:AggregateCommandParameters>
</Button.CommandParameter>
</Button>

Callback

Some blocks, currently just the Content block, support what is called Callbacks. You can learn more about these in the Advanced: Dynamic Content and the Developer chapters. But, for our purposes here, you can think of these as an API call back to the server's logic for the block.

If the CommandParameter is a plain string, then it is used as the name of the callback function to be queried on the server. If you need to pass any parameters to that function then CommandParameter should point to an instance of the CallbackParameters object.

Property

Type

Description

Name

string

The name of the callback to be called on the server.

Parameters

List<Parameter>

Any parameters that will be passed to the callback function.

Validator

Validator

Optional reference to a validator that will be executed before sending the command to the block. If the validator fails then the command is not sent.

Examples

<Button Text="Tap"
Command="{Binding Callback}"
CommandParameter="UserTap" />
<Button Text="Tap"
Command="{Binding Callback}">
<Button.CommandParameter>
<Rock:CallbackParameters>
<Rock:Parameter Name="GroupId" Value="18" />
</Rock:CallbackParameters>
</Button.CommandParameter>
</Button>

Logout

This command will allow you to logout the current person from the application. It will then redirect to the homepage.

The CommandParameter can be one of the following items:

  • A string that contains either the value "True" to indicate that the current page should be reloaded, or the Guid of the page to show instead of the home page.

  • An instance of the LogoutParameters object that is outlined below.

Property

Type

Description

ReloadPage

bool

If true then the current page is reloaded instead of navigating away. Defaults to false.

PageGuid

Guid?

The page to navigate to instead of the home page. Defaults to null.

Parameters

List<Parameter>

Optional parameters to pass to the page in the query string. Defaults to empty.

<Button Text="Logout"
Command="{Binding Logout}" />

PageEvent

You learned, or will learn, elsewhere that you can use Lava on the mobile shell to handle certain page events and respond to them. Normally these page events are just ones generated by the system for you. However, you can trigger your own custom page events using this command.

The CommandParameter can either be a plain string that indicates the event name to be triggered, or it can be an instance of the PageEventParameters object. This latter method allows you to pass parameters into your lava logic.

Property

Type

Description

Event

string

The name of the event to be triggered.

Parameters

List<Parameter>

Any parameters that will be passed to the Lava engine, these manifest as lava variables.

Examples

<Button Text="Tap"
Command="{Binding PageEvent}"
CommandParameter="UserTap" />
<Button Text="Tap"
Command="{Binding PageEvent}">
<Button.CommandParameter>
<Rock:PageEventParameters Event="UserTap">
<Rock:Parameter Name="GroupId" Value="18" />
</Rock:PageEventParameters>
</Button.CommandParameter>
</Button>

ReloadApplication

Don't use this. No seriously, you can use it but it has a very special purpose. Basically, this instructs the application to reload as if you had just force quit and started it again. This is a development tool that saves us a few seconds when we are debugging stuff, though you may find it useful when debugging your own blocks.

The CommandParameter is not used and will be ignored.

Examples

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

ScrollToVisible

There are two ways to initiate this command, we'll show them below. But the basic syntax is you specify the Anchor element that should be scrolled until it becomes visible. Think of this like the HTML Anchor href, or a "jump to" button.

You can either pass the view to be made visible directly by reference in the CommandParameter or you can pass an instance of the ScrollToVisibleParameters object.

Property

Type

Description

Anchor

VisualElement

The view which resides inside a ScrollView that should be made visible.

Position

ScrollToPosition

The position to put the view at after scrolling (see below). Defaults to MakeVisible.

The options you have with the Position parameter are as follows.

  • MakeVisible - Just make sure the anchor is visible on screen.

  • Start - Attempt to scroll until the anchor is at the start (top or left) of the screen.

  • Center - Attempt to scroll until the anchor is at the center of the screen.

  • End - Attempt to scroll until the anchor is at the end (bottom or right) of the screen.

Examples

<StackLayout>
<Button Text="Scroll"
Command="{Binding ScrollToVisible}"
CommandParameter="{x:Reference myLabel}" />
<BoxView Color="Red"
HeightRequest="1200" />
<Label Text="My Label"
x:Name="myLabel" />
<BoxView Color="Blue"
HeightRequest="1200" />
</StackLayout>

The above will scroll the first ScrollView in the view tree above the Label we specified as our anchor so that the label is visible. This by itself may be just fine for what you need, but it may not end up doing what you want. By default the anchor will be scrolled until it becomes "just visible". In this case, since we need to scroll down, the label will end up at the bottom of the screen.

To accommodate those situations, you are able to specify a parameters object like so.

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

This still indicates the same Label we want to use as the Anchor, but it also specifies the position we want it to end up at. Now, this is not a forced position. If there were nothing below the label, it wouldn't be possible for it to end up at the top. But since we have a lot of content below as well, there is enough room to scroll.

Finally, due to the way XAML works, there is a shorthand to the XAML we wrote above.

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

SetAppValue

The mobile shell has a concept of App Values. These are values that survive for the life of the application and allow you to save and read the values later. But what good or app values if you can't set them? The syntax of this command is pretty straight forward. You either provide a parameter value of just a key name; or a key name followed by an equals sign followed by a value.

<Button Text="Remove Value"
Command="{Binding SetAppValue}"
CommandParameter="KeyToRemove" />
<Button Text="Set Value"
Command="{Binding SetAppValue}"
CommandParameter="{KeyToSet=SomeValue}" />

SetContext

This command allows you to set an entity context value based on a user's action. For example, you could build a custom Campus Context Picker and set the context when the user taps an action button.

The parameter should be an instance of the SetContextParameters class, which is described below.

Property

Type

Description

Name

string

The name of the entity whose context is to be set. For example Campus.

Value

Guid?

The Guid value to set the context name to. If this is left blank then the context is unset. Defaults to null.

<Button Text="Tap"
Command="{Binding SetContext}">
<Button.CommandParameter>
<Rock:SetContextParameters Name="Campus"
Value="e4d80e57-da60-4822-bc22-c071f02958e8" />
</Button.CommandParameter>
</Button>

ShowActionPanel

This action will show an action panel (think action sheet in iOS terms). This is basically a popup that contains a short message and a number of buttons the user can choose from. A common example of this would be a "reply" button in a mail application. When tapping the button it might then popup an action sheet which contains a few buttons to help you decide what you intend to do: Reply, Reply All, Forward.

These popups usually have a Cancel button (though it's not strictly required. Additionally, you can specify a single "destructive" button that stands out to the user. Often this would be a Delete type action and is usually styled red.

The CommandParameter must specify an instance of the ShowActionPanelParameters object.

Property

Type

Description

Title

string

The title of the action panel, keep it short!

CancelTitle

string

The text to display in the cancel button (optional). Defaults to empty string.

DestructiveButton

ActionPanelButton

Defines the button that implies a destructive operation, for example on iOS this button becomes red (optiona). Defaults to null.

Buttons

ICollection<ActionPanelButton>

A collection of buttons to be shown, this is the default content property meaning you would just add ActionPanelButton nodes as child elements.

Examples

<Button Text="Action" Command="{Binding ShowActionPanel}">
<Button.CommandParameter>
<Rock:ShowActionPanelParameters Title="My Action Sheet"
CancelTitle="Do Nothing">
<Rock:ShowActionPanelParameters.DestructiveButton>
<Rock:ActionPanelButton Title="Delete"
Command="{Binding PushPage}"
CommandParameter="c258265c-9645-46f1-a69b-0e0f149e5e83" />
</Rock:ShowActionPanelParameters.DestructiveButton>
<Rock:ActionPanelButton Title="First Button"
Command="{Binding OpenBrowser}"
CommandParameter="https://www.google.com" />
<Rock:ActionPanelButton Title="Second Button"
Command="{Binding OpenExternalBrowser}"
CommandParameter="https://www.google.com/" />
</Rock:ShowActionPanelParameters>
</Button.CommandParameter>
</Button>

Thanks to the magic of XAML, we can simplify the definition of the destructive button a bit if we want, it's up to you.

<Button Text="Action" Command="{Binding ShowActionPanel}">
<Button.CommandParameter>
<Rock:ShowActionPanelParameters Title="My Action Sheet"
CancelTitle="Do Nothing"
DestructiveButton="{Rock:ActionPanelButton Title=Delete, Command={Binding PushPage}, CommandParameter=c258265c-9645-46f1-a69b-0e0f149e5e83}">
<Rock:ActionPanelButton Title="First Button"
Command="{Binding OpenBrowser}"
CommandParameter="https://www.google.com" />
<Rock:ActionPanelButton Title="Second Button"
Command="{Binding OpenExternalBrowser}"
CommandParameter="https://www.google.com/" />
</Rock:ShowActionPanelParameters>
</Button.CommandParameter>
</Button>

Write Interaction

This command is only available in Mobile Shell v2 and later.

Allows you to write an Interaction to Rock when the command is executed. For example you could write an interaction in response to the user tapping a button. By default only a single Interaction will be written no matter how many times the command is executed. Normally this is probably what you want. If for some reason you want to allow multiple Interactions to be generated, set the IsMultipleAllowed property to true.

This command takes a parameter object of type InteractionParameters that contains the following details.

Parameters

In order for your parameters to be considered valid, you must provide at least one of ChannelId or ChannelGuid; and you must provide at least one of ComponentId or ComponentName. Also note that some event sources will provide defaults for some of the properties in the table below or may even override a value you provide.

Property

Type

Description

ChannelId

int?

The identifier of the channel where this interaction will be recorded. Must already exist. Defaults to null.

ChannelGuid

Guid?

The unique identifier of the channel where this interaction will be recorded. Must already exist. Defaults to null.

ComponentId

int?

Specifies a specific component identifier where this interaction will be recorded. If used, the component must already exist. Defaults to null.

ComponentName

string

Specifies a component name for where this interaction will be recorded. If you use this property to pick the component then the system will look for a matching component and if not found create one. Defaults to null.

ComponentEntityId

int?

If the channel is configured to have an Entity associated with the components then this would provide the Id of the Entity if it gets created from the ComponentName property. Defaults to null.

Data

string

Custom data that should be stored with the interaction. There is no specific format requirements, as long as the data is a string. Defaults to null.

EntityId

int?

Associates the interaction with the specified entity. The entity type will be taken from the channel configuration. Defaults to null.

Operation

string

The type of operation that identifies this interaction. There is no specific list of strings that you must use, but a few suggestions are View and Watch. Defaults to null.

Summary

string

The text that describes this event in a user friendly manner. Defaults to null.

RelatedEntityTypeId

int?

Sets the EntityTypeId of the related entity that should be associated with this Interaction. Defaults to null.

RelatedEntityId

int?

Sets the EntityId of the related entity that should be associated with this Interaction. Defaults to null.

ChannelCustom1

string

Sets the first custom interaction string value. Defaults to null.

ChannelCustom2

string

Sets the second interaction string value. Defaults to null.

ChannelCustomIndexed1

string

Sets the first custom indexed interaction string value. Defaults to null.

IsMultipleAllowed

bool

Specifies if multiple interactions can be written for this single command. If set to true then each time the command is executed a new interaction will be written. Otherwise only the first execution will write an interaction. Note: If the page is reloaded then a new parameter object is created and a new interaction could again be written. Defaults to false.

Example

<Button Text="Like" Command="{Binding WriteInteraction}">
<Button.CommandParameter>
<Rock:WriteInteractionParameters Operation="Like"
Summary="I like this."
ChannelId="3"
ComponentId="87" />
</Button.CommandParameter>
</Button>

ShowPopup

Rock Mobile Shell supports the idea of small popup pages. These don't support navigation, but can be useful for a simple display of additional content without leaving the current page.

If the CommandParameter is a string then it will be interpreted as a page guid with optional query string parameters. This will display a full Rock page inside the popup view.

Alternatively, you can specify a view to use as the content for the popup. This is ideal for showing additional details of items or perhaps a list filter.

Finally, you can specify a ShowPopupParameters object and supply additional options as seen below.

Property

Type

Description

Anchor

ShowPopupAnchor

Where to anchor the popup, possible values are Center, Top, and Bottom. Defaults to Center.

Content

View

The view to display inside the popup, if set this will override the PageGuid property.

PageGuid

Guid

The Rock page to be displayed inside the popup.

Parameters

List<Parameter>

A collection of query string parameters that will be passed to the Rock page.

Title

string

The title of the popup.

ShowHeader

bool

Determines if the header should be shown. If disabled then you have complete control of the design. Defaults to True.

Examples

<Button Text="Tap"
Command="{Binding ShowPopup}"
CommandParameter="e4d80e57-da60-4822-bc22-c071f02958e8?GroupId=18&amp;Mode=Edit" />
<Button Text="Tap"
Command="{Binding ShowPopup}">
<Button.CommandParameter>
<Rock:ShowPopupParameters Title="Select Group"
PageGuid="e4d80e57-da60-4822-bc22-c071f02958e8">
<Rock:Parameter Name="ParentGroupId" Value="8293" />
</Rock:ShowPopupParameters>
</Button.CommandParameter>
</Button>
<Button Text="Tap"
Command="{Binding ShowPopup}">
<Button.CommandParameter>
<Rock:ShowPopupParameters Title="Select Group"
Anchor="Top">
<Rock:ShowPopupParameters.Content>
<StackLayout>
<Label Text="Hello Rock" />
<Button Text="Close"
Command="{Binding ClosePopup}" />
</StackLayout>
</Rock:ShowPopupParameters.Content>
</Rock:ShowPopupParameters>
</Button.CommandParameter>
</Button>

ClosePopup

This command is the opposite of the ShowPopup command. If there is an open popup then it will be closed.

This command takes no parameters.

Examples

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