The Problem

Many times, we organize our content by its format instead of its subject matter. Format is somewhat helpful, however, people typically search for content that revolves around a question that they have, or simply put, a specific topic. Rock empowers us to help people more quickly find the truth and hope that applies to the question they have by organizing our content by topic.

** Please note that having a website that is powered by Rock is a prerequisite for this recipe.

Okay, Great, So How Do We Do It?

1. Tag & Tag Category Setup
2. Content Channel Configuration
3. Tag Content
4. Create Lava Shortcodes
5. Create Tag List Page
6. Create Individual Tag Page
7. Add Tags to Existing Pages

1. Tag & Tag Category Setup

Go to `Admin Tools > General Settings > Tag Categories` and create a new category for your topic tags. If the modal for creating a new category gives you the option to select an Entity that your new category will apply to, choose the `Tag` entity. Once you've created your new category, click it, and then note the `CategoryId` that is listed in the browser address bar - we'll need that later.

Next, go to `Admin Tools > General Settings > Tags` and begin creating some tags that you think will apply to your content. You'll want to ensure that every tag you create has a scope of `Organization` and is correctly assigned to the tag category that you created above.

* Tips on Tags

Avoid creating tags that are too similar to one another - we want to use our tags to bring clarity to what the content is addressing. We also want to avoid our tags from being too narrow - a tag that only has a single piece of content connected to it doesn't help people discover more content related to the subject.

2. Content Channel Configuration

Secondly, we'll need to configure each content channel for which we'd like to tag content. Go to `Admin Tools > CMS Config > Content Channels` and click on a channel you'd like to configure for tagging. Click 'Edit' to make changes to the content channel. Next, click the checkbox labeled `Enable Tagging`. Upon doing that, a new field will appear where you can select the tag category you created in step 1 - select that category here.

Next, you'll need to specify a value for the `Content Channel Item Publishing Point` field. This can differ depending on how your website routes are structured, but generally speaking, you'll need the URL where you can view the individual items from this channel. For example, if the channel you were updating was for a blog, your website's blog entry URLs might look something like yourchurchsite.com/blog/some-blog-entry or yourchurchsite.com/blog?Item=52. Either of these examples will work, you'll just need to replace either the `Slug` (example 1) or `Id` (example 2) with a placeholder for this fields value. For the examples above, the value for `Content Channel Item Publishing Point` would look like `https://yourchurchsite.com/blog/{Slug}` or `https://yourchurchsite.com/blog?Item={Id}`, respectively.

You'll repeat this step for each channel that you'd like to tag content for.

3. Tag Content

For this step, you'll need to edit each content item within each of the channels you're adding tags to. As you prepare to enter tags, begin typing a topic and only use the suggested tags from autocomplete in the field - attempting to add a tag from the content item page directly will create a personal tag rather than an organizational tag, and it will not create the connections between content that we're after. If you find yourself needing to add additional tags, you can do that at any time at `Admin Tools > General Settings > Tags`. You'll always want to ensure you're correctly categorizing tags as you add them, so they'll be available to add to your content.

4. Create Lava Shortcodes

To support the tags and pages we're adding, there are a couple of helpful lava shortcodes that we'll want to add to your Rock install - one for listing out the tags of any content channel item (specified by Id), and another that will handle the pagination on our topic pages (where all of our content related to a specific topic will be displayed). For a more in-depth explanation of what lava shortcodes are, why they're useful, and how to use them, check out this RockU video and this manual.

** Remember, when creating and using lava shortcodes, parameter names must be all-lowercase or they will not work as expected.

Content Channel Item Tags

Go to `Admin Tools > CMS Config > Lava Shortcodes`, create a new shortcode, give it a name of `Content Channel Item Tags`, and use the following configuration options:

• Tag Name: contentChannelItemTags
• Tag Type: inline
• Description: This shortcode accepts a parameter `contentchannelitemid` and returns the UI for a list of the tags that this content item has been tagged with.
• Documentation (paste this via code editor): <pre>{[ contentChannelItemTags contentchannelitemid:'' ]}</pre>
• Shortcode Markup:

** Note: You must update the following from the shortcode markup for this shortcode to work on your Rock instance:

1. Tag Category Id on line 4 (find your tag category Id by clicking on your category on /page/497 and copying from browser address bar
2. Enable the `SQL` Lava Command on this new shortcode
3. Update the parameter in the `Prepend` filter on line 20 to match whatever route you'll be using for topic pages

Pagination

Create another new shortcode, give it a name of `Pagination`, and use the following configuration options:

• Tag Name: pagination
• Tag Type: inline
• Description: This shortcode accepts two parameters, `itemcount` and `pagesize` and returns the UI for paging links for a large group of items.
• Documentation (paste this via code editor): <pre>{[ pagination itemcount:'' pagesize:'' ]}</pre>
• Shortcode Markup:

** Note: You must update the following from the shortcode markup for this shortcode to work on your Rock instance:

1. `/page-not-found` url for your 404 page on line 4
2. Font Awesome will need to be included in order for the prev/next arrow icons to work
3. Parameters of `itemcount` and `pagesize` are both required. Recommended to set a default `pagesize` value on the shortcode itself.

5. Create Tag List Page

Now that we've got all of our setup done, we'll actually create some pages. On your external website, create a new page wherever you want your main topics list page to live. Remember that structurally you can put this page where it makes sense from an organization standpoint and still make your page route whatever you'd like it to be. You can also use whatever page layout makes most sense to you, but I'd suggest a full width layout to make your topics front-and-center.

Once you've created your new page, navigate to it, and we'll update a couple of page properties. Click the page properties button in the admin bar, and we'll click "Display Settings" and uncheck everything that's checked as we'll be adding our own page title and content with a Dynamic Data block. Next, click "Advanced Settings" and add a page route to this page. I would suggest "topics" or something similar. Save the changes you've made to this page's properties.

Lastly for this page, we'll add a Dynamic Data block to it. Click the "Page Zones" icon in the admin bar and add a new Dynamic Data block. The Dynamic Data block consist of two main sections that work together; a `Query` field that enables you to write a SQL query to get data from the Rock database, and a `Formatted Output` field that enables you to control how this data is displayed on the page, using lava. Edit the content of the new block you just added, and use the following for the `Query` field:

** Note: You must update the following in the above SQL query for it to work on your Rock instance:

1. Update the Tag Category Id above on line 1 (currently 1228) to match the topics category that exists on your own instance of Rock
   

And use the following for the `Formatted Output` field:

** Note: You must update the following in the above lava for it to work on your Rock instance:

1. Update the url segment above on line 9 (currently '/topics/') to match the route you're using for topic pages on your website

Save the changes you've made to the block, and you should now have a list of tag links on the page. Note that only tags that have content associated with them will be visible, as we don't want to create links to a page with no content.

6. Create Tag Content Page

Now that we've got our tag list page created, we'll set up another page that will handle surfacing all content related to a specific tag. Create a new page as a child of the Tag List page we created in step 5. Once you've done that, navigate to the new page. First, we'll configure page properties by clicking the gear icon in the admin bar. Click on `Display Settings` and uncheck everything that's checked as we'll be adding our own page title and content with a Dynamic Data block. Lastly, click `Advanced Settings` and add a route to the page that includes a placeholder for your tag name in the second url segment. You'll want to make sure that the first segment matches whatever route you used for your Tag List page in from step five. For example, since our Tag List page has a route of `topics`, we'll add a route of `topics/{Topic}` to this page. The `{Topic}` route placeholder is what allows this page to be served for any tag - `/topics/relationships`, `/topics/stewardship`, etc. By making this dynamic, it prevents us from having to set up a unique page for every topic tag individually. This means that as you add tags and content in the future, your topic pages will just work without any extra effort. Once you've added your page route, save your page properties changes.

Next, we'll add two blocks to this page - an HTML block that we'll use this for our page header, and a Dynamic Data block that will handle displaying all content related to the given topic.

For the HTML block, use the following lava to display the tag name and page number (for subsequent pages of pagination) as the page heading:

** Note: You must update the following in the above lava for it to work on your Rock instance:

1. Update the page parameter name (currently 'Topic') on line 1 and the link url (currently '/topics') on line 7 to match the configuration of your settings for your website

Now that we've got our page header setup, you should be able to go to various urls (/topics/spiritual-disciplines, /topics/marriage) and see the page header change, dynamically. Keep in mind that once we update the Dynamic Data block with its query and lava, urls that don't match an existing tag with content should redirect to your 404 page.

Next, we'll add a SQL query and lava to our Dynamic Data block. Click `Block Configuration` (the grid icon) from the admin toolbar, and edit the content of the Dynamic Data block.

Use the following SQL query in the `Query` field:

** Note: You must update the following in the above SQL query for it to work on your Rock instance:

1. Update the Tag Category Id on line 1 (currently 1228) to match the topics category that exists on your own instance of Rock

Next, we'll need to add `Topic=` in the `Parameters` field. Doing this gives us the ability to use the value of the `Topic` page parameter (we defined this in the page's route), which in our case will match the name of our topic tag. Having this dynamically available to us is what enables us to get the tag from our topics category that matches the URL, and subsequently get the content that has been tagged with that tag.

Lastly, use the following as a starting place for the `Formatted Lava` field:

** Note: You must update the following in the above lava for it to work on your Rock instance:

1. Update the `/page-not-found` redirect route on line 6 (this is where Rock will send requests for tags that either don't exist or don't have content associated with them)
2. Update lines 19-24 to match the Content Channel Id and Attribute Key combinations that apply to your instance of Rock
3. Ensure you've configured both the "Content Channel Item Tags" and "Pagination" shortcodes on your instance of Rock, as they are utilized in the lava above
   

7. Add Tags to Existing Pages

The last step we'll tackle is to surface our content's tags anywhere it's already surfaced on our website. We can do this with the use of our `ContentChannelItemTags` lava shortcode we created.

Simply put, you'll want to go to any places on your website where content channel items currently exist, and add the shortcode that displays the item's tags. This will enable users to more quickly learn what topics each piece of content is speaking to, as well as give them the ability to click into your topic pages and discover all of your content relating to a specific topic.

To recap, you'll add the following lava to each lava template that is display content channel items, and pass in the item's id to the `contentchannelitemid` parameter. Assuming that the lava variable that references your content channel item is called `Item`, it would look like the following:

{[ contentChannelItemTags contentchannelitemid:'{{ Item.Id }}' ]}

That's It!

At this point, you should have a page on your website that lists out all of your topics, a page that will serve all of your content that is relevant to any given topic, and the ability for your users to discover the content that you've published that matters most to them! 🎸