All pages
Powered by GitBook
1 of 96

Controls

Views are user-interface objects such as labels, buttons, and sliders that are commonly known as controls or widgets in other graphical programming environments.

.NET MAUI Base Views

The .NET MAUI framework provides a rich collection of base views (controls). You can find a documentation on these views on the Microsoft site.

Behaviors

Event To Command Behavior

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.

Examples

<Rock:FieldContainer>
    <Rock:TextEditor>
        <Rock:TextEditor.Behaviors>
            <Rock:EventToCommandBehavior EventName="TextChanged"
                Command="{Binding ShowToast}"
                CommandParameter="The text has been changed." />
        </Rock:TextEditor.Behaviors>
    </Rock:TextEditor >
</Rock:FieldContainer>

Touch Behavior

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.

Examples

<HorizontalStackLayout HorizontalOptions="Center" VerticalOptions="Center">
    <HorizontalStackLayout.Behaviors>
        <Rock:TouchBehavior
            DefaultAnimationDuration="250"
            DefaultAnimationEasing="{x:Static Easing.CubicInOut}"
            PressedOpacity="0.6"
            PressedScale="0.8" />
    </HorizontalStackLayout.Behaviors>

    <ContentView
        HeightRequest="100"
        WidthRequest="10"
        BackgroundColor="Gold" />
        
    <Label Text="The entire layout receives touches" 
        VerticalOptions="Center" 
        LineBreakMode="TailTruncation"/>
    <ContentView
        HeightRequest="100"
        WidthRequest="10"
        BackgroundColor="Gold" />
</HorizontalStackLayout>

Content Controls

Activity Indicator

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.

Properties

Property

Type

Description

IsVisible

bool

If true then the activity indicator will be visible and show that work is being done.

Example

<Rock:ActivityIndicator />

Application Info

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:

<Label>
    <Label.FormattedText>
        <FormattedString>
            <Span Text="App Version: " FontAttributes="Bold" />
            <Span Text="{Binding Application.ApplicationVersion}" />
        </FormattedString>
    </Label.FormattedText>
</Label>

Properties

This view contains no properties of it's own.

Example

<Rock:ApplicationInfo />

Avatar

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:

LogoAvatars | Rock Community

About

This control constructs an avatar image source based on the provided parameters or displays the current person's avatar.

Properties

Property
Type
Description

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.

Examples

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.

<Rock:Avatar Source="{{ CurrentPerson.PhotoUrl | Escape }}" />

Otherwise, you can pass in the parameters to build the Avatar source manually.

<Rock:Avatar PersonGuid="{{ CurrentPerson.Guid }}" />
<Rock:Avatar AvatarBackgroundColor="{Rock:PaletteColor App-Primary-Soft}" 
   AvatarForegroundColor="{Rock:PaletteColor App-Primary-Strong}"
   AvatarText="Custom Avatar"
   Rounded="False" />

If no properties are set, the component will display the current person's avatar:

<Rock:Avatar />

Bible Audio

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.

When including Psalms in the reading Reference be sure to use Psalms, notPsalm.

Properties

Property
Type
Description

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

InteractionParameters

An object containing parameters that control how the audio is interacted with. This could include behaviors like the audio play speed, volume, etc.

Custom Content

You can supply custom content to your Bible Audio control, and maintain a reactive UI through bindings and commands.

Bindable Properties

Property
Type
Description

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:

<Rock:BibleAudio Reference="Psalms 1">
    <Rock:Icon IconClass="{Binding BibleAudio.IsPlaying, Converter={Rock:BooleanValueConverter True=pause, False=volume-up}}"
        FontSize="20"
        StyleClass="text-primary"
        Command="{Binding BibleAudio.PlayOrPauseAudio}" />
</Rock:BibleAudio>

Bible Browser

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.

Deep links to the YouVersion Bible app are supported by Rock Mobile, which may provide a better experience than this native Bible Browser control. We'd recommend this option unless you need more control over the experience with more native app integration.

Find out more here ->

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!

Properties

Property
Type
Description

Content

View

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.

Default Content

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.

Property
Type
Description

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.

Example

<Rock:BibleBrowser Reference="Genesis 1">
    <StackLayout>
        <Label Text="{Binding BibleBrowser.Reference}"
            StyleClass="text-interface-strongest, title1, bold"
            HorizontalOptions="Center">
            <Label.GestureRecognizers>
                <TapGestureRecognizer Command="{Binding BibleBrowser.ShowPickerCommand}" />
            </Label.GestureRecognizers>
        </Label>
    
        <Grid ColumnDefinitions="*,*,*">
            <Rock:Icon IconClass="chevron-left"
                StyleClass="text-interface-stronger"
                IconFamily="MaterialDesignIcons"
                FontSize="36"
                Command="{Binding BibleBrowser.ShowPreviousBookOrChapterCommand}"
                IsVisible="{Binding BibleBrowser.HasPreviousBookOrChapter}"
                HorizontalOptions="Start"
                VerticalOptions="Center"
                Grid.Column="0" />
                      
            <Rock:Icon IconClass="chevron-right"
                StyleClass="text-interface-stronger"
                IconFamily="MaterialDesignIcons"
                FontSize="36"
                Command="{Binding BibleBrowser.ShowNextBookOrChapterCommand}"
                IsVisible="{Binding BibleBrowser.HasNextBookOrChapter}"
                HorizontalOptions="End"
                VerticalOptions="Center"
                Grid.Column="2" />
        </Grid>
        
        <Rock:BibleReader Reading="{Binding BibleBrowser.Reading}"
            ShowReference="false"
            Margin="0,12,0,0" />
    </StackLayout>
</Rock:BibleBrowser>

Bible Reader

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.

Reference Syntax

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.

  1. Multiple references are supported but must be separated by a semi-colon ;

  2. Consecutive verses from a single chapter are supported with this syntax: Genesis 1:1-9

  3. Verses cannot span across chapters, so divide them up: Genesis 1:30-31; Genesis 2:1-3

  4. If a book only contains a single chapter, it still must be included: Jude 1

  5. Full chapters can be included with this syntax: Genesis 1,2 or Genesis 1-2

When including Psalms in the reading Reference be sure to use Psalms, notPsalm.

Properties

Property
Type
Description

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.

Styling

For details on styling this control see the Bible Styling page.

Examples

<Rock:BibleReader Reference="Genesis 1:1-9" ShowHeadings="false" />

Campus Context Picker

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.

Properties

This control exposes no properties that can be modified.

Example

<Rock:CampusContextPicker />

Camera Code Reader

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.

Properties

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

NavigateMode

The type of navigation to perform when the code is scanned. Defaults to Push.

When a code is scanned, the scanner will turn off automatically. If you are using Push navigation then when the page becomes visible again the scanner will automatically re-enable itself and start scanning codes again.

Example

<Rock:CameraCodeReader WorkflowPage="2738f829-09a6-4b14-a4b2-4334a47d8de6" />

Code Types

There are currently two types of codes supported.

Workflow Code

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.

RK:WF:25af66d6-0b7f-41b8-a8ca-bf912574eeb1?GroupId=20&Mode=auto

Page Code

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.

RK:PG:6cb5d894-02e1-4868-93b1-6d52d94295de?source=qrcode

Cards

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.

Card Types

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.

Contained Card

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.

Contained Card
<Rock:ContainedCard 
    Tagline="DESTINATIONS"
    Title="Start Your Adventure"
    Image="https://yourserver.com/image-grandtetonfence.jpg">
        Bring to the table win-win survival strategies to ensure...
</Rock:ContainedCard>

Block Card

The block card is very similar to the Contained Card but the content is not in a clearly visible frame.

Block Card
<Rock:BlockCard 
    Tagline="DESTINATIONS"
    Title="Start Your Adventure"
    Image="https://yourserver.com/image-grandtetonpeak.jpg">
    Bring to the table win-win survival strategies... 
</Rock:BlockCard>

Inline Card

The Inline Card places the image behind the content and provides several options to create striking designs.

Inline Card
<Rock:InlineCard 
    Title="Start Your Adventure"
    HeaderLocation="Top"
    ContentLocation="Bottom"
    Tagline="DESTINATIONS"
    Image="https://yourserver.com/image-grandtetonfence.jpg">
    Bring to the table win-win survival strategies to ensure...
</Rock:InlineCard>

Block Card

The block card is very similar to the Contained Card but the content is not in a clearly visible frame.

Inherits from StyledView > PancakeView

Block Card

Properties

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)

Contained Card

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

Contained Card

Properties

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)

