Once you are done reading this walkthrough, you'll know the basics of H2O and will be able to quickly setup new forms in minutes.  This walkthrough does not go into most of the features in H2O in order to keep this simple for those just starting out with H2O.  For styling, workflow, logic, custom views and other advanced features in H2O please review the other articles on this site.

We will create a simple form with two fields to collect a persons name and email address.  In order to start this, you must have H2O installed.  Instructions on installing H2O are below.  Skip the install details below if you have already installed H2O.

Installing H2O
To reduce the file size of installs and to consolidate resources, common components used in the OnyakTech modules are now installed using the new OnyakTech Library. This library is installed the same as any other module. Each release of this library is versioned by a name, the first release is named Q3. If a module requires the Q3 OnyakTech Library, you will see this referenced in the name of the install. Ex: SigmaPro Draconis v7.0.53 (Q3).zip.

Using the Module Definitions page in the Host menu of DotNetNuke, install the core H2O module, H2O Forms Designer and the OnyakTech Library modules.  If you are upgrading, install the new releases over your existing installation.  The steps to install a module in DotNetNuke is below:

  1. Make a backup of your DNN installation and database.
  2. (Optional) Verify your web.config (see note below) for potential timeout issue
  3. Log in as host on your DNN installation
  4. Go to ‘Module Definitions’ under the host menu
  5. Select ‘Install New Module’ from the module list’s menu
  6. Browse to and select the H2O xx.xx (Q3).zip and click upload.
  7. Wait for all processing to finish.
  8. The web page you’re looking at should show you an installation report. Scroll down this report to check if there are any red text blocks signifying there were errors during install. If there were "time-out" errors, read the information below and try the install again.  If you continue to have problems with the install, contact Support from www.OnyakTech.com
  9. Repeat the install process for the OnyakTech Q3 Library and the H2O Forms Designer modules.  All other modules are optional.

Request Time-Outs and Large File Uploads

If you get "Request Time-Out" errors during the installation, modify your web.config as shown below. (This is not very common and if you need additional help with this, please contact OnyakTech Support from www.OnyakTech.com.) You will want to increase the executionTimeout attribute.  If the file you are uploading is over 4MB, you will want to increase the maxRequestLength attribute as well.  Most OnyakTech installs are below 4MB.

maxRequestLength
Specifies the limit for the input stream buffering threshold, in KB. The default value is 4096 (4 MB).

executionTimeout
Specifies the maximum number of seconds that a request is allowed to execute before being automatically shut down by ASP.NET.  The default in .NET Framework 2.0 is 110 seconds. In the .NET Framework 1.0 and 1.1, the default is 90 seconds. 

 

Creating Your First H2O Form
There are four steps to creating your first form in H2O.  Create your form, setup a Team to administer the form, create your project to organize form related data & security and then finally configure the core H2O module to present the form to the user.   If you are new to H2O and want to create a form to collect and store data, follow the steps in Method 2 below and ignore Method 1 until after you have mastered form creation with H2O.

DO NOT place the H2O Forms Designer and the H2O core module on the same page.  These modules will not function properly if placed on the same page and the H2O Forms Designer should be secured to administrators or form designers ONLY.   The core H2O Forms Designer module is used to create and modify H2O Forms.  The H2O core module is used to present your forms to your users.

Create Your First Form

You can create forms with the core H2O module as well as the new Forms Designer.   However, it is recommended to use the new Forms Designer for form creation.  The forms creation process in the core H2O module will eventually be removed in future releases of H2O.  Ok...let's get started...

  1. Add the H2O Forms Designer module to a page secured page allowing only you or your team of H2O admins access.  The Forms Designer does not present information to the user, it's only purpose is to aid in form design.
  2. Click the New Form image near the top of the module. Screen shot of this is to the right.
  3. After the New Form popup loads, enter a name for your form and description.  The Author field is automatically populated with your name.  The Author field is displayed in the Forms list and when someone uploads your form onto their site.
  4. You may leave the Form Rows and Column fields as is for now and click the Create New Form link at the bottom of the page. 

