Sample Upload Forms in .NET Getting Started with the Upload Forms in .NET

webservices · ‎03-25-2011

This page is intended to help users use the ASP Upload Form sample application.

1. Authentication data

Users will have to set up the API Key, account Username and Password in order to access the Constant Contact resources. The following features are available: add a new Contact (using the full or simplified from), search for a Contact and then add it or update it (both Contact adding or updating is performed using the simplified from), remove a Contact from all lists and unsubscribing a Contact (opted-out Contacts become members of the "Do-Not-Mail" special list).

To set up the authentication data, you need to change the following keys from the web.config file, found in the project:

APIKey: API Application Key and is used to identify the application making an API request
username: Constant Contact Customer's user name
password: Constant Contact Customer's password.

2. Create a New Contact

Users can create a new Contact by filling out the full or the simplified form . For the full form they can provide the following informations for the new Contact: Email Address, First Name, Last Name, Middle Name, Home Phone, Address, City, State/Province, Zip/Postal Code, Sub Zip/Postal Code, Country, Company Name, Job Title, Work Phone, Email Format, Notes, Custom field 1 - 15 and Contact Lists on which the newly Contact would receive occasional email.

Required fields are: Email Address and at least one Contact List should be checked.

For the simplified form they can provide the following informations for the new Contact: Email Address, First Name, Last Name, Middle Name, Home Phone, Address, City, State/Province, Zip/Postal Code, Sub Zip/Postal Code, Country and Contact Lists on which the newly Contact would receive occasional email.

Required fields are: Email Address and at least one Contact List should be checked.

If the contact does not exist or does not belong to “Do-Not-Mail” list, the contact will be added to the chosen lists and you are given the message below.

Note that this only works for a brand new contact that does not belong to any list. If a contact already exists, in any contact list, then you are notified that the contact already exists. To update an existing contact to another list, then you have to go into “Update” mode as described below.

3. Add or Edit a Contact

The Add or Edit a Contact section allows users to write an e-mail address and sign it up into their constant account. After clicking the Sign Up button the written e-mail address is searched in the user Constant Contact account.

If the e-mail address does not exist, then users are automatically redirected to the page that allows them to create a new Contact using the simplified form. On the create new Contact form, the E-mail Address field is automaticaly filled with the e-mail address provided on the Add or Edit a Contact page. You can enter Contact informations in this form and after that, pressing the Add Contact button will create the desidered Contact in your Constant Contact account.

If the e-mail address exists, then users are automatically redirected to the page that allows them to update that Contact using the simplified form. Using this screen, you can now edit each field as well as unsubscribe the Contact from a list by un-checking a list and subscribe to a list by checking it.

The Sign Up form consists of the following web page sources: SearchContact.aspx, SearchContact.aspx.cs, AddContactSmallForm.aspx, AddContactSmallForm.aspx.cs, UpdateContactSmallForm.aspx, UpdateContactSmallForm.aspx.cs and the master page (Master.master and Master.master.cs). The master page contains the menu items and the Constant Contact company logo.

In order use the Sign Up form on your web site you should follow these steps:

