This guide will walk you through the process of creating a new mobile application in Rock: adding some content, deploying, and finally testing with the Rock Mobile Core app. When we're finished you'll have everything you need to begin building the app of your dreams.

Deployment

Navigating to the Application page for your app shows the deployment status in the top right. New apps start as Not Deployed, so you'll need to click the Deploy button in the bottom right corner to test your app. The first deploy may take a few moments, but generally this process happens quickly.

Note that making changes to the app (like adding new pages and blocks or changing block settings and application colors) will require you to Deploy again, as well as reloading the app, to see the changes. Changes to Content blocks that have a Dynamic Content value of Yes will be shown without a new deployment. When a user opens the app and is shown the splash / launch screen the app is pulling the latest deployment from your server (or wherever your bundle is hosted).

Testing

The best way to test your application is using the Rock Mobile Core app available on the app stores.

Apple / iOS: https://apps.apple.com/us/app/rock-mobile-showcase/id1498547817 Google / Android: https://play.google.com/store/apps/details?id=org.sparkdevnetwork.rockmobile

Simply tap and hold the screen with two fingers and a small popup with app information will appear. Tapping the App Switcher button will allow you to change the server to which the app connects.

The App Switcher page has three fields that are required to connect to your server. All of this information can be found by navigating to the application's internal page (under Home > CMS Configuration > Mobile Applications) and selecting your app. Let's take a look at each of them.

Application Id

This is the ID given to the application by Rock when it is created. It cannot be changed. To find your application ID, navigate to the Application page and find the Site/App Id in the top right. Alternatively, you can see the number in the URL bar.

API URL

This is simply the URL to your Rock server's API. The Public Application Root with /api will be your URL. For example: https://www.rockrms.com/api

API Key

This was configured when creating your application. You can change this value during development, but any apps using this key will need to update their App Switcher page in order to connect again.

When finished, your form will look something like this:

Tap the Launch App button to connect and view your app. The App Switcher page will remember what you've entered so you only have to do this once.

Rock Core App Connection

You can always connect back to the original Rock Mobile Core app if needed:

App Id 36

API URL https://www.rockrms.com/api

API Key rocksolidpihc

Publishing

When it comes time to publish your app into the stores, get started with App Factory.

Let's begin by creating a new mobile application within Rock. Mobile applications can be found under Admin Tools > CMS Configuration.

Select the Mobile Applications box to view a list of all the apps in your Rock instance.

Click the Plus icon to create a new app, or select a previously created app from the list below.

Now it's time to configure your app. There are some options that are not covered below; they are beyond the scope of this walkthrough. Start by filling in the Application Name and optional Description.

Application Type

You have three options when it comes to the Application Type. Choose what makes the most sense for your app; you can always change your selection later.

Blank (not recommended)

This option will not provide a Flyout panel or tabbed navigation. Generally you'll want one of those, so Blank should only be selected when you need to remove those elements for a specific use case.

Flyout (recommended)

This is the most common type of application and one your users will be familiar with. A menu icon (three horizonal bars) will be displayed in the top left of your app and when pressed will reveal a slide out panel form the left side. Users can also swipe from the left side of the screen to reveal the Flyout panel.

Tabbed

When this option is selected users will be shown a tabs at the bottom of the app. If your app only has a few top-level pages this can be a great alternative to the Flyout. Each page can have a custom image associated with it which is displayed above the name.

Lock Orientation

You can force the application to be locked in Portrait or Landscape mode for both phones and tablets. Generally you'll want to leave these set to the defaults of Portrait for the phone and empty for the tablet.

Application Pages

You'll have the option to set the Login, Profile, and Communication View pages here... but we haven't created them yet. Although this guide won't dig into setting these up, know that coming back to add these page links is important for the app to understand where these fundamental areas exist for navigation.

API Key

Bad: mobileapp, Rock, testing Better: Gr33nToolb0x, ctr2p7

Flyout XAML

If you've selected an Application Type of Flyout then you can customize what appears inside via XAML. The default template will include a <ListView> that references a {Binding MenuItems} source; this will automatically add any pages with the Display In Navigation option checked. It is recommended to leave this alone unless you need custom functionality.

Homepage Routing Logic

This documentation will help you with building your Rock Mobile application. Be sure to check back regularly for updates. You can browse this documentation using the sidebar on the left or by searching in the top right (use the keyboard shortcut Ctrl+K).

Rock Mobile uses blocks the same way as Rock Web does. You create pages, add blocks to them, and configure them. Then when you deploy your app all that information will get bundled up so the mobile app knows how to communicate with your site.

Many blocks are self-explanatory, though we're not saying they don't need some documentation too. We'll continue adding some helpful hints about all the blocks, such as what is available in Lava merges and what-not.

If there is missing or unclear documentation, please feel free to file a documentation request on our issues board.

Integrated Scroll

Some blocks will have built-in scrolling mechanics. This means that the Zone in which the block resides should not be placed within any sort of layout that provides scrolling (such as ScrollView). These blocks will have a special badge in the documentation, that looks like this:

In some cases, you may want a block to stretch to the full height of the zone (in 99% of cases, this entails the entire screen). In Xamarin, this was achieved by the use of a now-deprecated FillAndExpand property.

In MAUI, this is achieved through the use of an attached property. Within the block, you want to expand add a Rock:Zone.Expands="true" property on the outermost layout.

This section refers to the 'CMS' mobile block group.

This block is useful for quickly displaying content channel items like messages or promotions. Instead of writing an entity command to get the data, this block will pull the full content channel item for you.

It functions similarly to the Content block in that the XAML template is up to you to define. Its advantage lies in the built-in data pull and optional interaction write so you don't have to wire them up yourself.

Parameters

Context can be provided to the block via item Id or Guid; you don't need to pass both.

Settings

Template

The Lava commands that are enabled for this block will only Lava rendered on the server.

Merge Fields

Want big, styled images that you can overlay with Lava content? You're in the right place. Hero images are a great way to attractively display a picture with text overlay.

Example

This is an example of a display created using this block. The Background Image was set to a stock photo, and to render the title, the block setting was set to {{ CurrentPerson.FirstName }}.

Using Lava

In order to use Lava in this block, please make sure to enable the 'Process Lava on Server' under the 'Block Settings > Mobile Settings'. If you are struggling to find or enable this setting, here is a good example.

If you are unfamiliar with Lava, please check out our Lava Reference.

Block Settings

Title

The main title that overlays the Background Image. Lava enabled.

Subtitle

The text that overlays the image, underneath the title. Lava enabled.

Background Image

Phone: The image to display on a phone. Recommended to be at least 1024px wide, and at least double the height of the Height - Phone setting.

Tablet: The image to display on a tablet. Recommended to be at least 2048 pixels wide, and at least double the height of the Height - Tablet setting.

Height

Phone: The height of the rendered image on a phone.

Tablet: The height of the rendered image on a tablet.

Text Align

This setting allows you to align the overlayed text to the left, center or right side of the image.

Title Color

Sets the color of the Title.

Subtitle Color

Sets the color of the Subtitle.

Padding

The padding around the inside of the Background Image.

This Content Collection View block is designed to bring your content collections to life. It offers powerful search and filtering tools that work across all items in your collection, delivering results at incredibly fast speeds. Learn more about Rock's Content Collection feature here in the manual:

Bindings

<Rock:Divider IsVisible="{Binding IsLastItem, Converter={Rock:InverseBooleanConverter}}" />

Parameters

Settings

When saving a new app, or selecting an existing one from the list, you'll be taken to the Application page. The title bar will show the name of your app on the left and the Site/App Id on the right, as well as the deployment status. Underneath you'll find tabbed navigation for the different areas of your app and some of the configuration values you previously selected.

To begin adding content to our app we need to navigate to the Pages area. The homepage has already been created for you. Selecting this page will bring you to the page details area where you can change the configuration and add blocks, similar to the process on Rock web.

Let's add our first block by selecting the Content block and dragging it into the Main section.

Once added click the Gear icon to change the block properties. In this Content block we'll add our first lines of XAML. Let's add a label and card to our page with the XAML below:

<StackLayout StyleClass="p-16"
    Spacing="16">
 
    <Label Text="News Feed"
        StyleClass="h4" />
    
    <Rock:ContainedCard Image="https://realchip.rocks/Content/Chip%20Rocks/Images/Chip%20Sticker@4x.png"
        Tagline="ANNOUNCEMENT"
        Title="Welcome to Rock Mobile"
        ImageRatio=".75:1">
        Check out just how easy it is to create a new mobile app for your organization...
    </Rock:ContainedCard>
    
</StackLayout>

First we started with a StackLayout, which can display any number of child elements in a vertical orientation. Next we added a Label control with some text and a style class. Finally we added a Contained Card with some various text properties.

