Create a Filtered Catalog Site Using Condition Tags and Snippets

This guest blog post was written by Homer Christensen, an Information Architect, MadSkills consultant, and an award-winning tech writer and UX designer. His client list includes Nestlé, Microsoft, Ellie Mae, Conga, and the State of California. When not writing or coding, he’ll likely be bikepacking, winemaking, or enjoying his permaculture garden.

You can create a filtered learning catalog site using MadCap Flare's native features and built-in condition tags. The Nestlé Technology Learning Center created one for the Digital Technical and Production Academy that included one-to-one and one-to-many relationships and had multiple ways of grouping the courses in the catalog.

Our internal client approached us with the need for a catalog of courses they were creating for all aspects of digital manufacturing of the multitude of products that Nestlé sells. They envisioned around 60 modules to organize the hundreds of planned courses. That part was fairly straightforward.  However, they also wanted to sort and organize the courses by the 60+ roles who are required to complete the courses.

To complicate matters, though a course might appear in one learning module, there were typically multiple roles that required it in their learning plan.

We approached this by organizing the roles and modules into groups (or Organizations) and categories. A learner would first select a role group they belonged to and then his or her role to see the courses that applied. Or, a user could instead go directly to the category of training they need--Digital Manufacturing Operations, for example--and see the modules within it.

The search path resembled this:

