Primary Content

The Primary Content page is default category. You need to configure one or more elements in this page to get started using this web part.

Primary Content contains the following:

 

Table 2. Primary Content

Element	Description
Title	Allows you to enter a title for the Web Part, or accept the default. This field is mandatory.
List Name	Allows you to select a SharePoint list or document library that is edited or displayed by this List Form. For more information, see List Name
Child List	Allows you to select one or more child list. For more information, see Child List
Form Type	Allows you to choose one of the following: • DisplayListItem — The form is used to display a list item (all fields are read-only). • NewListItem — The form is used to create a new item in the list. • EditListItem — The form is used to edit a list item. • DisplayDocument — The form is used to display a document metadata. • UploadDocument — The form is used to upload a document into a document library. • EditDocument — The form is used to modify a document metadata. • CreateDocument — The form is used to create a new document in the document library in a similar manner as the NewListItem except it will display the "File Name" field as the first field in the form. When you click the Save and Close button, a document is created and the metadata specified in the form is applied to the new document. After the document is created, the qListForm will append EditDoc=1 HTTP parameter to the URL where the user is redirected to. If the redirected page contains a qListForm, it will open up the newly created document. The target folder of the new document is specified by the RootFolder HTTP parameter in the URL. If the RootFolder is not specified, the document is created in the root folder of the document library. The qListForm determines which template is used to create the new document using one of the following methods: By using the document template specified in the content type. The content type is specified by the ContentTypeId HTTP parameter in the URL. If the ContentTypeId is not specified, the default content type is used by the list form. The user can select a document template from a document library. The 2 properties of the list form, Template List Site URL and Template List Name, specify the Site URL and List Name of the doc library that contains the document template. When both 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. When this property is set to DisplayListItem, EditListItem, DisplayDocument, or EditDocument, the URL of the current page must contain an ID HTTP parameter to indicate the identifier of the item to be displayed or edited. The ID HTTP parameters are usually included by the List Form when you click New Item in its toolbar or View Properties or Edit Properties in its context menu.
Form Layout	For more information, see Form Layout
Display Fields	For more information, see Display Fields NOTE: Use the Related Items check box if you want to display one or more child list along with parent list. This also enables you to add new items to the child list: once the form renders, the Related Items field automatically displays where you can add and save records directly to the child list. NOTE: The parent list should not have a field with the name Related Items in it as this field is automatically created.
Child List Display Fields	Defines the fields that should be displayed in the view for the child records. For more information, see Child List Display Fields
Relationship Mapping	For more information, see Relationship Mapping
ID HTTP Parameter Name	Allows the qListForm and several other web parts to an HTTP Parameter called ID to identify the item to be displayed or edited. This HTTP Parameter is usually generated automatically by the viewer web part, such as qListForm or qCalendarView, when you select an item to be displayed or edited. NOTE: If qListForm is placed on a web part page that is contained within a document library, the page will generate an error if the value of the ID HTTP Parameter is bigger than the number of pages within the document library. To prevent this error from happening, rename the ID HTTP Parameter. By default, the value of this property is "ID". You can change the value of this property to something else, such as LID. In that case, when you select "View Properties" or "Edit Properties" in the context menu, the URL of the display or edit form becomes: http://mysite.com/EditFormURL.aspx?LID=xxx Set the same property in the qListForm to the same value.

Form Layout

This property enables you to define the layout of the fields in the List Form. If this property is not defined, the List Form will display the fields in two column format: the first column is the field title and the second column is the control for the field.

This property is related to the Display Fields property. The Form Layout property defines the layout type and the containers. In order to place a certain field in a specific container, you will use the Tab/Panel/Container ID attribute of the Field element in the Display Fields property.

The Form Layout element can contain zero or more Container elements. You may not have to define any container for a certain type of layout manager. Some custom layout manager may have a fixed set of containers that do not need to be defined.

The Form Layout section contains the following:

 

Table 3. Form Layout

