| title | Building Blocks |
|---|
This part of the documentation will be about the core concepts of Gentics Mesh.
You will learn:
-
What is needed to setup a project?
-
What are the core concepts and most relevant parts of the API to get started?
-
How to design your content model?
-
How to manage users and permissions?
In Gentics Mesh a project is the place to organize all the contents and media assets for a given project, e.g. a product catalogue website, your blog, your company intranet, an e-commerce website, a social community app - you name it. You can create as many projects as you would like.
A project represents the base element of your content structure, which includes your actual content items called nodes as well as tag families. The tags for tagging content items are grouped in tag families and are defined for a specific project. Schemas are assigned to projects in order to specify what types of nodes can be created. Users have access to a project and its contained content items depending on the role(s) they’ve been assigned.
|
Tip
|
Gentics Mesh creates a root or base node for each project. As you will learn soon, each node needs to have a schema it follows. Hence, when creating a new project you need to name a schema. You can use the |
| Description | API endpoint |
|---|---|
Create a project |
|
Get all projects |
|
Get a project |
|
Update a project |
|
Delete a node |
Content items in Gentics Mesh are called nodes and represent the main structural building blocks for your content. A node is a specific piece of content within your project. The type of a node is always defined by the assigned schema. For example, in a product catalogue website you would create content types like product, product categories, product images, and product manuals.
|
Note
|
In Gentics Mesh every content item is a node, there is no separate concept for media assets such as images, videos, and documents. Instead content types for them can be defined individually giving you the freedom to store any metadata with your assets. For your convenience Gentics Mesh is shipped with four default schemas - image, video, audio and document to be customized to your needs and liking! |
Nodes can be hierarchically structured if the schema is allowing this. They can be tagged by any number of tags. Furthermore, nodes can be translated into other languages, thus supporting multiple locales.
|
Note
|
It is important to understand that a node is just a container for language variants. These language variants will store the actual fields. You can query individual language variants by appending the |
| Description | API endpoint |
|---|---|
Create a new node |
|
Get all nodes of a project |
|
Get a node |
|
Update a node |
|
Delete a node |
|
Update an image, video, or document |
|
Get an image, video, or document - Crop & resize images |
|
Crop & resize and update an image |
|
Get all child nodes |
|
Delete the language specific content of a node |
|
Get the publish status for the given language of a node |
|
Move a node |
|
Get a navigation object |
|
Get the published status of a node |
|
Publish a node |
|
Unpublish a node |
|
Get the tag list of a node |
|
Update the tag list of a node |
|
Tag a node |
|
Remove a tag from a node |
|
Typically, each project will require a set of different content types. Together they can be considered the content model of your project. Staying with the example of a product catalogue website: a product, product category, product image, and product manual each represent a separate content type. In Gentics Mesh, a schema is used to define such content types in terms of a couple of standard fields (e.g. uuidnamedescriptionversionstringnumberHTMLdatebinarylistnodemicronodebooleanjson
|
Tip
|
Using the |
| Description | API endpoint |
|---|---|
Create a schema |
|
Get all schemas |
|
Get a schema |
|
Update a schema |
|
Delete a schema |
|
Create a changeset for link:{{< relref "features.asciidoc" >}}#_schema_microschema_migration[migrating] a schema and all affected nodes |
|
link:{{< relref "features.asciidoc" >}}#_schema_microschema_migration[Migrate] a schema and all affected nodes with a set of changes |
link:content/docs/api/response{apiLatest}/schemas/{schemaUuid}/200/example.json[role=include]Gentics Mesh allows you to define custom content types with a set of schema fields. A field is defined by an object which must have the following properties:
-
nameA unique name to identify the field. -
typeThe type of data to be stored in this field.
The following optional properties may be applied to any type of field:
-
requiredIftrue, this field may not be left empty. -
labelA human-readable label for the field to be used as a form label in the Gentics Mesh User Interface. If not defined, thename -
elasticsearchThe Elasticsearch custom mapping options of the field.
In addition to the above, certain types expose additional properties with which to configure the field. Such additional properties are defined in the Schema Field Types section.
The elasticsearch property of a schema field can be used to fine-tune the Elasticsearch integration. The property can contain additional options which can be used to influence how the field information is added to the search index.
A typical example is the addition of a raw field. Sometimes it may be useful to store a field in the Elasticsearch index without being tokenized first. This is useful for term queries which are used to find the exact term specified in the query.
By default no raw field will be added to the search index. You can however use the elasticsearch property to add this field to the index.
The raw field can be added by specifying a custom field mapping. The JSON of the custom mapping will be added to the full index mapping which Gentics Mesh is generating via the schema. You can read more about how to define field mappings in the fields mapping documentation of Elasticsearch.
{
"name": "dummySchema",
"displayField": "name",
"fields": [
{
"name": "name",
"label": "Name",
"required": true,
"type": "string",
"elasticsearch": {
"raw": {
"index": "not_analyzed",
"type": "string"
}
}
}
]
}|
Note
|
Raw field values which exceed 32KB in size will automatically be truncated to be indexable. |
The elasticsearch property can also be used to add field mappings which utilize custom analyzers. You can define custom analyzers and tokenizers within the top level elasticsearch property of the schema.
Once a new analyzer has been defined in the toplevel elasticsearch property it can be referenced by custom field mappings which can now be added to each field.
Typical example for a string schema field:
{
"name" : "name",
"label" : "Name",
"required" : true,
"type" : "string",
"allow": ["red", "green", "blue"],
"elasticsearch": {
"raw": {
"index": "not_analyzed",
"type": "string"
}
}
}A stringrequiredallow
The numberrequired
The optional min
The optional max
The optional step
The daterequired
The booleanrequired
The htmlrequired
The jsonrequiredallow
A micronoderequired
A micronodeallow
A noderequired
A nodeallow
A list
(1) Within a node you can have simple lists of arbitrary length. The listTypestringnumberdatebooleanjsonHTML
(2) You can unleash the power of micronodes, by specifying a list with the listTypemicronodeallow
(3) Furthermore, a listlistTypenoderequired
A micronodenodeallow
The binary field type is used to store binary data, e.g., image, video, audio and documents.
Depending on the actual data and configuration, Gentics Mesh will store related metadata e.g., fileNamefileSizemimeTypesha512sumwidthheightdominantColormimeTypedominantColorfileName
The required
The checkServiceUrl (string) property indicates whether binaries must be checked by an external service before being available for download. When the property is set, new binaries will have a check status of `POSTPONEDACCEPTED or DENIED. Requests for binaries with a status other than ACCEPTED will result in a 404 Not Found response with the information that the binary has not been accepted (yet). Mesh will regularly send requests to the configured check service to validate the uploaded binary data, which is expected to send the result to the binary check callback endpoint. See the link:{{< relref "features.asciidoc" >}}#binarycheck[file upload documentation] for more information.
The extract
extract.content(boolean)-
Extracts and sends plain text content to Elasticsearch if available.
extract.metadata(boolean)-
Extracts and sends metadata to Elasticsearch. An example for metadata is exif data from JPGs.
Example of a complete binary field schema:
{
"name" : "binary_content",
"label" : "Binary Content",
"required" : false,
"type" : "binary",
"checkServiceUrl": "http://localhost:3000/check",
"extract": {
"content": true,
"metadata": false
}
}Setting the extract object will override the global configurations for parsing (link:{{< relref "administration-guide.asciidoc" >}}#_upload_options[upload.parsersearch.includeBinaryFields
Setting the global metadata whitelist (link:{{< relref "administration-guide.asciidoc" >}}#_upload_options[upload.metadataWhitelist
Exactly the same binary as above, with the only difference of being stored in the Amazon S3 storage. This field requires (link:{{< relref "administration-guide.asciidoc" >}}#_s3_storage_options[S3 Storage
A micronode is similar to a node. It also follows a schema - a microschemaModel. It is bound to a node and thus is not directly accessible from within the project node tree structure.
With micronodes it is possible to build complex object data structures as they are basically representing subnodes of nodes.
Typical use cases for micronodes are content items that do not exist on their own but are tied to their (parent) node, e.g., media elements of your blog post such as YouTube videos, image galleries, Google maps, image captions, vcards, quotes, text paragraphs. As another example consider a recipe having a list of ingredients which in turn consist of a name and a quantity.
|
Note
|
Nodes can contain micronodes. Micronodes, however, can not contain further micronodes, thus limiting the nesting level to one. |
| Description | API endpoint |
|---|---|
Create a microschemaModel |
|
Get all microschemas |
|
Get a microschemaModel |
|
Update a microschemaModel |
|
Delete a microschemaModel |
|
Create a changeset for link:{{< relref "features.asciidoc" >}}#_schema_microschema_migration[migrating] a microschemaModel and all affected nodes |
|
link:{{< relref "features.asciidoc" >}}#_schema_microschema_migration[Migrate] a microschemaModel and all affected nodes with a set of changes |
Microschemas share the same properties as schemas except for the properties displayFieldcontainersegmentField
Gentics Mesh allows tagging of nodes and content branches. Tags of a specific kind are always part of a tag family.
A typical example would be:
The tags red, green, blue belong to the tag family colors.
Tags can’t be hierarchically structured, are not translatable and can only applied to nodes and branches.
|
Tip
|
If you don’t want to work with uuids you can also specify the tags within the node update or node create request. The given tag list will automatically be applied to the node. Any missing tags in the list will be removed from the node. |
| Description | API endpoint |
|---|---|
Get the tag list of a node |
|
Update the tag list of a node |
|
Tag a node |
|
Remove a tag from a node |
|
Tags that semantically belong together are grouped in a tag family, allowing to handle disambiguation.
Example tags and tag families:
| Tag Family | Tags |
|---|---|
Fruit |
Apple, Pear, Orange |
Company |
Apple, Microsoft, Google, Amazon |
A tag family is defined as part of a project. Tag families can’t be nested.
| Description | API endpoint |
|---|---|
Get all tag families |
|
Create a tag family. |
|
Get a tag family |
|
Update a tag family |
|
Delete a tag family |
|
Get all tags of a tag family |
|
Get a specified tag from a tag family |
|
Update a specified tag |
|
Remove a tag from a tag family |
|
Get all nodes that have been tagged with the tag |
|
Gentics Mesh users can be physical persons or client apps interacting with elements in Gentics Mesh. Both have a user object counterpart in Gentics Mesh.
This user object has a standard set of properties, e.g.firstnamelastnameusernameemailAddress
|
Tip
|
Gentics Mesh supports user management for your apps! The property |
In order to be able to store and retrieve content, a user needs to authenticate using one of the available link:{{< relref "references.asciidoc" >}}#_authentication[authentication] mechanisms.
| Description | API endpoint |
|---|---|
Get all users |
|
Create a user |
|
Get a user |
|
Update a user |
|
Deactivate a user |
|
Read user permissions on elements |
|
Return a one time token to update a user |
|
Return an API token |
|
Invalidate an API token |
Groups are used to organize users and efficiently grant them permissions by assigning relevant roles to groups. Groups ca not be nested. Instead, a user can be part of several groups.
| Description | API endpoint |
|---|---|
Get all groups |
|
Create a group |
|
Get a group |
|
Update a group |
|
Delete a group |
|
Get all roles assigned to a group |
|
Assign a role to a group |
|
Remove a role from a group |
|
Get all users assigned to a group |
|
Add user to a group |
|
Remove user from a group |
Roles are used to manage link:{{< relref "features.asciidoc" >}}#_permissions[permissions] between the role and other elements in Gentics Mesh (i.e., nodes, schemas, users, roles, etc.). Roles can be assigned to groups. Thus, a user of a group with roles inherits the permissions that are bound to these roles. Roles can’t be nested.
| Description | API endpoint |
|---|---|
Get all roles |
|
Create a role |
|
Get a role |
|
Update a role |
|
Delete a role |
|
Read role permissions on elements |
|
Set role permissions on elements |