Kentico CMS 6.0 Developer's Guide

Modifying code of standard web parts

Modifying code of standard web parts

 Previous topic Next topic Mail us feedback on this topic!  

Modifying code of standard web parts

 Previous topic Next topic JavaScript is required for the print function Mail us feedback on this topic!  

This topic explains how you can create a copy of a standard web part and customize its behavior by modifying its code.

 

The following example uses the Forms -> On-line form web part as its base. It shows how you can send a custom e-mail when a form is submitted and display a confirmation message. Please note that this is only for demonstration purposes. There is a much easier way to set up notifications or autoresponders for on‑line forms through the built‑in functionality of the Forms module.

 

1. Create a copy of the On-line form web part in Kentico CMS. Go to Site Manager -> Development -> Web parts and select the Forms -> On-line form web part from the tree. Click the CloneReport Clone web part action and enter the following values:
 

•Display name: Form with custom e-mail

•Code name: FormWithEmail

•Category: Forms

•File name: BizForms/formwithemail.ascx

•Clone web part files: yes (checked)

 

Click OK. The system will create a copy of the existing web part using the new name and also copy the code files (ASCX and CS).

 

2. Now we will make the modifications to the web part. Open the web project using the WebProject.sln (or WebApp.sln) file in Visual Studio and edit the ~/CMSWebParts/BizForms/formwithemail.ascx file.

 

3. If you installed Kentico CMS as a web application, the file will not be visible right away, since it is not included in the project. In this case, click the Show all files button at the top of the Solution Explorer, right click the formwithemail.ascx file in the BizForms folder and select Include in Project. It is also necessary to manually convert the control to the web application format. You can do this by right clicking the file again and choosing the Convert to Web Application option. This will generate the necessary designer file for the control. You may skip this step if you are using a web site project.

 

4. Switch to the Design tab and drag and drop a Label control onto the page. Set its ID to lblConfirmationMessage and clear its Text property.
 

5. Next, edit the code behind file and locate the viewBiz_OnAfterSave handler, which is executed every time the form is saved. Insert the following code after the default content of the method:
 

[C#]

 

void viewBiz_OnAfterSave(object sender, EventArgs e)
{
 
...
 
  // Creates a new e-mail message.

   CMS.EmailEngine.EmailMessage msg = new CMS.EmailEngine.EmailMessage();
 
   msg.From = "mail@localhost.local"; // Enter any valid e-mail address.
   msg.Recipients = "mail@localhost.local"; // Use a valid e-mail address that you can access.
   msg.Subject = "Custom form e-mail";
   msg.Body = "The value of the FirstName field: "
               + CMS.GlobalHelper.ValidationHelper.GetString(
               viewBiz.BasicForm.GetDataValue("FirstName"), "N/A");
 
  // Sends out the custom e-mail notification.
   CMS.EmailEngine.EmailSender.SendEmail(msg);
 
  // Sets the confirmation message shown in the label.
   lblConfirmationMessage.Text = "The e-mail has been sent.";
}

 

This code creates a new e‑mail message, sends it out and adds text into the confirmation label. You can notice how the content of the e‑mail dynamically retrieves a field value from the current form by using the BasicForm.GetDataValue(string fieldName) method, which may be called through the corresponding property of the BizForm control. Fill in valid e‑mail addresses into the code to be able to try out the example.

 

Save all changes. Remember to Build the project if it is installed as a web application.
 

6. Go to CMS Desk -> Content, choose the Home page, switch to the Design tab and add the Form with custom e‑mail web part to the Main zone zone. Set the Form name property to the Contact Us form using the Select button. This form should be available by default if you are working with the sample Corporate Site, and it includes the FirstName field used in the custom code.
 

7. Finally, open the live site and view the Home page. Enter some values into the form and submit it. You will see the additional confirmation message ("The e-mail has been sent.") and the specified address will receive the e-mail.

 

You have seen how to create a customized version of a standard web part. Using the same approach, you can modify the ASPX markup or code behind of any of the default web parts in order to alter their functionality to fit your specific requirements.