Utility Commands
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.
The following properties are required at a bare minimum:
StartDateTime
Title
TimeZoneId
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.
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.
Examples
DownloadPass
This command can be used to download a pass directly to Apple Wallet (with user permission). This can be used to provide a nicer experience of adding a pass to the wallet without having to go through a browser intermediary.
You may want to consider hiding a button with this command on Android since the functionality is mainly intended for iOS. On Android, this command will simply open an external browser with the URL matching the command parameter. To learn how to show/hide an element based on the device platform, take a look at our On Device Platform markup extension.
Examples
EnablePushNotifications
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 State section 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
This command will allow you to logout the current person from the application. It will then redirect to the homepage.
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.
PrayForRequest
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.
The CommandParameter
can either be a plain string that represents the unique identifier (Guid) of the prayer request, or it can be an instance of the PrayForRequestParameters
object.
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
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.
Examples
PerformHapticFeedback
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
ReloadApplication
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
This instructs the application to reload the currently displayed page.
The CommandParameter
is not used and will be ignored.
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.
The options you have with the Position
parameter are as follows:
MakeVisible
- Just make sure the anchor is visible on screenStart
- Attempt to scroll until the anchor is at the start (top or left) of the screenCenter
- Attempt to scroll until the anchor is at the center of the screenEnd
- Attempt to scroll until the anchor is at the end (bottom or right) of the screen
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
To utilize an app value, you have access to an AppValues
dictionary in Lava:
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.
SetUserPreference
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
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:
Change the StyleClass values applied to a view
Show or hide a view by changing IsVisible
Disable another button
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.
You may notice above that there are two ways to set a property value. If you are only setting a single value you will probably find the Name
and Value
properties easier to deal with. But you can also set multiple properties at one time by using the Values
collection instead. You cannot set properties on multiple views; for that, you would need to use multiple SetViewProperty commands.
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
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.
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
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.
Example
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.
Examples
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.
Follow
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.
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.
Examples
ShowToast
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 CommandParameter
is a string, it will display using the default styles with the command parameter as the message to display.
Examples
ShowCoverSheet
Shows a Cover Sheet.
CloseCoverSheet
Closes any open Cover Sheet.
UpdatePersonProfilePhoto
This command is used to update the profile photo of either the CurrentPerson
, or if a PersonGuid
is supplied as the parameter, it will update theirs. Options are shown with the ShowActionPanel command, including uploading an existing photo or capturing a new one.
This command requires Edit permissions on the following API endpoint: POST api/People/UpdatePersonProfilePhoto?personGuid={personGuid}&filename={filename}
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
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.
Last updated