Entity

Entity Command Basics

So you may be wondering, "What's an entity?" An entity is simply a type of data that's stored in Rock. Things like People, Groups, and Financial Transactions are all entities.

Lava allows you to retrieve data from any entity using a simple and consistent pattern. For instance, to find all the Deckers you would use:

{% person where:'LastName == "Decker"' %}
        {% for person in personItems %}
                {{ person.FullName }} <br />
        {% endfor %}
{% endperson %}

Let's look at each line to unpack what's going on here.

  • 1. The first thing to note is the name of the Lava command 'person'. This tells Lava that we'd like to return people from our query. You can put any entity name here. Next we see our first parameter 'where'. The syntax used for parameters is:

    parameterName:'parameterValue'

    Note the use of the colon to separate the parameter name from the value. It's also important to wrap the parameter value in single quotes (double quotes won’t work as they are needed for determining expressions within the values (ala LastName == "Decker").

  • 2. Next we see the 'for' loop over the results. The iterator name is <entityName>Items. As you'll see soon, you can change the default if you wish.

  • 3. On line 3 we see that we're printing the FullName of the person.

  • 4. Finally, we have the end of the entity command.

So that's querying a person. What about a group?

{% group where:'GroupTypeId == 25' %}
    {% for group in groupItems %}
        {{ group.Name }} <br />
    {% endfor %}
{% endgroup %}

See, we told you it was consistent.

Parameters

We already saw the 'where' parameter in action, but we haven't even scratched the surface of what's possible. Let’s jump in!

The id parameter takes precedent over the other selection parameters, specifically where, dataview, and dynamicparameters. If the id parameter is specified, the other selection parameters are ignored. Therefore it is not recommended to mix id with where, dataview, nor dynamicparameters in the same entity command.

Quick Links:

Where

The 'where' parameter allows us to filter the entities based on their properties or attributes. So if we wanted to search for people with the LastName (property) of "Decker" and the Position (attribute) of "Outreach Pastor" we would use:

where:'LastName == "Decker" && Position == "Outreach Pastor"'

To use a group's IsActive property in combination with the earlier query we would use:

where:'GroupTypeId == 25 && IsActive == true'

Pretty cool right?! But there's more! Our example above uses 'equal' but there are several other conditions you can use including:

==equal
!=not equal
^=starts with
*=contains
*!does not contain
_=is blank
_!is not blank
>greater than
>=greater than or equal
<less than
<=less than or equal
$=ends with

Think of the powerful queries you’ll soon be writing!

