Form

The Form page contains the following elements:

 

Table 22. Form

Element	Description
Form Initialization Actions	Allows the List Form to be automatically pre-populated when the Form Type property is set to NewListItem, CreateDocument, or UploadDocument. The List Form will call the defined custom actions that are specified in this property. The fields that cannot be automatically pre-populated are: • Auto-fill field (fixed value, consume value from an HTTP parameter, calculated format, consume value from a session, consume row from a row provided by another web part, auto fill with a lookup or cross-site lookup field) • BDC Column • SI Column • Complex category field • Cross site lookup field See the Custom Action Help chapter on how to write a custom action to initialize the list form. You can click Edit and turn on Advanced Mode to edit Form Initialization Actions in XML: <FormInitialization>     <Action Name=”initial 1” Type="Custom" Class="MyCompany.DevStudio.SampleFormInitializationAction, MyCompany.DevStudio, Version=1.0.0.0, Culture=neutral, PublicKeyToken=451cac61f7ec4225" / >     <Action Name=”initial 2” Type="Custom" Class="MyCompany.DevStudio.SampleFormInitializationAction2, MyCompany.DevStudio, Version=1.0.0.0, Culture=neutral, PublicKeyToken=451cac61f7ec4225" / > </FormInitialization> Form initialization is a way to auto fill the form. It should not be used in conjunction with another auto fill method. If you do this, the result is unpredictable (that is sometimes the value from form initialization will take precedence, but sometimes the value from the other auto fill method will take precedence).
Form Component Behavior	For more information, see Form Component Behavior
Dependent Lists	For more information, see Dependent Lists
Template List Site URL	Allows you to specify the site URL of the document library that contains the document template that is used to create a new document when the Form Type is “Create Document”.
Template List Name	Allows you to specify the List Name of the document library that contains the document template that is used to create a new document when the Form Type is ‘CreateDocument’. When both the Template List Site URL and the Template List Name are specified, the qListForm will display a drop-down menu above the Field Name field that contains list of documents in that doc library. The user can then select a document that will serve as a template for the new document.

Form Component Behavior

This property is used to control the conditional behavior of the different components in the form, such as a field, a group of fields, or a tab. You can specify the following conditional behaviors: Show When, Hide When, Enabled When, Disabled When, Valid When, Invalid When, Required When, and Default When. See Table 24 for more information.

ValidWhen, InvalidWhen, and RequiredWhen are used with SharePoint List Item and Column validation. The validation is processed by:

1

The Form Component Behavior is processed first. If it succeeds (meaning no condition is true for InvalidWhen and no condition fails for ValidWhen and no condition is true for RequiredWhen), it goes on to perform SharePoint Column and List Item Validation. If they succeed, then Save and Close procedures follow.

2	The implementation of SharePoint List and Column validation applies to qListForm Save and Close action only. If user defines a custom action that has "performValidation" flag set to true, it will only enforce Form Component Behavior and will ignore List and Column Validation.

This property is an XML string in this format:

The Form Component Behavior element can contain one or more Component elements. Each Component element controls the behavior of a specific component in the form like a field or tab/panel.

The Component element contains the following elements:

Table 23. Form Components

Element	Description
Advanced Mode	Allows you to edit Form Component Behavior in XML. <FormComponentBehavior>     <Component Type="Field/Group/Container" ID="ComponentID">         <ShowWhen>             [Condition specified in CAML Filter format]         </ShowWhen>         <HideWhen>             [Condition specified in CAML Filter format]         </HideWhen>         <EnabledWhen>             [Condition specified in CAML Filter format]         </EnabledWhen>         <DisabledWhen>             [Condition specified in CAML Filter format]         </DisabledWhen>         <InvalidWhen Message=”Custom Message when condition is true”>             [Condition specified in CAML Filter format]         </InvalidWhen>         <ValidWhen Message=”Custom Message when condition is true”>             [Condition specified in CAML Filter format]         </ValidWhen>         <RequiredWhen Message=”Custom Message when condition is true”>             [Condition specified in CAML Filter format]         </RequiredWhen>     </Component>     <Component ...>     <Component ...> </FormComponentBehavior>
Type	Defines the type of the component that is assigned to the dynamic behavior. The choices are: Field, Group, or Container (that is, tab/panel). NOTE: A field cannot be hidden or disabled if that field is a mandatory field and the defined type of form component is either Field or Group. However, it can be hidden or disabled if the form component type is Container.
ID	Defines the ID or name of the component whose behavior is defined to be dynamic. When the Type is set to Field, this ID refers to the Name of a field that is defined in the Display Fields property. When the Type is set to Group, this ID refers to the Group Name attribute of a field that is defined in the Display Fields property. When the Type is set to Container, this ID refers to the ID of a container that is defined in the Form Layout property.

