Developer Docs - 303 - Blast Off - Context Aware Blocks

A context-aware block is so-named because its behavior is determined by the Rock entities that are active in the user's current context. The block may be designed to display information or perform actions that affect the specific Rock entities the individual user is currently working with.

The Notes block is an example of such a component - it can be used to add, edit or remove notes for a Rock entity such as a Person or a Group, and individual instances of the block inspect the current context to determine which Person or Group the notes are associated with.

Rock entities exist in the user's context when they are relevant to the current environment that the user is operating in. For example, when the Person Profile page is displayed, all of the context-aware blocks on that page display information about the selected person. Other entities related to that person may also be in context, such as the Campus with which the person is associated or the Group that represents the person’s family.

Rock provides the means to configure your custom block to work with specific types of entities, to determine which entities are available from the current user context and to easily access those entities. How your custom block makes use of the context is entirely dependent on the functionality you are seeking to implement.

Site vs Page Context

An entity can be set into the context for the site level or a page, and there are certain blocks that do this. For example the CampusContextSetter block has a "Context Scope" setting, and when set to 'Site' the user selected campus will then be put into the context (for that person) for the site so that future/other pages the person visits can present information specific to the campus they selected earlier.

// set context and refresh below with the correct query string if needed
RockPage.SetContextCookie( campus, pageScope, false );

Creating a Context-Aware Block

[ContextAware(typeof(Rock.Model.Person), IsConfigurable = false)]
// or
[ContextAware( typeof(Campus), typeof(Person) )]

If you have a block that can work with any entity, you can just use the plain attribute. In this case the context entity type can be configured via a block setting:

[ContextAware]

In this case, the block will automatically have a new block setting to allows configuration of a particular entity type:

Accessing the Context

To retrieve an entity instance from the context, reference it by type name in the ContextEntities dictionary.

var personContext = ContextEntities( “Rock.Model.Person” );

Alternatively, you can use one of the ContextEntity methods.

var personContext = ContextEntity();

// Get the entity from the block's context:
var contextEntity = this.ContextEntity();

Because there are some blocks (such as the ReminderLinks) block that works with many kinds of EntityTypes, it may be necessary to make a distinction between site or page scoped context entities. In these situations the RockPage.GetScopedEntityContexts(...) method might be used to get the collection of entities you are interested in:

var entityCollection = RockPage.GetScopedContextEntities( ContextEntityScope.Page );

Runtime Configuration

When a block is added to a page, the page properties (gear) will show a Context Parameters section under the Advanced Settings of the page properties popup.

This is how you can establish the parameter name that should be used to fill the context using that parameter’s value.