After you click the link to create the form, you will be presented with a screen that provides the next steps - ( Click Here to view this screen )  The next step is to add controls to your screen by clicking on the Edit link in the Forms list.  If you don't see your form, refresh the page.

  After you click on the link to open the details of your form, you will see the screen shown to the left.   The next step is to add controls to your form by following the steps below:
  1. Click Edit Form Controls
  2. The Control Editor will now open and you can add/edit your controls.
  3. The first control we are going to create is a text box for the user's name.
  4. Type "Your Name" into the Name field.
  5. Select "TextBox" from the Type list that contains a list of controls you can add to your form.
  6. We want the user to be required to enter this value, so check the Check to Require Data Entry option.
  7. We also want this control enabled on the form, so check the Enabled option as well.
  8. Next, we will need a label for this control as well.  H2O will create one for us if we check Create Label To Match option.  Check this option.
  9. Now click Update Control Info
  10. Your form should now have two controls.  The controls on your form are listed in the first drop down box at the top of the screen.  Click here to see what it should look like.

We also want to add a control to obtain the user's email address and then send them a copy of the form results once the form is saved.  To do this...

  1. Click Add New Control
  2. Type Email into the Name field
  3. Select Email Response from the control Type list.
  4. Check the option to Enable and Require Data Entry
  5. We should also add a ToolTip to this control, you will see the custom H2O Tooltip displayed later in this walkthrough.
  6. We also want to make sure people enter valid email addresses, to do this we will enter the REGEX value to validate an email address into the Validation field.  Don't worry, you don't need to understand REGEX.  You can obtain REGEX validation strings from www.RegExLib.com.
  7. Finally, click Update Control Info to add this control to your form.

Now you're ready to drag the controls around the form designer to place them where you want them to be displayed.  Close the Controls window and click on Form Layout Designer.  (Click Here For Help)   Your form should look something like this (click here).  

To move the controls around the form, click on the bar at the top of the controls container and drag it to another location on the form.  Once you are done, your form might look something like the image to the right.

Now that your form is created, we need to tell H2O how to present the form to the user.  There are two ways to present your form to the user. 

  1. Form Only:  This method displays just the H2O Form you specify.  Data can not be stored into a table or associated with a project.  Use this method to initiate a work-flow (that will eventually post form values to a table or to another instance of H2O that is setup to handle project data) or display a content management form, redirection of users based on role, etc.
  2. Project Related:  This method allows you to use the Project related features of H2O and store data directly into a form.   Note that you can still post data into a form using the Form Only method if your form uses a Link control that posts to a URL and you use the URL given to you from the Form Detail screen that is directly associated with a table.  If you use this method, you can have H2O redirect the users to a page once the data has been stored by entering the URL into the Form Details screen of the Form that is associated with the table.  It's the last field named "Post Redirect URL" in the Form Details screen.  This option is only visible if your form is associated with a table.

Method One: Functional Form Only (Dashboard, Charts, Redirects Based on Roles, etc)

  1. To display just a form, click on Edit H2O (in the core H2O module) from the module menu
  2. Click on User Interactions
  3. Check the Form Only option and select the form you want to display - Click here for a screen shot
  4. Click Update

At this point, you're all set and there is nothing else to be done.

Method Two: Project & Data Entry Forms

It's not required, but to make life easier, add an instance of the core H2O module to an admin secured page.  The default settings will give you full access to all projects and data entered into H2O throughout your portal.  Then add another instance of H2O to display the form we just created to the user.

We will configure H2O to present just the form to the user and then redirect them to a "Thank You" page once they save the form.   To do this, follow the directions below:
  1. The first thing we should do here is setup a Team to contain a list of people who are responsible for the data entered.  In this case, it's our Sales team.  To create a new Team, click on Teams.
  2. Next, click on the Create New Team link
  3. The Team Setup page should now be displayed.  Type "Sales" for the Team Name, select the Administrators role and give your team a description.
  4. The Assigned Role is used to make it easy to import users into a Team.  It's not required.  If you have selected a role, click the Sync Team With Roles link.  Click here for a screen shot.
  5. Your team is now created.

