Web Forms for Marketers - SDN forms/web... · Web Forms for Marketers package, ... 2.1.6 The Web Forms Example Items The module installs some sample forms under /sitecore/system/Modules/Web

Sitecore CMS Modules Web Forms for Marketers

Sitecore® is a registered trademark. All other brand and product names are the property of their respective holders. The contents of this document are the property of Sitecore. Copyright © 2001-2009 Sitecore. All rights reserved.

Sitecore CMS Module

Web Forms for Marketers Installation Guide and User Guide



Page 2 of 64

Table of Contents

Chapter 1 Introduction .......................................................................................................................... 4 Chapter 2 Installation Guide................................................................................................................. 6

2.1 Download and Install the Package .......................................................................................... 7 2.1.1 Access the Sitecore Desktop User Interface ...................................................................... 7 2.1.2 Upload and Install the Package .......................................................................................... 7 2.1.3 Upload the Package ............................................................................................................ 7 2.1.4 Install the Package .............................................................................................................. 7 2.1.5 Restrict Placeholders .......................................................................................................... 8 2.1.6 The Web Forms Example Items .......................................................................................... 8 2.1.7 Complete the Installation ..................................................................................................... 8 2.1.8 Post-Installation Steps ........................................................................................................ 8

Chapter 3 Using the Module .............................................................................................................. 10 3.1 Understanding the Web Form Storage ................................................................................. 11 3.2 Understanding the Form Structure ........................................................................................ 13 3.3 Multi-site Implementation ...................................................................................................... 15 3.4 Adding a New Form to a Layout............................................................................................ 16 3.5 Creating a New Form ............................................................................................................ 17 3.6 Form Designer....................................................................................................................... 21

3.6.1 The Form Designer Toolbar .............................................................................................. 21 3.6.2 The Workspace ................................................................................................................. 22 3.6.3 Form Fields ....................................................................................................................... 23 3.6.4 Field Sections .................................................................................................................... 23 3.6.5 Property Editor .................................................................................................................. 24 3.6.6 Configuring Submit Action ................................................................................................. 24

3.7 Editing Forms ........................................................................................................................ 25 3.8 Form Field Types .................................................................................................................. 26

3.8.1 Single-Line Text ................................................................................................................ 26 3.8.2 Multi-Line Text ................................................................................................................... 27 3.8.3 Password ........................................................................................................................... 28 3.8.4 Number .............................................................................................................................. 29 3.8.5 Email ................................................................................................................................. 30 3.8.6 Date ................................................................................................................................... 30 3.8.7 File Upload ........................................................................................................................ 31 3.8.8 Checkbox .......................................................................................................................... 32 3.8.9 Drop List ............................................................................................................................ 32 3.8.10 Radio Button List ........................................................................................................... 33 3.8.11 List Box .......................................................................................................................... 34 3.8.12 Checkbox List ................................................................................................................ 34 3.8.13 Section .......................................................................................................................... 35

3.9 Validation ............................................................................................................................... 36 3.10 Restricting Placeholders Shown in the Placeholder List ....................................................... 37 3.11 Actions ................................................................................................................................... 38

3.11.1 Save to Database .......................................................................................................... 39 3.11.2 Send Mail ...................................................................................................................... 40 3.11.3 Create Item .................................................................................................................... 41

3.12 Alternative for Actions ........................................................................................................... 45 3.13 Form Data Viewer ................................................................................................................. 46

3.13.1 Configuring Data Provider ............................................................................................. 47 3.13.2 Operations ..................................................................................................................... 48 3.13.3 Statistic .......................................................................................................................... 48



Page 3 of 64

3.14 Example Forms. .................................................................................................................... 49 3.15 Staging Environment ............................................................................................................. 51 3.16 Security ................................................................................................................................. 52

Chapter 4 Developer Hints ................................................................................................................. 53 4.1 Add a new field type .............................................................................................................. 54 4.2 Add a new action ................................................................................................................... 60 4.3 Css themes ........................................................................................................................... 61 4.4 Load items from content tree to list control ........................................................................... 62 4.5 Export to ASCX ..................................................................................................................... 63

4.5.1 Add ascx control to the page ............................................................................................. 63



Page 4 of 64

Chapter 1

Introduction

The Web Forms for Marketers module is designed to create simple forms in a blink of an eye and in a friendly manner. The module can be configured so that forms have only a few adjustable parameters thus making the user interface as simple as possible. For instance, the basic options cover the most frequent needs of a regular web site editor such as creating basic input fields (text boxes, checkboxes), basic actions (save to a database, send an email) and basic validators (RequiredField validator, Email address validator, etc.).

More complex forms can be developed based on a form generated by this module. There is an option to convert the form into a sublayout (.ascx file), so that developers can edit this sublayout using common development tools like Visual Studio.

Assuming the fact that usually most forms on a website are simple and straightforward, their creation and management may be simple and straightforward as well.

This is how a sample form created using this module looks like on a site:



Page 5 of 64



Page 6 of 64

Chapter 2

Installation Guide

This chapter describes how to download and install the module.



Page 7 of 64

2.1 Download and Install the Package