There is one current limitation with the 'where' parameter, which is that it does not allow for nested or grouped conditions (think parenthesis in the SQL 'where' clause). While we'll remove this limitation in an upcoming release, you'll see later there are some ways around this (we think you'll be very satisfied).

Tip: The _= and _! operators are special in that they ignore the right side of the expression and only evaluate the left side for null/blank. Example: {% tag where:'OwnerPersonAliasId _= ""' %} will return all tags where the OwnerPersonAliasId column is null (All Organization tags).

Id

Sometimes you may want to query for entities, other times you'll know the exact entity you're looking for. With the 'Id' parameter you can specify the exact Id that you'd like.

{% person id:'3' %}
    {{ person.FullName }} <br />
{% endperson %}

By providing a single Id you can specify the exact entity (in this case a person) you're interested in. This example also shows another interesting tidbit. If your expression only returns a single value, you can drop the 'for' iterator and simply use the name of the entity. You're welcome to still use it if you'd like though.

Ids

Sometimes you might want to specify a list of Ids. In that case try:

{% person ids:'3,4,5,50' %}
    {% for person in personItems %}
        {{ person.FullName }} <br />
    {% endfor %}
{% endperson %}

DataView

Building queries is fun using all of the parameter options of the entity commands. We've also enabled you to use dataviews to filter the entities.

{% person dataview:'9'  %}
    {% for person in personItems %}
        {{ person.FullName }} <br />
    {% endfor %}
{% endperson %}

Using a dataview allows you to update the filter using a nice UI in the admin portal. It should also be noted that using a dataview parameter doesn't keep you from also adding an additional 'where' parameter. The expression defined in the 'where' parameter will be tacked onto the dataview. Consider this example:

{% person dataview:'1' where:'LastName == "Decker"'  %}
    {% for person in personItems %}
        {{ person.FullName }}  <br />
    {% endfor %}
{% endperson %}

Sort

The 'sort' parameter does exactly what you'd think it would do. It orders the results by the fields you define (fields are delimited by a comma). These fields can consist of either entity properties or attributes.

{% person where:'Position _! "" ' sort:'LastName,NickName desc'  %}
    {% for person in personItems %}
        {{ person.LastName }}, {{ person.NickName }} ({{ person | Attribute:'Position' }}) <br />
    {% endfor %}
{% endperson %}

Limit

The 'limit' parameter will ensure that your results only have a certain number of records.

{% person dataview:'1' limit:'2'  %}
    {% for person in personItems %}
        {{ person.FullName }} <br />
    {% endfor %}
{% endperson %}

Offset

The 'offset' parameter will skip the provided number of records. This is helpful for activities like paging. In order to use the 'offset' parameter you must have a 'limit' parameter configured.

{% person dataview:'1' limit:'2' offset:'2'  %}
    {% for person in personItems %}
        {{ person.FullName }} <br />
    {% endfor %}
{% endperson %}

Dynamic Parameters

Hopefully by this point you're starting to drool thinking of all the cool things you can build with the Entity Lava command. But there's more!

Using the 'dynamicparameters' parameter you can tell the command that you'd like to use values from the query string as parameters in the command. Here are a few examples of what you can achieve.

{% person dynamicparameters:'Id'  %}
    {% for person in personItems %}
        {{ person.FullName }} <br />
    {% endfor %}
{% endperson %}

In this example, the command's 'id' parameter will be appended to the command based on the value from the query string. Assuming the query string of /MyPage?Id=3, Ted Decker from the sample data will be shown. Let's check out some more...

{% assign groupid = PageParameter['groupId'] %}

{% groupmember where:'GroupId == {{groupid}}' %}
    {% for gm in groupmemberItems %}
        {{ gm.Person.FullName }} <br />
    {% endfor %}
{% endgroupmember %}

As you see above, you can even pull the group Id from a page route such as /Group/82 you'll find on the group detail page. One last example...

{% person dynamicparameters:'LastName,NickName'  %}
    {% for person in personItems %}
        {{ person.FullName }} <br />
    {% endfor %}
{% endperson %}

Notice in this example that there are no command parameters called 'LastName' and 'NickName'. When this occurs Lava assumes that you'd like to add these as filter expressions. The query string /MyPage?LastName=Decker&NickName=Ted would again show Ted Decker's name.

Other common uses for the 'dynamicparameters' parameter include:

  • Passing in the 'offset' value for paging.
  • Providing various sorting options.
  • Changing the 'limit' parameter to adjust the number of rows returned.

Iterator

As we mentioned in the very beginning, the standard naming convention for the iterator is '<entityName>Items'. If you'd like to, you can change the name of the iterator variable like so:

{% person dataview:'1' iterator:'people'  %}
    {% for person in people %}
        {{ person.FullName }}  <br />
    {% endfor %}
{% endperson %}

Security

The Entity command does respect Rock model security. That comes at a performance cost, but hey... security is important. You'll want to consider who will be using your Lava templates that uses the Entity command and ensure that the models are set correctly.

Special Cases

For the most part, things work just as you'd expect. There are a couple of special cases you should be aware of though.

  1. For those who are astute with Rock's entities, you might know that both People and Businesses share the 'person' entity. To help reduce confusion, we've mapped the 'person' and 'business' entities to separate commands and added dynamic filters to ensure they return the proper record type.

  2. We've also added a dynamic filter for the 'person' entity to ensure that deceased people are not displayed. You can optionally disable this filter by adding includedeceased:'true' as a parameter.
  3. If you want to use a Lava variable in your where clause you need to enclose it in "{}".
    {% assign tag = PageParameter['tag'] %}
    
    {% contentchannelitem where:'Status.Value == "Approved" && Tags *= "{{tag}}" && StartDateTime.Value > Now' %}
        {% for item in contentchannelitemItems %}
            	{{item.Title}}
    	{% endfor %}
    {% endcontentchannelitem %}

Count (v7.0)

The 'count' parameter will return the number of records returned from your entity query. This is handy if you just want to know how many items there are without actually loading all the records.

{% attendance where:'DidAttend == true && GroupId == 56' count:'true' %}
  {{ count }}            
{% endattendance %}