Below the content input are some options for enabling Lava commands and selecting if block is Dynamic Content. If enabled, making changes to the XAML content will be shown upon refresh of the page instead of requiring a full redeploy.

Clicking Save will add our XAML to the block. Now let's deploy our application and view it on a device.

Block Configuration

Page Size

The number of items to send per page.

Detail Page

The page to redirect to when selecting an item.

List Template

The Lava used to generate the JSON object structure for the item list.

List Data Template

The XAML for the lists data template.

Merge Fields

In the template, you have access to these objects:

Animations in Rock Mobile Shell are provided by the Xamanimation library. That page has some samples and screenshots to give you a few ideas of what you can build. But we'll give you some information on how to build it here.

Defining Animations

Let's talk about simple animations first. Animations are referenced by name and defined in the Resources of an element. In order to access an animation, it must be defined in an ancestor of where you are trying to reference it. Said another way, let's suppose you have the following XAML defined:

<ScrollView>
  <StackLayout>
    <Label x:Name="myLabel" Text="Hello Rock!" />
  </StackLayout>
</ScrollView>

If you wanted to apply an animation to the label called myLabel then you would need to define it on either the StackLayout or the ScrollView. As long as it's defined above the element you are going to be referencing it from then you are fine. You cannot define it on the element itself.

So let's take an example of what this might look like:

<ScrollView>
  <StackLayout>
    <StackLayout.Resources>
      <Rock:FadeToAnimation x:Key="FadeOut"
        Target="{x:Reference myLabel}"
        Duration="2000"
        Opacity="0" />
    </StackLayout.Resources>

    <Label x:Name="myLabel" Text="Hello Rock!" />
  </StackLayout>
</ScrollView>

This defines an animation that references myLabel as the target of the changes it will be making. The animation is going to be changing the Opacity property of the label over a duration of 2,000 milliseconds (2 seconds). Finally, it will change the opacity of the label from its current opacity to the target opacity of 0. Note, this only defines the animation, it doesn't actually trigger it.

These types of animation definitions let you target specific visual elements with a pre-defined animation style.

Starting Animations

Okay, we were able to define an animation but we need to start it somehow. You have two choices when it comes to triggering an animation.

1. Trigger style in response to the user doing something.

2. Automatically when the view loads (behavior style).

Let's modify our example above but include a trigger style activator based on the user tapping a button:

<ScrollView>
  <StackLayout>
    <StackLayout.Resources>
      <Rock:FadeToAnimation x:Key="FadeOut"
        Target="{x:Reference myLabel}"
        Duration="2000"
        Opacity="0" />
    </StackLayout.Resources>

    <Label x:Name="myLabel" Text="Hello Rock!" />

    <Button Text="Fade">
      <Button.Triggers>
        <EventTrigger Event="Clicked">
          <Rock:BeginAnimation Animation="{StaticResource FadeOut}" />
        </EventTrigger>
      </Button.Triggers>
    </Button>
  </StackLayout>
</ScrollView>

We've added a button and a BeginAnimation trigger to it that starts the FadeOut animation we previously defined. Now, when the user taps the Fade button, the label above will slowly fade out over 2 seconds.

Another way we could define this is by behavior. Suppose we wanted the text to automatically fade out after the page loads? To do that we would use a BeginAnimationBehavior instead:

<ScrollView>
  <StackLayout>
    <StackLayout.Resources>
      <Rock:FadeToAnimation x:Key="FadeOut"
        Target="{x:Reference myLabel}"
        Duration="2000"
        Opacity="0" />
    </StackLayout.Resources>

    <Label x:Name="myLabel" Text="Hello Rock!">
      <Label.Behaviors>
        <Rock:BeginAnimationBehavior Animation="{StaticResource FadeOut}" />
      </Label.Behaviors>
    </Label>
  </StackLayout>
</ScrollView>

The way behaviors work is that they begin when the element they are attached to are themselves attached to their parent element. Because there might be a delay between when this happens and when the page itself becomes fully visible, there is a hard-coded 250-millisecond delay before the referenced animation actually begins.

Stopping Animations

You can also provide the ability to stop an animation by using a trigger. Technically, the library also supports stopping an animation using a behavior, but in our use case, those don't actually make sense. If you are curious though, it is available as EndAnimationBehavior. But here is an example of two buttons, one to start and one to stop an animation.

<ScrollView>
  <StackLayout>
    <StackLayout.Resources>
      <Rock:FadeToAnimation x:Key="FadeOut"
        Target="{x:Reference myLabel}"
        Duration="2000"
        Opacity="0" />
    </StackLayout.Resources>

    <Label x:Name="myLabel" Text="Hello Rock!" />

    <Button Text="Start Fade">
      <Button.Triggers>
        <EventTrigger Event="Clicked">
          <Rock:BeginAnimation Animation="{StaticResource FadeOut}" />
        </EventTrigger>
      </Button.Triggers>
    </Button>

    <Button Text="Stop Fade">
      <Button.Triggers>
        <EventTrigger Event="Clicked">
          <Rock:EndAnimation Animation="{StaticResource FadeOut}" />
        </EventTrigger>
      </Button.Triggers>
    </Button>
  </StackLayout>
</ScrollView>

Triggered Animations

Triggered animations are ones that are, well, triggered by some user interaction. Until the user activates that trigger event, such as tapping a button, the animation remains idle.

All of the animations in this section support the following properties.

BounceInAnimation

Animates the Scale and Opacity of the target to make it appear.

<Rock:BounceInAnimation x:Key="Demo"
    Target="{x:Reference myLabel}"
    Duration="2000" />

BounceOutAnimation

Animates the Scale and Opacity of the target to make it disappear.

<Rock:BounceOutAnimation x:Key="Demo"
    Target="{x:Reference myLabel}"
    Duration="2000" />

BackgroundColorAnimation

Animates the BackgroundColor of the target from its current value to a new color.

<Rock:BackgroundColorAnimation x:Key="Demo"
    Target="{x:Reference myLabel}"
    Duration="2000"
    ToColor="#ee7725" />

ColorAnimation

Animates the specified property of the target, which must be of type Color, between two values.

<Rock:ColorAnimation x:Key="Demo"
    Target="{x:Reference myLabel}"
    Property="TextColor"
    Duration="2000"
    To="#ee7725" />

CornerRadiusAnimation

Animates the specified property of the target, which must be of type CornerRadius, between two values.

<Rock:CornerRadiusAnimation x:Key="Demo"
    Target="{x:Reference myBox}"
    Property="CornerRadius"
    Duration="2000"
    To="15,15,5,5" />

DoubleAnimation

Animates the specified property, which must be of type double, of the target between two values.

<Rock:DoubleAnimation x:Key="Demo"
    Target="{x:Reference myLabel}"
    Property="Opacity"
    Duration="2000"
    To="0.5" />

FadeInAnimation

Animates the Opacity and Y position of the element to make it visible. As the element is faded in it will also slide down or up to its final position.

<Rock:FadeInAnimation x:Key="Demo"
    Target="{x:Reference myLabel}"
    Duration="2000"
    Direction="Down" />

FadeToAnimation

Animates the Opacity of the target from its current value to a new value.

<Rock:FadeToAnimation x:Key="Demo"
    Target="{x:Reference myLabel}"
    Duration="2000"
    Opacity="0.25" />

FadeOutAnimation

Animates the Opacity and Y position of the element to make it invisible. As the element is faded in, it will also slide down or up from its current position.

<Rock:FadeOutAnimation x:Key="Demo"
    Target="{x:Reference myLabel}"
    Duration="2000"
    Direction="Down" />

FlipAnimation

Animates the Opacity and RotationY axis of the element to make it visible. As the element is faded in it will also rotate along its y-axis (that is, it will grow from a single vertical line to full-width) as if a card were being turned 90 degrees.

<Rock:FlipAnimation x:Key="Demo"
    Target="{x:Reference myLabel}"
    Duration="2000"
    Direction="Left" />

HeartAnimation

Animates the Scale of the target to simulate a heartbeat, growing and shrinking slightly.

<Rock:HeartAnimation x:Key="Demo"
    Target="{x:Reference myLabel}"
    Duration="1000" />

IntAnimation

Animates the specified property of the target, which must be of type int, between two values.

<Rock:IntAnimation x:Key="Demo"
    Target="{x:Reference myLabel}"
    Property="TabIndex"
    Duration="2000"
    To="12" />

JumpAnimation

Animates the TranslationY of the target to cause it to jump up and down.

<Rock:JumpAnimation x:Key="Demo"
    Target="{x:Reference myLabel}"
    Duration="2000" />

RelRotateToAnimation

Animates the Rotation of the target to spin the element by the number of degrees. This rotation happens along the Z-axis, meaning it does not distort the element's perspective at all.

<Rock:RelRotateToAnimation x:Key="Demo"
    Target="{x:Reference myLabel}"
    Duration="2000"
    Rotation="-45" />

