ContentController
Summary
Defines base controller for all controllers which need to provide HTTP route actions for all requests relative to content entities.
A content entity is an entity owned by a user, consequently user must be authenticated to use ContentController actions. Content entities which belong to the anonymous user can be manipulated by all. Content entities which belong to a particular user can be manipulated by this particular user, the super administrator, the entity manager, and, if entity is inside a group, by all users which have enough privileges on this group.
The authenticated user must have the following properties:
- String id The user id
- Array permissions An array of permissions in the following format: OPERATION-group-GROUP_ID, where OPERATION is one of ContentController.OPERATIONS and GROUP_ID the id of a group (e.g. ['get-group-Jekrn20Rl', 'update-group-Jekrn20Rl', 'delete-group-YldO3Jie3'])
A content entity has a "metadata" property with:
- String user The id of the content entity owner
- Array groups The list of groups associated to the content entity
Constructor
ContentController
Syntax
ContentController
()
Summary
Methods
addAccessFilter
Syntax
Summary
Adds access rules to the given filter reference.
Access rules make sure that content entities belong to the user (owner or in the same group). If no filter is specified, a new filter is created.
Parameters:
-
[filter]ResourceFilter optionalThe filter to add the access rules to
-
userObjectThe user information
Returns:
The modified filter or a new one if no filter specified
addEntitiesAction
Syntax
addEntitiesAction
-
request -
response -
next
Summary
Adds entities.
Information about the user (which becomes the owner) is automatically added to the entities.
Parameters:
Example:
// Response example
{
"entities": [ ... ],
"total": 42
}getAnonymousId
Syntax
Summary
Gets the id of the anonymous user.
It must be overriden by the sub class.
Returns:
The id of the anonymous user
getEntitiesAction
Syntax
getEntitiesAction
-
request -
response -
next
Summary
Gets entities.
If user does not have enough privilege to read a particular entity, the entity is not listed in the response.
Parameters:
-
requestRequestExpressJS HTTP Request
-
queryObjectRequest query
-
[include]String | Array optionalThe list of fields to include from returned entities -
[exclude]String | Array optionalThe list of fields to exclude from returned entities. Ignored if include is also specified. -
[limit]Number optionalA limit number of entities to retrieve per page (default to 10) -
[page]Number optionalThe page number started at 0 for the first page (default to 0) -
[sortBy]String optionalThe entity field to sort by -
[sortOrder]String optionalEither "asc" for ascendant or "desc" for descendant
-
-
-
responseResponseExpressJS HTTP Response
-
nextFunctionFunction to defer execution to the next registered middleware
Example:
// Response example
{
"entities" : [ ... ],
"pagination" : {
"limit": ..., // The limit number of entities by page
"page": ..., // The actual page
"pages": ..., // The total number of pages
"size": ... // The total number of entities
}getEntityAction
Syntax
getEntityAction
-
request -
response -
next
Summary
Gets a specific entity.
User must have permission to read the entity.
Parameters:
Example:
// Response example
{
"entity" : { ... }
}getProvider
Syntax
Summary
Gets an instance of the entity provider associated to the controller.Returns:
getSuperAdminId
Syntax
Summary
Gets the id of the super administrator.
It must be overriden by the sub class.
Returns:
The id of the super admin
getUserAuthorizedGroups
Syntax
Summary
Gets the list of groups of a user, with authorization on a certain operation.
All user groups with authorization on the operation are returned.
Returns:
The list of user groups which have authorization on the given operation
getUserGroups
Syntax
Summary
Gets user permissions by groups.
Parameters:
-
userObjectThe user to extract groups from
Returns:
Groups organized by ids
Example:
// Example of user permissions
['get-group-Jekrn20Rl', 'update-group-Jekrn20Rl', 'delete-group-YldO3Jie3']
// Example of returned groups
{
'Jekrn20Rl': ['get', 'update'], // User only has get / update permissions on group 'Jekrn20Rl'
'YldO3Jie3': ['delete'], // User only has delete permission on group 'YldO3Jie3'
...
}isUserAdmin
Syntax
Summary
Tests if user is the administrator.
Returns:
true if the user is the administrator, false otherwise
isUserAnonymous
Syntax
Summary
Tests if user is the anonymous user.
Returns:
true if the user is the anonymous, false otherwise
isUserAuthorized
Syntax
Summary
Validates that a user is authorized to manipulate a content entity.
User is authorized to manipulate the entity if one of the following conditions is met:
- The entity belongs to the anonymous user
- User is the super administrator
- User is the owner of the entity
- User has permission to manage contents
- Entity has associated groups and user has permission to perform the operation on one of these groups
Parameters:
Returns:
true if the user can manipulate the entity, false otherwise
isUserManager
Syntax
Summary
Tests if user is a contents manager.
A contents manager can perform CRUD operations on content entities. It must be overriden by the sub class.
Returns:
true if the user has permission to manage contents, false otherwise
isUserOwner
Syntax
Summary
Tests if user is the owner of a content entity.
Parameters:
Returns:
true if the user is the owner, false otherwise
removeEntitiesAction
Syntax
removeEntitiesAction
-
request -
response -
next
Summary
Removes entities.
User must have permission to remove the entities. If user doesn't have permission to remove a particular entity an HTTP forbidden error will be sent as response and there won't be any guarantee on the number of removed entities.
Parameters:
Example:
// Response example
{
"total": 42
}removeMetatadaFromFields
Syntax
Summary
Removes "metadata" field from query fields.
The "metadata" property of a content entity is used by ContentControllers to validate that a user has enough privileges to perform an action. "metadata" property contains the id of the user the content property belongs to and the list of groups the entity is part of. Consequently "metadata" property has to be fetched by the provider when getting an entity, however we authorize the user the exclude / include fields from provider response. removeMetadataFromFields makes sure "metadata" property is not excluded from returned fields.
Parameters:
Returns:
The same fields object with new include and exclude arrays
updateEntityAction
Syntax
updateEntityAction
-
request -
response -
next
Summary
Updates an entity.
User must have permission to update the entity. If user doesn't have permission to update the entity an HTTP forbidden error will be sent as response.
Parameters:
Example:
// Response example
{
"total": 1
}Properties
OPERATIONS
Syntax
Summary
The list of operations used to manage privileges of a user.