Constructor
new ContentController()
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
- Source:
Extends
Members
(static, constant) OPERATIONS :Object
The list of operations used to manage privileges of a user.
Type:
- Object
- Default Value:
{"READ":"get","UPDATE":"update","DELETE":"delete"}
- Source:
Methods
(private, static) getUserAuthorizedGroups(user, operation) → {Array}
Gets the list of groups of a user, with authorization on a certain operation.
All user groups with authorization on the operation are returned.
Parameters:
Name | Type | Description |
---|---|---|
user |
Object | The user |
operation |
String | The operation (get, update or delete) |
- Source:
Returns:
The list of user groups which have authorization on the given operation
- Type
- Array
(private, static) getUserGroups(user) → {Object}
Gets user permissions by groups.
Parameters:
Name | Type | Description |
---|---|---|
user |
Object | The user to extract groups from |
- Source:
Returns:
Groups organized by ids
- Type
- Object
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'
...
}
addAccessFilter(filteropt, user) → {ResourceFilter}
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:
Name | Type | Attributes | Description | |||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|
filter |
ResourceFilter |
<optional> |
The filter to add the access rules to |
|||||||||
user |
Object | The user information Properties
|
- Source:
Returns:
The modified filter or a new one if no filter specified
- Type
- ResourceFilter
addEntitiesAction(request, response, next)
Adds entities.
Information about the user (which becomes the owner) is automatically added to the entities.
Parameters:
Name | Type | Description | ||||||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
request |
Object | ExpressJS HTTP Request Properties
|
||||||||||||||
response |
Object | ExpressJS HTTP Response |
||||||||||||||
next |
function | Function to defer execution to the next registered middleware |
- Overrides:
- Source:
Example
// Response example
{
"entities": [ ... ],
"total": 42
}
getAnonymousId() → {String}
Gets the id of the anonymous user.
It must be overriden by the sub class.
- Source:
Throws:
-
getAnonymousId is not implemented
- Type
- Error
Returns:
The id of the anonymous user
- Type
- String
getEntitiesAction(request, response, next)
Gets entities.
If user does not have enough privilege to read a particular entity, the entity is not listed in the response.
Parameters:
Name | Type | Description | ||||||||||||||||||||||||||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
request |
Object | ExpressJS HTTP Request Properties
|
||||||||||||||||||||||||||||||||||
response |
Object | ExpressJS HTTP Response |
||||||||||||||||||||||||||||||||||
next |
function | Function to defer execution to the next registered middleware |
- Overrides:
- Source:
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(request, response, next)
Gets a specific entity.
User must have permission to read the entity.
Parameters:
Name | Type | Description | |||||||||||||||||||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
request |
Object | ExpressJS HTTP Request Properties
|
|||||||||||||||||||||||||||
response |
Object | ExpressJS HTTP Response |
|||||||||||||||||||||||||||
next |
function | Function to defer execution to the next registered middleware |
- Overrides:
- Source:
Example
// Response example
{
"entity" : { ... }
}
getProvider() → {EntityProvider}
Gets an instance of the entity provider associated to the controller.
- Inherited From:
- Source:
Throws:
-
getProvider not implemented for this EntityController
- Type
- Error
Returns:
The entity provider
- Type
- EntityProvider
getSuperAdminId() → {String}
Gets the id of the super administrator.
It must be overriden by the sub class.
- Source:
Throws:
-
getSuperAdminId is not implemented
- Type
- Error
Returns:
The id of the super admin
- Type
- String
isUserAdmin(user) → {Boolean}
Tests if user is the administrator.
Parameters:
Name | Type | Description | ||||||
---|---|---|---|---|---|---|---|---|
user |
Object | The user to test Properties
|
- Source:
Returns:
true if the user is the administrator, false otherwise
- Type
- Boolean
isUserAnonymous(user) → {Boolean}
Tests if user is the anonymous user.
Parameters:
Name | Type | Description | ||||||
---|---|---|---|---|---|---|---|---|
user |
Object | The user to test Properties
|
- Source:
Returns:
true if the user is the anonymous, false otherwise
- Type
- Boolean
isUserAuthorized(user, entity, operation) → {Boolean}
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:
Name | Type | Description | |||||||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
user |
Object | The user Properties
|
|||||||||||||||
entity |
Object | The entity to manipulate Properties
|
|||||||||||||||
operation |
String | The operation to perform on the entity |
- Source:
Returns:
true if the user can manipulate the entity, false otherwise
- Type
- Boolean
isUserManager(user) → {Boolean}
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.
Parameters:
Name | Type | Description | ||||||
---|---|---|---|---|---|---|---|---|
user |
Object | The user to test Properties
|
- Source:
Throws:
-
isUserManager is not implemented
- Type
- Error
Returns:
true if the user has permission to manage contents, false otherwise
- Type
- Boolean
isUserOwner(entity, user) → {Boolean}
Tests if user is the owner of a content entity.
Parameters:
Name | Type | Description | ||||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
entity |
Object | The entity to test Properties
|
||||||||||||
user |
Object | The user to test Properties
|
- Source:
Returns:
true if the user is the owner, false otherwise
- Type
- Boolean
removeEntitiesAction(request, response, next)
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:
Name | Type | Description | ||||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
request |
Object | ExpressJS HTTP Request Properties
|
||||||||||||
response |
Object | ExpressJS HTTP Response |
||||||||||||
next |
function | Function to defer execution to the next registered middleware |
- Overrides:
- Source:
Example
// Response example
{
"total": 42
}
removeMetatadaFromFields(fields) → {Object}
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:
Name | Type | Description | ||||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
fields |
Object | The include and exclude fields Properties
|
- Source:
Returns:
The same fields object with new include and exclude arrays
- Type
- Object
updateEntityAction(request, response, next)
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:
Name | Type | Description | |||||||||||||||||||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
request |
Object | ExpressJS HTTP Request Properties
|
|||||||||||||||||||||||||||
response |
Object | ExpressJS HTTP Response |
|||||||||||||||||||||||||||
next |
function | Function to defer execution to the next registered middleware |
- Overrides:
- Source:
Example
// Response example
{
"total": 1
}