Create a Template Package Upload Page for Your Host Application

Template authors create and enable templates for use with HotDocs Cloud Services; however, your host application is ultimately responsible for storing and managing the templates that the template authors produce, as well as for making those templates available to end users. Therefore, you need to provide a way for template authors to upload their templates and other files to your host application.

You can choose any upload process your organization and users find workable, including any custom process you want; however, best practice is for to you implement a template package upload page as part of your host application. This approach simplifies uploading templates for template authors because it enables template creators to upload ("publish") their templates directly to your host application using the HotDocs Developer cloud upload plug-in.

An Upload Page is an HTML Form

The HotDocs Developer cloud upload plug-in uses a web browser control embedded within a HotDocs window to upload a template and any associated supplementary files (component files, inserted templates, graphics files, etc.) as a single template package. To enable this functionality, you need to provide the URL of your host application's upload page to anyone wanting to upload their templates to your host application. The upload page you create needs to contain an HTML form called HD_Templates_Upload_Form.

In order to complete an upload, your upload page's HTML form needs to implement two (three when uploading a template using HotDocs Developer 11) required fields. In addition, there are several optional fields you may find useful to facilitate your host application's interactions with HotDocs Cloud Services. These required and optional fields are each described under Creating Your Upload Page, below.

Workflow for Uploading a Template Package to Cloud Services

The interactions between HotDocs Developer and your host application's upload page flow as follows:

  1. When a template creator/publisher provides the URL for your upload page to the HotDocs Developer cloud upload plug-in's embedded web browser control, your upload page loads within the web browser control. While it loads, the cloud upload plug-in searches for, and then interacts with the elements of the HTML form within the HTML of your upload page to enable the template package upload. The upload plug-in also enables the transmission of certain metadata elements associated with each template.
  2. The HotDocs Developer upload plug-in populates your upload page by extracting the needed information from the library entry, the component file (.cmp), and the component manifest file associated with the template(s) in the template package (zip) file to be uploaded.

  3. The fields in your HTML that you have set to be visible are modifiable by the person uploading the template. For instance, if you make the template title and description fields visible, the person uploading the template may choose to modify the template title or the template description. The person uploading a template then uploads the template package to your host application's web server in accordance with the instructions you provide in your upload page.

  4. Details about the template are stored in the SQL database or XML files you have set up. Your web server can make calls to the Cloud Services web server to display web-based interviews and to assemble a document from the answer files generated.

Creating Your Upload Page

When you create your upload page, the first thing you need is a location (a URL) where the HotDocs Developer cloud upload plug-in can access and load your page into the plug-in's web browser control. You then create an HTML page at this URL; this is your upload page.

Required Fields

In order to successfully upload a template package to your host application, the HotDocs Developer cloud upload plug-in requires that you name your upload page's HTML Form HD_Templates_Upload_Form. You must also implement a field called HD_Template_Title<number>. In addition, if you want those using HotDocs Developer 11 to use your upload page, your form must also implement HD_Template_UploadItemType<number>. These required fields are described more fully below. The field suffixes are zero (0) based indices and take the following form <0,1,2,3>.

Plug-in Interactions and Field Definitions

When initiating a template package upload, the HotDocs Developer upload plug-in adds a parameter called HD_NumberTemplates to the query string sent to your upload page's location. This parameter contains the number of templates the user intends to upload.

You can design an upload page to display zero, one, or multiple sets of upload controls. If your upload page displays zero sets of upload controls, the upload plug-in simply ignores the page. If your upload page displays one, the upload plug-in expects the HD_Template_Title<number> above to be 0, and the plug-in populates the fields it finds on your form. If your upload page displays multiple sets of upload controls, these should be numbered beginning at 0 and incrementing by 1 for each additional upload field.

If the user has chosen to upload multiple templates, these will be loaded serially. If the upload page supports multiple uploads (say five), and the user uploads more than five, the upload page loads five, then waits for a submit event to fire. When the submit event fires, the upload page loads again and uploads another five until all templates have been uploaded. If the upload page supports only one template upload at a time, then the upload page uploads one template at a time and after the submit event fires, opens again to accept the next template. The upload page does this as many times as needed, until each template has been uploaded.

As mentioned, your upload page loads in a web browser window controlled by the upload plug-in. Each time the page loads in that window, the upload plug-in inspects your upload page's HTML and creates the following interaction and upload flow:

  1. If the upload plug-in finds an HTML form with an ID of HD_Templates_Upload_Form in your upload page, and that form's enctype attribute is set to multipart/form-data, the upload plug-in attempts to use that form to upload the number of templates specified in the HD_NumberTemplates query string parameter.

  2. The  upload plug-in then searches for a text field on the form called HD_Template_Title<number>. If the upload plug-in finds this field, the plug-in populates HD_Template_Title with the title of the template (escaped by replacing < and > with &lt; and &gt; respectively). If the upload plug-in does NOT find this field, the plug-in assumes the currently loaded upload form cannot accommodate any more templates or library items and the upload fails.

  3. Once the upload plug-in finds the HD_Template_Title<number> field (a visible field), the plug-in then searches for the following fields (and populates those it finds):

    • HD_Template_UploadItemType<number>—populated either with "Template", "URL" or "RawFile" (refers to any other file previously added to the library). This invisible field is required in order to accept uploads from HotDocs 11. (HotDocs 10 uploads only template packages, and does not look for or populate this field.) If this field does not exist in your form, the upload fails.
    • HD_Template_Description<number>—an invisible field populated with the template or library item description (escaped as with HD_Template_Title<number>, as shown above).
    • HD_Template_Filename<number>—invisible field populated with the file name only (not the path) of the template or library item. The file extension is .pkg.

