Skip to content

Add documentation for new workspace unique condition. #7649

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
wants to merge 1 commit into
base: main
Choose a base branch
from
+87 −73
Open

Add documentation for new workspace unique condition. #7649

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
160 changes: 87 additions & 73 deletions 15/umbraco-cms/customizing/extending-overview/extension-types/condition.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,7 +1,7 @@
---
description: >-
Learn how to declare requirements for your extensions using the Extension
Conditions.
Learn how to declare requirements for your extensions using the Extension
Conditions.
---

# Extension Conditions
Expand All @@ -14,50 +14,58 @@ For information on how to utilize conditions in your Manifest, see the [Utilizin

The following conditions are available out of the box, for all extension types that support Conditions.

* `Umb.Condition.Switch` - Toggles on and off based on the `frequency` set in seconds.
* `Umb.Condition.MultipleAppLanguages` - Requires the app to have more than one language, such as a multi-language site.
* `Umb.Condition.SectionAlias` - Requires the current Section Alias to match the one specified.
* `Umb.Condition.MenuAlias` - Requires the current Menu Alias to match the one specified.
* `Umb.Condition.WorkspaceAlias` - Requires the current Workspace Alias to match the one specified.
* `Umb.Condition.WorkspaceEntityType` - Requires the current workspace to work on the given Entity Type. Examples: 'document', 'block' or 'user'.
* `Umb.Condition.WorkspaceContentTypeAlias` - Requires the current workspace to be based on a Content Type which Alias matches the one specified.
* `Umb.Condition.Workspace.ContentHasProperties` - Requires the Content Type of the current Workspace to have properties.
* `Umb.Condition.WorkspaceHasCollection` - Requires the current Workspace to have a Collection.
* `Umb.Condition.WorkspaceEntityIsNew` - Requires the current Workspace data to be new, not yet persisted on the server.
* `Umb.Condition.EntityIsTrashed` - Requires the current entity to be trashed.
* `Umb.Condition.EntityIsNotTrashed` - Requires the current entity to not be trashed.
* `Umb.Condition.SectionUserPermission` - Requires the current user to have permissions to the given Section Alias.
* `Umb.Condition.UserPermission.Document` - Requires the current user to have specific Document permissions. Example: 'Umb.Document.Save'.
* `Umb.Condition.CurrentUser.GroupId` - Requires the current user to belong to a specific group by GUID. Accepts `match` (GUID), `oneOf` (array), `allOf` (array), and `noneOf` (array). Example: '8d2b3c4d-4f1f-4b1f-8e3d-4a6b7b8c4f1e'.
* `Umb.Condition.CurrentUser.IsAdmin` - Requires the current user to be an admin as defined by the backend, for example, that they belong to the Administrator group.
- `Umb.Condition.Switch` - Toggles on and off based on the `frequency` set in seconds.
- `Umb.Condition.MultipleAppLanguages` - Requires the app to have more than one language, such as a multi-language site.
- `Umb.Condition.SectionAlias` - Requires the current Section Alias to match the one specified.
- `Umb.Condition.MenuAlias` - Requires the current Menu Alias to match the one specified.
- `Umb.Condition.WorkspaceAlias` - Requires the current Workspace Alias to match the one specified.
- `Umb.Condition.WorkspaceContentTypeUnique` - Requires the current workspace Unique (GUID) matches the one specified.
- `Umb.Condition.WorkspaceEntityType` - Requires the current workspace to work on the given Entity Type. Examples: 'document', 'block' or 'user'.
- `Umb.Condition.WorkspaceContentTypeAlias` - Requires the current workspace to be based on a Content Type which Alias matches the one specified.
- `Umb.Condition.Workspace.ContentHasProperties` - Requires the Content Type of the current Workspace to have properties.
- `Umb.Condition.WorkspaceHasCollection` - Requires the current Workspace to have a Collection.
- `Umb.Condition.WorkspaceEntityIsNew` - Requires the current Workspace data to be new, not yet persisted on the server.
- `Umb.Condition.EntityIsTrashed` - Requires the current entity to be trashed.
- `Umb.Condition.EntityIsNotTrashed` - Requires the current entity to not be trashed.
- `Umb.Condition.SectionUserPermission` - Requires the current user to have permissions to the given Section Alias.
- `Umb.Condition.UserPermission.Document` - Requires the current user to have specific Document permissions. Example: 'Umb.Document.Save'.
- `Umb.Condition.CurrentUser.GroupId` - Requires the current user to belong to a specific group by GUID. Accepts `match` (GUID), `oneOf` (array), `allOf` (array), and `noneOf` (array). Example: '8d2b3c4d-4f1f-4b1f-8e3d-4a6b7b8c4f1e'.
- `Umb.Condition.CurrentUser.IsAdmin` - Requires the current user to be an admin as defined by the backend, for example, that they belong to the Administrator group.

## Make your own Conditions

You can make your own Conditions by creating a class that implements the `UmbExtensionCondition` interface.

```typescript
import {
UmbConditionConfigBase,
UmbConditionControllerArguments,
UmbExtensionCondition
} from '@umbraco-cms/backoffice/extension-api';
import { UmbConditionBase } from '@umbraco-cms/backoffice/extension-registry';
import { UmbControllerHost } from '@umbraco-cms/backoffice/controller-api';

export type MyExtensionConditionConfig = UmbConditionConfigBase<'My.Condition.CustomName'> & {
match?: string;
};

export class MyExtensionCondition extends UmbConditionBase<MyExtensionConditionConfig> implements UmbExtensionCondition {
constructor(host: UmbControllerHost, args: UmbConditionControllerArguments<MyExtensionConditionConfig>) {
super(host, args);

// enable extension after 10 seconds
setTimeout(() => {
this.permitted = true;
args.onChange();
}, 10000);
}
UmbConditionConfigBase,
UmbConditionControllerArguments,
UmbExtensionCondition,
} from "@umbraco-cms/backoffice/extension-api";
import { UmbConditionBase } from "@umbraco-cms/backoffice/extension-registry";
import { UmbControllerHost } from "@umbraco-cms/backoffice/controller-api";

export type MyExtensionConditionConfig =
UmbConditionConfigBase<"My.Condition.CustomName"> & {
match?: string;
};

export class MyExtensionCondition
extends UmbConditionBase<MyExtensionConditionConfig>
implements UmbExtensionCondition
{
constructor(
host: UmbControllerHost,
args: UmbConditionControllerArguments<MyExtensionConditionConfig>
) {
super(host, args);

// enable extension after 10 seconds
setTimeout(() => {
this.permitted = true;
args.onChange();
}, 10000);
}
}

// Declare the Condition Configuration Type in the global UmbExtensionConditionConfigMap interface:
Expand All @@ -74,47 +82,53 @@ The Condition then needs to be registered in the Extension Registry:

```typescript
export const manifest: UmbExtensionManifest = {
type: 'condition',
name: 'My Condition',
alias: 'My.Condition.CustomName',
api: MyExtensionCondition,
type: "condition",
name: "My Condition",
alias: "My.Condition.CustomName",
api: MyExtensionCondition,
};
```

Finally, you can make use of your condition in any manifests:

```typescript
export const manifest: UmbExtensionManifest = {
type: 'workspaceAction',
name: 'example-workspace-action',
alias: 'My.Example.WorkspaceAction',
elementName: 'my-workspace-action-element',
conditions: [
{
alias: 'Umb.Condition.SectionAlias',
match: 'My.Example.Workspace'
},
{
alias: 'My.Condition.CustomName'
}
]
}
type: "workspaceAction",
name: "example-workspace-action",
alias: "My.Example.WorkspaceAction",
elementName: "my-workspace-action-element",
conditions: [
{
alias: "Umb.Condition.SectionAlias",
match: "My.Example.Workspace",
},
{
alias: "My.Condition.CustomName",
},
],
};
```

As shown in the code above, the configuration property `match` isn't used for our condition. We can do this by replacing the timeout with some other check:

```typescript
// ...

export class MyExtensionCondition extends UmbConditionBase<MyExtensionConditionConfig> implements UmbExtensionCondition {
constructor(host: UmbControllerHost, args: UmbConditionControllerArguments<MyExtensionConditionConfig>) {
super(host, args);

if (args.config.match === 'Yes') {
this.permitted = true;
args.onChange();
export class MyExtensionCondition
extends UmbConditionBase<MyExtensionConditionConfig>
implements UmbExtensionCondition
{
constructor(
host: UmbControllerHost,
args: UmbConditionControllerArguments<MyExtensionConditionConfig>
) {
super(host, args);

if (args.config.match === "Yes") {
this.permitted = true;
args.onChange();
}
}
}
}

// ...
Expand All @@ -124,13 +138,13 @@ With all that in place, the configuration can look like shown below:

```typescript
{
// ...
conditions: [
// ...
{
alias: 'My.Condition.CustomName',
match: 'Yes'
}
]
// ...
conditions: [
// ...
{
alias: "My.Condition.CustomName",
match: "Yes",
},
];
}
```