Inline Card

The Inline Card places the image behind the content and provides several options to create striking designs.

Inherits from StyledView > PancakeView

Inline Card

Properties

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)

Elements of a Card

Below is a diagram of the various elements that make up a card.

Components of a Card

Masks

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.

Use
Description
Property Name (Block and Contained)
Property Name (Inline)

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

Built-In Masks

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.

Cover

Fade-Thin

resource://Rock.Mobile.Resources.Masks.fade-thin.png

Cover

Fade-Light

resource://Rock.Mobile.Resources.Masks.fade-light.png

Cover

Fade-Medium

resource://Rock.Mobile.Resources.Masks.fade-medium.png

Cover

Fade-Dark

resource://Rock.Mobile.Resources.Masks.fade-dark.png

Cover

Midline

resource://Rock.Mobile.Resources.Masks.midline.png

Cover

Vignette

resource://Rock.Mobile.Resources.Masks.vignette.png

Cover

Top-Bottom

resource://Rock.Mobile.Resources.Masks.top-bottom.png

Designing With Masks

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.

<Rock:InlineCard CardRatio="4:3"
    Title="Enjoy the Views"
    HeaderLocation="Center"
    ContentLocation="Bottom"
    Tagline="DESTINATIONS"
    Image="https://yourserver.com/image-grandtetonfence.jpg"
    ImageSaturation="0"
    ImageOpacity=".4"
    BackgroundColor="#6bac43"
    BackgroundMask="Midline"
    BackgroundMaskColor="#6bac43"
    BackgroundMaskOpacity=".6">
    Bring to the table win-win survival strategies... 
</Rock:InlineCard>

Styling Cards With CSS

Below is a chart of the various CSS styles available to you to style.

Context Menu

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!

Due to limitations on Android, these are more fleshed out on iOS. We didn't want to take the native iOS features away, so some properties may not translate to Android.

Getting Started

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 Actions or Menus. These cannot be nested.

Menu

Name
Type
Description

Title

string

A string title to be displayed at the top of the menu.

iOS ✅ Android ❌

MenuAction

Name
Type
Description

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.

MenuGroup

Name
Type
Description

Title

string

The title of the group.

System Icons

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.

Examples

Default

Opens a Context Menu when the Border is held down.

<Border HeightRequest="100" 
    BackgroundColor="White"
    Padding="16">
    
    <Label Text="Example Group Item" 
        StyleClass="title2, text-interface-stronger" 
        VerticalOptions="Center" />
           
    <Rock:ContextMenu.Menu>
        <DataTemplate>
            <Rock:Menu>
                <Rock:MenuGroup Title="Group Actions">
                    <Rock:MenuAction Title="Take attendance" 
                        Command="{Binding PushPage}"   
                        CommandParameter="d7a2700b-8c24-4ff2-908e-6f9ddcced79f" />
                    <Rock:MenuAction Title="View details" 
                        Command="{Binding ShowToast}"
                        CommandParameter="Group details" />
                    <Rock:MenuAction Title="Delete" 
                        IsDestructive="true"
                        SystemIcon="{OnPlatform iOS=xmark}" />
                </Rock:MenuGroup>
            </Rock:Menu>
        </DataTemplate>
    </Rock:ContextMenu.Menu>
</Border>

Show Menu on Click

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.

<Button Rock:ContextMenu.ShowMenuOnClick="True">
    <Rock:ContextMenu.Menu>
        <DataTemplate>
            <Rock:Menu>
                <Rock:MenuGroup Title="Group Actions">
                    <Rock:MenuAction Title="View details" 
                        Command="{Binding ShowToast}"
                        CommandParameter="Group details" />
                </Rock:MenuGroup>
            </Rock:Menu>
        </DataTemplate>
    </Rock:ContextMenu.Menu>
</Button>

Click Command

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!

<ContentView 
    Rock:ContextMenu.ClickCommand="{Binding ShowToast}"
    Rock:ContextMenu.ClickCommandParameter="Hello">
    <Rock:ContextMenu.Menu>
        <DataTemplate>
            <!-- ... -->
        </DataTemplate>
    </Rock:ContextMenu.Menu>
</ContentView>

Countdown

Adding a countdown timer to your page is simple. There are several options for providing a date and time to the control.

String

Simply enter a raw date time value as a string.

<Rock:Countdown StartDateTime="08/27/2020 10:30AM" />

Lava Filter

See the Lava documentation for more information.

<Rock:Countdown StartDateTime="{{ 'Now' | DateAdd:3, 'd' }}" />

Lava Shortcode

Utilize the scheduledcontent Lava shortcode.

{[ scheduledcontent scheduleid:'3' showwhen:'both' ]}
    <Rock:Countdown StartDateTime="{{ NextOccurrenceDateTime }}" />
{[ endscheduledcontent ]}

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.

Properties

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.

Sample Countdown

Special CSS Classes

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.

CSS X-Ray

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.

Cover Sheet

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.

Android

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.

Parameters

Listed below are the options provided via the ShowCoverSheetCommandParameters object.

Property
Type
Description

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.

Styling

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:

.cover-sheet {
    -maui-bar-background-color: green;
    -maui-bar-text-color: #ffffff;
    -rock-status-bar-text: light;
    -rock-ios-hide-navigation-bar-separator: true;
}

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.

Examples

To show a cover sheet that displays another page, pass in the PageGuid as the CommandParameter.

<!-- Cover sheet used to display another page as content. -->
<Button Text="Tap"
    StyleClass="btn, btn-primary"
    Command="{Binding ShowCoverSheet}"
    CommandParameter="71e80253-8d10-426b-8182-65dafe9b695f" />

To show a cover sheet from provided XAML content, pass in the XAML content you want to render inside of the CommandParameter.

<!-- Cover sheet with content as the parameter. -->
<Button Text="Tap"
    StyleClass="btn, btn-primary"
    Command="{Binding ShowCoverSheet}">
    <Button.CommandParameter>
        <StackLayout>
            <Label Text="This is cover sheet content."
                StyleClass="h1" />
        </StackLayout>
    </Button.CommandParameter>
</Button>

Here is an extensive example with most of the ShowCoverSheetParameters properties utilized.

<Button Text="Tap"
    StyleClass="btn, btn-primary"
    Command="{Binding ShowCoverSheet}">
    <Button.CommandParameter>
        <Rock:ShowCoverSheetParameters SheetTitle="Title" 
            ModalPresentationStyle="FullScreen">
            <Rock:ShowCoverSheetParameters.Content>
                <StackLayout>
                    <Label Text="This is cover sheet content."
                        StyleClass="h3" />
                </StackLayout>
            </Rock:ShowCoverSheetParameters.Content>
            <Rock:ShowCoverSheetParameters.PrimaryActionButton>
                <Button Command="{Binding ShowToast}" 
                    Text="Toast"
                    CommandParameter="That was a unique use of the PrimaryActionButton..." />
            </Rock:ShowCoverSheetParameters.PrimaryActionButton>
            <Rock:ShowCoverSheetParameters.SecondaryActionButton>
                <Button Command="{Binding CloseCoverSheet}" 
                    Text="Dismiss" />
            </Rock:ShowCoverSheetParameters.SecondaryActionButton>
        </Rock:ShowCoverSheetParameters>
    </Button.CommandParameter>
</Button>

Closing a Cover Sheet

To close any open cover sheet, use the CloseCoverSheet command.

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

Divider

Displays a separator line much like an HTML <hr> tag.

Inherits from BoxView

Properties

Name
Type
Description

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.

<Rock:Divider />
<Rock:Divider Thickness="Thick" />
<Rock:Divider Thickness="Thicker" />
<Rock:Divider Thickness="Thickest" />

Use the margin helper CSS classes like .my-12 to easily adjust the vertical spacing around your divider.

<Rock:Divider StyleClass="my-12" />

Expander

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.

Properties

Property
Type
Description

Content

View

The content that will be displayed when expanded. This is the default property so it can be omitted when creating child elements.

ContentTemplate

DataTemplate

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

View

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.

Direction

ExpandDirection

Which direction the expander will expand in. Defaults to Down.

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

Easing

The easing function to use when performing the animation. Defaults to Linear.

CollapseAnimationEasing

Easing

The easing function to use when performing the animation. Defaults to Linear.

Expand Direction

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.

Example

<Rock:Expander>
    <Rock:Expander.Header>
        <Label Text="Tap for details" />
    </Rock:Expander.Header>
    <StackLayout>
        <Label Text="Some details about this event." />
        <Button Text="Register" StyleClass="btn btn-primary" />
    </StackLayout>