RelScaleToAnimation

Animates the Scale of the target to make the element appear larger or smaller than it normally would.

<Rock:RelScaleToAnimation x:Key="Demo"
    Target="{x:Reference myLabel}"
    Duration="2000"
    Scale="0.8" />

RotateToAnimation

Animates the Rotation of the target to spin the element to the specified final rotation value. This rotation happens along the Z-axis, meaning it does not distort the element's perspective at all.

<Rock:RotateToAnimation x:Key="Demo"
    Target="{x:Reference myLabel}"
    Duration="2000"
    Rotation="180" />

RotateXToAnimation

Animates the RotationX of the target to shift the perspective of the element.

<Rock:RotateXToAnimation x:Key="Demo"
    Target="{x:Reference myLabel}"
    Duration="2000"
    Rotation="90" />

RotateYToAnimation

Animates the RotationY of the target to shift the perspective of the element.

<Rock:RotateYToAnimation x:Key="Demo"
    Target="{x:Reference myLabel}"
    Duration="2000"
    Rotation="90" />

ScaleToAnimation

Animates the Scale of the target to make the element appear larger or smaller than it normally would.

<Rock:ScaleToAnimation x:Key="Demo"
    Target="{x:Reference myLabel}"
    Duration="2000"
    Scale="1.2" />

ShakeAnimation

Animates the TranslationX target to make it appear as if it were being shaken back and forth.

<Rock:ShakeAnimation x:Key="Demo"
    Target="{x:Reference myLabel}"
    Duration="2000" />

ThicknessAnimation

Animates the specified property of the target, which must be of type Thickness, between two values.

<Rock:ThicknessAnimation x:Key="Demo"
    Target="{x:Reference myLabel}"
    Property="Margin"
    Duration="2000"
    To="15" />

TranslateToAnimation

Animates the TranslationX and TranslationY properties of the target to shift the element around from its normal position.

<Rock:TranslateToAnimation x:Key="Demo"
    Target="{x:Reference myLabel}"
    Duration="2000"
    TranslateX="30"
    TranslateY="-15" />

TurnstileInAnimation

Animates the RotationY and Opacity properties of the target to give a turnstile effect to the element appearing on the screen.

<Rock:TurnstileInAnimation x:Key="Demo"
    Target="{x:Reference myLabel}"
    Duration="2000" />

TurnstileOutAnimation

Animates the RotationY and Opacity properties of the target to give a turnstile effect to the element disappearing from the screen.

<Rock:TurnstileOutAnimation x:Key="Demo"
    Target="{x:Reference myLabel}"
    Duration="2000" />

GroupAnimation

This special animation does not conform to the common properties mentioned previously. This element lets you group animations so that they can be triggered at the same time. Animations to be grouped together can be added as child elements.

<Rock:GroupAnimation x:Key="FadeOut">
    <Rock:FadeToAnimation Target="{x:Reference myLabel}"
        Duration="2000"
        Opacity="0" />
    <Rock:FadeToAnimation Target="{x:Reference myButton}"
        Duration="2000"
        Opacity="0" />
</Rock:GroupAnimation>

Passive Animations

A passive animation is one that is always active and updates continuously whenever the property it uses to track progress changes. One example usage of this might be a slider that is used to specify the color of something. As the slider moves from one side to the other, the color slowly changes from one color to the other.

All of the animations in this section support the following properties.

AnimateProgressColor

Animates the Color-type property between the From and To values.

<StackLayout>
  <Slider x:Name="mySlider"
    Minimum="0"
    Maximum="100" />

  <BoxView Color="Blue"
    HeightRequest="100">
    <BoxView.Behaviors>
      <Rock:AnimateProgressColor Property="Color"
        From="Red"
        To="Green"
        Progress="{Binding Path=Value, Source={x:Reference mySlider}}" />
    </BoxView.Behaviors>
  </BoxView>
</StackLayout>

AnimateProgressCornerRadius

Animates the CornerRadius-type property between the From and To values.

<StackLayout>
  <Slider x:Name="mySlider"
    Minimum="0"
    Maximum="100" />

  <BoxView Color="Blue"
    HeightRequest="100">
    <BoxView.Behaviors>
      <Rock:AnimateProgressCornerRadius Property="CornerRadius"
        From="15,15,5,5"
        To="5,5,15,15"
        Progress="{Binding Path=Value, Source={x:Reference mySlider}}" />
    </BoxView.Behaviors>
  </BoxView>
</StackLayout>

AnimateProgressDouble

Animates the double-type property between the From and To values.

<StackLayout>
  <Slider x:Name="mySlider"
    Minimum="0"
    Maximum="100" />

  <BoxView Color="Blue"
    HeightRequest="100">
    <BoxView.Behaviors>
      <Rock:AnimateProgressDouble Property="HeightRequest"
        From="25"
        To="200"
        Progress="{Binding Path=Value, Source={x:Reference mySlider}}" />
    </BoxView.Behaviors>
  </BoxView>
</StackLayout>

AnimateProgressInt

Animates the int-type property between the From and To values.

<StackLayout>
  <Slider x:Name="mySlider"
    Minimum="0"
    Maximum="100" />

  <BoxView Color="Blue"
    HeightRequest="100">
    <BoxView.Behaviors>
      <Rock:AnimateProgressInt Property="TabIndex"
        From="0"
        To="15"
        Progress="{Binding Path=Value, Source={x:Reference mySlider}}" />
    </BoxView.Behaviors>
  </BoxView>
</StackLayout>

AnimateProgressThickness

Animates the Thickness-type property between the From and To values.

<StackLayout>
  <Slider x:Name="mySlider"
    Minimum="0"
    Maximum="100" />

  <BoxView Color="Blue"
    HeightRequest="100">
    <BoxView.Behaviors>
      <Rock:AnimateProgressThickness Property="Margin"
        From="0"
        To="20,20,10,10"
        Progress="{Binding Path=Value, Source={x:Reference mySlider}}" />
    </BoxView.Behaviors>
  </BoxView>
</StackLayout>

Load Animations

EntranceTransition

Provides the animated transition behavior on controls when they first appear. You can use this on individual objects or on containers of objects. In the latter case, child elements will animate into view in sequence rather than all at the same time.

<StackLayout>
    <StackLayout.Behaviors>
    	 <Rock:EntranceTransition Duration="1000"/>
    </StackLayout.Behaviors>
    
    <Label Text="Title"
        StyleClass="h3" />
    
    <Rock:ContainedCard Image="https://yourserver.com/image-grandtetonfence.jpg"
        Tagline="DESTINATIONS"
        Title="Start Your Adventure">
        Bring to the table win-win survival strategies to ensure...
    </Rock:ContainedCard>
</StackLayout>

This block is pretty self-explanatory. It can be used to edit the profile details of the currently logged-in individual.

Block Configuration

Connection Status

The connection status to use for new individuals. Defaults to Prospect.

Record Status

The record status to use for new individuals. Defaults to Pending.

Showing/Requiring Fields

In the Mobile Local Settings, each field follows a specific pattern. There is one setting for whether or not to show a field, and another that determines whether or not the field is required. If show is set to No, then the required field is irrelevant. This takes place for every field on that list, although the Gender field follows a newer style, the concept is the same (because it was added later).

Modifying Another Person Profile

In order to modify another person's profile, you must pass in the PersonGuid as a page parameter. Note that you must have access to make modifications.

This block allows an individual to register for a new account. There are a number of options that control what information you collect and which bits are required.

Block Configuration

Person Matching

In order for person matching to work, there are a few things that must come together:

1. Block Settings

   1. Check For Duplicates (Enabled by default)

   2. Confirmation Page (You must configure this)

   3. Confirm Account Template (Configured by default)

2. Mobile Shell Version 3 or Later

3. E-mail Address Provided by Individual

The first is, obviously, that you must turn on Check For Duplicates. This is the primary setting that dictates if the entire feature is enabled or not.

Once that is enabled, you also need to specify the Confirmation Page that the user will be sent to from their e-mail. This is a web page and not a mobile page, for example on your External Website you would select the "Support Pages > Account Confirmation" page.

Third, you must select the system e-mail that will be used as the template when generating the e-mail. This is selected by default.

In addition to the above block settings, there are two other things. First, as is pretty clear from the above, your users must be using version 3 or later of the Mobile Shell. This is because additional support was added in the shell to handle the UI to inform the user that the account was created but they need to confirm it. If an individual is running version 2 or below of the Mobile Shell then they will get the old behavior, which is no person matching.

Finally, they must provide an e-mail address. Because we need to send an e-mail when performing person matching the user must enter an e-mail address. This causes strict matching to be enabled in the search which means only people whose current, or previous, e-mail matches the one being searched for are considered for the duplicate search. Since adding a new user login to an existing person is a security-sensitive process, we need to be more strict about these things.