For URLs, the HD_Template_FileName field is set to <guid>.url, and the contents of the file are the actual url. For other files, the same field is set to the file name (with extension) of the actual file on the machine that the library item points to.

    • HD_Template_Library_Path<number>—invisible field (used in HotDocs 11 only) that is populated with the "library path" of the template or library item.
  2. If the HD_Template_UploadItemType<number> value is "Template," the upload plug-in searches for the following invisible fields (and populates those it finds):
    • HD_Template_CommandLineSwitches<number>—invisible field (used in HotDocs 11 only) that is populated with the command line switches that decorate the template in the HotDocs library from which it was uploaded.
    • HD_Template_Expiration_Date<number>—invisible field (used in HotDocs 11 only) that is populated with the template expiration date, if the template publisher provided one. The date is formatted as follows: YYYY-MM-DD (ex: 2013-08-31).  
  3. If the template has an expiration date, the plug-in searches for the following fields (and populates those it finds):
    • HD_Template_Warning_Days<number>—invisible field (used in HotDocs 11 only) that is populated with the number of warning days specified by the publisher of the template.
    • HD_Template_Extension_Days<number>—invisible field (used in HotDocs 11 only) that is populated with the number of extension days specified by the publisher of the template.
  4. If the upload plug-in finds any element on the page with an ID of "HD_CloseAfterUpload", and the plug-in has completed uploading all the templates, the plug-in immediately closes your upload page (so the user does not have to close it).
  5. After the upload plug-in has populated the fields in your upload page, the plug-in waits for the form to be submitted.  Typically the user does this after reviewing and perhaps modifying the template title and description (if you have provided that capability), and then clicking whichever button on the form causes the form's submit event to fire. After the form's submit event fires, the upload plug-in submits the form, adding one or two FILE uploads to the form:
    • HD_Upload<number>—populated with the content of either the template package, or other file (such as a PDF) or URL previously added to the library and now being uploaded.
    • HD_Package_Manifest<number>—for templates, populated with the content of the template package's XML manifest. Your Host application can use this manifest to find out more about the template being uploaded (if desired) without needing to crack the package itself.
      Upload pages that are compatible with HotDocs 11 (by virtue of having the HD_Template_UploadItemType0 input fields) are by nature also capable of accepting uploads from HotDocs 10.2.  If it makes a difference to whether your host application is talking to HotDocs 10.2 or 11 (it will not in most cases), you should have your host application check to see whether the HD_Template_UploadItemType0 field is populated.
  6. The upload plug-in also inspects the HTML of your upload page for these two required fields:
    • HD_Template_Title0
    • HD_Template_UploadItemType0
  7. If they are present, the plug-in adds the following items to the form:
    • HD_Upload0—the template package or other file or URL library item.
    • HD_Package_Manifest0—the template's package manifest (for template packages only).
  8. Once your upload page has successfully uploaded the template package, you can instruct your host application to take actions based on the metadata associated with the template. Host applications can derive metadata about uploaded templates from three places:
    • The form fields which are populated and submitted by the upload plug-in
    • The XML template package manifest (submitted for all packages, but not for other file or URL library items)
    • By directly inspecting the uploaded package, file, or URL: packages are standard zip files, and their contents can be inspected using the TemplatePackage class in the client library or by using 3rd party tools.

Testing Your Upload Page

When you've created your upload page, you can either test the upload feature yourself (if you have a copy of HotDocs Developer), or have someone who is going to use your host application test the page for you.

To test your upload page

  1. Deploy your upload page on your web server.
  2. In the left hand (library) column of HotDocs Developer, right-click a template; then click Upload > Edit Upload Sites.
  3. Click Add; then type the Site Name of your host application site and the URL of your upload page.
  4. Click OK; then click Close.
  5. Enable a template for uploading to your host application site by doing the following:
    1. Right-click a template; then click Test in Browser before clicking either JavaScript or Silverlight.
    2. On the message that appears, click Enable; then on the Answer File dialog, click Cancel.

If this template has already been enabled, the Enable window does not appear; click Cancel.

  1. Right-click the template you just enabled; then click Upload before clicking the name of the upload site to which you want to upload the template package.
  2. Your upload page should appear so you can inspect its features.
  3. Finish the upload to your website.