Form Layout type	Description
Advanced Mode	Turn on if you want to edit Form Layout in XML format: <FormLayout Type="TabLayout">     <Container Type="containerType" ID="containerID1" Label="tabText1"     ShowUserGroups="group1,group2" HideUserGroups="group3,group4">     <Container Type="containerType" ID="containerID2" Label="tabText2"     ShowUserGroups="group3,group4" HideUserGroups="group1,group2"> </FormLayout>
Tab Layout	Groups the fields in multiple tabs. You can add tabs to this layout by setting values for the following: • ID — the identifier for the tab. This ID must be unique for each container that is defined in the Form Layout. This identifier is referred to in the ContainerID attribute of the Field element in the Display Fields Property. • Label — the label for the container. Otherwise, if the container needs a label, it will use the ID. • Header — the content that would appear at the top of the form. • Footer — the content that would appear at the bottom of the form. • ShowUserGroups — the container is shown if the current user is a member of at least one of the specified SharePoint groups. You can define multiple SharePoint group names here by separating them with commas. • HideUserGroups — the container is hidden if the current user is a member of at least one of the specified SharePoint groups. You can define multiple SharePoint group names here by separating them with commas. The HideUserGroups attribute will take precedence if the current user is a member of one of the groups specified in the HideUserGroups and ShowUserGroups.
Panel Layout	Groups the fields in multiple panels. You can add panels to this layout by setting values for the following: • ID — the identifier for the panel. This ID must be unique for each container that is defined in the Form Layout. This identifier is referred to in the ContainerID attribute of the Field element in the Display Fields Property. • Label — the label for the container. Otherwise, if the container needs a label, it will use the ID. • Header — the content that would appear at the top of the form. • Footer — the content that would appear at the bottom of the form. • ShowUserGroups — the container is shown if the current user is a member of at least one of the specified SharePoint groups. You can define multiple SharePoint group names here by separating them with commas. • HideUserGroups — the container is hidden if the current user is a member of at least one of the specified SharePoint groups. You can define multiple SharePoint group names here by separating them with commas. The HideUserGroups attribute will take precedence if the current user is a member of one of the groups specified in the HideUserGroups and ShowUserGroups.
Custom Layout	Uses the custom layout manager class specified in the LayoutManagerClassName attribute to layout the fields. Using the custom layout, you can write your own custom Layout Manager where you can layout the fields in any way you want it or even create your own custom controls in the form. For more detail on how to write your own custom Layout Manager class, see System Integration. You can add containers to this layout by setting values for the following: • ID — the identifier for the tab. This ID must be unique for each container that is defined in the Form Layout. This identifier is referred to in the ContainerID attribute of the Field element in the Display Fields Property. • Type — they type of container. • Label — the label for the container. Otherwise, if the container needs a label, it will use the ID. • ShowUserGroups — the container is shown if the current user is a member of at least one of the specified SharePoint groups. You can define multiple SharePoint group names here by separating them with commas. • HideUserGroups — the container is hidden if the current user is a member of at least one of the specified SharePoint groups. You can define multiple SharePoint group names here by separating them with commas. The HideUserGroups attribute will take precedence if the current user is a member of one of the groups specified in the HideUserGroups and ShowUserGroups.
MultiColumn Layout	Displays the data in multiple columns. You can select the number of columns, and select if you want to render and control in a single row (displays the Label/Input control on the same row. If not selected, the Label/Input control is on separate row. Being on the separate row gives more screen real estate to render multiple columns. If this is selected, column span and row span attributes are applied to grouped field.)
Tab and MultiColumn Layout	Groups the fields in multiple tabs and in multiple columns in each tab. You can add tabs to this layout by setting values for the following: • ID — the identifier for the tab. This ID must be unique for each container that is defined in the Form Layout. This identifier is referred to in the ContainerID attribute of the Field element in the Display Fields Property. • Label — the label for the tab. Otherwise, if the container needs a label, it will use the ID. • Header — the content that would appear at the top of the form. • Footer — the content that would appear at the bottom of the form. • ShowUserGroups — the tab is shown if the current user is a member of at least one of the specified SharePoint groups. You can define multiple SharePoint group names here by separating them with commas. • HideUserGroups — the tab is hidden if the current user is a member of at least one of the specified SharePoint groups. You can define multiple SharePoint group names here by separating them with commas. The HideUserGroups attribute will take precedence if the current user is a member of one of the groups specified in the HideUserGroups and ShowUserGroups. • Render and Control in a single row — the tab displays the Label/Input control on the same row. If not selected, the Label/Input control is on separate row. Being on the separate row gives more screen real estate to render multiple columns. If this is selected, column span and row span attributes are applied to grouped field.
Panel and MultiColumn Layout	Groups the fields in multiple panels and in multiple columns in each panel. You can add panels to this layout by setting values for the following: • ID — the identifier for the panel. This ID must be unique for each container that is defined in the Form Layout. This identifier is referred to in the ContainerID attribute of the Field element in the Display Fields Property. • Label — the label for the panel. Otherwise, if the container needs a label, it will use the ID. • Header — the content that would appear at the top of the form. • Footer — the content that would appear at the bottom of the form. • ShowUserGroups — the panel is shown if the current user is a member of at least one of the specified SharePoint groups. You can define multiple SharePoint group names here by separating them with commas. • HideUserGroups — the panel is hidden if the current user is a member of at least one of the specified SharePoint groups. You can define multiple SharePoint group names here by separating them with commas. The HideUserGroups attribute will take precedence if the current user is a member of one of the groups specified in the HideUserGroups and ShowUserGroups. • Render and Control in a single row — the panel displays the Label/Input control on the same row. If not selected, the Label/Input control is on separate row. Being on the separate row gives more screen real estate to render multiple columns. If this is selected, column span and row span attributes are applied to grouped field.

Custom Layout

The Custom Layout capability enables you to write your own Layout Manager for the qListForm or qSIListForm.

This document explains the programming interface for writing the custom Layout Manager and how to deploy your custom Layout Manager into the server.

Layout Manager

A Layout Manager is a part of the list form that determines the layout of the controls on the form. The type of the layout for your form is specified in the Form Layout property. Out of the box, the list form provides two layout managers:

 

Table 4. Layout Manager

Layout manager	Description
Default Layout Manger	Is used if the Form Layout property of the list form is blank. The default layout manager lays out the controls vertically in two columns: the first column is the field title and the second column is the control for the field.
Tab Layout Manager	Enables you to group your fields into multiple tabs. You can use the Tab layout manager by specifying TabLayout in the Type attribute of the FormLayout element in the Form Layout property.

You can create your own Layout Manager:

•	When you want to layout the controls in a way that is not provided by the out of the box layout managers. For example, grouping the controls in different sections and having multiple sections in the same row.

•	When you want to create a custom control for one or more fields in the form. For example, in Figure 1, the table at the bottom of the form is a custom control created by the custom layout manager. This table contains the list of opening hours for a restaurant for every day during the week.

Figure 1. Creating a custom control

You can create your own custom Layout Manager class or use the sample custom Layout Manager class that is shipped with QuickApps for SharePoint.

To open the sample code

1	Select Start | All Programs | AgreeYa | QuickApps for SharePoint | Sample Code.

The Sample Code folder opens in Windows Explorer.

2	Double-click SampleCode.sln.

