Home > Developer Documentation Center > Guides and Tutorials > Educational > First Steps With Studio: Technical Documentation Tutorial > Documentation Item Implementation
Guides and Tutorials

Documentation Item Implementation

Updated: October 16, 2020

At this first step, we will create a new document type called documentationItem. This documentation item will be the main document type we will be using in our project.

We recommend you first take a look at the Repository Concepts page if you are not yet familiar with the Nuxeo Platform.

Item names
In this section we provide example names for items. You'll see different names in screen shots. Most of the time a suffix like "tuto" is added. In your Studio project please use the suggested names (or invent your own) and not the ones in screen shots.

Declaring the New Document Type

As stated in the introduction of the project, the goal is to manage all kinds of documents like procedures or notices. We will use one document type called documentationItem. And we will use the Nature metadata to differentiate the different kinds of documentation items. See the page Several Document Types vs One Document Type with a Nature Metadata for more information.

To create the documentationItem document type:

  1. In Nuxeo Studio, go in Content Model > Document Types.
  2. Click on New.
  3. Type a feature ID (i.e. the document type name in Studio): documentationItem.
  4. Choose what document type it extends. Here we need to have something holding a binary file with metadata, life cycle, version and validation. This is very similar to the "File" document type. So let's extend this one to have the same facets and schemas (it is still possible to add new schemas later).
  5. Type a label for the end user in the Nuxeo Platform: Technical documentation item.
  6. Click on Next.
    The documentationItem document type is created.
  7. Click on the Save button.

Check your changes on the Nuxeo Platform:

  1. Go to your Nuxeo Platform and deploy your project.
  2. On the Nuxeo Platform interface, go in a workspace and click on New. You should see "Technical Document item" in the Miscellaneous category.

The new document type is created, it is now time to customize it.

Defining Properties and Facets

Let's define some properties of the documentationItem.

  1. In Studio go back on the documentationItem Definition tab.
  2. Select the category Document. The category is where the document type will be shown in the Nuxeo Platform UI when a user clicks on the New button. Default is Miscellaneous, but Document is a good idea in this case.
  3. Choose icons.
  4. Leave the default life cycle for now. We will change it later.
  5. Container type are the spaces in which the document can be created. For now Folder and Workspace are fine.
  6. Take a look at the facets. The ones we are interested in are already selected and grayed out: versionable, can be published. This is because the DocumentationItem inherits the File doc type facets.
  7. Leave the inherited schemas for now, we will come back to it later
  8. Click on Save.

The documentation item is now available in the correct category and it has some icons. But it does not hold the needed informations (process, nature, binary...).

Read more:

Defining the Metadata

Checking the Metadata and Schemas You Need

To be able to describe and find the document, the following metadata should be available on the document:

  • A nature: a simple and limited list of choices
  • A process: a two level list of choices. Since there can be many processes we will group them by category.
  • The usual descriptive information (title, description, creation date, creator...)
  • A binary file (Word, PDF...): the attachment that will be the actual content. On the Nuxeo Platform, binary files are "just another metadata" with a specific type (blob).

In the Nuxeo Platform metadata are always grouped by schemas. A schema is a set of metadata that make sense together. A document very often has several schemas of metadata. In Studio, look at the bottom of the Definition tab: there are already several inherited schemas. Once again, this is because DocumentationItem extends File.

  • common and uid are schemas used by the system.
  • file is a schema defined to hold a binary file. This exactly what we need.
  • files enables to hold other binaries (like attached files). This could be useful for the annexes of the documentationItem for instance.
  • dublincore is a standard schema that holds descriptive information like title, creator... One of them is "nature" which is perfect for our needs. There is no need to redefine a nature metadata as it is already available.

In the end the only metadata that is not already available is the "process". So let's create a new metadata in Studio.

Read more:

Creating the Schema

In Studio, each document type has its own dedicated schema. It can be found in the Schema tab, next to the Definition tab. The "process" metadata can be a generic metadata in a technical documentation management app. So let's create a generic schema in the Schemas item on the menu of Nuxeo Studio.

  1. Click on Content Model > Schemas.
  2. Click on the New button.
  3. Name the schema quality as processes are often managed by quality departments. The idea here to have a schema that could have several metadata of the same domain.
  4. Choose a shorter name for the prefix: qa.
  5. Click on Next to validate the schema creation. The schema is created. It is empty for now.

Adding the Schema to the documentationItem Document Type

