How do I Create a Custom Form for HomeGauge?

PDF Form Creation for HomeGauge Software

A form in HomeGauge consists of three parts:

• A PDF file that will have data merged into it
• An HTML file that is used in the HomeGauge software to enter data
• A file (the .HGF file) that ties together the fields between the PDF file and the HTML file

When a form is filled out in HomeGauge, the data is saved much like in a HomeGauge report. When the Print/Preview button is pressed on the Forms screen, or a report that has a form attachment is printed or uploaded, the data is then "merged" into a PDF file and saved in the current report folder. The merging of data can save you time by using the same info from the report where applicable. During the merge, data is pulled from the on-screen HTML form that the user has filled out, and inserted into the proper place(s) in the PDF form. The third file mentioned above defines the type of data for each field and where it should go in the PDF file.

Creating a form for use in HomeGauge thus requires several steps and should only be attempted by advanced users with knowledge of HTML and PDF editing. Note that in order to edit the PDF file to define data fields, you must also have the full version of Adobe Acrobat, not just the Acrobat Reader or other PDF viewing software. Most users would be better served by calling or emailing HomeGauge to have their custom form(s) created by our support team.

Creating A New HomeGauge Form

Creating the PDF

The first step in creating a form is to create or edit the PDF file. If the form is a state pest or mold form, the PDF is normally available from a state agency. Other forms, such as a pre-inspection agreement, must be created by hand if not already in PDF format. When the layout of the PDF file is complete, fields must be placed in the PDF form to receive data. These are called "form fields" and can be inserted by Adobe Acrobat (not Reader, as mentioned above). Note: some PDFs may already have form fields in place, but this is very uncommon. Also note that the instructions below regarding menus, etc., refer to Adobe Acrobat, not the HomeGauge software.

To create a form field, select "Edit Form In Acrobat" from the Forms menu in Adobe Acrobat. Note: do not select "Create New Form..." from the Forms menu - this will create a form with fields, but it will do so in a way that is notcompatible with HomeGauge. When you select "Edit Form In Acrobat", Acrobat will go into form editing mode and the Forms toolbar will appear so you can insert different types of form fields. The two types of fields supported for a HomeGauge form are text fields and checkboxes. To place the field in the PDF, click on the checkbox or text field button on the Forms toolbar; if you do not see the Forms toolbar, select Tools Forms Show Forms Toolbar.Note: you can also select Tools Forms and select Check Box Tool or Text Field Tool from the sub-menu.
Then click and drag to place the new field in the appropriate place in the PDF, using the lines, boxes, etc. in the PDF as a guide.

After the field is placed and sized as needed, right-click on the new field and select "Properties...". A new field will have a default name, such as "Text1" or "Check Box 2", but you may want to change the name to something that indicates its function, such as "InspectorName", etc. For text fields, most other properties should be fine as is, unless you want a text field that spans multiple lines - this is set via the "Multi-line" checkbox under the "Options" tab of the Properties window.
For checkboxes, you will probably need to go to the "Appearance" tab of the Properties window and select "No Color" for the Border Color and Fill Color. This is because you normally only want to see the checkmark - the "box" is usually part of the background of the PDF. Note: make sure you save your PDF periodically to avoid losing any work.

After placing, sizing, and setting properties for the PDF form fields, you should then select "Edit Form In Acrobat" again (if it is checked) in the Forms menu in Acrobat (or click the Preview button on the Forms toolbar). Now you can enter some text in your text fields and make sure they are lined up and sized appropriately; you should also check your checkboxes and make sure they fit nicely with the background PDF. Select "Edit Form in Acrobat" from the Forms menu (or click the Edit Layout button in the Forms toolbar) to toggle back and forth between editing and previewing the appearance of the form fields. Once you have the fields set up as you like, it's time to create the HTML form that will be used in HomeGauge.

Creating The HTML Form

For forms you wish to use with the Android HG Companion, we recommend you format the HTML in a responsive/mobile friendly way using custom CSS or Bootstrap.

