Developer Docs - Mobile Docs - Utility Commands
AddEventToCalendar
M v3.0
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.
The following properties are required at a bare minimum:
AggregateCommand
You specify the child commands to execute by using an instance of the AggregateCommandParameters object.
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.
Examples
CopyToClipboard
This command sets text to the user's clipboard through the CommandParameter. It enhances the person experience by simplifying copy-and-paste actions.
The CommandParameter accepts a string representing the text to be copied to the person clipboard.
DownloadPass
M v5.0
This command adds a pass to the device wallet. Provide a URL that serves a pass file as the command parameter.
On iOS, the command downloads the file at the URL and hands the bytes to Apple Wallet (PassKit), prompting the individual to add the pass without leaving the app. The URL must return a valid .pkpass payload.
Android has no in-app wallet install, so the command opens the URL in an external browser. What happens next is up to that page or server.
The command is not tied to any pass provider. Any URL that returns a valid .pkpass file works, whether it comes from a Rock workflow, a file on your server, or a third-party pass service.
Because the platforms behave differently, decide whether the button should appear on Android at all, and if so, where it should send them. See the OnPlatform extension for varying content by device platform.
EnablePushNotifications
M v2.0
Normally, notifications are enabled by the application automatically on launch or during the onboarding process of a new user. But sometimes you might want to display a custom page that talks about why you are going to be sending them push notifications to encourage a better response. This command allows you to initiate the request to enable push notifications.
You might want to check out the Push Notification documentation for an example of how to integrate this command with UI that updates automatically based on notifications being enabled or disabled.
The optional CommandParameter is an instance of the EnablePushNotificationsParameters object that is outlined below.
Be aware that Android does not ever show a popup message. Instead, it will just automatically enable notifications and then show your EnabledMessage.
Logout
M v1.0
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: M v2.0
PrayForRequest
M v3.0 C v13.0
Prayer is a big thing for churches, at least it should be. To that end, we wanted to make prayer in your mobile applications as easy as possible. Rather than being limited to specific blocks that support prayer, we decided to give you a command that is available in any block. Using this command you can easily add "Pray" buttons to any page and any content block.
Examples
The first example is a simple Pray button. No special processing happens, it just increments the prayer count for the request.
This second example makes use of the PrayForRequestParameters object to disable the interaction and also provide a workflow to be launched.
PageEvent
M v1.0
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.
Examples
PerformHapticFeedback
M v3.0
This is to perform Haptic Feedback on a user's device. If you are unfamiliar with what haptic feedback is, here is a good reference.
The CommandParameter is a string, but can be left out unless you specifically want to implement the "LongPress" type. Everything else will default to the "Click" type.
Examples
// Example with no command parameter. Defaults to "Click".
// Example with the "LongPress" command parameter.
ReloadApplication
M v1.0
This instructs the application to reload as if you had just forced quit and started it again. This is a development tool that saves a few seconds when debugging stuff. It's not a command you'll want to use in a public app.
The CommandParameter is not used and will be ignored.
ReloadPage
M v1.0
This instructs the application to reload the currently displayed page.
The CommandParameter is not used and will be ignored.
ScrollToVisible
M v1.0
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.
The options you have with the Position parameter are as follows:
Examples
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 can specify a parameters object like so.
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 above.
SetAppValue
M v2.0
The mobile shell has a concept of AppValues. These are values that survive for the life of the application and allow you to save and read the values later. But what good are app values if you can't set them? The syntax of this command is pretty straightforward. You either provide a parameter value of just a key name; or a key name followed by an equals sign followed by a value.
To utilize an app value, you have access to an AppValues dictionary in Lava:
{{ AppValues | ToJSON }}
SetContext
M v1.0
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.
SetUserPreference
M v4.0
Save user-specific properties that we only store on the shell. Be careful not to go overboard with these, as they directly affect your application size. In reality, this is just a SetAppValue command that prefixes the key with user-preference-.
SetViewProperty
M v3.0
There may be times you want to modify the appearance of something or hide it completely, in response to a user action. This command will let you change a property value on a view in your XAML. Here are a few quick examples:
You might be tempted to try disabling the button that the command is attached to. This will most likely not work. When the command finishes executing the button will be automatically re-enabled. In these cases, you might need to hide the button and show a different, already disabled, button instead.
The CommandParameter must specify an instance of the SetViewPropertyParameters object.
Examples
This first example demonstrates a simple action. When the button is tapped then the style class will change from success to danger.
Our next example will show a more advanced version that changes two properties. We are going to do the same transition to a danger button, but also change the text displayed in the button. The first example showed the concise form, but it's a bit harder to read because of how long that string is. The second example will also show the more verbose form, which is a bit easier to read.
Our final example shows how to modify two views in response to a single action using the AggregateCommand. In this case, we want to disable the button after it is tapped. But since we can't directly modify the IsEnabled property (since it gets re-enabled after the command finishes) we have to swap it out with a different button. Instead, we first make "myButton3" visible and then make "myButton4" invisible.
ShowActionPanel
M v1.0
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 pop up an action sheet that 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.
Actions on iOS with automatic dark and light mode, revealed at the bottom of the screen
Actions on Android that don't change with light or dark theme, revealed in the center of the screen
Examples
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.
Write Interaction
M v2.0
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
Example
ShowPopup
M v1.0
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.
Examples
ClosePopup
M v1.0
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.
Follow
M v1.0
The command is used to follow and unfollow specific entities.
Previously, this behavior was only utilized using the Following Icon, but now with this command, you can easily mimic that to create custom follow/unfollow buttons.
When following a person you'll want to use the PersonAlias entity type, not the Person.
Also, be sure to check out the Security Considerations needed to enable following.
Note that this command does not refresh the page. If you have following icons and expect them to be updated from this command, it does not work as such. Consider using SetViewProperty to make visual changes in response to follow and unfollow actions.
{% assign group = 70 | GroupById %}
Share With Contact
Opens a cover sheet that lets the user pick someone from their My Contacts outreach list and share a piece of content with that specific person, rather than handing off to the OS share sheet. Picking a contact prompts the user to share via Email or Message (using the contact's stored email address and phone number); the email/SMS is pre-filled with the supplied subject, body, and URL. Each share is recorded as a Rock Interaction so the outreach activity can be reported on.
Use this command on detail pages where the share is part of an intentional outreach flow (sermon to a specific person, prayer card to a family member, event invite to a contact) and you want it tracked as an interaction. For a generic "share to anything" button, use ShareContent instead.
Properties (ShareWithContactParameters)
The following properties are required at a bare minimum:
Behavior
When the user taps a contact in the cover sheet:
Examples
Share a sermon with a contact
Minimal share (URL only)
Notes
ShowToast
M v4.0
This command displays a "Toast" style message, often used to show quick and temporary messages, such as "saved" or "updated" and things of the sort.
If the CommandParameteris a string, it will display using the default styles with the command parameter as the message to display.
ShowCoverSheet
M v4.0
Shows a Cover Sheet.
CloseCoverSheet
M v4.0
Closes any open Cover Sheet.
UpdatePersonProfilePhoto
M v5.0
This command requires Edit permissions on the following API endpoint:
POST api/People/UpdatePersonProfilePhoto?personGuid={personGuid}&filename={filename}
Starting with Core v16, the role of 'RSR - Mobile Application Users' should be given permission. Previous versions should remain using the role of 'All Authenticated Users'.
The action panel options shown with this command
There are some additional command parameters that can be used for extended functionality. These are UpdatePersonProfilePhotoCommandParameters.
Here's an example for using the Image property:
CreateEntitySetAndNavigate
M v6.0
This command is pretty complex. It does two things... First it generates an Entity Set based on the provided parameters and then performs a Navigation command with an appended query string of the entity set value.