</Rock:Expander>

Field Container

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.

Properties

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.

FieldLayout

FieldLayout

The type of layout to use when rendering the fields. Defaults to Automatic.

Field Layout

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.

Examples

<Rock:FieldContainer Title="Your Name">
    <Rock:TextBox Label="First Name"
        IsRequired="True" />
    <Rock:TextBox Label="Last Name" />
</Rock:FieldContainer>

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.

<Rock:FieldContainer>
    <Rock:TextBox Label="Your Name"
        IsRequired="True" />
</Rock:FieldContainer>

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.

<Rock:FieldContainer FieldLayout="Individual">
    <Rock:TextBox Label="First Name" IsRequired="True" />
    <Rock:TextBox Label="Last Name" />
</Rock:FieldContainer>

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.

Flip View

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.

Properties

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.

Orientation

FlipOrientation

The orientation of the flip. Default is Horizontal.

Easing

Easing

The type of animation easing function to use. Default is Linear.

FlipCommand

ICommand

You can bind an action to this property to initiate a flip.

Flip Orientation

Value

Description

Horizontal

The content is flipped horizontally.

Vertical

The content is flipped vertically.

Example

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.

<Rock:FlipView x:Name="textCard">
    <Rock:FlipView.GestureRecognizers>
        <TapGestureRecognizer Command="{Binding FlipCommand, Source={x:Reference textCard}}" />
    </Rock:FlipView.GestureRecognizers>
    
    <Rock:FlipView.FrontView>
        <Label Text="Front Text" />
    </Rock:FlipView.FrontView>

    <Rock:FlipView.BackView>
        <Label Text="Back Text" />
    </Rock:FlipView.BackView>
</Rock:FlipView>

Following Icon

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.

Properties

Property
Type
Description

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

IconFamily

The icon family to use when the entity is not being followed. Defaults to FontAwesomeSolid.

FollowingIconColor

Color

The color to use for the icon when the entity is being followed.

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

IconFamily

The icon family to use when the entity is not being followed. Defaults to FontAwesomeRegular.

NotFollowingIconColor

Color

The color to use for the icon when the entity is not being followed.

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..

Security Considerations

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:

  1. DELETE - api/Followings/{entityTypeId}/{entityId}?purposeKey={purposeKey}

  2. 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.

Example

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.

<StackLayout Orientation="Horizontal">
    {% assign group = 41 | GroupById %}
    <Rock:FollowingIcon EntityTypeId="{{ group.TypeId }}"
        EntityId="{{ group.Id }}"
        FontSize="20"
        IsFollowed="{{ group | IsFollowed }}"
        FollowingIconColor="#ee7725"
        NotFollowingIconColor="#ee7725" />
    <Label Text="{{ group.Name | Escape }}" />
</StackLayout>

Geo Boundary View

Display content based on whether or not a person is within a geofence.

Inherits from Xamarin.Forms.ContentView

Creating Fences

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.

Using Points and PointRadius

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.

<Rock:GeoBoundaryView x:Name="GeoBoundary"
    Points="31.7058,35.2007"
    PointRadius="2">
    <Rock:GeoBoundaryView.InBoundary>
        <Label Text="You're really in Bethlehem? Cool!" />
    </Rock:GeoBoundaryView.InBoundary>
    <Rock:GeoBoundaryView.OutOfBoundary>
        <StackLayout Spacing="0">
            <Label Text="The closest Geographical Boundary is:" />
            <Label Text="{Binding ClosestGeoFence, Source={x:Reference GeoBoundary}}" />
        </StackLayout>
    </Rock:GeoBoundaryView.OutOfBoundary>
</Rock:GeoBoundaryView>

Results in a 2km radius circle around Bethlehem:

You can provide multiple points (syntax) to create multiple geo-fences.

Properties

Property
Type
Description

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.

Point Syntax

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

Fence Syntax

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

HTML

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.

<Rock:Html>
    <![CDATA[
    <p>This is some sample text.</p>
    <p>This is a second paragraph.</p>
    ]]>
</Rock:Html>
Property
Type
Description

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?

Markdown

Supported Tags

A 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

Styling

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).

Note that bold and italic styles aren't natively supported for custom fonts added to the shell during the App Factory publishing process. While other font weights can be included, they must be uploaded and referenced as separate font family files. If you need to apply bold or italic formatting, the default font families on iOS and Android provide this support.

  • <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:

<Rock:Html StyleClass="html-content">...</Rock:Html>

Then in the custom CSS, target classes you want to change:

.html-content .paragraph { margin-bottom: 0; }

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.

Icon

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.

Icon Family

Rock Mobile currently supports the following font families:

Font Family
Internal Font Name
Description

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/

TablerIcons

TablerIcons

The outline variant icons from Tabler: https://tabler.io/icons

Properties

Property
Type
Description

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.

IconFamily

IconFamily

The icon font family to use to display the icon. Default value is FontAwesome.

FontSize

double

The size of the icon.

TextColor

Color

The color of the icon to use by default.

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.

Use the Font Family name when definiting the IconFamily property with Rock:Icon. The Internal Font Name can be used to add an icon as an image within a Button.

<HorizontalStackLayout Spacing="8">
    <Rock:Icon IconFamily="TablerIcons" IconClass="user" />
    <Rock:Icon IconFamily="FontAwesomeSolid" IconClass="user" />
    <Rock:Icon IconFamily="FontAwesomeBrands" IconClass="RockRMS" />
    <Rock:Icon IconFamily="FontAwesomeRegular" IconClass="user" />
    <Rock:Icon IconFamily="MaterialDesignIcons" IconClass="account" />
</HorizontalStackLayout>
<Button Text="Save"
    StyleClass="btn, btn-primary, headline, font-weight-bold"
    ContentLayout="Left, 12">
    <Button.ImageSource>
        <FontImageSource Glyph="&#xeb62;" FontFamily="TablerIcons" Size="20" />
    </Button.ImageSource>
</Button>

Icon Button

Displays a Button with an Icon as the content.

Inherits from Button

Overview

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.

Properties

Name
Type
Description

IconClass

string

The icon to display.

IconFamily

IconFamily

The icon family to use. Defaults to FontAwesome.

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.

<Rock:IconButton IconClass="user"
    IconFamily="FontAwesomeSolid"
    HeightRequest="28"
    WidthRequest="28"
    FontSize="14"
    CornerRadius="14"
    StyleClass="btn, btn-outline-primary" />

This example creates a circular IconButton with a user icon, styled as an outlined primary button.

Image

Inherits from Xamarin.Forms.ContentView

If you'd like to show an animated GIF, use the default Image control instead.

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.

<Rock:Image Source="https://server.com/photo.jpg" />

Is that it? No, we're just getting started. Below are all of the properties you can add to images.

Basic Image

Properties

Property
Type
Description

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

LayoutOption

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

LayoutOption

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.

Image Transformations

You can apply several different transformations to your images. Each is discussed below.

Blur

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.

Property
Type
Description

Radius

Float

The amount of blur to add.

<Rock:Image Source="https://server.com/photo.jpg" >
    <Rock:BlurTransformation Radius="4" />
</Rock:Image>
Blur Transform

Circle

The circle transformation masks your images into a circle shape. The syntax for this is below.

Property
Type
Description

BorderSize

int

The size of the optional border around the image.

BorderColor

Color

The color of the border around the image.

<Rock:Image 
    Source="https://server.com/photo.jpg" 
    BackgroundColor="#c4c4c4"
    HeightRequest="128"
    WidthRequest="128"
    Aspect="AspectFill" 
    HorizontalOptions="Center" 
    VerticalOptions="Fill">
    <Rock:CircleTransformation BorderSize="4" 
        BorderColor="rgba(255, 255, 255, 0.58)" />
</Rock:Image>
Circle Transform

Drop Shadow

The filter adds a customizable drop shadow to your images.

Property
Type
Description

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.

<Rock:Image 
    Source="https://server.com/photo.jpg" 
    BackgroundColor="#c4c4c4"
    HeightRequest="300"
    WidthRequest="300"
    Aspect="AspectFill" 
    HorizontalOptions="Center" 
    VerticalOptions="Fill">
    <Rock:DropShadowTransformation 
        Distance="8"
        Angle="135"
        Radius="4"
        Color="#c4c4c4"
        Opacity="0.5" />
</Rock:Image>
Drop Shadow Transformation

Fill Color

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.

Property
Type
Description

Color

Color

The color to fill the image with.