This opens the solution in Microsoft Visual Studio. The sample custom Layout Manager class can be found in SampleLayoutManager.cs file in the SampleCustomActionsAndCustomLayouts project.

Custom Layout Manager Class

If you want to write your own custom Layout Manager class, ensure the following:

•	A Class Library project is created using Microsoft Visual Studio

•	Microsoft SharePoint Server is installed and running properly

•	QuickApps for SharePoint is installed and running properly in your SharePoint environment

•	You have a strong name key file to sign your assembly

Programming Interface

Your custom Layout Manager classes must be derived from WA.Core.LayoutManager.FormLayoutManager class. This class is located in WA.Core.DLL that is installed in the Global Assembly Cache (GAC) when you install the QuickApps for SharePoint.

Properties

The following are the properties of the WA.Core.LayoutManager.FormLayoutManager class:

 

Table 5. WA.Core.LayoutManager.FormLayoutManger class properties

Property	Description
FormType	indicates the type of list form that contains the layout manager class. The type of this property is FormTypeEnum enumeration and the options are New, Edit or Display. This property is useful when you create custom controls in your layout manager. For example, when the FormType is Display, you may want to make your custom control read only.
WebPart	references the parent web part, which is either a qListForm or a qSIListForm.
FormItem	references the item that is being created, edited, or displayed in the form. The type of this property is System.Object. The real type of the FormItem depends on whether the Layout Manager is used in the qListForm or qSIListForm. The qListForm will assign a Microsoft.SharePoint.SPListItem object to the FormItem property. The qSIListForm will assign a System.Collections.Hashtable object to the FormItem property. The Hashtable contains a key value pair of field name and field value. You can use the FormItem to get the values of the fields to populate your custom controls and to save the value from your custom controls back to the form.
FormLayout	indicates an XML string that is entered in the Form Layout property of the qListForm or qSIListForm. You can use this information to find out about the containers that are specified for your layout manager.
ClientSide ValidationErrorHandler	indicates a read only property to get the name of the Javascript function that is called in the validation error in the client side, such as a required field that is empty, number field outside a specific range. You do this only if you need special handling such as showing the control with the validation error. For example, the Tab layout manager groups fields in different tabs. The field with the validation error maybe located in the tab that is not currently shown. In that case, the Tab layout manager needs to show the tab that contains the field with the validation error. NOTE: Your layout manager class can override this property.

Methods

The following are the methods of the WA.Core.LayoutManager.FormLayoutManager class.

 

Table 6. WA.Core.LayoutManager.FormLayoutManager class methods

Method	Description
public abstract void AddControlToContainer(System. Web.UI.Control control, string containerID, string fieldDisplayName, string fieldInternalName, Guid fieldID, string fieldDescription, bool isFieldRequired, bool isControlHidden)	Is called by the list form during initialization phase (in the OnInit method). The list form will create controls for the fields specified in the Display Fields property and then call this method to add the control to the layout manager. Your layout manager class must override this method. The following are the parameters for this method: • control – the control to be added • containerID – the ID of the container where this control should be added. The containerID for the field is specified in the Display Fields property of the list form. If not specified, the containerID is NULL. • fieldDisplayName – the display name of the field that owns this control. For qListForm, this means the display name for the SharePoint field, which is usually different than the internal name of the field. • fieldInternalName – the internal name of the field that owns this control. For qListForm, this means the internal name for the SharePoint field, which is usually different than the display name of the field. For example, the internal name of the “Assigned To” field may be “Assigned _x0020_To”. For qSIListForm, the fieldDisplayName and the fieldInternalName are the same. • fieldID – the unique identifier for the field. This is a good candidate to use as a unique key to keep track of your fields. For example, when the list form needs to hide the controls for certain fields by using the HideControl method, it will use the fieldID as parameter. • fieldDescription – the description for the field. This is the field description that is specified by the user in the Display Fields property of the list form. It’s up to you on how you want to display it in your layout manager. One option is to display the description underneath the control. If not specified, the fieldDescription is NULL. • isFieldRequired – a boolean flag to indicate whether or not this is required field. You may want to put some visual indicator for required fields such as a ‘*’ in the field title. • isControlHidden – a boolean field to indicate whether or not the control for the field should be hidden. The user can mark a certain field as a hidden field in the Display Fields property. If a field is hidden, you still have to add the control into the control hierarchy but you need to hide it in a certain way. For example, you can set the style’s Display attribute to None.
public abstract void AddMessageToContainer(string message, string containerID)	Is called if the list form needs to display a certain message on the form. For example, if the Email Notification Section in the qListForm is enabled, the qListForm will call this method to generate this message: "If you want to send an email notification, please complete the following information.” The email is sent if you enter one or more email addresses in the To field. You need to display the message in the layout manager when this method is called.
public abstract void HideControl(Guid fieldID)	Is called if the list form needs to hide a certain control. For example, when the qListForm is editing a Calendar item, the Start Time and End Time fields needs to be hidden when the user checks the All Day Event and Recurrence fields. You must implement this method for your layout manager to support the Form Component Behavior property of the list form.
public abstract void ShowControl(Guid fieldID)	Is called if the list form needs to show a certain control. For example, when the qListForm is editing a Calendar item, the Start Time and End Time fields needs to be shown when the user unchecks either the All Day Event or Recurrence fields. You must implement this method for your layout manager to support the Form Component Behavior property of the list form.
public virtual void EnableControl(Guid fieldID)	Is called if the list form needs to enable a certain control. You must implement this method for your layout manager to support the Form Component Behavior property of the list form.
public virtual void DisableControl(Guid fieldID)	Is called if the list form needs to disable a certain control. You must implement this method for your layout manager to support the Form Component Behavior property of the list form.
public virtual void ShowContainer(Guid fieldID)	Is called if the list form needs to show a certain container in your layout manager. You must implement this method for your layout manager to fully support the Form Component Behavior property of the list form.
public virtual void HideContainer(Guid fieldID)	You layout manager class may override this method. The list form will call this method if it needs to hide a certain container in your layout manager. You must implement this method for your layout manager to fully support the Form Component Behavior property of the list form.
public virtual void EnableContainer(Guid fieldID)	Is called if the list form needs to enable a certain container in your layout manager. You must implement this method for your layout manager to fully support the Form Component Behavior property of the list form.
public virtual void DisableContainer(Guid fieldID)	Is called if the list form needs to disable a certain container in your layout manager. You must implement this method for your layout manager to fully support the Form Component Behavior property of the list form.
public virtual void PopulateFormControls()	Overridden if this method creates custom controls for certain fields. You must create the custom controls already in the OnInit method. The list form will call this method during pre-render phase and you can use the FormItem property to get the values for the fields and populate your custom controls. You do not have to populate the controls that are created by the list form and added by the AddControlToContainer method. Those controls is populated by the list form.
public virtual void SaveValuesToFormItem()	Overridden if this method creates custom controls for certain fields. The list form will call this method after the user clicks the save button in the form. You must write back the value from your custom controls to the FormItem so that the list form can save the value back to SharePoint or your external system.

