Step 5 Datadescriptors

Order DataDescriptor

Create a file named  ordersDS.ds.xml. This file contains DataDescriptor settings, that is, this file is the DataDescriptor descriptor for the orders.

As the first step, create the descriptor structure, determine the database name and the domain class associated with the DataDescriptor:

With the access rights issue now solved, you can start to include columns in the DataDescriptor and set parameters for each column. Columns must come after the ‘access’ tag, but in this example you can only see the tags for each column. You can see the DataDescriptor at the end of this chapter.

Lastly, insert the ID column:

This is one of the simplest columns in this example. Specify the column name that must be the same as the field name in the domain class. As the DataDescriptor is based on the Orders domain class and there it is named ‘id’, use the same naming convention here in the ‘name’ attribute. Specify the column’s data type (the one that is included in the ‘datatype’ attribute). In this case it is ‘NUMBER’, as the table identifier contains numbers. The next attribute is the ‘primaryKey’. Setting this attribute to ‘true’ means that this column is the unique identifier in the DataDescriptor. If you don’t specify it or set it to ‘false’, the column does not fulfil the role of a unique identifier. Also, set the ‘visible’ attribute to ‘HIDDEN’ as you don’t want to make the column visible. As a result, the record’s unique identifier isn’t displayed in the list or the editor interface, therefore it remains invisible for the user. It isn’t included in the HTML DOM either, further increasing data security.

The next column is the order date column, also a simple column:

Here you’ll have to set the column name and data type, as well as specify the ‘nullable’ attribute that is either ‘true’ or ‘false’. By default, it is ‘false’, but since we want the column to be a required one (one that does not accept ‘null’), you set it to ‘true’. The JBStrap framework automatically determines the right editor component for the column, therefore you don’t have to specify it here, as the DatePicker component is fine for this purpose. If you don’t specify column visibility, the column is displayed in the list and the editor screen as the default one. Since this is what we want for this project, you don’t have to specify visibility here.

The next column is order number. This is not a simple column, so you’ll have to set multiple parameters:

Setting the column starts with specifying the usual attributes. Set the column name and data type. As this column is a text column, you can specify the maximum length by setting the ‘length’ attribute. The value specified here must be measured in characters, so in this example, the user is not allowed to enter more than 30 characters into the field. We implement further changes within the ‘column’ tag. First, we set the default filter operator. If you don’t do this, the text column’s default operator is CONSTRAINT, meaning that the column must contain a user-specified text. Since this column has numbers – despite the column type being a text column – it is advisable to change the filter operator. In this example we use the STARTS_WITH operator, displaying all records with the specified text.

In the next section you can set the component on the editor interface using parameters. By default, all editor components (text input fields) can be modified. In the example, the order number is an automatically generated number and we don’t want users to manually change it. Since it is an important piece of information, we don’t want to hide it either, so the best solution is to display it as a read-only field. Accordingly, we set the readOnly parameter to true, so that users are able to see the number, but cannot change it.

The next two columns are simple columns. Set the below attributes:

It is important to note the column names in the above two code lines. The column name is specified using a reference, e.g. customer.firstName. No field with this name is included in the Orders domain class, although the first column is expected to contain names that were included in the domain. The reason for this is the relationship we talked about when creating the domain class. The domain class includes a customer field. The customer field type is a Customer entity, known to contain customer details. In the Customer domain class there is a firstName field that contains the customer’s first name. The JBStrap framework can resolve this reference, so that the customer’s first name is displayed in the column despite it not having been included in the Orders domain class.

As these columns are only displayed on the list screen, the visibility of both columns are set to LIST. Consequently, it is displayed on the lists, but not on the editor screen.

The next column is associated with the customer and here we do a little trick to the code:

Passing parameters to the column is done the same way as above. Set the column name, data type, and make data entry required for the user. Set visibility to EDIT, meaning that the column does not show on the screen, only on editor interfaces. In case this remains the same, the user must specify a unique ID in a field that only accepts numbers. This solution is not a feasible one, so we just set the editor component. In this example we’ll show you a Combobox component where users can select a customer from the dropdown list. Set this using an editorType attribute.

The next task is to customize the component and provide it with data. This is what parameters between the params tags are for. Set the placeholder parameter and specify the placeholder text. The placeholder is displayed only when the editor component is empty (before the user selects an item from the list). Use the DataDescriptor parameter to specify a customer DataDescriptor in the component. This component is able to display and save different types of columns, you need to set what you’re using the specified DataDescriptor column for. First, you specify in the dataColumn parameter that you use id column in the customer DataDescriptor as data values. This value is then saved to the database, also, this value shows the customer name if you open an order. Also, instead of the customer name, we want to see the customer ID on the interface. Accordingly, we set the dataColumn parameter, specifying that we’re showing the firstName and lastName columns in the customer DataDescriptor. We’re almost done, but you need to define how the two displayed columns should be delimited. In this case, we’re creating a full name out of the first name and the last name, so the delimiter is a space character. Set it in the displayColumnSeparator parameter by typing a space only into the value.

Our next column is the status column:

Also, set the required attributes and indicate that the editor component is a combobox . Users cannot specify any text, but only something that the application can process. This is a text field, so you’ll need to change the filter. However, instead of a text filter, display a combobox component here. This is what you can do by setting the filters tag.

The combobox created here is different from the previous one in a way that the field’s value set does not come from a different DataDescriptor, but users can select from a predetermined value set. You can use the value tags between the values tags to determine this value set. The data attribute within the value tag is the combobox data value that you save to the database and the tag’s value is the display value. In this case, data values, along with other values in the database are all uppercase, while the value on the screen is not all uppercase. Values specified here are displayed by editor interfaces and list interfaces.

As the last step, create the final column that contains the total sum of the order:

Creating this column should be simple, as all the other parameters have already been used, except for the decimals parameter. Use the decimals parameter to specify for the NumberItem component the number of decimal digits on the interface. If you don’t provide a number, all available decimal digits are shown. In this case (as field includes the sum now) a 2-decimal digit number is fine.

Now we successfully set up the DataDescriptor that looks like the one below:

Customer DataDescriptor

Create a new file, customerDS.ds.xml, for the Customer DataDescriptor. In this DataDescriptor we will create only simple columns. Since this DataDescriptor is used only by Combobox components on the interface, you don’t need further settings.

The DataDescriptor should look like the following:

Supplier DataDescriptor

Create a new DataDescriptor called supplierDS.ds.xml. This is where supplier data is stored.

OrderItems DataDescriptor

Create a DataDescriptor called orderItemsDS.ds.xml that provides order item details. The DataDescriptor should look like the following:

Product DataDescriptor

There is also something new for us in this DataDescriptor, namely that we specify the width of the unitPrice, quantity and amount columns. This setting must be done by specifying the width parameter. As a result of the setting, the specified column will appear in the list with specified width. By default, all columns have an equal width on the interface, but since we have specified the width of each column here, they appear with the specified width. Additional columns in the DataDescriptor whose width is not specified will have an equal width in the rest of the table. In this example, there is only one column in the list that does not have a size specified, so it will fit to the entire available space.

Finally, let’s create a new DataDescriptor for our products. This DataDescriptor should be named productDS.ds.xml.

There are no new features in this DataDescriptor, with the exception of a new editor type. This new editor type is the CheckBox.