Basic Layout Customizations
.pf-section-header-text {font-size:14px; color:#3333FF; float:left;}
First Look
When the installer finishes you should notice the newly added options on SharePoint’s toolbars, under List Settings. There is a new group called BPC PowerWebForms containing three buttons: NewForm, EditForm and ViewForm Options.
In the most simple scenario, each button will present one option, to register/unregister the PowerForms components for new items,editing or view items respectively.
Let’s take a look at the UI of PowerForms.
Comparing it with SharePoint’s own (displayed below) there are very few changes, so one can start using PowerForms out of the box, without a steep learning curve.
PowerForms has its own Close and Maximize/Restore buttons. Maximizing to fill the entire working space will often be useful, especially if your list gets crammed with components. If you want you to change the default form size, you can do so by editing the web part and specifying a fixed width or height.
In the upper part of the form, there’s a toolbar displayed which consists of the following buttons.
• New Record: If pressed while editing an existing item, it will clear the form and allow you to create a new record. It’s the same as selecting Add New Item while viewing the list. Note, that this will allow you to use the exiting form for adding items, even though you might have not registered PowerForms for New Items. Also, note that any changes to the existing item will not be saved.
Tip: You can use this button to add multiple items, by using Save and New Record, rather than closing the form and re-opening it.
• Save Record: Saves the currently displayed item without closing the form.
• Save and Exit: Saves the currently displayed item and returns to the list.
• Delete Record: Deletes the currently displayed item. If you were in the process of adding a new record but haven’t saved it yet, then trying to delete it will provide you with an error message: Record not saved yet.
• Cancel: Closes the form without committing any of the changes you might have done.
Note that changes regarding the form’s settings (see Design Form, Customizations or Run-Time Designer) have already been committed and are not affected by choosing Cancel. The same effect can be achieved by pressing the X on the top-right corner.
• Flat Mode: Changes the form’s layout to include every different tab and control on a single form, making it easier to print.
• Print: Prints the form.
• Design Form: Pops up a form to view or change all the settings regarding the specific form.
For all of the above buttons, the user must have the relevant permissions. But even then you can choose to hide them using the Designer. For example, you can hide the New Record button if you don’t want to allow users to add records using this form.
Pressing the Design Form button creates a new pop-up window where you can make changes to how the form looks and functions.
Once again, there is a toolbar in the upper part of the form which consists of the following buttons
• Save: Saves the changes made in the Designer view.
• New Tab: Creates a new container tab on the form.
• New Section: Creates a new section on a tab. You can use sections to group controls in order to create a cleaner look for your form as well as to group information together.
• Hide Controls: This square looking button becomes active after you select a control on the form. Its purpose is to quickly make that control invisible on the PowerForms UI after you save the changes on the editor.
• Delete: Deletes the selected control
• Align Left: Changes the alignment of the selected control
• Align Right: Changes the alignment of the selected control
• Format Painter: Copies a single control layout to multiple controls.
• Form Versions: Opens a new pop-up form that lists the different customizations for this specific UI form.
• Migrate Customization: Opens the migration tool. You can use it to copy the customization to an identical list in another web site.
• Export Xml Customization: Exports the form’s customization to an Xml file.
• Import Xml Customization: Imports a PowerForms Xml customization file.
• About: Opens the About PowerForms pop-up screen.
Click here to view a brief demonstration describing the basic concepts and usage of the Designer view.
Registering PowerForms/HTML for a list
Registering PowerForms HTML to work with a Sharepoint list is a very easy process. All that is required is to navigate to the preferred list and then click on one of the buttons located on the far right side of the List Ribbon Bar.
 |
Will replace the default New Item form with a PowerForms HTML form. |
 |
Will replace the default Edit Item form with a PowerForms HTML form. |
 |
Will replace the default View Item form with a PowerForms HTML form. |
Pressing on a button will expand another selection, informing you that you are about to register PowerForms HTML to use instead of the selected default form.
Pressing on the above selection will cause the appearance of a confirmation box. Selecting OK will register PowerForms HTML for use.
To unregister PowerForms HTML and use the default Sharepoint Page again, simply click on the same button on the ribbon bar. The selection informs you that the default Sharepoint form will be used again.
Press OK on the confirmation box.
Helper Methods
PowerForms helper methods is a collection of methods used to help with the creation of scripts.
pf.ParseDate
The above method can be used to easily create a Date object. Date objects can then be used to retrieve year, month and day. DatePicker control values are simple strings. ParseDate can be used to turn DatePicker values to date objects with ease.
For example, c_RegistrationDate is a DatePicker control. To retrieve the registration year, one must do the following:
var dateInStringFormat = form.GetControl(“c_RegistrationDate”).GetValue();
var registrationDateObject = pf.ParseDate(dateInStringFormat);
var theRegistrationYear = registrationDateObject.getFullYear();
alert(theRegistrationYear);
pf.IsEmpty
The above method checks an object to see if it is null or empty.
Example:
if(pf.IsEmpty(value))
{
alert(“Empty value object”);
}
pf.GetNameFromLookup and pf.GetValueFromLookup
The above two functions can be used with any lookup value of the type value;#name.
i.e. 1;#Administrator, 15;#Company.
Values of the above type can be extracted from PeoplePicker, LookupPicker, RadioButton or Comboboxcontrols.
For our examples, we will retrieve the author of a list item using the following formula:
form.DataItem.Author
The above statement returns the following value:
1;#Sharepoint Administrator, which is of the value;#name type.
To retrieve only the Name part:
pf.GetNameFromLookup(form.DataItem.Author)
returns Sharepoint Administrator.
To retrieve only the Value part:
pf.GetValueFromLookup(form.DataItem.Author)
returns 1.
pf.GetNamesFromMultiLookup and pf.GetValuesFromMultiLookup
The above two functions can be used with any multilookup value of the type value1;#name1;#value2;#name2;#value3;#name3.
i.e. 1;#USA;#3;#Middle East and Europe;#2;#North Asia.
Both functions require two parameters to function, the actual values and a seperator, i.e. a comma (,)
pf.GetNamesFromMultiLookup(values, seperator)
pf.GetValuesFromMultiLookup(values, seperator)
To retrieve only the Name part:
pf.GetNamesFromMultiLookup(items[i].CompanyType, “, “)
returns USA,Middle East and Europe,North Asia.
To retrieve only the Value part:
pf.GetValuesFromMultiLookup(items[i].CompanyType, “,”)
returns 1,3,2.
pf.Format(obj, format, locale)
This function can be used to format a Number or Date using the specified format and the current culture.
Examples:
pf.Format(new Date(2013, 3, 12, 22, 12), “dddd MMMM d, yyyy hh:mm tt”, “en-US”);
pf.SetCookie(c_name, value, exdays)
This function can be used to create a cookie for the current page. The function accepts three variables, the name of the cookie, the actual cookie value and the number of days till the cookie expires.
Examples:
pf.SetCookie(“test”,”test123″, “1”);
pf.GetCookie(c_name)
This function can be used to retrieve the value of a previously created cookie. The function accepts one variable, the name of the cookie.
Examples:
var theCookieValue = pf.GetCookie(“test”);
alert(theCookieValue);
pf.AddDaysToDate(date, number of days to add)
This function can be used to add number of days in a date variable. The function accepts two arguments, the value of the date and the number of days that is going to be added.
Examples:
var theNewDateValue= pf.AddDaysToDate(new Date(), 2);
alert(theNewDateValue);
pf.AddDaysToDateSting(string date, number of days to add)
This function can be used to add number of days in a date string variable. The function accepts two arguments, the string value of the date and the number of days that is going to be added.
Examples:
var theDateValue = form.GetControl(‘c_Date’).GetValue();
var theNewDateValue = pf.AddDaysToDateString(theDateValue, 2);
alert(theNewDateValue );
pf.CloneObjectSimpleProperties(object)
This function clones only a control’s simple properties. It is mainly used for serialization.
Examples:
The ImageCheckBox control
The ImageCheckbox control is just like an ordinary checkbox, but instead of having a box to tick, you can use images for the checked/unchecked state.
Type : Checkbox
Name
Provides a unique name for the control.
Binding
Indicates if the control is
- Unbound
- Bound to list column
- Is a label for a control bound to list column
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
Required
Marks the cotnrol as Required.
By default, the system recognizes required fields and marks them with this flag. Additionaly, controls can be marked as required event if the bound column is not.
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”)
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”
Value
This property defines how the control will get its value.
Here are the available options :
- The value is Static (this is the default for label controls)
- The value will be provided by the user (Not applicable for labels)
- The value will be calculated by a formula
- The value will be retrieved from a list query
- The value will be provided by a web service call
- The value will be provided by a SQL query
Static value
A static text must be set in the appropriate designer control.
Formula
A javascript expression must be set that will provide the value for the control.
If the formula contains references to other controls, dependencies will be automatically identifies during run-time and the value will be updated to reflect changes.
Example :
form.FieldValue(“c_Active”) ? “Yes” : “No”
There is an additional option that instructs the form to perform calculations only for new records. Existing records will keep their original value.
List Query
A predefined list query is bound to the value of the control. So during form initialization, the specified list query is executed and if it returns any item, it selects the first one and it will apply the value to the label based on the following rule :
If a Field Name has been selected in the corresponding box, that specific column will be used from the list item to fill the control value.
If the Field Name is left blank, the first column retrieved will be used.
Web Service
The same as above, the required web service is selected and after the web service retrieves data, the first item will be used to update the control value. If no Field Name is set, the control will receive the first field of the retrieved item.
SQL Query
Works the same way ListQueries and Web Service works.
Default Value
The default value has any effect only of the control is bound to a list column.
For unbound controls, the default value is ignored.
You may set a static value here or use a formula by starting your input with the “equals” (=) sign.
Example :
=form.UserInGroup(1) ? “1” : “0”
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 CheckBox control.
Back Color
Not Applicable for the CheckBox control.
Cell Color
Defines the color of the parent cell.
Font Size
Not Applicable for the CheckBox control
Margin
Sets the margin applied to the control, that is, the spacing between the control and the cell borders.
Font Bold
Not Applicable for the CheckBox control
Italics
Not Applicable for the CheckBox control
Not Applicable for this control
YesImage
Represents the image that will be used for the ‘True’ value of the control. If not set, the default image will be used.
NoImage
Represents the image that will be used for the ‘False’ value of the control. If not set, the default image will be used.
ShowAsButton
If you select this option, the image checkbox will be displayed as a button.
Sets the script that will be executed at the value-change event of the control.
Example :
var value = form.GetControl(“c_Title”).GetValue();
if (value == “Open”) form.HideSection(“Details”);
else form.ShowSection(“Details”);