How does Form portlet work?

From Sense/Net 6.0 Wiki

[edit] What is Form Portlet?

Form portlet is responsible for displaying form lists for submission on portal pages. With form portlet you can get user responses, survey users. To use a form portlet you have to create a form list first. A form list defines the fields and other settings of the form. Think of it as a form template. When you set up the form list, you can request email notifications when a form got submitted, you can define the template of this e-mail, etc. You can also export the results if it's necessary.

Features:

• User defined field sets (lists - templates)
• Form submissions are saved to the content repository (Sense/Net Content Repository)
• Information submitted through forms can be sent also via email
• Submissions can be exported (xml, csv)

If you want Form Portlet to display a form or survey, you have to create a Form List first if the Sense/Net Content Repository. (A form list is special list type.) Then you have to copy the path of the form list to Form portlet's form list property.

In this picture below you can see a the edit view of Form titled as Survey.

[edit] How to insert Form portlet to a page?

If you want your form to be submitted by the visitors/user of your portal, you have to make it accesible for them - not surprisingly. This section will guide you through the process of creating, setting up and placing Form portlet on your portal's page.

1. First of all you have to log in to your portal as an Administrator.
2. Then launch Content Explorer using the method discussed in another namespace.
3. You need to create a Form type of content now. For the sake of transparency of your portal's file system we recommend you to store forms in a disntinct section of Sense/Net Content Repository. Select a folder in the tree-structure on the left of Content Explorer.
4. On the toolbar click New Content.
   
   
   
   
5. From the displayed dialog window choose New Form. New Form dialog box appears.
   
   
   
   
6. Most of the fields of this dialog box speak for themselves, you can add the Name of the form(it will appear in the Sense/Net Content Repository, and Content Explorer will create a folder with this name on the location where you created the form. This folder will contain all the data of the forms users/visitors submitted), the Title and Description of the form (they will be visible on the page where you place the form), you can add the AfterSubmitText (this text will be displayed after submission), and you can add emails where the submitted forms will be sent to.
7. But the most important field is ListerDefinition. Let's say a few words about it. In this field you can define the looks of your desired form, you can configure the fields in a very similar way to what you can see it under the What is a Content Type Definition? namespace. Here is an example for a simple Form's ListerDefinition:

<?xml version="1.0" encoding="utf-8" ?>
<ListerType xmlns='http://schemas.sensenet.hu/SenseNet/ContentRepository/ListerTypeDefinition'>
  <Title>Newform</Title>
  <Description>NewForm</Description>
  <Icon>Newform</Icon>
  <Fields>
	<ListerField name="#Title" type="ShortText">
	  <Title>Title</Title>
	  <Description>Title</Description>
	</ListerField>
  </Fields>
</ListerType>

[edit] E-mail addresses of submitters and reply e-mails to them

There is an option to gather e-mail addresses from those who submitted the form, and then send them a reply e-mail (saying thanks for submitting the form, or something like that). To do this you have to:

1. Create a ListerField (ListerFieldName could be something like "#Email" or "#SubmitterEmail") on the form to where submitters can paste their e-mail addresses.
2. Then you have to add the name of the field specified among lister fields containing the submitter's email address to the field called EmailField. (You will paste the name "#Email" or "#SubmitterEmail" given the previous examples)
3. You can also specify the e-mail address of the e-mails the system will send out. This e-mail address will appear as the e-mails were sent from this address. To do this, you have to fill out EmailFrom field as well.
4. In the EmailTemplate field you can add the template of the after-submit e-mail sent out by the system to the submitter. By default the template of this notification email is the same as the one sent to the recipients given in the email list above. Other text messages can be inserted using the "{0}" string.

[edit] ListerFields and Content Field Types

The main difference between configuring Content Type Fields and configuring fields of a Form is that you have to use this line in the xml of the Form fields (instead of the one you got used to with Content Field Types):

<ListerField name="#[FIELDNAME]" type="[FIELDTYPE]">