Teams are available to be assigned to multiple projects.  You do not need to create a new team for every project.

Feel free at this time to navigate around the Teams editor to familiarize yourself with the available options.  You can add individual users to a team by clicking on the View Team link the main Team screen.  Here is a screen shot.  You can also define a team member's skills, cost per hour and more from the Team Members detail screen by clicking on the View link from the Members list (the screen made visible after clicking View Team).

If you are using forms in H2O that don't need a project ( such as a form used to display HTTP Post or Query String postings directly into a table in your database, or a form that simply redirects a user to another page if they are in a specific role, or if you want to display multiple forms creating a Wizard type step-through with the last form posting to a project) you can bypass the steps of creating a Project and Teams. 

H2O gives you the ability to create a simple form and display just that form for data entry.  But it also goes far beyond that point if you should need it.  H2O also stores the data a the Portal level so that you can display a form in different ways throughout your site (for example, one instance may be for your users to complete the forms and another for your sales team to approve a form which then is posted to yet another instance of H2O configured to display the third form).  You can process an unlimited number of steps in your workflow through one or more instances of H2O, it all depends on your site setup and what you want people to see in other modules on the same page. 

Projects in H2O are used to organize form data into groups, segregating completed forms from each other and allowing the above scenario to be easily setup.  Projects also give you security to grant specific users or Role access to one phase (or project) of your workflow.  This access level grants email notifications to multiple team members, ability to view the history of changes to a single form and to add comments to a form that only Team members can view.

 

The next step is to create a project (if you require it).  To do this, follow the steps below:
  1. Click on the Projects icon in the toolbar
  2. Click Create New Project
  3. The New Project Wizard will start...on the first screen type a name, description and select the project administrator.  Screen shot of this is to the left.
  4. Click Next
  5. In Step 2, select the form you want to control with this project and then click on the Activate link to assign the form.
  6. Step 3 is to assign Teams.  You can assign multiple teams by clicking on the Team in the list provided and then the button to assign or remove teams to the project.  Click here for a screen shot.
  7. You have completed the basic project setup and the success screen is displayed.

 

Now you have a form, a team and a project. Your form is now ready for full production use.  Unless, you need to display your form to users for simple data entry - like a custom DotNetNuke Portal Registration form or to collect feedback.  In these situations, you won't want your users to see the toolbar with access to all of your projects or to even view the completed items.  So now we'll add another instance of H2O to your site where you want your users to complete form entries.

  1. Add a new instance of H2O to your site.  After you do this, H2O will be preset with full security options and may look like the image here. (Pointed out in this image is the project we just created)
  2. To edit the display options for H2O, click Edit H2O from the module menu.
  3. Displayed at this point is the main Edit menu of H2O At the bottom of the screen you will notice that you can download and upload configuration files.  These are files that store the settings you make in the Edit H2O menu option.
  4. Click User Interactions
  5. Check Enable Quick Entry
  6. Type the URL you want users to be redirected to after they complete the form. 
  7. Click Update at the bottom of the page.
  8. Now click Visual Settings
  9. Check Hide Stats and Display Comments and Files Only.
  10. Click Update

 

H2O should now display your form with a Save link.  Hovering over the "Your Name" text box will display the H2O Tooltip we entered while creating the form.  If your form looks different, that is because I have updated the Label controls to a width of 80 and changed the text displayed in the lblYourName control.

Now that you have everything in place, you may want to view the data your users have entered.  To do this, go back to the instance of H2O you created initially for administration purposes.  Click the project icon to view the records created with this form.  You can group, filter and sort the data entered using the data grid provided.  Screen shots are below:

That's it for the basics.  You are now ready to move into more advanced features of H2O.  If you have any questions, please visit the Members Forums on www.OnyakTech.com, submit a support request or call 1-866-921-7235


Copyright 2009 by OnyakTech
Privacy StatementTerms Of Use