, ,

The DocumentGrid 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).

 

Type : DocumentGrid

Name

Provides a unique name for the control.

Binding

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.

Required

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 :

Code

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 :

Code

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

 

Value

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.

Width

Defines the width of the control.

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

Height

Defines the control height.

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

H.Alignment

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

V.Alignment

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

Margin

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

Italics

Changes the font style for the control text

 

Lookup Details

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

 

PageSize

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

ShowGroups

This property enables or disables grouping for the grid data

TargetFolder

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.

AllowUpload

Enables/Disables Uploading

AllowDelete

Enables/Disables Delete

DataLoadedScript

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:

Code

if (items.length > 0)

{
  alert(“The first item’s ID is: ” + items[0].ID);
}

 

 

SelectionChangedScript

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.

Code

alert(“ID: ” + item.ID + ”  Title:” + item.Title);

 

 

LoadCompletedScript

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

DaysToShowNewIndicator

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.

 

NewIndicatorImageURL

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

 

Values

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).

 

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.

 

 

ExportToExcel

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.
 Example:
Code
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”);

 

 

DocumentUploading

This event will fire as soon as you press the Upload button on the DocumentGrid control, just before the actual documents are uploaded.
Example:
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.
Code
var grid = form.GetControl(“c_aDocumentGrid”).InputControl;
grid.DocumentUploading.AddHandler(function (e2) {
    pf.UploadValues(e2);
});
pf.UploadValues = function(e) {
    var conf = confirm(“Are you sure you want to upload this file?”);
    // documents to be loaded
    alert(grid.CTRL_ADD_FILES.value);
    if(conf == true){
      // continues uploading files
      e.Cancel = false;
      e.Callback(e);
    }
    else
    {
      // cancels uploading
      e.Cancel = true;
    }
}

 

DocumentUploaded

This event will fire, after a document gets uploaded, using the DocumentGrid control.
Example:
Code
var grid = form.GetControl(“c_aDocumentGrid”).InputControl;
grid.DocumentUploaded.AddHandler(function (e3) {
     alert(“Document Uploaded!”);
});
/by