Component Visibility (Private Beta)

Component visibility lets you decide, for each component model, who can add it to a page and where it can go. Use it to keep a page's structure the way you designed it: a hero component that only goes in the hero zone, a component only your design team should place, or a component that belongs to one site and not another. You can also disable a component so nobody can add it, without deleting the model or touching the pages that already use it.

What it affects, and what it doesn't

Visibility rules only apply when a component is placed:

• adding a component to a zone
• moving a component to a different zone, or onto a different page model
• copying a component to a page

A component that's already on a page is never affected. It keeps rendering on your site, and editors can keep editing it, reordering it within its zone, and removing it. A rule only stops a new placement, so adding a rule never breaks an existing page, and re-saving a page that already holds a component the rule wouldn't allow still works.

Nothing changes on an instance until someone sets a rule. A component with no rules can be added by anyone who can edit the page, anywhere, just as before.

Set a component's visibility

1. Go to Models → Component Models and open the component model.
2. In the right-hand rail, choose Visibility.
3. Set Who can add this component, Sitemaps, and Page models and zones (each is described below).
4. Save.

Administrators, Managers and Designers can change visibility. The component models list shows a Visibility column, so you can see at a glance which components are Disabled or Restricted, and hover for a summary of each rule.

Who can add this component

Option	What it means
Anyone who can edit the page	The default. Anyone who can edit the page can add the component.
Only these people	Only the people you choose can add it. Choose any of Designers, Managers, specific Users and specific Teams. Administrators are always included.
Nobody (disabled)	Nobody can add or copy the component, Administrators included, and it's hidden from the component list. See Disable a component.

Designers and Managers mean anyone who holds that permission, whatever their role is called on your instance. Someone who belongs to a chosen team can add the component, including when the team gives them their access to the instance.

Where it can go

Two settings control where a component can be placed. A component must match both.

Sitemaps. Choose All sitemaps, or Only these sitemaps and pick them. A page belongs to the sitemap at the top of its page tree.

Page models and zones. Choose Anywhere, or Only these page models and zones. Pick a page model to allow all of its zones, or pick only the zones you want. For example, to keep a hero component in the hero zone, pick just the Hero zone of each page model that has one.

The "where" rules apply to everyone, Administrators included, because they're about the page's structure, not about who's editing it.

If a sitemap, page model or zone you picked is later deleted, the rule shows it as (deleted). A deleted target never matches. If every target in a list has been deleted, the component can't be placed anywhere until you update the rule.

Disable a component

Choose Nobody (disabled) under Who can add this component to retire a component without deleting it. This is useful when several instances share the same models (for example, when you sync them with the CLI) and a component doesn't apply to one of them.

When a component is disabled:

• nobody can add it or copy it, Administrators included;
• it's hidden from the component list in the page editor;
• components already on a page still render and stay editable, and they can still be moved to another zone or page model, as long as the "who" and "where" rules allow it.

To use it again, choose Anyone who can edit the page or Only these people.

What editors see

The page editor only offers what a rule allows:

• the component list only shows the components this person can add on this page;
• when adding a component, Choose Zone only lists the zones it's allowed in;
• a zone the component can't go in won't accept it when it's dragged there;
• Copy Component only offers the zones of the target page that the component is allowed in;
• when you change a page's page model, each component moves to the first zone of the new page model that it's allowed in. If a component isn't allowed in any of them, the change is stopped and Agility lists the components that are in the way.

If a placement is refused, the message says why, using one of these sentences:

• The "Hero" component is disabled on this instance.
• You don't have permission to add the "Hero" component.
• The "Hero" component isn't allowed on the "Main" sitemap.
• The "Hero" component isn't allowed in the "Main Content" zone of the "Landing Page" page model.

For the editor's view of this, see Why can't I add a component?.

The Management API, MCP and CLI

The same rules are checked on the server, so they apply however a page is saved: the Manager App, the Management API, the Management SDK, the MCP server and the Agility CLI.

• Saving a page. A page save that places a component the rules don't allow is refused with a 400, and the message is one of the sentences above. The whole save is refused, so none of that save's other changes to the page are kept. As in the Manager App, a placement that's already on the page is never re-checked. The check is made as the user the token belongs to, so a script running with a non-Administrator's Personal Access Token can be refused by a "who" rule.

• Reading and setting rules. The Management API has three endpoints, documented in the API reference:

  • GET /api/v1/instance/{guid}/model/availability returns the rules of every component model that has any.
  • GET /api/v1/instance/{guid}/model/{id}/availability returns one component model's rules. A null addableBy means anyone who can edit the page, and a null allowedIn means anywhere.
  • POST /api/v1/instance/{guid}/model/{id}/availability saves them. addableBy and allowedIn are saved separately: leave a group out (or send null) to keep it, send an object to replace it, or send one whose lists are all empty to remove the restriction. Users, teams, sitemaps, page models and zones are matched by ID, or by email address or name when the ID isn't found, so a rule can be copied between instances. If any target can't be matched, nothing is saved and the 400 lists them.

  Anyone on the instance can read the rules. Saving them needs the same permission as saving a model.

• Disabling a component is done in the Visibility pane. Through the Management API, a model's isVisible setting only applies when the model is created; saving an existing model never changes it.

Syncing instances with the CLI

Visibility settings belong to each instance:

• Who and where rules are never copied by agility sync. Set them on each instance.
• Disabled is copied only when the sync creates the model on the target instance. After that, each instance keeps its own setting, so a component you disable on one instance stays disabled through every later sync.
• If the sync can't save a page because of a visibility rule on the target (for example, a new page that uses a component the target has disabled), that page is skipped and the reason is shown in the sync summary. The sync carries on with the other pages. The page is tried again on the next sync, so change the rule, the model or the source page to let it through.

Good to know

• Visibility controls placement only. It doesn't hide a component's content on your website, and it doesn't stop anyone from editing a component that's already on a page.
• Rules apply to component models. Content models and page models aren't covered yet.
• A change to a rule can take a couple of minutes to show up in a page editor that's already open.

Related

• Component Models
• Page Models
• User Permissions
• Why can't I add a component?