• Be familiar with Lava and HTML
• Be familiar with Lava Shortcodes (optional)
• Be familiar with the difference between Attributes and Properties
• Be frustrated with the 'Matrix' Field Type

1. What
   • Illustration #1
   • Illustration #2
2. How (general concept)
   • How to Configure
   • How to Use
3. Notes
4. Update History

What

This recipe shows how to use Lava in order to convert a "table" stored in a Matrix-type Attribute into a JSON-formatted string. This way, you can use the FromJSON Filter in order to use the "rows" of the "table" by treating it as an array of "rows".

Illustration #1

Let's say you have a Person Attribute named "Emergency Contacts" (let's say the Attribute Key is EmergencyContacts_Matrix), and let's say this Attribute is useful for your Youth Ministry to be able to keep track of various Emergency Contacts for each kid.

Let's say that you want to print a PDF packet or write an Email Template that will only include the "first row" of this Matrix.

With the current way matrices are configured in Rock's Data Model, we can't easily do that. 😓

But what if we could simply treat the Matrix-type Attribute as an array of rows? 🤔 Then, we could return only the "first row" of this Matrix by writing something like this:

Illustration #2

Let's say you have a Person Attribute named "Prescribed Medications" (let's say the Attribute Key is Medications_Matrix), and let's say this Attribute is useful for your Youth Ministry to be able to provide your Summer Camp Nurse with a packet of prescribed medications for each kid that is going to the camp.

If we had the convenience of treating each "row" as an item in an array, we can get really creative with our Lava Templates:

How (general concept)

1. You can use this Lava script in order to transpose the "columns" and "rows" of your Matrix into a JSON string.
   • i recommend making this into an inline-type Lava Shortcode.
2. Once you have a JSON string, you can use the FromJSON Filter in order to transform the string into a Lava object.
3. Once it is a Lava object, you can proceed with all the Lava tricks in your bag.

How to Configure

Step 1: Navigate to Admin Tools > CMS Configuration > Lava Shortcodes, and click the '+' button in order to create a new Shortcode.

Step 2: Create a Lava Shortcode with these properties:

• Name:
  
  MatrixToJSON
• Active:
  
  ✅ TRUE
• Tag Name:
  
  MatrixToJSON
• Tag Type:
  
  Inline
• Description:
  
  This Lava Shortcode allows you to use Matrix-type attributes the way you thought they would work.
• Documentation:
  (Remember to press the 'Code Editor' button () in order to paste this HTML)
  
• Shortcode Markup:
  
• Parameters:
  ‎guid‎______
• Enabled Lava Commands:
  
  Sql

It will look kinda like this:

How to Use

Generally speaking, there are three things you want to do when using this JSONificator (JSONifier?).

1. Pass the RawValue of a Matrix-type Attribute into the Shortcode
2. Capture the output of this Shortcode
3. Use the FromJSON Filter in order to transform the JSON string into an object

Let's unpack that a little bit.

For example, if you have a Matrix-type Person Attribute named "Emergency Contacts", and the key of this attribute is EmergencyContacts_Matrix, then this Lava:

{{ Person | Attribute:'EmergencyContacts_Matrix', 'RawValue' }}

Would return something like this output:

d330ea78-ce5d-46b9-8b36-11ba81342b47

You could very well copy+paste that RawValue into the Shortcode like this:

{[ MatrixToJSON guid:'d330ea78-ce5d-46b9-8b36-11ba81342b47' ]}

But it will make your life easier if you could assign that RawValue into a variable and pass the variable instead. Like this:

{% assign variable_1 = Person | Attribute:'EmergencyContacts_Matrix', 'RawValue' %}

{[ MatrixToJSON guid:'{{ variable_1 }}' ]}

Then, capture the output of the Shortcode and name your variable. For example, i am capturing it and labeling it as `EmergencyContacts_JSON`:

{% assign variable_1 = Person | Attribute:'EmergencyContacts_Matrix', 'RawValue' %}

{% capture EmergencyContacts_JSON %}
{[ MatrixToJSON guid:'{{ variable_1 }}' ]}
{% endcapture %}

Lastly, convert this JSON into a Lava object. For example, like this:

{% assign variable_1 = Person | Attribute:'EmergencyContacts_Matrix', 'RawValue' %}

{% capture EmergencyContacts_JSON %}
{[ MatrixToJSON guid:'{{ variable_1 }}' ]}
{% endcapture %}

{% assign EmergencyContacts_Object = EmergencyContacts_JSON | FromJSON %}

And from here on out, you can take over and use all the Lava tricks you've got in your bag!

Now that we know the exact way to use this Lava script in order to JSONize Matrix Items, let's revisit Illustration #1 and Illustration #2.

We would achieve the use case in Illustration #1 in this way:

And we would achieve the use case in Illustration #2 in this way:

Notes

This Recipe was only possible thanks to the unending patience and knowledge of Ben Murphy and Luke Taylor-- who have always encouraged me to learn and understand. Thanks guys!

Update History

• 01-MAR-2024: Updated this Recipe in order to reflect Pull Request #1