Debugging

In order to debug the code, generate the debug version of the DLL and copy the DLL and PDB file into the bin folder under the root folder of your SharePoint application. If you cannot find the bin folder, you can create one. Sign your assembly with a strong name key file.

 

NOTE: You can set the output folder of your project to the bin folder of your SharePoint application. Therefore, the DLL and PDB files are automatically updated every time you compile your application.

Physical Path

To find the physical path of the root folder of your SharePoint application

1	Select Start | Control Panel | Administrative Tools | Internet Information Services (IIS) Manager.

2	Expand the node with your computer name.

3	Expand the Web Sites folder.

4	Find the node that represents your site. The SharePoint site should contain _layouts, _vti_bin and _wpresources underneath it.

5	Right-click the node and select Properties.

6	Select Home Directory tab.

The value in the Local path tells you the physical path of your root folder.

Trust Level

Once you generate the debug version, you should change the trust level for your web application to Full while debugging the custom Layout Manager class. The trust level is specified in the web.config. Find the trust element in your web.config and change the level to Full.

<trust level="Full" originUrl="" />

Using the Custom Layout Manager Class

In order to use your custom Layout Manager class, you should refer to it in the Form Layout property of the qListForm or qSIListForm as follows:

<FormLayout Type="CustomLayout" LayoutManagerClassName="Fully qualified class name of the custom Layout Manager" />

 

NOTE: When you specify the class name in the LayoutManagerClassName attribute in the FormLayout element, you must use a fully qualified class name.

For example, in order to use the SampleLayoutManager class that comes in the sample code, specify the following in the Form Layout property:

<FormLayout Type="CustomLayout" LayoutManagerClassName="MyCompany.DevStudio.SampleLayoutManager, MyCompany.DevStudio, Version=1.0.0.0, Culture=neutral, PublicKeyToken=451cac61f7ec4225" />

Constructing the XML

To use the Form Layout property editor to construct the XML

1	Make sure that you have compiled your custom layout manager project and put the resulting DLL into the bin folder of your SharePoint web application.

2	Create a qSIListForm.

3	Select Web Part Menu | Configure from the SI List Form.

4	Click Edit on the Form Layout property.

5	Select CustomLayout in the Form Layout Type drop-down menu.

6	Select the class name in the drop-down menu under the Layout Manager Class Name.

7

Click OK.

Debugging the Code

To debug the code in your custom Layout Manager class

1	Open the SharePoint page that contains the qListForm or qSIListForm that contains the custom Layout Manager.

2	Open your project's solution using Visual Studio.

3	Select Debug | Attach to Process.

4	Select w3wp.exe in the process list.

If w3wp.exe is not listed, make sure that you check Show processes in all sessions. You may see more than one w3wp.exe listed. If you do, select the one with your user name or try it one by one until you find the process that contains the executable for your code.

5	Click Attach.

6	Set some breakpoints in your custom action code.

7	Invoke your custom action by clicking the custom toolbar button or the custom context menu that you configure in qListView or qListForm.

Deploying the Custom Layout Manager Class

When it is ready to deploy the solution, build your custom action project in release mode. Sign the assembly with a strong name key file. This ensures the assembly created can be deployed into Global Assembly Cache (GAC).You can deploy your assembly into the GAC by using the gacutil.exe that comes with the .NET Framework SDK. Here is the command: gacutil /i <DLLName>.

Once the assembly is dropped into the GAC, your class is ready to use.

Display Fields

This property defines what fields should be displayed in the List Form and how the fields are populated.

NOTE: In addition to the fields in the list, the listform recognizes the following special field.

•

CAPTCHA — This field contains the security image used for authenticating data that is input in the form and works for the following form types: NewListItem, EditListItem, UploadDocument, CreateDocument and EditDocument. If the list contains an existing field that has the name CAPTCHA then this field will take precedence.

•	Add Separator — Allows you to add static text that can be used as a description or label for a corresponding field or a group of fields in the field display sequence. You can add as many separators as required.

When you select the Edit button, a dialog box opens with a list of field names based on the list you have selected. You can enter a title and description for each field name.

You can add more details to the field names.

Table 7. Display Fields