The upper levels would be best presented as tiles, so I designed them as a list (for ease of coding that I'll show later) that included a title, FontAwesome icon, and a link to summary pages. To simplify things and identify like elements, we had unique icons for the groups and categories. The roles and modules used the same icons as their parent.

The courses are set up as two-sided cards that flip over on hover. The front contains the course title, duration, level (basic, intermediate, advanced), a representative image, and a link to the course. The reverse side lists the learning objectives and the course link.

The courses were not part of this Flare project;  instead, they were housed in a Nestlé learning management system.

Because this was a new implementation, I started with a new project. It used shared files (such as our CSS, common images and logos, and so on), but the structure was wide open.

In order to simplify the links to images and topics, I imposed some strict rules on naming conventions and folder structure:

• Content pages were divided into two folders:  roles and cat.
• Internal folders were to be named for the group or category condition tag.
• Summary group or category pages would share the same name as the condition tag, enclosed within the similarly named folder (e.g., Content/cat/aao/aao.htm).
• Role and module summary pages were named for the role and module condition tag, within the group or category folder (e.g., Content/cat/aao/aao-braincube.htm).

This was essential to making it easy for non-Flare users to provide the data to populate the site and allowed me to approach the link structure and paths in a very programmatic way.

Setting up the Condition Tags

I set up condition tags for groups, roles, categories, and modules. The condition tag set consisted of each of the entries for the tag: the groups condition tag had a tag for each group, the roles for each role, and so on. Naming the condition tag set the same as the object made it easy to identify the condition.

For example, in the Digital Manufacturing Operation category, the category condition tag was group.dmo. Its modules included mod.dmo-bom, mod.dmo-clp, and so on.

Roles and modules were associated with one group or category, so those followed the same pattern as the groups and categories.

Courses had one-to-many relationships with roles and modules, so I didn't create a condition tag for courses. However, courses used condition tags most extensively, both in applying condition tags for the roles and modules to associate the course with them, but also as snippet conditions on the summary pages for the roles and modules to include only those that matched the role or module condition.

With over 60 roles and modules referencing several hundred courses, it became a daunting task to keep everything straight. It was time to bring in a helper app, Microsoft Excel.

Using Excel Workbook Sheets

Excel worked beautifully for two reasons: it made it easy to track which tags link to which objects and I could use it to import information into Flare. To support that, I built five sheets: group, role, category, module, and course.

For groups and categories, I created cells for the title, tag, and the FontAwesome icon that would identify the group or category.

Roles and modules had the same—title, tag, and icon—but also the tag of the related group or category.

Courses required much more information, as I wanted to make it as client- friendly as possible and the information was subject to change frequently. The client was going to learn Flare after we launched the site, but not before, and it made sense to use a shared Excel file so that they could modify it at their leisure (and European time) and I could push it to the site on my schedule.

In addition to the title, we included multiple bits of information, such as a brief description, five learning points, the duration, the course level, the link to the course on the learning management system (LMS), and an image for the card.

Once the data was in the worksheets, it was time to construct the pages. To save time (a lot of time), I tasked Excel to build the list items and the course cards through formulas.

Excel Formulas Build the Content

During the design, I created a couple of placeholder list items and cards to determine how I'd construct the formula. I was thinking originally of using snippets and variables, but having a client maintain it meant that it was easier to maintain if it was text.

I won't deny that the formulas were complex and they took a couple of tries to get right, but over the past few weeks as we've added chunks of data to the site, it's proven it was time well spent.

The formulas enabled me to build the list items as well as the condition tag set (I opened the condition tag set as text) for a quick copy and paste.

A couple of key points: I set up the folder structure to mirror the tag names, and the summary pages also shared the tag name. Having a consistent, simple structure where all summary pages were on the same level enabled me to ref- erence images and link objects with confidence. Because the client was building the site out as we went forward, having the data in Excel made it easy to sort alphabetically after each data push before we moved it to Flare.

The course formulas were way more complex, but yielded the same great results. I built some error checking in for missing information (for example: if the course doesn't have a link, insert Coming Soon, otherwise create a button with the link) or to hide blank learning objectives.

Snippets do the Heavy Lifting

I relied on some snippets and used snippet conditions to limit the information that appeared on the page. To do this, I created summary pages for groups, roles, categories, and modules, and created snippets for roles, modules, and courses.

A key decision was to place all of the course cards in one file. Because each course card had conditions applied to it, I could use a snippet variable to show only those courses that matched the snippet variable.

For each snippet, I copied the formula result for the appropriate sheet into the Text Editor side.

Another thing to note is that Flare doesn’t need to have the new line returns that you’re used to seeing after each tag in the Text Editor view. You can paste multiple tags in a single line (each Excel cell) and as long as it is valid XML, Flare will parse it correctly.  If you copy a group of cells in Excel and paste into Flare, the pasted result includes a new line after each cell.

I was a bit concerned that having all of the course cards in a single snippet might take too long to build or cause memory problems, but so far, it builds quickly and it is easy to maintain. More importantly, it is very snappy on the published site as each page includes only the relevant courses.  There’s no javascript to filter or hide the courses that don’t apply.

Building out the Structure

This greatly simplified the summary pages for roles and modules, and I could (once again!) use an Excel formula to quickly build my pages. I copied the formula results to a Word file and applied styles to each column (filename to the file name column, and <pre> to the part that was XML because I didn't want it to URL-encode on import), converted it to text, imported it into a Flare project, specifying a new topic each time it encountered the filename style.

I opened each file and moved the <pre> text to the XML side, and then deleted any extraneous text to create the summary pages and then moved on to the next file. In one afternoon I was able to build and finalize 140 topics.

The filenames were identical to my tags (another win!), so the files matched my links and I had only to drag the imported topics into their appropriate group or category folder.

Not All Lists are Bullets and Numbers

Lists are an easy way to create and style elements, such as these tiles. I applied a style tag to the <ul> tag and another to each of the list items <li> tags. That allowed me to give them unique style definitions to set them apart from normal lists.

Because the list is a flexbox parent, we can set the display characteristics of the list items to flow into a row that wraps to the next row when it reaches the edge--great for responsive design.

Here's the CSS I used for the tiles.  (We use a special font, which I’ve removed from the definition.)

Final Result

The final result functioned as I had hoped it would. The client’s response has been very positive, and we worked together to design a clean, uncluttered site that dovetails nicely into their other materials.

On the Home page, the learner can choose between groups and categories. Clicking a category displays its associated modules, and then clicking a module shows a list of related courses.

The course cards flip up on hover (or a tap on portable devices) to display the learning objectives.