The Web Forms for Marketers module is distributed as a Sitecore package. Sitecore packages resemble Windows Archive (.zip) files, but should not be unzipped before installation. If you do not already have the Web Forms for Marketers package, you may download it via the Sitecore Developer Network (http://sdn.sitecore.net).

2.1.1 Access the Sitecore Desktop User Interface

Once you have the module package available on your local machine, log in to the Sitecore Desktop user interface for the target site. You should log in as a user with administrator privileges, such as Admin.

2.1.2 Upload and Install the Package

Open the Installation Wizard from the Sitecore » Development Tools menu or the Control Panel » Administration » Install a Package task.

2.1.3 Upload the Package

Select the Upload button to open the Upload Wizard.

Select the Browse button on the Select Files step and locate the Calendar package on your local machine.

Select the Open button on the Choose File dialog when you have selected the Calendar package.

Select the “Next »” button on the Select Files step.

Select the “Next »” button again, on the Overwrite Existing Files step.

Select the “Finish” button to close the Upload Wizard.

2.1.4 Install the Package

Select the “Next »” button on the Specify Package step.

Read the License Agreement and select the “I accept the terms of the license agreement” radio button.

Select the “Next »” button on the License Agreement step.

Read the Readme information.

Select the “Next »” button on the Readme step.

The Installation Wizard now displays the Ready to Install step, which shows the revision of the module package you will install.

Select the “Install” button to begin the installation.

Note: Progress Meter Freezes This installation will restart the Sitecore server process and will therefore the progress bar will freeze at various stages of the installation. Please have patience! Do not abort the installation once the progress bar appears.



Page 8 of 64

2.1.5 Restrict Placeholders

When the installation is finished, the module will ask you to create the list of placeholders which will be available when adding forms on layouts.

You can specify the placeholders at this point or do it any time later using the All Applications » Web Forms for Marketers » Restricting Placeholders command.

2.1.6 The Web Forms Example Items

The module installs some sample forms under /sitecore/system/Modules/Web Forms for Marketers/Example Forms.

2.1.7 Complete the Installation

When the Installation Wizard displays the final step, select the Restart the Sitecore Client toggle, but leave the Restart the Sitecore Server toggle unselected.

Select the Finish button.

The installation is now complete.

2.1.8 Post-Installation Steps

The module is ready to use right after the installation without any additional changes.

By default the SQLite database is used to store the module’s internal information. If you want the module to work with MSSQL database you should perform the following steps:

1. Comment out the following section:



Page 9 of 64

<formsDataProvider

type="Sitecore.Forms.Data.DataProviders.SQLite.SQLiteDataProvider,

Sitecore.Forms.Core">

…

</formsDataProvider>

2. Uncomment the following section: 

<formsDataProvider

type="Sitecore.Forms.Data.LINQ.LinqDataProvider,Sitecore.Forms.Core">

<param desc="connection string">Database=(database);data

source=(server);user id=(user);password=(password);Connect

Timeout=30</param>

<cacheSizes hint="setting">

<data>20MB</data>

<archive>20MB</archive>

</cacheSizes>


3. Set the connection string to the MSSQL database in the forms.config file.

By default the module databases are stored in the /data/ folder under the Sitecore CMS root folder. The databases include:

sitecore.webforms.db – SQLite database;

sitecore.webforms.mdf – MSSQL database; sitecore,webforms_log.ldf – MSSQL log file;

sitecore.webforms.bak – backup file of the empty MSSQL database.



Page 10 of 64

Chapter 3

Using the Module

This chapter describes the functionality of the module and the user interface.



Page 11 of 64

3.1 Understanding the Web Form Storage

The structure of the forms is defined in the Sitecore CMS content tree. User input, entered in the forms, is saved in the modules own database.

The module defines forms using items that are stored in appropriate folders under /sitecore/system/Modules/Web Forms for Marketers.

The location of forms for each site is defined by the “formsRoot” attributes of “/sitecore/sites/site” nodes of web.config file. In case when the “formsRoot” attribute is not defined for a site, new forms are created in the /sitecore/system/Modules/Web Forms for Marketers/Local Forms folder.

The form folders are based on the /sitecore/templates/Web Forms for Marketers/Forms Folder template.

Each form is based on the /sitecore/templates/Web Forms for Marketers/Form template and can contains any number of sections or fields, but not sections and fields on the same level.

Every form has a submit button and you can associate actions with this button. Actions are executed on the server.



Page 12 of 64

The list of available actions is stored under the /sitecore/system/Modules/Web Forms for Marketers/Settings/Actions folder.



Page 13 of 64

3.2 Understanding the Form Structure

Forms generated by the Web Forms for Marketers module have a standard set of elements which include:

The form title – the name of the form. Rendered on top of the form.

Introduction – the piece of text which includes any useful information that users should know before they fill your form. Rendered after the form title.

Sections and Fields – the main content of the form.

Footer – the piece of text rendered below all sections and fields.

Submit Button – the button which triggers the actions attached to this form.

Success Message – the message shown to users after the form is submitted without any errors.

Take a look at the sample form:



Page 14 of 64

And this is how the same form looks in the Form Designer:



Page 15 of 64

3.3 Multi-site Implementation

The module supports multi-site environments. This means that administrators can define unique forms location and settings for different sites. This behavior is available through the “formsRoot” attribute in the definition of any site in .config files. The value of this attribute is a Sitecore path which defines:

The folder that stores the forms of the current site;

The appearance and color theme settings for forms of the current site;

The access rights.

The “formsRoot” parameter must contain either an item path or the ID of the target item that is based on the /sitecore/templates/Web Forms for Marketers/Forms Folder template.

For example, this is how the formsRoot parameter is defined in web.config file:

<sites>

<site

name="samplesite"

virtualFolder="/"

physicalFolder="/"

rootPath="/sitecore/content"

startItem="/forms" database="web" domain="extranet"

formsRoot="/sitecore/system/modules/Web Forms for Marketers/local forms"

...

And this is how it can be defined in the forms.config file using the ID:

<site name="website">

<patch:attribute name="formsRoot">

{F1F7AAB6-C8CE-422F-A214-F610C109FA63}

</patch:attribute>

</site>

</sites>

We recommend to define the “formsRoot” parameter in the /App_Config/forms.config file. This approach ensures the absence of duplicated values.

In case when the “formsRoot” attribute is not defined for a site, new forms are stored in the /sitecore/system/Modules/Web Forms for Marketers/Local Forms folder.



Page 16 of 64

3.4 Adding a New Form to a Layout

New forms can be inserted via the Page Editor interface and via the Presentation tab of the Content Editor ribbon.

The module adds the “Insert Form” button in the “Presentation” tab of the Content Editor ribbon:

The “Insert Form” button starts the “Insert a New Form” wizard that will guide you through the form creation process.



Page 17 of 64

3.5 Creating a New Form

The module provides the Create a New Form wizard which will guide you through the form creation process.

When you click the Insert Form button, the wizard first checks whether the current item has a layout assigned. If this condition is not met, the wizard displays the following message:

Forms are renderings, so they should be attached to layouts.

If it’s possible to insert a form, the Create a New Form appears. It consists of the following steps.

Create a New Form You can either create a new blank form and fill it, or use an existing form as a template. If you choose the Select a form to copy option you will be moved to the Copy an existing form wizard page.



Page 18 of 64

Copy an existing form Select a form to copy and click “Next”.

Select a Placeholder Select a placeholder where the new form will be inserted. The wizard scans the current layout for available placeholders and filters them according to the “Restrict placeholders” setting. Moving the mouse cursor over the placeholder calls the special flyover help that shows additional information about the current placeholder (if available). The Devices field allows you to choose a device.



Page 19 of 64

Confirmation This window shows the summary of the choices you made. If you choose the “Copy an existing form” option, the summary will contain the prototype of the form. Verify your choices and click the Create button to complete the process.

After you click the Create button, the new form will be opened in the Form Designer.



Page 20 of 64

The location where the form will be created depends on the “formsRoot” parameter in the forms.config file or web.config file.



Page 21 of 64

3.6 Form Designer

The Form Designer is the application which allows you to design and edit the forms. You can see the Form Designer in the following image:

3.6.1 The Form Designer Toolbar

The Form Designer toolbar contains the following buttons:

Save Saves the current state of the form. Fields without names and sections without names and fields are not saved.

Save/Close Saves the form and closes the designer.

Title Hides or shows the title of the form. The command does not delete the text in the title field.

Intro Hides or shows the introduction of the form. The command does not delete the text in the field.

Footer Hides or shows the footer of the form. The command doesn’t delete the text in this field.

Language Switches the current language. The command helps to build multiple languages forms.



Page 22 of 64

To ascx Converts the current form into the regular ASCX control.

Sorting Commands Allows users to define the order in which the sections and fields are shown in the form. The designer also supports drag&drop to sort the fields.

Close Closes the “Form Designer” window without saving the current form.

3.6.2 The Workspace

The Forms Designer workspace has three main parts:

The field editor on the left.

The sections and fields list on the right.

Submit action. The designer allows you to define the actions performed when the user clicks the Submit button.



Page 23 of 64

3.6.3 Form Fields

The set of fields defines the look and purpose of a form.

Each form field, in one’s turn, contains the following fields:

Title The name of the field on the front end. It is also a label generated for the field.

Type The type of the field.

Required This checkbox defines whether the “Required not empty value” validator is attached to this field. The checkbox is disabled if it doesn’t have any sense for the current field.

Delete button The button which deletes the selected field.

3.6.4 Field Sections

Field sections are used to group other fields.

Every form contains the Add Section buttons which should be used to create sections. A form can have only fields not grouped into any sections.



Page 24 of 64

3.6.5 Property Editor

When you select a field, you can see its available properties on the left in the Property Editor.

The list of properties depends on the type of the field selected.

3.6.6 Configuring Submit Action

When you select a submit action in the form, you will see the property editor on the left which will look similar to the one shown in the image below:

Button Name The name of the submit button.

Actions The list of actions which will be executed on the server after a user clicks the submit button.

Success Message The text shown inside the form in case of successful execution of all actions.



Page 25 of 64

3.7 Editing Forms

Use the Design button in the Forms tab to start the Forms Designer from the Content Editor ribbon.

Use the “Edit” button when using the Page Editor mode:



Page 26 of 64

3.8 Form Field Types

The Web Forms for Marketers module provides module specific field templates which are used in forms.

All form field types are stored under the /sitecore/system/Modules/Web Forms for Marketers/Settings/Field Types item and are based on the /sitecore/templates/Web Forms for Marketers/Field Type template.

The Field Type template has the following fields:

Class – the full name of the class that renders the field on the front-end using settings from an item in the content tree.

Assembly – the name of the assembly that contains the class.

Required – the field which defines whether the “required value” validator is applied to this type.

Validation – the list of validators which should be applied to the value entered in this field.

3.8.1 Single-Line Text

This is a one line text field. The length is limited to 255 characters by default.

The /sitecore/system/Modules/Web Forms for Marketers/Settings/Field Types/Simple Types/Single-Line Text item contains the following settings for this type:



Page 27 of 64

Name Value

Class Sitecore.Form.Web.UI.Controls.SingleLineText

Assembly Sitecore.Forms.Custom.dll

Required Yes

Validation Count Chars, Regex Pattern

The Sitecore.Form.Web.UI.Controls.SingleLineText class provides the following properties for the “Properties Editor”:

Name Default value Localizable Description

Default value

Yes Sets initial value for the field.

Help Yes A text to display as help message for users near the field.

Css Class scfSingleLineTextBorder

No Sets the name of the css class.

Regular Expression

No Sets regular expression that checks user’s input. The property is using with Regex Pattern validator.

Minimum Length 0 No The minimal count of chars that must be typed here. Using with Count Chars validator.

Maximum Length 256 No The maximal count of chars that can be typed here. Using with Count Chars validator.

3.8.2 Multi-Line Text

The Multi-Line Text field is used to store multiple lines of text. In addition, this field spans across multiple lines and accepts more text than you will probably ever need. The number of characters is limited to 512 by default.

The /sitecore/system/Modules/Web Forms for Marketers/Settings/Field Types/Simple Types/Multiple-Line Text item contains the following settings for this type:

Name Value

Class Sitecore.Form.Web.UI.Controls.MultipleLineText



Page 28 of 64


Required Yes


The Sitecore.Form.Web.UI.Controls.MultipleLineText class provides the following properties for the “Properties Editor”:


Default value


Rows 4 No Sets the number of rows displayed in the field.


Css Class scfMultipleLineTextBorder


Regular Expression




3.8.3 Password

A text field where all characters entered are masked.

The /sitecore/system/Modules/Web Forms for Marketers/Settings/Field Types/Simple Types/Password item contains the following settings for this type:

Name Value

Class Sitecore.Form.Web.UI.Controls.Password


Required Yes


The Sitecore.Form.Web.UI.Controls.Password class provides the following properties for the “Properties Editor”:



Page 29 of 64


Default value



Css Class scfPasswordBorder No Sets the name of the css class.

Regular Expression




3.8.4 Number

Use this field to enter data in numerical format.

The /sitecore/system/Modules/Web Forms for Marketers/Settings/Field Types/Simple Types/Number item contains the following settings for this type:

Name Value

Class Sitecore.Form.Web.UI.Controls.Number


Required Yes

Validation Number, Number Range

The Sitecore.Form.Web.UI.Controls.Number class provides the following properties for the “Properties Editor”:


Default value



Css Class scfNumberBorder No Sets the name of the css class.

Minimum Value 0

No The minimal value that can be typed here. Using with Number Range validator.

Maximum Value 2147483647 No The maximal count of chars that can be typed here. Using with Number Range validator.



Page 30 of 64

3.8.5 Email

Use to enter email addresses. The "@" and "." characters are validated, as well as the length of the email server domain.

The /sitecore/system/Modules/Web Forms for Marketers/Settings/Field Types/Simple Types/E-mail item contains the following settings for this type:

Name Value

Class Sitecore.Form.Web.UI.Controls.Email


Required Yes

Validation Email

The Sitecore.Form.Web.UI.Controls.Email class provides the following properties for the “Properties Editor”:


Default value



Css Class scfEmailBorder No Sets the name of the css class.

3.8.6 Date

Use to enter date data.

The /sitecore/system/Modules/Web Forms for Marketers/Settings/Field Types/Simple Types/Date item contains the following settings for this type:

Name Value

Class Sitecore.Form.Web.UI.Controls.DateSelector


Required No

Validation Date



Page 31 of 64

The Sitecore.Form.Web.UI.Controls.DateSelector class provides the following properties for the “Properties Editor”:


Display Format dd-MMM-yyyy No Sets format for the displaying of the date.

Selected Date Today No Sets initial value for the field.


Css Class scfDateSelectorBorder No Sets the name of the css class.

Start Date 01 January 2000 No Represents the smallest possible value of the field. Using with Date validator.

End Date Today No Represents the largest possible value of the field. Using with Date validator.

3.8.7 File Upload

File Upload displays a text box control and a browse button that allow users to select a file to upload to the server.

The /sitecore/system/Modules/Web Forms for Marketers/Settings/Field Types/Simple Types/File Upload item contains the following settings for this type:

Name Value

Class Sitecore.Form.Web.UI.Controls.UploadFile


Required No

Validation

The Sitecore.Form.Web.UI.Controls.UploadFile class provides the following properties for the “Properties Editor”:


Upload To /sitecore/media library/Files

Yes Sets a folder in the content tree where files will be stored

Help No A text to display as help message for users near the field.

Css Class scfFileUploadBorder No Sets the name of the css class.

The field works with the master database.

http://msdn.microsoft.com/en-us/library/system.datetime%28VS.71%29.aspx

http://msdn.microsoft.com/en-us/library/system.datetime%28VS.71%29.aspx



Page 32 of 64

3.8.8 Checkbox

The field displays a check box control that allows users to select a true or false condition.

The /sitecore/system/Modules/Web Forms for Marketers/Settings/Field Types/Simple Types/Checkbox item contains the following settings for this type:

Name Value

Class Sitecore.Form.Web.UI.Controls.Checkbox


Required No

Validation

The Sitecore.Form.Web.UI.Controls.Checkbox class provides the following properties for the “Properties Editor”:


Checked No No Sets initial state for the field.


Css Class scfCheckboxBorder No Sets the name of the css class.

3.8.9 Drop List

Drop Down Lists allows users to select one option from a list.

The /sitecore/system/Modules/Web Forms for Marketers/Settings/Field Types/List Types/Drop List item contains the following settings for this type:

Name Value

Class Sitecore.Form.Web.UI.Controls.DropList


Required Yes

Validation



Page 33 of 64

The Sitecore.Form.Web.UI.Controls.DropList class provides the following properties for the “Properties Editor”:


Items

No Represents the list of items for the field.

Selected Value No Sets initial value for the field.

Empty choice Yes No Adds or removes the empty choice to the items list


Css Class scfCheckboxBorder No Sets the name of the css class.

3.8.10 Radio Button List

The field represents a list control that contains a group of radio button controls.

The /sitecore/system/Modules/Web Forms for Marketers/Settings/Field Types/List Types/Radio List item contains the following settings for this type:

Name Value

Class Sitecore.Form.Web.UI.Controls.RadioList


Required No

Validation

The Sitecore.Form.Web.UI.Controls.RadioList class provides the following properties for the “Properties Editor”:


Items



Direction Vertical No Sets the direction in which the radio buttons within the group are displayed.

Columns 1 No sets the number of columns to display in the field.




Page 34 of 64

Css Class scfRadioButtonListBorder


3.8.11 List Box

The field provides a list box control that allows single or multiple item selection.

The /sitecore/system/Modules/Web Forms for Marketers/Settings/Field Types/List Types/List Box item contains the following settings for this type:

Name Value

Class Sitecore.Form.Web.UI.Controls.List


Required Yes

Validation

The Sitecore.Form.Web.UI.Controls.List class provides the following properties for the “Properties Editor”:


Items



Selection Mode Multiple No Defines the selection behavior for the field.

Rows 4 No Sets the number of rows displayed in a multiline text box.


Css Class scfListBoxBorder No Sets the name of the css class.

3.8.12 Checkbox List

The field displays a multi selection check box group.



Page 35 of 64

The /sitecore/system/Modules/Web Forms for Marketers/Settings/Field Types/List Types/Checkbox List item contains the following settings for this type:

Name Value

Class Sitecore.Form.Web.UI.Controls.CheckboxList


Required Yes

Validation

The Sitecore.Form.Web.UI.Controls.CheckboxList class provides the following properties for the “Properties Editor”:


Items



Direction Vertical No Sets the direction in which the radio buttons within the group are displayed.

Columns 1 No Sets the number of columns to display in the field.


Css Class scfCheckBoxListBorder


3.8.13 Section

Section is a special field that can be a container for fields. It represents the following properties for the “Properties Editor”:


Show title Yes No Defines whether the section title is visible.


Css Class scfSectionBorder No Sets the name of the css class.



Page 36 of 64

3.9 Validation

The module provides a set of predefined validation rules.

The module installs two validator templates:

/sitecore/templates/Web Forms for Marketers/Validators/BaseValidator.

/sitecore/templates/Web Forms for Marketers/Validators/Regular Expression Validator.

The latter one inherits the fields of the former one and extends them.

The “validator” item contains the following fields:

Class – the full name of the class which handles the validation.

Assembly – the name of the assembly that contains the class.

Error Message – the text for the error message displayed in a ValidationSummary control when validation fails.

Text – the text displayed in the validation control when validation fails.

Static Display - the display behavior of the error message in a validation control:

a. None - The validation message is never displayed inline.

b. Static - Space for the validation message is allocated in the page layout.

c. Dynamic - Space for the validation message is dynamically added to the page if validation fails.

Enable Script Validation - value indicating whether client-side validation is enabled.

Parameters – the additional parameters for the validation control.

Inner Control – indicates the place where the validation control is added.

Validation Expression - sets the regular expression assigned to be the validation criteria (Only for validation items that use the Regular Expression Validator).

http://msdn.microsoft.com/en-us/library/system.web.ui.webcontrols.validationsummary.aspx



Page 37 of 64

3.10 Restricting Placeholders Shown in the Placeholder List

The “Insert a New Form” wizard allows the adding forms only to placeholders that have “Placeholder Settings” items. Besides users that add new forms must have write access to those items to see placeholders in the Placeholder list”. This allows developers and web-site administrators to define which placeholders may contain a form.

The “Restricting Placeholders” application helps to restrict the list of placeholders shown in the “Placeholder list” of the “Insert a New Form” wizard.

The placeholders in the “Selected” part of the window displays where users can add a new form. After click the “Ok” button all changes are stored.

After the module installation the module shows the “Restricting Placeholders” application and users can select the placeholders they want to use. This application is also called through the Sitecore \All Applications\Web Forms for Marketers\Restricting Placeholders command.



Page 38 of 64

3.11 Actions

To process form data on the server side users can use a predefined list of actions. The module provides 3 actions:

“Save to Database” stores forms data to the module database.

“Send Mail” sends a notification mail with a predefined text to an e-mail.

“Create item” creates the new item on basis of form data.

All actions are stored under the /sitecore/system/Modules/Web Forms for Marketers/Settings/Actions item.

Users can configure the following fields of any action:

Class – the full name of the class that process form data on the server side.

Assembly – the name of the assembly that contains the referred to above class.

Parameters – sets irrespectively of forms parameters for the action.

Editor – provides the application using that users can change parameters of the action for any form.

To customize actions for the form users should run “Select Submit Actions” dialog. It can be called:

from the “Properties Editor” panel of the “Form Designer” application. Users should select “Submit” section in the designer and in the shown panel of properties click “Edit Actions” link.

from the toolbar of the ”Content Editor”. Users should select a form item in the content tree and in the showed “Forms” contextual ribbon click the “Actions” button



Page 39 of 64

The “Select Submit Actions” dialog allows on the level of the form defines action. The “Actions” list contains all available actions. Choosing necessary one and clicking the “Add” button you can attach new actions to the form.

The “Edit” button is only shown for the actions that have an editor.

3.11.1 Save to Database

The action allows the saving of form data to a predefined database. To view stored data users can run the “Form Data Viewer” application.

The /sitecore/system/Modules/Web Forms for Marketers/Settings/Actions/Save to Database item contains the following settings:

Name Value

Class Sitecore.Form.Submit.SaveToDatabase

Assembly Sitecore.Forms.Custom

Parameters

Editor



Page 40 of 64

The only parameter of this action is the connection string for the database that users want to use. To choose one or another database user can in the forms.config.

The distributive of the module provides the using of DLINQ and SQLite databases.

3.11.2 Send Mail

The “Send Mail” action sends a mail every time users click the submit button. The recipient and body of the mail can differ for each form. The mail is sent using the SMTP protocol.

The /sitecore/system/Modules/Web Forms for Marketers/Settings/Actions/Save to Database item contains the following settings:

Name Value

Class Sitecore.Form.Submit.SendMail


Parameters <Host>example.net</Host><From>[email protected]</From>

Editor control:SendMail.Editor

“Host” and “From” must have a valid values otherwise the action will not work.

The item for this action allows you to set the following properties:

To represents address collection that contains the recipients of this e-mail message.

CC provides address set that contains the carbon copy (CC) recipients for this e-mail message.

Subject sets the subject line for this e-mail message.

Body sets the message body

The divider in the To and CC is the “;” symbol.

Use the "Insert Field" button from the toolbar to add the value from a form field to the mail. This exchanges the chosen field with the chosen value when the action is executed.

The settings that are defined using this editor are stored in the form item.



Page 41 of 64

3.11.3 Create Item

The “Create Item” action creates a new item in the content tree which is performed every time the Submit button is clicked on a form.

The /sitecore/system/Modules/Web Forms for Marketers/Settings/Actions/Create Item item provides the following settings:

Name Value

Class Sitecore.Form.Submit.SendMail

Assembly Sitecore.Form.Submit.CreateItem

Parameters

Editor control:MappingTemplate

The extra wizard editor for this action consists of 3 pages:

“Select template” allows you to select the template for future items and the destination folder in which they will be stored. Select your parameters and click “Next”.



Page 42 of 64



Page 43 of 64



Page 44 of 64

“Mapping form fields” determines which values will be stored in which form fields for all future items which use the template.

Users can use “Show Standard Fields” if they want to use values of system fields. This might helpful for automatically assigning names to fields.

“Confirmation” shows you a list of the fields and values you have chosen. It will also display warnings in cases where information might be lost (for example where fields have no values mapped to them.) or field collision (conflicting values).

After verifying your choices click “Finish” to complete the configuration process.



Page 45 of 64

3.12 Alternative for Actions

In addition to adding actions to a form you can subscribe to the event created when the “Submit” action is performed and add executing commands in your handler based on that event.

The module creates the “forms:save” event to which you can subscribe in the forms.config

<events timingLevel="custom">

<event name="forms:save">

<handler type="Sitecore.Form.Submit.FormSaveEventTest,Sitecore.Forms.Custom"

method="OnFormSave" />

</event>

</events>

The FormSaveEventTest class should be like this:

using System;

using System.Collections.Generic;

using Sitecore.Data;

using Sitecore.Events;

using Sitecore.Form.Core.Controls.Data;

namespace Sitecore.Form.Submit

{

public class FormSaveEventTest

{

protected void OnFormSave(object sender, EventArgs args)

{

SitecoreEventArgs sArgs = args as SitecoreEventArgs;

if (sArgs != null)

{

ID formID = sArgs.Parameters[0] as ID;

AdaptedResultList results = sArgs.Parameters[1] as AdaptedResultList;

}

}

}

}

The “forms:save” event is created for all forms.



Page 46 of 64

3.13 Form Data Viewer

The data viewer reads data from the database and presents it in a page. The viewer can be called

from the toolbar of the ”Content Editor”. Users should select a form item in the content tree and in the showed “Forms” contextual ribbon click the “Data View” button

from the Sitecore\All Applications\Web Forms for Marketers\Form Data Viewer menu. After in the “Select Form” dialog users select the form they want the viewer will open.

The data for the form is stored only if this form has a “Save to Database” action.

Besides the viewing the application provides a possible to delete, archive data and also to export data to some other formats.

The “Form Data Viewer” contains of 2 tabs page. On the first you can review from data in the data grid and the second contains detailed statistic about using the current form.



Page 47 of 64

3.13.1 Configuring Data Provider

In order for the “Form Data Viewer” to work correctly. the relation between the module and the database must be configured. The module supports MSSQL and SQLite databases. In the forms.config file, choose a data provider using the “type” attribute in the “formsDataProvider” tag. Among the possible values are:

Sitecore.Form.DataProvider.WFMDataProvider,Sitecore.Forms.Core – the provider for the work with MSSQL. <formsDataProvider

type="Sitecore.Forms.Data.DataProviders.WFMDataProvider,Sitecore.Forms.

Core">

<param desc="connection string">Database=(database);data

source=(server);user id=(user);password=(password);Connect

Timeout=30</param> </formsDataProvider>

Sitecore.Form.DataProvider.SQLite.SQLiteWFMDataProvider,Sitecore.Forms.Core – the provider for the SQLite database. <formsDataProvider type="

Sitecore.Forms.Data.DataProviders.SQLite.SQLiteWFMDataProvider,Sitecore

.Forms.Core ">

<param desc="connection string">Data

Source=/data/sitecore.webforms.db;version=3;BinaryGUID=true</param>




Page 48 of 64

3.13.2 Operations

The “Form Data Viewer” ribbon allows you to select actions and views related to Form Data.

View/Refresh reloads form data.

Columns/Select allows you to choose the set of columns you want to see in the application.

Open displays the selected form and its related data.

Operations/Delete removes selected records in the data grid. “Delete All” menu removes all records from the database.

Operations/Archive command moves selected records in the data grid to the archive. “Archive All” moves all records to the archive.

Export/To Excel exports selected records to the excel document. “All to Excel” exports all records to the excel file.

Export/To Xml exports selected records to the xml format. “All to Xml” exports all records to the xml format.

Switch to/Archive loads form data from the archive.

Switch to/Designer opens the active form in the “Form Designer”.

3.13.3 Statistic

Tthe “Form Data Viewer” also allows you to view statistics about the selected form.

The statistics include a “Response” count, which describes how many times each value from the listed list fields.



Page 49 of 64

3.14 Example Forms.

The module provides form templates that you can use or modify as required. These can be found in /sitecore/system/Modules/Web Forms for Marketers/Example Forms and are available for all users by default.

Leave a Message

This form allows a website visitor to submit a query or give you feedback.

Create an Account

This form can be used allow website visitors to create an account.

This form uses password validation action which ensures that the values from the “Password” and “Confirmation” fields match. The action is based on the /sitecore/system/Modules/Web Forms for Marketers/Settings/Actions/Compare Password-Confirmation item.

Tell a Friend



Page 50 of 64

This form can help spread the word about your site.

This form uses the Send Mail action. The action uses the “Friend’s Email” and “Message” fields to define the recipient email address and body of the email message. The action is based on the /sitecore/system/Modules/Web Forms for Marketers/Settings/Actions/Tell a Friend item.



Page 51 of 64

3.15 Staging Environment

The module supports staging. Add a new connection string that points on your master server to the connectionstrings.config file on the slave in order to configure this.

<add name="remoteWfmService"

connectionString="url=http://localhost/sitecore%20modules/shell/Web%20Forms%20for%20Marketers/Sta

ging/WfmService.asmx;user=[domain\username];password=[password];timeout=60000" />

Where

[domain\username] – sitecore user(full name). The necessary access rights depend on items the form is working with.

[password] – a user’s password



Page 52 of 64

3.16 Security

Users that inherit the sitecore\Sitecore Client Forms Author role can insert and edit forms.



Page 53 of 64

Chapter 4

Developer Hints



Page 54 of 64

4.1 Add a new field type

The list of field types you can be extended by creating a class that renders the field and registers it as sitecore content.

After you create a new item using /sitecore/templates/Web Forms for Marketers/Field Type template in the /sitecore/system/Modules/Web Forms for Marketers/Settings/Field Types/Custom folder you should complete the associated fields.

For example, in the Custom.dll assembly you create a new control named Sitecore.Custom.Controls.Textbox.

namespace Sitecore.Custom.Controls

{

public class Textbox

{

…

}

}

Create a new item in the /sitecore/system/Modules/Web Forms for Marketers/Settings/Field Types/Custom folder and set its Class and Assembly fields.

Check “Required” if you want your control to use the “Required Value” validator. You can select then the any other validations that you require here in the Validation section.

If your control must return a value to the server, the control should implement IResult interface:

namespace Sitecore.Form.Web.UI.Controls

{

public interface IResult

{

ControlResult Result { get; }

string ControlName { get; set; }



Page 55 of 64

string FieldID { get; set; }

}

}

Result – returns the value of the field in the object of the ControlResult class. The

constructor of the ControlResult has the following signature:

public ControlResult(string fieldName, object value, string parameters)

where

fieldName – is the name of the field, defined only for the custom customization.

value – is the value of the field.

parameters – additional parameters.

If a retunred value is not a string you must set an adapter for it. You can do this before the class

definition using the Adapter attribute.


{

[Adapter(typeof (DateAdapter))]

[ValidationProperty("Value")]

public class DateSelector : ValidateControl, IHasTitle

The type from this attribute must inherit the Adapter abstract class.

using System.Collections.Generic;

namespace Sitecore.Form.Core.Client.Submit

{

public abstract class Adapter

{

// Convert object value to string

public virtual string AdaptResult(object value)

{

return value.ToString();

}

// Convert value from database to friendly value. Using in the Form Data Viewer

public virtual string AdaptToFrendlyValue(string value)

{

return value;

}

// Convert list value from database to friendly value. Using in the Form Data

Viewer

public virtual IEnumerable<string> AdaptToFrendlyListValues(string value)

{

return new List<string>(new[]{value});

}

}

}

ControlName – the name of the item that is corresponding this field is moved here

FieldID – inits by the id of the item that is corresponding this field



Page 56 of 64

You can also use the abstract Sitecore.Form.Web.UI.Controls.BaseControl class that

implements the ControlName and FieldID properties of the IResult interfaces.

The control must implement the IHasTitle interface if you want the control to be iniatilized with title that

you define in the Form Designer.


{

public interface IHasTitle

{

string Title { set; }

}

}

If you would like properties from your control to be available in the FormDesigner you should use the following special attributes:

VisualProperty means that property is displayed in the “FormDesigner”.

Constructors:

public VisualPropertyAttribute(string displayName)

public VisualPropertyAttribute(string displayName, int sortorder)

where

displayName - defines the name of property in the designer

sortorder - sets the position of the sorting in the designer

VisualCategory - sets a category name.

VisualFieldType - defines the type of the input control for the property. If the attribute absents

the property has the EditField input type.

DefaultValue - sets an initial value in the designer.

Localize - defines whether property suppors multiple languages or not.

For example the definition of the following property:

[VisualProperty("Help:", 500)]

[VisualCategory("Appearance")]

[VisualFieldType(typeof(TextAreaField)), Localize]

public string Information

{

...

}

is shown on the picture



Page 57 of 64

The module provides following values of the VisualFieldType attribute:

EditField looks like usual a input control

BooleanField always provides 2 values: Yes and No.

CssClassField offers to choose one of avalable css classes

DateFormatField provides allowed date formats

DirectionField always provides 2 values: Vertical and Horizontal.

SelectionModeField provides 2 values: Single and Multiple.



Page 58 of 64

ListField allows to input items for list controls.

SelectDateField allows to select a date

SelectDirectoryField allows to select a path in the content tree

TextAreaField looks like a big input control

MultipleSelectedValueField works with ListField field and allows to set selected values for list items

EmptyChoiceField works with ListField field and allows to add the empty choice to list items



Page 59 of 64



Page 60 of 64

4.2 Add a new action

All actions must implement the ISubmit interface

public interface ISubmit

{

void Submit(ID formid, List<AdaptedControlResult> fields);

}

The engine transfers all form data to the “Submit” method and the related actions then decide how to handle that data.

The class that implements ISubmit should be registered as sitecore content. Create a new item using

the /sitecore/templates/Web Forms for Marketers/Submit Action template in the /sitecore/system/Modules/Web Forms for Marketers/Settings/Actions folder.

“Class” and “Assembly” fields of created items must refer to the class containing your action.



Page 61 of 64

4.3 Css themes

The module contains a few css themes that can be applied to forms. To change a theme you should go to the forms folder. This item is based on the /sitecore/templates/Web Forms for Marketers/Forms Folder template.

The Forms Folder item has the following fields:

Theme - sets an appearance theme for all forms that are under this item

Color - sets a color theme for all forms that are under this item

If you want to extend the list of available themes you should register it in the content. Under the /sitecore/system/Modules/Web Forms for Marketers/Settings/Meta data/Themes or /sitecore/system/Modules/Web Forms for Marketers/Settings/Meta data/Colors folder you must create a new item. The name of this item must coincide with the name of the file where you defined css styles. This file must be in the sitecore modules/web forms for marketers/themes or sitecore modules/web forms for marketers/themes/colors folder.

You can also change the css class on the field level. For this in the Form Designer you can use “Css Class” property that is available for all fields.

The list of css classes you can extend:

4. Add definition of the css class to the sitecore modules/web forms for marketers/themes/Custom.css class file

5. Create under the /sitecore/system/Modules/Web Forms for Marketers/Settings/Meta data/Css Classes folder new item using the /sitecore/templates/Web Forms for Marketers/Meta Data/Extended List Item template

6. Add the name of your css class to the “value” field of the created item.



Page 62 of 64

4.4 Load items from content tree to list control

Any list control used by the module can read its items from the content tree. T o do this, set the source from which the control will take its items. Use the “Items” property in the “Form Designer” for this:

Click “…” to display the dialog editor for the list items:

The control can read either “source” or “predefined list” items. To select the source you should click “Source”. To input the “predefined list” you should input name of the item to “Input items by hand” textbox and click Add.



Page 63 of 64

4.5 Export to ASCX

Use “Export to ascx” button in the “Form Designer” to convert the form to “ascx” control. First, the code will be displayed.

Click Download to store the code as an .ascx file.

4.5.1 Add ascx control to the page

1. Create a new “default.aspx” page to the layouts\ folder.

<%@ Page Language="C#" AutoEventWireup="true" %>

<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"

"http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">

<html xmlns="http://www.w3.org/1999/xhtml" >

<head runat="server">

<title>Untitled Page</title>

</head>

<body>

<form id="form1" runat="server">

</form>

</body>



Page 64 of 64

</html>

2. Export the form you need to the layouts\ folder using “Export to ascx” button. Use the “forms.ascx” name.

3. Add to the default.aspx page the following changes

<%@ Page Language="C#" AutoEventWireup="true" %>

<%@ Register Src="form.ascx" TagName="SimpleForm" TagPrefix="uc1" %>

<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"

"http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">

<html xmlns="http://www.w3.org/1999/xhtml" >

<head runat="server">

<title>Untitled Page</title>

</head>

<body>

<form id="form1" runat="server">

<div>

<uc1:SimpleForm ID="WebUserControl1" runat="server" />

</div>

</form>

</body>

</html>

Type the http://localhost/layouts/default.aspx url in the browser.

The module does not verify the form works correctly after you add changes into the .ascx file.

http://localhost/layouts/default.aspx

Documents

Web Forms for Marketers - SDN forms/web... · Web Forms for Marketers package, ... 2.1.6 The Web Forms Example Items The module installs some sample forms under /sitecore/system/Modules/Web