Element	Description
Advanced Mode	Turn on if you want to edit Display fields in XML format. For example: <DisplayFields>     <Fields ContentType="Task">         <Field Name="Title" ConsumeHTTPParameterName="InitTitle" />     </Fields> </DisplayFields>
Field Name	Displays the field name.
Field Type	Indicates the type of the field selected. This is a read-only field and displays for all available list templates.
Title	Allows you to change the displayed title for the field. The value can be a plain string or an encoded HTML string. Change the displayed title, for example, when the title is too long or to make the title more descriptive.
Title Resource ID	If supporting a multi-lingual site, you may want to display a different Title for the field depending on the current culture. This property defines the identifier in the Resource List that is used as the title of the field. The TitleResourceID and the current cultural setting (identified with the Culture HTTP parameter) are used to retrieve the string in the Resource List. If the string with the given identifier is not found, the default Title is used.
Tooltip	Allows you to set the text that is displayed in the tooltip when you hover your mouse over the control for the field in the list form. If you do not specify this attribute, the display name of the field is used as the tooltip text.
Tooltip Resource ID	If supporting a multi-lingual site, you may want to display a different tooltip for the field depending on the current culture. This property defines the identifier in the Resource List that is used as the title of the field. The Tooltip Resource ID and the current cultural setting (identified with the Culture HTTP parameter) are used to retrieve the string in the Resource List. If the string with the given identifier is not found, the default tooltip is used.
Description	Allows you to set the field description. It can be a plain string or an encoded HTML string. The Description is added below the field value.
Description Resource ID	If supporting a multi-lingual site, you may want to display a different description for the field depending on the current culture. This property defines the identifier in the Resource List that is used as the title of the field. The Description Resource ID and the current cultural setting (identified with the Culture HTTP parameter) are used to retrieve the string in the Resource List. If the string with the given identifier is not found, the default description is used.
Width (in pixels)	Allows you to set the width of the control in pixels. Some controls, such as the Rich Text Editor, have minimum width and it will not honor the specified width if it is smaller than its minimum width.
Column Span	Allows you to set the span of the column.
Row Span	Allows you to set the span of the row.
Hidden	Allows you to hide the field.If the field is hidden, the List Form will not modify that field at all. If you hide the field using the Hidden attribute, the field is processed according to the way it is defined, but it will not be shown in the List Form.
Group Name	Allows you to create dynamic behavior for a group of fields. The list form can be defined to have dynamic behavior where certain fields or group of fields can be hidden, shown, disabled, or enabled based on certain conditions. The value in the Group Name field is referred to in the Form Component Behavior property.
Column Count	Allows you to define the number of columns that the choices for the multi-choice field should be broken into. This is useful if you have many choices in your multi-choice field to minimize the vertical scrolling when entering the data into the list form. This attribute is ignored if the field is not a multi-choice field.
Hide Select and Unselect All	Allows you to hide the Select All and Unselect All links in the multi-choice field control. If not specified, the Select All and Unselect All links are shown by default. This attribute is ignored if the field is not a multi-choice field.
Auto Post Back	If selected, allows the control to refresh the form when its value changes. This attribute is applicable for the following field types: Lookup field, Cross-site lookup field, Yes/No and Choice. This attribute is ignored for other field types. This attribute should be set to true in the following scenarios: • When a lookup field or cross site lookup field is defined as the Parent Field of another field. • When a lookup field, cross site lookup field, Yes/No, or choice field is being used in the conditions of the Form Component Behavior property.
Use People Editor	If selected, allows the qListForm to display the People Editor control for the People and Group field. With the People Editor control, you can lookup any user in your directory service. By default, the value is false. If set to false, the qListForm will display the users from the site user list. This attribute only effects the People and Group field. It is ignored for any other fields. There is a known issue in the SharePoint People Editor control where it cannot persist its value during AJAX operation. Therefore, you need to set Enable AJAX property to false when you use the People Editor control and have an auto-postback lookup field in the form.
Use Current User as Default Value	If selected, allows the name of the current user to become the default value of the People and Group field when the Form Type is set to New List Item or Upload Document. This attribute is ignored if the Form Type property is set to another value or when the field is not a People and Group field. By default, the value is false.
Do not Render as Hyperlink	This attribute affects the display of the Person or Group field, the lookup field or the cross-site lookup field when the Form Type is set to Display List Item or Display Document. If set to true, the value of those kinds of field is rendered as plain text instead of hyperlink.
Disable Resize	This attribute determines whether or not the Rich Text Editor for the Rich Text Field can be resized. To resize a Rich Text Editor, you can drag the resize handle in the lower right hand corner of the editor. The resize handle is hidden when this attribute is set to true.
Expand Options on Load	Allows you to expand the list of users or options when selected.
Show User Groups	Allows you to list SharePoint groups whose members can view the web part. Separate groups with commas.
Hide User Groups	Allows you to list SharePoint groups whose members cannot view the web part. Separate site group names with commas (for example, Administrators, Readers). If users are defined in Show User Groups and Hide User Groups, Hide Groups takes precedence.
Mask	Allows you to define the format of the input for a single line of text field. This property is ignored for another field type. The mask can contain characters and input-mask-flags such as: # — digit or space, optional. If this position is blank in the mask, it is rendered as a prompt character. L — uppercase letter, optional. Restricts input to the ASCII letters A-Z. l (lower case L) — lowercase letter, optional. Restricts input to the ASCII letters a-z. a — accepts any character <n..m> — restricts the user input to the declared numeric range, for example: <0..255>. The numeric range mask part must occupy multiple characters of the mask. <option1|option2|option3> — restricts user input to one of the set options, for example: <Sun|Mon|Tue|Wed|Thu|Fri|Sat>. \ — escapes a mask character, turning it into a literal. "\\" is the escape sequence for a backslash. All other characters — all non mask elements will appear as themselves. Literals always occupy a static position in the mask at run time, and cannot be moved or deleted by the user.
Prompt Character	Allows you to define the character that is displayed and saved in place of the empty characters when you specify a Mask. If not specified, "_" (underscore) is used as the default prompt character. Specify only a single character in this attribute.
Parent Field	Allows you to define another lookup or cross-site lookup field that is used to filter this field. The parent field must be listed before this field in the XML property.
Parent Filter Field Name	Allows you to define the field in the parent field that is used to filter this field. In other words, it is the primary key in the list that is used in the lookup or cross-site lookup field.
Filter Field Name	Allows you to define the field in the list that is used by this lookup or cross-site lookup field that is filtered by the parent filter field.
Field Type	Allows you to select a field type. More options are available depending on the field type selected. The default is regular field. See the following fields for more information: • Fixed Value • Consume Value from an HTTP Parameter • Calculated Format • Autofill with a lookup/cross-site lookup field • Consume value from a row provided by another web part • Consume value from a session • Lookup Field • Cross-site Lookup • System Integration • Complex Category