<Rock:Image Source="https://server.com/photo.jpg" >
    <Rock:FillColorTransformation Color="#41BFD0" />
</Rock:Image>
Fill Transformation

Flip

Flips the image either horizontally, vertically, or both.

Property
Type
Description

Direction

FlipDirection

Valid values include: Horizontal, Vertical or Both

<Rock:Image Source="https://server.com/photo.jpg" >
    <Rock:FlipTransformation Direction="Both" />
</Rock:Image>
Flip Transformation

Grayscale

Converts the image to grayscale.

Property
Type
Description

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.

<Rock:Image Source="https://server.com/photo.jpg" >
    <Rock:GrayscaleTransformation Saturation="0" />
</Rock:Image>
Grayscale Transformation

Reflection

Draws a reflection of the image as if the image were sitting on a glass surface.

Property
Type
Description

Size

double

The size of the reflection.

<Rock:Image Source="https://server.com/photo.jpg" >
    <Rock:ReflectionTransformation Size="96" />
</Rock:Image>
Reflection Transformation

Rounded

Rounds the corners of the image and optionally adds a border.

Property
Type
Description

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.

<Rock:Image Source="https://server.com/photo.jpg" >
    <Rock:RoundedTransformation CornerRadius="120, 0, 0, 120" 
        BorderSize="4" 
        BorderColor="rgba(255, 255, 255, 0.58)" />
</Rock:Image>
Rounded Transformation

Tint

Tints the image using the provided color.

Property
Type
Description

Color

Color

The color to use to tint the mid-tones of the image.

<Rock:Image Source="https://server.com/photo.jpg" >
    <Rock:TintTransformation Color="#41BFD0" />
</Rock:Image>
Tint Transformation

Keep in mind you can use more than one transformation on a single image.

Now are we done? Not quite, what's the rush?

Layering Images

Want to go to the next level with your images? Layer them! Look at the sample below:

<Grid>
    <!-- Bottom image -->
    <Rock:Image Source="https://server.com/photo.jpg" 
        Aspect="Fill"
        HeightRequest="360"
        HorizontalOptions="FillAndExpand">
        <Rock:TintTransformation Color="#53AFBE" />
    </Rock:Image>
    
    <!-- Top mask -->
    <Rock:Image Source="resource://Rock.Mobile.Resources.Masks.vignette.png" 
         Aspect="Fill"
         HeightRequest="360"
         HorizontalOptions="FillAndExpand">
         <Rock:FillColorTransformation Color="#53AFBE" />
     </Rock:Image>
</Grid>
Results of Layering Images

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.

Styling

Ratio vs. HeightRequest

While HeightRequest can be used to size images, using Ratio is preferred.

<Rock:Image 
    Source="https://server.com/photo.jpg"
    Ratio="4:2" />

Interaction

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.

Properties

Property
Type
Description

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.

<Rock:Interaction Operation="Watched video"
    Summary="Watch"
    ChannelId="28"
    ComponentName="{{ video.Name | Escape }}"
    Data="{{ video.Url | Escape }}" />

Items Collection

Display a highly performant list of views powered by JSON data and an item template.

Inherits from Sharpnado.CollectionView

About

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:

<ScrollView> <!-- Usually in the layout, but I moved here for demo -->
    <StackLayout>
        {% for item in items %}
            <StackLayout>
                <Label Text="{{ item.Name }}" />
                <Label Text="{{ item | Attribute:'FavoriteColor' }}" />
            </StackLayout>
        {% endfor %}
    </StackLayout>
</ScrollView>

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.

Properties

Property Name
Type
Description

CollectionLayout

CollectionViewLayout

Layout of the collection view.

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.

Collection View Layout

Description

Horizontal

A horizontal layout.

Grid

A grid layout.

Carousel

A carousel layout.

Vertical

A vertical layout.

Usage

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.

  1. Define your data source as JSON

  2. Bring your JSON into memory

  3. Create a single item template

  4. Set up your Items Collection container

Examples

Make sure to use Rock:ViewCell as the base of your template. This control has some special logic to make sure the views are properly dark mode responsive.

//- Load our JSON data from an entity command.
{%- capture people -%}
  [
    {%- person where:'LastName == "Decker"' -%}
    {
      "name": "{{ person.FirstName }} {{ person.LastName }}",
      "campus": "{{ person.Campus }}",
    }{%- unless forloop.last -%},{%- endunless -%}
    {%- endperson -%}
  ]
{%- endcapture -%}

<Grid>
    <Grid.Resources>
        //- Bring the JSON into memory.
        <Rock:FromJson x:Key="People">{{ people }}</Rock:FromJson>
        
        //- Define the item template for the list.
        <DataTemplate x:Key="PersonItem">
            <Rock:ItemViewCell>
                <Border StrokeShape="RoundRectangle 12"
                        StyleClass="px-16">
                    <Label Text="{Binding name}"
                           StyleClass="title2, text-interface-stronger"
                           VerticalTextAlignment="Center" />
                </Border>    
            </Rock:ItemViewCell>
        </DataTemplate>
    </Grid.Resources>

    //- List the items, with the in memory items.
    <Rock:ItemsCollection ItemHeight="75"
                          ItemSpacing="8"
                          CollectionPadding="16"
                          ItemsSource="{StaticResource People}"
                          ItemTemplate="{StaticResource PersonItem}">
    </Rock:ItemsCollection>
</Grid>

Login Status

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.

Properties

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.

NoProfileIconColor

Color

If set this will paint the NoProfileIcon image with the specified color.

NotLoggedInIcon

string

The image that is displayed if no user is logged in. Defaults to resource://Rock.Mobile.Resources.person-no-photo-unknown.svg.

NotLoggedInColor

Color

If set this will paint the NotLoggedInIcon image with the specified color.

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

Color

The color to use when drawing the border around the profile image. Defaults to White.

TitleFont

Font

The font to use when rendering the Title text.

TitleFontSize

double

The size of the font to use when rendering the Title text.

TitleTextColor

Color

The color to use when rendering the Title text.

SubTitleFont

Font

The font to use when rendering the SubTitle text.

SubTitleFontSize

double

The size of the font to use when rendering the SubTitle text.

SubTitleTextColor

Color

The color to use when rendering the SubTitle text.

Example

<Rock:LoginStatus />

Update Photo

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.

Login Status Photo

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.

Properties

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

Color

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

Color

Provides a way to quickly change the color of the entire image when drawing the "logged in but no profile photo" image.

ProfilePhotoStrokeColor

Color

The color to use when drawing the border around the profile 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.

Example

<Rock:LoginStatusPhoto />

Lottie View

A component that seamlessly displays engaging animations to enhance your mobile app's user experience.

Quick Links

  1. Lottie Files Gallery

Lottie Files

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.

Properties

Property
Type
Description

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.

RepeatMode

RepeatMode

The way in which to repeat the animation. Default is Restart.

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.

Repeat Mode

Value
Description

Restart

Restarts the animation from the beginning.

Reverse

Reverses the animation from the end back to the beginning.

Examples

<Rock:LottieView Source="https://church.com/lottiefile.json"
    HeightRequest="64"
    WidthRequest="64" />

Markdown

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!

Properties

Property
Type
Description

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.

Supported Syntax

Example(s)

Headings

# h1 Heading
## h2 Heading
### h3 Heading
#### h4 Heading
##### h5 Heading
###### h6 Heading

Bold

**This is bold text**
__This is bold text__

Italic

*This is italic text*
_This is italic text_

Unordered List

+ Create a list by starting a line with `+`, `-`, or `*`
+ Sub-lists are made by indenting 2 spaces:
- Marker character change forces new list start:
    * Ac tristique libero volutpat at
    + Facilisis in pretium nisl aliquet
    - Nulla volutpat aliquam velit
+ Very easy!

Ordered List

1. Lorem ipsum dolor sit amet
2. Consectetur adipiscing elit
3. Integer molestie lorem at massa

Inline Code

Inline `code`

Code Fence

``` Sample code here ```

Links