This one is going to be a challenge to describe, but we'll get you up to speed on how to use it. This block allows you to build a visual interface to provide challenges to your people. These challenges span multiple days and comprise one or more individual challenge items on each day. An example might make more sense of what we are talking about.

Let's suppose you want to have a 7 day "Get to Know God" challenge. Each day they are prompted to complete two tasks: Prayer and Bible reading. Each day would give different instructions about what to pray for and what verses to read. When they first land on the page hosting this block they will see the challenge items for day 1. After they tick those off they might see a "way to go" type message. Then the next day when they return they will see the items for day 2, and so on. Once they finish day 7 and come back the next day they start on day 1 again.

Lava Reference

When your lava template is parsed, you will get a number of merge fields to help you render the daily challenge. There is some sequence of operations you will need to be aware of.

First, you will probably want to check if the CompletedChallenge merge field is not null. If it contains a value then that means the user just finished the final challenge item for a day. In this case, you likely want to display some kind of "well done" message, or possibly switch to a read-only view that removes the check-boxes - since trying to uncheck an item from a fully completed day is not allowed. In this case, the Challenge merge field may contain either the same object as the CompletedChallenge or it may contain what the system thinks is the "next" daily challenge, depending on the situation. But generally you probably don't want to just display whatever is in the Challenge at this point.

Secondly, if the MissedDates merge field contains any values then those should be displayed to the user and must be filled in before you display the challenge in the "Challenge" merge field. Otherwise, they will start a new challenge. Also, the MissedDates must be filled in sequentially. Meaning, if they missed two dates they need to fill in the challenge for the first date and then the second date, otherwise it will also break the challenge and start them over. The default template displays just the first date of the array.

Merge Fields

• MissedDates - An array of dates that indicate the user has missed one or more dates in their current challenge that they can still go back and fill in. Note that this merge field will be empty if you have requested by any means that a specific challenge be shown.

• TodaysChallengeGuid - The unique identifier of the daily challenge that indicates today's challenge. This can be different than the Challenge value in as it takes into account an ongoing challenge where they might have skipped some days. One exception to this is if you pass a query string parameter of DailyChallengeGuid to request a specific challenge then this value will match that challenge.

Object Structure

ChallengeState

• Guid - The unique identifier of the daily challenge.

• IsComplete - Will be true if the individual has completed the challenge corresponding with this day.

DailyChallenge

This object contains all the details about a single day of a challenge.

• Guid - The unique identifier of the daily challenge.

• HeaderContent - This contains the same text content as the "Content" box when editing the "Day 1", "Day 2", etc. items. This is normally displayed at the top of the page before any checkboxes.

• IsComplete - Will be true if the individual has completed this daily challenge already. For example, if they have just checked the last checkbox, or if you are linking directly to a previously completed daily challenge.

• AttributeValues - If you defined any custom attributes for the daily challenge then they will show up here. This is a dictionary of attribute keys and string values.

ChallengeItem

This object contains the information about a single checkbox item that will be displayed for the user to complete.

• Guid - The unique identifier of the challenge item.

• Title - The text from the content channel item title. This is normally displayed next to the checkbox.

• Content - The text from the "Content" box of the content channel item.

• AttributeValues - If you defined any custom attributes for the challenge item then they will show up here. This is a dictionary of attribute keys and string values. You can use this to provide custom rendering logic to your lava template. It will not include the "InputType" value.

ChallengeItemValue

Contains the user-supplied information about a single challenge item. Meaning, if it has been completed and any custom user value that was entered.

• Guid - The unique identifier of the challenge item this value is for.

• IsComplete - Will be true if the checkbox is checked.

• Value - Contains any custom value the user has typed into a text field for this item.

XAML Bindings

So your lava template will set up the initial XAML content to paint the page. But how do you link user actions (like tapping a checkbox) back so it actually does something? There are some special bindings available to you:

• Challenge.ToggleChallengeItem - A command that toggles a checkbox on or off. The command parameter is the item unique identifier.

Okay, so those are the XAML bindings available. But examples certainly make more sense than just the description. For a moment, lets imagine that all we are going to display is a checkbox and the name of the item to be completed. So we will loop through the Challenge.ChallengeItems array and render out a horizontal stacklayout to contain our checkbox and then the label.

Most of that should look pretty normal to you. We have a bit of a mix between lava and bindings. In some places we are using lava to display a value (for example, the Label text). In others, you will notice we are using binding values. The binding value means it will actually persist the change in value. If we had used a normal lava "if" statement then it wouldn't automatically update or track the change in value.

But, that binding syntax is probably not what you normally see, so let's break it down. There are two parts to the binding, first is the path and then the converter. Let's take a look at that path first.

Challenge.ItemValues[{{ forloop.index0 }}].IsComplete

This is binding to the array Challenge.ItemValues and then binding to a specific item in the array, identifies by {{ forloop.index0 }}, which is the index of the item being processed in the loop. Finally, in that particular indexed object we are binding to the IsComplete property. Next is the converter.

{Rock:BooleanValueConverter True=check-circle, False=circle}

What we are doing here is taking that boolean value from the IsComplete property and running it through a converter that will return different values depending on if the value is true for false. If it is true we return check-circle and if it is false it returns circle. This gives us the allusion of a nice checkbox that we can style ourselves.

Setup

So how do you set up these challenges? You are going to use a Content Channel to do that. You will also need to setup 2 Content Channel Types (if you set up multiple challenges you can re-use these channel types).

Content Channels Types

The first content channel type will hold the challenges that you are going to set up, in this case we are talking about your 7-day "Get to Know God" challenge. To create a general use Content Channel Type for these challenges. Create a new Content Channel Type with the following settings:

• Name = Multi-Day Challenge

• Date Range Type = No Dates

• Disable Priority = Yes

• Disable Status = Yes

• Show in Channel List = Yes

Next, create a second Content Channel Type that will hold the individual items to be completed each day.

• Name = Challenge Items

• Date Range Type = No Dates

• Disable Priority = Yes

• Disable Status = Yes

• Show in Channel Lists = Yes

• Item Attributes

  • Name = Input Type

  • Field Type = Single-Select

  • Values = Text,Memo

  • Control Type = Drop Down List

The item attribute allows you to specify that the challenge item should have a (required) input field. You can also define other item attributes and these will be included in the Lava so you can better customize how things are displayed.

Content Channels

First, we are going to create the content channel that will hold the individual challenge items to be completed each day.

• Name = Challenge Items

• Type = Challenge Items

• Default Content Control = Code Editor

Now you need to create a Content Channel for the actual 7-day challenge.

• Name = Get to Know God

• Type = Multi-Day Challenge

• Child Content Channels = Challenge Items (the one you just created above)

• Items Manually Ordered = Yes

• Child Items Manually Ordered = Yes

Day Items

It may seem obvious, but you need to create a Content Channel Item inside your "Get to Know God" channel for each day. To keep things simple, just create 7 items titled "Day 1", "Day 2", and so on up to "Day 7". If you get things out of order, you can use manual sorting to put things in the proper order. That order is used to determine the order of the days, not the title.

All you really need is the Title, but you can enter some XAML in the Content that will be displayed at the top of the page when viewing that day's challenges.

Challenge Items

Go into "Day 1" and create a new child item.

• Title = Pray for 15 minutes

Then add a second item to be the challenge item for reading the bible.

• Title = Read the Bible

• Content = <Label Text="Genesis 1:1-18" />

So we now have two items that will be displayed for "Day 1". The first is a checkbox with the title "Pray for 15 minutes" and no additional content. The second item will be a checkbox with the title "Read the Bible" and then below that it will display the verses that they are supposed to read.

To complete this you would do the same for "Day 2" through "Day 7". And obviously you can use different verse references. You can even have them in different order or additional items to be completed on certain days.

Overview

At first glance, check-in seems simple—just a way for someone to say, "I'm here!" However, from a technical perspective, recording this data involves several requirements. To streamline the process, we've broken down these requirements and provided solutions to ensure the check-in block is as seamless as possible.

Block Configuration

Check-in Settings

Check-in Configuration

This is a required setting. The configuration template to use for this check-in block.

Kiosk

This is a required setting. The kiosk to associate this check-in process with. Necessary for things like location based check-in, etc.

Primary Areas

The areas directly associated with the check-in configuration, to make available to this block.

Secondary Areas

The areas not directly associated with the check-in configuration.

Mobile Settings

Loading Screen Template

The XAML content to display when the block is loading data.

Completion Screen Template

The XAML content to display when a check-in process successfully completes.

Login Screen Template

The XAML content to display when a user presses log-in. If no content is provided, the application Login page will be used.

Allow Add Family Member

Whether or not you should be able to add a new family member during the check-in process.

Add Person Attributes

The custom attribute fields to display when a family member is being added.

Page Parameters