Fixed Value

You can assign a fixed value to a field using the FixedValue attribute.

For example, to assign Accounting to the Department field:

<Field Name="Department" FixedValue="Accounting"/>

Additionally, you can use special variables for the FixedValue attribute.

•

<CurrentUserID/> — this value is replaced by the ID of the currently logged in user. If you want to assign the current user to the People and Group field, use this variable. If you are using Advanced Mode and you would like to assign a task to the currently logged in user, you can specify the following Field element: <Field Name="Assigned To" FixedValue="&lt;CurrentUserID/&gt;" /> (If you are using Advanced Mode)

•	<CurrentUserName/> — this value is replaced by the name of the currently logged in user.

•	<CurrentUserEmail/> — this value is replaced by the email of the currently logged in user.

•	<CurrentLoginName/> — this value is replaced by the login name of the currently logged in user. The login name is usually in the form of domain\username.

•	<Today/> — this value is replaced by today's date.

•	<Now/> — this value is replaced by the current date and time.

NOTE: If you are using SharePoint Form-Based Authentication, the above variables will return the following, for example: • CurrentUserName=testuser • CurrentLoginName=i:0#.f|<site>|testuser • CurrentUserID=6 • CurrentUserEmail=testuser@company.com

You can edit the following:

Table 8. Fixed Value

Element	Description
Allow Edit	Allows you to edit the fixed value field.The value that is retrieved from the Fixed Value attribute will only be used to initialize the field. Afterwards, the user can modify the value as they wish and save it.

Consume Value from an HTTP Parameter

The HTTP Parameter Consumer field gets its value from an HTTP parameter. This is the attribute to create an HTTP Parameter Consumer field:

 

Table 9. Consume Value from an HTTP Parameter

Element	Description
Consume HTTP Parameter Name	Allows you to enter the name of the HTTP parameter whose value is to be consumed. This field is mandatory.
Allow Edit	Allows you to edit the fixed value field.The value that is retrieved from the Fixed Value attribute will only be used to initialize the field. Afterwards, the user can modify the value as they wish and save it.

Calculated Format

You can format a value of a field using values from other fields by using the CalculatedFormat attribute. The value of the another field can be referred to using the <%fieldName%> field replacement expression. If you are using Advanced Mode, you must use the encoded form of the < and > characters, which are &lt; and &gt;, respectively unless you type in the value in the Display Fields editor in the List Form Editor, where the Editor will encode the characters automatically for you.

For example, if you want to format the Full Name field as Last Name, First Name, the Field element should be specified as:

<Field Name="Full Name" CalculatedFormat="&lt;%Last Name%&gt;, &lt;%First Name%&gt;" />

Another example is to assign a ten-digit number to the AccountNumber field using the ID of the list item. If the ID is less than 10 digits, it is padded with zeros.

<Field Name="AccountNumber" CalculatedFormat="&lt;%{0:0000000000}
ID%&gt;"/>

This attribute can also be used to make a field read-only. For example, to make the AccountNumber a read-only field:

<Field Name="AccountNumber" CalculatedFormat="&lt;%AccountNumber%&gt;" />

Autofill with a lookup/cross-site lookup field

The Auto Fill field gets its value from the parent field. The parent field must be a lookup field or a cross-site lookup field.

The following are the attributes to create an auto-fill field:

Table 10. Autofill with a lookup/cross-site lookup field

Element	Description
Parent Field	Allows you to defines the name of the parent field. The parent field must be specified before any of the child fields.
Auto Fill Display Field Name	Allows you to define the field in the parent field where the value comes from
Auto Fill Display Format	Allows you to define the string format for the values. This attribute takes precedence over the Auto Fill Display Field Name attribute. The format of the Auto Fill Display Format is the same as the format used in the Calculated Format attribute.
Allow Edit	Allows you to define if this field is editable. By default, the list form displays this field type as a non-editable field. If this attribute is set to true, this field is editable.

For example, a List Form is used to edit the Employee list. Manager is a field in the Employee list, and it is a lookup field. Two other fields, ManagerFirstName and ManagerLastName, are filled based on the row selected in the Manager field. The Fields element for the Manager, ManagerFirstName,and ManagerLastName will look like the following:

<DisplayFields>
   <Fields ContentType="Employee">
      <Field Name="Manager" AutoPostBack="true"/>
      <Field Name="ManagerFirstName" ParentField="Manager" AutoFillDisplayFieldName="FirstName"/>
      <Field Name="ManagerLastName" ParentField="Manager" AutoFillDisplayFieldName="LastName"/>
   </Fields>