[link text](https://www.rockrms.com)
[link with title](https://www.rockrms.com "Visit Rock!")

Image

![Minion](https://octodex.github.com/images/stormtroopocat.jpg)
<Rock:Markdown>
    <![CDATA[
    # Heading
    This is some **bold** text.
    ]]>
</Rock:Markdown>

Media Player

Stream content directly into your Rock Mobile application, with a ton of rich features built in.

Inherits from Maui.CommunityToolkit.MediaElement

The Media Player was heavily updated in version 6. If you need to see the documentation for the legacy component, you can view that here.

For those upgrading, all of the previously existing properties should work, but are considered deprecated.

Properties

Property Name
Type
Description

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.

Watch Map Properties

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.

Inherited Properties

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.

Property
Type
Description
Default Value

Aspect

Aspect

Determines the scaling mode for the (visual) media that

Aspect.AspectFit

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

Examples

<Rock:MediaPlayer Source="https://example.com/video_file.mp4" 
                  ShouldAutoPlay="false" />
<Grid>
    {% mediaelement id:'1' %}
        {% assign interactionGuid = null %}
        {% assign watchMap = null %}
        
        {% if CurrentPerson and CurrentPerson != null %}
            {% sql personId:'{{ CurrentPerson.Id }}' mediaId:'{{ mediaelement.Id }}' %}
SELECT TOP 1

[I].[Guid],
[I].[InteractionData]

FROM [Interaction] AS [I]
INNER JOIN [InteractionComponent] AS [IComp] ON [IComp].[Id] = [I].[InteractionComponentId]
INNER JOIN [InteractionChannel] AS [IChan] ON [IChan].[Id] = [IComp].[InteractionChannelId]
INNER JOIN [PersonAlias] AS [PA] ON [PA].[Id] = [I].[PersonAliasId]

WHERE [IChan].[Guid] = 'D5B9BDAF-6E52-40D5-8E74-4E23973DF159'
  AND [PA].[PersonId] = @personId
  AND [IComp].[EntityId] = @mediaId
  AND [I].[InteractionDateTime] >= DATEADD(DAY, -7, GETDATE())

ORDER BY [I].[InteractionDateTime] DESC
            {% endsql %}
            
            {% assign result = results | First %}
            {% if result != null %}
                {% assign interactionGuid = result.Guid %}
                {% assign watchMap = result.InteractionData | FromJSON | Property:'WatchMap' %}
            {% endif %}
        {% endif %}

        <Rock:MediaPlayer Source="{{ mediaelement.DefaultFileUrl | Escape }}"
            ThumbnailSource="{{ mediaelement.DefaultThumbnailUrl | Escape }}">
            <Rock:MediaPlayer.WatchMap>
                <Rock:WatchMapParameters MediaElementGuid="{{ mediaelement.Guid }}"
                    {% if interactionGuid != null %}
                        InteractionGuid="{{ interactionGuid }}"
                        WatchMap="{{ watchMap }}"
                    {% endif %}
                    />
            </Rock:MediaPlayer.WatchMap>
        </Rock:MediaPlayer>
    {% endmediaelement %}
</Grid>

This second example shows how to configure the MediaPlayer to save the watch interaction when watching a media element video.

Legacy

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.

Properties

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

View

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

View

The view tree to be used as the on-screen controls. Defaults to the standard screen controls you normally see.

PlaybackCompletedCommand

Command

The command to be executed when the media plays to the end.

PlaybackCompletedCommandParameter

object

The parameter to pass to the PlaybackCompletedCommand.

WatchMap

WatchMapParameters

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.

Watch Map Properties

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.

Examples

<Rock:MediaPlayer Source="https://example.com/video_file.mp4"
                  AutoPlay="false" />
<StackLayout>
    {% mediaelement id:'1' %}
        {% assign interactionGuid = null %}
        {% assign watchMap = null %}
        
        {% if CurrentPerson and CurrentPerson != null %}
            {% sql personId:'{{ CurrentPerson.Id }}' mediaId:'{{ mediaelement.Id }}' %}
SELECT TOP 1

[I].[Guid],
[I].[InteractionData]

FROM [Interaction] AS [I]
INNER JOIN [InteractionComponent] AS [IComp] ON [IComp].[Id] = [I].[InteractionComponentId]
INNER JOIN [InteractionChannel] AS [IChan] ON [IChan].[Id] = [IComp].[InteractionChannelId]
INNER JOIN [PersonAlias] AS [PA] ON [PA].[Id] = [I].[PersonAliasId]

WHERE [IChan].[Guid] = 'D5B9BDAF-6E52-40D5-8E74-4E23973DF159'
  AND [PA].[PersonId] = @personId
  AND [IComp].[EntityId] = @mediaId
  AND [I].[InteractionDateTime] >= DATEADD(DAY, -7, GETDATE())

ORDER BY [I].[InteractionDateTime] DESC
            {% endsql %}
            
            {% assign result = results | First %}
            {% if result != null %}
                {% assign interactionGuid = result.Guid %}
                {% assign watchMap = result.InteractionData | FromJSON | Property:'WatchMap' %}
            {% endif %}
        {% endif %}

        <Rock:MediaPlayer Source="{{ mediaelement.DefaultFileUrl | Escape }}"
            ThumbnailSource="{{ mediaelement.DefaultThumbnailUrl | Escape }}">
            <Rock:MediaPlayer.WatchMap>
                <Rock:WatchMapParameters MediaElementGuid="{{ mediaelement.Guid }}"
                    {% if interactionGuid != null %}
                        InteractionGuid="{{ interactionGuid }}"
                        WatchMap="{{ watchMap }}"
                    {% endif %}
                    />
            </Rock:MediaPlayer.WatchMap>
        </Rock:MediaPlayer>
    {% endmediaelement %}
</StackLayout>

This second example shows how to configure the MediaPlayer to save the watch interaction when watching a media element video.

Closed Captioning

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:

LogoDisplay subtitles and captions on iPhoneApple Support

Notification Box

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.

Properties

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.

NotificationType

NotificationType

The type of notification to display. Defaults to Information.

Notification Type

  • Information

  • Success

  • Validation

  • Warning

  • Error

  • Primary

  • Secondary

  • Dark

  • Light

Example

<Rock:NotificationBox NotificationType="Information"
                      HeaderText="Information Needed"
                      Text="Please update your information below to keep our records current." />

Paragraph Text

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.

Properties

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.

Example

<Rock:ParagraphText>
    Leverage agile frameworks to provide a robust synopsis for high level 
    overviews. Iterative approaches to corporate strategy foster collaborative 
    thinking to further the overall value proposition. Organically grow the
    holistic world view of disruptive innovation via workplace diversity 
    and empowerment.
    Bring to the table win-win survival strategies to ensure proactive 
    domination. At the end of the day, going forward, a new normal that has 
    evolved from generation X is on the runway heading towards a streamlined 
    cloud solution. User generated content in real-time will have multiple 
    touchpoints for offshoring.
    Capitalize on low hanging fruit to identify a ballpark value added 
    activity to beta test. Override the digital divide with additional 
    clickthroughs from DevOps. Nanotechnology immersion along the information 
    highway will close the loop on focusing solely on the bottom line.
</Rock:ParagraphText>

Don't worry if your paragraphs have more than one line-break between them. All extra line breaks will be ignored.

QR Code

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.

Properties

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.

Level

ECCLevel

The ECC Level to be applied to the generated QR code. Defaults to M.

Content

string

The actual content to be encoded into the QR Code.

ECCLevel

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.

Example

<Rock:QRCode Content="{{ CurrentPerson.Guid }}" />

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.

Ratio View

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.

Properties

Ratio

string

The ratio to constrain the view to (ex: "16:9").

Example

<Rock:RatioView Ratio="16:9">
    <Rock:Image Source="example.com/image.png" />
</Rock:RatioView>

Redirect

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.

Properties

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.

Example

<Rock:Redirect PageGuid="8beefd7c-9939-4892-9cb2-243e58fca457"
    QueryString="ItemType=Person&amp;ItemId=4823" />

Responsive Column

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.

Properties

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.

Responsive Layout

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.

Properties

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.

Basic Example

<Rock:ResponsiveLayout ColumnCount="2">
    <Rock:ResponsiveColumn ExtraSmall="1">
        <Rock:Image Source="https://image.source.com/image.png" Aspect="AspectFill"/>
    </Rock:ResponsiveColumn>
    <Rock:ResponsiveColumn ExtraSmall="1">
        <Rock:Image Source="https://image.source.com/image.png" Aspect="AspectFill"/>
    </Rock:ResponsiveColumn>
</Rock:ResponsiveLayout>

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.

Responsive Example

<Rock:ResponsiveLayout>
    <Rock:ResponsiveColumn Small="7" Medium="9" ExtraSmallOrder="1" SmallOrder="0">
        <Label Text="This is our main body content." />
    </Rock:ResponsiveColumn>
    <Rock:ResponsiveColumn Small="5" Medium="3" ExtraSmallOrder="0" SmallOrder="1">
        <Label Text="This might be our navigation menu" />
    </Rock:ResponsiveColumn>
</Rock:ResponsiveLayout>

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.

Advanced Example

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.

<Rock:ResponsiveLayout>
    <Label Text="This is our main body content."
           Rock:ResponsiveLayout.Small="7"
           Rock:ResponsiveLayout.Medium="9"
           Rock:ResponsiveLayout.ExtraSmallOrder="1"
           Rock:ResponsiveLayout.SmallOrder="0" />
    <Label Text="This might be our navigation menu."
           Rock:ResponsiveLayout.Small="5"
           Rock:ResponsiveLayout.Medium="3"
           Rock:ResponsiveLayout.ExtraSmallOrder="0"
           Rock:ResponsiveLayout.SmallOrder="1" />
</Rock:ResponsiveLayout>

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.

Styling

This layout offers a couple of unique style classes to help ease customization.

Property
Type
Description

-rock-responsive-layout-row-spacing

int

Sets the Row Spacing property.

-rock-responsive-layout-column-spacing

int

Sets the Column Spacing property.

Scroll View

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

Properties

Property
Type
Description

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

NoSafeArea

bool

On iOS, this removes any ContentAreaInset (safe area padding) from the ScrollView.

Example

<Rock:ScrollView IsBounceEnabled="False">
    <StackLayout>
        <Label Text="This scroll view does not bounce when you scroll past it!" />
    </StackLayout>
</Rock:ScrollView>

Segment Picker

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.

Properties

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.

Note that you cannot set the background-color via CSS, however the BackgroundColor property in XAML works just fine.

Example

<Rock:SegmentPicker>
    <Rock:PickerItem Value="12"
        Text="All" />
    <Rock:PickerItem Value="13"
        Text="Men" />
    <Rock:PickerItem Value="14"
        Text="Women" />
</Rock:SegmentPicker>

Styling

You can target special CSS properties to style certain aspects of the picker.

Property
Type
Description

-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.

^SegmentPicker {
  -rock-tint-color: red;
  -rock-selected-tint-color: orange;
}

Styled Border

Inherits from Border

Overview

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.

Styling

The following CSS classes are available for use with this control:

CSS Property
Corresponding Property
Description

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.

Example

<Rock:StyledBorder
    StyleClass="border, bg-interface-softest, border-primary-strong, p-16">
    <Label Text="Borders borders borders oh my!" />
</Rock:StyledBorder>

Styled View

Inherits from Border

This component was introduced with the original Xamarin Forms release of Rock Mobile, offering functionality that exceeded what was achievable at the time. Although it remains functional, you might want to consider using a Border element instead, as it can handle most of the same styling requirements.

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.

Properties

Property

Type

Description

BackgroundGradientAngle

int

A value between 0-360 to define the angle of the background gradient.

BackgroundGradientStartColor

Color

The start color of the background gradient.

BackgroundGradientEndColor

Color

The end color of the background gradient.

BackgroundGradientStops

GradientStop[]

A list of GradientStop objects that define a multi color background gradient.

BorderColor

Color

The color of the border.

BorderGradientAngle

int

A value between 0-360 to define the angle of the border gradient.

BorderGradientStartColor

Color

The start color of the border gradient.

BorderGradientEndColor

Color

The end color of the border gradient.

BorderGradientStops

GradientStop[]

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.

Gradient Stop

Property

Type

Description

Color

Color

The color to use for this segment of the gradient.

Offset

float

Value between 0 and 1 that specifies the stop point offset.

Examples

<Rock:StyledView BackgroundColor="#bc91d7"
    CornerRadius="60,0,0,60"
    IsClippedToBounds="true"
    HorizontalOptions="FillAndExpand"
    HeightRequest="150" />

Gradient Stops

<Rock:StyledView HeightRequest="300">
    <Rock:StyledView.BackgroundGradientStops>
        <Rock:GradientStop Color="Yellow"
            Offset="0.0" />
        <Rock:GradientStop Color="Green"
            Offset="0.5" />
    </Rock:StyledView.BackgroundGradientStops>
</Rock:StyledView>

Linear Gradient Brush

This can be applied to more than StyledViews: https://docs.microsoft.com/en-us/xamarin/xamarin-forms/user-interface/brushes/lineargradient

<Rock:StyledView HeightRequest="300">
    <Rock:StyledView.Background>
        <LinearGradientBrush StartPoint="0,0"
            EndPoint="1,1">
            <GradientStop Color="Pink"
                Offset="0.0" />
            <GradientStop Color="Purple"
                Offset="0.5" />
        </LinearGradientBrush>
    </Rock:StyledView.Background>
</Rock:StyledView>

Tag

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.

Properties

Property
Type
Description

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.

<Rock:Tag Text="Articles"
     Type="Primary"
     Size="Default" />

Structure

When styling tags via CSS, it's helpful to understand how this control is built. The Tag contains two underlying controls:

  1. Styled View – This is the container control

  2. 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.

The corner radius for Tags is calculated automatically by the shell to ensure the rounding is always correct regardless of the content or padding.

To style the text of a tag you'd want to have a style similar to:

.tag ^Label {
    color: red;
}

Toggle Button

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.

CSS Classes

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.

Class
Description

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.

Properties

Property
Type
Description

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.

Example

<Rock:ToggleButton Text="Include Completed"
    IsChecked="True" />

Web View

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.

Display & Troubleshooting

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.

<meta name="viewport" content="width=device-width, initial-scale=1">

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.

If the embedded web page contains an iframe and only a blank page is shown, it may be a CORS issue. On iOS, these errors are "swallowed" meaning nothing will be shown.

Keep in mind the domain of your API URL that the shell connects to your server with.

Properties

Property
Type
Description

Source

string

The initial URL to be used when the WebView first loads.

<Rock:WebView Source="https://rock.rocksolidchurchdemo.com/page/482" />

Developer Controls

Execute Command

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.

Properties

Property
Type
Description

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.

Example

In this example we used in an app to welcome people with a periodic toast message like, "Welcome to Rock Solid Church!!".

<Rock:ExecuteCommand
            Command="{Binding ShowToast}"
            CommandParameter="Welcome to Rock Solid Church!!"
            Delay="3000"
            Repeat="true"/>
  • 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).

Bible Book And Chapter Picker

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.

Properties

Property

Type

Description

Reference

string

The reference text based on the selections the user made.

Command

ICommand

The command to be executed after the user has made their selection.

CommandParameter

object

The parameter to be passed to the Command.

Styling

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.

Book Page

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.

Chapter Page

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:

<ContentView StyleClass="bible-chapter-content">
    <Frame HasShadow="false" StyleClass="bible-chapter-frame">
        <Label StyleClass="bible-chapter" Text="1" />
    </Frame>
</ContentView>

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.

Command Reference

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

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

Field Stack

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.

Properties

Property

Type

Description

BorderColor

Color

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.

Media Cast Button

Inherits from Xamarin.Forms.View

Renders a button on the screen that can be used by the user to select a Cast (Android) or AirPlay (iOS) device to stream any currently playing media to.

This control currently has no properties that can be customized.

Example

<Rock:MediaCastButton />

Media Progress Bar

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.

Properties

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

Color

The color of the track background for the region that has not been played. Defaults to 50% gray at 65% opacity.

TrackProgressColor

Color

The color of the track background for the played region. Defaults to the application's primary color.

ThumbColor

Color

The color of the thumb knob. Defaults to White.

Example

<Rock:MediaProgressBar Duration="{Binding Duration}"
                       Position="{Binding Position}" />

Parameter

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.

Example

<StackLayout>
    <Rock:FieldContainer>
        <Rock:TextBox x:Name="tbSearch" Label="Search For" />
    </Rock:FieldContainer>
    
    <Button StyleClass="btn,btn-primary"
            Text="Search"
            Command="{Binding PushPage}">
        <Button.CommandParameter>
            <Rock:PushPageParameters PageGuid="8fedc079-e133-4577-bc11-35c24d5e439e">
                <Rock:Parameter Name="q"
                                Value="{Binding Source={x:Reference tbSearch}, Path=Text}" />
            </Rock:PushPageParameters>
        </Button.CommandParameter>
    </Button>
</StackLayout>

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.

Scan Code

Inherits from Xamarin.Forms.ContentView

This is a special control that allows you to initiate a scan of a barcode.

Properties

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.

Mode

CameraMode

The mode to be used with the camera. Defaults to Manual.

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)

Camera Mode

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.

Example

<Rock:ScanCode x:Name="scanner"
               Command="{Binding PushPage}"
               Mode="Automatic">
    <Rock:ScanCode.CommandParameter>
        <Rock:PushPageParameters PageGuid="d6260c47-7364-405b-883c-f533b244a175">
            <Rock:Parameter Name="code"
                            Value="{Binding Source={x:Reference scanner}, Path=Value}" />
        </Rock:PushPageParameters>
    </Rock:ScanCode.CommandParameter>
</Rock:ScanCode>

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.

<Rock:ScanCode x:Name="scanner"
               Command="{Binding PushPage}">
    <Rock:ScanCode.Template>
        <Button Text="Custom Button"
                StyleClass="btn,btn-default"
                Command="{Binding Source={x:Reference scanner}, Path=Scan}" />
    </Rock:ScanCode.Template>
    <Rock:ScanCode.CommandParameter>
        <Rock:PushPageParameters PageGuid="d6260c47-7364-405b-883c-f533b244a175">
            <Rock:Parameter Name="code"
                            Value="{Binding Source={x:Reference scanner}, Path=Value}" />
        </Rock:PushPageParameters>
    </Rock:ScanCode.CommandParameter>
</Rock:ScanCode>

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.

Validator

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.

Properties

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.

Example

<Rock:FieldContainer>
    <Rock:TextBox x:Name="term"
                  Name="Search For"
                  IsRequired="true" />
</Rock:FieldContainer>

<Rock:Validator x:Name="validator">
    <x:Reference>term</x:Reference>
</Rock:Validator>

<Button StyleClass="btn,btn-primary"
        Text="Search"
        Command="{Binding Callback}">
    <Button.CommandParameter>
        <Rock:CallbackParameters Name="Search"
                                 Validator="{x:Reference validator}">
            <Rock:Parameter Name="SearchTerm"
                            Value="{Binding Text, Source={x:Reference term}}" />
        </Rock:CallbackParameters>
    </Button.CommandParameter>
</Button>

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.

Volume Control

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.

Example

<Rock:VolumeControl />

Zone

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.

Properties

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.

Example

<Rock:Zone ZoneName="Main" />

Effects

What effects do you have access to in Rock Mobile?

An effect is something that is applied to an element in XAML to change it's default appearance or behavior. Usually this is something that is platform specific, though not always.

Example Effect

<StackLayout>
    <!-- StackLayout content goes here -->
    <StackLayout.Effects>
        <!-- Effects would go here to apply to the element -->
    </StackLayout.Effects>
</StackLayout>

Blur Effect

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:

<Rock:ContainedCard HeightRequest="300" 
    BackgroundColor="Transparent"
    HasShadow="False">
    <Label TextColor="White" 
        Text="Ultra Thin Blurred Card" />
    <Rock:ContainedCard.Effects>
        <Rock:BlurEffect BlurStyle="UltraThin" />
    </Rock:ContainedCard.Effects>
</Rock:ContainedCard>

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.

<Grid VerticalOptions="FillAndExpand">
    <StackLayout VerticalOptions="FillAndExpand">
        <Rock:Image Source="https://server.com/photo.jpg" />
    </StackLayout>
    
    <ContentView VerticalOptions="Start">
        <ContentView.Effects>
            <Rock:BlurEffect BlurStyle="UltraThin" />
            
            <Rock:SafeAreaPaddingEffect Edges="Top" />
        </ContentView.Effects>
    </ContentView>
</Grid>
Status Bar Blur Effect

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.

Properties

The following properties are available to the effect.

Property
Type
Description

BlurStyle

IOSBlurStyle

What type of blur style would you like to be applied?

Blur Style

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:

Safe Area Padding Effect

Safe Area Padding Effect

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.

Properties

Property

Type

Description

Edges

SafeAreaEdge

The edges that should have padding applied to them. Defaults to All.

Safe Area Edge

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.

You may have noticed the mention of "padding" above. Because we are modifying the Padding property, this effect only works on layout type elements.

Example

<ContentView BackgroundColor="Blue">
    <ContentView.Effects>
        <Rock:SafeAreaPaddingEffect Edges="Top" />
    </ContentView.Effects>
    <Label Text="This label will vertically be below any unsafe area." />
</ContentView>

Form Fields

Rock Mobile supports several custom form fields. This page contains information on using form fields and covers each of the various field types.

Using Form Fields

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.

<Rock:TextBox Label="Name" Placeholder="Your Name" />

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.

<Rock:FieldContainer>
        <Rock:TextBox Label="Name" Placeholder="Your Name" />
</Rock:FieldContainer>

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.

Attribute Value Editor

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.

Properties

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.

Example

<Rock:FieldContainer>
    <Rock:AttributeValueEditor Label="Start Date"
                               Value="2020-07-04T00:00:00-07:00"
                               FieldType="Rock.Field.Types.DateFieldType" />
</Rock:FieldContainer>

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.

var attr = CurrentPerson.Attributes["BaptismDate"];

var xamlFragment = string.Format( @"<Rock:AttributeValueEditor
    Label=\"{0}\"
    IsRequired=\"{1}\"
    FieldType=\"{2}\"
    ConfigurationValues=\"{{}}{3}\"
    Value=\"{4}\" />",
    attr.Name.EncodeXml( true ),
    attr.IsRequired,
    attr.FieldType.Class,
    attr.QualifierValues.ToDictionary( a => a.Key, a => a.Value.Value ).ToJson().EncodeXml( true ),
    CurrentPerson.GetAttributeValue( attr.Key ).EncodeXml( true ) );

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:

using Rock.Mobile;

var attributes = CurrentPerson.Attributes.Values.ToList();
var xamlFragment = MobileHelper.GetEditAttributesXaml( CurrentPerson, attributes );

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.

Address

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.

Properties

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.

Example

<Rock:FieldContainer>
    <Rock:Address Label="Rock Address" IsRequired="false" />
</Rock:FieldContainer>

If you need to provide a default address to be displayed when the view is rendered, you can do so as follows:

<Rock:FieldContainer>
    <Rock:Address Title="Rock Address" IsRequired="false">
        <Rock:Address.SelectedAddress>
            <Common:MobileAddress Street1="1885 Lost Ln"
                                  City="Knowhere"
                                  State="CA"
                                  PostalCode="92710"
                                  Country="USA" />
        </Rock:Address.SelectedAddress>
    </Rock:Address>
</Rock:FieldContainer>

Campus Picker

Inherits from Picker

The Campus Picker view is a picker that automatically populates with the campuses configured on the Rock server. The user can then select a campus from the list of items.

Properties

See Picker for available properties.

Example

<Rock:FieldContainer>
    <Rock:CampusPicker Label="Rock Campus Picker"
                       IsRequired="false"
                       SelectedValue="76882AE3-1CE8-42A6-A2B6-8C0B29CF8CF8" />
</Rock:FieldContainer>

Check Box

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.

Properties

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.

EditStyle

CheckBoxStyle

The style to use when displaying the edit control. Defaults to CheckBox.

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.

Check Box Style

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.

Example

<Rock:FieldContainer>
    <Rock:CheckBox Label="Show All"
                   EditStyle="Switch"
                   Color="#ee7725" />
</Rock:FieldContainer>

Check Box List

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.

Properties

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.

Example

<Rock:FieldContainer>
    <Rock:CheckBoxList Label="Categories">
        <Rock:Parameter Name="All Church" Value="38" />
        <Rock:Parameter Name="Men" Value="39" />
        <Rock:Parameter Name="Women" Value="40" />
    </Rock:CheckBoxList>
</Rock:FieldContainer>

Currency Box

Inherits from NumberBox

The Currency Box view provides an input box for the user to enter a currency amount. It ensures the value is a valid decimal amount during validation.

Properties

See NumberBox for available properties.

Example

<Rock:FieldContainer>
    <Rock:CurrencyBox Label="Rock Currency Box"
                      IsRequired="false"
                      Text="23.98" />
</Rock:FieldContainer>

Date Picker

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.

Properties

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.

DatePickerStyle

This property/enum only makes a difference on iOS.

Name
Description

Wheels

The default value -- displays the Wheels style date picker.

Inline

A calendar style date picker.

Example

<Rock:FieldContainer>
    <Rock:DatePicker Label="Rock Date Picker"
        IsRequired="false"
        SelectedDate="7/4/2019" />
</Rock:FieldContainer>
Native date picker on iOS

How to update the year is not immediately apparent on Android - you must tap the year at the top and not the date between the arrows.

Native date picker on Android
<Rock:FieldContainer>
    <Rock:DatePicker Label="Rock Date Picker"
        IsRequired="false"
        SelectedDate="7/4/2019"
        DatePickerStyle="inline" />
</Rock:FieldContainer>
Native iOS picker with an Inline DatePickerStyle.

Email Box

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.

Properties

See TextBox for available properties.

Example

<Rock:FieldContainer>
    <Rock:EmailBox Label="Rock Email Box"
                   IsRequired="false"
                   Text="ted@rocksolidchurchdemo.com" />
</Rock:FieldContainer>

Literal

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.

Properties

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.

Example

<Rock:FieldContainer>
    <Rock:Literal Label="Category" Text="All Church" />
</Rock:FieldContainer>

Marital Status Picker

Inherits from Picker.

This control is only available in Shell v2 and later. It also requires your Rock Server to be on v1.13.0 or later as it needs the server to send down the Marital Status Defined Values.

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.

Example

<Rock:MaritalStatusPicker Label="Marital Status" IsRequired="true" />

Multi Picker

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.

Properties

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)