The Component element may contain any or none of the following conditional behavior elements:

Table 24. Conditional Behavior Components

Element	Description
Show When	Defines the conditions of when the form component should be shown.
Hide When	Defines the conditions of when the form component should be hidden. This conditional behavior takes precedence over the other conditional behavior. Therefore, if Hide When and Show When are defined and both evaluate to true, the component is hidden.
Enabled When	Defines the conditions of when the form component should be enabled.
Disabled When	Defines the conditions of when the form component should be disabled. This conditional behavior takes precedence over the Enabled When conditional behavior. Therefore, if Enabled When and Disabled When are defined and both evaluate to true, the component is disabled.
Required When	Defines the conditions of when the form component should be required. This conditional behavior is for fields only. It has no effect on a field that has been defined as required by SharePoint. A custom message can be specified. It is displayed when the Required When condition is satisfied. The message is displayed by default in red after the input control on the form. However you can specify any text or HTML code as the Message attribute.
Valid When	Defines the conditions of when the form component should be valid. This conditional behavior is for fields only. A custom message can be specified. It is displayed when the Valid When condition is satisfied. The message is displayed by default in red after the input control on the form. However you can specify any text or HTML code as the Message attribute.
Invalid When	Defines the conditions of when the form component should be invalid. This conditional behavior is for fields only. This conditional behavior takes precedence over the Valid When conditional behavior. Therefore, if Valid When and Invalid When are defined and both evaluate to true, the field is invalid. A custom message can be specified. It is displayed when the Invalid When condition is satisfied. The message is displayed by default in red after the input control on the form. However you can specify any text or HTML code as the Message attribute.
Default When	Defines the conditions of when the form component should be set as default.

These conditional behavior elements also work with any required field that is configured on the form.

For fields of type text, numeric or date/time, regular expression matching can be used for validation. Use the “Matching” operator in the conditional behavior element. You can also use the “Not Match” operator to apply the validation for input values that do not match the specified regular expression.

The following are some examples of how to use this property:

1	Show the Resolved Date and Resolved By fields when the Status field is changed to "Resolved". By specifying both fields’ GroupName attribute in the Display Fields property to “ResolvedFieldsGroup”, it is defined that both fields belong to the same group.

<FormComponentBehavior>
    <Component Type="Group" ID="ResolvedFieldsGroup">
        <ShowWhen>
            <Eq><FieldRef Name="Status"/><Value Type="Choice">Resolved</Value></Eq>
        </ShowWhen>
    </Component>
</FormComponentBehavior>

2	Enable the "Amount Paid" field when the Invoice Status field is changed to "Paid".

<FormComponentBehavior>
    <Component Type="Field" ID="Amount Paid">
        <EnabledWhen>
            <Eq><FieldRef Name="Invoice Status"/><Value Type="Choice">Paid</Value></Eq>
        </EnabledWhen>
    </Component>
</FormComponentBehavior>

3	Hide the Reason field when the Project Status field is not "Behind"

<FormComponentBehavior>

    <Component Type="Field" ID="Reason">
        <HideWhen>
            <Neq><FieldRef Name="Project Status"/><Value Type="Choice">Behind</Value></Neq>
        </HideWhen>
    </Component>
</FormComponentBehavior>

4	Show error message if field, Assigned To, is blank when Status is “In Process”