</DisplayFields>

Set the AutoPostBack attribute to true in the parent field. Otherwise, the ManagerFirstName and the ManagerLastName fields will not be refreshed when the user selects another manager.

 

NOTE: The maximum limit of characters that an auto-fill field supports is 255. If this limit exceeds, then use Multiple lines of text instead of Single line of text in an Autofill field.

Consume value from a row provided by another web part

The row consumer field gets its value from the row that is consumed by this List Form. To create a row consumer field, you must connect the List Form with another web part that implements the IRowProvider interface (such as the qSelector or qMultiSelectors).

These are the attributes to create a row consumer field:

Table 11. Consume value from a row provided by another web part

Element	Description
Consume Row Display Field Name	Allows you to defines the field name in the row from where the value comes.
Consume Row Display Format	Allows you to define the string format for the values. This attribute takes precedence over the Consume Row Display Field Name attribute. The format of the Consume Row Display Format is the same as the format used in the Calculated Format attribute.
Allow Edit	Allows you to define if this field is editable. By default, the list form displays this field type as a non-editable field. If this attribute is set to true, this field is editable.

For example, a List Form is used to edit a Tasks list. The Tasks list contains a Project Name field, and this field is configured as a row consumer field. The row is provided by a qSelector web part that displays the list of projects from the Projects list and is connected to the List Form.

<DisplayFields>
   <Fields ContentType="Task">
      <Field Name="ProjectName" ConsumeRowDisplayFieldName="Name"/>
   </Fields>
</DisplayFields>

Consume value from a session

Session consumer field gets its value from a row that is stored in the session object. The concept is similar to Row Consumer Field Attributes. However, if you need to get values from multiple providers, you must use the Session Consumer Field instead of Row Consumer Field because the List Form can only be connected to one row provider.

To create a session consumer field, you must first declare a Sessions element. A Sessions element can contain one or more Session elements. The Sessions element contains the information about the list where the row stored in the session comes from. After the Sessions element is defined, you can use it in the Field element. The XML for the session consumer field looks like the following:

<DisplayFields>
   <Sessions>
       <Session Name="sessionName" SiteUrl="siteUrl" ListName="listName"/>
   </Sessions>
   <Fields ContentType="contentType1">
      <Field Name="field Name" ConsumeSessionName="sessionName" ConsumeSessionDisplayFieldName="displayFieldName"/>
   </Fields>
</DisplayFields>

These are the attributes to create a row consumer field:

Table 12. Consume value from a session

Element	Description
Name	Allows you to enter the name of the session you want to consume. This field is mandatory.
Site URL	Allows you to enter the URL of the list site.
List Name	Allows you to enter the list name.
Consume Session Display Field Name	Allows you to defines the field name in the session from where the value comes.
Consume Session Display Format	Allows you to define the string format for the values. This attribute takes precedence over the Consume Session Display Field Name attribute. The format of the Consume Session Display Format is the same as the format used in the Calculated Format attribute. If you select New List Item type as Form type, leave this field blank unless it is in simple text format.
Allow Edit	Allows you to define if this field is editable. By default, the list form displays this field type as a non-editable field. If this attribute is set to true, this field is editable.

You can replace the Consume Session Display Field Name attribute with Consume Session Display Format if you want to use multiple fields as the source of values for this field.

For example, a List Form is used to edit a Tasks list. The Tasks list contains a Project Name field, and this field is configured as a session consumer field. The row is provided by a qSelector web part in another page that is visited before this page is opened.

<DisplayFields>
   <Sessions>
      <Session Name="ProjectsSession" SiteUrl="../../.." ListName="Projects" />
   </Sessions>
   <Fields ContentType="Task">
      <Field Name="ProjectName" ConsumeSessionName="ProjectsSession" ConsumeSessionDisplayFieldName="Name"/>
   </Fields>
</DisplayFields>

Lookup Field

You can sort and filter the entries for the Lookup fields by using the Sort Field and CAML Filter attributes, respectively. These attributes are ignored if the field is not a lookup field.

For example, if you are using Advanced Mode and you want to sort the Related Task lookup field by its title and only want to show high priority tasks, you can specify the following configuration:

<Field Name="Related Task" SortField="Title" CamlFilter="&lt;Eq&gt;&#xD;&#xA; &lt;FieldRef Name=&quot;Priority&quot; /&gt;&#xD;&#xA; &lt;Value Type=&quot;Choice&quot;&gt;(1) High&lt;/Value&gt;&#xD;&#xA;&lt;/Eq&gt;" />

Cross-site Lookup

Cross-site lookup is the capability of the List Form to refer to multiple lists in different sites.

To use this feature, create a single-line-of-text field, not a lookup field. Internally, the List Form will store the field value in this format: siteUrl;#listName;#listItemId.

For example, add a Document Type field to the metadata of every document that you store in the document library. One way of doing this is to make this field a choice field. However, if you need to change the options for the Document Type, you have to go to every document library in every site to change it. The same problem occurs if you make the Document Type field a SharePoint lookup field (because SharePoint can look up a list in the same site). The solution is to make the Document Type field a cross-site lookup field. You can create a Document Type list in a centralized place and create a DocumentType field (as single line of text field) in every document library. Configure this field as:

<Field Name="DocumentType" DisplayFieldName="Type" SortField="Type" AutoPostBack="true">
   <List SiteUrl="../../.." SiteName="Dashboard" ListName="DocumentType" />
</Field>

The Display Field Name attribute can be replaced with Display Format attribute if you want to display multiple fields in the drop-down menu. The value of the Display Format attribute is in the same format as that of the Calculated Format attribute.

The above configuration assumes the following conditions:

•	The DocumentType list resides three levels above the current page (indicated by ../../.. in the Site URL attribute).

•	The Document Type list contains one field called Type that contains the text for the document type, such as Budget, Proposal, Manual.

•	You want to display the document types sorted alphabetically using the Sort Field attribute. If you do not specify the Sort Field, the document types are sorted in the order they appear in the list; sorted by list item ID.

•	The Site Name attribute is a text description of the Site URL. It does not have to match with the real name of the site pointed to by Site URL.

•	You want the form to be refreshed every time you select another item by specifying AutoPostBack="true". This is necessary if this field is a parent field of other fields in the form and the child fields are visible. Otherwise, it is optional.

You can specify more than one List element inside the Field element. If you do, the List Form will display two dropdowns. The first drop-down menu selects the list and the second drop-down menu selects the items in the list. This function makes the Site Name important because the first drop-down menu displays the list as List Name in SiteName.

System Integration

System Integration (SI) field gets its values from a data column accessible through the System Integration Framework — the same mechanism used by SI Web Parts to connect to external data sources.

In order to use the SI Field, the qListForm should be added to a web part page which belongs to a SharePoint site that has System Integration configuration defined. It also requires that the Catalog property be defined prior to specifying the SI Field.

The required attributes for a field of this type:

Table 13. System Integration

Element	Description
Entity Name	Allows you to specify which entity to use from Catalog property.
Operation Name	Allows you to specify which entity operation to use from Catalog property to retrieve the options from the external system. The syntax for the operation is EntityName.OperationName. Both the entity and the operation must already be defined in the Catalog property.
Data Member/Data Index	Allows you to specify the data table name that contains the options in case the operation returns multiple tables. If the external system returns multiple data tables without names, you can use the DataIndex attribute to refer to the table. The index is a number and it starts with 0 (not 1).
Data Text Field	Allows you to specify the column in the data table whose value is displayed in the drop-down menu.
Data Value Field	Allows you to specify the column in the data table that contains the real value that should be saved back to the external system. Define the DataTextField/DataValueField to be the primary key column for your external data and any other columns as the source for the secondary fields to ensure data integrity; however, it is not required.
Secondary Field Name	Allows you to specify an additional column in the data table whose value is displayed in the drop-down menu. This is an optional field. Secondary fields are elements under the regular display field so you can specify one or more fields. These fields is read-only.
Data Value Field	Allows you to specify the column in the data table from which the actual value is used that is associated with the displayed Secondary Field.
Eliminate Duplicate Values	Allows you to specify whether you want to eliminate duplicate values in the drop-down menu.
Use Item Picker	Allows you to specify whether to use an entity item picker or a drop-down list to display the System Integration column. The default is to use the drop-down list. If you select to use the item picker, you may specify zero or more Finder Operations to be used by the entity item picker. The Finder Operation references the entity.operation defined in the System Integration Catalog property. You can define one or more entity/operation in the Catalog to help filter the data returned from the external system. Select the Add Operation button to add a Finder Operation: • Finder Operation — specifies a valid entity and operation defined in Catalog property to be used in the LookupOperation. • Filter Field — the field name to be used for filtering. If the operator takes an argument, the filtering happens in the back-end server. If not, the filtering happens in the web server by using the data view filter. The filter field name is also used to match the finder operation during the item picker search. • Data Member/Data Index — defines the data table name that contains the options in case the operation returns multiple tables. If the external system returns multiple data tables without names, you can use the DataIndex attribute to refer to the table. The index is a number and it starts with 0 (not 1). The Item Picker option provides the ability to filter a large amount of data before bringing the filtered data into the list form. The default, drop-down list, option will bring all the data over to SharePoint and display it all in a list. Make sure to take into account the amount of data that is returned when deciding the best option to display SI column data using drop-down menu or item picker. Here is an example: <DisplayFields>      <Sessions />           <Fields ContentType="Task">                <Field Name="Title" />                <Field Name="Priority" />                <Field Name="Status" />                <Field Name="AWEmployeeID" LookupOperation="Product.EmployeeList" DataMember="row" DataTextField="LoginID" DataValueField="EmployeeID">                     <SecondaryField Name="AWContactID" DataValueField="EmployeeID" />                     <SecondaryField Name="AWLoginID" DataValueField="LoginID" />                 </Field>           </Fields> </DisplayFields>

Complex Category

The Complex Category field allows the SharePoint discussion view webpart to function like the Lotus Notes response document which contains a category attribute. Categories that allow multiple values are not supported.

The attributes for a field of this type:

Table 14. Complex Category

Element	Description
Edit Mode	Allows you to define how the treeview for the complex category control should be displayed. There are two options: • Inline — the treeview control is displayed in the form itself which enable the user to assign and edit the complex category values directly in the form • Popup — the treeview control will display the complex category value as a read only field with and Edit link. When the user clicks the Edit link, it will display the treeview in a popup dialog box. The Popup option is recommended if you have many categories to be displayed in the treeview.
Complex Category Index Site URL	Allows you to index the Complex Category field. Another SharePoint list is used to store the index. The Complex Category Index Site URL is the site URL of the index list. If not defined, the Complex Category Index Site URL will default to the current site URL.
Complex Category Index List Name	Allows you to set the list name of the index list. If not defined, the Complex Category Index List Name will default to the name of the discussion list plus Categories. For example, if your discussion list name is Team Discussion, then the index list name is Team Discussion Categories.
Height	Allows you to define the height of the complex category control in pixels. If not specified, it will always fit the whole categories in the form without a scrollbar
Expand to Level	Allows you to define the number of category levels that can be expanded when the complex category control is loaded for the first time.