Create your first lens

In this tutorial, we’re going to build a lens, put it on a new assets page in your portal, and then change the lens to watch the page update. Lenses decide which assets each page displays, so the right people find the right content without anyone curating pages by hand. By the end, you’ll have a working assets page whose contents are controlled by keywords alone.

This is part 4 of 4 in the portal creator tutorials. Previous: Build your first CMS page.

Prerequisites

To follow this tutorial, you need:

Access to Lenses in Platform Administration, through the Admin role for Administration Panel. The Client Admin role preset includes this.
The Creator role for Content Portal, so you can add pages to a portal. The Portal Creator and Client Admin role presets include this. Each role’s permissions are listed in User role presets and permissions.
The keyword category and tagged assets from Build your first keyword category: one Active asset tagged Spring, and one tagged Summer sale.

What we’ll create

We’ll make a lens that picks up our two tagged assets, and a page called Tutorial seasons that uses it. Then we’ll change the lens so it excludes one of them, and check that the page follows.

The tutorial takes about 20 minutes, including the videos, in four steps:

Step 1: Understand how lens rules work
Step 2: Create the lens
Step 3: Put the lens on a page
Step 4: Change the lens

Step 1: Understand how lens rules work

A lens picks assets using rules about their keywords. Before we build one, we’ll work out what our rules will do.

How lens rules work (2 min 37 s)

A lens has three kinds of rule, called constraints:

All: an asset must have every keyword listed.
Any: an asset needs at least one of the keywords listed.
None: an asset with any of these keywords is left out, whatever else it has.

We have two assets: one tagged Spring, and one tagged Summer sale.

You’ll notice that:

Spring and Summer sale in Any picks up both assets.
Spring and Summer sale in All picks up neither, because no asset has both keywords.
Spring and Summer sale in Any, with Summer sale also in None, picks up only the Spring asset.

We’ll build the first of these now, and the third in step 4. For further information, refer to Understanding lenses.

Step 2: Create the lens

Create a lens (3 min 41 s)

We’re going to create a lens that picks up any asset tagged Spring or Summer sale.

Navigate to Administration > Lenses.
Select Create New Lens.
Enter Tutorial seasons as the name, then select Save.
Search for Tutorial seasons, and select it to open its details.
In the phase settings, check that only Active assets are included.
In Collation, select Add, choose Tutorial season, and confirm.

Collation sets which keyword categories appear as filters on the page, and in what order.
In the constraints section, under Any, select Add and choose Spring and Summer sale.
Select the tick icon to confirm.

Leave the adapters and types empty. They narrow a lens by kind of resource, which we don’t need here.

You’ll notice that:

Each change needs the tick icon before it’s saved.
Once the constraints are set, an overview displays what the lens targets: our two assets.

Step 3: Put the lens on a page

A lens displays nothing until a page uses it. We’re going to add an assets page to your portal and point it at our lens.

Add a page that uses a lens (2 min 44 s)

Open your portal and select , then Navigation.
Select Add Page Item.
Choose the listing page type, then Assets, and select Next.

Lenses only work on listing pages.
Enter Tutorial seasons as the page name, and tutorial-seasons as the URL name.
Leave the page enabled, and select Next.
Choose the Tutorial seasons lens.
Leave the other options as they are, and select Save and Apply.
Open the new Tutorial seasons page in the portal navigation.

You’ll notice that:

The page displays exactly our two assets, and nothing else from the DAM.
Tutorial season appears as a filter, because we added it to Collation.

Step 4: Change the lens

The page doesn’t hold a list of assets: it asks the lens each time. So changing the lens changes the page, without editing the page at all.

Manage existing lenses (1 min 20 s)

We’re going to exclude the Summer sale asset.

Navigate to Administration > Lenses, search for Tutorial seasons, and select it.
In the constraints section, under None, select Add and choose Summer sale.
Select the tick icon to confirm.
Refresh the Tutorial seasons page in your portal.

You’ll notice that the page now displays only the Spring asset. The Summer sale asset still matches Any, but None overrules it.

Tagging works the same way in reverse. Tag another active asset with Spring, refresh the page, and that asset appears too. This is how a page stays current: keep the keywords right, and the lens does the rest.

The finished lens and page

Here’s what we’ve built:

Lens: Tutorial seasons, which picks up active assets tagged Spring or Summer sale, then leaves out any tagged Summer sale.
Collation: the Tutorial season category, shown as a filter.
Page: Tutorial seasons, an assets listing page in your portal that uses the lens.

If you don’t want portal users to see the practice page, hide it from the navigation panel: open the page’s menu and select Hide. For further information, refer to Add your first portal pages.

Conclusion

In this tutorial, you’ve learned how to:

Predict which assets the All, Any, and None rules pick up.
Create a lens with keyword constraints and collation.
Add an assets listing page that uses a lens.
Change a lens, and see every page that uses it update.

Create lenses covers every lens option, including types, adapters, linking to a lens from a button, and showing expired assets. Understanding lenses explains how lenses relate to taxonomy.