Property Definitions
Contents
A PropertyDef is the definition of a property on a Biskit. In the example of a Session, described in Biskit Definitions, we saw that a Session has 6 properties. Therefore, the BiskitDef describing a Session contains 6 PropertyDefs.
A PropertyDef itself has properties. For example, it needs to record the name and type of the Biskit property it represents. There are quite a few different property types:
Type |
Description |
Type-Specific Content |
Biskit |
Properties of type Biskit contain a reference to another Biskit. |
|
Boolean |
Contains a true/false value |
|
Date |
Contains a date without a time element |
None |
DateRange |
Contains a range of date/time values |
None |
Datetime |
Contains a date and time |
None |
Double |
A floating point number |
|
Int |
The property contains a 32-bit signed integer. This may be interpreted via a drop-down selector if the PropertyDef indicates this is a Mapped Integer, and may allow you to set multiple values if it is a Bit Set. |
|
JavaEnum |
The property contains a value that is from an enumeration defined in the source code. This is represented by a drop-down list. |
See Java Enum Property Definitions. Must specify the Java Enum Definition. |
Long |
The property contains a 64-bit signed integer. Javascript does not directly support 64 bit values, and so long properties may cause performance problems because Calpendo has to emulate the behaviour of a 64 bit integer in the browser. |
None |
Set |
The property contains a set of items. The PropertyDef also needs to define the type of the data contained in the set. |
|
String |
A text property value. The value may be constrained, by specifying a Mapped String, in which case the value would be edited using a drop-down list. Otherwise, it will be a free text entry. |
|
StringEnum |
A property that contains a string constrained by a String Enumeration. Note that these properties are deprecated and may be removed in a future version of Calpendo. |
See String Enum Property Definitions. Must specify the String Enumeration |
UserDefined |
Used when the actual type isn't known in advance. Normally used only for indirect properties. |
None |
The different property types have different requirements about what information must be stored. For example, an integer property needs to specify whether it is to have values constrained by being a Mapped Integer or a Bit Set, and in both cases in needs to know which particular Mapped Integer should be used. But other property types do not need to know anything about Mapped Integers.
The requirements of the individual property types are shown in the following sections, the rest of this section will focus on the properties they have in common.
Name |
Description |
Primary Key |
This is the database ID for the PropertyDef. This cannot be changed, it is only for information purposes. |
Type |
The type of the property, integer, long, date etc |
Name |
The name of the property. This must be unique amongst all the property definitions on its Biskit, and contain only letters, numbers and the underscore. In particular, this cannot contain spaces. |
Description |
A description of the content of this property. This is only used for display in the Bakery so that anybody using the Bakery will be able to see this text. It's not used anywhere else. |
Label |
This is the text used to display the property name. This is used whenever a Biskit's detail is displayed, with each property's label show before its value. |
Tooltip |
This is a tool tip that should be displayed whenever the mouse hovers over this property when it is being displayed or edited in a Biskit. |
Sort Order |
Used to change the order in which properties are displayed. This cannot be modified directly. Instead, property sort order is modified by drag-and-drop in the Bakery. |
Live |
Used internally. |
Min |
The minimum value the property can take. This is only used for numeric and string values. For numeric properties, the minimum should be a number representing the minimum value the property should have. For string properties, the minimum should be the minimum length of the string. If a minimum is set the string is automatically required. |
Max |
Similar to Min, this specifies the maximum value the property can take and is only used for numeric and string values. |
Attributes |
These are defined in a separate table, below. |
Rows |
The number of rows used to display the value. Particularly useful for multi-line string values. |
Columns |
The number of columns used to display the value. Particularly useful for multi-line string values. |
Group |
This can be any text required. In some contexts, Biskits are displayed with their properties in separate groups. In that case, it's the PropertyDef's Group string that defines the group that each property belongs to, and the text that should be used to name that group. If this is used, when viewing a Biskit, separate tabs each with the appropriate group name will be used to display the properties. This property is used if no layout has been defined in the layout editor for this Biskit Type. The Project Biskit will always use this property for its layout.
|
Storage Mechanism |
Indicates whether the property is static, dynamic or indirect. See Property Storage Mechanisms for more information. |
Formulaic |
Dynamic only. Allows a formula to be entered to calculate the value of this property. See the section on Formulae for more details on the formatting. |
Column Name |
Only required for dynamic properties, this is the name of the database column used to hold the property. |
Unique |
Only required for dynamic properties, this indicates whether the value stored in this property should be unique. If it is, then when Calpendo is asked to generate SQL code to update the database schema, it will add the necessary commands to tell the database that the column contains unique values. This will make it illegal for the same non-null value to be present twice. |
Automated Property Type |
This specifies whether the property is automatically assigned a value, and when. The potential values are: None, Create, Update or Create & Update. If a property has a value other than None then the property will not be viewable when a Biskit is being edited. |
Default Value |
The value the user will see on creation. If this value is outside the Min and Max values above then the user will have to update before saving. |
The attributes on a PropertyDef are all boolean values as follows:
Name |
Description |
Visible |
Indicates whether the property should ever be displayed. If you make a property invisible, it will always be hidden. |
Editable |
Specifies whether this property can ever be modified. Some static properties are special and cannot be changed, but you may sometimes have dynamic properties that are calculated from some other source and inserted into the database. You can mark such properties as not being editable to protect them from accidental change. |
Persistent |
Indicates whether the property is stored in the database. Dynamic and indirect properties should always be persistent. |
Null Allowed |
Specifies whether null is an allowed value for the property. See below for a discussion about Null Allowed and Required. |
Required |
Specifies whether it is mandatory to provide a value for the property. See below for a discussion about Required and Null Allowed. |
Specifies whether this property should be visible when the full detail of a Biskit is displayed. |
|
Specifies whether this property should be visible when a list of Biskits is displayed. |
|
Specifies whether this property should be visible when displaying a collection of Biskits of this type. Normally, when editing a collection of Biskits, the number of properties displayed would be kept very small. |
Required Fields And Null Allowed
Required and Null Allowed sound like they are exact opposites, and therefore Calpendo shouldn't support both of them. However, there is a subtle difference that means that it is sometimes useful to define a property that is both required and allows null. The Null Allowed attribute is checked when building an editor for a property. So, when displaying a drop-down for a Mapped Integer, Mapped String, Java Enum or String Enum, a value representing null will be added if the Null Allowed attribute is set to true.
When a new Biskit is being created, the default value of a property displayed with a drop-down with Null Allowed set to true will be null, since that is the first value shown in the drop-down.
However, if a property is set to Required, then a value must be provided; it cannot be saved without a non-null value. For properties that have Required and Null Allowed both set to true, this means that the user is forced to choose one of the values from the drop-down as the default value of null cannot be left as the current value. A drop-down for a property that is Required but for which Null Allowed is false would be built without a value representing null, and so the user would not be forced to choose. Instead, the first value in the drop-down would be automatically selected unless a choice is made by the user.
For string properties, an empty string is a non-null value and so will satisfy Required. In order to make sure the user can not do this set a minimum length for strings where you want to make sure they enter something.
Large Numbers Of Properties And Tab Layout
If you are adding a large number of properties to a Biskit and wish them to be displayed in particular groups under specific tab names then use the Group meta-property. All properties with the same Group meta-property will be displayed under the same tab which will be labelled with the value of the Group meta-property unless a layout has been defined for this Biskit in the Layout Editor. (The Project Biskit will always use Group for its layout)