Now you add this new schema to the DocumentationItem document type:

  1. Go back to the Definition tab of the document type.
  2. Scroll down to the bottom of the tab.
  3. Expend Add extra schemas to this document type.
  4. In the left list select the quality schema.
  5. Add it to the right list.
  6. Click on Save. The schema is now available on the document type. So every metadata added to the schema will automatically be added to the document.

Adding a Metadata to the Schema

  1. In Studio, go to the quality schema.
  2. Add a new field and name it process.
  3. Select the String type.
  4. A document is only related to one process, so we do not check Multi-Valued.
  5. Click on Save.

Nuxeo makes a difference between the content model (what are the document types and metadata?) and the user interface. The metadata is available on the document but we haven't defined how to fill in this metadata.

Read more:

Showing Metadata in the User Interface

Metadata are displayed in form layouts. A form layout can be generic and reused by several documents or it can be specific to a document type. In our example, we will change the specific layouts of our document type.

  1. Go on the DocumentationItem definition. Four layout tabs are available. Each layout corresponds to a way to access the document: creation, view, edition. You can then control what can be seen and modified. The header layout is what you see on the top of the document. We will leave it empty, and it will take the default layout that displays the title of the document.
  2. Click on the Creation Layout tab. You can see that the layout is already filled with a minimum set of metadata.
  3. Click on the icon of the WARNING row and confirm deletion.
  4. Select the quality schema in the right drop down list.
  5. Drag the process metadata from the list and drop it on a row of the layout. The widget edition pop-up displays several options for the widget you just dropped.
  6. Leave the default values for now, and click on Save.
  7. Click on the Add Row button to add two new rows to the layout.
  8. In the dublincore schema, drag and drop the Nature metadata on a row and save default values.
  9. In the file schema, drag and drop the content metadata and save default values. In the end you should have a creation layout looking like:
    Which will give, once deployed on the server:

If we look back at what we wanted on the document, we have all the information we wanted but not how we wanted them. Nature and Process should be lists of choices and not simple text boxes.

Read more:

Showing a List of Choices in the UI for a Metadata

In the Nuxeo Platform lists of choices are called vocabularies. A specific section is available in Studio for them.

Creating the Nature Choices

  1. In Studio, go in the Vocabularies section.
  2. Create a new vocabulary: call it it qualNat, and select Simple Vocabulary.
  3. Add a few entries (ids are for the system, labels will be displayed to the final user). In the end, you should have something like:

Creating the Process Choices

  1. Create a new vocabulary: call it procQual and select the type Hierarchical Vocabulary. We need a two-level vocabulary as they are processes and sub-processes.
  2. By default, you already have two levels. You can add several roots (processes) and children for each roots (sub-subprocesses). In the end, you can have something like that (please note that these are dummy processes):

Now that you have the two vocabularies, you still have to bind them to the metadata so that the user can select them. This is where we will customize each metadata widget in the creation layout from a simple text to list of choices.

Read more:

Configuring the Nature Widget

  1. Go back to the creation layout of DocumentationItem.
  2. Edit the Nature metadata widget by clicking on the icon .
  3. In the Layout Widget Editor, select the widget type Vocabulary.
  4. In the Edit properties part, select the vocabulary qualNat.
  5. You can make the nature field required if you want to by selecting Yes in the Required drop down list.
  6. Click on Save.

Configuring the Process Widget

  1. Edit the process widget.
  2. In the Layout Widget Editor, select the widget type Chained vocabulary.
  3. Select the vocabulary procQual.
  4. Click on Save. The Creation Layout is now fully configured.

Applying the Creation Layout Configuration to Other Layouts

  1. Click on the View Layout tab, and click on Import Layout > Import 'create' layout. It imports what you did on the creation layout, so that you are able to see on the Summary tab the metadata of your document.
  2. Do the same thing on the Edit Layout tab.
  3. Click on Save.

Testing Your Changes

  1. Redeploy your customization the server.
  2. Create a new Technical Documentation Item. You should see:

Congratulation
You created a document type that will hold all the information you need to manage your technical documentation items.

To sum up, what we saw:

  • A document type can have metadata of several types (String, Integer...).
  • Metadata are grouped in schemas. Of course, one document can have several schemas.
  • The content model is different from the user interface. When you add a metadata to a document (through its schemas), you have to add the metadata in the layouts of the document.
  • You can control how the metadata are filled in directly from the layouts of the document by changing the widget type.

The next step is to adapt where the documents are created and how they are displayed when browsing.

Read more: