Writing the GUI information file

Below is an example of the typical structure of .llblgengui file. At the moment we haven't an .xsd file to check whether your file is well formed, so the templates just query your xml file to find the relevant GUIi information. We will add xsd soon so you can edit your file more naturally.

<LLBLGenProjectGUIDefinition>
  <EntityModel>
    <EntityDefinitions>

        <EntityDefinition Name="TheEntityName" 
            DescriptiveField="TheDescriptiveField" 
            ShowValidationSummary="TrueOrFalse"
            AllowAddNew="TrueOrFalse" 
            AllowEdit="TrueOrFalse" 
            AllowDelete="TrueOrFalse" 
            AllowExportToExcel="TrueOrFalse">
             
             <Fields>
                 <Field Name="TheFieldName" 
                    LabelText="TheLabelText">
                     
                      <ValidationRules>              
                          <ValidationRule 
                             Type="RangeValidator" 
                             MinValue="0" 
                             MaxValue="16000" 
                             ErrorMessage="The error message."/>

                          <ValidationRule 
                             Type="CompareValidator" 
                             Operator="GreaterThan" 
                             Value="0" 
                              ErrorMessage="The error message."/>

                          <ValidationRule 
                             Type="RegularExpressionValidator" 
                             Expression="^regex expression$" 
                             ErrorMessage="The error message"/>                          
                      </ValidationRules>
                </Field>
                 ...
            </Fields>
            ...
        </EntityDefinition>
         ...
    </EntityDefinitions>
  </EntityModel>
</LLBLGenProjectGUIDefinition>

Although the elements are self-explained, we describe them below.

<LLBLGenProjectGUIDefinition>

This is the root node of the GUI information file. It's there just to know that the file is a valid.
<LLBLGenProjectGUIDefinition>
    ...
</LLBLGenProjectGUIDefinition>

<EntityModel>

This is the node that contains the information about your model.
<LLBLGenProjectGUIDefinition>
  <EntityModel>
    ...
  <EntityModel>
...

<EntityDefinitions>

This is where the definitions of the entities reside.
<LLBLGenProjectGUIDefinition>
  <EntityModel>
      <EntityDefinitions>
         ...
      </EntityDefinitions>
      ...

<EntityDefinition>

This keeps the GUI information for one entity. You should add one EntityDefinition for each entity you want to custom its GUI. Entities that aren't added are still generated with the default behavior.
<LLBLGenProjectGUIDefinition>
  <EntityModel>
      <EntityDefinitions>
          <EntityDefinition>
              ...
          </EntityDefinition>
          ...
These are the properties you can use in the EntityDefinition element:

Name

(Required) This is the name of the entity you are customizing. This must be the exact name of the entity you see in your LLBLGen project. If you rename the entity in the LLBLGen project, you should change it in your EntityDefinition as well.
Example
<EntityDefinition Name="Category" />

DescriptiveField

This is the name of the field used from entities that have a FK pointing to this entity. Therefore this field will be used in DropDownLists, Grids and FormViews in View mode. This should be the field that describes better your entity. This property is used in conjunction with UseLookupDropDownList in the related entity.
Example
<EntityDefinition Name="Category" DescriptiveField="CategoryName" />
Above property, in conjunction with UseLookupDropDownList in the related thread will generate a reference to this property in various views of the related entity. See above images to see how it will look like.

 
Descriptive Field in Grid Descriptive Field in Grid Descriptive Field in Grid

ShowValidationSummary

When set to true (default is false) it shows an ASP.Net ValidationSummary control in the Insert/Edit views for the validation rules indicated at Field level. Otherwise the errors are shown just below the fields.
Example
<EntityDefinition Name="Category" ShowValidationSummary="True" />

AllowAddNew

When set to false (default is true) no controls are generated to add entities (no Add button nor InsertView on FormViews).
Example
<EntityDefinition Name="Category" AllowAddNew="False" />

AllowEdit

When set to false (default is true) no controls are generated to edit entities (no Edit button nor EditView on FormViews).
Example
<EntityDefinition Name="Category" AllowEdit="False" />

AllowDelete

When set to false (default is true) no controls are generated to delete entities (no Delete button on grids).
Example
<EntityDefinition Name="Category" AllowDelete="False" />

AllowExportToExcel

When set to false (default is true) no controls are generated to export grid to excel (no ExportToExcel button list view).
Example
<EntityDefinition Name="Category" AllowExportToExcel="False" />

<Fields>

This is where the fields definitions reside.
<LLBLGenProjectGUIDefinition>
  <EntityModel>
      <EntityDefinitions>
          <EntityDefinition>
              <Fields>
                   ...
              <Fields>
               ...

<Field>

This is where you put the GUI information for a field. You should add a Field element for each field you want to customize. Fields not included are still generated with the default behavior.
<LLBLGenProjectGUIDefinition>
  <EntityModel>
      <EntityDefinitions>
          <EntityDefinition>
              <Fields>
                  <Field>
                      ...
                  </Field>
                   ...
These are the properties you can use in the Field element:

Name

(Required) This is the name of the field you are customizing. This must be the exact name of the entity's field you see in your LLBLGen project. If you rename the field in the LLBLGen project, you should change it in your Field element at your GUI information file as well.
Example
<Field Name="CompanyName" />

LabelText

This is the text used in the labels that are side by side with the field's controls.
Example
<Field Name="CompanyName" LabelText="Company Name"/>

UseLookupDropDownList

This property indicates whether the involved field should use a DropDownList control in the Insert/Edit views. To use this, the field must be a FK. The DataTextField property to use in the DDL is obtained from the DescriptiveField at the PK side entity. If no DescriptiveField is found in the PK side entity, the PK field is used as the DataTextField. Note: No composite-key FK are supported for this.
Example
<EntityDefinition Name="Product">
    <Fields>
        <Field Name="CategoryId" UseLookupDropDownList="True" />
    </Fields>
</EntityDefinition>
...
<EntityDefinition Name="Category" DescriptiveField="CategoryName" />
Above code will generate a DropDownList for Insert/Edit views in Product for the CategoryId field. See how it would look like:

Descriptive Field in Grid

CustomFormat

You can specify how the field is formatted in your GUI, putting a valid .net string formatter.
Example
<Field Name="RequiredDate" LabelText="Fecha de Entrega Requerida" CustomFormat="{0:MMMM dd, yyyy (dddd)}" />
<Field Name="Freight" LabelText="Flete" CustomFormat="{0:C}" />

<ValidationRules>

This is where the validation rules for a field reside.
<LLBLGenProjectGUIDefinition>
  <EntityModel>
      <EntityDefinitions>
          <EntityDefinition>
              <Fields>
                   <Field>
                       <ValidationRules>
                           ...
                       </ValidationRules>
                       ...

<ValidationRule>

This is where you put ASP.Net validation rules for the involved field. At the moment you can put three kind of validations: CompareValidator, RangeValidator and RegularExpressionValidator.
<LLBLGenProjectGUIDefinition>
  <EntityModel>
    <EntityDefinitions>
        <EntityDefinition>
             <Fields>
                 <Field>                     
                      <ValidationRules>              
                          <ValidationRule Type="RangeValidator" 
                             MinValue="0" 
                             MaxValue="16000" 
                             ErrorMessage="The error message."/>

                          <ValidationRule Type="CompareValidator" 
                             Operator="GreaterThan" 
                             Value="0" 
                              ErrorMessage="The error message."/>

                          <ValidationRule Type="RegularExpressionValidator" 
                             Expression="^regex expression$" 
                             ErrorMessage="The error message"/>                          
                     </ValidationRules>
                    ...
The properties you can use in the ValidationRule depends on the type of validator. These are the properties:

Type

This represents the type of validator you are using. It accepts three values:
  • RangeValidator
  • CompareValidator
  • RegularExpressionValidator

MinValue and MaxValue

Used in the RangeValidator to restrict the values you can enter into numeric fields.
Example
<Field Name="Freight" LabelText="Flete" CustomFormat="{0:C}">
  <ValidationRules>
    <!-- ASP.Net Validation: Freight must be a positive value-->
    <ValidationRule Type="RangeValidator" MinValue="0" MaxValue="16000" ErrorMessage="Freight shouldn't be negative."/>

    <!-- Above validation rule also could be written like this: -->
    <!--<ValidationRule Type="CompareValidator" Operator="GreaterThan" Value="0" ErrorMessage="Freight shouldn't be negative."/>-->
  </ValidationRules>
</Field>

Operator and Value

Used in the CompareValidator to restrict the value you can enter into some fields. The allowed Operators are:
  • Equal
  • GreaterThan
  • GreaterThanEqual
  • LessThan
  • LessThanEqual
  • NotEqual
Example
<Field Name="RequiredDate">
  <ValidationRules>
    <!-- RequiredDate should be greater than the OrderDate -->
    <ValidationRule Type="CompareValidator" Operator="GreaterThan" FieldToCompare="OrderDate" Value="Value" ErrorMessage="RequiredDate should be greater than the OrderDate."/>
  </ValidationRules>
</Field>

Expression

Used in the RegularExpresssionValidator. This should be a valid RegEx expression you commonly use in regex validation.
Example
<Field Name="ShipCountry">
  <ValidationRules>
    <!-- ShipCountry sholdn't contain numbers and can't be longer than 50 characters. -->
    <ValidationRule Type="RegularExpressionValidator" Expression="^[A-Za-z']{1,50}$" ErrorMessage="ShipCountry sholdn't contain numbers and can't be longer than 50 characters.."/>
  </ValidationRules>
</Field>

Last edited Jun 13, 2011 at 8:53 AM by daelmo, version 10

Comments

No comments yet.