Data Requirements

Successful check-in requires multiple data points. The diagram below highlights the key information needed:

If any required data is missing, the UI will prompt the user, potentially extending the check-in process. However, by providing more context through page parameters—such as using deep links, QR codes, or NFC tags—you can create a faster, more seamless experience.

Additionally, Rock intelligently fills in missing data where possible. For example, if only one applicable schedule exists for the selected Area, Group, and Location, that step is skipped automatically.

With these optimizations, you can create a truly frictionless check-in experience.

This section refers to the 'CMS' mobile block group.

This section refers to the 'Communication' mobile block group.

This section refers to the "Connection" mobile block group.

This is an extremely powerful block for managing workflows from a mobile application. If you aren't sure what workflows are quite yet, please refer to Blasting Off With Workflows, a Rock manual that goes over the subject.

Page Parameters

Block Configuration

What is Microsoft Entra

Microsoft Entra ID is a cloud-based identity and access management service that is typically used for employees. It can be used to effectively manage authentication, security and much more at an extremely scalable level.

Setup

To ensure Entra works perfectly in Rock Mobile, follow this step-by-step guide.

1. Create and configure a new App Registration in the Azure AD Portal.

2. Add permissions for our mobile application to retrieve necessary data points.

3. Ensure our authentication returns enough information to the Rock server.

4. Configure your Rock Mobile to support Entra.

1. Registering the app

a. In the Entra admin portal, navigate to Applications > App registrations > New registration.

b. Configure the Register an application screen considering the information below.

Name

Provide a name for your Rock Mobile app registration. Nothing really hinges on this.

Supported account types

This is really up to you. If you're limiting Entra login to staff, then the Accounts in this organizational directory only is likely the right choice.

Redirect URI

This is important. This needs to be formatted like <BundleId/PackageName>://entra/callback, otherwise authentication won't work. If your bundle identifier and package name differ, you'll have to add a Redirect URI for both (App Registrations > Your App > Authentication).

Ensure that the type of Redirect URI is set to Public client/native (mobile & desktop).

2. Add necessary permissions

We need to ensure that our mobile application has permission to see the necessary data of a newly authenticated user.

a. Navigate to your newly created app registration, then to API permissions > Add a permission.

b. Select Microsoft Graph.

c. Select Delgated permissions, check email, openid and profile permissions. Press Add permissions.

3. Add optional claims

Out of the box, Entra will not return the first name and last name of an authenticated person to the shell. Rock needs this information to process/person match etc., so we need to go in and add these data points.

a. Under your newly created app registration, navigate to Token configuration > Add optional claim.

b. Select ID as the Token type, and check email, family_name (last name) and given_name (first name). Press Add.

4. Configuring Rock Mobile

a. Jump into your Rock Mobile application (CMS Configuration > Mobile Applications > Your application > Edit).

b. In the Authentication Settings section, we're going to be configuring the Microsoft Entra settings.

Entra Client ID & Entra Tenant ID

To retrieve your Entra Client ID and Entra Tenant ID, jump into the Entra portal, your newly created app registration, into Overview. The values will be displayed.

Microsoft Entra Authentication Provider

Select the same authentication provider that provides Entra login on web. In almost all cases, this component is either the Triumph Tech Azure AD Sync & SSO plugin or BEMA Single Sign On plugin.

c. Configure the Login block to provide Entra as an SSO option.

Supported Claims

The following identity claims are supported and can be utilized to supply additional information about a Rock Person. Since Entra configurations can vary, we supply a few different keys that are recognized and translated accordingly.

The purpose of this block is pretty obvious, but in case you are unsure, it is to log a registered individual into your application using a Rock credential.

If you need to set up registration, check out the Register or Onboard Person blocks.

Login Page App Setting

When you create an instance of the Login block, it would be a good idea to also set the Login Page application setting. This allows the app to perform auto-security redirects and is used in a couple of other places functionally.

Settings

Page Parameters

The following page parameters are recognized by the Login block.

External Authentication

Listed below is the corresponding documentation for every external authentication provider that can be integrated with Rock Mobile.

If/when more are added, corresponding documentation will be added to this section.

What is Auth0?

Auth0 is a cloud-based identity and access management (IAM) platform that provides developers and organizations with secure and easy-to-use solutions for authenticating and authorizing user access to applications. Auth0 offers a range of authentication methods such as username and password, social identity providers, multi-factor authentication, and more.

With Auth0, developers can add authentication and authorization capabilities to their applications quickly and easily. Check out their website to learn more about the services they offer.

Setup

To ensure Auth0 works seamlessly in Rock Mobile, follow this step-by-step guide to configure a new Auth0 application for Rock Mobile. In this guide, we will:

1. Create and configure a new Auth0 application for Rock Mobile.

2. Configure Auth0 to provide enough data for Rock sign-up.

3. Configure Rock Mobile to support Auth0.

Creating an Auth0 Application

To begin, let's create the Auth0 application that will handle our Rock Mobile logins. You should only need one application for all of your mobile applications.

1. In the Auth0 Dashboard, create a new application.

1. Select Native as the type of application.

2. Head into the Settings of the Application. You can ignore the Quick Start guide that they typically start you on. Note down the Client ID and Domain of your Auth0 application.

1. Make sure you have your app's Bundle ID (iOS) and Package Name (android) available. If you are unsure of these values or where to retrieve them you should contact the AppFactory publishing service.

2. In the Allowed Callback URLs of the Auth0 application, add an entry in the following format. If your package name and bundle identifier differ, you will require two URLs, one for each.

<Bundle Identifier/Package Name>://auth0/callback

1. Under Credentials, ensure the Token Endpoint Authentication Method is set to None. Mobile apps use a different form of authentication in comparison to web applications.

Great! We should now have all of the basic configuration finished.

Getting Additional Data for Rock

In order to sign a person up, Rock requires a First Name, Last Name, and either a Phone Number or an Email. Auth0 does not require all of these data points out of the box. There are quite a few ways that you could customize the login flow to support this additional data, but we're going to keep it pretty straightforward in this guide.

To ensure all of the necessary data for Rock is obtained, we will:

1. Configure Universal Login to add additional fields for database sign-up.

2. (optional) Configure a post-login rule to pass additional information to Rock.

Configuring Universal Login

1. First, we need to configure Auth0's Universal Login to ensure there is enough data collected to create a person in Rock. Head over to Branding > Universal Login > Advanced Options > Login. Enable the Customize Login Page option.
2. Scroll down to the customizable HTML. This section will allow us to modify the sign-up page to request additional information. You can supply additionalSignUpFields to the main Lock object to set specific user data. In this tutorial, we'll be accepting an additional phone number, gender, and the individual's first and last name. You can view the Auth0 documentation to see more about what you can do with these fields.