<FormComponentBehavior>
    <Component Type="Field" ID="Assigned To">
        <InvalidWhen Message="Assigned To Must be filled if Status is In Process">
            <And>
                <IsNull>
                    <FieldRef Name="AssignedTo" />
                </IsNull>
                <Eq>
                    <FieldRef Name="Status" />
                    <Value Type="Choice">In Progress</Value>
                </Eq>
            </And>
        </InvalidWhen>
    </Component>
</FormComponentBehavior>

5	Field % Complete must be between 0 and 100

<FormComponentBehavior>
    <Component Type="Field" ID="% Complete">
        <ValidWhen Message="% Complete must be between 0 and 100">
            <And>
                <Geq>                    
<FieldRef Name="PercentComplete" />
                    <Value Type="Number">0</Value>
                </Geq>
                <Leq>
                    <FieldRef Name="PercentComplete" />
                    <Value Type="Number">1</Value>
                </Leq>
            </And>
        </ValidWhen>
    </Component>
</FormComponentBehavior>

6	Set the container to default when the Project Status field is "In-progress"

<FormComponentBehavior>

    <Component Type="Container" ID="Initiation">
        <DefaultWhen>
            <Neq><FieldRef Name="Project Status"/><Value Type="Choice">In-progress</Value></Neq>
        </DefaultWhen>
    </Component>
</FormComponentBehavior>

Dependent Lists

This property identifies the child lists to be updated when the List Form saves the changes to the current list item.

This property works in conjunction with the Form Type property. When the Form Type property is set to EditListItem or EditDocument, the List Form will update the values in the child lists. When the Form Type property is set to NewListItem or UploadDocument, the List Form will create a new record in the child lists. This is useful when you have two lists with a one-to-one relationship.

This property also prevents the deletion of the current item if there are any child records in the specified lists. The user can delete a record when the Form Type property is set to DisplayListItem or EditListItem.

The Lists element can contain multiple List elements. One List element represents one child list. These are the attributes of the List element:

Table 25. Dependent Lists

Element	Description
Advanced Mode	Allows you to edit Dependent Lists in XML. The value of this property is an XML string in this format: <Lists>    <List SiteUrl="siteURL" ListName="listName" KeyFieldName="keyFieldName">       <Field SourceFieldName="sourceFieldName" TargetFieldName="targetFieldName"/>    </List> </Lists>
Site URL	Allows you to set the URL of the site that contains the child list.
List Name	Allows you to set the name of the child list. The name is case sensitive
Key Field Name	Allows you to set the name of the field in the child list that contains the ID of the parent item. The key field is usually a single line of text that contains the parent item ID or a cross-site lookup field to the parent list. The name is case sensitive.

The List element can contain zero or more Field elements. One Field element represents a field in the child list that needs to be updated. These are the attributes of the Tasks list:

•	Source — The name of the field in the parent list where the value comes from. The name is case sensitive.

•	Target — The name of the field in the child list where the value is copied to when the parent record is saved. The name is case sensitive.

The following diagram illustrates parent child relationship between two different lists

Figure 2. Parent/Child Relationship between two lists

The Project Phases list is the parent list of the Tasks list. The ID field is the primary key in the Project Phases list because the value of the ID field is guaranteed to be unique (every SharePoint list and library contains a field called ID. This field cannot be modified and its value is uniquely auto-generated by SharePoint). The Phase List Item ID is the foreign key in the Tasks list. We replicate the value of the Project List Item ID, Project Name and Phase Name into the fields with the same name in the Tasks list.

For example, if the List Form is configured to edit an item in the Project Phases list, then every time we modify the information in the Project Phase list we need to make sure the values that are replicated and the Tasks lists are modified. The following is how the Dependent List property should be setup:

<Lists>
   <List SiteUrl="." ListName="Tasks" KeyFieldName="Phase List Item ID">
      <Field SourceFieldName="Project List Item ID"TargetFieldName="Project List Item ID"/>
      <Field SourceFieldName="Project Name"TargetFieldName="Project Name"/>
      <Field SourceFieldName="Phase Name"TargetFieldName="Phase Name"/>
   </List>
</Lists>