mirror of
https://github.com/strapi/strapi.git
synced 2025-09-19 21:38:05 +00:00
Add documentation
Signed-off-by: soupette <cyril.lpz@gmail.com>
This commit is contained in:
soupette
parent
5c677e70f1
commit
dfe7780b90
@ -0,0 +1,377 @@
|
||||
# Technical documentation
|
||||
|
||||
Here we will cover how the `<Permissions />` component works.
|
||||
This component is in charge of managing the permissions of the admin panel, it has 4 children one child for each tab.
|
||||
The collection types & single types tabs uses the same component: `<ContentTypes>` similarly, the settings & plugins tab uses the `<Plugins>` component.
|
||||
|
||||
The UI uses the layout received from the back-end in order to build the UI.
|
||||
|
||||
## Layout shape
|
||||
|
||||
```js
|
||||
const layout = {
|
||||
conditions: [{ id: 'string', displayName: 'string', category: 'string'}], // Array of conditions that can be applied on a permission
|
||||
sections: {
|
||||
plugins: [
|
||||
{ displayName: 'string', action: 'string', subCategory: 'string', plugin: 'string'}
|
||||
],
|
||||
settings: [], // Same shape as the plugins
|
||||
collectionTypes: {
|
||||
subjects: [ // Array of subjects
|
||||
{
|
||||
uid: 'string', // Collection type uid,
|
||||
label: 'string', // Collection type label,
|
||||
properties: [
|
||||
{
|
||||
label: 'string', // Property label ex: Fields,
|
||||
value: 'string', // Value of the property ex: fields,
|
||||
children: [ // This corresponds to the fields that we will display
|
||||
{
|
||||
label: 'string',
|
||||
value: 'string',
|
||||
required: 'boolean', // This key is optional,
|
||||
children: [], // This key is optional, if it exists it means that a field has nested fields
|
||||
}
|
||||
]
|
||||
},
|
||||
]
|
||||
}
|
||||
],
|
||||
actions: [ // Array of actions
|
||||
{
|
||||
label: 'string', // Label of the action ex: Create,
|
||||
actionId: 'string', // id of the action ex: content-manager.explorer.create
|
||||
subjects: [<string>], // Array of subjects (collection type uid) on which the action can be applied
|
||||
applyToProperties: [<string>] // Array of properties (ex: fields or locales) on which an action can be applied
|
||||
}
|
||||
]
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Concepts
|
||||
|
||||
- Checkbox: has only 1 `checked=true` or `checked=false`.
|
||||
|
||||
- Parent checkbox: A **parent checkbox** is a checkbox which the state value depends on the state of its children ones. It means that we cannot directly access its value from the `modifiedData` object.
|
||||
Such checkbox can have multiple states:
|
||||
- someChecked: `true` or `false`,
|
||||
- checked: `true` of `false`
|
||||
> Both states are coupled: if `someChecked=true` then `checked=false`.
|
||||
> In terms of user's interaction when cliking a parent checkbox is will toggle the value of its children.
|
||||
|
||||
Ex: given the following data:
|
||||
|
||||
```js
|
||||
const modifiedData = {
|
||||
address: {
|
||||
create: {
|
||||
fields: { f1: true, f2: true,}
|
||||
locales: { en: false, fr: false}
|
||||
},
|
||||
update: {
|
||||
enabled: true,
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
From the `modifiedData` object we can identify 4 parent checkboxes:
|
||||
|
||||
1. `address` which value depends on the values of `address.create` & `address.create.update` here the state will be: `someChecked=true`
|
||||
2. `create` which value depends on the values of `address.create.fields` & `address.create.locles` here the state will be: `someChecked=true, checked=true`
|
||||
3. `fields` which value depends on the values of `address.create.fields.f1` & `address.create.fields.f2` here the state will be: `checked=true`
|
||||
4. `locales` which value depends on the values of `address.create.locales.en` & `address.create.locales.fr` here the state will be `checked=false, someChecked=falses`
|
||||
|
||||
> `address.update` is not a parent checkbox since we can access its value directly `address.update.enabled`
|
||||
|
||||
---
|
||||
|
||||
## Components architecture
|
||||
|
||||
### `<Permissions />` archictecture
|
||||
|
||||
```js
|
||||
<PermissionsDataManagerProvider>
|
||||
<Tabs>
|
||||
<ContentTypes /> // Used with the `layout.sections.collectionTypes` data
|
||||
<ContentTypes /> // Used with the `layout.sections.singleTypes` data
|
||||
<PluginsAndSettings /> // Used with the `layout.sections.settings` data
|
||||
<PluginsAndSettings /> // Used with the `layout.sections.plugins` data
|
||||
</Tabs>
|
||||
</PermissionsDataManagerProvider>
|
||||
```
|
||||
|
||||
Below, is the architecture of the `<Permissions />` component:
|
||||
|
||||
```js
|
||||
<ContentTypes>
|
||||
<GlobalActions /> // Component in charge of displaying the global action checkboxes (parent
|
||||
checkboxes), they are used to toggle all the checkboxes of the associated column
|
||||
<ContentTypeCollapses>
|
||||
{' '}
|
||||
// Wrapper or the collapse and the matrix
|
||||
<ContentTypeCollapse>
|
||||
<Collapse /> // Main row of a content type => Displays the main actions of a content type
|
||||
(parent checkboxes)
|
||||
<CollapsePropertyMatrix>
|
||||
{' '}
|
||||
// Matrix of the actions subject property
|
||||
<Header /> // Row that displays the actions labels inside a property (ex: create, read,
|
||||
update)
|
||||
<ActionRow>
|
||||
{' '}
|
||||
// Displays a subject's property values
|
||||
<SubActionRow /> // Recursive component if a property has a children key, the component
|
||||
will return itself
|
||||
</ActionRow>
|
||||
</CollapsePropetyMatrix>
|
||||
</ContentTypeCollapse>
|
||||
</ContentTypeCollapses>
|
||||
</ContentTypes>
|
||||
```
|
||||
|
||||
### Building the matrix layout
|
||||
|
||||
In order to build the layout, the components uses the `sections.collectionTypes.subjects` value received from the API.
|
||||
|
||||
#### Retrieving the actions to display in the `<GlobalActions />`
|
||||
|
||||
Pratical example:
|
||||
|
||||
```js
|
||||
// layout.sections.collectionTypes.actions
|
||||
const actions = [
|
||||
{
|
||||
label: 'Create',
|
||||
actionId: 'content-manager.explorer.A1',
|
||||
subjects: ['address', 'restaurant'],
|
||||
applyToProperties: ['fields', 'locales',],
|
||||
},
|
||||
{
|
||||
label: 'Read',
|
||||
actionId: 'content-manager.explorer.read',
|
||||
subjects: ['address'],
|
||||
applyToProperties: ['fields'],
|
||||
},
|
||||
{
|
||||
label: 'Delete',
|
||||
actionId: 'content-manager.explorer.delete',
|
||||
subjects: ['restaurant'],
|
||||
}
|
||||
{
|
||||
label: 'Publish',
|
||||
actionId: 'content-manager.explorer.publish',
|
||||
subjects: [],
|
||||
}
|
||||
]
|
||||
```
|
||||
|
||||
Here we will display only 3 actions: `create`, `read` and `delete` since they are the only actions that can be applied to a `subject`.
|
||||
|
||||
#### Building the content type's matrix
|
||||
|
||||
We will use the actions defined above and the following data:
|
||||
|
||||
```js
|
||||
// layout.sections.collectionTypes.subjects
|
||||
const subjects = [
|
||||
{
|
||||
uid: 'address',
|
||||
label: 'Address'
|
||||
properties: {
|
||||
{
|
||||
label: 'Fields',
|
||||
value: 'fields',
|
||||
children: [
|
||||
{value: 'f1', label: 'F1'},
|
||||
]
|
||||
}
|
||||
}
|
||||
},
|
||||
{
|
||||
uid: 'restaurant',
|
||||
label: 'Restaurant',
|
||||
properties: [
|
||||
{
|
||||
label: 'Fields',
|
||||
value: 'fields',
|
||||
children: [
|
||||
{
|
||||
label: 'F1',
|
||||
value: 'f1',
|
||||
children: [
|
||||
{
|
||||
label: 'F11',
|
||||
value: 'f11',
|
||||
children: [
|
||||
{ label: 'F111', value: 'f111' }
|
||||
]
|
||||
}
|
||||
]
|
||||
},
|
||||
{ label: 'F2', value: 'f2' }
|
||||
]
|
||||
},
|
||||
{
|
||||
label: 'Locales',
|
||||
value: 'locales',
|
||||
children: [{ label: 'en', value: 'en'}, { label: 'fr', value: 'fr' }]
|
||||
}
|
||||
]
|
||||
}
|
||||
]
|
||||
```
|
||||
|
||||
With this layout the ui will look like the following: (`[]` represents a checkbox )
|
||||
|
||||
| | [] Create | [] Read | [] Delete | `<GlobalActions />` | Parent Wrapper: `<ContentTypes />` |
|
||||
| ------------- | ---------- | -------- | --------- | ------------------- | -------------------------------------------- |
|
||||
| [] Address | [] | [] | | `<Collapse />` | Parent Wrapper: `<ContentTypeCollapse />` |
|
||||
| **Fields** | **Create** | **Read** | | `<Header />` | Parent Wrapper: `<CollapsePropertyMatrix />` |
|
||||
| [] F1 | [] | [] | | `<ActionRow />` | Parent Wrapper: `<CollapsePropertyMatrix />` |
|
||||
| | | | | | |
|
||||
| [] Restaurant | [] Create | [] Read | [] Delete | `<Collapse />` | Parent Wrapper: `<CollapsePropertyMatrix />` |
|
||||
| **Fields** | **Create** | | | `<Header />` | Parent Wrapper: `<CollapsePropertyMatrix />` |
|
||||
| [] F1 | [] | | | `<ActionRow />` | Parent Wrapper: `<CollapsePropertyMatrix />` |
|
||||
| F1.F11 | [] | | | `<SubActionRow />` | Parent Wrapper: `<ActionRow />` |
|
||||
| F1.F11.F111 | [] | | | `<SubActionRow />` | Parent Wrapper: `<SubActionRow />` |
|
||||
| [ ] F2 | [] | | | `<ActionRow />` | Parent Wrapper: `<CollapsePropertyMatrix />` |
|
||||
| **Locales** | **Create** | **Read** | | `<Header />` | Parent Wrapper: `<CollapsePropertyMatrix />` |
|
||||
| [ ] EN | [] | [] | | `<ActionRow />` | Parent Wrapper: `<CollapsePropertyMatrix />` |
|
||||
| [ ] FR | [] | [] | | `<ActionRow />` | Parent Wrapper: `<CollapsePropertyMatrix />` |
|
||||
|
||||
#### Shape of the `modifiedData.collectionTypes` object:
|
||||
|
||||
In order to easily know the state of a checkbox, we build the `modifiedData` using the `layout.sections.collectionTypes` to generate the following shape:
|
||||
|
||||
```js
|
||||
const conditions = [
|
||||
{
|
||||
id: 'admin::is-creator',
|
||||
displayName: 'Is creator',
|
||||
category: 'default',
|
||||
},
|
||||
{
|
||||
id: 'admin::has-same-role-as-creator',
|
||||
displayName: 'Has same role as creator',
|
||||
category: 'default',
|
||||
},
|
||||
];
|
||||
const collectionTypesDefaultForm = createDefaultCTFormFromLayout(layout.sections.collectionTypes, action, conditions)
|
||||
// createDefaultCTFormFromLayout returns an object with all the values set to false.
|
||||
// Using the data from above it will return
|
||||
|
||||
console.log(collectionTypesDefaultForm)
|
||||
|
||||
{
|
||||
address: {
|
||||
'content-manager.explorer.create': {
|
||||
fields: {
|
||||
f1: false,
|
||||
},
|
||||
conditions: {
|
||||
'admin::is-creator': false,
|
||||
'admin::has-same-role-as-creator': false
|
||||
}
|
||||
},
|
||||
'content-manager.explorer.read': {
|
||||
fields: {
|
||||
f1: false,
|
||||
},
|
||||
conditions: {
|
||||
'admin::is-creator': false,
|
||||
'admin::has-same-role-as-creator': false
|
||||
}
|
||||
},
|
||||
},
|
||||
restaurant: {
|
||||
'content-manager.explorer.create': {
|
||||
fields: {
|
||||
f1: {
|
||||
f11: {
|
||||
f111: false
|
||||
},
|
||||
},
|
||||
f2: false
|
||||
},
|
||||
locales: { en: false, fr: false},
|
||||
conditions: {
|
||||
'admin::is-creator': false,
|
||||
'admin::has-same-role-as-creator': false
|
||||
}
|
||||
},
|
||||
'content-manager.explorer.delete: {
|
||||
enabled: false,
|
||||
conditions: {
|
||||
'admin::is-creator': false,
|
||||
'admin::has-same-role-as-creator': false
|
||||
}
|
||||
},
|
||||
},
|
||||
};
|
||||
```
|
||||
|
||||
#### Getting the state of a checkbox using the `modifiedData` object
|
||||
|
||||
Examples:
|
||||
|
||||
- The `create` checkbox located in the `<GlobalActions />` component is a **parent checkbox** therefore, it's value depends on its children ones. Since, this checkbox is related the `content-manager.explorer.create` action we need to know the values of:
|
||||
- `address['content-manager.explorer.create'].fields.f1`
|
||||
- `restaurant['content-manager.explorer.create'].fields.f1.f11.f111`
|
||||
- `restaurant['content-manager.explorer.create'].fields.f2`
|
||||
- `restaurant['content-manager.explorer.create'].locales.en`
|
||||
- `restaurant['content-manager.explorer.create'].locales.fr`
|
||||
|
||||
> The `conditions` key is not a property of an action so the value of `create` does not depend on it
|
||||
|
||||
A way to dynamically retrieve the state of the `create` checkbox, is to create the following object:
|
||||
|
||||
```js
|
||||
const objectToRetrieveTheStateOfTheCreateCheckbox = {
|
||||
address: {
|
||||
fields: { f1: false },
|
||||
},
|
||||
restaurant: {
|
||||
fields: {
|
||||
f1: { f11: { f111: false } },
|
||||
f2: false,
|
||||
},
|
||||
locales: { en: false, fr: false },
|
||||
},
|
||||
};
|
||||
```
|
||||
|
||||
Know we need to know, if all the properties are `false` or if some of them `true`, since we are only dealing with `Boolean` values we can create the following array using the object:
|
||||
|
||||
```js
|
||||
const arrayOfBooleanValues = [
|
||||
false, // address.fields.f1
|
||||
false, // restaurant.field.f1.f11.f111,
|
||||
false, // restaurant.fields.f2,
|
||||
false, // restaurant.locales.en
|
||||
false, // restaurant.locales.fr
|
||||
];
|
||||
|
||||
const checkboxCreateState = { someChecked: false, allChecked: false };
|
||||
```
|
||||
|
||||
- The state of the checkbox located on the left of F1 field (`address.fields.f1`) depends on the values of `address.create.fields.f1` & `address.read.fields.f2`
|
||||
|
||||
```js
|
||||
const objectToRetrieveTheStateOfTheCheckbox = {
|
||||
create: {
|
||||
f1: false,
|
||||
},
|
||||
read: {
|
||||
f1: false,
|
||||
},
|
||||
};
|
||||
|
||||
const arrayOfBooleanVales = [false, false];
|
||||
|
||||
const checkboxState = { someChecked: false, allChecked: false };
|
||||
```
|
||||
Loading…
x
Reference in New Issue
Block a user