additionalSignUpFields: [{
    name: "given_name",
    placeholder: "Enter your first name",
    storage: "root" // IMPORTANT!
    {
    name: "family_name",
    placeholder: "Enter your last name",
    storage: "root" // IMPORTANT!
    },
    {
}]

The entire file looks like this if you want to copy and paste the entire example.

<!DOCTYPE html>
<html>
<head>
  <meta charset="utf-8">
  <meta http-equiv="X-UA-Compatible" content="IE=edge,chrome=1">
  <title>Sign In with Auth0</title>
  <meta name="viewport" content="width=device-width, initial-scale=1, maximum-scale=1, user-scalable=0" />
</head>
<body>

  <!--[if IE 8]>
  <script src="//cdnjs.cloudflare.com/ajax/libs/ie8/0.2.5/ie8.js"></script>
  <![endif]-->

  <!--[if lte IE 9]>
  <script src="https://cdn.auth0.com/js/base64.js"></script>
  <script src="https://cdn.auth0.com/js/es5-shim.min.js"></script>
  <![endif]-->

  <script src="https://cdn.auth0.com/js/lock/11.32/lock.min.js"></script>
  <script>
    // Decode utf8 characters properly
    var config = JSON.parse(decodeURIComponent(escape(window.atob('@@config@@'))));
    config.extraParams = config.extraParams || {};
    var connection = config.connection;
    var prompt = config.prompt;
    var languageDictionary;
    var language;

    if (config.dict && config.dict.signin && config.dict.signin.title) {
      languageDictionary = { title: config.dict.signin.title };
    } else if (typeof config.dict === 'string') {
      language = config.dict;
    }
    var loginHint = config.extraParams.login_hint;
    var colors = config.colors || {};

    // Available Lock configuration options: https://auth0.com/docs/libraries/lock/v11/configuration
    var lock = new Auth0Lock(config.clientID, config.auth0Domain, {
      auth: {
        redirectUrl: config.callbackURL,
        responseType: (config.internalOptions || {}).response_type ||
          (config.callbackOnLocationHash ? 'token' : 'code'),
        params: config.internalOptions
      },
      configurationBaseUrl: config.clientConfigurationBaseUrl,
      overrides: {
        __tenant: config.auth0Tenant,
        __token_issuer: config.authorizationServer.issuer
      },
      assetsUrl:  config.assetsUrl,
      allowedConnections: connection ? [connection] : null,
      rememberLastLogin: !prompt,
      language: language,
      languageBaseUrl: config.languageBaseUrl,
      languageDictionary: languageDictionary,
      theme: {
        //logo:            'YOUR LOGO HERE',
        primaryColor:    colors.primary ? colors.primary : 'green'
      },
      prefill: loginHint ? { email: loginHint, username: loginHint } : null,
      closable: false,
      defaultADUsernameFromEmailPrefix: false,
    	additionalSignUpFields: [
    	{
        name: "given_name",
        placeholder: "Enter your first name",
        storage: "root" // IMPORTANT
    	},
     	{
        name: "family_name",
        placeholder: "Enter your last name",
        storage: "root" // IMPORTANT!
         },
	]
});

    if(colors.page_background) {
      var css = '.auth0-lock.auth0-lock .auth0-lock-overlay { background: ' +
                  colors.page_background +
                ' }';
      var style = document.createElement('style');

      style.appendChild(document.createTextNode(css));

      document.body.appendChild(style);
    }

    lock.show();
  </script>
</body>
</html>

Once finished, paste it into the HTML section into the box. Ensure the preview looks correct.

(optional) Pass in Additional Information to your Rock instance

There are a billion ways in which you can configure your Auth0 login process. You may want to enhance the process to return additional information to your Rock instance (such as Gender, BirthDate, etc).

This is supported through the use of Identity Claims. In short, identity claims are set during your authentication process to provide additional information about an authenticated individual. There are quite a few ways you can set these claims as well, mostly through Auth0 Rules or Actions.

1. Do you remember the additionalSignUpFields we configured earlier? Let's add some more fields to that.

 type: "select",
    name: "gender",
    placeholder: "choose your gender",
    options: [
      {value: "1", label: "Male"},
      {value: "2", label: "Female"},
      {value: "0", label: "Unspecified"}
      ],
    },
    {
    name: "phone_number",
    placeholder: "Phone Number"

This will add a Gender picker that reflects the Gender enum, and a basic Phone Number field.

1. Jump into Action > Flows and press Login to configure a post-login flow. Select Build Custom.

1. In onExecutePostLogin method, configure the identity claims to pass down the proper data, like such:

exports.onExecutePostLogin = async (event, api) => {
  var userPhoneNumber = event.user.phone_number ?? event.user.user_metadata?.phone_number;
  var userEmail = event.user.email ?? event.user.user_metadata?.email;

  var needsPhoneOrEmail = (userPhoneNumber && userPhoneNumber != "") || (userEmail && userEmail != "");

  if( needsPhoneOrEmail )
  {
    // Invalid login. Here you could customize the login flow to prompt the users for the values, if you wanted to.
  }

  if (event.authorization) {
    // We're careful here to only update the claims if they don't
    // already exist. These can be set previously be social providers, so 
    // if we have a value that's null it's likely it came from there,
    // and the claim is already set (so we don't need to reference metadata).
    if( userPhoneNumber )
    {
      api.idToken.setCustomClaim("phone", userPhoneNumber );
    }
    if( event.user.user_metadata?.gender )
    {
      api.idToken.setCustomClaim("gender", event.user.user_metadata?.gender );
    }
    if( event.user.user_metadata?.given_name )
    {
      api.idToken.setCustomClaim("given_name", event.user.user_metadata?.given_name );
    }
    if(  event.user.user_metadata?.family_name )
    {
      api.idToken.setCustomClaim("family_name", event.user.user_metadata?.family_name );
    }
  }
};

Press Deploy. The last thing we need to do is add it to the login flow. Add the Action you just created before the completion of the login, like such. Make sure to press Apply afterwards.

Configuring Rock Mobile

There are a couple of configuration steps for Rock Mobile.

1. In your mobile application (Cms Configuration > Mobile Applications), look for the Auth0 Client ID and Auth0 Domain settings. Update them with your application values.
2. Enable Auth Login in the Login block.

   Hooray! You should now be fully capable of handling Auth0-related logins.

Go into your login block, and press the Login With Auth0 button. That button has a btn-auth0 style class applied for customization. You should now be prompted with an Auth0 login.

In the Sign Up tab, you should see all of the additional fields you configured.

When you successfully log in with Auth0 (even for new accounts), a Person in Rock will be matched or created with the values of the Auth0 account.

Supported Claims

The following identity claims are supported and can be utilized to supply additional information about a Rock Person. Since Auth0 configurations can vary, we supply a few different keys that are recognized and translated accordingly.

Arguably the most fundamental block in any Rock Mobile application, this block could be described as a necessity, used to render Lava and XAML within your shell, as provided in the "Content" block setting. If you are unfamiliar with XAML, please refer to the official Microsoft documentation. If you are unfamiliar with Lava, please check out the Rock Lava Reference.

For example, you could use it to display a simple label:

<Label Text="Hello!" />

Or use it to implement more complex views, such as a BibleBrowser.

Block Configuration

Dynamic Content This setting is extremely useful. When checked, it will download fresh content from the server every time the page is initialized. In a sense, it causes the content to "refresh" every time the page is loaded.

If you have static, unchanging content, you can leave this as a No. This means that a Deploy will be required before the content is updated in-app. Behind the scenes, this content will be baked into the shell bundle that's downloaded during the app launch. Lava will still be processed, but you won't have a CurrentPerson context.

Using Lava

After the content, the second block setting to discuss is the "Enabled Lava Commands". If you have a Lava command within your Content, it is important to make sure to check the applicable settings here. It is also just as vital to make sure that you check the "Process Lava on Server" setting within the 'Block Properties > Mobile Settings', as seen here:

Entity Context

With just a few settings, you can wire up entity context to the Content block making it even more powerful! Maybe you want to create a profile page for people based on Search results. Instead of running Lava in the content to pull the needed data, let the block set the person context for you.

Using the Context Entity Type setting in the block, you can select any of the available entities.

Next, you'll need to set the context parameter for the page. This is how the block will know where to find the context identifier. This setting is found by editing the Page (not the block) and expanding the Advanced Settings section. Based on the entity type you chose, you should see a setting labeled {{ Entity }} Parameter Name. Add a parameter key that makes sense for your data.

Now that you've set the block entity type and page context parameter, be sure to Save and Deploy. The final step is to simply link to your page and pass the appropriate context via the key you set. Going back to the example of the person profile page, you might end up with something like this:

<StackLayout>
    ...
    <Button Text="Profile"
        StyleClass="btn, btn-primary"
        Command="{Binding PushPage}"
        CommandParameter="3446dcac-0078-4ba4-a19a-65ce8b7fb776?Guid={{ Person.Guid }}" />
</StackLayout>

Within your Content block, you can check that the context isn't null and begin accessing the entity. If context wasn't set correctly, consider a graceful fallback to another page via Redirect.

<StackLayout>

    <!-- If context isn't set, fall back to page and display error message -->
    {% if Context == null %}
        <Rock:Redirect PageGuid="82370b8d-0fea-4454-8ad7-7e7c950e3345"
            QueryString="Message={{ 'Unable to find person' | UrlEncode }}" />
    {% endif %}
    
    <!-- Context has been set -->
    <Label Text="{{ Context.Person.NickName | Escape }}" />
    
</StackLayout>

This block displays structured content from Rock in the app. You can use this to display interactive sermon notes with tap-to-reveal areas and note-taking areas.

Block Settings

Content Channel

You'll see a channel called "Message Notes" that comes out of the box with Rock, so you typically won't need to set this up manually unless you have another purpose in mind. When editing a content channel, you can check the Is Structured Content option to enable this functionality. This will change the Default Content Control option to Editor Tool Configuration.

Adding new child items to this content channel will allow you to edit the structured content with a rich editor. Check out the Supported Formatting section to see what's available. In order to link this note item to a Message, simply add it as a child to the content channel item for the Message.

Mobile App

In the app, you'll need a page with the Structured Content View block added. Thankfully there aren't any block settings to worry about, so you'll just need to add a link to this page that passes context using the ItemGuid query string with a value of the content channel item GUID. In the case of Message Notes, you can use Lava to look at the ChildItems of a message to get the Notes/Structured Content item.

<!-- Set the content channel type Guid of Message Notes -->
{% assign typeGuid = '48951e97-0e45-4494-b87c-4eb9fca067eb' %}

{% assign noteItem = '' %}
{% for childItem in Item.ChildItems %}
    
    <!-- Skip any child items that are not of type Message Notes -->
    {% if childItem.ChildContentChannelItem.ContentChannelType.Guid == typeGuid %}
        
        <!-- Assign the note and skip the remaining child items -->
        {% assign noteItem = childItem.ChildContentChannelItem %}
        {% break %}
    {% endif %}
{% endfor %}

{% if noteItem != '' %}
    {% assign noteGuid = noteItem.Guid %}
    <Button Text="Message Notes"
        Command="{Binding PushPage}"
        CommandParameter="{{ yourMessageNotesPageGuid }}?ItemGuid={{ noteGuid }}" />
{% endif %}

Supported Formatting

Not all formatting options are supported natively in the app, but here's what can be used safely:

1. Text

2. Heading

3. List (ordered and unordered)

4. Image

   1. Image captions

5. Checklist

6. Quote

   1. Left-aligned

   2. Center-aligned (stays aligned left)

7. Warning

8. Code

9. Note (can be left blank or default content entered)

10. Delimiter

11. Link

12. Table

When highlighting text, the following formatting is supported:

1. Bold (depending on font support)

2. Italic (depending on font support)

3. Link

4. Marker

5. Fill-in

6. Code

Notes

When using note blocks in structured content, they will only display if a user is logged in. We recommend putting a content block above this one that only displays if a user is not logged in, and prompts them to log in or at least lets them know that the notes are missing until they do so.

This block is simple to use, but it's important to understand its function. When authoring a new push communication, you may have seen the question for Open Action, which includes the options Link to Mobile Page and Show Details. This block handles the Show Details option.

If you've ever wanted to show additional information to someone after they tap a notification, you can! The content you enter into the Additional Details box will be shown in the app via this block. Start by creating a new page and adding the Communication View block. Next, you'll need to tell the app which page has this block so it knows where to direct people that tap on notifications. Under the Application tab, click Edit and select the page you created for Communication View Page.

Note that not every formatting option is supported in the mobile app, so don't go crazy with fonts and colors. Images are supported, and will generally try to adhere to the layout you set in the editor. For more info on what's supported, check out the HTML control.

Block Configuration

Header Template

This is the content that is rendered above the lists of your requests. This allows you to put a logo, header, or do whatever you like to style the top of this component.

Type Template

This is the main template that is used to display the entire list of your connection types. You can fully customize this template using the entire list object to do whatever you like with it.

Merge Fields

In the opportunity template, you have access to these objects:

No Requests Content

You may have noticed in some other blocks, there is a block setting to provide content when there is nothing to display. Often seen as something like a:

We have decided to make this an even easier piece of the puzzle to set, by including it in the template itself. If you wish to customize this content, the piece you are looking for is:

Detail Page

This is the page that is linked when a specific request is selected. You can see it being used here in the default template.

Block Configuration

Communication List Categories

Select the categories of the communication lists to display, or select none to show all that the user is authorized to view.

Show Description

If enabled then the description of the communication list will be shown.

Show Medium Preference

If enabled, a segment picker will be displayed for lists that the person is subscribed to in order to set their preferred communication type.

Show Push Notification as Medium Preference

If enabled, push notification will be displayed as an option for medium preference.

Filter Groups By Campus Context

If enabled, groups will be filtered by the current campus context. If a campus is not set on the communication list, then it will be displayed no matter what.

Always Include Subscribed Lists

When filtering by campus, you may want to display lists that the user is subscribed to regardless of the campus context. Enabling this will do just that.

Styling

Configuration

Allowed SMS Numbers

This setting allows you to designate which phone numbers are permitted as From numbers. If no numbers are selected, all numbers will be available.

Show Only Personal SMS Number

When this setting is turned on, only SMS numbers associated with the current person will display. Administrators, however, will be able to view all SMS numbers.

Hide Personal SMS Number

Enable this setting to only show SMS numbers that aren't linked to a specific person - essentially, numbers without an "Assigned To Person" value.

Show Conversations From Months Ago

Limits the conversations shown to those of X months ago or newer.

Max Conversations

The max number of conversations to show in the panel.

Database Timeout

The number of seconds to wait before reporting a database timeout.

Conversation Page

Person Search Stopped Typing Behavior Threshold

The amount of time to wait before executing the person search command, from the millisecond that the person stops typing.

Page Parameters

The following query string parameters are recognized and utilized by this block.

Styling

Configuration

Snippet Type

The type of snippets that will be made available via the snippet keyboard button.

Message Count

The number of messages to be returned each time more messages are requested.

Database Timeout

The number of seconds to wait before reporting a database timeout.

Page Parameters

The following query string parameters are recognized and utilized by this block.

Styling

Message Bubbles

To style message bubbles, we introduced the following custom CSS classes.

You can target these elements by using the ^MessageBubble selector.

Block Configuration

The only thing required for this block to function is the RequesterId. This can be the string IdKey or Guid of the Requester.

Connection Types

The connection types that will be made available to this block. If none are selected, all available connection types will be shown.

Post Save Action

The navigation command to execute after a save successfully occurs.

Post Cancel Action

The navigation command to execute when the "cancel" button is pressed.

Page Parameters

This section is in reference to the 'Core' mobile block group.

This section refers to the 'Events' mobile block group.

This section refers to the 'Finance' mobile block group.

This block is relatively simple to use, but it requires a decent understanding of Communications in Rock.

Setup

For this block to work correctly, you must pass in a valid EntitySetGuid page parameter. This will populate the list of recipients that receive the communication. The EntitySetType should be of Person.

You can generate these EntitySetGuid parameters auto-magically, using the Group Member List block.

Settings

Page Parameters

This block supports many query strings that can be used to override the block settings. This allows you to set a default, then customize the experience for each individual based on something like the group role or other data from Rock.

Security (Approving Communications)

This block uses a unique security verb, named Approve. This security role determines if someone is allowed to instantly queue a communication, or if it must be submitted for approval beforehand. It is highly recommended to configure the security on this block, to ensure not anyone can send a communication to a large number of people.

Here is the security action configured to behave exactly the same as the web block:

This block is used to display a list of connection opportunities for a single connection type. If you are unfamiliar with Connections in Rock, please refer to the connections manual.

Getting Content

Getting the connection types

In order for the block to know which 'Connection Type' to display opportunities for, you need to give it some context. Navigate to 'Admin Settings > Power Tools > SQL Command' and execute the following query:

SELECT Name,Guid FROM [ConnectionType]

If there are any connection types available, this will display a list containing their name and guid. Select and copy the guid of the specific connection type you are trying to display opportunities for. In this walkthrough, I will be using the 'Involvement' connection type guid.

Using query parameters

To provide the guid we just obtained to the block, we do so by providing it with 'query parameters', which are context passed to the block when the page containing this block is pushed. This block looks for the following query parameters:

Conveniently, that is the same value we just obtained by getting the connection types. Create a new page that only contains a 'Content' block. Provide the following as the content, but change pageGuidto represent the guid of the page you just created and the connectionTypeGuid to represent the guid that we got earlier.

{% assign pageGuid = '' %}
{% assign connectionTypeGuid = 'dd565087-a4be-4943-b123-bf22777e8426' %}

<Button Command="{Binding PushPage}">
    <Button.CommandParameter>
        <Rock:PushPageParameters PageGuid="{{ pageGuid }}">
            <Rock:Parameter Name="connectionTypeGuid" Value="{{ connectionTypeGuid }}" />
        </Rock:PushPageParameters>
    </Button.CommandParameter>
</Button>

Deploy, press that button, and voila! The block should display the list of connection opportunities for the specific type. So now you can see how to show the opportunities for one specific connection type... but that would rarely be the actual intended use case.

If only there was some type of list to display all of the types for us... Oh, wait! There is. To fetch all of your connection types, create a new page with a 'Connection Type List' block, and set the 'Detail Page' to a page containing this block.

Header Template

This is the content that is rendered above the lists of your requests. This allows you to put a logo, header, or do whatever you like to style the top of this block.

Merge Fields

Merge fields are fields that are available to use within the template. So in the header template, you have access to these objects:

Opportunity Template

This is the main template that is used to display the entire list of your opportunities. You can fully customize this template using the entire list object to do whatever you like with it.

Merge Fields

In the opportunity template, you have access to these objects:

No Requests Content

You may have noticed in some other blocks there is a block setting to provide content when there is nothing to display. Often seen as something like a:

<NotificationBox Text="You currently have no current requests. Please check again later." />

We have decided to make this an even easier piece of the puzzle to set, by including it in the template itself. If you wish to customize this content, the piece you are looking for is:

{% if ConnectionOpportunities == empty %}
    ... Put your content here!
{% endif %}

Detail Page

This is the page that is linked when a specific request is selected. You can see it being used here in the default template.

{% if DetailPage != null %}            
    <Frame.GestureRecognizers>
        <TapGestureRecognizer Command="{Binding PushPage}" 
            CommandParameter="{{ DetailPage }}?ConnectionOpportunityGuid={{ opportunity.Guid }}" />
    </Frame.GestureRecognizers>
{% endif %}

If you are lost, this is within the main for-loop of the Opportunity Template, and by doing this, each opportunity passes its individual Guid as a query string parameter for the detail page.

Psst! This setting would be utilized as intended if it was set to a page that had the Connection Request List block on it.

This block is used to display a list of connection requests for a single connection opportunity. If you are unfamiliar with Connections in Rock, please refer to the connections manual.

Getting Content

To summarize, this block looks for the connectionOpportunityGuid as a query string parameter upon loading. You can provide this specifically (demonstrated below), or by following these steps below:

1. Create another page that contains a Connection Opportunity List (COL) block.

2. Set the 'Detail Page' setting within the COL block to a page that contains this block.

3. Navigate to the page containing the COL block, and tap!

Getting the connection opportunities

In order for the block to know which 'Connection Opportunity' to display requests for, you need to give it some context. Navigate to 'Admin Settings > Power Tools > SQL Command' and execute the following query:

SELECT Name,Guid FROM [ConnectionOpportunity]

If there are any connection opportunities available, this will display a list containing their name and guid. Select and copy the guid of the specific connection opportunity you are trying to display requests for. In this walkthrough, I will be using the 'Greeter' connection opportunity guid.

Using query parameters

To provide the guid we just obtained to the block, we do so by providing it with 'query parameters', which are context passed to the block when the page containing this block is pushed. This block looks for the following query parameters:

Conveniently, that is the same value we just obtained by getting the connection opportunites. Create a new page that only contains a 'Content' block. Provide the following as the content, but change pageGuid to represent the guid of the page you just created and the connectionOpportunityGuid to represent the guid that we got earlier.

{% assign pageGuid = 'c327bdc5-dc76-4408-baa4-c4a2d022ed36' %}
{% assign connectionOpportunityGuid = 'dd565087-a4be-4943-b123-bf22777e8426' %}

<Button Command="{Binding PushPage}">
    <Button.CommandParameter>
        <Rock:PushPageParameters PageGuid="{{ pageGuid }}">
            <Rock:Parameter Name="connectionTypeGuid" Value="{{ connectionOpportunityGuid }}" />
        </Rock:PushPageParameters>
    </Button.CommandParameter>
</Button>

Deploy, press that button, and voila! The block should display the list of connection opportunities for the specific type. So now you can see how to show the opportunities for one specific connection type... but that would rarely be the actual intended use case.

If only there was some type of list to display all of the opportunities for us... Oh, wait! There is. To fetch all of your connection opportunities, create a new page with a 'Connection Opportunity List' block, and set the 'Detail Page' to a page containing this block.

Block Configuration

Header Template

This is the content that is rendered above the lists of your requests. This allows you to put a logo, header, or do whatever you like to style the top of this block. Please note, that if a ConnectionOpportunity is not found, this content will not display.

Merge Fields

Merge fields are fields that are available to use within the template. So in the header template, you have access to these objects:

Request Template

This is the main template that is used to display the entire list of connection requests. You can fully customize this template using the entire list object to do whatever you like with it.

Merge Fields

In the request template, you have access to these objects:

No Requests Content

You may have noticed in some other blocks, there is a block setting to provide content when there is nothing to display. Often seen as something like a:

<NotificationBox Text="You currently have no current requests. Please check again later." />

We have decided to make this an even easier piece of the puzzle to set, by including it in the template itself. If you wish to customize this content, the piece you are looking for is:

{% if ConnectionRequests == empty %}
    ... Put your content here!
{% endif %}

Detail Page

This is the page that is linked when a specific request is selected. You can see it being used here in the default template.

{% if DetailPage != null %}            
    <Frame.GestureRecognizers>
        <TapGestureRecognizer Command="{Binding PushPage}" 
            CommandParameter="{{ DetailPage }}?ConnectionRequestGuid={{ request.Guid }}" />
    </Frame.GestureRecognizers>
{% endif %}

If you are lost, this is within the main for-loop of the Request Template, and by doing this, each opportunity passes its' individual Guid as a query string parameter for the detail page.

Psst! This setting would be utilized as intended if it was set to a page that had the Connection Request Detail block on it.

Overview

In order to get content for our notes block, we need to do a couple of things. In this section, we will walk through the steps necessary to display notes of a specific entity by:

1. Adding a note to a Person entity.

2. Configuring the block settings.

3. Configuring the context parameter.

4. Passing in a GUID as a page parameter.

Adding a Note to an Entity

In order to get started, we need to make sure that we actually have a note to display. On your Rock server, navigate to a person's profile page (using the search in the top right is a fast and easy way) and press the add button to add a note. I would recommend adding a note to yourself, as you know that you will have permission to view it.

From here should be pretty self-explanatory. Go ahead and add a note with whatever text you wish, and press Save Note.

Configuration

Block Settings

Next, we need to configure our block to actually look for those personal notes. In the block settings, set the Entity Type to Person and in the Note Types, select Person: Personal Note.

So now, the block knows the entity type that we are fetching notes for, and also the specific note type we are fetching.

The communication template to use when a note is added and Enable Group Notification is true. Note will be passed in as a merge field to the communication template that you select.

If enabled, a toggle will display that allows an individual to mark a Note as alert.

If enabled, a toggle will display that allows an individual to mark a Note as private.

Context Parameter

Next, we need to configure the page settings to look for a PersonGuid as a context parameter. We do this by heading to the page settings, which can be navigated to by pressing the Edit button above the mobile page builder.

Once in the page detail, underneath Advanced Settings, you should see a Context Parameters section. If you do not see this setting, please try refreshing the page and potentially clearing your cache. Set this to PersonGuid so the page knows that we are attempting to pass in a person guid as the context parameter.

Passing Context

We're so close! For some of you, this should be easy peasy by now. But for those still getting started, let's go over quickly how to pass in the GUID as a query string parameter. Start by creating a new page with nothing but a Content block on it. For the content, we will supply a simple button that does two things.

1. Navigate to our page containing the Notes block.

2. Passes in the PersonGuid as a query string parameter.

For number one, we will need to obtain the PageGuid of the page containing our Notes block. Luckily, there is a handy feature that lets you do this easily. Press the little blue icon in the top right of your mobile page editor, as seen here:

Once obtained, go back to our blank page with nothing but the content block, and set the content to the following XAML:

{% assign pageGuid = 'your page guid' %}

<Button Text="Notes!" Command="{Binding PushPage}">
    <Button.CommandParameter>
        <Rock:PushPageParameters PageGuid="{{ pageGuid }}">
            <Rock:Parameter Name="PersonGuid" Value="{{ CurrentPerson.Guid }}" />
        </Rock:PushPageParameters>
    </Button.CommandParameter>
</Button>

Simply replace the pageGuid to the one you just copied, and you are good to go.

Launch the application, and tap the button we just created. You should see a similar outcome:

Using a Template

The notes block is typically meant to be used as a full-screen block, with a layout that does not contain a ScrollView. This is due to the usage of a CollectionView, which is a highly performant Xamarin Forms control that allows us to implement things like loading more notes as you continue scrolling down.

In many cases, you may want to incorporate Notes into another layout. That's why we introduced an option for you to customize the Notes block using your own XAML template.

To use a custom template, you must enable the Use Template block setting. When this setting is enabled, the Page Load Size becomes the amount of notes (ordered by recency) supplied to the template. It is recommended to keep this as a relatively low number. You can set a Note List Page block setting that is meant to direct to a page containing the Notes block in a full-screen manner (not using a template). The following commands and merge fields become available to you in the Notes Template:

Getting Started

A little bit of forewarning for when jumping into this block is that it has been pre-configured to function with the 'Person Name' search component. If you plan to change the component type, a decent understanding of XAML will have to be incorporated into the Result Item Template to use the ItemType.

The good news is that if that is the intended functionality, it works right out of the box, as long as you set the Search Component to Person Name.

Settings

Styles

You can utilize certain block settings to display a 'recently searched for' view that displays when the search field is empty. This is done through a combination of a few things, with the first being the AppendToSearchHistory command. This command is available on the Result Item Template. This command saves specific information about the entity to the shell.

<StackLayout.GestureRecognizers>
    <TapGestureRecognizer Command="{Binding AppendSearchHistory}">
        <TapGestureRecognizer.CommandParameter>
            <!-- We should pass in the Guid (of the entity that we are saving)-->
            <Rock:AppendToSearchHistoryParameters Guid="{{ Item.Guid }}">
                <!-- These are parameters that become available as merge fields 
                to the Historical Result Item Template -->
                <Rock:Parameter Name="Name" Value="{{ itemName }}" />
            </Rock:AppendToSearchHistoryParameters>
        </TapGestureRecognizer.CommandParameter>
    </TapGestureRecognizer>
</StackLayout.GestureRecognizers>