add the following files into your ASP web project:
- the ConstantContact.cs file. It should be imported into the App_Code folder of your web project
- the SearchContact, AddContactSmallForm and UpdateContactSmallForm web pages (both .aspx and .aspx.cs files)
- the master page Master.aspx and Master.aspx.cs (optionally, but if you don't add it into your project you need to edit the previous imported .aspx pages, to not be displayed using a master page)
- the ConstantContactLogo.jpg Constant Contact logo (optionally and only if the master page was added)
edit the Web.Config file of the project, by adding the following code:

   1:  <configuration>
   2:      <appSettings>
   3:          <!--API Application Key and is used to identify the application making an API request-->
   4:          <add key="APIKey" value=""/>
   5:          <!--Constant Contact Customers user name-->
   6:          <add key="username" value=""/>
   7:          <!--Constant Contact Customers password-->
   8:          <add key="password" value=""/>
   9:      </appSettings>    
  10:  </configuration>

3. add references to your project for the following assemblies: ConstantContactBO.dll and ConstantContactUtility.dll (from the [BaseFolder]\output\Debug folder).

If you open the SearchContact.aspx web page from your project it should display a content similar with the image above only if you imported also the master page. If you don't import the master page then the SearchContact.aspx web page should not display the menu items and the Constant logo.

The Sign Up button click event handler code is described below:

   1:  /// <summary>
   2:  /// Search button click event handler
   3:  /// </summary>
   4:  /// <param name="sender"></param>
   5:  /// <param name="e"></param>
   6:  protected void btnSearch_Click(object sender, EventArgs e)
   7:      {
   8:          if (!Page.IsValid)
   9:          {
  10:              return;
  11:          }
  12:   
  13:          string[] emailAddress = new string[] {txtEmail.Text.Trim()};
  14:          try
  15:          {
  16:              string nextChunkId;
  17:              // search Contact by email
  18:              IList<Contact> list = Utility.SearchContactByEmail(AuthenticationData, emailAddress, out nextChunkId);
  19:              if (list.Count != 0)
  20:              {
  21:                  // save Contact Id to be updated into Session
  22:                  Session.Add("ContactIdToUpdate", list[0].Id);
  23:                  // redirect to update Contact
  24:                  Response.Redirect("~/UpdateContactSmallForm.aspx");
  25:              }
  26:              else
  27:              {
  28:                  // save the Contact E-mail Address
  29:                  Session.Add("NewContactEmailAddress", txtEmail.Text.Trim());
  30:                  // redirect to add Contact
  31:                  Response.Redirect("~/AddContactSmallForm.aspx");
  32:              }
  33:          }
  34:          catch (ConstantException ce)
  35:          {
  36:              #region display alert message
  37:   
  38:              StringBuilder stringBuilder = new StringBuilder();
  39:              stringBuilder.Append(@"<script language='javascript'>");
  40:              stringBuilder.AppendFormat(@"alert('{0}')", ce.Message);
  41:              stringBuilder.Append(@"</script>");
  42:              ClientScript.RegisterStartupScript(typeof (Page), "AlertMessage", stringBuilder.ToString());
  43:   
  44:              #endregion
  45:          }
  46:      }

After the e-mail address is validated then it is stored into a variable (line 13). The utility method Utility.SearchContactByEmail performs the search and returns a collection of Contacts that exists with the e-mail address the user provided (line 18). If the returned collection is not empty (the collection items count is different than 0) then it means that a Contact with that e-mail address exists and the user is redirected to the update page (line 24). If the returned collection is empty (items count is equal with 0) then there is no Contact with specified e-mail address and the user is redirected to the add Contact simplified form (line 31). In case of REST API communication errors a message is displayed to the user, lines from 36 to 44.

4. List all Contacts

The List all Contacts option will display all contacts that the acount owner have. Edition of a contact can be performed by clicking on the Edit link. The Remove link will remove the contact from all lists. Since the Constant Contact REST API uses chunk data, this page also displayes information using chunks (50 contacts on page). The Next link, below the table, will perform another query that will retrieve from the Constant Contact server next 50 contacts and if you press it again it will display the next 50 contacts. When there are no next contacts, then the link it will be automaticaly disabled. The First link will get the first 50 contacts from the server and you will be able after that to get the next available contacts from the server (if there is the case).

5. Unsubscribe a Contact

Using the update form (simplified form - from the Add or Edit Contact menu item or full form - from the List all Contacts menu item) users have an option to unsubscribe it all lists using the "Unsubscribe me from all lists" check box marked in the image below. Checking this will remove the contact from all lists and add the user to the "Do-Not-Mail" list.

6. Remove a Contact

Using the List all Contacts, users can remove a Contact (removing it from all lists) by clicking the Remove link. The Contact Status will be changed from Active to Removed. Only contacts that are Active can be unsubscribed from all lists. To change the status of a removed contact, click the Edit link, subscribe it to any list(s) and update it's profile. The status of the contact will be changed from Removed to Active.

7. Application class diagram

ASP upload form uses the following types:

Contact class - contains information's about a Constant Contact
ContactList class - contains information's about a Constant Contact List
ContactOptInList class - links a Contact to a Constant Contact List
ContactEmailType enumeration - describes the Contact preferred type of email
ContactStatus enumeration - describes the status of the Contact
ContactSystemList enumeration - describes what kind of system predefined list is a Contact List
ContactOptSource enumeration - type of the Contact opt-in / opt-out source

AuthenticationData class- used to store API Key, username and password for the Constant Contact REST API
Utility class - provides all necesary methods to create a new Contact, update an existing one, search by Contact email address, etc..
ConstantException class - exception thrown if communication with the Constant Contact server occured
ConstantAuthenticationException class - exception thrown if user credentials (API Key, username and passoword) are not valid
ContactComponent class - parse response streams into Contacts, creates entries for creating and updating Contacts
ContactListComponent class - parse response streams into Contact Lists, creates entries for creating and updating Contact Lists

8. Installation guide

In the Release/Setup folder, double click the setup.exe to begin the installation of ASP Net Sample application.

Click the Next button then choose the Site where this application will be installed. Also the Virtual directory name can be specified.

Pressing the Next button will guide you to the Confirmation Step. Pressing again the Next button will start the installation process. After it is completed press the Close button to close the wizard.

Before staring the sample API Key, Username and Password must be defined. To do that, you should edit the web.config configuration file from the %SystemDrive%\Inetpub\wwwroot\UploadContactForm folder.

Note: If you changed the Virtual directory when installing the sample then you should found the web.config file in the following folder %SystemDrive%\Inetpub\wwwroot\[virtual_directory] ([virtual_directory] it should mach the folder you specified for the Virtual directory).

Open the configuration file and edit the following key values: APIKey, username, password.

9. Customize displayed lists

In order to customize the displayed lists you will need to make some changes in the ConstantContact class from the ConstantContact.cs file, found in the App_Code folder of the ASP solution. The prefiltering is disabled by default and to enable it you need to make minor changes. Right now the prefiltering method contains the following code:

   1:  /// <summary>
   2:  /// Prefilter the Contact Lists
   3:  /// </summary>
   4:  /// <param name="contactLists"></param>
   5:  /// <returns></returns>
   6:  public static IEnumerable<ContactList> PrefilterContactLists(IEnumerable<ContactList> contactLists)
   7:          {
   8:              return contactLists;
   9:   
  10:              //// define the collection of lists name do you want
  11:              //string[] prefilterNames = new string[] { "List 1", "List 2", "List 3" };
  12:  
  13:              //foreach (ContactList contactList in contactLists)
  14:              //{
  15:              //    foreach (string contactListName in prefilterNames)
  16:              //    {
  17:              //        if (string.Equals(contactList.Name, contactListName, System.StringComparison.Ordinal))
  18:              //        {
  19:              //            yield return contactList;
  20:              //        }
  21:              //    }
  22:              //}
  23:          }

To enable it you need to comment the line number 8 and uncomment the lines 10-22. If you do that, then the Contact Lists displayed on the forms are filtered and only those that have the name equal with "List 1", "List 2" and "List 3" are shown.

   1:  /// <summary>
   2:  /// Prefilter the Contact Lists
   3:  /// </summary>
   4:  /// <param name="contactLists"></param>
   5:  /// <returns></returns>
   6:  public static IEnumerable<ContactList> PrefilterContactLists(IEnumerable<ContactList> contactLists)
   7:          {
   8:              //return contactLists;
   9:   
  10:              // define the collection of lists name do you want
  11:              string[] prefilterNames = new string[] { "List 1", "List 2", "List 3" };
  12:   
  13:              foreach (ContactList contactList in contactLists)
  14:              {
  15:                  foreach (string contactListName in prefilterNames)
  16:                  {
  17:                      if (string.Equals(contactList.Name, contactListName, System.StringComparison.Ordinal))
  18:                      {
  19:                          yield return contactList;
  20:                      }
  21:                  }
  22:              }
  23:          }

The prefilterNames string array stores Contact List names that you want to display on the forms. If you change the array items, let's say add another one with the name "List 4", then, only Contact Lists that have the name equal with "List 1", "List 2", "List 3" and "List 4" are shown.

10. How-To use it

The [BaseFolder]\ASPSample.sln file represents the Visual Studio 2005 solution project for this application and is composed of three projects: two class library projects (ConstantContactBO and ConstantContactUtility) and the web project itself (ConstantContactBO - provides access to the following .NET wrapper objects: Contact Lists and Contacts;ConstantContactUtility - provides access to utility methods to create a new Contact, update an existing one, search Contact by email, etc).

The ConstantContactBO project consists of the following files: Contact.cs (contains information's about a Constant Contact), ContactList.cs (contains information's about a Constant Contact List) and one class diagram file named ClassDiagram.cd that describes the structure of theConstantContactBO project.

The ConstantContactUtility project consists of the following files: ContactComponent.cs (contains class used parse response streams into Contacts, creates entries for creating and updating Contacts, etc.), ContactListComponent.cs (contains class used to parse response streams into Contact Lists, creates entries for creating and updating Contact Lists, etc.), AuthenticationData.cs (contains class used to store API Key, username and password for the Constant Contact REST API), Utility.cs (provides utility methods to create a new Contact, update an existing one, search by email, etc.) and one class diagram file named ClassDiagram.cd that describes the structure of the ConstantContactUtility project.

The web project consists of the following files:

ConstantContact.cs - this class contains API Key, Username and Password used to acces Constant resources. Also, it contains definition for State/Province and Country
AddContactConfirmation.aspx - Contact added confirmation page
AddContactConfirmation.aspx.cs - code behind of the Contact added confirmation page
AddContactFullForm.aspx - page that allows to add a new Contact using the full form
AddContactFullForm.aspx.cs - code behind of the add new Contact page using the full form
AddContactSmallForm.aspx - page that allows to add a new Contact using the simplified form
AddContactSmallForm.aspx.cs - code behind of the add new Contact page using the simplified form
ConstantContactLogo.jpg - Constant Contact logo
Default.aspx - main page of the sample
Default.aspx.cs - code behind of the main page
ListContacts.aspx - page that allows to list all existing Contacts
ListContacts.aspx.cs - code behind of the list all existing Contacts
Master.master - master page that displayes the menu and the company logo
Master.master.cs - code behind of the master page
SearchContact.aspx - page that allows users to search for an existing Contact
SearchContact.aspx.cs - code behind of the search page
UpdateContactConfirmationEnd.aspx - Contact updated confirmation page
UpdateContactConfirmationEnd.aspx.cs - code behind of the Contact updated configuration page
UpdateContactFullForm.aspx - page that allows to update an existing Contact using the full form
UpdateContactFullForm.aspx.cs - code behind of the update page
UpdateContactSmallForm.aspx - page that allows to update an existing Contact using the simplified form
UpdateContactSmallForm.aspx.cs - code behind of the update simplified page
Web.Config - configuration file that exposes the APIKey, Username and Password used to access Constant Contact REST API.

If you want to import pages from this sample into your web site, you need to:

add the following files into your ASP web project:
- the ConstantContact.cs file. It should be imported into the App_Code folder of your web project
- the desidered web page(s), both .aspx and .aspx.cs files
- the master page Master.aspx and Master.aspx.cs (optionally, but if you don't add it into your project you need to edit the imported page, to not be displayed using a master page)
- the ConstantContactLogo.jpg Constant Contact logo (optionally and only if the master page was added)
edit the Web.Config file of the project, by adding the following code:

   1:  <configuration>
   2:      <appSettings>
   3:          <!--API Application Key and is used to identify the application making an API request-->
   4:          <add key="APIKey" value=""/>
   5:          <!--Constant Contact Customers user name-->
   6:          <add key="username" value=""/>
   7:          <!--Constant Contact Customers password-->
   8:          <add key="password" value=""/>
   9:      </appSettings>    
  10:  </configuration>

add references to your project for the following assemblies: ConstantContactBO.dll and ConstantContactUtility.dll (from the [BaseFolder]\output\Debug folder)
customize the page as you want (e.g. change some displayed text, remove unwanted fields).