Example

<Rock:FieldContainer>
    <Rock:MultiPicker Label="Rock Multi Picker"
                      IsRequired="false"
                      SelectedValues="1,3,5">
        <Rock:PickerItem Value="1" Text="One" />
        <Rock:PickerItem Value="2" Text="Two" />
        <Rock:PickerItem Value="3" Text="Three" />
        <Rock:PickerItem Value="4" Text="Four" />
        <Rock:PickerItem Value="5" Text="Five" />
    </Rock:MultiPicker>
</Rock:FieldContainer>

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.

Number Box

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.

Properties

See TextBox for available properties.

Example

<Rock:FieldContainer>
    <Rock:NumberBox Label="Rock Number Box"
                    IsRequired="false"
                    Text="-1325" />
</Rock:FieldContainer>

Phone Number Box

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.

Properties

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.

Example

<Rock:FieldContainer>
    <Rock:PhoneNumberBox Label="Rock Phone Number Box"
                         IsRequired="false"
                         CountryCode="1"
                         PhoneNumber="(800) 555-1234" />
</Rock:FieldContainer>

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.

Picker

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.

Properties

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)

Example

<Rock:FieldContainer>
    <Rock:Picker Label="Rock Picker"
                 IsRequired="false"
                 SelectedValue="2">
        <Rock:PickerItem Value="1" Text="One" />
        <Rock:PickerItem Value="2" Text="Two" />
        <Rock:PickerItem Value="3" Text="Three" />
        <Rock:PickerItem Value="4" Text="Four" />
        <Rock:PickerItem Value="5" Text="Five" />
    </Rock:Picker>