The HomeGauge software loads a separate HTML file to allow editing of a form. This file can be created in any way you like; the only requirement is that the form fields have the same name(s) as the fields in your PDF file. One place to start is to load your PDF in Acrobat and select File Export HTML to have Acrobat export an HTML file. Depending on the layout and complexity of your PDF, the resulting HTML may or may not end up being useful. At HomeGauge, we try to create HTML files that at least somewhat resemble the PDF files in appearance so that they seem familiar to (for example) a pest inspector, but this not strictly necessary.

Once you have an HTML layout, then you need to create HTML form fields to match the fields in the PDF. Once again, text fields and checkboxes are normally all that is required. However, note that in HTML, a single-line text field and a multi-line "textarea" are two different types of fields. You must make the "id" attribute of the HTML fields match the name(s) of the fields in the PDF. Note: these instructions assume at least some knowledge of HTML editing - a discussion of how to create an HTML field and set its attributes is beyond the scope of this document.

Creating The HGF File

The third file that needs to be created is an XML file that links the fields of the PDF and HTML files and defines each field's type. It has a .HGF extension (for HomeGauge Form). This file also defines the name and description of the form as displayed inside the HomeGauge software. It has the following format:

The Name and Desc tags define a name and description that will show up in HomeGauge when you insert a form.Note: the description is also used as the title of the attachment if a form is attached to a report. The PDFfile and HTMLfile tags define which PDF file and HTML file are used for this form. Each block defines one field in the form. The FieldName tag defines the name, which must be the same in both the PDF and HTML files. The Type tag defines the type of field - a list of types is below. Some fields can be pre-loaded with default data; for example the "inspector" field above is preloaded with the inspector's name. Also note that the default values can be changed at any time from within HomeGauge by using the "Set Defaults From Current" button on the Forms screen.

Below is a list of types for the Type field above. See the following section for information on how to make sure date, city, zip, etc. are handled correctly inside HomeGauge.

Interactive Form Elements In The HTML

Fields set to a type of 1-8 can use the interactive controls inside HomeGauge to set values - like the city or state dropdown lists on the Customer and Report Info screens for example. In order for this to work, the correct type from the table above must be set for the field in the HGF file, and the following block of code must be present in the head section of the HTML file:

Dates, Times, and Auto-Comments

Date and/or time type fields need to have a certain class: "datestyle" for date fields, or "timestyle" for time fields. When this class is set on the text fields in the HTML, an interactive calendar or time picker is displayed when the field is clicked from within HomeGauge.

A text field where an auto-comment can be inserted needs to have the "editstyle" class. Without this class, double-clicking in the field, or clicking the Insert Comment button on the form screen in HomeGauge, will have no effect.

Images

Images can be inserted into forms. In the PDF file, insert a hidden text field with a name like "Image1". Place the text field so that the upper left corner of the field is where you would like the upper left corner of the image to be. In the HTML file, insert three buttons near where the image should appear; the class of these buttons must be "imgbuttonstyle" and they must be named according to the field inserted into the PDF. Using the "Image1" example above, the buttons would be called "SetImage1", "EditImage1", and "ClearImage1" (i.e. their "id" attribute). These buttons will allow the user to set an image at this location, edit the image, or remove the image. In the .HGF file, the only field that needs to be added is the field added to the PDF ("Image1" in the example above), with a type of 10. Note: only the buttons mentioned above need to be added to the HTML file; no other fields are necessary.

Signatures

HomeGauge forms support up to two signature images. Even though they are images, and thus could be handled as above, they can also be set up as signature-specific images, which saves some time when filling out the form in HomeGauge.
To add a signature image field, add a hidden text field as for an image to the PDF. In this case the position and the size will be used; place the field carefully so that it fits within the signature area on the PDF. Then simply add a field block to the .HGF file with the name, and a type of 11. Depending on the user's HomeGauge form signature settings (available in HomeGauge at Options Forms Options), one or two signature are automatically inserted when the form is merged. Note: nothing needs to be added to the HTML file for signatures.