Table of Contents

Creating a master detail

Creating an entity

To create our master detail screen, the first step is to add another entity. In the following example, you will add a category to our product. As explained in this article, go to the Entities section and click on the + button. Call this entity Category:

Name = Category
Description = My categories

Add the following properties to our new entity:

CategoryID:

Name = CategoryID
Caption = Category ID
Data type = AutoIncrementedInteger
Is key = true

CategoryName:

Name = CategoryName
Caption = Category name
Data type = String
Required = true

Description:

Name = Description
Caption = Category description
Data type = String
Required = true
Warning

Don't forget to click on the save button.

Associating the entities

Creating the property

You will add a category to the product by referencing this newly created entity.

To do so, open the Entity item in the menu and click on Product. You can see the entity with its properties. Click on the Add button in the Properties table and create the following property:

CategoryID:

Name = CategoryID
Caption = Category ID
Data type = Integer
Required = true

Creating the reference

Adding the property is not enough to link two entities. It is necessary to create a reference from the entity Product to the entity Category. A reference will link an entity A (Entity = Product) to an entity B (Referenced entity = Category) from one or more properties (Scalar properties = CategoryID). A navigation property will be added on entity A to access entity B (Referenced entity = Category). You also have the possibility to create a navigation property on entity B to access to entity A (Referenced entity navigation property = Products). In principle this is optional, but it is needed here in order to create a sub view for our master-detail.

Note

If you do not create the scalar property first, it will be automatically generated from the information entered in the reference.However, this exercise will help you to understand that the reference is inseparable from its scalar property. For more details on references and collections on entities, see this article.

Click on the v next to the Add button and select Add reference (one to many) button to create the new reference :

Category:

Referenced entity = Category
Name = Category
Property linked to Category.CategoryID = CategoryID
Create the collection in the entity = true
Name of the collection created in the entity = ProductList
Warning

Don't forget to click on the save button.

Generating all the metadata

Generate the metadata for the following two entities as seen in the the previous article :

  • First, for the entity Category
  • And then, for the entity Product to update it and add the reference

This process will create the following objects from the entity :

  • A Category data table and its columns
  • A CategoryView entity view and its properties for retrieving categories from their storage
  • A CategoryUI user interface view (UI view), its properties and its template for listing and editing categories
  • A Category menu item

Updating the menu

The Category menu item has been created during the previous step but you need to add it to the Catalog menu. In the menu on the left, deploy the Catalog module, click on Frontend, deploy the Menus item, open the Catalog menu and add a menu item using the one generated : Category

Before continuing further, you need to generate the application to be able to use all the newly generated elements linked to your entity. This manipulation is described here.

Warning

Be careful: if you have started entering data and you have chosen database persistence, you will get this kind of error:

System.Exception: An error occurred executing the following sql:
ALTER TABLE "public"."Product" ALTER "CategoryID" TYPE integer, ALTER "CategoryID" SET NOT NULL;
The error was 23502: column « CategoryID » of table « Product » contains null values

The modification fails because there are already null values in the "CategoryID" column. The non-nullity constraint prevents the insertion of null values in the column, but since there are already null values present, the modification is rejected with error 23502. To resolve this error, you must first ensure that there are no null values in the "CategoryID" column. You can either delete the rows containing null values or assign them a non-null value before attempting to modify the table structure.

Updating the UI

If you open the application at this stage, you will find that you have two independent screens to create and modify the Product and Category entities. If you want to have a master-detail screen to consult a category and its products, you have to modify the category screen. To do so, open the CategoryUI in Neos Studio. You would like to add a table to create, modify or delete associated products.

Creating a sub view

Before updating the template, it is necessary to add a sub view.

The purpose of this sub view is to create a link between a navigation property and a UI view that will display it. Here, you need to declare that the UI view ProductUI can display the navigation property Products of the Category.

Open the CategoryUI in Neos Studio, click on the Sub-views node and add the following sub view :

Products:

Relation property = ProductList
Sub UI view = ProductUI

Updating the templates

Now, you can use this sub-view to update the UI of CategoryUI. Go back to the template of this UI and add the <context relation-property-name="ProductList">...</context> part to have a template similar to this one:

<vertical-layout layout:height="fill">
    <heading level="1" layout:padding="small">
        @Title
    </heading>
    <card>
        <splitter layout:height="fill">
            <splitter-panel size="60">
                <vertical-layout layout:height="fill" layout:padding="small">
                    <toolbar refresh="true" />
                    <datagrid layout:height="fill" />
                    <pagination-bar />
                </vertical-layout>
            </splitter-panel>
            <splitter-panel>
                <vertical-layout layout:height="fill" layout:padding="small">
                    <form-field property-name="CategoryID" />
                    <form-field property-name="CategoryName" />
                    <form-field property-name="Description" />
                </vertical-layout>
            </splitter-panel>
        </splitter>
        <context relation-property-name="ProductList">
            <group-box expanded="true">
                <group-box-header>
                    <text weight="strong">
                        @Title
                    </text>
                </group-box-header>
                <group-box-content>
                    <toolbar close="false" save="false" refresh="false" add="false" />
                    <datagrid />
                    <pagination-bar />
                </group-box-content>
            </group-box>
        </context>
    </card>
</vertical-layout>

The <splitter>...</splitter> part of this layout contains the form for editing the properties of current category. The part <context relation-property-name="ProductList">...</context> that you added shows the products of current category.

Finally, you need to update the ProductUI to add to its template the input for the CategoryID :

<vertical-layout layout:height="fill">
    <heading level="1" layout:padding="small">
        @Title
    </heading>
    <card layout:height="fill">
        <toolbar refresh="true" />
        <splitter layout:height="fill">
            <splitter-panel size="60">
                <vertical-layout layout:height="fill" layout:padding="small">
                    <datagrid layout:height="fill" />
                    <pagination-bar />
                </vertical-layout>
            </splitter-panel>
            <splitter-panel>
                <vertical-layout layout:height="fill" layout:padding="small">
                    <form-field property-name="ProductID" />
                    <form-field property-name="ProductName" />
                    <form-field property-name="CategoryID" />
                    <horizontal-layout>
                        <form-field property-name="UnitPrice" layout:min-width="300" />
                        <form-field property-name="Discontinued" />
                    </horizontal-layout>
                </vertical-layout>
            </splitter-panel>
        </splitter>
    </card>
</vertical-layout>

Testing the application

Open the https://localhost/neos/Northwind URL in your browser to display the application.

Click on the My categories menu entry to show the category screen. You now have a new table located under the table listing all the categories. Add a new category and save.

Click on the My products menu entry select a category in the Category ID field on the products you previously created and save.

If you go back to the category screen and hit the Refresh button, you now see your products listed when you select the category they belong to.