</Rock:FieldContainer>

Text Box

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.

Properties

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.

<Rock:FieldContainer>
    <Rock:TextBox Label="Rock Text Box"
        IsRequired="false"
        Text="Rock Lobster!" />
</Rock:FieldContainer>

Disabled Styling

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.

 <StackLayout>
     ...
    <StackLayout.Resources>
        <Style TargetType="Rock:TextBox">
            <Setter Property="VisualStateManager.VisualStateGroups">
                <VisualStateGroupList>
                    <VisualStateGroup x:Name="CommonStates">
                        <VisualState x:Name="Disabled">
                            <VisualState.Setters>
                                <Setter Property="TextColor"
                                    Value="{Rock:PaletteColor Gray-500}" />
                            </VisualState.Setters>
                        </VisualState>
                    </VisualStateGroup>
                </VisualStateGroupList>
            </Setter>
        </Style>
    </StackLayout.Resources>
</StackLayout>

Text Editor

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.

If you want to set initial text that contains new line characters, you will need to either encode them as an XML escape sequence or use the alternate assignment method. The escape sequences for Carriage Return and Line Feed respectively are &#x0d and &#x0a.

Properties

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.

Example

<Rock:FieldContainer>
    <Rock:TextEditor Label="Comments"
                     IsRequired="false"
                     HeightRequest="200"
                     Text="Some default text&#x0aon two lines." />
