The DocumentGrid conrol

The DocumentGrid conrol

The Document Grid Control

The DocumentGrid control is a container for listing the documents in a SharePoint document library, and provides the means of opening, deleting or uploading a document from/to a specific location:


"Open" button will open the selected document, prompting for ReadOnly/Edit mode just like SharePoint does. 

"Refresh" button will reload the grid's data.

"Remove" button will delete the document from the library.

"Upload" button will add a new document from the user's local disc (the new document is selected with the "Browse" button)

In order to specify the document library from which to retrieve the documents, a ListQuery must be defined and provided as a value to the control (see "Value" below). 


Designer Properties

Type : DocumentGrid


Provides a unique name for the control.


Not Applicable for the DocumentGrid control. It is always unbound. 

Enabled for new records

Sets if the control will be enabled or disabled when the forms handles a new record

Enabled for existing records

Sets if the control will be enabled or disabled when the forms handles an existing record

Note: When not enabled, the grid's "Remove" and "Upload" buttons are disabled. 


Not Applicable for DocumentGrid control.

Enabled Formula

Set an expression then will be evaluated during run-time and enable or disable the control.

The expression must be in javascript and should return a boolean value.

Dependencies between controls are automatically identified and the expression is re-calculated every time a control affecting the formula changes.

Example :


form.GetControl("c_Status").GetValue() != "Open" && form.UserInGroup("Administrators")

Note: When not enabled, the grid's "Remove" and "Upload" buttons are disabled.   

Visibility Formula

Define a valid formula (using javascript) that will be evaluated during runtime to show or hide the control.

The expression should return a boolean value.

For example :


form.FieldValue("c_Status") != "Rejected" || form.UserID() == "1"



The DocumentList control receives its value only with a ListQuery. A predefined list query that returns a set of list items each of which corresponds to a document in a library, is bound to the value of the control. Let's assume the following List Query is defined in the respective section of the designer:



This ListQuery will be used to provide data to the DocumentGrid control: 


Default Value

Not applicable for the DocumentGrid control. 

Layout Properties


Defines the width of the control.

When the value is zero, the maximum allowed width will be used.


Defines the control height.

If the value is zero, the height property will not be set. 


Defines the horizontal alignment of the parent cell (values : left, right, center)


Defines the vertical alignment of the parent cell (values : top, bottom, center)

Fore Color

Not applicable for the DocumentGrid control. 

Back Color

Not applicable for the DocumentGrid control. 

Cell Color

Defines the color of the parent cell.

Font Size

Declares the font size of the text


Sets the margin applied to the control, that is, the spacing between the control and the cell borders.

Font Bold

Changes the weight of the font used


Changes the font style for the control text


Lookup Details

Not applicable for the DocumentGrid control. The control's data are retrieved through ListQuery.


Extra Configuration


Define the page size for the grid. Zero indicates no paging.


This property enables or disables grouping for the grid data


Define the folder where new attachments should be uploaded. If empty, it assumes the default root folder of the document library defined in the ListQuery.


Enables/Disables Uploading  


Enables/Disables Delete


Javascript code to be executed once the data inside the DataGrid are loaded. The reserved variable "items" contains the items retrieved. The following example will show the ID of the first item in the list:


if (items.length > 0)

  alert("The first item's ID is: " + items[0].ID);




Javascript code to be executed once the row selection changes. The "item" variable contains a reference to the selected list item. The following example outputs the ID and Title fields of the selected grid item.


alert("ID: " + item.ID + "  Title:" + item.Title);




Occurs AFTER the data have been placed inside the grid. The 'items' variable is available containing the items retrieved.


Define the duration (in days) for which the new indicator will be shown in the Field(s) where ShowNewIndicator=true. The duration is compared with the Created Date ('Created' field) of the record. 



Specify the url of the image to display as a 'new' indicator. 



Name/Value pairs that are goind to be used to update the document's meta data when a new document is uploaded. This is extremely useful in master detail records, for example when a document library named "Order Documents" has a custom column named "OrderID" that links that document with a list named "Orders". In this case, you would input a pair Name=OrderID, Value = {c_ID} (Value can take either static or calculated values based on existing fields).



The fields to be presented to the grid. If ommited, then the columns returned from the ListQuery are displayed. Each field has the following attribute:

Name:  The internal name of the column to display.

Header:  The column header.

Width: The grid column width (for example 200px). Leave blank for auto sizing.

DisplayFormat: Indicates the way the value will be presented inside the data grid. (The value as-is, the ValueField or DisplayField for lookup controls (ID;#TITLE), Date, DateTime, or Number).

FormatString :  Sets the format for Date and Number fields. For example '#,##0.00' or 'MM/dd/yyyy'.

ForeColor: The color of the cell's text.

FontBold: Sets whether the text font will be bold or not.

FontSize: Sets the font size (for example 20px) 

HAlign: Sets the Horizontal align of the column (Left, Center, Right)

ColumnFiltering :  If selected, then the grid displays a dropdown menu when the user clicks this column, for filtering and sorting purposes.

ShowNewIndicator :  If this property is set to True, the sharepoint 'new' indicator will be shown next to the column value.


Not applicable for Grid controls. Use SelectionChangedScript and DataLoadedScript.


Extra Methods



As the name suggests, this function will export the data to an Excel file, ready to be saved or opened. The function accepts three parameters, described below:

ExportToExcel(array of columns, string file name, string sheet name) 


Columns should be an array of objects with "field" and "title" properties. If no columns are provided, all of the grid's visible columns will be exported.



var grid = form.GetControl("c_Cases").InputControl.DataGrid;

var cols = [];
cols.push({field:"CaseNumber", title:"Case Number"});
cols.push({field:"Title", title:"Title"});
cols.push({field:"CaseType", title:"Case Type"});
cols.push({field:"CType", title:"Case Category"});

grid.ExportToExcel(cols, "Cases.xls", "Cases");




Control Specific Events



This event will fire as soon as you press the Upload button on the DocumentGrid control, just before the actual documents are uploaded.


Show a confirmation dialogue to the user, asking whether to upload the documents or not. If the user presses yes, the documents will be uploaded, otherwise they will not.


var grid = form.GetControl("c_aDocumentGrid").InputControl;

grid.DocumentUploading.AddHandler(function (e2) {

pf.UploadValues = function(e) {
    var conf = confirm("Are you sure you want to upload this file?");
    // documents to be loaded
    if(conf == true){
      // continues uploading files
      e.Cancel = false;
      // cancels uploading
      e.Cancel = true;




This event will fire, after a document gets uploaded, using the DocumentGrid control.



var grid = form.GetControl("c_aDocumentGrid").InputControl;

grid.DocumentUploaded.AddHandler(function (e3) {
     alert("Document Uploaded!");