Views are user-interface objects such as labels, buttons, and sliders that are commonly known as controls or widgets in other graphical programming environments.
The .NET MAUI framework provides a rich collection of base views (controls). You can find a documentation on these views on the Microsoft site.
Attach commands to events.
Inherits from EventToCommandBehavior
The EventToCommandBehavior lets you link a command to an event in your UI. For example, the Text Editor control has a TextChanged event. With this behavior, you can trigger a command whenever that event occurs—like showing a toast notification every time the text is modified.
Polish your views to react to different types of gestures (in place of a non-animated TapGesture)
Inherits from TouchBehavior
The TouchBehavior allows you to add touch interaction to any VisualElement. It lets you customize visual properties like BackgroundColor
, Opacity
, Rotation
, Scale
, and more when the element is touched.
Inherits from Xamarin.Forms.ContentView
Sometimes things take a moment to load. You don't want to just display a big white screen for the user to stare at, you want them to know we're working hard for them. That said, usually you are not going to be instantiating this view directly. But just in case you want to, here you go.
The ActivityIndicator will begin "working" when it becomes visible on screen. Initially, it will not show anything. Once a built-in timer elapses (350ms) then the actual indicator becomes visible. Your user will not care if it takes your page a few hundred milliseconds to load so there is no need to show them a spinning wheel right away.
Property
Type
Description
IsVisible
bool
If true
then the activity indicator will be visible and show that work is being done.
Inherits from Xamarin.Forms.ContentView
Somewhere in your application you normally have some sort of About page that gives information about your app, such as version numbers. This view provides those version numbers in a quick way without you having to worry about styling. It simply lays out each item as a single Label inside a vertical StackLayout.
The values displayed are:
Package Version - This displays the version number of the site package. This is the file that is built when you click the Deploy button when viewing your site. This can tell you if the user is somehow using an outdated site package.
Shell Version - The shell is what provides all the standard code and functionality across all Rock Mobile applications. This helps you know what features are supported on the user's device.
App Store Version - This will match the version number of your application bundle as reported by the Google Play Store and Apple App Store.
If you wish to completely customize how this data is presented, you can access the same information via data binding to Application.PackageVersion
, Application.ShellVersion
, and Application.ApplicationVersion
. Such as:
This view contains no properties of it's own.
Display a person's avatar using the configured settings. Rock's avatar feature provides the ability to create unique avatar images for each person record within the system.
Inherits from Microsoft.Maui.Controls.ContentView
Visit the link below to learn more about this Rock feature:
This control constructs an avatar image source based on the provided parameters or displays the current person's avatar.
Source
string
The direct source to the Avatar URL.
PersonGuid
Guid
The person to display the avatar for.
Rounded
bool
Whether or not the avatar should be rounded.
ShowStroke
bool
Whether or not a default stroke shape should be applied to the avatar.
AvatarBackgroundColor
Color
The background color of the avatar. This is passed along to the GetAvatar
request.
AvatarForegroundColor
Color
The foreground color of the avatar. This is passed along to the GetAvatar
request.
AvatarAgeClassification
AgeClassification
The age classification of the avatar.
AvatarGender
Gender
The gender of the avatar.
AvatarBold
bool
Whether or not the avatar should be bolded.
AvatarStyle
string
The style of the avatar.
Typically initials
or icon
.
AvatarText
string
The text to use for the avatar.
In most cases, you'll want to provide the Avatar source directly to the component. This should be the method utilized whenever you have a person object available.
Otherwise, you can pass in the parameters to build the Avatar source manually.
If no properties are set, the component will display the current person's avatar:
Listen to specific Bible verses on the fly.
This control is a component designed for playing audio content of Bible verses. This is handled via the Spark Data API to retrieve the information about the Bible and the verses to be displayed.
Reference
String
One or more Bible references separated by a semicolon. Example: Genesis 1:1-9; Matthew 2,3
. This would result in the contents of Genesis chapter 1 verses 1-9 being displayed, followed by Matthew chapters 2 and 3.
WriteInteraction
Boolean
A property that allows you to enable or disable the writing of interactions.
WriteInteractionParameters
An object containing parameters that control how the audio is interacted with. This could include behaviors like the audio play speed, volume, etc.
You can supply custom content to your Bible Audio control, and maintain a reactive UI through bindings and commands.
IsPlaying
Boolean
A flag indicating whether audio is currently playing. A value of true
means the audio is playing; false
means it's not.
PlayAudio
ICommand
A command that triggers the playing of the Bible audio. This is used to start the audio.
PauseAudio
ICommand
A command that triggers the pausing of the Bible audio. This is used to pause the audio.
PlayOrPauseAudio
ICommand
A command that either plays or pauses the Bible audio based on the current state (if it's playing or not).
Then the content is simply supplied as the direct child of the control:
Inherits from Xamarin.Forms.ContentView
The BibleBrowser control provides a way for you to build a nice interface for the user to browse through the Bible. How that browser looks and behaves is up to you. The intended purpose is to let the user pick the chapter and book they want to read and then let them navigate to the next/previous chapters or books via interface elements.
The primary purpose of this control is to handle much of the logic in regards to navigating within the Bible for you. As an example, you need to know when to show and hide the "move next" and "move previous" buttons. Building in all the logic to determine if there is another book or chapter after the current one is tedious. So we did it for you!
Content
The content that will be displayed inside the browser. This is the default property so it can be omitted when creating child elements. Defaults to null.
Reference
string
A single Bible reference, should not contain any verse information. Example: Genesis 12
. This would result in the browser starting on Genesis 12 and then allowing the user to browse to different books and chapters from there.
Translation
string
The translation of the Bible to display. ESV, NLT or MSG are supported. Defaults to ESV.
This control provides no default content so you must provide some content of your own for it to be of any use.
There are some special bindings available for your custom content. In addition to the normal bindings (such as PushPage) that you normally have available, there are a few additional ones you can use. All of these additional bindings are inside the BibleBrowser
property.
Reference
string
The current reference that should be displayed in the browser.
Reading
Reading
The internal state data of the Bible content to be displayed. If using Bible Reader control as children they should be bound to this property.
CurrentBook
string
The current book that is displayed in the browser. read-only
CurrentChapter
int
The current chapter number that is displayed in the browser. read-only
HasPreviousBookOrChapter
bool
true
if there is a book or chapter before the currently displayed chapter.
HasPreviousBook
bool
true
if there is a book before the currently displayed chapter.
HasPreviousChapter
bool
true
if there is a chapter in the current book before the currently displayed chapter.
HasNextBookOrChapter
bool
true
if there is a book or chapter after the currently displayed chapter.
HasNextBook
bool
true
if there is a book after the currently displayed chapter.
HasNextChapter
bool
true
if there is a chapter in the current book after the currently displayed chapter.
ShowPickerCommand
ICommand
Execute this command to show the book and chapter picker to the user for them to select a new reference to read or listen to.
ShowPreviousBookOrChapterCommand
ICommand
Execute this command to update the reference to move to the previous book or chapter. If a previous chapter is available it will be used, otherwise the previous book will be used.
ShowPreviousBookCommand
ICommand
Execute this command to update the reference to move to the previous book.
ShowPreviousChapterCommand
ICommand
Execute this command to update the reference to move to the previous chapter.
ShowNextBookOrChapterCommand
ICommand
Execute this command to update the reference to move to the next book or chapter. If a next chapter is available it will be used, otherwise the next book will be used.
ShowNextBookCommand
ICommand
Execute this command to update the reference to move to the next book.
ShowNextChapterCommand
ICommand
Execute this command to update the reference to move to the next chapter.
Inherits from Xamarin.Forms.ContentView
The Bible Reader control allows you to display a set of verses for the user to read. This is handled via the Spark Data API to retrieve the information about the Bible and the verses to be displayed.
Here are some guidelines for creating reference values. It's recommended to test any complex ones in advance to ensure they work as expected. If the reference list is long, consider breaking them up on the page above and load each one individually.
Multiple references are supported but must be separated by a semi-colon ;
Consecutive verses from a single chapter are supported with this syntax: Genesis 1:1-9
Verses cannot span across chapters, so divide them up: Genesis 1:30-31; Genesis 2:1-3
If a book only contains a single chapter, it still must be included: Jude 1
Full chapters can be included with this syntax: Genesis 1,2
or Genesis 1-2
Reference
string
One or more Bible references separated by a semicolon. Example: Genesis 1:1-9; Matthew 2,3
. This would result in the contents of Genesis chapter 1 verses 1-9 being displayed, followed by Matthew chapters 2 and 3.
Reading
Reading
The internal state data of the Bible content to be displayed.
ShowReference
boolean
Shows the reference text (for example Genesis 1:1-9
) above the verses. Defaults to true.
ShowHeadings
boolean
Shows any headings along with the verse text. For example Genesis 1:1 has the heading The Creation of the World
. Defaults to true.
ShowVerseNumbers
boolean
Show verse numbers inline along with the verse text. Defaults to true.
ShowCopyright
boolean
Show the copyright text below the verse text. Please do not turn this off unless you are displaying the copyright text elsewhere. For example, if you are displaying multiple BibleReader controls in the page you could put the copyright notice at the very bottom rather than after each individual control. Defaults to true.
Translation
string
The translation of the Bible to display. ESV, NLT or MSG are supported. Defaults to ESV.
WriteInteraction
boolean
Determines whether the individual's interaction should be recorded.
For details on styling this control see the Bible Styling page.
Inherits from Xamarin.Forms.ContentView
The Campus Context Picker allows you to display a picker with all the campus choices allowed for a person. The selected campus is sent with every request, even if you leave the page. This then allows blocks to use that information to make default campus decisions, or show content specific to a campus.
If you are familiar with the web control of the same name, this offers pretty much the same functionality for mobile.
Note: If no context value is set the current person's home campus will be used.
This control exposes no properties that can be modified.
Inherits from Xamarin.Forms.ContentView
This is a special use camera control that allows you to scan specially formatted QR codes. When scanned, the app will automatically direct the user to the appropriate page to display the content.
Since an example usage might make things clearer; suppose you are doing small group signups. You want to provide your app-users an easy way to sign up for a group. Normally you might print out a bunch of sign-up sheets that people can write their name and contact information on so that you can later add them to the group. After service, these get laid out on various tables in the lobby.
For our use, you would include a QR code on the sheet that contained a workflow identifier and the group identifier. When the user opens their app to scan the code it would take them to the workflow entry page, launch that workflow and set the group they want to join. If they are logged in, all you have to do is display a confirmation page so that they can verify the group they are joining.
Property
Type
Description
Page
string
The page identifier that the reader will navigate to using the NavigationMode property. Whatever code data is retrieved is passed in as a query string parameter with a Data
key.
WorkflowPage (Legacy)
Guid
The same as the version 5 property without additional query string parameters.
NavigationMode
The type of navigation to perform when the code is scanned. Defaults to Push.
There are currently two types of codes supported.
A workflow code will take the user to the workflow entry page and launch a new workflow. These codes begin with RK:WF:
and then contain a Guid to identify the workflow type to be launched. If you wish to pass any default values to be set on the new workflow you can pass then as query string parameters after the workflow type Guid.
A page code will navigate the user to whatever page Guid is contained in the QR code. These codes begin with RK:PG:
and then contain a Guid to identify the page to be navigated to. You can also optionally include any query string parameters you wish.
Cards are an essential piece of UI that serve as an entry point to additional information. As you'll see they are very extensible and allow you to quickly achieve remarkable results.
There are three types of cards for you to choose from. While they share many of the same elements that each have a different design style.
The contained card is the classic design that keeps all of the content inside of a frame. There's plenty of options to adjust both the frame and content.
The block card is very similar to the Contained Card but the content is not in a clearly visible frame.
The Inline Card places the image behind the content and provides several options to create striking designs.
The block card is very similar to the Contained Card but the content is not in a clearly visible frame.
Inherits from StyledView > PancakeView
Property
Type
Description
AdditionalContent
object
The text or controls to add to the content of the card. If text is provided it will be converted to paragraphs based on line breaks.
BorderThickness
float
The thickness of the border.
BorderColor
Color
The color of the border.
Command
ICommand
The command to use when the card is clicked.
CommandParameter
object
The parameters to set to the command when clicked.
DescriptionLeft
object
The text or controls to place in the left description.
DescriptionRight
object
The text or controls to place in the right description.
Elevation
int
The Material Design elevation desired.
HasShadow
bool
Determines if a shadow should be shown behind the card.
Image
string
The URL of the image.
ImageLocation
VerticalAlignment
Determines where the image should be placed on the card. (Top, Bottom)
ImageMask
string
The URL or name of the image to use for the mask.
ImageMaskColor
Color
The color to use to tint the mask.
ImageMaskOpacity
double
The opacity to use on the mask.
ImageOpactity
double
The opacity of the image.
ImageRatio
string
Determines the size of the image based on the width of the parent container. The format is height:width with a default of 2.1:4.
ImageSaturation
double
The saturation of the image.
Tag
string
The text for the card's tag.
TagBackgroundColor
Color
The background color of the tag.
TagTextColor
Color
The text color of the tag.
Tagline
string
The text to display for the tag line.
TaglineJustification
HorizontalAlignment
The text alignment for the tagline. (Left, Right, Center)
Title
string
The text to display for the title.
TitleMaxLines
int
The maximum number of lines the title can be (default 2).
TitleJustification
HorizontalAlignment
The text alignment for the title (Left, Right, Center)
The contained card is the classic design that keeps all of the content inside of a frame. There's plenty of options to adjust both the frame and content.
Inherits from StyledView > PancakeView
Property
Type
Description
AdditionalContent
object
The text or controls to add to the content of the card. If text is provided it will be converted to paragraphs based on line breaks.
BorderThickness
float
The thickness of the border.
BorderColor
Color
The color of the border.
Command
ICommand
The command to use when the card is clicked.
CommandParameter
object
The parameters to set to the command when clicked.
DescriptionLeft
object
The text or controls to place in the left description.
DescriptionRight
object
The text or controls to place in the right description.
Elevation
int
The Material Design elevation desired.
HasShadow
bool
Determines if a shadow should be shown behind the card.
Image
string
The URL of the image.
ImageLocation
VerticalAlignment
Determines where the image should be placed on the card. (Top, Bottom)
ImageMask
string
The URL or name of the image to use for the mask.
ImageMaskColor
Color
The color to use to tint the mask.
ImageMaskOpacity
double
The opacity to use on the mask.
ImageOpactity
double
The opacity of the image.
ImageRatio
string
Determines the size of the image based on the width of the parent container. The format is height:width with a default of 2.1:4.
ImageSaturation
double
The saturation of the image.
Tag
string
The text for the card's tag.
TagBackgroundColor
Color
The background color of the tag.
TagTextColor
Color
The text color of the tag.
Tagline
string
The text to display for the tag line.
TaglineJustification
HorizontalAlignment
The text alignment for the tagline. (Left, Right, Center)
Title
string
The text to display for the title.
TitleMaxLines
int
The maximum number of lines the title can be (default 2).
TitleJustification
HorizontalAlignment
The text alignment for the title (Left, Right, Center)
The Inline Card places the image behind the content and provides several options to create striking designs.
Inherits from StyledView > PancakeView
Property
Type
Description
AdditionalContent
object
The text or controls to add to the content of the card. If text is provided it will be converted to paragraphs based on line breaks.
BackgroundMask
string
The URL or name of the image to use for the mask.
BackgroundMaskColor
double
The color to use to tint the mask.
BackgroundMaskOpacity
double
The opacity to use for the mask.
BorderThickness
float
The thickness of the border.
BorderColor
Color
The color of the border.
CardRatio
string
Determines the size of the image based on the width of the parent container. The format is height:width with a default of 4:3.
Command
ICommand
The command to use when the card is clicked.
CommandParameter
object
The parameters to set to the command when clicked.
DescriptionLeft
object
The text or controls to place in the left description.
DescriptionRight
object
The text or controls to place in the right description.
Elevation
int
The Material Design elevation desired.
HasShadow
bool
Determines if a shadow should be shown behind the card.
Image
string
The URL of the image.
ImageLocation
VerticalAlignment
Determines where the image should be placed on the card. (Top, Bottom)
ImageOpactity
double
The opacity of the image.
ImageSaturation
double
The saturation of the image.
Tag
string
The text for the card's tag.
TagBackgroundColor
Color
The background color of the tag.
TagTextColor
Color
The text color of the tag.
Tagline
string
The text to display for the tag line.
TaglineJustification
HorizontalAlignment
The text alignment for the tagline. (Left, Right, Center)
Title
string
The text to display for the title.
TitleMaxLines
int
The maximum number of lines the title can be (default 2).
TitleJustification
HorizontalAlignment
The text alignment for the title (Left, Right, Center)
Below is a diagram of the various elements that make up a card.
Transparent gradient images to overlay on images for a beautiful design.
The goal of any content strategy should be extensibility. In order to achieve rich designs, you need images that are crafted for each medium and use case. You probably don't want to spend time having to create different variations of each image though. To assist with that, we've designed a powerful masking system that can be used with images and cards, reducing the number of custom images needed in your mobile applications.
These image masks can be referenced directly within the Source
of an Image, or you can apply them automatically inside the card components. For Block Card and Contained Card, the mask is placed on the image, while the mask for Inline Card is placed over the entire card. This makes sense as the image on an Inline card takes up the full background.
Mask
This is the location of the mask image. You can either provided your own via a URL or take advantage of the masks that our built into the application (recommended)
ImageMask
CardMask
Opacity
The opacity of the mask.
ImageMaskOpactity
CardMaskOpacity
Color
The color to overlay the mask.
ImageMaskColor
CardMaskColor
While you can provide your own masks via a URL, you can save load time and bandwidth by using one of the built-in masks. These are highlighted below.
These masks give you several different options to start from. Using image transformations like Fill Color Flip, and Tint will provide additional customize to achieve your desired look. Learn more about Layering Images to design beautiful cards and graphics in your apps!
When applying masks to cards, you can also append -Flip
to the end of the mask name to flip the mask 180 degrees. For example, if you wanted a light fade flipped use Fade-Light-Flip
.
Fade-Thin
resource://Rock.Mobile.Resources.Masks.fade-thin.png
Fade-Light
resource://Rock.Mobile.Resources.Masks.fade-light.png
Fade-Medium
resource://Rock.Mobile.Resources.Masks.fade-medium.png
Fade-Dark
resource://Rock.Mobile.Resources.Masks.fade-dark.png
Midline
resource://Rock.Mobile.Resources.Masks.midline.png
Vignette
resource://Rock.Mobile.Resources.Masks.vignette.png
Top-Bottom
resource://Rock.Mobile.Resources.Masks.top-bottom.png
As you set out to design with masks, keep in mind that the best designs will be a recipe that incorporates the properties of the card, image, and mask. Take for example the design below. The effect of the card comes from the card's background, the effects on the image as well as the mask.
Below is a chart of the various CSS styles available to you to style.
Display a native context menu that can be attached to nearly any control.
A popular pattern in mobile development is attaching a native menu to a control that opens with a tap or long press. With Rock Mobile, this is not only easy to implement but also highly customizable!
To get started, we've introduced three controls:
Menu - The top-level menu, can be nested for submenus.
MenuAction - An action that can be taken from the menu (think of this as a Menu item).
MenuGroup - A group of Action
s or Menu
s. These cannot be nested.
Title
string
A string title to be displayed at the top of the menu.
iOS ✅ Android ❌
Title
string
The title of the action.
Command
ICommand
The command to execute when the action is selected.
CommandParameter
object
The parameter to pass along to the command.
Icon
ImageSource
An image icon to display with the menu action.
SystemIcon
string
The system icon to display with the menu icon. See the System Icons section for more info.
iOS ✅ Android ❌
IsEnabled
bool
Enables or disabled the menu action.
IsVisible
bool
Whether or not the action should currently display.
IsDestructive
bool
Whether or not this is a destructive menu item.
Title
string
The title of the group.
These are only really supported on iOS. These are in the form of SF Symbols, and you should be careful to ensure this only gets set on the iOS platform. You can see examples of this below.
Opens a Context Menu when the Border is held down.
In certain cases, you may want the Context Menu to open instantly without a long-press. For this to work properly, the Menu must be attached to a Button.
The Context Menu can sometimes interfere with a TapGestureRecognizer
or other command triggers. To avoid this, you can use the ClickCommand
and ClickCommandParameter
attached properties. This lets you define both the long-press context menu and tap functionality simultaneously!
Adding a countdown timer to your page is simple. There are several options for providing a date and time to the control.
Simply enter a raw date time value as a string.
See the Lava documentation for more information.
Utilize the scheduledcontent
Lava shortcode.
Note: This shortcode's logic does take some overhead. You may consider caching the output if your page will be heavily visited, even if it's only cached for a minute or two.
Property
Type
Description
StartDateTime
object
The date/time that the event starts can be provided as either a string or a date object.
ShowLabels
bool
Determines if the date unit labels below the values should be displayed. Default is to show.
AbbreviateLabels
bool
Determines if the labels values should be abbreviated (Minutes vs Mins). The default is to abbreviate.
SeparatorValue
string
The character to use to separate values. The default is ':'.
CompletedMessage
object
What to show at when the counter reaches 0. This can be either a string message or a view control. If no value is provided the counter will end at 00:00:00:00
.
The countdown timer will add specific CSS classes as it gets close to completion. These are outlined below.
CSS Class
Purpose
.less-than-day
Add when the countdown timer is less and a day from completion.
.less-than-hour
Added when there is less than 60 minutes on the timer.
.less-than-15-mins
Added when there is less than 15 minutes on the timer.
.less-than-5-mins
Added when there is less than 5 minutes left.
.countdown-complete
When the timer has reached 0.
While the countdown timer looks simple it's actually made up of a series of StackLayouts and Labels. This is to ensure that everything says aligned as the timer ticks. Below is a view of the various CSS classes available to you.
Note: Each unit of time is actually a .countdown-field though we only note it for clarity once above. Likewise each separator has the same classes.
The ins and outs of displaying and styling cover sheets
Cover sheets are a commonly patterned way to present information to a user that doesn't rely on changing the navigation stack.
Cover sheets cannot be opened within cover sheets. Some blocks utilize cover sheets to reveal content or forms, so be sure not to include these blocks in the navigation stack.
Currently, there is not a ton of Android functionality. It works similarly to a PushPage but has an animation that slides from bottom to top instead of from right to left.
If you set IsNavigationPage
to false, Android users won't have a way to close the cover sheet. You'll need a custom button that uses the CloseCoverSheet command.
Listed below are the options provided via the ShowCoverSheetCommandParameters
object.
PageGuid
Guid
The Guid of the page to display in the cover sheet. Use this instead of Content.
Content
View
The content to display inside of the cover sheet. Use this instead of PageGuid.
ModalPresentationStyle
ModalPresentationStyle
[iOS ONLY] The way that the sheet is presented. There are currently four accepted values: FormSheet
, PageSheet
, FullScreen
and OverFullScreen
. Defaults to FormSheet
.
IsNavigationPage
bool
Whether or not the page displayed should be converted into a page that has a toolbar with a dismiss button. Defaults to true.
SheetTitle
string
The title of the sheet, displays in the middle of the navigation bar.
DismissButtonText
string
The text to use in the dismiss button, seen in the toolbar (navigation bar) of the sheet. Defaults to Cancel.
ShowNavigationBar
bool
Whether or not this instance should show a navigation bar. IsNavigationPage
must be enabled. (defaults to false)
PrimaryActionButton
Button
The button to use as the primary action in the top right corner of cover sheets.
SecondaryActionButton
Button
The button to use as the secondary action in the top left corner of cover sheets.
You can style the Navigation Bar itself by targeting the cover-sheet
class. For example, if you want to change the background bar color, text color, and remove the FullScreen separator:
Setting -rock-ios-hide-navigation-bar-separator: true;
works on initial page loads, but changing the OS theme will reveal this separator on the current page.
To show a cover sheet that displays another page, pass in the PageGuid
as the CommandParameter
.
To show a cover sheet from provided XAML content, pass in the XAML content you want to render inside of the CommandParameter
.
Here is an extensive example with most of the ShowCoverSheetParameters
properties utilized.
To close any open cover sheet, use the CloseCoverSheet command.
Displays a separator line much like an HTML <hr> tag.
Inherits from BoxView
Thickness
string
The vertical thickness of the line. Valid values are:
Thick
- 2 units in height
Thicker
- 4 units in height
Thickest
- 8 units in height
If not specified, the default is 1 unit.
Inherits from Microsoft.Maui.Controls.ContentView
The expander allows you to display two stacked views. A header view and then a content view. When the Expander is collapsed, the content is hidden. When expanded, it's shown. And then when tapping on the header it will toggle the state of the Expander.
Before shell v6, animations were used to show and hide content. However, properties related to animations will no longer work in shell v6 and later.
Content
The content that will be displayed when expanded. This is the default property so it can be omitted when creating child elements.
ContentTemplate
This will also provide content to be displayed but it doesn't create the views until they are needed. If your expanded content is rather heavy you might consider using this to improve initial page load performance.
Header
The view that will make up the header of the expander. This is what will respond to tap events.
IsExpanded
bool
Allows you to set the initial state of the expander. Defaults to false.
ExpandAnimationLength
int
The duration of the expand animation in milliseconds. Defaults to 250.
CollapseAnimationLength
int
The duration of the collapse animation in milliseconds. Defaults to 250.
ExpandAnimationEasing
The easing function to use when performing the animation. Defaults to Linear.
CollapseAnimationEasing
The easing function to use when performing the animation. Defaults to Linear.
Value
Description
Down
Expands down below the header.
Up
Expands up above the header.
Left
Expands to the left of the header.
Right
Expands to the right of the header.
Inherits from Xamarin.Forms.Layout
You know those fancy input fields that have the nice labels, borders, required field markers, and all that? Well, the FieldContainer view handles all that fancy work for you.
A FieldContainer displays views that implement the IRockField interface. You can find all the views that implement this interface in the Form Fields section of the documentation. All of these views implement the required properties to get the title of the field as well as know if the field should be considered required.
The fields can be displayed in one of two ways. Either as individual fields or as grouped fields. An example of the grouped fields would be the login block. The username and password fields are displayed in a single grouping that contains both fields. While a good example of individual fields would be the workflow entry block, each field is displayed one at a time.
Usually, you will want to display fields individually, unless you have full control over the titles. The reason for this is that the titles take up much more space in a Grouped layout vs an Individual layout. So if you are, for example, displaying attributes in a Grouped layout, some of those attributes might have names consisting of 10-15 words, which will just look really odd in the Grouped layout.
Finally, on the layout, some fields require an Individual layout. One example of this is the Address field. It actually displays its components in a grouped stack already, so trying to force that inside another Grouped layout will result in a visual headache.
Property
Type
Description
Title
string
When in Grouped layout, this value provides the title that will be used above the entire group. If not set or set to an empty string, then no group title will be displayed.
Value
Description
Automatic
The container will examine its own contents and determine the best layout to use. If only a single field has been provided or if any of the fields require Individual layout, then Individual layout will be used. Otherwise Grouped layout will be used.
Individual
Each field will be displayed with a title above and then the field itself will be displayed full-width below.
Grouped
A single group title will be displayed above all the fields, then each field will be displayed with a title on the left and the field on the right in a sort of grid.
The above will render as a Grouped layout with a title for the entire group of Your Name
and then will display the individual fields for First Name
(which will be marked as required) and Last Name
in a single group below.
The above will render an Individual field (since there is only one). It will display the label Your Name
above and then have the text input box placed below it.
The above is very similar to our first example. But because we are specifically requesting Individual layout, you will first get the First Name
label with the related text input below it. Then slightly further down you will have the Last Name
label with the related text input below it.
Inherits from Xamarin.Forms.ContentView.
This is a simple view that allows you to have two views take up the same space on the page. You wire up whatever interaction you want to cause the view to flip from front to back and vice-versa. So you can wire it up to a tap on the view itself, or whatever else you want.
There are two ways to initiate a flip. You can bind the IsFlipped
property to a boolean value that will cause the view to flip when the value changes. This is probably not a common situation for you. Instead there is a FlipCommand
property that you can bind to an action to initiate the flip, as you will see in the example below.
Property
Type
Description
FrontView
View
The view content to display on the front side.
BackView
View
The view content to display on the back side.
IsFlipped
boolean
If true then the back view will be displayed, otherwise the front view will be displayed. Default is false.
IsHeightNormalized
boolean
If true then the flip view will always take the height of whichever view is taller and ensure it always takes up that much space. If false then when you flip views content below may shift up or down. Default is true.
Duration
boolean
The time in milliseconds that the transition between views will take. Default is 400.
FlipCommand
ICommand
You can bind an action to this property to initiate a flip.
Value
Description
Horizontal
The content is flipped horizontally.
Vertical
The content is flipped vertically.
The FlipCommand
is not a standard command, so as you can see we are actually using a named reference to the FlipView in our binding.
Inherits from Xamarin.Forms.Label
Wouldn't it be nice if your mobile users could follow a content channel item and then later view a list of all their followed items? This view displays one of two icons, depending on the current state. That initial state is determined by the IsFollowed
property. When the user taps on the icon, the state is toggled and an API call is made to the server to update the followed state of the entity.
This of course assumes that the user is currently logged in. If they are not logged in, then no action will be taken. You can show a message to them using NotLoggedInText
to encourage logging in.
EntityId
int
The Id number of the entity to be followed.
EntityTypeId
int
The Id number of the entity's type.
PurposeKey
string
The key to identify a custom purpose to the following. Defaults to null.
IsFollowed
bool
The current followed state of the entity. Defaults to false.
FontSize
double
The size of the font to use.
FollowingIconClass
string
The icon class to display when the entity is being followed. Defaults to star.
FollowingIconFamily
The icon family to use when the entity is not being followed. Defaults to FontAwesomeSolid.
FollowingText
string
The text to display to the right of the icon when the entity is being followed.
NotFollowingIconClass
string
The icon class to display when the entity is not being followed. Defaults to star.
NotFollowingIconFamily
The icon family to use when the entity is not being followed. Defaults to FontAwesomeRegular.
NotFollowingText
string
The text to display to the right of the icon when the entity is not being followed.
NotLoggedInText
string
The message that is displayed to the user when they try to follow an item while not logged in. Defaults to You must be logged in to follow this item..
This control uses two API endpoints on your Rock instance. One to start following an entity and one to stop following. By default, the security on these endpoints only allows Staff and Staff-Like or above roles access. If you want to allow others to be able to follow and unfollow things then you will need to adjust the security on these two endpoints.
You can make these changes under Rock > Admin Tools > Security > REST Controllers > Followings. The two endpoints you will need to grant access to are:
DELETE - api/Followings/{entityTypeId}/{entityId}?purposeKey={purposeKey}
POST - api/Followings/{entityTypeId}/{entityId}?purposeKey={purposeKey}
To allow all users to be able to follow and unfollow things you will need to add the All Authenticated Users
role to the Edit permission for both of those endpoints.
The example below demonstrates how to display a group's name and a following icon to let the user follow that group. We are using the default icons. The first screenshot shows the not followed state and the second screenshot shows the followed state.
Display content based on whether or not a person is within a geofence.
Inherits from Xamarin.Forms.ContentView
Don't let the words mislead you - creating a geofence isn't hard! All a geofence really is comprised of is a list of points (latitude and longitude) that connect at different areas.
You can provide any number of singular points with a PointRadius
to create perfect circle geo-fences around that point.
For example, take the point (31.7058, 35.2007)
(the latitude/longitude of Bethlehem) and supply it with a 2-kilometer PointRadius
.
Results in a 2km radius circle around Bethlehem:
You can provide multiple points (syntax) to create multiple geo-fences.
Points
string
Represents the coordinates or reference points within the geofence.
Fences
string
Defines the polygons or boundaries for geofencing.
PointRadius
int
If provided with a singular point, this amount of distance (in kilometers) will be applied to the point to create a geofence.
DisableLocationPermissionRequest
bool
Should you prefer not to have this request potentially seek permissions, you can deactivate the permission prompt. (defaults to false).
InBoundary
View
Content to display when the location is within the specified boundaries.
OutOfBoundary
View
Content to display when the location is outside the specified boundaries.
PermissionNotRequested
View
Content to display when the location permission has not been requested. Only shown if AlwaysRequestLocation is false.
NoPermission
View
Content to display when the location permission is not granted.
Error
View
Content to display in case of any error related to geofencing or location permissions.
GeolocationCheckInterval
int
The amount of time (in milliseconds) to wait in between re-checking the person's geolocation to see if they're within a fence. Defaults to 15000 (15 seconds).
ClosestGeoFence
string
The key of the closest geofence.
ClosestGeoFenceDistance
double
The distance(km) to the closest geo fence. Will be negative if you're inside of it.
Latitude and longitude should be comma delimited, while points are pipe |
delimited. For example:
31.7,35.2|33,36
This would result in two separate points. The first point is the latitude and the second point is the longitude.
When you're supplying the Points property, you can specify a key for each point that you want to recognize. That key of the closest geofence is stored in the ClosestGeoFence property.
To supply a key, simply prepend the point with Key=
.
FirstPoint=31.7,35.2|SecondPoint=33,36
Fences are comprised of points, and delimited by a caret ^
. For example, here is a singular geofence around the Cardinals stadium:
33.5281,-112.2645|33.5281,-112.2630|33.5270,-112.2630|33.5270,-112.2645
And now let's add one around the Phoenix Suns court:
33.5281,-112.2645|33.5281,-112.2630|33.5270,-112.2630|33.5270,-112.2645^ 33.4460,-112.0712|33.4460,-112.0697|33.4449,-112.0697|33.4449,-112.0712
When you're supplying the Fences property, you can specify a key for each point that you want to recognize. That key of the closest geofence is stored in the ClosestGeoFence property.
To supply a key, simply prepend the point with Key=
.
Cardinals=
33.5281,-112.2645|33.5281,-112.2630|33.5270,-112.2630|33.5270,-112.2645^
Suns=
33.4460,-112.0712|33.4460,-112.0697|33.4449,-112.0697|33.4449,-112.0712
Inherits from ContentView
This view enables HTML rendering on the page, though HTML support is limited in mobile applications and may impact performance. It's best to use HTML sparingly; you don’t need to avoid it altogether, but rendering numerous paragraphs may reduce responsiveness.
Since you’re defining HTML in an XML file, using Text="{{ Item.Html }}"
won’t work directly. You’ll need to escape the HTML text or apply the CDATA approach shown below. Alternatively, you can use the XamlWrap filter in Lava as well.
Text
string
The text content that contains the HTML.
Lava
bool
If true then the Text will be processed for any Lava before final rendering happens. Defaults to false.
FollowHyperlinks
bool
If true then any hyperlinks will be decorated with an underline and made tappable. When tapped they will open using the internal browser and must be absolute URLs. Defaults to false.
When enabling FollowHyperlinks, the text will be tappable on iOS, however there is a bug in Xamarin Forms (shell v5) that prevents the text from being styled with an underline.
Did you know that formatted content can also be shown with Markdown?
MarkdownA limited subset of HTML tags is supported. Any non-supported tags will be rendered as their plain text contents (meaning, the HTML tags are stripped).
h1
- h6
div
p
a
br
span
strong
b
em
i
code
pre
ol
ul
li
You can perform limited styling of rendered HTML content. This only operates at a block level and only with internal classes that are applied. This means you cannot specify your own CSS class in the HTML, nor can you target a specific inline element via CSS (such as a span
tag).
<p>
are rendered with the paragraph
class applied.
<div>
tags are rendered with the text
class applied.
<pre>
tags are rendered with the paragraph
class applied and are overridden to use a specific monospace font.
<img>
are rendered with the image
class applied.
Ordered and unordered lists are rendered in a container view. The container has either the ordered-list
or unordered-list
class applied. Individual list items are rendered with both the text
and list-item
classes applied.
The best way to style these elements would be with a custom StyleClass
applied like so:
Then in the custom CSS, target classes you want to change:
In general, styling should be kept to basics, such as margins and possibly colors or font selections. The HTML control elements may change in future versions, so avoid applying styles to specific elements unless you're prepared for potential breakage down the line.
Display from a variety of different icons.
Inherits from Xamarin.Forms.Label
We're used to having sleek icons on our web pages, and your mobile app should be no exception. Add icons from various libraries, ensuring your pages look polished and visually appealing.
Rock Mobile currently supports the following font families:
FontAwesome (default)
N/A
Automatically pick the first Font Awesome family that supports the requested icon in order of Regular, Solid and then Brands.
FontAwesomeSolid
FontAwesome5Free-Solid
The solid icons from Font Awesome free v5.11: https://fontawesome.com/v5/search?o=r&ic=free&s=solid
FontAwesomeRegular
FontAwesome5Free-Regular
The regular icons from Font Awesome free v5.11: https://fontawesome.com/v5/search?o=r&ic=free&s=regular
FontAwesomeBrands
FontAwesome5Brands-Regular
The brand icons from Font Awesome free v5.11: https://fontawesome.com/v5/search?ic=brands
MaterialDesignIcons
MaterialDesignIcons
Many of the Material Design icons: https://materialdesignicons.com/
IconClass
string
The icon class name to use. This can be found on the FontAwesome website. If it specified fas fa-car
then you would use car
.
FontSize
double
The size of the icon.
Command
ICommand
The command to be executed when the user taps on the icon.
CommandParameter
object
The object to be passed as the parameter to Command
.
Displays a Button with an Icon as the content.
Inherits from Button
Looking to use an icon instead of text on a button? This control is made just for that. While you can usually customize content using a Border
with a TapGestureRecognizer
, this control comes in handy when you need to attach a context menu—something you can’t do directly with a Border
.
IconClass
string
The icon to display.
IsActive
bool
Used to apply special styling when active (e.g., setting this to true
when a context menu opens).
IsActiveCssClass
string
The CSS class applied when IsActive
is true
.
InactiveCssClass
string
The CSS class applied when IsActive
is false
.
This example creates a circular IconButton
with a user icon, styled as an outlined primary button.
Inherits from Xamarin.Forms.ContentView
One of the most common controls you'll want to use is the Image control. Because of its importance, effort has been invested into ensuring that it has all the power you need. Let's start with the basics.
Is that it? No, we're just getting started. Below are all of the properties you can add to images.
Aspect
Aspect
Determines how the image will fill the space allotted. Valid values are:
AspectFill - Fill the space with the image, some parts of the image may be cropped.
AspectFit - Scale the image to fit the space, some parts of the space may be left empty.
Fill - Scale the image to exactly fill the space, this may warp the image.
BackgroudColor
Color
The color to use for the background. This is useful if you'd like to show a placeholder color while the image downloads.
Command
ICommand
The command to execute when the user taps on the image.
CommandParameter
object
The parameters to pass to the command when it's executed.
ErrorPlaceholder
string
The URL of the image to display if an error occurred trying to load the main image.
HeightRequest
int
The height you'd like your image to be.
WidthRequest
int
The width you'd like your image to be.
HorizontalOptions
This describes how the element is laid out horizontally within the parent , and how this element should consume leftover space on the X axis. Common values would be:
Center - centered and does not expand.
FillAndExpand - Fills the whole area.
LoadingPlaceholder
string
The URL of the image to use as a loading placeholder while the main image loads. This image will need to be loaded once and then due to caching it will be available to all Image tags.
Ratio
string
Determines the size of the image based on the width of the parent container. The format is height:width (e.g. '4:2').
Source
string
The URL of the image to be loaded and displayed.
VerticalOptions
This describes how the element is laid out vertically within the parent , and how this element should consume leftover space on the Y axis.
Margin
Thickness
Images, like most controls can have margins. This is typically note as Margin="Left,Top,Right,Bottom"
.
Done now? Nope, still have much more to consider.
You can apply several different transformations to your images. Each is discussed below.
You can easily add a blur to your image with this simple transformation.
Blurring is a very CPU-intensive operation. The higher the radius value the more intensive this becomes. Use caution to not over blur something dynamically when you can instead replace it with a statically blurred image. Android devices have been known to crash with radius values over 15 or so.
Radius
Float
The amount of blur to add.
The circle transformation masks your images into a circle shape. The syntax for this is below.
BorderSize
int
The size of the optional border around the image.
BorderColor
Color
The color of the border around the image.
The filter adds a customizable drop shadow to your images.
Distance
double
Determines how far the drop shadow should extend below the image.
Angle
double
Sets the direction the drop shadow should extend from.
Radius
double
Determines the level of blur the drop shadow should use.
Color
Color
The color of the drop shadow.
Opacity
double
The opacity of the shadow.
When using the drop shadow transformation be sure you do not have a background color. Otherwise, the background color will cover the drop shadow.
This fills the image with the selected color. Not sure why you'd ever use this? Well, there's a great usage for this when used with Masks on layered images.
Color
Color
The color to fill the image with.
Flips the image either horizontally, vertically, or both.
Direction
FlipDirection
Valid values include: Horizontal, Vertical or Both
Converts the image to grayscale.
Saturation
double
Determines this level of color saturation. A value of 1.0
will not change the original image. Using 0.0
will make the image fully gray scale. You can also provide -1.0
to invert the image.
Draws a reflection of the image as if the image were sitting on a glass surface.
Size
double
The size of the reflection.
Rounds the corners of the image and optionally adds a border.
CorderRadius
CornerRadius
You can provide a specific radius for each corner, or provide one value to be used for all of them.
BorderSize
float
The size of the border to optionally apply.
BorderColor
Color
The color of the border to apply.
Tints the image using the provided color.
Color
Color
The color to use to tint the mid-tones of the image.
Keep in mind you can use more than one transformation on a single image.
Now are we done? Not quite, what's the rush?
Want to go to the next level with your images? Layer them! Look at the sample below:
To make this, simply stack the original mountain under one of our built-in Masks. Note how the mask is just a PNG with an alpha channel. Notice how the mask is black. Applying a Fill Color transformation allows us to match the tint we added to the mountain photo producing a nice color vignette effect.
While HeightRequest can be used to size images, using Ratio is preferred.
Inherits from Xamarin.Forms.ContentView
Whenever you view a page in the mobile app, a page view interaction is automatically logged on the server. More specifically, they are queued up and sent to the server in bulk every minute or so. But sometimes you might want to record a custom interaction that the user had when viewing the page. Say for example, recording an interaction that they viewed a blog article. Yes, we know content channels have built-in functionality to do that now too. Why nitpick?
Anyway, this control takes up zero space and provides a simple way to record a custom interaction. You need to specify the Operation
, Summary
, ChannelId
and then one of either ComponentId
or ComponentName
. All other properties are optional.
ChannelId
int
The identifier of the channel where this interaction will be recorded. Must already exist.
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.
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.
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
.
Summary
string
The text that describes this event in a user friendly manner.
Display a highly performant list of views powered by JSON data and an item template.
Inherits from Sharpnado.CollectionView
At some point in your mobile development career... there will come a point in which you need to display a list of items, either horizontally or vertically. These items will all look the same and be powered from a singular data source (likely a Lava entity command).
Like most, your first attempt will likely look something like this:
And who knows, maybe that is enough to get the job done and call it a day... Or maybe it isn't.
You may realize pretty quickly that with a lot of items, the performance starts to deteriorate. Most layouts simply aren't built to handle that many items generated in the form of raw XAML. If you've been in the game a while, you may have experimented with CollectionView or CarouselView, which are performant alternatives. The ItemsCollection (this) control is a friendlier, viable and stable alternative to both of those controls.
This control requires an item height (or width). This plays a big factor with performance. If you need a list with differently sized items, take a look at one of the alternatives listed above.
ItemsSource
IEnumerable
The source of items for the collection view.
ItemTemplate
DataTemplate
Template for items within the collection view.
ItemHeight
double
Height of each item in the collection view.
ItemWidth
double
Width of each item in the collection view.
CollectionPadding
Thickness
Padding around the collection view.
ItemSpacing
int
Spacing between items in the collection view.
TapCommand
ICommand
Command triggered on tap.
ScrollBeganCommand
ICommand
Command triggered when scrolling begins.
ScrollEndedCommand
ICommand
Command triggered when scrolling ends.
ScrollingLeftCommand
ICommand
Command triggered when scrolling left.
ScrollingUpCommand
ICommand
Command triggered when scrolling up.
ScrollingRightCommand
ICommand
Command triggered when scrolling right.
ScrollingDownCommand
ICommand
Command triggered when scrolling down.
DisableScroll
bool
Disables scrolling within the collection view.
Horizontal
A horizontal layout.
Grid
A grid layout.
Carousel
A carousel layout.
Vertical
A vertical layout.
Let's get into the business... how can we display long lists (horizontally OR vertically) without killing performance and maintaining a smooth scroll experience? The answer can be achieved with four simple steps.
Define your data source as JSON
Bring your JSON into memory
Create a single item template
Set up your Items Collection container
Inherits from Xamarin.Forms.ContentView
The Login Status control displays an icon and message encouraging individuals to log in. After logging in, it will display their profile image, and tapping will provide the option to capture or upload a new photo.
Property
Type
Description
WelcomeMessage
string Lava
The welcome message that is displayed when a user is logged in. Defaults to Hello {{ CurrentPerson.FirstName }}!
LoginMessage
string Lava
The login message that is displayed if a user is not logged in. Defaults to Login.
EditProfileLabel
string Lava
The edit profile subtext that is displayed if a user is logged in. Defaults to Edit Profile.
LoginLabel
string Lava
The login subtext that is displayed if a user is not logged in. Defaults to Tap to Personalize.
NoProfileIcon
string
The no profile icon that is displayed if a user is logged in but has no profile photo. Defaults to resource://Rock.Mobile.Resources.profile-no-photo.png.
NotLoggedInIcon
string
The image that is displayed if no user is logged in. Defaults to resource://Rock.Mobile.Resources.person-no-photo-unknown.svg.
ProfilePageGuid
Guid
The profile page unique identifier that the user will be directed to when they tap on the Edit Profile text.
ImageSize
double
The width and height of the profile image to be displayed. Defaults to 80.
ImageBorderSize
double
The width of the profile image border to be displayed. Defaults to 0.
ImageBorderColor
The color to use when drawing the border around the profile image. Defaults to White.
TitleFontSize
double
The size of the font to use when rendering the Title text.
SubTitleFontSize
double
The size of the font to use when rendering the SubTitle text.
The popup window was replaced with the UpdatePersonProfilePhoto command. Although the command itself supports updating the photo for any individual, the LoginStatus control only changes the photo for the CurrentPerson
.
Users will have the option to take a new photo or select an existing one from their photo library. These options appear in a popup window that you can style using the CSS classes listed below.
Inherits from Xamarin.Forms.ContentView
The LoginStatus view is the one you would normally use in the Flyout shell. But what if you want to just present a small icon that indicates to the user if they are logged in or not? The LoginStatusPhoto view does just that. In fact, LoginStatus uses this view itself to present the user's photo.
A number of properties allow you to specify how the profile photo will be displayed, and what photos to use if no profile picture is available or if the user is not logged in. Another set of properties allow you to specify the commands to be executed when the user interacts with the profile picture.
Property
Type
Description
NotLoggedInPhotoSource
string
The image that is displayed if no user is logged in. Defaults to resource://Rock.Mobile.Resources.icon-person-not-logged-in.svg.
NotLoggedInPhotoFillColor
Provides a way to quickly change the color of the entire image when drawing the "not logged in" image.
LoggedInNoPhotoSource
string
The no profile icon that is displayed if a user is logged in but has no profile photo. Defaults to resource://Rock.Mobile.Resources.icon-person-no-photo.png.
LoggedInNoPhotoFillColor
Provides a way to quickly change the color of the entire image when drawing the "logged in but no profile photo" image.
ProfilePhotoStrokeWidth
double
The width of the profile image border to be displayed. Defaults to 0.
ProfilePhotoCircle
boolean
If true, then the logged in profile photo image will be drawn with the Circle transformation applied. Defaults to false.
NotLoggedInCommand
ICommand
The command to be executed when the user interacts with the photo when they are not logged in.
NotLoggedInCommandParameter
object
The parameter to be passed to the NotLoggedInCommand
.
LoggedInCommand
ICommand
The command to be executed when the user interacts with the photo when they are logged in.
LoggedInCommandParameter
object
The parameter to be passed to the LoggedInCommand
.
A component that seamlessly displays engaging animations to enhance your mobile app's user experience.
Lottie files are JSON-based animations. These files are lightweight, scalable, and can be rendered natively on mobile and web platforms, allowing for high-quality animations with minimal performance impact. Lottie animations can include complex animations and interactivity, making them an excellent choice for adding visual flair to your applications.
Source
Source
The source of the lottie file.
Progress
TimeSpan
The current playback progress of the animation.
RepeatCount
int
The number of times to repeat the animation. Default is 0 (no repeat). A negative (-1) value will repeat forever.
IsAnimationEnabled
bool
Determines whether the control will play the animation provided.
AnimationCompletedCommand
Command
A command that executes once the animation has completed.
AnimationCompletedCommandParameter
object
The parameter to pass to the animation completed command.
Restart
Restarts the animation from the beginning.
Reverse
Reverses the animation from the end back to the beginning.
Inherits from Xamarin.Forms.ContentView
Another way that information is often styled in Rock is with something called Markdown. This syntax allows you to indicate that you want things formatted in a certain fashion, but it does not give you the ability to specify exactly how that formatting is done. For example, you can specify that you want a heading, but you don't get to pick exactly how that heading is formatted.
Not everything in the Markdown syntax is supported, for example, tables and footnotes. But most of the basic syntax is supported. As with the HTML component, you will probably want to wrap your content in a CDATA
tag.
When converting the markdown to XAML the Markdown control will add StyleClasses for you. Headings will get .heading1-.heading6
, paragraphs will be assigned the .text
class and links will be assigned the .link
CSS class.
Note: Links are only clickable at a leaf block level (formatted strings don't support span user interactions). If a leaf block contains more than one link, the user is prompted. This is almost a feature since the text may be too small to be precise enough!
Text
string
The markdown text to be displayed.
Lava
bool
If true then the Text will be processed for any Lava before final rendering happens. Defaults to false.
Headings
Bold
Italic
Unordered List
Ordered List
Inline Code
Code Fence
``` Sample code here ```
Links
Image
Stream content directly into your Rock Mobile application, with a ton of rich features built in.
Inherits from Maui.CommunityToolkit.MediaElement
Title
string
The title of the media being played.
Subtitle
string
The subtitle of the media being played.
IsCastEnabled
bool
Indicates if casting to external devices is enabled.
ThumbnailSource
string
The source of the thumbnail image.
WatchMap
WatchMapParameters
Parameters for watching the media with mapped data.
PlaybackCompletedCommand
ICommand
Command executed when media playback is completed.
PlaybackCompletedCommandParameter
object
Parameter for the playback completed command.
ThumbnailPosition
double?
The position of the thumbnail in the media timeline.
PlayButtonSource
string
The source of the play button image.
InitialAspectRatio
string
The initial aspect ratio of the media player.
ShowThumbnail
bool
Indicates whether the thumbnail should be shown.
AllowsPictureInPicturePlayback
bool
Only relevant on iOS. A flag indicating whether or not Picture in Picture is enabled for the player. Defaults to true.
Property
Type
Description
SaveChanges
bool
If true then changes to the watch map will be saved to the server if possible. Defaults to true.
WatchMap
string
A special run length encoded representation of the watch map that was previously saved. Defaults to null.
InteractionGuid
Guid?
The unique identifier of an existing Interaction to be updated. If the interaction cannot be found or does not match this video then a new interaction will be created. Defaults to null.
MediaElementGuid
Guid?
The unique identifier of the MediaElement that is being watched. This value is required to save changes. Defaults to null.
RelatedEntityTypeId
int?
An optional value to store in the interaction's RelatedEntityTypeId property. Defaults to null.
RelatedEntityId
int?
An optional value to store in the interaction's RelatedEntityId property. Defaults to null.
These properties are inherited from the control we built on top of. You can view a full list of the supported properties here, although we've trimmed down this documentation to only have the ones of interest.
ShouldAutoPlay
bool
Indicates whether media playback will begin automatically when the Source
property is set. This is a bindable property.
false
ShouldLoopPlayback
bool
Describes whether the currently loaded media source should resume playback from the start after reaching its end. This is a bindable property.
false
ShouldKeepScreenOn
bool
Determines whether the device screen should stay on during media playback. This is a bindable property.
false
ShouldMute
bool
Determines whether the audio is currently muted. This is a bindable property.
false
ShouldShowPlaybackControls
bool
Determines whether the platforms playback controls are displayed. This is a bindable property. Note that on iOS and Windows the controls are only shown for a brief period after interacting with the screen. There is no way of keeping the controls visible at all times.
true
Source
string
The source of the media loaded into the control.
The source of the media loaded into the control.
Speed
double
Determines the playback speed of the media. This is a bindable property
1
This second example shows how to configure the MediaPlayer to save the watch interaction when watching a media element video.
The documentation for the Media Player before Rock Mobile version 6 (.NET MAUI).
Inherits from Xamarin.Forms.ContentView
While there are commands that will allow you to start playback of an audio or video file in full-screen mode, usually you want that video embedded on the page. For example, on your message library pages, you might want to display the sermon title, then the video in-line, and then the description of that sermon. This view will allow you to have a video embedded into a page. The video itself can be set to auto-play (use sparingly) or to wait for the user to instruct it to play.
If a video is not set to AutoPlay
then a thumbnail will be displayed. If you specify a ThumbnailSource
for the view, then that image will be used as the thumbnail. Otherwise, the view will attempt to generate a thumbnail by inspecting the stream and using the ThumbnailPosition
property value as the offset into the video to capture a thumbnail. Due to limitations in both iOS and Android, auto-thumbnail generation only works on MP4/M4V files. It will not work on HLS streams (usually having an m3u8
extension).
HLS (.m3u8) streams from the service Resi are not supported on Android due to an issue on their end. If you need support for this, you'll need to utilize another streaming service.
Property
Type
Description
Source
string
The URL to be loaded into the video player. Supports MP4 and HLS.
ThumbnailSource
string
The URL to be loaded as the thumbnail. Overrides any automatic thumbnail generation.
PlayButtonSource
string
The URL to be loaded as the play button if AutoPlay is false
. This image can be any size but we recommend 128x128. It will be displayed inside a 64x64 box, but will maintain aspect ratio. Defaults to resource://Rock.Mobile.Resources.PlayButton.png.
AutoPlay
bool
If true
then the video will start playing as soon as it has loaded into the player. Defaults to false
.
InitialAspectRatio
string
The initial aspect ratio to use until the video has loaded and we know the actual aspect ratio. Can be specified as either a width:height
ratio (example 16:9
) or as a decimal number (example 1.77777
). Defaults to 16:9.
ThumbnailPosition
double?
The position into the video to use to generate a thumbnail automatically if no ThumbnailSource is specified. Value is specified in seconds. Defaults to 2
Title
string
The text to display in the title position of the screen controls. This overrides any data found in the media metadata.
Subtitle
string
The text to display in the subtitle position of the screen controls. This overrides any data found in the media metadata.
OverlayContent
The view tree to display as an overlay on top of the media. Defaults to a standard view that displays album artwork for audio files only.
ControlsContent
The view tree to be used as the on-screen controls. Defaults to the standard screen controls you normally see.
PlaybackCompletedCommandParameter
object
The parameter to pass to the PlaybackCompletedCommand.
WatchMap
Enables the Watch Map feature in the media player that allows saving playback position to the server and resuming a previous session. Defaults to null.
Property
Type
Description
SaveChanges
bool
If true then changes to the watch map will be saved to the server if possible. Defaults to true.
WatchMap
string
A special run length encoded representation of the watch map that was previously saved. Defaults to null.
InteractionGuid
Guid?
The unique identifier of an existing Interaction to be updated. If the interaction cannot be found or does not match this video then a new interaction will be created. Defaults to null.
MediaElementGuid
Guid?
The unique identifier of the MediaElement that is being watched. This value is required to save changes. Defaults to null.
RelatedEntityTypeId
int?
An optional value to store in the interaction's RelatedEntityTypeId property. Defaults to null.
RelatedEntityId
int?
An optional value to store in the interaction's RelatedEntityId property. Defaults to null.
This second example shows how to configure the MediaPlayer to save the watch interaction when watching a media element video.
The MediaPlayer doesn't have a way to toggle captions on or off, but iOS users can take advantage of the Closed Captions + SDH option that will show them. This is currently found under Settings > Accessibility > Subtitles & Captioning. Some video hosts like Vimeo can auto-generate captions.
For more information, check out Apple's official documentation:
Inherits from Xamarin.Forms.Frame
It happens. Something goes wrong and you need to display an error message to the user. Or perhaps something goes right and you want to be sure the user has feedback that everything is taken care of. Either way, you need a nice way to display a message on the page that has some nice colorful visual indicators.
The NotificationBox allows you to display a color-coded notification on the page. The notification will be colored to match the type of notification and contain the text you specify. You can also include an optional header text to stand out even more.
Property
Type
Description
Text
string
The text to be displayed as the message of the notification.
HeaderText
string
An optional bit of text that can be used to give the user context about the message.
Information
Success
Validation
Warning
Error
Primary
Secondary
Dark
Light
Inherits from Xamarin.Forms.StackLayout
Using a normal Label for text works great, but if you have several paragraphs worth of text it won't have the best typography. Correctly styled text should have a good amount of spacing between paragraphs. This helps individuals to read the content quicker. Using a single Label will give you the proper line returns, but it won't have the best spacing.
The ParagraphText control allows you provide a text string that contains several paragraphs worth of content. It will parse this and ensure each paragraph gets its own Label. These labels will have a CSS style class of body
applied to them. It's this class that applies the correct amount of margin below the Label. You can also override this class to provide a different-sized text/margin.
Property
Type
Description
Text
string
The text to show. This can also be provided via the content of the tag.
LabelCssClass
string
A string of the CSS classes to apply to each Label that represents a paragraph. If no value is applied each paragraph will have a body
class added to it.
Ever wish you could display a QR Code in your application based on something generated on the server? Okay maybe this isn't a common thing just yet, but we think QR Codes will become a great way to pass information without having to make direct contact.
QR Codes allow you to store lots of information. But the more information you store, the more complex they become. The more complex they become the more difficult they are to scan. That isn't to say you can't scan them, but think of it like the old Where's Waldo books. Imagine you had two Waldo pages. One page had Waldo standing all by himself in an open field. It only takes a quick glance to know where he is. Now imagine your standard "complex" Waldo page. It's not hard to find him because he is obscured and barely visible, it's just because there is a lot of clutter that looks similar around him.
The same is true of QR Code complexity. A simple code can be scanned without trouble. A complex code might take a bit more finesse on the scanner to get things lined up properly. So the moral of the Waldo story is test your codes. It isn't just the complexity, but the size and color choices also play a role. So test your code at the "most complex" it could be and verify it will scan easily. Otherwise you might need to adjust size and color (assuming you can't make it less complex) so it's easier to scan.
Property
Type
Description
BackgroundColor
Color
The background color behind the QR Code. By default this is transparent so whatever background color your page is will be used.
Color
Color
The color of the foreground blocks in the QR Code. Defaults to Black.
Content
string
The actual content to be encoded into the QR Code.
ECC Level or Error Correcting Code Level, defines how much of the QR Code can be damaged before it can no longer be scanned. A higher ECC Level means a more complex image, so you shouldn't plan on just using the highest ECC Level and calling it a day. Since we are displaying on a screen, the chance of damage is near zero (unless your finger is in the way).
Value
Description
L
Allows for up to 7% damage.
M
Allows for up to 15% damage.
Q
Allows for up to 25% damage.
H
Allows for up to 30% damage.
In this example, we are assuming the user is logged in and that we are processing Lava on the server. This would generate a QR Code on screen whose scanned content would contain the person's unique identifier. Later, you could use this with another application to scan the QR Code and know who the person is. Another option would be to encode something like the Guid value of an Event Registration Registrant. Then when scanned you could display the details of their registration.
Constrain a view to a certain ratio.
Inherits from Xamarin.Forms.ContentView.
This is a simple view that allows you to constrain the size to a certain ratio.
Ratio
string
The ratio to constrain the view to (ex: "16:9").
Inherits from Xamarin.Forms.View
While technically a View, this control does not actually render any content. Instead, it is used as a way for you to redirect the user to another page. This works similarly to the ReplacePage
command. The primary difference is that the Redirect
view does not require user interaction. This allows you to simply put the Redirect
view in your XAML and the user is automatically redirected to the target page before the current page content is ever displayed.
If the Redirect
view is encountered before the page is fully rendered then the redirect happens after the page has finished initializing but before the page is displayed. On the other hand, if it is encountered after the page is fully rendered then the redirect happens immediately.
Property
Type
Description
PageGuid
Guid
The page identifier that the user will be redirected to.
QueryString
string
An optional set of query string parameters that will be passed to the page. Note: This value must be XML escaped for the XAML to be parsed properly.
Inherits from Xamarin.Forms.StackLayout
Let's just get the obvious out of the way - you are probably reading the wrong page. We imagine you meant to be reading the ResponsiveLayout page instead. Unless you are just looking for the API reference all the juicy details are over there.
Property
Type
Description
ExtraSmall
int?
The number of column segments that this column occupies on extra small devices. Defaults to null.
Small
int?
The number of column segments that this column occupies on small devices. Defaults to null.
Medium
int?
The number of column segments that this column occupies on medium devices. Defaults to null.
Large
int?
The number of column segments that this column occupies on large devices. Defaults to null.
ExtraLarge
int?
The number of column segments that this column occupies on extra large devices. Defaults to null.
ExtraSmallOrder
int?
Overrides the default ordering of columns on extra small devices. Defaults to null.
SmallOrder
int?
Overrides the default ordering of columns on small devices. Defaults to null.
MediumOrder
int?
Overrides the default ordering of columns on medium devices. Defaults to null.
LargeOrder
int?
Overrides the default ordering of columns on large devices. Defaults to null.
ExtraLargeOrder
int?
Overrides the default ordering of columns on extra large devices. Defaults to null.
Spacing
double
Specifies the amount of spacing between child views (inherited from StackLayout). Defaults to 10.
Inherits from Xamarin.Forms.Layout<T>
If you are familiar with Bootstrap's responsive grid system, this will be familiar to you. The ResponsiveLayout allows you to quickly build a layout that will be responsive to the size of the device that is currently being used to view the content. Smaller devices can display data in a vertical layout while larger devices can display the same content with multiple columns of content. It even works when rotating tablets to orientations.
The ResponsiveLayout takes any View as a child, but you would normally use the ResponsiveColumn as the direct child views. The ResponsiveColumn view provides additional properties that let you specify the various settings to indicate the width of a column on various device sizes. See the advanced section below for how to do the same with any generic view.
A row is identified as the child views required to "fill up" the number of available columns (by default, 12). And a single layout can contain multiple rows. Meaning, you don't need to add up 12 columns and then close the layout and start a new layout, you can just keep going. So if you use the default configuration of 12 available columns and have 4 total sub-views, each one set to use 6 columns on a Medium device, then that will end up laying out a 2x2 grid on a medium device or 4x1 (4 rows, 1 column) grid on a small and extra small device.
Speaking of device sizes, we define a number of them for you to use. These are known as the breakpoints. The width of the entire device is used in the calculation of which break-point to use. Below we use the term pixel, but be aware this is the "normalized" pixel. For example, your average Retina iPad actually has 2,048 pixels in landscape, but it reports to the application as 1,024.
Extra Small: Devices < 576px wide (phones in portrait mode)
Small: Devices >= 576px and < 720px wide (most phones in landscape, some small tablets in portrait)
Medium: Devices >= 720px and < 992px wide (a few larger phones in landscape, most tablets in portrait)
Large: Devices >= 992px and < 1200px wide (most tablets in landscape)
Extra Large: Devices >= 1200px wide (some larger tablets in landscape, such as the iPad Pro)
Now, if we assume that you want something to display as a single column on Extra Small and Small devices, but two columns on Medium devices and above, you would only need to specify Medium to be a value of 6. The layout will determine the current break-point that should be used and then check if you have specified a column count. If not it will move down to the next smaller break-point size and repeat the process until finds a specified column count. If a column count is never specified, it is assumed to use the full-width of the layout. So in this example, Extra Small and Small devices would end up using 12 column segments (one display column) and Medium, Large and Extra Large devices would use 6 column segments (two display columns).
Each ResponsiveColumn can not only specify how many column segments it will take up at various device sizes, it can also optionally specify in what order that column is displayed. If you don't specify an order, then the order you defined the columns is used. But this lets you, for example, specify one order to be used for small devices and a different ordering used for medium and larger devices.
Property
Type
Description
ColumnCount
int
The column count for this layout. This allows you to override the normal layout calculations and use a custom number of columns to make up an entire row. Defaults to 12.
ColumnSpacing
double
The amount of space between columns when they are laid out side by side. This lets you have multiple columns of text (or other content) in a larger device and ensure there is some margin between them so it doesn't appear to be one giant block of text. But when translated to a smaller device so a single column shows up, that margin goes away. Defaults to 6.0.
RowSpacing
double
The amount of space in between rows when they are laid out. Defaults to 6.0.
The above code block is a simple example of a responsive layout that will place two images side-by-side on all device sizes using a 2-column layout.
So the above is going to declare 3 total layout options. Let's cover each in turn.
Extra Small: On the smallest device, we will get two rows, each a single column wide. The first row will contain our "navigation menu". Even though it is declared second, we are overriding the order on the extra small devices so that it appears first. Then below that will come our "body content". Since we didn't specify an ExtraSmall column count (and there is nothing smaller to check instead) it defaults to the full-width of the layout.
Small: Next, on the small devices we will get one row of two columns. The left column will contain our "body content" and the right column will contain our "navigation menu". The width of the left column will be roughly 58% and the right column would be roughly 42%. On a small device, we need to give the menu a bit more room after all.
Medium: Finally, on medium and larger devices the layout will be the same, one row of two columns. The "body content" will again be on the left and the "navigation content" will be on the right. This time, because we have more room, we specified that the left column should be 75% wide and the right column only 25% wide.
The ResponsiveColumn inherits from a StackLayout, which means you can put multiple views inside the column without having to add your own StackLayout first. While there is nothing wrong with doing it this way even if you only need to specify a single view, performing layout calculations takes time. So if by chance you were using this to display a few dozen columns that each contained a single view, we are processing layout calculations on a few dozen StackLayouts that we don't need to.
You can achieve exactly the same results as our above example by using special attached properties. These are far more verbose, but you can shave some CPU cycles off the rendering of your page. Again, this is really only a concern if you are using dozens of these things.
As you can see, that is indeed far more verbose so it isn't recommended unless you have a lot of these defined on a page and that page has some slowness in rendering. Places you might use this method are things like the Event Calendar page if you were using a responsive layout to define the layout of the individual calendar items in the list. That list might end up containing over a hundred items and that is a lot of CPU cycles to calculate layout that are wasted.
This layout offers a couple of unique style classes to help ease customization.
Inherits from Xamarin.Forms.ScrollView
There are certain things on a ScrollView that you wish to customize further than what the default properties allow. This functions the same as a default ScrollView, with additional properties.
We encourage you to read and understand the built-in ScrollView first: https://learn.microsoft.com/en-us/xamarin/xamarin-forms/user-interface/layouts/scrollview
IsBounceEnabled
bool
On iOS, ScrollViews natively have a "bounce" that lets an individual scroll past the content, and then bounces it back. This property is a boolean offering a way to disable that native behavior. Defaults to True
Inherits from Xamarin.Forms.ContentView
Think of the Segment Picker as somewhere between a single select field and a set of tabs. Basically, it displays a single horizontal bar with each option making up a segment of the bar. Visually, as the user selects different segments, the control updates to put a border around that segment.
Because the control displays a single row of items, care should be taken to ensure you don't provide too many items or items with names that are too long. Especially on phones which have very limited width.
Property
Type
Description
Options
List<PickerItem>
A collection of PickerItems which provide the values to be displayed inside the Segment Picker. This is also the default content property so PickerItems can be specified as direct child elements.
SegmentSelectedCommand
ICommand
The command to be executed when the user selects one of the segments. The parameter will be the value of the SelectedValue property.
SelectedIndex
int
The integer index of the selected segment. Defaults to 0.
SelectedTextColor
Color
The color to use for the text of the selected segment. This should be paired with the TintColor to ensure that the selected item is easily readable. Defaults to White.
SelectedValue
string
The value, as provided by the PickerItem, of the currently selected segment. This property is read-only.
TintColor
Color
The color to use when tinting various parts of the control. Defaults to the primary app color.
You can target special CSS properties to style certain aspects of the picker.
-rock-tint-color
Color
Sets the tint color of the unselected segments.
-rock-selected-tint-color
Color
Sets the tint color of the selected segment.
Inherits from Border
With the release of Shell v6 and the transition to .NET MAUI, the commonly used Frame
control was deprecated. This was an intentional move, as it has been replaced by the more performant and feature-rich Border control.
However, one key limitation of Border
is its lack of CSS support. To address this, StyledBorder was introduced—offering CSS compatibility while retaining all the benefits of the new Border
control.
For general usage and additional features, refer to the official Microsoft Border documentation.
The following CSS classes are available for use with this control:
border-radius
CornerRadius
Sets the corner radius of the frame.
border-width
double
Defines the width of the border stroke.
border-color
Color
Specifies the color of the border stroke.
Inherits from Border
Have you ever wished you could make your layouts do... more? A little more pizzazz, a little more wow factor, a little more... style. This view lets you do just that. Most of its functionality centers on borders and what you can do with them. However, it's not just about adding a border. Because you can do that now. The power comes when you apply things like corner radius to individual corners, add gradients to your border color, gradient background colors, and much more.
Property
Type
Description
BackgroundGradientAngle
int
A value between 0-360 to define the angle of the background gradient.
BackgroundGradientStops
A list of GradientStop objects that define a multi color background gradient.
BorderGradientAngle
int
A value between 0-360 to define the angle of the border gradient.
BorderGradientStops
A list of GradientStop objects that define a multi color border gradient.
BorderIsDashed
boolean
Whether or not the border needs to be dashed.
BorderThickness
float
The thickness of the border.
CornerRadius
CornerRadius
The radius of each of the four corners. Specified as "topLeft,topRight,bottomLeft,bottomRight".
HasShadow
bool
Whether or not to draw a shadow beneath the control. Note: For this to work we need to clip the view. This means that individual corner radii will be lost. In this case the TopLeft value will be used for all corners.
Elevation
int
The Material Design elevation desired. Note: For this to work we need to clip the view. This means that individual corner radii will be lost. In this case the TopLeft value will be used for all corners.
OffsetAngle
double
The rotation of the StyledView when Sides
is not its default value of 4.
Sides
int
The number of sides to the shape. Default is 4.
Property
Type
Description
Offset
float
Value between 0 and 1 that specifies the stop point offset.
This can be applied to more than StyledViews: https://docs.microsoft.com/en-us/xamarin/xamarin-forms/user-interface/brushes/lineargradient
Inherits from RockMobile.StyledView
Tags are pill-shaped labels that help to mark and categorize content. They usually consist of relevant keywords which make it easier to find and browse the corresponding piece of content. These are not directly correlated with Rock Tags.
Text
string
The text to display on the tag.
Type
string
The type (color) of the tag. Primary, Secondary, Success, Info, Warning Danger
Size
string
The size of tag to display. Small, Default, Large
TextColor
Color
Sets text color using any of the supported formats.
BackgroundColor
Color
Sets background color using any of the supported formats.
BorderColor
Color
Sets border color using any of the supported formats.
BorderThickness
Double
Sets the thickness of the border. This can be a single value or a specific value for Left, Top, Right, Bottom.
When styling tags via CSS, it's helpful to understand how this control is built. The Tag contains two underlying controls:
Styled View – This is the container control
Label – This is the text for the tag
All tags have a .tag
class attached to them.
If you add a type an additional class with the pattern of .tag-[typename]
will be applied.
Each size (Small, Default, & Large) will have .tag-sm
, .tag-default
, and .tag-lg
appended.
To style the text of a tag you'd want to have a style similar to:
Inherits from Xamarin.Forms.ContentView
Think of a Toggle Button as a fancy check box. It provides the same basic functionality, an on/off toggle. But it presents it as a large button. An icon is used to indicate state, but the visual state of the button also updates to reflect the state. This makes it very obvious to the user when looking at a list of items which ones are turned on and which are turned off.
The construction of a toggle button is made up of multiple controls. A Frame contains the entire button. Inside of that is an Icon and Label which display the contents of the button.
toggle-button
Always on the Frame. Can be used to style border and background color for the button.
icon
Always on the Icon that shows either the check-circle icon or the circle icon depending on state.
title
Always on the Label that contains the text of the button.
checked
This will be applied to the Frame when the button is in the checked state and it will be removed when the button is no longer in the checked state.
IsChecked
bool
If true
then the button is considered to be in the checked state.
Text
string
The text to be displayed inside the button next to the icon.
Command
ICommand
Can be used to trigger a command each time the state of the button changes.
CommandParameter
object
Contains the parameter to be passed to the Command.
Inherits from WebView
Embeds a web page into your mobile app page. This control wraps the standard WebView and should generally be used instead of the .NET MAUI one. It adds an initial Activity Indicator that will be visible until the web page actually loads. Otherwise, someone might see a blank area for a few seconds before anything appears.
WebView content is completely contained and cannot affect the app shell or native page. For example, an action within a WebView cannot initiate a native navigation command.
To ensure that the web page displays with the proper scale within the application, add the following meta tag to the <head> of the page.
Note that the WebView control must not be embedded within a ScrollView; otherwise, the content will be clipped. You do not need to define the HeightRequest
and WidthRequest
properties when using the Rock Mobile version.
Source
string
The initial URL to be used when the WebView first loads.
Allows a command to be executed upon initialization (and repeated).
Inherits from Microsoft.Maui.Controls.ContentView
The ExecuteCommand
control is a simple and flexible way to execute commands with customizable timing and repetition. It’s ideal for use cases like delayed actions or periodic updates.
Delay
int
The delay interval (in milliseconds) before the command executes.
Repeat
bool
Indicates if the command should repeat. Repeat indefinitely if RepeatCount
is not specified.
RepeatCount
int
The number of times the command repeats. Use -1
for unlimited.
StartWithExecution
bool
If true
, the command executes immediately before starting the delay timer.
Command
ICommand
The command to execute.
CommandParameter
object
A parameter passed to the command when executed.
In this example we used in an app to welcome people with a periodic toast message like, "Welcome to Rock Solid Church!!".
Command: Bound to the ShowToast
command, which handles the logic for displaying the message.
CommandParameter: Passes the string "Welcome to Rock Solid Church!!"
as a parameter to the command.
Delay: Specifies a 3-second delay (3000 ms) before executing the command.
Repeat: Ensures the command executes repeatedly execute (Repeat indefinitely if the RepeatCount
is not specified).
Inherits from Xamarin.Forms.Label
This control provides a simple UI interface to allow the user to pick a book and chapter from the Bible. This would normally be used with one of the Bible content controls to then display the text from the reference.
Property
Type
Description
Reference
string
The reference text based on the selections the user made.
CommandParameter
object
The parameter to be passed to the Command.
While this control itself does not have any styling properties that can be set, you can use CSS to style the modal pages that appear to handle user selection.
The book page will have the class bible-book-picker
applied to it. You can use the following CSS properties to customize how the text appears.
CSS Property
Description
font-family
The custom font to use for the text.
font-size
The font size to display the book name and chevron-right icon.
font-style
The font attribute style to use when rendering the book name.
color
The text color for the book name and chevron.
The chapter page will have the class bible-chapter-picker
applied to it. It does not have any styles directly on itself, but the content elements look roughly like this:
You can style those views as you normally would.
The UI for the Bible Book And Chapter Picker may change in future versions which may break your custom styling. If you are doing anything beyond just setting font size and color be sure to test your styles when and if the UI does change.
Provide a command as a parameter for something else.
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.
In this became the default content property, so you can specify the parameter as a direct child node.
Examples
Inherits from Xamarin.Forms.Layout
This view cannot be accessed directly from XAML. The FieldStack is used internally by the FormContainer to display multiple fields in a vertical layout.
When displaying a FormField this view is responsible for drawing the border around the group of fields as well as the lines between the fields.
Property
Type
Description
BorderColor
The color to be used for the border as well as the inter-field lines. Default value is #c1c1c1.
BorderWidth
double
The width, in pixels, to be used when drawing the borders. Default value is 1.
CornerRadius
double
The radius to use when drawing the four corners of the outside border.
Inherits from Xamarin.Forms.View.
Functionally, this control behaves just like a Slider. However, the Slider has a few quirks that make it unsuitable for use with tracking progress of a media player. Visually this renders a track bar as well as a thumb that shows the current position of playback. It can also be used by the person to scrub through the media by moving the thumb along the track.
Property
Type
Description
Position
double
The current position of the playback in fractional seconds.
Duration
double
The total length of the media being played in fractional seconds.
ThumbSize
double
The diameter of the drawn thumb on the play track. Defaults to 12.
TrackBackgroundColor
The color of the track background for the region that has not been played. Defaults to 50% gray at 65% opacity.
TrackProgressColor
The color of the track background for the played region. Defaults to the application's primary color.
The parameter control is not actually a visual control. However, you will see it used by various other controls, such as the Picker. Additionally, nearly all commands use the Parameter control to let you pass information to the command handler.
One of the things that makes this such a powerful element is that it supports binding. Both the Name
and Value
properties can be bound to another element. For example, you can bind the Value
property to a text input field that the user fills in and then pass that data back to your block on the server.
Property
Type
Description
Name
string
The name of the parameter. This can be either the displayed name or the name used, for example, in a query string parameter key.
Value
object
The value to be associated with the name.
In the above example, we display a text box to the user as well as a button. When the button is tapped, we transition to a new page. That new page is passed a parameter of q
whose value is whatever the user typed in the search box.
Inherits from Xamarin.Forms.ContentView
This is a special control that allows you to initiate a scan of a barcode.
Property
Type
Description
ButtonText
string
The text to display in the scan button that is automatically provided. Defaults to Scan.
ButtonStyleClass
IList<string>
The CSS style classes to apply to the scan button. Defaults to btn, btn-default.
Command
ICommand
The command to be executed when a barcode has been detected and scanned.
CommandParameter
object
The parameter to be given to the Command when it is executed.
Scan
ICommand
This command can be used with a custom button to trigger the camera to be shown. (read-only)
Template
View
If supplied, allows you to override the default template built by the control. When this is set then the default Scan button is not generated.
Value
string
The code that was scanned from the barcode. (read-only)
Value
Description
Manual
The camera will not start until manually triggered.
Automatic
The camera will automatically start as soon as possible.
Passive
The camera will start automatically but have no visual presence. The user can still manually trigger the camera so that it shows up. This mode is most useful when users are knowledgeable and know that they can scan a code but you want to still show a UI for manual entry.
The above example will create a barcode scanner and give it a name of scanner
that is used later to reference it. It's configured for Automatic mode so as soon as the page loads, it will show a full-screen camera scanner interface. If the user closes that then they will return to the page and see the normal content as well as a Scan
button that they can use to enter scan mode again.
When a code is detected, we have configured the Scan Code control to execute the Push Page command. We specify the Page Guid to transition to and then a parameter called code
that takes it's value from the Scan Code control's Value property. So when a code is scanned, the user will be redirected to a new page and that page will receive a query string parameter of code
that contains the scanned code.
The above will generate a Scan Code control that runs in manual mode, meaning the user must do something to initiate the scan. In this case, we are providing a template so the default button isn't rendered. To be honest, our template is rather pointless because we could achieve the same by just modifying the existing properties. But the important part of the example is how we bind the button's command to the Scan command of the Scan Code control. From this, you can imagine the possibilities of using an Image control with a tap gesture recognizer that triggers the Scan command. Or any other custom interface you want to make.
Inherits from NotificationBox
This control allows you to add client-side validation to your forms. For example, suppose you are building a custom Search form. It doesn't make sense to allow the user to search if they don't enter a term to search for. This control handles validation as well as displaying any validation errors.
Property
Type
Description
ControlsToValidate
List<IRockValidation>
References to the controls to be included in validation. This is the default content property so you can simply add the control references as child elements.
Everything above will render a simple text box for the user to type something into, and mark it as required. Then the validator will be there, though it won't be visible by default since there are no bad validations until it is run. Finally, we have a Search button that initiates a callback to the block. The command is configured to be a Callback command, and the parameters passed in include a reference to the Validator to be used duration validation.
What might be new and need a little explanation is the <x:Reference>
node. You are probably used to seeing {x:Reference term}
like we have in the SearchTerm parameter so we can bind to the Text property of the text box. In this new format, <x:Reference>term</x:Reference>
does something very similar. The entire node is replaced with a reference to the "term" text box. This allows you to use multiple <x:Reference>
nodes inside the validator to specify multiple fields to be validated.
If the user taps on the Search button without entering any text in the Search For box, then the validator will show up and give some information about the field being required. It will also prevent the Callback from happening.
Currently, the only command that supports validation is the Callback command.
Inherits from Xamarin.Forms.View
This control presents a simple volume icon on the screen. When tapped, a small popup will appear that allows the user to adjust the device volume.
There are no properties currently available to customize.
Inherits from Microsoft.Maui.Controls.Grid
Inherits from Xamarin.Forms.StackLayout
This control should only be used in your mobile templates. It defines the zones and their names that are made available to blocks when you configure a page.
Note that when you add multiple blocks to a zone, there will be a space between them. This comes from the default spacing on a StackLayout which is 10
. If you want to remove the gap, simply add a Spacing="0"
property to your zone and all the blocks within will touch.
Property
Type
Description
ZoneName
string
The name of the zone that will be used on the page details page when deciding where to place a block.
What effects do you have access to in Rock Mobile?
Beautiful native blur effects on iOS
You may have noticed the setting to adjust the Navigation Bar Transparency and Blur (iOS), but why stop there? You can apply the same effects to almost any iOS visual element (cards, StackLayout, etc).
The effect can be applied to almost any visual element:
If a control provides a default background color, you must specify a background color of transparent. It's also recommended to remove all shadow effects.
The Blur Effect has many great uses and interestingly enough can be used in more places than one might imagine.
Above was a demonstration of how the Blur Effect can exclusively utilizes the space defined by the SafeAreaPadding, even when there is no content within the visual element.
The following properties are available to the effect.
BlurStyle
IOSBlurStyle
What type of blur style would you like to be applied?
The blur style property is an enum, with the following accepted values:
Light
Dark
Thin
ThinDark
UltraThin
UltraThinDark
Thick
ThickDark
Chrome
ChromeLight
ChromeDark
System (default)
SystemDark
ExtraLight
ExtraDark
Here's a video that shows most of the blur styles that can apply to a visual element:
Newer phones commonly have areas that are not considered safe for content. For example, a phone with a camera notch has an unsafe area around the notch because your content might not actually display. The same is true of devices with rounded screen corners.
However, sometimes things look strange if you just leave those spots blank. So often what you would do is draw your background in the unsafe area, which can be clipped, and then draw your foreground content in the safe area. So you might put a ContentView in the entire screen with it's background color set and then use Padding to inset your actual content from the edges.
This effect is what lets you make sure your content is displayed in the safe area. It does this by modifying the element it is attached to and setting the Padding property to a value that is safe for the current orientation of the screen.
Property
Type
Description
Edges
SafeAreaEdge
The edges that should have padding applied to them. Defaults to All.
Value
Description
Left
The left padding edge will be modified so that the child content will be within the safe bounds.
Top
The top padding edge will be modified so that the child content will be within the safe bounds.
Right
The right padding edge will be modified so that the child content will be within the safe bounds.
Bottom
The bottom padding edge will be modified so that the child content will be within the safe bounds.
All
All padding edges will be modified so that the child content will be within the safe bounds.
Rock Mobile supports several custom form fields. This page contains information on using form fields and covers each of the various field types.
Before we go through the various fields available, let's take a look at how they look with their different embed options.
The first way to display one of these fields is just by itself without a container view.
The <Rock:FormField>
view provides a way to show the label. It also handles showing a required indicator. This will be covered in more detail when reading up on that view itself.
Now we're talking. The <Rock:FormGroup>
adds a border as well as some other sugar to your layout. Again, you can get all the details by reading up on the FormGroup
view. However, note that in this sample we removed the Label
from the TextBox
and moved it to the Title
property of the FormGroup
. When displaying a single field this works well.
This will be the format the screenshots for each individual field will be shown in as it provides a good way to see the entire view and what it will look like.
Inherits from Xamarin.Forms.ContentView
This view takes care of all logic behind deciding which UI to show when editing an attribute value. This is a developer level control. You shouldn't need to use this field unless you are developing a custom block.
Normal usage would be to loop through all the attributes on an entity and build a collection of these views, one for each attribute. All with a unique name that can be used when the data is submitted back to the user to know which attributes to update with what values. As noted below in the examples section, there is a helper method in the MobileHelper
class that will do all of this for you.
Note: Only a subset of Rock field types are supported. You can find a list of those here.
Property
Type
Description
Label
string
The name of the attribute as it should be displayed to the user.
IsRequired
bool
If this field should be considered required when performing form validation on the mobile device.
FieldType
string
The Rock class name of the field type, such as Rock.Field.Types.DateFieldType
.
ConfigurationValues
Dictionary<string, string>
The configuration values (sometimes called attribute qualifiers) that help the field define it's options. While this is actually a dictionary, you will most likely be passing in an JSON encoded string. It will be converted for you. When passing JSON you must prefix the JSON with {}
to ensure the XAML engine processes it correctly, for example: {}{"maxLength": 100}
.
Value
string
The current value as it is, or should be, stored in the database.
The above example creates a field on the screen that the user can use to enter a date. For normal uses, you would just use a DatePicker view instead. But remember this is intended to provide you with a value in the proper format to be stored in an Attribute Value. A more realistic example (in C#) is below.
The above code is going to get the attribute definition for the BaptismDate
attribute and then build an Attribute Value Editor field that will edit the value. If you were to use this you would also need to include a way to pass whatever value the user entered back to your form with an x:Name
attribute or something as well. In fact, we have an entire helper method that will build a form of attributes that you can use. The above could be simplified into:
Check out the mobile Group Edit block to see a good example of how to build a form with editable attributes by using the above method.
Inherits from FieldStack
This view provides a field that allows the user to enter an address, or display an address to be updated. Because it has to account for international addresses very little validation is performed.
Property
Type
Description
Label
string
The title for this input field.
IsRequired
bool
If set to true then the user will need to enter a value.
SelectedAddress
MobileAddress
Contains the address as entered by the user. Valid child properties are: Street1, City, State, PostalCode, Country.
The Address field is one of the few fields that should not be displayed in a FieldContainer that is forced into grouped mode. It is itself a grouped view so if you try to embed it inside another grouped view then you end up with double padding and double borders.
If you need to provide a default address to be displayed when the view is rendered, you can do so as follows:
Inherits from Xamarin.Forms.ContentView
The Check Box field allows the user to enter a Yes/No value. It has a number of different display options that will let you control the look and feel of your page.
Property
Type
Description
Label
string
The label associated with this input field.
IsRequired
bool
If set to true
then the user will be required to fill this in. Only applicable with drop down style.
Color
Color
Specifies the highlight color to be used when displaying as a either a CheckBox or Switch.
IsChecked
bool?
Gets or sets the current state of the checkbox. Defaults to false.
YesText
string
The text to use when displaying the truthy value in the drop down style. Defaults to Yes.
NoText
string
The text to use when displaying the falsey valye in the drop down style. Defaults to No.
Command
ICommand
Used to set the command to be executed when the value changes.
CommandParameter
object
The parameter to pass to the Command when the value changes.
Value
Description
CheckBox
Displays the control as a simple checkbox that the user can tap on to toggle the state.
Switch
Displays the control as a toggle switch. When on, it is highlighted with a color.
DropDown
Displays the control as a drop down. When the user taps on the control they are presented with a popup that lets them pick the option they want.
Inherits from Xamarin.Forms.ContentView
This field displays a series of check boxes for the user to turn on or off. An example of how this could be used is with a filter of categories where you want to display a list of categories and allow the user to pick which ones to show.
Property
Type
Description
Label
string
The label associated with this input field.
IsRequired
bool
If set to true
then the user will be required to fill this in. This value is currently ignored.
Options
List<Parameter>
The list of checkbox options that will be presented to the user. The displayed text is taken from the Name
property and the stored value is taken from the Value
property.
SelectedValues
IEnumerable<string>
The options that have been selected by the user. This corresponds to the Value
property of the parameter objects.
SelectedValueText
string
A comma separated list that represents the current selection as a single string.
Inherits from Xamarin.Forms.DatePicker
Presents a field that displays the selected date (or placeholder text) and allows the user to change the date. During edit mode, the date picker also exposes a Clear button that allows the user to clear the selected date completely.
Property
Type
Description
Label
string
The label title to be used when wrapped in a control that displays a label for the field.
IsRequired
bool
If True then any validation performed will require that a date be selected.
Placeholder
string
The text to display in the field if no date is selected.
SelectedDate
DateTime?
The currently selected date or null if no date is selected.
DatePickerStyle
DatePickerStyle
(iOS only) - Use this to change the OS-level style of the Date Picker.
This property/enum only makes a difference on iOS.
Wheels
The default value -- displays the Wheels
style date picker.
Inline
A calendar style date picker.
Inline
DatePickerStyle.Inherits from TextBox
The Email Box view provides an input box for the user to enter an e-mail address. It ensures the value is a somewhat valid address during validation. This does not sure it is a working e-mail address, only that it matches a basic syntax format.
See TextBox for available properties.
Inherits from Xamarin.Forms.Label
This field acts as a read-only field for you. Basically, it is a simple label that can be used with the field container. For example, if you wish to display some attribute values that the user does not have access to edit, you can use the Literal to display the formatted value of the attribute.
Property
Type
Description
Label
string
The label associated with this input field.
IsRequired
bool
Ignored since this field is not editable.
Text
string
The text to display in the field's contents.
Inherits from Picker.
This control provides a convenience for you to place a picker for a person's marital status. It automatically populates the available options based on what you have defined on the server. The picker item values are the defined value Guids.
Inherits from Xamarin.Forms.Label
The multi picker will allow the user to make multiple selections from a list of available items. If the field is not marked as required then the user can also leave it empty. When the field is tapped then a new model screen is shown with the list of items and a toggle for each one.
Property
Type
Description
Label
string
The label title to be used when wrapped in a control that displays a label for the field.
IsRequired
bool
If True then any validation performed will require that at least one value be selected.
Items
List
The items to be made available for user selection. (readonly)
SelectedItems
IEnumerable<PickerItem>
The items that have been selected by the user. (readonly)
SelectedValues
IList<string>
The item values that have been selected by the user.
SelectedValuesAsDelimited
string
The selected values as a comma delimited string. Useful with bindings to send the selected values back to the server. (readonly)
As you can see in this example, the SelectedValues
property can be used to set the initial selection with a comma delimited string. There is some magic happening in XAML that allows that to work. But you try to bind to that property or read it's value then you get an array of strings back. That is why the SelectedValuesAsDelimited
property exists, it automatically converts that array into a comma delimited string for you.
Inherits from TextBox
The Number Box view provides an input box for the user to enter a decimal number. It ensures the value is a valid decimal number during validation. The number may be negative and may or may not contain a fractional amount. However, if it does contain a decimal separator then it must also include at least one digit after the separator.
See TextBox for available properties.
Inherits from Xamarin.Forms.ContentView
The phone number box is actually a compound view composed of an optional Picker and a text box. The text box is for the actual phone number to be entered. If the Rock server is configured with more than one country code then the picker will become visible for the user to select the country code to use with the phone number.
If the entered country code and phone number match one of the formatting expressions in Rock then the phone number will be formatted according to those rules.
Property
Type
Description
Label
string
The label title to be used when wrapped in a control that displays a label for the field.
IsRequired
bool
If True then any validation performed will require that a phone number be entered.
CountryCode
string
Contains the selected country code, even if the picker is not visible.
PhoneNumber
string
Contains the formatted phone number, not including the country code.
The example above includes the country code so you can see what it looks like. Most Rock installations will probably have only one country code so that picker will not be visible.
Inherits from Xamarin.Forms.Picker
The picker will allow the user to select from a list of available items. If the field is not marked as required then the user can also leave it empty. When the field is tapped then a popup will appear allowing the user to select which item to choose.
Property
Type
Description
Label
string
The label title to be used when wrapped in a control that displays a label for the field.
IsRequired
bool
If True then any validation performed will require that a value be selected.
Items
List
The items to be made available for user selection. (readonly)
SelectedItem
PickerItem
The item that has been selected by the user. (readonly)
SelectedValue
string
The item value that has been selected by the user.
SelectedValueAsInt
int?
The currently selected value cast to an integer, or null
if there is no valid selection. (readonly)
SelectedValueAsGuid
Guid?
The currently selected value cast to a Guid, or null
if there is no valid selection. (readonly)
Inherits from Xamarin.Forms.Entry
Come on. Do we really need to explain what a text box is for? But seriously, as the name implies this view provides a place for the user to enter text on a page.
Property
Type
Description
Label
string
The label title to be used when wrapped in a control that displays a label for the field.
IsRequired
bool
If True, any validation performed will require that some text be entered.
MaxLength
int
The maximum allowed length of the entered text, set to 0 for no limit.
ValidationExpression
string
A regular expression that will be used to validate the input.
ValidationExpressionMessage
string
The error message to display when input fails the ValidationExpression.
Text
string
The content to be displayed inside the text box.
When a TextBox has IsEnabled
set to False
, the text color will be black or white depending on the iOS theme. This may be present in Workflow Entry forms, Prayer Request Details, and other blocks that use this TextBox to display an entry form. Use the Visual State Manager to override this to your desired color. You can add this to your page or even a Layout to affect all of its child pages.
Inherits from Xamarin.Forms.Editor
Like the Text Box, the Text Editor allows the user to enter text into a form. While the Text Box only allows a single line of text, the Text Box allows the user to enter multiple lines of text.
Unlike the related input in HTML, you cannot specify the height in lines of text. Instead you will need to specify the height in pixels.
Property
Type
Description
IsRequired
bool
If true
then the user will be required to enter a value in the field.
Label
string
The label that describes what this field is for.
Placeholder
string
The text to display when the user has not entered any value yet.
Text
string
Sets or gets the value for the text editor.
ValidationExpression
string
If not null or empty, specifies a regular expression that the user value must match in order to be considered valid.
ValidationExpressionMessage
string
The message to display to the user when the input does not match the ValidationExpression. Defaults to is not valid.
As you can see, in the above example we used the inline method to specify the default multi-line text value. Another method to achieve the same exact result that may be a bit easier to read/write, especially if you are hard coding the value in XAML.
Whichever method you choose, you will need to ensure that you have encoded any XML characters, such as <
, >
, or &
.
XAML markup extensions allow you to do some pretty cool things inside the XAML. You have probably already been using them in fact. For example, x:Name
and x:Reference
are both markup extensions. An extension is a XML node that entirely replaces itself with a new value after the XML content has been parsed. In the case of the x:Reference
node, it replaces itself with the item being referenced.
There are a few standard Xamarin Extensions that you might find useful, but we have also added a few of our own that should make your life a bit easier.
XAML extensions have two formats. I will call them Inline and Element. Let's look at the Binding as an example. While a Binding doesn't normally make sense as an Element style, let's pretend it does:
In the Element style, the properties are specified just like they are in HTML like you are probably accustomed to. The property name is followed by an equals sign and the value is enclosed by quotes. Then an space and the next property follows the same pattern.
However, the Inline format is different:
In the Inline format, we see that the property values are not enclosed by quotes, and a comma is used to separate two properties. The reason for the lack of quotes is that these Inline extensions are enclosed in a property value and thus the double-quote character is already in use.
If the value you need to specify includes a space, it is fine to use as the comma is used to note the end of the value (either that or the closing }
character). Conversely, if the value needs to include the comma character, you can wrap the value in single quotes, such as:
Obviously, this is a bad example since the Path to a property could neither include a comma or a space, but you get the idea.
This Value Converter allows you to bind something to a Boolean but then convert that Boolean value to any object you want for truth/false. It might be easier to explain with an example.
Say you have an Icon control and you want to change the displayed icon class depending on the value of something else like a checkbox. You would bind your Icon.IconClass property to the CheckBox.IsChecked property like normal, but then you apply the Boolean Value Converter inside that binding so you can change the value set in the IconClass based on the IsChecked being either true or false.
Property
Value
Description
True
object
Any value you want to use when the expression evaluates to True.
False
object
Any value you want to use when the expression evaluates to False.
This example would change the IconClass
property to either play
or pause
depending on the boolean value we are binding to.
Parses a JSON string into the appropriate type. Useful to pass data from the server to the client and then being able to use that data in bindings. This will only parse simple JSON types. Meaning, you cannot encode a Group object into JSON and then expect that it will become a Group object on the client. It will be parsed as a generic dictionary object instead. However, you will still be able to reference it's child elements by their names when using bindings.
Property
Type
Description
Content
string
The JSON content that will be parsed. This is the default content property so you can also provide the content
In this example we are going to be pre-parsing the XAML with Lava on the server. The seriesJSON
variable contains the JSON that identifies a series being viewed. You could use ToJSON
but that should be used only if you know exactly what properties it contains. For example, using ToJSON
on a Group
would be a bad idea as it will generate a huge amount of JSON you don't need, including most likely some sensitive data.
Lets break open that FromJson
tag a bit and see what it might look like after it's parsed by the server-side Lava.
As you will notice, that {}
prefix we had is still there. That is required so the the XAML system knows that the {
which starts the JSON data should not be treated as a XAML extension. Basically it sees the {}
and then knows to just ignore that part and treat the rest as a plain text string.
So once this all runs on the client, we end up with a static resource on the Stack Layout called Series
. Then, on a Label inside that Stack Layout we use binding to bind to the name of the series. This is obviously a somewhat pointless example as you could do this more easily. But suppose your JSON also included a Messages
property that contained an array of the messages in the series. You could use a Collection View or something like that to bind to that Messages property for it's content and dynamically build the UI to display all those messages.
While the same could be done by rendering the XAML on the server, this allows for reduced bandwidth and offloads some of the processing from the server onto the client. While a page that displays 4 or 5 items probably doesn't save a ton, imagine if you are displaying something with 50+ items, such as a list of upcoming events.
This simple Value Converter allows you to invert the state of a boolean that you are binding to. A command use case is when you want to provide a checkbox for the user to do something but the underlying property to be set is inverted from how you want the text to read.
The value you're binding to must be an actual boolean, not a string of True or False.
Suppose you want to have the user set a property value for "NotReady". While that is a perfectly good property name that states it's purpose clearly, showing a checkbox to the user with the label "Not Ready" might be confusing. You want to show a label of "Ready" and then use this converter to convert the value of the checkbox before storing it in the "NotReady" property.
Example
This converter allows you to change a String to a Guid type. Some properties and bindings in XAML require this type, meaning a string with an actual Guid value within will still fail without this converter.
In this example, the string Guid value within ItemGuid
would be converted to a Guid type.
This is deprecated in Rock Mobile V6 and later. There is a built-in XAML extension for .NET MAUI.
In some cases, it can be useful to customize content or appearance across platforms—for example, applying one style on Android and a different one on iOS to match each platform's native aesthetic. This extension provides a way to set content or property values depending on the device's OS platform.
Below is legacy documentation for the original Rock:OnDevicePlatform
extension.
Android
object
The value to be used when the device is running on Android.
iOS
object
The value to be used when the device is running on iOS.
Default
object
The value to be used when the device is running on something else.
When running on an Android device, the text will be blue. If instead running on an iOS device then the text will be red. Otherwise, the text will be black. While not currently required, the Default value should be specified in case we add other platforms in the future.
Here is a more interesting example. In this case, we are replacing not just a property but an entire element. On Android, they will see a button that they can tap. On every other platform, they will see a label that informs them the feature only works on Android.
This is deprecated in Rock Mobile V6 and later. There is a built-in XAML extension for .NET MAUI.
Similar to the On Device Platform, this extension lets you change property values and entire nodes depending on what type of device the app is running on. A good use case for this would be if you want to display a different image on tablets than you do on phones.
Property
Type
Description
Phone
object
The value to be used when the device is a phone.
Tablet
object
The value to be used when the device is a tablet.
Default
object
The value to be used when the device is something else.
When running on a phone, the image will have a height of 300 pixels. But on a tablet it will only have a height of 150 pixels. This might be useful if you are worried that the image might take up too much vertical space on a tablet under normal sizing circumstances.
Here is a more interesting example. In this case we are replacing not just a property but an entire element. On tablet devices, they will see a button which they can tap. On every other device type they will see a label that informs them the feature only works on tablets.
Rock Mobile gives you the ability to have a whole suite of named colors that can be used in CSS. Things like the primary app color. But what if you want to access those colors in XAML as well? This extension gives you the ability to do just that.
To see the various colors available to you check out the Colors styling page.
Property
Type
Description
ColorName
string
The name of the palette color to be used.
The colors below are available as of Rock Server 1.12.5.
Text-Color
Heading-Color
Background-Color
App-Primary
App-Secondary
App-Success
App-Info
App-Danger
App-Warning
App-Light
App-Dark
App-Brand
This would set the label's text color to be the applications primary color, as defined in the app bundle. These color names are case-insensitive.
The purpose of this converter is to allow you to take a value in seconds and have it displayed as a time string, such as HH:MM:SS
. There are a few properties that let you customize the format.
Property
Type
Description
ShowHours
How to show the hours segment of the time string. Defaults to Automatic.
ShowMinutes
How to show the minutes segment of the time string. Defaults to Automatic.
ShowSeconds
How to show the seconds segment of the time string. Defaults to Automatic.
Value
Description
Automatic
The value will be hidden unless it is non-zero or a prior segment is visible.
Never
The segment will never be visible.
Always
The segment will always be visible.