</Rock:FieldContainer>

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.

<Rock:FieldContainer>
    <Rock:TextEditor Label="Comments"
                     IsRequired="false"
                     HeightRequest="200">
        <Rock:TextEditor.Text>
<![CDATA[Some default text
on two lines.]]>
        </Rock:TextEditor.Text>
</Rock:FieldContainer>

Whichever method you choose, you will need to ensure that you have encoded any XML characters, such as <, >, or &.

XAML Extensions

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:

<Binding Path="Text" Source="{x:Reference textbox}" />

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:

{Binding Path=Text, Source={x:Reference textbox}}

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:

{Binding Path='Hello, Daniel', Source={x:Reference textbox}}

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.

Boolean Value Converter

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.

Properties

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.

Example

<Rock:Icon IconClass="{Binding IsPlaying, Converter={Rock:BooleanValueConverter True=pause, False=play}}"
           IconFamily="MaterialDesignIcons" />

This example would change the IconClass property to either play or pause depending on the boolean value we are binding to.

From Json

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.

Properties

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

Example

<StackLayout>
    <StackLayout.Resources>
        <Rock:FromJson x:Key="Series">
            {}{{ seriesJSON | XamlWrap }}
        </Rock:FromJson>
    </StackLayout.Resources>
    
    <Label Text="{Binding Name, Source={StaticResource Series}}" />
</StackLayout>

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.

Because the JSON contents might have some special characters in them we are using the XamlWrap to ensure any special characters are taken care of. You should do the same.

Lets break open that FromJson tag a bit and see what it might look like after it's parsed by the server-side Lava.

<Rock:FromJson x:Key="Series">
{}{ "Name": "Exploring John", "MessageCount": 7 }
</Rock:FromJson>

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.

Inverse Boolean Converter

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

<Label Text="Something"
       IsVisible="{Binding HideLabel, Converter={Rock:InverseBooleanConverter}}" />

Nullable Guid Converter

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.

<Rock:Parameter Name="Guid"
    Value="{Binding ItemGuid, Converter={Rock:NullableGuidConverter}}" />

In this example, the string Guid value within ItemGuid would be converted to a Guid type.

On Device Platform

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.

<Label Text="{OnPlatform iOS=Hello iOS!, Android=Hello Android!}" />
<ContentView>
    <OnPlatform x:TypeArguments="View">
        <On Platform="iOS"><Label Text="Hello iOS"/></On>
        <On Platform="Android"><Label Text="Hello Android"/></On>
    </OnPlatform>
</ContentView>

You can also style platforms independently via Custom CSS classes.


Below is legacy documentation for the original Rock:OnDevicePlatform extension.

Properties

Property
Type
Description

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.

Examples

<Label Text="Hello World!"
    TextColor="{Rock:OnDevicePlatform Android=Blue, iOS=Red, Default=Black}" />

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.

<StackLayout>
    <Rock:OnDevicePlatform>
        <Rock:OnDevicePlatform.Android>
            <Button Text="Go" />
        </Rock:OnDevicePlatform.Android>
        <Rock:OnDevicePlatform.Default>
            <Label Text="This feature required Android." />
        </Rock:OnDevicePlatform.Default>
    </Rock:OnDevicePlatform>
</StackLayout>

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.

On Device Type

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.

Properties

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.

Example

<Image Source="https://www.rocksolidchurchdemo.com/GetImage.ashx?guid=923329f4-819e-4eaa-8d96-9611624736e8"
       HeightRequest="{Rock:OnDeviceType Phone=300, Tablet=150}" />

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.

<StackLayout>
    <Rock:OnDeviceType>
        <Rock:OnDeviceType.Tablet>
            <Button Text="Go" />
        </Rock:OnDeviceType.Tablet>
        <Rock:OnDeviceType.Default>
            <Label Text="This feature requires a tablet." />
        </Rock:OnDeviceType.Default>
    </Rock:OnDeviceType>
</StackLayout>

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.

Palette Color

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.

Properties

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

Example

<Label Text="Welcome to Rock!"
       TextColor="{Rock:PaletteColor App-Primary}" />

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.

Seconds To Time String Converter

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.

Properties

Property

Type

Description

ShowHours

TimeSegmentVisibility

How to show the hours segment of the time string. Defaults to Automatic.

ShowMinutes

TimeSegmentVisibility

How to show the minutes segment of the time string. Defaults to Automatic.

ShowSeconds

TimeSegmentVisibility

How to show the seconds segment of the time string. Defaults to Automatic.

Time Segment Visibility

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.

Example

<Label Text="{Binding Value, Converter={Rock:SecondsToTimeStringConverter ShowMinutes=Always}}" />