Where the presence of the hashmark (#) is compulsory before the name of the fieldname in the case of a Form field.

Click the link to learn more about the available Field Types you can use when configuring Form portlets.

Ok, when you are done with this, save this form by clicking Save.

[edit] Placing Form Portlet on the page of your Portal

Now that you have created your Form, it's time to place it somewhere on your portal. Please follow these steps to do so.

1. Make sure you are logged in to your Enterprise Portal as an Administrator.
2. Navigate your browser to the page you want to add Portlet to. Click the PRC icon in the upper right corner of the page
   
   to display the PRC.
   
3. Click Add Portlet. Add Portlet dialog box will be displayed, with miniature views of the available portlets.
4. Select Form portlet, then select the desired area of the page by selecting it from the drop-down menu. Then click Add.
5. Form Portlet is added to the desired are of the page. Now you need to tell the portlet which form it has to display. To do this click Edit Properties icon (represented by a pencil in the upper rigt corner of portlet).
   
   
   
   
6. When the dialog box appears you need to add the path of the Form in the Sense/Net Content Repository to the field FormPath. Then click OK.
7. The Form you created earlier is now displayed on the page. Feel free to try it by submitting it.
   
   
   
   

When a Form is submitted, the results get stored in the Sense/Net Content Repository in the folder where you created the New Form, so you can view them anytime.

[edit] Setting the permissions of the form

After you have created your Form, you might want to let users to access it. To do this. you have to apply special permissions settings to it, with breaking the the Security Inheritance.

1. Log in as an Administrator to your portal and open Content Explorer.
2. Select the form file you want to add special (not the one inherited from its parents) permission settings to, by clicking the form in the middle section.
3. On the right section of Content Explorer's interface click Security tab. The applied security settings will be displayed. You can view the permission settings of the respective groups or individual users by clicking the View button in line with their names.
   
   
   
   
4. If you want to apply different security settings to the form, click on Add new security settings button, and set whatever security settings you need. To do this, you need to specify the name of the user or group whose settings you want to modify.
   
   
   
   
   1. Select the search type from the drop-down menu (User, Group, Organizational Unit).
   2. Enter the name of the user or group to the field "Filtering expression", then click Search button.
      
      
      
      
   3. You can modify the permission settings of more users or groups at once, you need to use the "arrows" to move items from the "Search result" field to the "Selected user or group" field. You might want to let visitors to submit your form, in order to do so give them AddNew permissions.
   4. Now you can apply the security settings (listed below the fields) to the items selected. When you are finished, click Add.
   5. The new security settings will be visible on the bottom of the list on the security tab. You can edit these settings whenever you want.

[edit] How to create custom views for a Form

When you create a Form, you might possibly run into the problem, that the default view of a particular field is not the one that you were looking for. In this case you'll need to create a custom view for that field, to display data in a way that you need. With this method you can change a Form's field control, for example from drop-down to radio buttons.

To do such a thing, you need to follow these steps:

1. You have to be logged in to your Portal as an Administrator.
2. Navigate Content Explorer to the Content View used by the Form you want to edit.
   
   
   
   
3. Create a copy of the Browse.ascx (let's name it Browse2.ascx).

<%@  Language="C#" AutoEventWireup="true" Inherits="SenseNet.Portal.UI.SingleContentView" %>
<div class="snForm snClearfix">
     <h2 class="snFormTitle">
        <%= (this.Content.ContentHandler.Parent as SenseNet.Portal.Portlets.ContentHandlers.Form).Title %>
    </h2>
    <div class="snFormDesc">
        <%= (this.Content.ContentHandler.Parent as SenseNet.Portal.Portlets.ContentHandlers.Form).Description %>
    </div>
    <div class="snFormFields">
        <sn:ErrorView ID="ErrorView1" runat="server" />
        <sn:GenericFieldControl runat=server ID="GenericFieldControl1" ListerFieldsOnly="true" />
    </div>
    <div class="snFormComment">
        * compulsory field
    </div>
    <div class="snFormButtons">
        <asp:Button ID="BtnSend" CssClass="snSubmit" runat="server" CommandName="save" Text="Send" EnableViewState="false" OnClick="Click" />        
    </div>
</div>

4. Delete the line of GenericView from it, and replace it with the new FieldControls for each fields. You have to make sure, that every control has a unique ID.

5. When you are done with this you have to add this newly created Browse2.ascx to the Form portlet's properties, to the Content View Path field.