Help Topics for HotDocs

Developer 10

Help Topics for HotDocs Developer 10

Contents
SECTION 1: LEARNING ABOUT HOTDOCS............................................................................................... 1
Chapter 1: Becoming Familiar with HotDocs.................................................................................................................... 2
What Is HotDocs?......................................................................................................................................................... 2
Plan a Template Development Project......................................................................................................................... 4
Quick Help Links......................................................................................................................................................... 10

SECTION 2: GETTING STARTED.............................................................................................................11

Chapter 2: What's New in HotDocs Developer...............................................................................................................12
New and Enhanced Features of HotDocs 10............................................................................................................. 12
New and Enhanced Features of HotDocs 2009 HF2................................................................................................. 14
New and Enhanced Features of HotDocs 2009 HF1................................................................................................. 15
New and Enhanced Features of HotDocs 2009......................................................................................................... 16
New and Enhanced Features of HotDocs 2008 SR 2................................................................................................18
New and Enhanced Features of HotDocs 2008 SR 1................................................................................................19
New and Enhanced Features of HotDocs 2008......................................................................................................... 20
New and Enhanced Features of HotDocs 2007 SP1................................................................................................. 22
New and Enhanced Features of HotDocs 2007......................................................................................................... 23
New and Enhanced Features of HotDocs 2006 SP1................................................................................................. 24
New and Enhanced Features of HotDocs 2006......................................................................................................... 25
New and Enhanced Features of HotDocs 6.2 SP1.................................................................................................... 28
New and Enhanced Features of HotDocs 6.2............................................................................................................ 29
New and Enhanced Features of HotDocs 6.1 SP1.................................................................................................... 32
New and Enhanced Features of HotDocs 6.1............................................................................................................ 33
New and Enhanced Features of HotDocs 6.0............................................................................................................ 35
New and Enhanced Features of HotDocs 2005 SP3................................................................................................. 39
New and Enhanced Features of HotDocs 2005 SP2................................................................................................. 40
New and Enhanced Features of HotDocs 2005 SP1................................................................................................. 41
New and Enhanced Features of HotDocs 2005......................................................................................................... 43
Chapter 3: Installing HotDocs..........................................................................................................................................45
What Is HotDocs?....................................................................................................................................................... 45
Compatibility of HotDocs 10 Files with Earlier Versions of HotDocs..........................................................................47
System Requirements................................................................................................................................................. 49
Install HotDocs.............................................................................................................................................................50
Understand HotDocs Installation.................................................................................................................................51
Default File Locations in HotDocs 10......................................................................................................................... 52
Use International Characters in HotDocs....................................................................................................................53
HotDocs and XML File Formats..................................................................................................................................55
Uninstall HotDocs........................................................................................................................................................ 56
Chapter 4: Starting With HotDocs................................................................................................................................... 57
Start HotDocs.............................................................................................................................................................. 57
Exit HotDocs................................................................................................................................................................ 58
Get Help Using HotDocs.............................................................................................................................................59
Verify HotDocs 5 Templates for Use with HotDocs 10...............................................................................................61
Use HotDocs with Microsoft Word 2007 and 2010.................................................................................................... 62
List of HotDocs File Name Extensions....................................................................................................................... 63
Complete the HotDocs Tutorials................................................................................................................................. 65
Documentation Feedback............................................................................................................................................66
Copyright 2010 HotDocs Ltd. All rights reserved

Help Topics for HotDocs Developer 10

Chapter 5: Using the Keyboard in HotDocs....................................................................................................................67

Use the Keyboard to Work in HotDocs...................................................................................................................... 67
Full List of Keyboard Shortcuts...................................................................................................................................69

SECTION 3: SETTING HOTDOCS OPTIONS.............................................................................................81

Chapter 6: Setting HotDocs Options............................................................................................................................... 82
Overview: HotDocs Options........................................................................................................................................ 82
Interviews and Dialogs................................................................................................................................................ 83
Document Assembly....................................................................................................................................................90
Document Markup....................................................................................................................................................... 94
Model Documents........................................................................................................................................................97
Form Documents......................................................................................................................................................... 98
Question and Answer Summaries.............................................................................................................................107
Personal Information..................................................................................................................................................109
Spell Checking...........................................................................................................................................................110
Template Development..............................................................................................................................................112
Word Processors....................................................................................................................................................... 118
File Locations............................................................................................................................................................ 120
File Management....................................................................................................................................................... 122
Template Set Updates...............................................................................................................................................124

SECTION 4: USING LIBRARIES............................................................................................................ 125

Chapter 7: Using HotDocs Libraries..............................................................................................................................126
Overview: Use HotDocs Libraries............................................................................................................................. 126
Create a Library.........................................................................................................................................................128
Open a Library.......................................................................................................................................................... 129
Add Templates and Other Files to a Library............................................................................................................ 130
Work with Templates and Other Files in a Libary.................................................................................................... 131
Remove Items from a Library................................................................................................................................... 132
Change the Properties of a Single Library Item....................................................................................................... 133
Change the Properties for Multiple Items in a Library.............................................................................................. 134
Sort Items in a Library.............................................................................................................................................. 136
Organize the Contents of a Library.......................................................................................................................... 137
Create a Favorites Folder in the Template Library...................................................................................................138
Create a New Library By Exporting Part of an Existing Library............................................................................... 139
Import One Library Into Another............................................................................................................................... 140
Print a List of Items in a Library............................................................................................................................... 141
Save a Library........................................................................................................................................................... 142
Save the Contents of a Library as a Text File......................................................................................................... 143
Move Items Within a Library..................................................................................................................................... 144
Move Items to New Locations on Disk..................................................................................................................... 145
Copy Templates to New Locations........................................................................................................................... 146

SECTION 5: AUTOMATING TEXT TEMPLATES.......................................................................................147

Chapter 8: Creating and Working with Template Files................................................................................................. 148
Overview: Template and Component Files...............................................................................................................148
HotDocs Editing and Navigation Toolbar Buttons.....................................................................................................150
Create a New Text Template File.............................................................................................................................153
Create a Text Template Based on an Existing Template.........................................................................................154
Convert a Single Template to a New File Format.................................................................................................... 155
Copyright 2010 HotDocs Ltd. All rights reserved

ii

Help Topics for HotDocs Developer 10

Edit a Template......................................................................................................................................................... 157

Assign Colors to Fields and Instructions in Templates.............................................................................................158
Move Between Fields in a Template........................................................................................................................ 159
Use Labels to Identify Instructions............................................................................................................................160
Go to a Specific Field in the Template..................................................................................................................... 162
View the Template in Markup View.......................................................................................................................... 163
View an Outline of Scripting in the Template........................................................................................................... 164
Create a Foreign Language Template...................................................................................................................... 166
Tips on Using Graphics in Word Templates.............................................................................................................168
Chapter 9: Inserting Variables in Text Templates.........................................................................................................170
Overview: Create and Customize Variables............................................................................................................. 170
Insert a Variable Field in a Text Template............................................................................................................... 171
Replace Other Instances of Selected Text with a Variable...................................................................................... 173
Create and Insert a Variable Using Component Manager........................................................................................174
Add a Comment to a Variable or Instruction Field................................................................................................... 175
Edit a Variable........................................................................................................................................................... 176
Chapter 10: Using Variable Types................................................................................................................................ 177
Overview: Create and Customize Variables............................................................................................................. 177
Customize a Text Variable........................................................................................................................................178
Customize a Number Variable.................................................................................................................................. 180
Customize a Date Variable....................................................................................................................................... 182
Customize a True/False Variable..............................................................................................................................184
Customize a Multiple Choice Variable...................................................................................................................... 186
Customize a Computation Variable...........................................................................................................................188
Insert a Personal Information Variable..................................................................................................................... 190
Create a Date Variable that Inserts the Current Date.............................................................................................. 191
Merge the Name of the Answer File in the Document............................................................................................. 192
Use Automatic Paragraph Numbering...................................................................................................................... 193
Count the Number of Entries in a List...................................................................................................................... 194
Chapter 11: Editing Variables........................................................................................................................................195
Overview: Create and Customize Variables............................................................................................................. 195
Edit a Variable........................................................................................................................................................... 196
Format the Variable...................................................................................................................................................197
Create a Prompt for a Variable.................................................................................................................................199
Control How HotDocs Processes a Variable............................................................................................................ 200
Specify the Width of Answer Fields in the Interview................................................................................................ 201
Control How Answers Appear in the Assembled Document.................................................................................... 202
Add Resource Information to a Variable or Dialog................................................................................................... 204
View Relationship Between the Current Component and Other Components......................................................... 205
Add Notes to Components........................................................................................................................................206
Add a Comment to a Variable or Instruction Field................................................................................................... 207
Format an Answer as the Time of Day.................................................................................................................... 208
Use Pattern Codes to Create a Custom Pattern...................................................................................................... 209
Work with Multiple Choice Options........................................................................................................................... 210
Specify Merge Text Options as Default or Field-Specific Properties........................................................................211
Copy and Paste Columns in a Multiple Choice Variable Spreadsheet.....................................................................212
Name a Group of Merge Text Values...................................................................................................................... 213
Use Variables and Scripts in Prompts, Dialog Element Text, and Resources......................................................... 214
Use the Script Editor................................................................................................................................................. 215
Copyright 2010 HotDocs Ltd. All rights reserved

iii

Help Topics for HotDocs Developer 10

Chapter 12: Setting Values for Variables......................................................................................................................218

Automatically Assign Answers to a Variable............................................................................................................ 218
Chapter 13: Tips on Using and Editing Variables.........................................................................................................219
Tips on Naming Your Variables................................................................................................................................ 219
How Example Formats are Interpreted..................................................................................................................... 221
Understand the HotDocs Scripting Language...........................................................................................................225
Understand How Component Titles and Prompts are Used.....................................................................................227
Chapter 14: Creating and Using Dialogs...................................................................................................................... 229
Overview: Create Your Own Dialogs........................................................................................................................ 229
Gather Questions into a Custom Dialog................................................................................................................... 232
Edit a Custom Dialog................................................................................................................................................ 234
Change a Dialog's Options....................................................................................................................................... 235
Add Resource Information to a Variable or Dialog................................................................................................... 238
Use Scripts to Add Power to Your Dialogs.............................................................................................................. 239
Change the Layout of Variables in a Dialog.............................................................................................................240
View Relationship Between the Current Component and Other Components......................................................... 241
Add Notes to Components........................................................................................................................................242
Use the Same Variable or Clause in Two or More Dialogs......................................................................................243
Control Whether Dialogs are Asked Automatically................................................................................................... 244
Chapter 15: Inserting Dialog Elements in Dialogs........................................................................................................ 245
Add Text to Your Dialogs..........................................................................................................................................245
Add the Ability to Launch an Application from a Dialog........................................................................................... 246
Add a Link to a Dialog That Runs a Computation....................................................................................................247
Add a Hyperlink to a Dialog......................................................................................................................................248
Add Spacing and Separator Lines to a Dialog......................................................................................................... 250
Add a Graphic File to a Dialog................................................................................................................................. 251
Chapter 16: Using Scripts to Make Dialogs Dynamic................................................................................................... 252
Automatically Disable Irrelevant Variables in Interviews...........................................................................................252
Use Scripts to Add Power to Your Dialogs.............................................................................................................. 254
Chapter 17: Assigning Answer Sources to Dialogs...................................................................................................... 255
Suggest an Answer Source for Dialogs....................................................................................................................255
Tips for Working with Answer Sources.....................................................................................................................257
Link a Dialog to a List Gathered by a Repeated Dialog...........................................................................................258
Link an Existing Answer Source to Other Dialogs .................................................................................................. 259
Let Users Retrieve Answers from an Outlook Contacts List.................................................................................... 260
Let Users Retrieve Answers from a Time Matters Record....................................................................................... 261
Chapter 18: Inserting Dialogs into Other Dialogs......................................................................................................... 262
Insert Dialogs Into Dialogs........................................................................................................................................ 262
Group Child Dialogs in a Parent Dialog................................................................................................................... 263
Chapter 19: Using ASK Instructions to Control Dialog Order....................................................................................... 264
Control When Your Dialogs Appear..........................................................................................................................264
Put ASK Instructions in a Computation Variable...................................................................................................... 265
Use ASK Instructions to Control the Interview......................................................................................................... 266
Chapter 20: Working with Component Files................................................................................................................. 267
Open and Close Component Manager..................................................................................................................... 267
Open Component Manager at the Template Library................................................................................................ 268
Use Component Manager to Work with Components.............................................................................................. 269
Copyright 2010 HotDocs Ltd. All rights reserved

iv

Help Topics for HotDocs Developer 10

Create and Edit Multiple Components Simultaneously.............................................................................................271

Change Component File Properties..........................................................................................................................272
Delete a Component from the Current Component File........................................................................................... 277
Copy Components From One File to Another.......................................................................................................... 278
Rename Components in a Single Template............................................................................................................. 279
Make a Duplicate Copy of a Variable.......................................................................................................................281
Edit Formats, Merge Text, Dialog Elements, and Patterns...................................................................................... 282
Search Component Files...........................................................................................................................................283
Spell Check Components..........................................................................................................................................285
Print a List of Components....................................................................................................................................... 286
Use One Component File for Multiple Templates.....................................................................................................287
Specify Whether Component File Properties are Shared.........................................................................................289
Make Templates Stop Sharing Component Files..................................................................................................... 290
Control Whether Users See the End of Interview Dialog......................................................................................... 291
Position the Cursor in the Assembled Document..................................................................................................... 292
Specify a Word Template for Storing Post-Assembly Macros..................................................................................293
Remove Hidden Data from Assembled Documents................................................................................................. 294
Remove Hidden Data from Word RTF Templates....................................................................................................295
Work with Variables in Headers, Footers, Footnotes, and Text Boxes.................................................................... 296
Chapter 21: Using IF Instructions................................................................................................................................. 297
Overview: Make Parts of Templates Conditional......................................................................................................297
Include or Exclude a Single Version of Text Using a Simple IF Instruction or Expression....................................... 298
Include or Exclude Multiple Versions of Text Using IF and ELSE IF Instructions or Expressions............................ 300
Edit an IF Instruction or Expression..........................................................................................................................302
Nest IF Instructions................................................................................................................................................... 303
Use Conditional Instructions in a Computation Script.............................................................................................. 304
Tips on Using IF Instructions.................................................................................................................................... 305
Add a Comment to a Variable or Instruction Field................................................................................................... 306
Understand How Smart Returns are Inserted After Instructions...............................................................................307
Assign Colors to Fields and Instructions in Templates.............................................................................................309
Use Labels to Identify Instructions............................................................................................................................310
Match Opening Instructions with Closing Instructions.............................................................................................. 312
Chapter 22: Creating Lists of Answers......................................................................................................................... 313
Overview: Include Lists in Your Documents............................................................................................................. 313
Create a REPEAT Instruction to Gather a List of Answers...................................................................................... 315
Edit a REPEAT Instruction........................................................................................................................................316
Choose a Presentation Style for the Repeated Dialog.............................................................................................317
Customize REPEAT Titles........................................................................................................................................ 318
Punctuate a Sentence-Style List............................................................................................................................... 320
Sort a List of Answers...............................................................................................................................................321
Filter a List of Answers............................................................................................................................................. 322
Control How Many Rows are Visible in a Spreadsheet Dialog................................................................................ 323
Limit the Number of Answers Allowed for a Repeated Dialog................................................................................. 324
Get Sum Totals for Repeated Number Variables..................................................................................................... 325
Use a Word Processor Table to Display a List........................................................................................................ 326
Make a List Appear as one or More Columns......................................................................................................... 327
Count the Number of Entries in a List...................................................................................................................... 328
Retrieve a Specific Answer from a List.................................................................................................................... 329
Add a Comment to a Variable or Instruction Field................................................................................................... 330
Copyright 2010 HotDocs Ltd. All rights reserved

Help Topics for HotDocs Developer 10

Understand How Smart Returns are Inserted After Instructions...............................................................................331

Assign Colors to Fields and Instructions in Templates.............................................................................................333
Use Labels to Identify Instructions............................................................................................................................334
Match Opening Instructions with Closing Instructions.............................................................................................. 336
Chapter 23: Using Computations to Create Lists......................................................................................................... 337
Create a REPEAT Instruction Using a Computation Variable.................................................................................. 337
Punctuate a List Using a Computation Variable....................................................................................................... 338
Sort a List Using a Computation Variable................................................................................................................ 339
Filter a List Using a Computation Variable............................................................................................................... 340
Tips on Using Computations to Create Lists............................................................................................................ 341
Chapter 24: Creating Lists Within Lists.........................................................................................................................342
Overview: Create Lists Within a List.........................................................................................................................342
Create a List Within a List........................................................................................................................................ 343
Display a Child Dialog Directly on the Parent Dialog............................................................................................... 344
Nest REPEAT Instructions Using a Computation Variable.......................................................................................345
Use a Particular Answer from a Sublist....................................................................................................................346
Chapter 25: Inserting Templates into Other Templates................................................................................................ 348
Overview: Insert Templates into Templates..............................................................................................................348
Make Part of a Template into an Inserted Template................................................................................................ 349
Insert an Existing Template...................................................................................................................................... 350
Edit an INSERT Template Instruction....................................................................................................................... 351
Inserted Templates and Shared Component Files................................................................................................... 352
Define Headers and Footers in Inserted Word Templates....................................................................................... 353
Start a New Assembly From a Template..................................................................................................................355
Insert Image Files in a Template.............................................................................................................................. 357
Specify File Names for Inserting Files During Assembly..........................................................................................359
Chapter 26: Marking Editable Text in a Template........................................................................................................ 360
Overview: Use SPAN Instructions.............................................................................................................................360
Allow Users to Edit the Text of an Assembled Document........................................................................................361
Allow Users to Enter New Text in the Assembled Document.................................................................................. 362
Add a Comment to a Variable or Instruction Field................................................................................................... 363
Understand How Smart Returns are Inserted After Instructions...............................................................................364
Use Labels to Identify Instructions............................................................................................................................366
Match Opening Instructions with Closing Instructions.............................................................................................. 368
Chapter 27: Creating and Editing Clauses....................................................................................................................369
Overview: Use Clauses and Clause Libraries.......................................................................................................... 369
Understand How Clauses Work................................................................................................................................ 370
Open and Close a Clause Library............................................................................................................................ 371
Create a Clause Library at the HotDocs Library...................................................................................................... 372
Add a Folder to a Clause Library............................................................................................................................. 373
Create Clauses at the Clause Library.......................................................................................................................374
Add Existing Clauses to a Clause Library................................................................................................................ 375
Customize a Clause Library......................................................................................................................................376
Create Clauses at the Template and Add Them to the Library................................................................................378
Create and Insert Clauses Directly in Template....................................................................................................... 379
Insert a Clause Library into a Template................................................................................................................... 380
Edit an Existing Clause............................................................................................................................................. 381
Group Clause Components in One Custom Dialog..................................................................................................382
Copyright 2010 HotDocs Ltd. All rights reserved

vi

Help Topics for HotDocs Developer 10

Chapter 28: Defining the Interview for the Document...................................................................................................383

Overview: HotDocs Interviews.................................................................................................................................. 383
Have HotDocs Generate a Default Interview............................................................................................................384
Define a Custom Interview........................................................................................................................................385
Improve Interview Speed Using a Custom Interview................................................................................................387
Automatically Disable Irrelevant Variables in Interviews...........................................................................................388
Chapter 29: Using Dot Codes to Format Text and Insert Special Characters.............................................................. 390
Overview: Dot Codes................................................................................................................................................ 390
Change Font Properties of Text................................................................................................................................392
Insert a Web Link in a Prompt or Dialog Text Element............................................................................................394
Add Punctuation and Capitalization to Sentences....................................................................................................395
Insert Characters in Text Strings.............................................................................................................................. 396
Punctuate Non-Repeated Lists of Answers.............................................................................................................. 398
Chapter 30: Using Instruction Models........................................................................................................................... 399
Use Operators When Scripting................................................................................................................................. 399
Use Line Breaks, Paragraph Ends, and Tabs in Computation Scripts..................................................................... 401
Use the Script Editor................................................................................................................................................. 402
View an Outline of Scripting in the Template........................................................................................................... 405
Full List of Instruction Models................................................................................................................................... 407
ADD TEXT TO MULT_CHOICE_VAR; CLEAR MULT_CHOICE_VAR.................................................................... 409
ASCEND VAR; DESCEND VAR...............................................................................................................................410
ASK DIALOG............................................................................................................................................................. 411
ASK VAR................................................................................................................................................................... 412
ASSEMBLE "FILENAME"..........................................................................................................................................413
CONCEAL VAR......................................................................................................................................................... 414
DEBUG...................................................................................................................................................................... 415
DEFAULT VAR TO VALUE...................................................................................................................................... 416
ERASE VAR; ERASE DIALOG.................................................................................................................................417
FILTER COMPUTATION_VAR................................................................................................................................. 418
FORMAT "LIST_FORMAT"....................................................................................................................................... 419
GRAY ALL; GRAY VAR; UNGRAY ALL; UNGRAY VAR.........................................................................................420
HIDE ALL; HIDE VAR; SHOW ALL; SHOW VAR.................................................................................................... 421
IF EXPRESSION; ELSE IF; ELSE; END IF............................................................................................................. 422
INCREMENT NUM_VAR; DECREMENT NUM_VAR............................................................................................... 423
INSERT "FILENAME"................................................................................................................................................ 424
LANGUAGE CODE................................................................................................................................................... 425
LIMIT NUM................................................................................................................................................................ 426
OMIT VAR................................................................................................................................................................. 427
PLAY "MACRO".........................................................................................................................................................428
QUIT...........................................................................................................................................................................429
REPEAT DIALOG; END REPEAT............................................................................................................................ 430
REQUIRE ALL; REQUIRE VAR................................................................................................................................431
SET VAR TO VALUE................................................................................................................................................432
WHILE EXPRESSION; END WHILE........................................................................................................................ 433
Chapter 31: Using Expression Models..........................................................................................................................435
Overview: Instruction and Expression Models.......................................................................................................... 435
Use Operators When Scripting................................................................................................................................. 436
Use Line Breaks, Paragraph Ends, and Tabs in Computation Scripts..................................................................... 438
Use the Script Editor................................................................................................................................................. 439
Copyright 2010 HotDocs Ltd. All rights reserved

vii

Help Topics for HotDocs Developer 10

Full List of Expression Models.................................................................................................................................. 442

Enter a Date.............................................................................................................................................................. 446
Enter a Number......................................................................................................................................................... 447
Enter some Text........................................................................................................................................................ 448
Enter True or False................................................................................................................................................... 449
ABSOLUTE VALUE( NUM )...................................................................................................................................... 450
AGE( DATE )..............................................................................................................................................................451
ANSWERED( DIALOG )............................................................................................................................................ 452
ANSWERED( VAR )...................................................................................................................................................453
COUNT( DIALOG ).................................................................................................................................................... 454
COUNTER................................................................................................................................................................. 455
COUNT( MULT_CHOICE_VAR )...............................................................................................................................456
DATE - NUM DAYS.................................................................................................................................................. 457
DATE - NUM MONTHS............................................................................................................................................ 458
DATE - NUM YEARS................................................................................................................................................459
DATE + NUM DAYS................................................................................................................................................. 460
DATE + NUM MONTHS............................................................................................................................................461
DATE + NUM YEARS............................................................................................................................................... 462
DATE OF( NUM, NUM, NUM )..................................................................................................................................463
DAY OF( DATE )....................................................................................................................................................... 464
DAY OF WEEK( DATE )........................................................................................................................................... 465
DAYS FROM( DATE, DATE )................................................................................................................................... 466
FIRST( TEXT, NUM ).................................................................................................................................................467
FORMAT( VALUE, "EXAMPLE" )..............................................................................................................................468
INTEGER( TEXT )......................................................................................................................................................469
LAST( TEXT, NUM ).................................................................................................................................................. 470
LENGTH( TEXT )....................................................................................................................................................... 471
MAX( NUM, NUM ).................................................................................................................................................... 472
MID( TEXT, NUM, NUM )..........................................................................................................................................473
MIN( NUM, NUM )..................................................................................................................................................... 474
MONTH OF( DATE )..................................................................................................................................................475
MONTHS FROM( DATE, DATE )..............................................................................................................................476
MULT_CHOICE=TEXT; MULT_CHOICE!=TEXT......................................................................................................477
NOT TRUE_FALSE................................................................................................................................................... 478
OTHER( MULT_CHOICE_VAR )............................................................................................................................... 479
POSITION( TEXT, TEXT ).........................................................................................................................................480
POWER( NUM, NUM ).............................................................................................................................................. 481
REMAINDER( NUM, NUM )...................................................................................................................................... 482
REPLACE( TEXT, TEXT, TEXT, NUM )................................................................................................................... 483
RESULT..................................................................................................................................................................... 484
ROUND( NUM, NUM )...............................................................................................................................................485
SELECTION( MULT_CHOICE_VAR, NUM ).............................................................................................................486
SPACE( TEXT, TEXT )..............................................................................................................................................487
STRIP( TEXT, TEXT, TRUE_FALSE, TRUE_FALSE ).............................................................................................488
SUM( COMPUTATION_VAR )...................................................................................................................................489
SUM( NUM_VAR )..................................................................................................................................................... 490
TEXT CONTAINS TEXT........................................................................................................................................... 491
TODAY.......................................................................................................................................................................492
TRUNCATE( NUM, NUM )........................................................................................................................................ 493
UNANSWERED......................................................................................................................................................... 494
Copyright 2010 HotDocs Ltd. All rights reserved

viii

Help Topics for HotDocs Developer 10

UNION( MULT_CHOICE, MULT_CHOICE )............................................................................................................. 495

VALUE( VAR, EXPRESSION )..................................................................................................................................496
YEAR OF( DATE )..................................................................................................................................................... 497
YEARS FROM( DATE, DATE )................................................................................................................................. 498
ZERO( NUM_VAR )................................................................................................................................................... 499
Chapter 32: Linking Templates to a Database............................................................................................................. 500
Overview: Link Templates to a Database.................................................................................................................500
Use Supported Databases........................................................................................................................................ 501
Understand Database Connectivity........................................................................................................................... 502
Create a Database Component Using ADO............................................................................................................. 503
Create a Database Component Using ODBC.......................................................................................................... 505
Save ADO Connection Information in a Separate File............................................................................................. 507
Convert ODBC-based Connections to ADO............................................................................................................. 508
Edit a Database Component.....................................................................................................................................509
Link Variables to Database Fields............................................................................................................................ 510
Remember Selected Records................................................................................................................................... 511
Save Changed Answers Back to the Database....................................................................................................... 512
Change Database Component Properties................................................................................................................ 513
Use a Custom Command to Retrieve Data from a Database.................................................................................. 515
Choose Which Database Fields Appear During Assembly.......................................................................................516
Cause HotDocs to Update Selected Records Between Assemblies........................................................................ 517
Limit the Number of Database Records from Which a User Chooses..................................................................... 518
Specify a User Name and Password for a Database...............................................................................................519
Sort Records in a Database Table........................................................................................................................... 520
Generate a List of Records in an Assembled Document......................................................................................... 521
Tips on Filtering and Sorting Repeated Database Components.............................................................................. 522
Merge Filtered Records into the Document Automatically........................................................................................523
Ask Variables Already Answered by the Database.................................................................................................. 524
Select Related Database Records............................................................................................................................ 525
Control When Your Database Tables Appear.......................................................................................................... 526
Choose a Database Cursor...................................................................................................................................... 527
Chapter 33: Testing HotDocs Automation.....................................................................................................................529
Overview: Test HotDocs Templates..........................................................................................................................529
Test Individual Variables........................................................................................................................................... 530
Test a Computation Script........................................................................................................................................ 531
Test a Custom Dialog............................................................................................................................................... 532
Test Assemble a Document......................................................................................................................................533
Use a Test Answer File............................................................................................................................................ 534
Simultaneously Edit a Template and Test Assemble a Document...........................................................................535
Understand and Resolve Syntax Errors in a Template or Script..............................................................................536
Chapter 34: Using the HotDocs Debugger................................................................................................................... 537
Overview: Debugging Templates.............................................................................................................................. 537
Insert Debugging Instructions in Templates and Scripts.......................................................................................... 538
Step Through a Template or Script.......................................................................................................................... 539
Add Variables to the Debugger Watch List.............................................................................................................. 542
Chapter 35: Using the Test Panel.................................................................................................................................543
Overview: Use the Test Panel.................................................................................................................................. 543
Validate Variable Usage in a Template.................................................................................................................... 544
Check Interviews for Improper Scripting................................................................................................................... 545
Copyright 2010 HotDocs Ltd. All rights reserved

ix

Help Topics for HotDocs Developer 10

Move From the Document to the Template During Testing..................................................................................... 546

Chapter 36: Managing Templates................................................................................................................................. 547
Overview: Use Template Manager............................................................................................................................547
Open and Close Template Manager.........................................................................................................................549
Understand Parts of Template Manager Window.....................................................................................................550
Template Manager Toolbar....................................................................................................................................... 552
Export Contents of a Template Manager Window to a Spreadsheet....................................................................... 554
Convert Multiple Templates to Work with HotDocs 10............................................................................................. 555
Convert Templates and Clauses to Microsoft RTF...................................................................................................556
Rename Templates Using Template Manager......................................................................................................... 558
Chapter 37: Managing Components............................................................................................................................. 559
Overview: Use Template Manager............................................................................................................................559
Open and Close Template Manager.........................................................................................................................561
Understand Parts of Template Manager Window.....................................................................................................562
Template Manager Toolbar....................................................................................................................................... 564
Copy and Paste Components Across Multiple Component Files............................................................................. 566
Rename Components Across Multiple Component Files......................................................................................... 567
Delete Components from Multiple Component Files................................................................................................ 568
Modify Component File Properties Across Multiple Files......................................................................................... 569

SECTION 6: AUTOMATING FORM TEMPLATES......................................................................................570

Chapter 38: Creating and Working with Forms.............................................................................................................571
Overview: HotDocs Automator.................................................................................................................................. 571
HotDocs Automator Toolbar......................................................................................................................................572
Create a Form Template...........................................................................................................................................574
Save Existing HFT Files as PDF-based Form Templates........................................................................................ 576
Edit a Form Template............................................................................................................................................... 577
Add Pages to a Form Template............................................................................................................................... 578
Remove Pages from a Form Template.................................................................................................................... 579
Update the Underlying Text in a Form Template..................................................................................................... 580
View the Form in More than One Window............................................................................................................... 581
Globally Change Properties in a Template or Group of Templates..........................................................................582
Save and Close a Form Template............................................................................................................................584
Define the Interview for a Form Template................................................................................................................ 585
Chapter 39: Creating Form Fields.................................................................................................................................586
Create a Form Field.................................................................................................................................................. 586
Select a Field........................................................................................................................................................... 587
Create a Check-Box Field.........................................................................................................................................588
Attach a Variable to a Field...................................................................................................................................... 589
Attach an ASK Instruction to a Field........................................................................................................................ 590
Make a Field Conditional.......................................................................................................................................... 591
Attach an INSERT Instruction to a Field...................................................................................................................592
Detect Borders to Create or Resize a Field............................................................................................................. 593
Move a Field on a Form........................................................................................................................................... 594
Align Two or More Fields.........................................................................................................................................595
Change the Borders and Margins of a Field............................................................................................................ 596
Copy One or More Form Fields................................................................................................................................597
Resize Form Fields................................................................................................................................................... 598
Change the Tab Order of Fields...............................................................................................................................599
Copyright 2010 HotDocs Ltd. All rights reserved

Help Topics for HotDocs Developer 10

Group Form Fields So Answers Can Flow From One Field to Another................................................................... 601
Attach a Variable to Single-Character Boxes........................................................................................................... 602
Attach a Multiple Choice Variable to a Group of Check Boxes................................................................................603
Ungroup Form Fields.................................................................................................................................................604
Attach an Answer Wizard to a Field......................................................................................................................... 605
Chapter 40: Changing Field Properties.........................................................................................................................606
Preview the Formatting of Answers in a Form Field................................................................................................ 606
Show and Hide Fields............................................................................................................................................... 607
Change the Field Type..............................................................................................................................................608
Change the Font Used for a Field............................................................................................................................ 610
Format Lines and Paragraphs of Text in a Form Field............................................................................................ 611
Rotate Answers in a Field.........................................................................................................................................612
Keep Contents of Form Fields from Printing............................................................................................................ 613
Create a Field for Behind-the-Scenes Tasks............................................................................................................614
Create a Resource Link on a Form.......................................................................................................................... 615
Cross Out Static Text on the Form...........................................................................................................................616
Circle Static Text on a Form.....................................................................................................................................617
Insert a Graphic File in a Form................................................................................................................................ 618
Convert Answers on the Form to Bar Code Format.................................................................................................619
Move a Field on a Form........................................................................................................................................... 621
Merge a List of Answers in a Standard Table.......................................................................................................... 622
Merge a List of Answers in a Nonstandard Table.................................................................................................... 623
Flow a Single Answer Across Two or More Pages in a Form..................................................................................625
Chapter 41: Defining Form Overflow Properties........................................................................................................... 626
Define Overflow Properties for a Regular Field........................................................................................................ 626
Define Overflow Properties for Run-on Fields.......................................................................................................... 628
Define Overflow Properties for a Table.................................................................................................................... 630
Customize the Look of the Addendum..................................................................................................................... 632
Split a Multi-Line Answer Between the Form and the Addendum............................................................................ 634
Create Independent Addendums for Forms..............................................................................................................635
Use Answer Overflow and Addendum Text Codes.................................................................................................. 636
Chapter 42: Creating and Using Fillable PDF Form Templates................................................................................... 638
Overview: Use Fillable PDFs as Form Templates....................................................................................................638
Create a Form Template Using a Fillable PDF........................................................................................................ 639
Detect Fillable Fields in a PDF Template................................................................................................................. 641
Attach Variables to Fillable Fields.............................................................................................................................643
Tips for Working with Fillable Fields......................................................................................................................... 645

SECTION 7: PUBLISHING TEMPLATES..................................................................................................647

Chapter 43: Publishing HotDocs Templates................................................................................................................. 648
Overview: Publish HotDocs Templates.....................................................................................................................648
Publish a Template as a Standard File.................................................................................................................... 649
Publish Templates as Auto-Assemble Files (HDA).................................................................................................. 650
Publish Templates as Auto-Install Files (HDI).......................................................................................................... 652
Protect Published Files..............................................................................................................................................654
Publish and Register Templates for Use With HotDocs Player................................................................................655
Create a Shortcut for an Auto-Install Library............................................................................................................ 656
Create an HDI File for a CD-based Template Set................................................................................................... 657
Add Files to a Published Set.................................................................................................................................... 658
Copyright 2010 HotDocs Ltd. All rights reserved

xi

Help Topics for HotDocs Developer 10

Save Publishing Settings...........................................................................................................................................659

Use a Custom Library Splash Screen...................................................................................................................... 660
Automatically Update Published Template Sets....................................................................................................... 661
Chapter 44: Publishing HotDocs Server Templates......................................................................................................664
What is HotDocs Server?..........................................................................................................................................664
Features Not Allowed in HotDocs Server Templates............................................................................................... 666
Features That Work Differently in HotDocs Server Interviews................................................................................. 667
Enable Templates for Use With HotDocs Server..................................................................................................... 670
View an Interview in a Web Browser........................................................................................................................671
Publish Templates For Use With HotDocs Server....................................................................................................672
Upload Templates to a Web Server......................................................................................................................... 673
Chapter 45: Uploading Published Files.........................................................................................................................674
Overview: Upload HotDocs Files to a Web Server...................................................................................................674
Create Custom HTML Documents for Template Uploading..................................................................................... 675
Upload Templates to a Web Server......................................................................................................................... 676
Chapter 46: Uploading Answer Files to a Server......................................................................................................... 677
Overview: Upload HotDocs Answer Files................................................................................................................. 677
Specify Options to Upload Answers......................................................................................................................... 678
Handle Data in Uploaded Answers...........................................................................................................................679

SECTION 8: ASSEMBLING DOCUMENTS...............................................................................................681

Chapter 47: Completing an Interview............................................................................................................................682
Overview: Assemble a Text or Form Document.......................................................................................................682
Adjust HotDocs Windows and Panes....................................................................................................................... 683
Update Your Interview Outline and Document......................................................................................................... 684
Preview a Template Before Assembling It................................................................................................................685
Search for a Specific Template in a Library............................................................................................................. 686
Assemble a Text or Form Document........................................................................................................................687
Select an Answer File for Assembly......................................................................................................................... 688
Assemble an Interview Template.............................................................................................................................. 689
Assemble a Document Without Showing an Interview............................................................................................. 690
Overlay Answers in the Current Answer File............................................................................................................691
Assemble Multiple Documents.................................................................................................................................. 692
Use the Assembly Queue......................................................................................................................................... 693
Assemble a Clause Library from the Template Library............................................................................................ 695
Navigate Through Answer-Gathering Dialogs...........................................................................................................696
View Resources During Assembly............................................................................................................................ 698
Save an Answer File During Assembly.................................................................................................................... 699
Switch Answer Files During Assembly..................................................................................................................... 700
Use Repeated Dialogs During Assembly..................................................................................................................701
Use Inserted Dialogs During Assembly.................................................................................................................... 703
View Individual Rows in a Spreadsheet................................................................................................................... 704
Select Clauses During an Interview..........................................................................................................................705
View an Assembled Document in Markup View....................................................................................................... 706
Answer Date Questions.............................................................................................................................................707
View an Answer's Variable Name.............................................................................................................................708
Use the End of Interview Dialog............................................................................................................................... 709
Edit Answers at the Document Preview Tab............................................................................................................ 711
Spell Check Answers................................................................................................................................................ 713
Copyright 2010 HotDocs Ltd. All rights reserved

xii

Help Topics for HotDocs Developer 10

Chapter 48: Working with Assembled Text Documents................................................................................................714

Preview the Assembled Text Document................................................................................................................... 714
Edit Answers at the Document Preview Tab............................................................................................................ 715
Edit Document Text at the Document Preview Tab................................................................................................. 717
View an Assembled Document in Markup View....................................................................................................... 719
Send the Assembled Text Document to the Word Processor.................................................................................. 720
Open a Saved Text Document for Editing................................................................................................................721
Print an Assembled Text Document......................................................................................................................... 722
Save an Assembled Text or Form Document.......................................................................................................... 723
Save Assembled Text Document as PDF................................................................................................................ 724
Save Assembled Form Document as PDF............................................................................................................... 725
Assign Security Options to a PDF Document...........................................................................................................726
Chapter 49: Working with Assembled Form Documents.............................................................................................. 727
Overview: Assemble a Form Document................................................................................................................... 727
Enter Answers Directly at the Form Document Tab................................................................................................. 728
View the Assembled Form Document...................................................................................................................... 730
Assemble a Fillable PDF Document......................................................................................................................... 731
Override an Answer in a Form................................................................................................................................. 732
Print an Assembled Form Document........................................................................................................................ 733
Choose Default Form Printing Options for a Form................................................................................................... 734
Edit a Saved Form Document...................................................................................................................................735
Create a Form Field.................................................................................................................................................. 736
Select a Field........................................................................................................................................................... 737
Create a Check-Box Field.........................................................................................................................................738
Detect Borders to Create or Resize a Field............................................................................................................. 739
Move a Field on a Form........................................................................................................................................... 740
Align Two or More Fields.........................................................................................................................................741
Change the Borders and Margins of a Field............................................................................................................ 742
Copy One or More Form Fields................................................................................................................................743
Resize Form Fields................................................................................................................................................... 744
Change the Tab Order of Fields...............................................................................................................................745
Group Form Fields So Answers Can Flow From One Field to Another................................................................... 747
Ungroup Form Fields.................................................................................................................................................748
Change the Field Type..............................................................................................................................................749
Change the Font Used for a Field............................................................................................................................ 751
Format Lines and Paragraphs of Text in a Form Field............................................................................................ 752
Rotate Answers in a Field.........................................................................................................................................753
Keep Contents of Form Fields from Printing............................................................................................................ 754
Cross Out Static Text on the Form...........................................................................................................................755
Circle Static Text on a Form.....................................................................................................................................756
Insert a Graphic File in a Form................................................................................................................................ 757
Convert Answers on the Form to Bar Code Format.................................................................................................758
Flow a Single Answer Across Two or More Pages in a Form..................................................................................760
Check Form Fields for Answer Overflow.................................................................................................................. 761
Customize the Look of the Addendum..................................................................................................................... 763
Define Overflow Properties for a Regular Field........................................................................................................ 765
Split a Multi-Line Answer Between the Form and the Addendum............................................................................ 767
Chapter 50: Creating Template and Document Summaries......................................................................................... 768
Overview: Question and Answer Summaries........................................................................................................... 768
Copyright 2010 HotDocs Ltd. All rights reserved

xiii

Help Topics for HotDocs Developer 10

View a Question Summary....................................................................................................................................... 769

View an Answer Summary........................................................................................................................................770
View the Variable Sheet............................................................................................................................................771
Chapter 51: Answer Files: Saving Answer Files...........................................................................................................772
Overview: Save Answers.......................................................................................................................................... 772
Create a Default Answer File....................................................................................................................................773
Suggest an Answer File for Every Assembly........................................................................................................... 774
Save an Answer File During Assembly.................................................................................................................... 775
Switch Answer Files During Assembly..................................................................................................................... 776
Attach an Answer File to an E-mail Message.......................................................................................................... 777
Spell Check Answers................................................................................................................................................ 778
Chapter 52: Answer Files: Using Answer File Manager............................................................................................... 779
Overview: Use Answer Management........................................................................................................................779
Open and Close Answer File Manager.....................................................................................................................780
Add an Answer File to Answer File Manager........................................................................................................... 781
Work with Answer File Manager............................................................................................................................... 782
Add, Modify, and Delete Folders in Answer File Manager....................................................................................... 784
Chapter 53: Using Published and Web-Based Files.....................................................................................................785
Overview: Use Published Files on the Internet........................................................................................................ 785
Register HotDocs to Work with Web Browsers........................................................................................................ 786
Add an Auto-Assemble File on the Internet to a HotDocs Library............................................................................787
Download Auto-Assemble Files for Use Offline........................................................................................................788
Install a Template Set............................................................................................................................................... 789
Check for Template Set Updates..............................................................................................................................790
Upload Answers.........................................................................................................................................................791
Add a Web Page to a HotDocs Library.................................................................................................................... 792
Chapter 54: Assembling Documents Linked to a Database......................................................................................... 793
Overview: Assemble Documents Linked to a Database...........................................................................................793
Select Records During Document Assembly............................................................................................................ 794
Sort Database Records During Assembly................................................................................................................ 795
Filter Database Records During Assembly............................................................................................................... 796
Save Selected Records in an Answer File............................................................................................................... 797

SECTION 9: USING COMMAND-LINE OPTIONS......................................................................................798

Chapter 55: Using Command-Line Options.................................................................................................................. 799
Overview: Command-Line Options........................................................................................................................... 799
Full List of Command-Line Options.......................................................................................................................... 800
Answer File................................................................................................................................................................ 808
Answer Summary...................................................................................................................................................... 809
Clause Name............................................................................................................................................................. 810
Default Answer File................................................................................................................................................... 811
Discard Answers........................................................................................................................................................812
Edit Template............................................................................................................................................................ 813
Exit HotDocs.............................................................................................................................................................. 814
Finish Interview Action.............................................................................................................................................. 815
Hide Library............................................................................................................................................................... 816
HotDocs Auto-Assemble File.................................................................................................................................... 817
HotDocs Auto-Install File...........................................................................................................................................818
Interview Scope......................................................................................................................................................... 819
Copyright 2010 HotDocs Ltd. All rights reserved

xiv

Help Topics for HotDocs Developer 10

Keep Interview Group................................................................................................................................................820

Library File................................................................................................................................................................. 821
Lock Answer File....................................................................................................................................................... 822
Lock Library............................................................................................................................................................... 823
Model Document........................................................................................................................................................824
New Answer File....................................................................................................................................................... 825
No Assembly Window............................................................................................................................................... 826
No Interview...............................................................................................................................................................827
Output File................................................................................................................................................................. 828
Overlay Answer File.................................................................................................................................................. 829
Paper Size................................................................................................................................................................. 830
Paper Tray................................................................................................................................................................. 831
Print............................................................................................................................................................................832
Print Answers Only....................................................................................................................................................833
Print Both................................................................................................................................................................... 834
Print Copies............................................................................................................................................................... 835
Print Duplex............................................................................................................................................................... 836
Print Form Only......................................................................................................................................................... 837
Print Without Dialogs.................................................................................................................................................838
Question Summary.................................................................................................................................................... 839
Save Answers............................................................................................................................................................840
Save Answers Prompt...............................................................................................................................................841
Send to Word Processor...........................................................................................................................................842
Show Library..............................................................................................................................................................843
Start Interview Group................................................................................................................................................ 844
Suggest Save............................................................................................................................................................ 845
Suggest Save New....................................................................................................................................................846
Suppress Unanswered Warning................................................................................................................................847
Template File............................................................................................................................................................. 848
Use Command-Line Options at File Properties........................................................................................................ 849
Use Command-Line Options When Starting HotDocs.............................................................................................. 850
Use Command-Line Options when Using a Shortcut to Start HotDocs....................................................................851

SECTION 10: MODEL DOCUMENTS...................................................................................................... 852

Chapter 56: Creating and Using Model Documents..................................................................................................... 853
Overview: Create a Model Document....................................................................................................................... 853
Convert HotDocs Templates to Model Documents...................................................................................................854
Convert Model Documents to HotDocs Template Format........................................................................................ 855
Model Document Naming Standards........................................................................................................................ 856

SECTION 11: TROUBLESHOOTING....................................................................................................... 857

Chapter 57: Template Development............................................................................................................................. 858
Can't Dynamically Add Merge Text to a Multiple Choice Variable........................................................................... 858
Changing the Order Questions are Asked in an Interview....................................................................................... 859
Checking the Spelling of Library Entries...................................................................................................................860
Child Dialog Always Appearing in Interview Outline Even When it Shouldn't...........................................................861
Choosing Which Word Processor Will Be Used By Default.................................................................................... 862
Comparing the Contents of Two or More Component Files..................................................................................... 863
Converting WordPerfect Templates to Word............................................................................................................ 864
'The Component File Cannot Be Used With This Version of HotDocs' Message Appearing....................................865
Copyright 2010 HotDocs Ltd. All rights reserved

xv

Help Topics for HotDocs Developer 10

Dot Code Formatting Doesn't Seem to Work in True/False and Multiple Choice Options........................................866
Editing Answer Source Records Causes Problems..................................................................................................867
Enabling Multiple Templates for Use with HotDocs Server At Once........................................................................ 868
Entered Answers Getting Overwritten.......................................................................................................................869
Entering Multiple Choice Option Prompts and Merge Text...................................................................................... 870
Fixing Warnings Listed at Warnings Tab..................................................................................................................871
Foreign Characters Are Appearing as Boxes or Question Marks in HotDocs.......................................................... 873
Getting Missing END IF or Missing END REPEAT Errors........................................................................................874
Hiding the End of Interview Dialog During the Interview.......................................................................................... 875
'HotDocs Cannot Play the Macro HD6EditTemplate.Main' Message Appearing...................................................... 876
HotDocs is Creating Database File with Library File................................................................................................ 877
Keeping Users from Editing Templates.................................................................................................................... 878
Limiting Visible Rows but Not Limiting Number of Answers.....................................................................................879
Matching Pairs of Instructions in a Computation Script............................................................................................880
Merging Check Boxes in a Text Template............................................................................................................... 882
Merging Just a Portion of a Date Instead of the Whole Date...................................................................................883
Optional Variables Showing Up as Unanswered in Interview and Document.......................................................... 884
Punctuating a Repeated List of Answers..................................................................................................................885
Receiving 'Invalid Variable Name' Errors When Creating Components................................................................... 886
Reducing Template File Size.................................................................................................................................... 887
Renaming Components Correctly............................................................................................................................. 888
Repeating the Contents of a Single Cell in a Table................................................................................................. 889
Repeating a Single Variable in a Dialog...................................................................................................................890
Test Assembling Template with ASSEMBLE Instructions........................................................................................ 891
Trying to Save an Invalid Computation Script......................................................................................................... 892
Understanding the Difference Between Multiple Choice Options and Merge Text................................................... 893
Using DEFAULT Instruction Causes Extra Repetition.............................................................................................. 894
Using Headers and Footers of Inserted Templates..................................................................................................895
Using INSERT Instructions in a Table...................................................................................................................... 896
Using One Variable in Two Different Dialogs........................................................................................................... 897
Variables Not Working in Word Text Boxes............................................................................................................. 898
Chapter 58: Document Assembly..................................................................................................................................899
Can't Attach Answer File or Document to Outlook 2007 E-mail Message............................................................... 899
Changing Unanswered Text Markers........................................................................................................................900
Discerning Between Template Preview and Actual Template.................................................................................. 901
Downloading HDIs and HDAs as ZIP Files.............................................................................................................. 902
Editing Answers in Assembled Document................................................................................................................ 903
Entering a Two-Digit Year.........................................................................................................................................904
HotDocs Skips Questions When Navigating from Child Dialog................................................................................ 905
Increasing Font Size..................................................................................................................................................906
Installing Support for New Word Processor..............................................................................................................907
Moving Between Questions in Interview Slow.......................................................................................................... 908
Moving to the Next Dialog After Entering a Date or Number.................................................................................. 909
Organizing Files in the Library vs. on the Disk.........................................................................................................910
Overriding an Answer in a Form...............................................................................................................................911
Printing Form Document Takes Incredibly Long Time............................................................................................. 912
Printing Form Document is Off-Center..................................................................................................................... 913
Receiving Error Messages When Launching HDAs, HDIs....................................................................................... 914
Restoring System Defaults to HotDocs.................................................................................................................... 915
Copyright 2010 HotDocs Ltd. All rights reserved

xvi

Help Topics for HotDocs Developer 10

Saving Answers During Interview............................................................................................................................. 916

Specifying Printing Options When Printing Text Documents....................................................................................917
Understanding What Happens When Deleting Templates from the Library............................................................. 918
Updating Changes Made in Word Processor Document in the Answer File, Template............................................919
Updating Cross-References in an Assembled Document.........................................................................................920
Viewing File Names Instead of Template Titles at Library....................................................................................... 921
Chapter 59: HotDocs Automator................................................................................................................................... 922
Double-Clicking Doesn't Create Field as Expected.................................................................................................. 922
Fixing Page Rotation Problems in PDF Templates.................................................................................................. 923
Getting Errors When Automating Table in Form...................................................................................................... 924
Keeping Control Field Text From Appearing on Form..............................................................................................925
Modifying a Single Field in a Group......................................................................................................................... 926
Moving Form Fields Using Keyboard Takes Too Long............................................................................................ 927
Needing Characters in Answer to Appear in Individual Boxes................................................................................. 928
No Interview When Assembling Form Document..................................................................................................... 929
Setting Form Properties Not Taking Effect in Existing Templates............................................................................930
Tabbing Through Fields Sequentially in Form.......................................................................................................... 931
Want Check Box to Use Actual Check Mark............................................................................................................932

SECTION 12: LEGAL NOTICES.............................................................................................................933

Chapter 60: Legal Notices.............................................................................................................................................934
Copyright Information................................................................................................................................................ 934
Software Licence Agreement.................................................................................................................................... 935
Third-Party Software Acknowledgements................................................................................................................. 937

Copyright 2010 HotDocs Ltd. All rights reserved

xvii

Help Topics for HotDocs Developer 10

SECTION 1:
LEARNING ABOUT HOTDOCS

Copyright 2010 HotDocs Ltd. All rights reserved

Help Topics for HotDocs Developer 10

Chapter 1: Becoming Familiar with HotDocs

What Is HotDocs?
HotDocs is an award-winning software application that significantly reduces the time spent generating customized
documents, such as contracts, sales proposals, government and court forms, legal documents, loan applications, and
medical forms.
Using HotDocs, you can transform any PDF document or word processor file into an interactive template by marking
changeable text with HotDocs variables. Then, the next time you want to generate a completed form or text document,
just assemble the interactive template you've created. As you do this, you will be prompted for the information needed in
the document and that information will be merged into the document.
When using HotDocs, you can perfect a template, minimizing the "human error" factor that repetitive typing introduces.
Additionally, you can automate your templates so that verb tenses, gender references, dates, numbers, calculations, and
more are updated automatically as users enter information. Custom interview questions and help resources guide you or
your users through the interview.
Virtually any document in your workflow can be converted to a HotDocs template, including lengthy and complex
documents. HotDocs templates then become your gold standardexperienced colleagues can share their knowledge,
and new colleagues come up to speed faster. Using HotDocs, you can compile an invaluable repository of special
language, unique clauses or terms, correspondence, and more.
The following diagram shows the HotDocs process, from template development to document assembly:

Copyright 2010 HotDocs Ltd. All rights reserved

Help Topics for HotDocs Developer 10

Copyright 2010 HotDocs Ltd. All rights reserved

Help Topics for HotDocs Developer 10

Plan a Template Development Project

Note:
This section assumes you understand, at least conceptually, the template development process.
To step through each topic in this section sequentially, use the Next and Previous links at the end of each topic.
The success of any automation project is in the details. This document describes some of the details you should consider
as you automate your template set.
Specifically, this group of sequential topics covers the following:

1. Planning the project

2. Marking up the document set
3. Preparing to automate the templates
4. Automating the templates
5. Managing the template library
6. Distributing the finished templates
Planning the Project
Gather and Review Documents
Before you can automate any templates, you must first identify which documents you want to include in your set. You
should gather all of these documents into one central location. Documents you should consider are those you routinely
create for clients.
As you review your documents, youll probably realize youve created the same type of document for multiple clients.
While each of these documents contains generally the same content, some documents may contain unique or different
paragraphs or clauses. To capitalize on the work youve already done, create a model document where you copy all of
these text variations. Then, when you automate the template, you can use HotDocs scripting to include or omit these
different paragraphs, depending on the user.

Define the Audience

Another point to consider is your audience. Are you the only one who will use the automated templates, or will you share
your work with others, perhaps in your firm or more broadly? If others will use the templates, how do you plan to distribute
these templates to them? (Template distribution options are covered later in this document.)
As you identify your audience, you should also consider their experience in using the types of documents you are
automating. If your users dont have the same understanding or experience you do with the documents, you may need to
change the way the templates are automated to help them better understand the documents. For example, you may need
to include additional resources to help users better understand how to answer questions in the interview.

Mark Up the Document Set

The process of marking up a document for template automation includes identifying the text in the document that will
change, depending on the person for whom the document is being created. Once identified, you indicate the variable that
should replace that text. Variable information includes names, dates, numbers, and so forth.
How you mark up the document depends on your project and your needs. Following are some options:
Copyright 2010 HotDocs Ltd. All rights reserved

Help Topics for HotDocs Developer 10

You can create a model document using the Model Document Markup Language (or MDML). Once the document
is marked up, you can convert it to HotDocs template format. (See http://support.hotdocs.com/modeldocuments for
details.)
You can manually mark up word processor documents and store the markup information in a spreadsheet
application, such as Excel. You can then take the marked up documents and create templates from them, referring
back to the spreadsheet for specific information about how the template should be automated.
Another option is to simply print a copy of each document in your set and mark up the documents by hand. You
can write directly on the printed document what variables should be used and identify which properties should be
assigned to these variables.
Regardless of which markup option you choose, you should try to address these questions in the markup:

1. How should variables be named? While it might not seem important at first, defining a naming scheme up front will
save you time later when you need to manage a large list of components.
For example, should you name related variables using a consistent format (like Client Name, Client Address, Client
City, Client State, etc.)?

2. Which variables can be reused in other templates in the set? When templates require the same information,
you should mark the variables using the same name. This way, when users save answer files after assembling
a document, the answers can be used with those other documents. This saves the user from retyping common
answers.

3. How should answers in the document be formatted? For example, should text answers be written using all capital
letters? Should number answers be numeric (7) or spelled out (seven)?

4. How much information does the user need to know in order to answer certain questions during the interview? How
should questions be phrased, punctuated, and capitalized? Should they contain examples of possible answers?

5. How much additional information should be included with variables? For example, when should variable resource (or
help) information be included? How much is too much?

6. What other information should be known about the variables? For example, are there restrictions or limits for
answers? Should an answer be formatted a certain way? If the answer must be calculated, what kind of calculation
should it be? (For a complete list of properties you can assign to the different variables, see Appendix 1: Variable
Properties.)

7. What text in the document should be included only under certain conditions? For example, if theres a paragraph
about the clients spouse, but the client isnt married, you wouldnt want to include the paragraph.
Note:
You can also mark in the document where lists of answers should be merged and where boilerplate text should be
inserted. See Appendix 2: Template Instructions for details.

Automate Your Templates

The next step in the process is to actually start automating your templates.
Note:
Detailed instructions on each phase of this process can be found in the HotDocs Help.

Create the Template

You first begin by creating templates from the documents you marked up.
When you create a new template, you can enter a title and a description for the template. Include as much information as
necessary to better identify the file. For example, if the file thats created and saved to disk uses some cryptic file naming
scheme (such as RLWHCP.rtf), you could enter a different title that makes more sense, such as Revocation of Living Will
and Health Care Proxy. In the description you can enter as little or as much information about the template as you feel
necessary. (See Overview: Template and Component Files.)
Copyright 2010 HotDocs Ltd. All rights reserved

Help Topics for HotDocs Developer 10

Also, if you plan to point your templates to a shared component file, you should do so right after you create the template
and before you begin any automation work. That way, variables and other components you create will be saved correctly
to the shared component file. (See Use One Component File for Multiple Templates.)

Replace Template Text with Variables

Once the template has been created, you replace changeable text in the template with variable fields. If youve previously
marked up the template, you should be using variable names and properties you defined in the markup. (See Overview:
Create and Customize Variables.)
As you create variables, you should test them (by clicking the Test button on the component editor). This shows you how
the question will appear to the user. Frequently, testing helps you identify ways to improve the variable question. For
example, if youre testing a Text variable that requires the user to enter a long description, you may realize you forgot to
adjust the answer field height to allow for multiple lines of answer text. (See Overview: Test HotDocs Templates.)

Make Text Conditional

Once you have replaced all of the variable information with variable fields, you should then review the document to
identify sections of text that are optional. To mark these sections, you use IF instructions. IF instructions use a True/False
variable (for example, Is the Client Married?) to determine whether to include text or not. More complicated instructions
usually require more than a simple yes/no question to determine. An example of an expression would be IF YEARS
FROM( Childs Birth Date, TODAY ) <= 17.
There are two different ways you can use conditional text:
First, you can use IF and END IF instructions to include or exclude simple optional text. For example, in an employment
agreement, you may need to include or exclude a paragraph describing a probationary period for the new employee. If the
employee isnt required to complete a probationary period, you wouldnt include information about it.
Second, you can use IF, ELSE IF, ELSE, and END IF instructions to include alternative text. For example, you may have
different versions of a paragraph, only one of which should be included in the assembled document. Using ELSE IF and
ELSE, you can create a series of conditions under which the user determines which text should be included.
See Overview: Make Parts of Templates Conditional.

Repeat Variables to Create Lists

Sometimes there are variables in a template that need to be repeated so users can enter more than one answer. For
example, you may need to list the clients children. Because you dont know how many children a client may have, you
can repeat the Child Name variable. This allows the user to enter as many children as necessary. You accomplish this by
using a REPEAT instruction. You can repeat a single variable, or you can repeat entire sections of text. (See Overview:
Include Lists in Your Documents.)
Note:
At times you may need to repeat the contents of a table. Be aware, however, that when inserting REPEAT instructions
in a table, you must repeat the entire row of a table. To repeat text within a single cell, you must use a Computation
variable that contains the REPEAT instruction.

Group Variables in Dialogs

As you know, variables in the template represent the questions users must answer during the interview. You can organize
these variables into logical groupings, called dialogs. (See Overview: Create Your Own Dialogs.)

Copyright 2010 HotDocs Ltd. All rights reserved

Help Topics for HotDocs Developer 10

Typically, when you create a dialog, you group similar questions together. For example, if the template asks for the
name and address of a client, you could group all of these variables together in a single dialog named Client Information.
Information about the spouse could be asked in a separate dialog, as could information about the case.
If questions in the dialog should be asked only under certain conditions, you can use dialog scripting to include or exclude
those questions. You can also select several different options that control the way the questions appear in the dialog. For
example, you can choose to place all of the questions above the answer fields, or you can choose to place each question
to the left of its answer field.

Test Assemble the Template

Test assembling a template is an imperative task in the template development process. Testing allows you to see the full
interview as the user will see it. It provides an opportunity for you to correct mistakes, as well as fine-tune the interview
process by improving questions and adding other information to make the process easier for the user. (See Overview:
Test HotDocs Templates.)
Its important that as you are testing, you enter many different combinations of answers. This exercises the scripting in
your template and helps you ensure that no matter what answers users enter, the document will be assembled correctly.
As you test assemble a template, you should check for the following things:
HotDocs isnt reporting any errors or warnings that need to be fixed.
The interview outline looks right and operates properly.
Dialogs look right and operate properly.
The document is assembled correctly with no unanswered questions. Answers in the document are formatted
correctly.
If you find problems as you are testing, you can leave the test assembly window open and make changes to the
underlying components. You can then update the test assembly window with your changes. (See Simultaneously Edit a
Template and Test Assemble a Document.)

Organize the Final Template Library

Once all of your templates are automated, you can organize them within the library. How you organize the library depends
on the template set. (See Overview: Use HotDocs Libraries.)
One way you can organize the library is to create folders for storing the templates. Frequently, you can group similar
templates in these folders. For example, wills can be organized in one group or a series of subgroups, depending on the
number and types of wills you have automated. (See Organize the Contents of a Library.)
If you have a large set of templates, it may make more sense to create individual libraries for the template types. Real
estate templates can be stored in one library, while family law templates could be saved in a different library.
Because the items in the library work like shortcuts to the actual files, you must be cautious when working with the actual
files. Moving an actual file without updating the reference in the library will make the file inaccessible from the library. If
you need to move the files in the library, use either the Move command or the Copy command (both commands found in
the Template menu). If you need to update references, choose Properties or Multiple (Edit menu). (See Move Items to
New Locations on Disk, Change the Properties of a Single Library Item, and Change the Properties for Multiple Items in a
Library.)
When you created the templates, you may have added template titles and descriptions for each template you added to
the library. If you did not, this is a good time to do this. Template titles and descriptions are an easy way to help the user
identify the template. You do this by editing the template properties. (See Change the Properties of a Single Library Item.)

Copyright 2010 HotDocs Ltd. All rights reserved

Help Topics for HotDocs Developer 10

Distribute the Templates

The final task in the template development process is to distribute your template sets so they can be used for assembly.
Before doing this, you must first identify who will use your templates.
If youve automated your templates for your own practice, there may not be a distribution planyou can assemble
documents from the same templates you are editing. Or, if youd like to separate template development from document
assembly, you can create a new library and copy your completed templates to a different folder. As you make corrections
to the templates, you can update those files saved in the assembly-only location.
If you plan to share your templates with others in the firm, you should place copies of the files on a network location
for your co-workers. You should restrict access to the templates as much as possible to keep users from inadvertently
changing the files. Some ways you can do this include:
Making the network folder where the templates are saved read-only. (You should also make the template files
themselves read-only.)
Placing a copy of the files on a network and then having users import the library to their local drives for assemblyonly. (See Copy Templates to New Locations and Import One Library Into Another.)
Publishing the template set as a HotDocs auto-install file, which users can then install on their computers. (See
Publish Templates as Auto-Install Files (HDI).)
If you plan to share your templates with those outside the firm, you should publish the templates and distribute them using
the Internet or even a CD.
If you plan to sell your automated templates and distribute copies of HotDocs Player with the templates, you must acquire
a publishing license from HotDocs Corporation, which allows you to redistribute HotDocs Player to your customers.
(HotDocs Player is a free, assembly-only version of HotDocs.) (See Publish and Register Templates for Use With
HotDocs Player.)

Appendix 1: Variable Properties

Following is a list of the different variable types, followed by the properties you can assign to each variable type:
Text Variables
Patterns

HotDocs allows you to assign a pattern to a text variable. The two most common patterns
are telephone number patterns and Social Security number patterns. These patterns
format users answers correctly both in the interview and in the assembled document.

Answer field height

Each variable in a template is asked in an answer-gathering dialog during the interview.

You can control how tall (up to 12 lines) the answer field is in the dialog.

Maximum number of
characters

The maximum number of characters allowed in a text answer is 15,000. If an answer

requires a specific number less than this, you can specify it.

Number Variables
Minimum and maximum
values

You can specify limits for how large or small a number can be. For example, if new
employees are allowed between 10 and 15 paid vacation days, you can specify these
limits so that users dont inadvertently specify more vacation days than they are allowed.

Decimal places

You can indicate the number of decimal places (up to 7) that should be allowed in a
number.

Currency symbol

You can designate whether a currency symbol should be used for a monetary amount.
Predefined options include $, , DM, and , but you can enter your own. (Patterns have a
3-character limit).

Copyright 2010 HotDocs Ltd. All rights reserved

Help Topics for HotDocs Developer 10

Multiple Choice Variables

Multiple Choice options,
prompts, and merge text

Multiple Choice variables allow users to choose an answer from a list of predefined
options. If the options you specify aren't descriptive enough, you can define a prompt
for each option. Additionally, you can specify different text for each option that will be
merged in the completed document.
For example, say you need to merge gender-specific pronouns (like he/she or his/hers)
in the document. To do this, you would create a Multiple Choice variable (Gender) with
two optionsMale and Femaleand then specify merge text that will merge the correct
pronoun (he or she), based on the users gender.

Selection options and styles

You can allow users to select only one option or select multiple options. You can also
designate whether the options appear as buttons or as lists.
By default, all new Multiple Choice variables are set to Select One Only.

Computation Variables
Scripts

Computation variables tell HotDocs to perform a particular task during assembly, such
as insert one template into another or perform some action based on an answer the user
provides. Similarly, they are used to calculate monetary amounts or other figures, or find
the number of years between two given dates, and so forth.

Appendix 2: Template Instructions

HotDocs Instruction

What It Does

IF instruction

Designates that a variable, word, phrase, or paragraph should only be included in the
assembled document when a certain condition is met.

REPEAT instruction

Repeats variables and text so that users can enter more than just one answer.

INSERT instruction

Inserts another template into the current template. (For example, perhaps you have
a separate file that includes boilerplate language. You can use a separate document
for this language and then just insert it wherever you need it.) In most cases, inserted
templates appear "inline" with the template into which they are inserted.

Copyright 2010 HotDocs Ltd. All rights reserved

Help Topics for HotDocs Developer 10

Quick Help Links

Using the links below, you can quickly find topics of interest, particularly if you are a new user.
New and Enhanced Features of HotDocs 10
Complete the HotDocs Tutorials
Get Help Using HotDocs

Starting HotDocs
What Is HotDocs?
Start HotDocs
Overview: Use HotDocs Libraries
Create a Library
Work with Templates and Other Files in a Libary

Automating a Template
Overview: Template and Component Files
Create a New Text Template File
Use Component Manager to Work with Components
Insert a Variable Field in a Text Template
Gather Questions into a Custom Dialog
Create a REPEAT Instruction to Gather a List of Answers
Include or Exclude a Single Version of Text Using a Simple IF Instruction or Expression

Assembling a Document
Assemble a Text or Form Document
Select an Answer File for Assembly
Navigate Through Answer-Gathering Dialogs
Preview the Assembled Text Document
Save an Assembled Text or Form Document
Save an Answer File During Assembly

Copyright 2010 HotDocs Ltd. All rights reserved

10

Help Topics for HotDocs Developer 10

SECTION 2:
GETTING STARTED

Copyright 2010 HotDocs Ltd. All rights reserved

11

Help Topics for HotDocs Developer 10

Chapter 2: What's New in HotDocs Developer

New and Enhanced Features of HotDocs 10
The following new features and enhancements were implemented for the release of HotDocs 10:

Edition Name Changes

HotDocs is now available in three different editions:
New Name

Previous Name

Developer

Professional

Developer LE

Standard

User
Player

Player

Word Processor Support

Word 2010 support: HotDocs now supports the use of Word 2010.
WordPerfect X5 support: HotDocs now supports the use of WordPerfect X5.
(See Install Support for New Word Processors for information on installing support for new word processors.)

Silverlight Interview
Templates intended for use with HotDocs Server can now be test-assembled using the Microsoft Silverlight web
application framework. Unlike the traditional JavaScript-based interviews, where the interview logic is written in an
interpretive language (JavaScript), Silverlight-based interviews are compiled into machine code, which makes them much
quicker. This is especially noticeable in long, complex interviews.
(See View an Interview in a Web Browser for more information.)

Desktop & JavaScript Interviews

Desktop and JavaScript interviews have been updated and improved for HotDocs 10.

PDF Support
The functionality previously provided by HotDocs PDF Advantage is now integrated with HotDocs 10.

Changes to Files, Folders and Registry Keys

HotDocs Files
New Filename

Previous Filename

hotdocs.exe

hotdocs6.exe

hotdocs.dot

hotdocs6.dot

HotDocs.dotx

HotDocs6.dotx

Copyright 2010 HotDocs Ltd. All rights reserved

12

Help Topics for HotDocs Developer 10

hd_api.dll

hd6api.dll

hd_dispatch.exe

hd6dispatch.exe

HotDocs Default Installation Folder

New Folder

Previous Folder

C:\Program Files\HotDocs

C:\Program Files\HotDocs 6

Registry Keys
New Key

Previous Key

HKEY_CURRENT_USER
> Software > HotDocs >
HotDocs

HKEY_CURRENT_USER > Software > LexisNexis > HotDocs 6

HKEY_LOCAL_MACHINE
> Software > HotDocs >
HotDocs

HKEY_LOCAL_MACHINE > Software > LexisNexis > HotDocs 6

Copyright 2010 HotDocs Ltd. All rights reserved

13

Help Topics for HotDocs Developer 10

New and Enhanced Features of HotDocs 2009 HF2

This release of HotDocs contains software corrections and minor enhancements to existing features.

Copyright 2010 HotDocs Ltd. All rights reserved

14

Help Topics for HotDocs Developer 10

New and Enhanced Features of HotDocs 2009 HF1

This release of HotDocs contains software corrections and minor enhancements to existing features.

Copyright 2010 HotDocs Ltd. All rights reserved

15

Help Topics for HotDocs Developer 10

New and Enhanced Features of HotDocs 2009

The following new features and enhancements were implemented for the release of HotDocs 2009:

File Formats
Save component files, library files (both template and answer), and answer files in XML format: HotDocs now
allows you to save component files, library files, and answer files in either XML format (required to use HotDocs 2009
features) or binary format (required to be compatible with HotDocs 2008 and earlier).
Caution:
Please see Compatibility of HotDocs 10 Files with Earlier Versions of HotDocs for a complete description of this format
change.

Unicode Support
Automate templates using international languages: You can now automate your templates using any left-to-right
reading languages that are supported in the Unicode character set. See Use International Characters in HotDocs for
details.

Template Development
Use INSERT instructions to include images: You can now use an INSERT instruction to insert JPGs, PNGs, and
GIFs in a template. Additionally, you can insert RTF documents that contain image files. INSERT image instructions are
appended with the IMAGE keyword.
Use variable INSERTs to specify inserted file names during assembly: Template developers can now use a variable
INSERT in a template, which allows the file path and name of a template file or graphic file to be specified at the time
of assembly, rather than during template development. You must use a Text variable, a Multiple Choice variable, or a
Computation variable that results in text with a variable INSERT.
Navigate repeated dialogs using new button: When completing an interview, end users now add new repetitions to
a repeated series list by clicking the
Add Another button, which is located both after all questions in the dialog as
well as in the dialogs title bar. (Users can no longer use the previously available methods for adding new repetitions to a
dialog.) You can customize the title of this new button on a per-dialog basis by specifying it at the Dialog Editor.
Define a default behavior when automatically disabling irrelevant variables: At Component File Properties, you
can specify a default behavior for irrelevant variables you automatically disable during the interview.
Enter comments about components at the Notes tab: Component editors now include a Notes tab where you can
enter notes about the component, such as an explanation about why the component was created or how it should function
in the interview.
Hide editing buttons on spreadsheet dialogs: You can now keep HotDocs from showing the Edit Row, Insert Row,
and Delete Row buttons associated with a spreadsheet dialog. (The options are still available via buttons and menus,
however.)
Publish templates so they're compatible with HotDocs 2005-2008: HotDocs lets you publish templates created in
HotDocs 2009 so they will still be compatible with HotDocs 2005-2008.

Document Assembly
Install auto-install file libraries to any location: HotDocs now allows you to install a template set library to the same
folder as you install the templates sets.
Copyright 2010 HotDocs Ltd. All rights reserved

16

Help Topics for HotDocs Developer 10

Use new method for adding repetitions to a list of answers: When completing an interview, users now add new
repetitions to a repeated series list by clicking the Add Another button, which is located both after all questions in
the dialog as well as in the dialogs title bar. (Users can no longer use the previously available methods for adding new
repetitions to a dialog.)

HotDocs Automator/Filler
Create PDF templates from fillable PDFs: You can create PDF templates based on fillable PDF documents. When
you create the template, HotDocs first presents you with several options for working with existing fillable fieldsyou can
have HotDocs create mirror fields that match the existing fillable fields. You can also have HotDocs remove all existing
fillable fields. Finally, if the PDF document contains annotations (like sticky notes, stamps, and so forth), you can remove
them from the newly created template. Once you create a template that contains fillable fields, you can attach HotDocs
variables to those fields using an automated wizard.
Save assembled forms as fillable PDFs: You can assemble a document from a template that was created from a fillable
PDF document and save it once again as a fillable PDF document.

Copyright 2010 HotDocs Ltd. All rights reserved

17

Help Topics for HotDocs Developer 10

New and Enhanced Features of HotDocs 2008 SR 2

This release of HotDocs contains software corrections and minor enhancements to existing features.

Copyright 2010 HotDocs Ltd. All rights reserved

18

Help Topics for HotDocs Developer 10

New and Enhanced Features of HotDocs 2008 SR 1

The following new features and enhancements were implemented for the release of HotDocs 2008 Service Release 1:

Word Processor Support

WordPerfect X4 support: HotDocs is now supported for use with WordPerfect X4. (See Install Support for New Word
Processors for information on installing support for it.)

New HotDocs Help Format

The look and feel of the HotDocs Help file has changed. The Help is contained in a single window, with new navigation
options along the top of the window. Searching the help file is much more intuitive and useful. For details, see Get Help
Using HotDocs and Form a Help Search Query

Document Assembly
Send assembled PDF documents to Adobe: If you're assembling PDF-based form documents, you can select a
HotDocs option that will send assembled documents to Adobe Acrobat, rather than HotDocs Filler. See Send Assembled
PDF Documents to Adobe for details.

HotDocs Automator and Filler

Create independent addendums: You can create multiple, independent addendums for forms where each page of the
form represents a duplicate. See Create Independent Addendums for Forms.

Copyright 2010 HotDocs Ltd. All rights reserved

19

Help Topics for HotDocs Developer 10

New and Enhanced Features of HotDocs 2008

The following new features and enhancements were implemented for the release of HotDocs 2008:

Model Documents
Create model documents, independent of HotDocs, and use them to assemble custom documents: Using Microsoft
Word, you can create model documents. A model document is an exemplar document used as the basis for drafting
documents of the same type for specific clients. Using a defined markup language, you identify text that varies from one
client to another. This markup provides an unambiguous description of how a model document should be used to draft
client-specific documents. Once you have a model document, you can use it with HotDocs Player to generate custom
documents for your clients.

Template Development
New Go to Field button added to HotDocs toolbar: When you receive scripting error messages in HotDocs, they
often include the field number for the field where the error is located. To help you quickly find this field in a text template,
HotDocs now includes a

Go To Field button in the HotDocs navigation toolbar.

New Test Panel added: HotDocs now includes a Test Panel, which you can access during a test assembly. Features of
this test panel include the following tabs:
Variable usage: This tab shows how variables are being used in the template. For example, you can review a list
of variables that are asked during the interview, but they aren't used in the document. You can also review which
variables are used in the document but don't appear in the interview. These two lists can help you make sure the
questions you are asking the user are relevant to the document, which ultimately improves the accuracy of the
document.
Warnings: In previous versions of HotDocs, the Warnings tab was included directly in the assembly window.
This tab has now been moved to the Test Panel. It includes information about scripting in the template that may
cause unexpected results in the interview or assembled document. For example, the Warnings tab can report when
SET instructions have been used incorrectly. It can also identify when variables have been asked or referred to
incorrectly.
Go to Template: Using the Go To Template command, you can place your cursor in the Document Preview text
and have HotDocs take you to the same place in the template. This lets you review the automation in that particular
section of the template, perhaps to understand the conditions under which the text was inserted in the document.
Publishing licenses now include annual expiration: Licenses for publishing and registering templates for use with
HotDocs Player now expire annually.
Have HotDocs automatically exclude irrelevant questions from an interview: Rather than write dialog scripts, you
can have HotDocs automatically gray or hide variables that aren't relevant to the document.
Set HotDocs Server interviews so all dialogs in the interview appear in the same view: You can design your
HotDocs Server interviews so that users can view all of the dialogs in an interview at once, on a single Web page.

Document Assembly
Entering Non-English answers during an interview: During a HotDocs interview, you can enter answers in left-to-right
reading languages other than English.
Create a Favorites folder in the template library and add templates to it: You can group the templates you use most
frequently in a Favorites folder of your library.

Copyright 2010 HotDocs Ltd. All rights reserved

20

Help Topics for HotDocs Developer 10

Database Connection
All installations of HotDocs now include the HotDocs Database Connection by default. You do not need to install it
separately.

HotDocs Compare
HotDocs Compare now available separately for purchase: To use HotDocs Compare, you must now purchase a
separate license for it. For details, contact your HotDocs sales representative. NOTE: Starting with the release of
HotDocs 2009, HotDocs Compare is no longer available.

Copyright 2010 HotDocs Ltd. All rights reserved

21

Help Topics for HotDocs Developer 10

New and Enhanced Features of HotDocs 2007 SP1

This release of HotDocs contains software corrections and minor enhancements to existing features. It also contains the
following new features:
New Web link dot code added: You can now use the Web link dot code to insert hyperlinks in your prompts, plain-text
resources, and dialog text elements.

Copyright 2010 HotDocs Ltd. All rights reserved

22

Help Topics for HotDocs Developer 10

New and Enhanced Features of HotDocs 2007

The following new features and enhancements were implemented for the release of HotDocs 2007:
HotDocs supported on Windows Vista: HotDocs is now supported for use on the new Microsoft Windows Vista
operating system.
Support for Microsoft Word 2007 added: HotDocs now supports Microsoft Word 2007.
View document markup in assembled documents: You can now change the formatting of an assembled document to
Markup View and then submit it to an attorney or peer for revisions or corrections.
New command-line options: HotDocs now includes two command-line optionsStart Interview Group and Keep
Interview Group (/sig and /kig). These options are used to control which questions are asked when assembling a group
of related documents; specifically, they keep questions that are already answered in one interview from being asked in
subsequent interviews.
Access HotDocs Help directly from Expression and Instruction Model lists: You can now select a model in either the
Expression models list or the Instruction models list and press Ctrl+F1 to view the help topic for that specific model.

Copyright 2010 HotDocs Ltd. All rights reserved

23

Help Topics for HotDocs Developer 10

New and Enhanced Features of HotDocs 2006 SP1

The following new features and enhancements were implemented for the release of HotDocs 2006 Service Pack 1:

Usability
Better keyboard accessibility: In an effort to make HotDocs compliant with Section 508, you can now access most
commands and elements in various HotDocs windows and dialog boxes using the keyboard. Additionally, HotDocs is now
more compatible with screen readers.

HotDocs Automator and Filler

End-user option of splitting an overflowing answer between the form and the addendum: Form users can now
decide whether multi-line answers should be split between an answer field and the addendum.

Copyright 2010 HotDocs Ltd. All rights reserved

24

Help Topics for HotDocs Developer 10

New and Enhanced Features of HotDocs 2006

The following new features and enhancements were implemented for the release of HotDocs 2006:

Template Development
Allow users to edit assembled document text while viewing the Document Preview tab: Sometimes users may need
to edit the text of a document once it has been assembled. As the developer, you can control editing by marking sections
of a template using a SPAN instruction. This allows users to edit that section of text at the Document Preview tab of the
assembly window. Changes made during assembly can be saved to the answer file so that users can reassemble the
same document later and have their changes reapplied.
Improved implementation for adding additional items to a dialog: HotDocs now provides a new Dialog Element
component that lets you more easily add additional text, hyperlinks, buttons, graphics, lines, and spacing to dialogs.
This implementation includes greater control over how these items appear, including control over whether they appear in
desktop interviews, HotDocs Server interviews, or both. (In previous versions of HotDocs, many of these elements were
added to a dialog using the @ command. This new feature replaces the need to use this command.)
Remove hidden data from assembled Microsoft Word templates and documents: Often, when working in Microsoft
Word templates and documents, hidden data is saved to the file that may compromise the security of the document
or increase the document's file size. You can choose which of these properties should be removed from a template.
Additionally, you can have this data removed from a document after it is assembled.
Use HotDocs dot codes: HotDocs 2006 includes a new feature called dot codes, which allow you to 1) format text
results derived from computation scripts, 2) insert special characters in plain text and template text, 3) format variable
prompts and additional text, and 4) punctuate non-repeated lists of answers.
View an outline of scripting in a Word template: Using the HotDocs Outliner, you can generate an outline of scripting
in the template. This outline can include just a list of instructions used in the template, or it can include variables as well.
This gives you a more condensed view of instructions used in the template.
New schemes added for coloring fields in a template: Two new color schemes were added to help you better identify
instructions in a template. They are Nested and Sequential. Nested marks each level of IF and REPEAT instructions
using a custom color. (For example, all first-level IF instructions will use a specific color, while all second-level instructions
will use a different color, and so on.) Sequential marks each IF and REPEAT instruction field using a custom color. (For
example, the first instruction in a template will be marked using one color, while the next instruction will be marked using a
different color, and so on.)
Display Word templates in Markup View: You can now display a Word template in Markup View, which allows you to
provide non-HotDocs users with easy-to-understand versions of your templates.
Generate default interviews or specify custom interviews for all template types: When automating a template, you
can now select whether HotDocs should generate a default interview for the template or whether HotDocs should use a
custom-scripted interview. If choosing to use a custom interview, you can assign any name to the interview component.
(In previous versions, all interview scripts were required to be named INTERVIEW.) You now designate the name of the
interview component at the Component File Properties dialog box.
Choose which component file provides properties when pointing templates: In past versions of HotDocs, when
you pointed a component file to a shared file, most of the properties for the pointed template would be specified by the
shared component file--not the pointed component file. Now, if you need the pointed template to use its own component
file properties, you make that designation at the component file.
Control how HotDocs inserts returns after inserting instructions in a template: When you insert an instruction in a
text template, by default, HotDocs inserts a return after the instruction. (This return is removed during assembly.) You can

Copyright 2010 HotDocs Ltd. All rights reserved

25

Help Topics for HotDocs Developer 10

select a HotDocs option that inserts these returns only when working with entire paragraphs of text--otherwise, HotDocs
won't insert a return character. (This keeps instructions within a paragraph from breaking up the paragraph text.)
Use new expression models to manipulate text answers: HotDocs includes four new expression models:
REPLACE lets you search a string of text for a given character string and replace the results with new text.
SPACE tests whether the variable is answered. If it is, it merges the answer, followed by a space character. If the
variable is unanswered, it merges nothing ("").
STRIP removes a specified character or characters from the beginning or end of a text answer.
VALUE returns a default value for the variable type if the variable is unanswered. If the variable is answered, the
value is the answer the user specifies.
Use new expression models to manipulate multiple choice answers: HotDocs includes two new expression models:
SELECTION returns a specific selected option of a Multiple Choice answer.
UNION combines all selected (and unique) options from several Multiple Choice variables.
Use new instruction models to erase answers in repeated dialogs: HotDocs includes two new instruction models:
ERASE VAR clears all answers for a specific variable in a repeated dialog.
ERASE DIALOG clears all answers in a repeated dialog.
Create 'Used In' lists for components: You can view which other components in the template use the component you
are currently editing. This information is displayed in the new Used In tab of the component editor. (This tab was formerly
the Asked In tab, which showed only the dialogs that used the variable.)
Store PLAY macros for RTF templates in a Word template and reference the template from the component file:
You can store your post-assembly macros in a template specifically designed for HotDocs. You specify the name of this
file at the Component File Properties dialog box for the template.
Update tables of contents, cross references, indexes, and fields after sending assembled documents to word
processor: You can select a component file property that automatically updates all cross-references (including the table
of contents and index) in an assembled document once the document is sent to the word processor.
New Word menu option for inserting variables, instructions in a Word template: Word users can now more easily
insert instructions such as ASSEMBLE, ANSWER FILE NAME, LANGUAGE, and DEBUG in their templates. The option
for doing so can be found in the new HotDocs menu in the HotDocs toolbar. (Users can also insert other HotDocs field
types (such as variables, REPEAT instructions, and so forth) using this new menu.) Finally, most of these options are also
now available in the Word shortcut menu.
Multiple Choice options included in auto-complete lists: When scripting with Multiple Choice variables, you can
use the auto-complete feature to access lists of options for the Multiple Choice variable. This keeps you from having to
manually enter the options.
Scripting supported in plain-text resources: You can now include variables, IF instructions, and REPEAT instructions
in plain-text resources. This allows you to customize the resource text users see in the interview, based on their answers
to questions.
Save button added to component editors: As you edit components, you can now save your work without closing the
component editor.

Document Assembly
Install support for new word processors without reinstalling HotDocs: In previous versions of HotDocs, if you
installed a new word processor, you had to reinstall HotDocs in order to integrate the two products. Starting with HotDocs
2006, you can install support for new word processors at HotDocs Options.
Copyright 2010 HotDocs Ltd. All rights reserved

26

Help Topics for HotDocs Developer 10

Control font properties of dialog text: You can now specify the font face, size, and color of text used in dialogs. You
can also change the font used for items in the interview outline.
Edit the document while viewing the Document Preview tab (Word users only): If the template provider has allowed
it, you can edit the text of a document while viewing the Document Preview tab. This allows you to make changes to
the document and be able to save those changes in the answer file so they can be reapplied if you ever reassemble the
document.
View variable names for answers in interview: Sometimes you may need to communicate with a template provider
about a specific question in the interview. While answering questions in the interview, you can place your cursor in an
answer field, right-click and choose Variable Name from the shortcut menu.
Simultaneously copy an answer file to the Answers folder and add it to Answer File Manager: Frequently you
receive answer files from other users. You can now open Answer File Manager and choose the Import command to copy
an answer file to the Answers folder and add it to the answer library. You can also double-click on the answer file in
Windows Explorer and the file will be added to the library and copied to the Answers folder.
Mark required answers in a dialog: In addition to marking dialogs that contain required questions in the interview
outline, you can now mark the actual questions in the dialog. Specifically, you can designate the color used for prompts of
required questions as well as control whether an asterisk is used to indicate this.
Follow dialogs in interview outline when moving through interview: A new navigation option, Next Dialog Follows
Outline, has been added. Selecting this option will move you to the next dialog in the interview outline when you click
Next. For example, if you are in a main-level dialog, clicking Next will move you to any inserted dialogs in main dialog.
Clicking Next again will move you to the next main-level dialog, rather than back to the current main-level dialog.
Update published template sets: If you are using a published template set, HotDocs can check for updates to the set at
regular intervals and notify you when updates are available.

HotDocs Automator Filler

HotDocs HFT Driver no longer supported: When creating a HotDocs form template (.HFT) file in previous versions of
HotDocs, you had to use the HotDocs HFT driver, which was only supported for use with Windows 98 and Windows Me.
Starting with the release of HotDocs 2006, these operating systems are no longer supported. Now, when you create new
form templates, you must create them in PDF format.
Look and feel of HotDocs Automator / Filler updated: Several HotDocs Automator and Filler dialog boxes and
windows have been updated.
Keep Field Properties dialog box open as you modify field properties: When applying field properties to form fields,
you can keep the Field Properties dialog box open as you move between fields in the form. This allows you to set
properties for a field and then test to see how the properties affect the underlying field.
Circle static text on a form document: You can now create a field that circles preprinted options on a form.
Send just the part of an answer that overflows to addendum (rather than the entire answer): When specifying
overflow options for a multi-line edit field, you can select an option that sends just the part of the answer that doesn't fit in
the field to the addendum.

Copyright 2010 HotDocs Ltd. All rights reserved

27

Help Topics for HotDocs Developer 10

New and Enhanced Features of HotDocs 6.2 SP1

This release of HotDocs contains software corrections and minor enhancements to existing features.

Copyright 2010 HotDocs Ltd. All rights reserved

28

Help Topics for HotDocs Developer 10

New and Enhanced Features of HotDocs 6.2

The following features and enhancements were implemented for release of HotDocs 6.2:

Default File Locations

Several changes were made to default file locations HotDocs uses.

Template Development
New word processor support: HotDocs version 6.2 is now supported for use with WordPerfect 12.
Troubleshoot problems in templates or scripts: You can now insert a DEBUG instruction either in your scripts or in
your templates to help diagnose problems with automation. The HotDocs Debugger lets you step through a template field
by field, or through a script line by line. It also lets you track variable answers as they change during the interview. Finally,
it lets you view the sequential list of templates and components you are processing. This can help you understand the
path of execution.
Repeatedly loop through an answer or set of answers: The WHILE EXPRESSION instruction allows you to repeatedly
process (or loop through) an answer or set of answers until a certain condition is met, such as a certain answer is found or
a limit is reached.
Increment temporary counters using new instruction: You can use the INCREMENT and DECREMENT instructions
in a HotDocs script to increment or decrement a counter. Previously, this was done using SET instructions such as SET
Num TO Num + 1. These instructions are useful when incrementing counter variables used in WHILE instructions.
Component Explorer redesigned and renamed to Template Manager: The purpose of Component Explorer was
expanded to include template management features, such as template conversion and renaming (see below). This
necessitated a change to the name of the tool. It is now called Template Manager.
Convert templates to HotDocs 6 format or to RTF: Use Template Manager to convert large batches of templates or
clauses either from HotDocs 5 format to HotDocs 6 format. You can also convert WordPerfect or Microsoft DOT templates
to the faster RTF format.
Rename templates: Use Template Manager to rename templates in a library. When renaming templates using this
method, all associated files (such as component files, clause libraries, and so forth) will be renamed, as well. References
to the renamed file will be updated throughout the library.
New template navigation toolbar added to text templates: A new toolbar has been added to word processor templates
that allows you to more quickly work with fields in the template. Specifically:
HotDocs now assigns different colors to the different types of fields in a template using the
Apply Colors button.
Specific fields include variable fields, IF instructions, REPEAT instructions, ASK instructions, and comments. You
can customize the colors used at HotDocs Options.
You can use the new
Label Fields button to label matching IF and END IF instructions as well as matching
REPEAT and END REPEAT instructions. Additionally, where you've nested these instructions, you can identify the
level of nesting. Finally, you can assign the word processor's hidden text property to these comments and labels so
that you can show and hide them during automation.
You can use the new

Match Fields button to quickly find corresponding IF, ELSE, END IF, REPEAT, and END

REPEAT fields. For example, if you place your cursor in a REPEAT field and click the
Match Fields button,
HotDocs will move your cursor to the matching END REPEAT field. This can help you troubleshoot problems
you may experience as you work with these types of instructionsparticularly when there are multiples levels of
instructions.

Copyright 2010 HotDocs Ltd. All rights reserved

29

Help Topics for HotDocs Developer 10

You can use the new Next Field and Previous Field buttons to move from one field to the next. This is
particularly useful when you have several pages in your template that do not have any automation and you don't
want to scroll through these pages manually.
Double-click in Word fields to edit them: You can now double-click in a Word field to bring up the Variable Field dialog
box for that variable. (This requires Word 2000 and above.)
Control whether dialogs are asked automatically: The Dialog Editor now includes an Ask automatically option, which,
when cleared, causes HotDocs not to ask the dialog when it is used in a REPEAT instruction or in an expression that
refers to the dialog's True/False status. This eliminates much of the need for ASK NONE instructions.
Add comments to template fields: You can now add comments to the end of fields. After creating the field in your
template, insert your cursor after the component name (or instruction), type two forward slashes, and then type your
comment, for example, Employee Name //comment.
Keep the End of Interview dialog from appearing in users' interviews: You can select a component file property that
keeps the End of Interview dialog from appearing in the interview. When the user clicks Next at the last dialog in the
interview, HotDocs will either send the assembled document to the word processor or it will display the Document tab,
depending on which End of Interview action the user has defined at HotDocs Options.
Sort components in Component Manager: You can now sort lists of components by type as well as alphabetically.
In Component Manager, sorting is done using the new
options are found on the shortcut menu.

Sort Components button. In other component lists, sorting

Edit components in second component list: If you have two component files open in Component Manager, you can
now edit components in both component files. Previously, you could only modify components in the left pane.
Online test a template from the templatenot the library: You can online test templates directly from the template.
(Previously, you had to close the template and test from the template library.) To do this, press the Shift key as you click
the

Test Assemble button.

New unanswered variable placeholder added: A new unanswered variable placeholder has been added. It inserts the
variable name between square brackets, for example [Variable]. You can choose this option either at the Component
File Properties dialog box or at HotDocs Options.
Generate templates from marked up documents: Markup editors can mark up a document for automation using the
HotDocs Markup Tool. Once marked up, you can use the Template Set Generator to convert the documents to HotDocs
templates. (Contact your HotDocs sales representative for details on purchasing a license for the Markup Tool and
Template Set Generator.) (With the release of HotDocs 2008, support for the Markup Tool and Template Set Generator
was removed.)

Document Assembly
Rearrange entries in a repeated list, and remove or add entries any place in the list: When entering sets of
answers in a repeated dialog, you can now move entries around in the list as well as add or remove entries.
Changes to End of Interview dialog: The following changes have been made to improve the End of Interview dialog:
You can choose which buttons appear in the End of Interview dialog. You make your selections at HotDocs Options.
You can choose to keep the End of Interview dialog from being displayed during the interview. (When hidden,
clicking Next at the last dialog in the interview either sends the document to the word processor or Filler, or
switches the view to the Document tab. You choose which option you prefer at HotDocs Options.)
Buttons for each option have been enlarged and arranged in the order they are most frequently used.
A new button was added that, when clicked, pastes the assembled document into the current word processor. (This
is useful when assembling clause documents.)
Copyright 2010 HotDocs Ltd. All rights reserved

30

Help Topics for HotDocs Developer 10

A new button was added that, when clicked after assembling a form document, moves you to the Form Document
tab of the assembly window. (This allows you to view the assembled form document in the assembly window where
changes you make will be reflected in the answer file.) Before clicking this button, you can choose to have HotDocs
check fields in the form for any answers that overflow.
A new button was added that, when clicked, lets you choose which End of Interview buttons you want in the dialog.
Finish Interview button added to navigation bar: A new button was added to the navigation bar which allows you to
skip any remaining questions in the interview and view the assembled document. You can choose whether to view the
document at the Document tab or whether to send the document to the word processor or HotDocs Filler. HotDocs will
perform this same action when the End of Interview dialog is hidden and you navigate past the last dialog in the interview.
Send assembled documents to the word processor that matches the template type: You now have two options for
sending the assembled document to the word processoryou can either send to the default word processor always or
send to the word processor that matches the template type. You select your preference at HotDocs Options.
New unanswered variable placeholder added: A new unanswered variable placeholder has been added. It inserts the
variable name between square brackets, for example [Variable]. You can choose this option at HotDocs Options. All
variables that do not have a specific placeholder assigned will use this placeholder.
Save As option added to Save Answers dialog box: Now, when you close the assembly window, you have the option
of saving existing answers to either the current answer file or a new answer file.
Choose where assembly window tabs are placed: You can now choose to have the assembly window tabs (Interview,
Document Preview, etc.) displayed either along the top or along the bottom of the assembly window.

HotDocs Automator and Filler

Span a text field across multiple form pages: Often, a text answer needs to flow from one field to another. In most
situations, you can group these related fields as a run-on group and when the answer won't fit in the first line, it will flow
to the next line. However, when the fields span across two or more pages, HotDocs will not allow you to group them. You
can, however, use the Named Group overflow property to span a text field across multiple pages.
Control when form field answers are updated: You can now use the
Instant Update button to control when
HotDocs updates answers in form fields. When selected, HotDocs updates all fields whenever an answer changes. When
cleared, HotDocs updates a field only when it is tabbed to or out of.
New PDF printing options added to HotDocs print function: When printing a nonstandard-sized PDF form using the
HotDocs print function, you can choose the paper size that most closely matches the page size, or you can scale the
content of the page to fit the printable area.

Copyright 2010 HotDocs Ltd. All rights reserved

31

Help Topics for HotDocs Developer 10

New and Enhanced Features of HotDocs 6.1 SP1

The following features and enhancements were implemented for the release of HotDocs 6.1 Service Pack 1:

Template Development
Auto complete while typing component names: As you are creating components, HotDocs can now automatically
complete the component name if what you are typing matches the name of an existing component. This was implemented
to help you distinguish between new and existing components. (You can disable this feature at Tools > HotDocs Options
> Template Development.)
Default Multiple Choice variable to multiple values: Multiple Choice variables that have the Select All That Apply
property set can now be defaulted to multiple values using the Automatically select this option check box at the
Options tab.
SET Multiple Choice variable to multiple values: Multiple Choice variables that have the Select All That Apply
property set can now be SET to multiple values using an instruction (for example, SET MC Variable TO "Option 1|Option
2|Option 3"). (You must use the vertical bar character as the separator between options.)
LIMIT allows numeric expression: The LIMIT instruction now accepts a numeric expression. (Previously you had to use
a single variable to specify the limit.)
Force a paragraph break in text answers: Text variables now include a property called Enter key in multi-line
answers inserts new paragraph mark (). This allows you to control what kind of break is inserted into multiple-line text
when the user presses Enter. Because of this change, the option Enter key action in multiple-line fields was removed
from HotDocs Options.
Drag variables from Component Manager to Automator: You can now drag variables from Component Manager and
drop them directly on a form field in HotDocs Automator. If no field exists where the dropping occurs, a default field will be
created.

Document Assembly
Bypass assembly window: You can now select an option at the Answer File dialog box at the beginning of an interview
that allows you to skip the assembly window and immediately view the assembled document.
Check spelling of answers: You can now spell check answers at the Interview and Form Document tabs of the
assembly window.

Copyright 2010 HotDocs Ltd. All rights reserved

32

Help Topics for HotDocs Developer 10

New and Enhanced Features of HotDocs 6.1

The following features and enhancements were implemented for the release of HotDocs 6.1:

Template Development
New word processor support: HotDocs version 6.1 is now supported for use with Microsoft Word 2003 and WordPerfect
11.
Use the new script editor: Several enhancements were made to the way you write computation, dialog, and expression
scripts. These include customizable color coding for the different keywords and placeholders in a script, as well as Auto
Complete functionality that allows you quicker access to instruction and expression keywords and component names.
Additionally, you can more easily 'comment' blocks of script, and match IFs with END IFs (and REPEATs with END
REPEATs), among other things.
Additionally, now, when including literal text strings in computation scripts, it is much easier to insert return characters as
well as tabs.
Caution:
In previous versions of HotDocs, returns produced from computations were treated as paragraph marks. However, in
HotDocs 6.1, they are now treated as line breaks. You should check existing automation in your template to make sure
this change does not create problems.
Support for HotDocs Database Connection 6.1: The HotDocs Database Connection has been updated to work with
HotDocs 6.
Control answer field widths: Template developers can now specify answer field widths for both regular answer fields
and spreadsheet column widths. These changes are made at each variable's Variable Editor. (Make your changes at the
Advanced tab.)
Tighter integration with document management programs: Those integrating with document management systems
now have greater control over the format of their saved answer files and assembled documents. These options are
specified at the HotDocs Options dialog box, in the File Management folder (and the subsequent Advanced ODMA
Settings folder).
Customize the library Properties tab: HTML-savvy developers can customize the Properties tab of the library window
using custom HTML pages. Properties pages can be customized for individual files in the library, for a single library as a
whole, for the main folder in a library, or for all libraries.
Duplicate button improved: The
Duplicate button functionality (in Component Manager) has been improved.
Template developers can duplicate a single variable, or they can 'batch' duplicate several variables at once.
Better control over inserted templates: HotDocs no longer tries to enforce the requirement that inserted files (such as
templates and clause libraries) must be in the same folder as the host template. If the inserted file exists in a different
folder, however, the path to that folder must be specified in the instruction.
Changes to CLEAR and ADD: When using the CLEAR and ADD instructions to populate a Multiple Choice variable, you
can also ADD prompts for the options.
@COMPUTE and @EXECUTE supported: The instructions, @COMPUTE and @EXECUTE are now officially supported
for use in dialog components.
Publish templates with ASSEMBLE instructions: When publishing templates, you can now select to automatically
publish any templates used in INSERT and ASSEMBLE instructions. (Previously, HotDocs would include templates
specified only in INSERT instructions if this option were selected.)

Copyright 2010 HotDocs Ltd. All rights reserved

33

Help Topics for HotDocs Developer 10

Add templates to a library using drag-and-drop: In addition to using the

Add Template button or command to add
templates to the HotDocs library, you can now drag templates (text, form, and interview) from Windows Explorer to the
HotDocs template library list.
Copy components both ways using Component Manager: When you are displaying a second component list at
Component Manager, you can now copy components from the current component list into it. You can also delete and
rename components in this second list.

Document Assembly
Selecting child dialogs: Selecting grouped child dialogs in an interview is now more intuitiveyou can either select the
preceding check box (or option button) and then click the child dialog icon to display the dialog, or you can click the child
dialog icon immediately. Doing this selects the check box (or option button) for you. (Selecting the check box or option
button is imperative because it tells HotDocs to add the child dialog to the interview outline. It also lets you test whether a
child dialog has been answered, as well as set a child dialogs answered status to true or false.)
Viewing resources: Resources assigned to both variables and dialogs now appear simultaneously in the Resource pane.
(Before, either the variable or the dialog had to have 'focus' for its corresponding resource to be visible.)
Improvements to overall assembly process: Several changes have been made to improve interview speed as well as
dialog navigation.
Customize dialog pane colors: You can now change the background color of the dialog pane in the assembly window.
These changes are specified at the HotDocs Options dialog box.
Better document preview for Word templates: When previewing a Word template or assembled document, you can
now get a much truer view of the document.

HotDocs Automator
Start HotDocs Automator from library window: You can now start HotDocs Automator from the Tools menu of the
HotDocs template library.
New tools: HotDocs includes a new
were also made to existing tools.

Fill Fields tool, which allows you to type text directly in the field. Improvements

Creating form templates: If you create a new form template from Automator, HotDocs will first ask which type of form
you want to createa HotDocs form template (HFT) or a HotDocs PDF template (HPT).
Handling form overflow: When you print an assembled PDF-based form document, and the document contains
unresolved answer overflow, HotDocs gives you three options for resolving the overflow: 1) review and change the
answers or field properties, 2) send all overflowing answers to the addendum, or 3) ignore the overflow and leave the
answer truncated.
Viewing thumbnails: If you are viewing thumbnails in HotDocs Automator or HotDocs Filler, HotDocs highlights the
page number of the form page being viewed. This makes it easier to identify the thumbnail for the page you are currently
viewing, especially in a form that contains many pages.
Send addendum to word processor: If an addendum is created during assembly, you can now send the addendum
directly to the default word processor, rather than the Clipboard. (This option is only available from the HotDocs assembly
window. It is not available in HotDocs Filler.)

Copyright 2010 HotDocs Ltd. All rights reserved

34

Help Topics for HotDocs Developer 10

New and Enhanced Features of HotDocs 6.0

The following new features and enhancements were implemented for the release of HotDocs 6.0:

Template Development
Use the new template library: The new template library contains several additional buttons and new menu items that
allow you to perform multiple template development and document assembly tasks, including managing the contents
of the library more efficiently. The toolbar and menus also make it easier to access other HotDocs tools, including
Component Manager, HotDocs Options, Answer File Manager, Component Explorer, and the Assembly Queue.
The library window is divided into two panes: the left pane shows the list of templates, clause libraries, and other
library items, while the right pane shows tabbed views of either the items properties (such as the file type and title) or a
preview of the library item.
Create a new template: HotDocs gives you more control over the type of template you want to create by including a
Type drop-down list at the New Template dialog box. This lists all the different template formats available, based on the
supported word processors you are currently using. Template titles are automatically generated based on template file
names; however, you can change the title to something more descriptive.
Use the new HotDocs editing toolbar: The look of the existing HotDocs editing toolbar has changed, and three new
buttons have been added:
The
Clause Library button displays the clause library associated with the template. From here, you can create
clauses, edit existing clauses, remove clauses, and perform several other tasks relating to clause management.
The
Edit Component button bypasses the Variable Field dialog box and lets you edit the component properties
of a variable while at the template.
The HotDocs Help button makes it easier for you to access information in the Help files directly from the word
processor window.
Create variable fields and variable components: Now when you create variables, there is greater distinction between
the variable field and the variable component. For example, when you first create a variable at the template, the Variable
Field dialog box appears, where you can assign a variable type, name, and any field-specific properties. Then, from the
Variable Field dialog box, you can click the
Edit Component button to display the Variable Editor. At this dialog box,
you can assign component-specific properties, such as prompts and resources.
Assign either default or field-specific formats: You can assign answer formats, field formats (such as field widths,
alignment, and fill characters), and merge text (for Multiple Choice variables) either at the Variable Field dialog box, or
the Variable Editor. If you assign them at the Variable Field dialog box, they are available for that specific instance of the
variable only. If you assign these properties at the Variable Editor, they become a default property of the component and
will be available each time you use the variable in the template.
Use Multiple Choice variables: At the Multiple Choice Variable Editor, you can now provide prompts for each multiple
choice option. Also, if you want to further customize each row of options, you can do so by clicking the Options tab and
making your changes. These include adding longer prompts and merge text, and pre-selecting options for the user.
Assign resources (formerly known as variable and dialog help): The name for this type of help has been changed
to Resources to better distinguish between HotDocs Help (the documentation provided with the software) and template
developer help (the help assigned by you). You also can now use an HTML Help (.CHM) file as a source file for variable
and dialog resources.
Use the new Component Manager: With the enhanced distinction between fields and components, Component
Manager becomes the preferred method for editing components in a template, including variables and dialogs.
Component Manager is now a sizeable dialog box that can be arranged next to the template window so that you can work
Copyright 2010 HotDocs Ltd. All rights reserved

35

Help Topics for HotDocs Developer 10

in both windows simultaneously. Using Component Manager, you can edit as many components at a time as you want.
You can also drag variables from Component Manager and drop them directly in the template.
Share components between component files: The process for sharing component files has been improved. For
example, the Pointed Component File button in the Component Manager toolbar makes it more apparent a component
file is pointed (for example,
more intuitive.

versus

), and the actual process of finding the component file and pointing it is much

Change component file properties: At the Component File Properties dialog box, you can now specify a product title
for the template you are creating. You can also have HotDocs hide the interview outline for the template during assembly
as well as have HotDocs generate default dialog titles. The interface for several existing properties has changed, as well.
Copy components using Component Manager: You can expand the Component Manager window to show another
component files list of components, from which you can copy into the current component file. (You can no longer copy out
of the current component file, however.)
Use IF, INSERT, ASK, and REPEAT instructions: All of the dialog boxes for inserting IF, INSERT, ASK, and REPEAT
instruction fields have changed. At each of these dialog boxes, you can choose a specific type of field you want to merge,
and then edit the underlying component.
Use clauses and clause libraries: The process of creating clauses and clause libraries is now much easier. You can
open a clause library from the template-editing toolbar, and it can stay displayed as long as you need, allowing you to
work in both the template and the clause library simultaneously.
Use Dialog Editor to edit dialogs: The Dialog Editor includes tabs for customizing a dialog. A Find option has also been
added to make searching for specific variables, clauses, or dialogs easier. When you are at the Script tab of the Dialog
Editor, you can click the Variables drop-down button and select Variables in Dialog to see only the variables used in
that specific dialog. (This makes it easier to create dialog scripts since you can limit the list of variables to show only those
used in the current dialog.)
Assign titles to dialogs: You can now assign titles to dialogs. The dialog title replaces the dialog name in the interview
outline.
Change the layout of a dialog: In earlier versions of HotDocs, to change the placement of variables in a dialog, you had
to test the dialog and make your changes directly in the test dialog. Now, you can click the Layout tab of the Dialog Editor
and drag-and-drop variables there.
Simultaneously test and edit variables, dialogs, and scripts: You can simultaneously test and edit components within
a template (such as variables, dialogs, and scripts). When you do, HotDocs displays the variables and any corresponding
answer fields in a test assembly window. You can leave that dialog open and make changes to the component and then
update the dialog to see the changes implemented. Once you click OK at the Variable Editor, the changes are saved to
the component file.
Simultaneously test assemble and edit a template: You can test assemble all or a portion of a template while
simultaneously making changes in the underlying template text. HotDocs will update the assembly window with changes
you make.
Save answers used for testing once: When you test a variable or test assemble a document, you are prompted to save
your answers. Once you save them (using Test Answer File as the file name), HotDocs uses that test answer file for each
subsequent test assembly. If needed, you can specify a new answer file or use a different answer file at the assembly
window.
Use Component Explorer: The Component Explorer tool lets you more closely manage components across a large
number of component files, including removing unused components, renaming components in both the component and
template file, and copying and pasting components between files.

Copyright 2010 HotDocs Ltd. All rights reserved

36

Help Topics for HotDocs Developer 10

Document Assembly
Choose an answer file for assembly: When you first select a template for assembly, HotDocs displays the Answer
File dialog box, which allows you to choose an answer file to use with the assembly. (You no longer choose any other
assembly options, such as assembling Question/Answer summaries, or viewing only unanswered variable questions. All
of those options are now controlled directly in the assembly window.)
View the new assembly interface: Once an assembly has started, the assembly window appears. By default, it is
divided into three panes: the interview outline (or left pane) lists all the dialogs and variables asked in the template. When
users click one of these items, the corresponding dialog appears in the dialog pane (or right pane). Users enter the
required information in the answer fields and proceed through the interview until all the answers have been given. The
interview outline is dynamic so items can be added and removed, depending on answers the user provides. Finally, if the
template developer has provided helpful information about a dialog or a specific variable, that information appears in the
third pane, the resource pane (below the dialog pane).
Navigate an interview: You can click items in the interview outline in any order to complete the interview. You can also
click buttons in the navigation bar at the bottom of the dialog pane.
Use the new assembly toolbar buttons: The assembly toolbar buttons let you perform several different tasks, such
as work with answers and answer files, send the assembled document to a word processor (so you can edit it), view the
Assembly Queue, access HotDocs Options, view the resource pane, and perform other general tasks.
Use the tabbed views of the assembly window: The assembly window contains several tabs that let you change your
view of the assembly process. You can view any of these tabs at various times during assembly and the information
contained therein will be current. These tabs include:
Interview displays a three-paned window that includes the interview outline, the dialog pane, and the resource pane.
Preview shows a rough preview of the document so far as it has been assembled.
Question Summary displays an HTML-based summary of the questions in the template.
Answer Summary displays an HTML-based summary of the questions and answers provided during the interview.
Variable Sheet displays a spreadsheet-like summary of variables, prompts, answers, and variable types.
For the most part, the contents of these different tabs can be saved as word processor or HTML documents, and can be
attached to e-mail messages.
View the End of Interview dialog: When you complete an interview, the End of Interview dialog appears. It contains
information about unanswered variables as well as gives instructions and options for working with the assembled
document. (The End of Interview icon always appears in the interview outline.)
Use the resource pane: HotDocs now displays template developers resource information (formerly known as variable or
dialog help) in the resource pane of the assembly window. By default, this pane is continually displayed; however, you can
hide and show it as needed. You can also specify an option (at HotDocs Options) that displays a resource button next to
answer fields that contain resources.
Preview the assembled document: As you complete an interview, you can click on the Preview tab to view your
document during assembly. Any answers you have given are merged into the text, while any answers that are still needed
are marked by unanswered variable placeholders. You cannot edit the text in the Preview tab, but once you finish an
assembly, you can send a copy of the document to the word processor for post-assembly editing.
Because of the way HotDocs renders assembled text in the Preview tab, the document sometimes will not show the
formatting you see when you send a copy of the assembled document to the word processor.
Use Answer File Manager: The Answer File Manager has a newly designed interface (including a new toolbar) that
makes it easier to view the properties as well as the contents of an answer file.

Copyright 2010 HotDocs Ltd. All rights reserved

37

Help Topics for HotDocs Developer 10

Change answer files during assembly: As you assemble a document, you can change the answer file you are using.
When you do, HotDocs lets you save the current answer file and assembled document before you load a new answer file.
Attach answer files, assembled documents to e-mail messages: You can attach answer files, assembled documents,
and question and answer summaries to e-mail messages.
Manage multiple assemblies using the assembly queue: When you select multiple templates for assembly, HotDocs
automatically displays the Assembly Queue dialog box, which lists each template and its assembly status. Using this
dialog box, you can change the order in which documents will be assembled, as well as add assemblies to and remove
them from the queue.
Change your HotDocs Options (formerly known as Settings or Preferences): HotDocs now provides one central
location--the HotDocs Options dialog box--to control how HotDocs operates. General options include template
development, interview, and document assembly preferences, as well as file location management.

HotDocs Automator/Filler
Changes to HotDocs Automator: Some changes have been made in HotDocs Automator to more tightly integrate
it with the new HotDocs 6 interface. These include new toolbar buttons and menu items, as well as minor changes in
various dialog boxes. Additionally, the default field colors have changed, and several pre-designed color schemes have
been provided.
Changes to HotDocs Filler: Some changes have been made in HotDocs Filler to more tightly integrate it with the new
HotDocs 6 interface. These include some new toolbar buttons and menu items, as well as minor changes in various dialog
boxes. Additionally, in the Document tab of the assembly window, you can type your answers directly in the form fields.
If the template developer has created a custom interview (or allowed HotDocs to generate a default interview), you can
move between the Interview and Document tabs to complete the interview.

Copyright 2010 HotDocs Ltd. All rights reserved

38

Help Topics for HotDocs Developer 10

New and Enhanced Features of HotDocs 2005 SP3

The following new features and enhancements were implemented for the release of HotDocs 2005 Service Pack 3:
Support for WordPerfect 13 added: HotDocs version 2005 SP3 is supported for use with WordPerfect 13.

Copyright 2010 HotDocs Ltd. All rights reserved

39

Help Topics for HotDocs Developer 10

New and Enhanced Features of HotDocs 2005 SP2

The following new features and enhancements were implemented for the release of HotDocs 2005 Service Pack 2:

Template Development
Rename multiple components simultaneously: You can now select multiple components at Component Manager and
rename them all at once.
Limit the number of rows in a spreadsheet: When a dialog is repeated as a spreadsheet, you can control the number
of rows that are displayed in the dialog. (This option simply controls the number of rows that are displayedusers are still
able to enter as many answers as they need.)
Map Text variables to Multiple Choice values (and vice versa) in an answer source: When mapping an answer
source, you can map a Multiple Choice variable to a text value. You can also map a Text variable to a multiple choice
value.
Create an answer source that links a dialog to a Time Matters Contacts or Matters record: You can now link an
answer source to a Time Matters Contacts or Matters record. This allows you to retrieve information you're already storing
in Time Matters and use that information in your documents. When creating the answer source, you can also designate
whether changes to answers can be written back to Time Matters. (To create this answer source, you must be using Time
Matters 7.0 or later.)

Document Assembly
Expand and collapse all folders at once in the library: You can now expand or collapse all subfolders in the template
library. This makes it easier to quickly view or hide template lists in the library. (This command is available in the library
View menu.)
Choose a color for additional text: When customizing the appearance of dialogs in an interview, you can now assign a
different color to additional text. This may be useful if you want to distinguish additional text from other text in the dialog.
You do this at the Dialog Appearance folder of HotDocs Options.
Open Windows Explorer from the template library: You can click on a reference to a template in a library and choose
Go To from the Template menu. This opens the folder where the template file is saved.
View resource buttons for all answer fields at once: When viewing a dialog with answer field resources, you can now
choose to display the resource button for all answer fields at once, or you can choose to display the button only when
you are viewing that specific answer field. (This new functionality changes the available settings at Tools > Options >
Interviews and Dialogs > Show answer field resource button.)

Copyright 2010 HotDocs Ltd. All rights reserved

40

Help Topics for HotDocs Developer 10

New and Enhanced Features of HotDocs 2005 SP1

The following new features and enhancements were implemented for the release of HotDocs 2005 Service Pack 1:

Template Development
Save component files in HotDocs 6 or HotDocs 2005 format: When HotDocs 2005 was released, you had to upgrade
your component file to the latest version. You can now designate a component file property that saves the component file
either in version 6 format (so you can continue to use the template with HotDocs 6.x) or in version 2005 format (so you
can use all of the functionality of HotDocs 2005).
Caution:
If you want to use HotDocs 2005 to develop your templates but you want them to be compatible with HotDocs 6, do
not use any HotDocs 2005-specific features (such as non-breaking spaces) or the features implemented in this release
(described in this topic). If you do, you may see unexpected results.
Changes to Component File Properties dialog box: The Component File Properties dialog box has been redesigned
and now includes tabs to differentiate between the different types of properties.
Add titles to variables: You can now specify a title, or alternate name, for a variable. Sometimes you use variable names
that are useful for you during template development, but not useful for users during an interview. For example, maybe
you name your variables with some type of variable notation, like Client name TE. To a user, this name, if seen in an
interview, may not make much sense. Here, a title (Client's Name) can be used in place of the variable name.
Assign a label to the entire repeated series: You can now assign a label to the entire repeated series, which lets you
customize the dialog title for each individual repetition in the list.
Copy Multiple Choice options, prompts, and merge text and paste them into other spreadsheets: You can copy
data from other spreadsheets or tables and paste it into the Multiple Choice Variable Editor spreadsheet. Similarly, you
can copy the contents of a Multiple Choice Variable Editor spreadsheet and paste it into other tables or spreadsheets
(including other Multiple Choice variables).
Automatically set repeat style when creating a REPEAT field: When you create a REPEAT instruction in the
template (using the REPEAT Field command), HotDocs will automatically suggest Repeated Series as the dialog Style.
Previously, you had to manually specify a repeat style.
Specify merge text on as-needed basis: You can now include merge text for Multiple Choice options on an as-needed
basis. Previously, if you included merge text for one option, you had to provide it for all options. However, now you can
provide it for only those options that require it.
New repeated list format added: When you create a new template, HotDocs includes a, b in the example format lists for
repeated answers. This will format a series of answers as apples, oranges, cherries (excluding any conjunction). To use
the format in existing templates, simply type it in the Format box, either at the Multiple Choice Variable Editor or at the
REPEAT Field dialog box.

Document Assembly
Sort spreadsheets (including answer sources) during the interview: You can now sort the contents of a spreadsheet
in alphanumeric order.
Print contents of the Preview tab at library window: You can select a text or form template at the template library and
print a blank copy of it.
View file names in library's item list: You can now view either the template's title in the library list, or you can view the
template's file name. Additionally, when searching for a specific template, the search is performed on the title, description,
and file name. (Previously, HotDocs would search just the title and description.)
Copyright 2010 HotDocs Ltd. All rights reserved

41

Help Topics for HotDocs Developer 10

HotDocs Filler
Skip conditioned-out fields during direct-fill assembly: During direct-fill assembly of a form document, HotDocs will
now skip fields that are conditioned (and resolved as false).

Copyright 2010 HotDocs Ltd. All rights reserved

42

Help Topics for HotDocs Developer 10

New and Enhanced Features of HotDocs 2005

The following new features and enhancements were implemented for the release of HotDocs 2005:

Template Development
Database Connection: HotDocs Database Connection is now included with all licenses for HotDocs Developer.
Database Connection allows you to retrieve answers from a database.
Changes to HotDocs Server templates and interviews: HotDocs Server 2005 has been redesigned to display browserbased interviews that more closely match desktop interviews. When creating templates for use with HotDocs Server,
you must first enable them to be used on the server. (You do this at the Component File Properties dialog box.)
Once templates are enabled, they will be checked for features that are incompatible with the server or Web browser.
Additionally, enabling the template will let you test the template in a simulated browser environment.
Caution:
To use the new style of interviews, you must regenerate the JavaScript (.JS) files and HotDocs Variable Collection
(.HVC) files. You can do this by republishing your templates. (First make sure they are enabled for HotDocs Server.)
Override parent template headers and footers with those in inserted templates: When you insert templates and
clauses, you can now select options that allow you to keep the headers and footers in the inserted files, rather than
have them overwritten by the parent template's headers and footers. This is useful if you either want to create a master
document containing several subdocuments, or you want the headers/footers defined in one of the inserted templates to
be the headers/footers for the entire document.
Use symbol fonts for answers in text templates: In text templates, can now assign symbolic character fonts (as well
as standard character fonts) for answers in your document. This is useful if users' answers must appear in a non-standard
font, such as a bar code.
Use non-breaking spaces and hyphens in variable formats: Often, you need a user's answer to stay on a single line
in the assembled document. Now you can assign an example format that will keep answers from breaking at the end of a
line of text.
Access a Microsoft Outlook Contacts list: You can now link an answer source to your address book in Microsoft
Outlook. This allows you to retrieve information you're already storing in Outlook and use that information in your
documents.

Document Assembly
Edit answers directly at the Document Preview tab: When previewing an assembled document, you can choose to
have HotDocs identify the answers you have entered. Once you are viewing these answers, you can edit the answers (by
double-clicking on the field). (This feature is available to Microsoft Word users only. Additionally, it is only enabled if the
template provider has enabled it.)
Navigate through answer fields in the document: If you are viewing either an assembled Word document or an
assembled form document, you can use the new Navigation Bar to move between answers fields on the document.
Specifically, you can move between all answers, unanswered questions only, or matching answers (for example, just
those answers that are the same). Additionally, you can have HotDocs take you to the dialog in the interview where
the question is asked. (Moving through fields at the Document Preview tab is available to Microsoft Word users only.
Additionally, it is only enabled if the template provider has enabled it.)
Compare different versions of a document at the assembly window: When HotDocs Compare is installed, you can
answer questions in the interview one way, save a snapshot of the document, and then answer questions differently
so you can compare versions of the document. Additionally, you can save multiple versions of a snapshot to use in the
Copyright 2010 HotDocs Ltd. All rights reserved

43

Help Topics for HotDocs Developer 10

comparisons you are doing. (HotDocs Compare is available to Microsoft Word users only.) NOTE: Starting with the
release of HotDocs 2009, HotDocs Compare is no longer available.
Copy templates to new locations on disk: In addition to moving templates using the Move Templates command, you
can copy templates to new locations using the new Copy Templates command. When you copy templates, you create a
copy of the template in a new location. Additionally, you can designate that the copied file be marked as read-only.

Copyright 2010 HotDocs Ltd. All rights reserved

44

Help Topics for HotDocs Developer 10

Chapter 3: Installing HotDocs

What Is HotDocs?
HotDocs is an award-winning software application that significantly reduces the time spent generating customized
documents, such as contracts, sales proposals, government and court forms, legal documents, loan applications, and
medical forms.
Using HotDocs, you can transform any PDF document or word processor file into an interactive template by marking
changeable text with HotDocs variables. Then, the next time you want to generate a completed form or text document,
just assemble the interactive template you've created. As you do this, you will be prompted for the information needed in
the document and that information will be merged into the document.
When using HotDocs, you can perfect a template, minimizing the "human error" factor that repetitive typing introduces.
Additionally, you can automate your templates so that verb tenses, gender references, dates, numbers, calculations, and
more are updated automatically as users enter information. Custom interview questions and help resources guide you or
your users through the interview.
Virtually any document in your workflow can be converted to a HotDocs template, including lengthy and complex
documents. HotDocs templates then become your gold standardexperienced colleagues can share their knowledge,
and new colleagues come up to speed faster. Using HotDocs, you can compile an invaluable repository of special
language, unique clauses or terms, correspondence, and more.
The following diagram shows the HotDocs process, from template development to document assembly:

Copyright 2010 HotDocs Ltd. All rights reserved

45

Help Topics for HotDocs Developer 10

Copyright 2010 HotDocs Ltd. All rights reserved

46

Help Topics for HotDocs Developer 10

Compatibility of HotDocs 10 Files with Earlier Versions of HotDocs

This topic describes the compatibility of files between earlier versions of HotDocs and HotDocs 10:

Installation of Program Files

When you install HotDocs Developer 10 over earlier versions of HotDocs Developer or Professional Edition (starting with
HotDocs 6), it overwrites that installation.

Library Files
Template Libraries
Template libraries created and saved in HotDocs 2008 and earlier were saved in binary format. Starting with the release
of HotDocs 2009, however, template libraries can be saved in either binary format or as XML. When you open an existing
template library in HotDocs 10, HotDocs keeps it in binary format until you either manually convert the file to XML format,
or you attempt to use foreign characters in the properties of the library, at which time HotDocs will prompt you to save
the file in XML format. (To manually save the file in either format, choose Save Library As from the File menu and
then choose the option you want from the Save as type drop-down list. Foreign characters are characters that are not
compatible with your system's default language.)
Answer Libraries
HotDocs 6 through HotDocs 2008 supported binary answer libraries (or answer libraries with the .HAL file name
extension). Starting with the release of HotDocs 2009, however, HotDocs now supports both binary answer libraries and
XML-based answer libraries (which use the .HDL file name extension). By default, HotDocs will continue to use binary
answer libraries as long as the answer file properties of items in the library use characters that are compatible with your
system's default language. If you define answer file properties that contain foreign characters, HotDocs will create an
XML-based answer library (so that it can properly display these characters in the Properties tab of the library window.)
Caution:
If you are working in HotDocs 10, but the library needs to be compatible with HotDocs 2005-2008, do not use any
foreign characters (for example, characters that are not compatible with your system's default language) in the library
properties. Any foreign characters you use will appear as boxes or question marks in HotDocs 2005-2008.

Templates and Component Files

If you are upgrading from earlier versions of HotDocs (starting with HotDocs 6), you will be prompted to convert your
component files to HotDocs 2009-10 format. When you make this choice, you can choose to either convert the file to the
current, HotDocs 2009-10 format, or you can choose to keep it in the format it was last edited in. So, for example, if you
are upgrading from HotDocs 2005, you can choose to convert the file to HotDocs 2009-10, or you can choose to keep it in
HotDocs 2005 format.
Once you convert a component file to HotDocs 2009-10 format, you can make it backwards-compatible by specifying a
specific format at the Component File Properties dialog box of Component Manager. (See Change Component File
Properties.) If you are using HotDocs 10 to automate templates for use with a pre-2009 version of HotDocs, do not use
any new features that arent supported in the earlier version or your templates may not work correctly. This includes using
foreign characters (or characters that are not compatible with your system's default language) in component prompts,
titles, resources, etc. See the New Features section of this help file for a list of features implemented in each release of
HotDocs.

Copyright 2010 HotDocs Ltd. All rights reserved

47

Help Topics for HotDocs Developer 10

Note:
If you need to keep several templates in their existing pre-HotDocs 10 format and you don't want to be prompted to
make this selection on a template-by-template basis, you can use Template Manager to change the component file
format for several files at once. See Modify Component File Properties Across Multiple Files for details.

Answer Files
HotDocs 6 through HotDocs 2008 support two types of answer filesbinary answer files (.ANS) and XML answer files
(.ANX). Starting with HotDocs 2009, answer files are saved in XML format only. This means that if you open a binary
answer file (an .ANS file) in HotDocs 10, change one or more answers, and then save, the answer file will be saved as
XML. The file extension will not be changed, but will continue to be .ANS even though the file is in XML format.
If you are using HotDocs 10 to create answer files for use with a pre-2009 version of HotDocs, you must save the answer
file in a backwards-compatible format. Specifically, if you need to use the answer file with HotDocs 2005 through HotDocs
2008, you must save the file as a HotDocs 2005-2008 answer file. You can select this format at the New Answer File
dialog box or the Save Answer File As dialog box. You can also select it at the Properties dialog box for the answer file.
Any unsupported foreign characters you use will appear as boxes or question marks in HotDocs 2005-2008.
Note:
HotDocs 10 answer files can be used with HotDocs 2008 SR2 without making the files backwards compatible.

Copyright 2010 HotDocs Ltd. All rights reserved

48

Help Topics for HotDocs Developer 10

System Requirements
To ensure the best performance using HotDocs, please note the following requirements for hardware and software:

Hardware
900 MHz processor (2GHz, recommended)
1 GB RAM (2 GB, recommended)
50 MB hard disk storage
1024 x 768 screen resolution with at least 16-bit color

Software
Windows XP (SP1 or higher), Windows Vista (32-bit or 64-bit), or Windows 7 (32-bit or 64-bit)
Microsoft Internet Explorer 6.0 or later
Microsoft Word 2000, XP, 2003, 2007, or 2010
Corel WordPerfect 8, 9, 10, 11, 12, X3, X4, or X5
Caution:
WordPerfect X3 SP2 and later are the only versions of WordPerfect supported for use on Windows Vista and
later.
Microsoft .NET Framework 3.5, Microsoft Silverlight 3 Runtime, and Microsoft Silverlight 3 SDK (These are only
required if you want to view Silverlight-based interviews for your HotDocs Server-enabled templates.)
Tip:
You can download the Microsoft .NET Framework and Silverlight requirements from the following sites:
o

http://www.microsoft.com/NET/

http://www.microsoft.com/silverlight/get-started/install/default.aspx

http://www.microsoft.com/downloads/details.aspx?FamilyID=1ea49236-0de7-41b1-81c8-a126ff39975b

Databases
If you plan to integrate HotDocs with a database, you must have one of the following applications or servers installed:
Microsoft Access
Microsoft SQL Server
Oracle 8i or 9i with the OraOLEDB OLEDB provider
Most other ODBC-compliant database

Copyright 2010 HotDocs Ltd. All rights reserved

49

Help Topics for HotDocs Developer 10

Install HotDocs
When you insert the HotDocs installation disk in your CD-ROM drive, a CD browser window should automatically appear.
From this window, you can view the Readme and install HotDocs. Once installation has started, HotDocs prompts you for
all of the information it needs to complete the process.
Before installing HotDocs, make sure your computer meets the minimum requirements necessary for using HotDocs. (See
System Requirements.)
To install HotDocs

1. Close all open programs, especially any word processors or existing versions of HotDocs you may have open.
2. Insert the HotDocs installation CD into your CD-ROM drive. The CD browser window appears.
3. Click Install HotDocs Developer. The installation program begins installing HotDocs.
4. Follow the on-screen prompts to complete the installation.
Note:
To manually install HotDocs, select Run from the Start menu. If you are running a 32-bit operating system, type
D:\setup. If you are running a 64-bit operating system, type D:\setup64 (substitute the correct drive letter if your
CD-ROM drive is not mapped to D:\). Follow the on-screen prompts to complete the installation.
For a description of how HotDocs is installed, see Understand HotDocs Installation.

Copyright 2010 HotDocs Ltd. All rights reserved

50

Help Topics for HotDocs Developer 10

Understand HotDocs Installation

When you install HotDocs, two different installations actually happenthe HotDocs Setup and the Current User Setup.
This two-part installation process not only allows the program be installed just once for multiple users on a single
workstation, but it also allows each user who logs on to the workstation to have his or her own custom files and settings.

HotDocs Setup
When you first install HotDocs (see Install HotDocs) from setup.exe (for 32-bit operating systems) or setup64.exe (for 64bit operating systems), HotDocs installs the program files needed to use HotDocs, including any executable files used to
run HotDocs. Among others, it also installs the HotDocs Help files and a folder containing scripts, images, and stylesheets
which are needed for developing HotDocs Server templates. These files are installed, by default, to C:\Program Files
\HotDocs. This location is not user-specific, which allows all users of a single workstation access to the files.
As HotDocs installs these files, it registers information about them in the Local Machine key of the Windows System
Registry. For example, the Registry stores information about where the executable file for HotDocs is located on disk, as
well as which word processors HotDocs supports. It also sets some preliminary file location information for the various
files HotDocs uses, including information about library files and template set files. All of this information must be registered
in order for HotDocs to work correctly.

Current User Setup

When you install HotDocs, the installation creates a folder named Source in the HotDocs program folder. This folder
contains several files, including word processor macro or startup files, the user spell-checking dictionary, and the HotDocs
tutorial files.These files must be in user-specific folders on the disk. However, because multiple users may use a single
workstation, HotDocs Setup doesnt install these files. Instead, when a user logs on to the workstation and runs HotDocs,
the Current User Setup copies these files to the correct locations for the user. (See Default File Locations in HotDocs 10.)
The Current User Setup also registers information about each user in the Current User key of the System Registry.
This information includes default file locations for such things as templates, answer files, and library files. As each user
specifies preferences for working with HotDocs, these settings are likewise written to the Current User key. This allows
each workstation user to have his or her own HotDocs settings without other users overriding those preferences with their
own.
The Current User Setup happens each time a user starts HotDocs. This means that each time you run HotDocs, HotDocs
checks to make sure all of the required files (such as word processor startup files) are located where it expects to find
them. If the file isnt found, HotDocs replaces it using a copy it finds in the Source folder.
Caution:
Even if you delete the tutorial files that are installed to your default Templates folder, because of the Current User
Setup, the next time you launch HotDocs, HotDocs will recopy the files to that folder. To keep this from happening,
open the Source folder, select the Tutorials subfolder and press Delete.

Restore Installation Defaults

At times, you may want to restore default settings in HotDocs. You can accomplish this by clearing the Current User key
of the Registry.
Please see Restore Installation Defaults for instructions on how to do this.

Copyright 2010 HotDocs Ltd. All rights reserved

51

Help Topics for HotDocs Developer 10

Default File Locations in HotDocs 10

When you install and use HotDocs, the program makes several entries in the System Registry that indicate to HotDocs
where to look for files, as well as where to suggest you save files. (See Understand HotDocs Installation.) In most
situations, HotDocs uses this information each time you perform a task in HotDocs. For example, each time you create a
new template, HotDocs suggests a default location for the new template, based on the information it finds in the System
Registry.
The following is a list of these default locations:
Caution:
In Windows Vista, the My Documents folder has been renamed as Documents. The All Users Documents folder has
been renamed as Public Documents.
File Type

Default Location

Program Files

C:\Program Files\HotDocs

Help Files

Program Files\HotDocs

Spelling Dictionary File

My Documents\HotDocs\Spelling

Library Files

My Documents\HotDocs\Libraries

Template Files

My Documents\HotDocs\Templates
Note:
Even though HotDocs saves all template types to this folder, it still maintains separate
default settings for text templates, form templates, and interview templates.

WordPerfect Macro Files

Word Processor Macro Folder

MS Word Startup Files

Word Processor Startup Folder

Template Sets

All Users Documents\HotDocs\Templates

Text Document Files

Word Processor Documents Folder

Form Document Files

My Documents

Answer Files

My Documents\HotDocs\Answers

Catalog Files

All Users Documents\HotDocs\Catalogs

Publish Settings Files

My Documents\HotDocs\Publish

If you need to change these default locations after HotDocs is installed, you can do so at HotDocs Options. See Change
Word Processor File Locations and Change HotDocs Program File Locations for details.
Caution:
If you are upgrading from HotDocs 6.1 or earlier and your libraries are saved in the HotDocs 6 Program Files
folder, HotDocs will set this folder as the default location for libraries. If you do not have library files saved here,
HotDocs will use My Documents\HotDocs\Libraries.
If you perform a custom installation, HotDocs will install files and set registry entries using the information you
specify during installation. Whatever settings you specify during installation will be used for all users of the
workstation.

Copyright 2010 HotDocs Ltd. All rights reserved

52

Help Topics for HotDocs Developer 10

Use International Characters in HotDocs

What is Unicode?
Unicode is a computer specification that makes it possible for computers to represent and manipulate characters used in
most of the worlds written languages.
According to the technical description given by the Unicode Consortium, Unicode provides a consistent way of encoding
multilingual plain text and brings order to a chaotic state of affairs that has made it difficult to exchange text files
internationally. Computer users who deal with multilingual textbusiness people, linguists, researchers, scientists, and
otherswill find that the Unicode Standard greatly simplifies their work. Mathematicians and technicians, who regularly
use mathematical symbols and other technical characters, will also find the Unicode Standard valuable.

HotDocs and Unicode

Unicode support in HotDocs makes it possible to automate and assemble documents in non-native, left-to-right-reading
languages. This includes automating and assembling Microsoft Word templates as well as PDF-based form templates.
Caution:
WordPerfect does not support Unicode. As such, Unicode characters that are assembled into WordPerfect documents
will not appear correctly.
For example, say you need to automate a template using the German language. You can draft the underlying template
text in German, and then create all of the components in the template using German. This includes assigning component
names, titles, prompts, resources, and so forth in that language. Users can then complete the interview by entering their
answers in German. The resulting assembled document can be entirely in German.

Using Fonts that Contain Unicode Characters

Even though HotDocs supports Unicode characters, these characters may not appear correctly if you do not have fonts
installed that can display them.
For example, say you automate your template using the Tahoma font on Windows Vista. If the template is used on an
earlier operating system, some of the characters you have used may not appear correctly because those characters may
not be supported in the version of Tahoma available on that operating system.
Or, perhaps you use a very specialized font for displaying symbolic characters. If your users do not have the same font
installed on their computers, your text will appear as unrecognized charactersusually boxes or question marks.
Additionally, you must also be careful when assigning font styles (such as bold or italic) to international characters, as
characters may not display correctly when these styles are applied.

Unicode and Backwards Compatibility

HotDocs 2008 and earlier does not support Unicode. (The exception to this is HotDocs 2008 answer files where you could
use Unicode characters in answers.) If you attempt to use a HotDocs 2009 (or later) template with an earlier version of
HotDocs, any foreign characters you have used will appear as boxes or question marks. In some cases, HotDocs will
warn you when you attempt to use one of these types of files. (See Compatibility of HotDocs 10 Files with Earlier Versions
of HotDocs.)
Detailed, technical information on Unicode can be found by visiting any of the following Web sites:
http://www.w3.org/
http://www.unicode.org/
Copyright 2010 HotDocs Ltd. All rights reserved

53

Help Topics for HotDocs Developer 10

http://en.wikipedia.org/wiki/Unicode
Note:
While the template, interview, and assembled document may appear in most languages supported by Unicode,
the HotDocs application itself continues to be supported in English only.
This help file defines Unicode characters that are not part of your typical language set as foreign or international
characters.

Copyright 2010 HotDocs Ltd. All rights reserved

54

Help Topics for HotDocs Developer 10

HotDocs and XML File Formats

In versions of HotDocs prior to HotDocs 2009, HotDocs-specific filessuch as library files, component files, and so forth
were saved in binary formats.
Binary file formats are common in most software applications. They allow information about the files to be encoded for
storage and processing purposes. However, one limitation of storing information in HotDocs in binary format is that thirdparty application developers aren't able to inspect, edit, or otherwise make use of information contained in the files.
Another limitation is that the binary formats used in HotDocs do not support the use of foreign characters, or international
characters that are not represented in your computer system's default language.
From the release of HotDocs 2009 onwards, however, users can save libraries and component files in either binary format
or in XML format. Saving HotDocs files in XML format allows third-party developers easier access to the data stored in
these files, making it easier to create integrations with other applications. The XML format also supports a wide range of
left-to-right-reading international characters.
As you work in HotDocs 10, you can choose which format you use to save your HotDocs files. Here are some guidelines
to help you decide:
XML library and component file formats are only supported in HotDocs 2009 and later. This means that if you
need to use your files with earlier versions of HotDocs, you must save them in binary format. For example, say you
are using HotDocs 10 to automate templates, but your users are still using HotDocs 2008. Or, perhaps you are
using a published template set with HotDocs Player 10 but youre still using HotDocs 2008 for your own template
development. In order to maintain compatibility between these different versions of HotDocs, you must save your
files in the format that is supported in both versions. In this case, it would be the binary format.
If you plan to use international characters (characters not typically supported by your default system language), you
must choose to save your files in XML format.
Caution:
If you generate XML files using a program other than HotDocs, you must make sure the encoding declaration in the
XML file matches the actual encoding used in the document.
Note:
HotDocs uses XML schema documents (or XSD files) to validate XML content. By default, these documents are
found in C:\Program Files\HotDocs\Schemas.
Previous versions of HotDocs supported both binary answer files and XML answer files. However, all answer files
in HotDocs 2009 onwards are saved in XML format. See Compatibility of HotDocs 10 Files with Earlier Versions
of HotDocs for additional details on using backwards-compatible HotDocs 10 answer files.
One benefit of saving files in XML format is the ability to more easily recover files that become corrupted or
unusable in HotDocs. Using the XML schema documents, you (or someone with XML programming experience)
can examine how the contents can be reconstructed, where possible.

Copyright 2010 HotDocs Ltd. All rights reserved

55

Help Topics for HotDocs Developer 10

Uninstall HotDocs
You can remove existing versions of HotDocs from your computer by using the HotDocs uninstall program. When you
uninstall, all of the program files are removed from your computer. However, the program does not remove any custom
templates, libraries, or answer files you have created.
To uninstall HotDocs in Windows XP

1. At the Start menu, select Settings > Control Panel. The Control Panel dialog box appears.
2. Click Add or Remove Programs. The Add or Remove Programs dialog box appears.
3. Select the version of HotDocs that needs to be removed, then click Remove. The HotDocs uninstall process starts.
4. Follow the on-screen prompts to remove the program.
You can remove existing versions of HotDocs from your computer by using the HotDocs uninstall program. When you
uninstall, all of the program files are removed from your computer. However, the program does not remove any custom
templates, libraries, or answer files you have created.
To uninstall HotDocs in Windows Vista and above

1. At the Start menu, select Control Panel > Programs > Uninstall a Program.
2. Select the version of HotDocs that needs to be removed, then click Uninstall. The HotDocs uninstall process starts.
3. Follow the on-screen prompts to remove the program.
Caution:
If you plan to reinstall HotDocs to restore default settings, you must delete the user-specific settings HotDocs entered
in the Windows System Registry. For details on doing this, see Restore Installation Defaults.
1

"The Unicode Standard: A Technical Introduction. 17 Sept, 2008, 12:27 PM. 5 Dec 2008 http://www.unicode.org/
standard/principles.html.

Copyright 2010 HotDocs Ltd. All rights reserved

56

Help Topics for HotDocs Developer 10

Chapter 4: Starting With HotDocs

Start HotDocs
To start HotDocs so you can edit templates or assemble documents, you must first open the HotDocs library. The library
includes commands for performing most tasks in HotDocs.
To start HotDocs
Choose Start > Programs > HotDocs 10 > HotDocs Developer. The HotDocs library window appears.
Note:
To start HotDocs, you can also click the
the HotDocs library window.

Copyright 2010 HotDocs Ltd. All rights reserved

HotDocs button in the word processor toolbar. This will open and display

57

Help Topics for HotDocs Developer 10

Exit HotDocs
When you are finished using HotDocs, you can exit it.
To exit HotDocs
Click Exit (File menu).

Copyright 2010 HotDocs Ltd. All rights reserved

58

Help Topics for HotDocs Developer 10

Get Help Using HotDocs

HotDocs Help Window Overview
HotDocs Developer includes a Help file to assist you in using the product.
The HotDocs Help window is divided into three parts the navigation bar along the top of the help window, the main help
content pane, and the topic navigation path that appears along the bottom of the window (which is visible as you are
viewing specific help topics).

Organization of the Help File

Content within the help file is categorized into four areas:

1. Overviews: These topics describe, in general terms, a particular feature or tool of HotDocs.
2. How do I ?: These topics provide step-by-step instructions for completing a task in HotDocs.
3. Reference Material: These topics offer additional information about a HotDocs feature or tool, such as background
data or tips.

4. Dialog Box Descriptions: These topics provide information for a specific dialog box or window. (You usually access
these help topics by clicking the Help button on a dialog box that has one.)

Find Topics in the Help File

To use the help file, you have several options:
Click the Home link in the navigation bar to view the main table of contents for the help file. This displays a page
that describes sections of the help file. You can click a folder and navigate to the specific help topic that most
interests you.
Click the Index link to view a listing of all the topics in the help file, referenced by index keyword.
Enter a search term or phrase in the Search box and click Search to view topics that contain your search phrase. If
the search phrase is found, a Search Results page is displayed, showing the different topics, grouped by category,
that meet your criteria.
Note:
See Form a Help Search Query for detailed instructions on creating a search query.

Whats This? Help and Dialog-Level Help

HotDocs provides two other types of helpWhats This? Help and Dialog-Level Help.
To access Whats This Help, at any dialog box where Whats This? Help is available, click the Whats This? Help
button, either on the title bar (

) or in the toolbar (

), and then click the item for which you want help.

To access dialog-level help, click the Help button at any dialog that contains one.

Other Help Resources

Click the Contact link to view different options for contacting HotDocs Corporation.
Click Glossary to view a glossary of HotDocs terms.
Click the
Click the
the help file.

Print Topic button to print a help topic.

Increase Size or

Copyright 2010 HotDocs Ltd. All rights reserved

Decrease Size buttons to increase or decrease the font size used for viewing
59

Help Topics for HotDocs Developer 10

Note:
For additional help using HotDocs, you can view the online HotDocs Knowledge Base. See http://
help.hotdocs.com/knowledgebase.
When you view a topic in a search results list, the help system highlights your search terms. If you want to
remove these highlights, click the Remove Highlighting button. (To show highlighted terms again, click the
Highlight Search Terms button.)

Copyright 2010 HotDocs Ltd. All rights reserved

60

Help Topics for HotDocs Developer 10

Verify HotDocs 5 Templates for Use with HotDocs 10

When documents are assembled in HotDocs 10, HotDocs displays an interview outline in the assembly window. This
outline represents all the dialogs in the interview. Using it, users can select any dialog and answer questions in it. When
they do this, HotDocs processes the answers and then updates the entire interview outline.
This type of interview processing is different than it was in HotDocs 5, where interviews were sequential, meaning
answers entered in one dialog affected answers only in subsequent dialogs. This type of processing rarely required the
interview to be updated entirely and at once.
Because of this change in interview processing, some scripting and other features that were used in HotDocs 5 may now
cause the interview in HotDocs 10 to process incorrectly. This can result in inconsistent answers in the interview as well
as produce an incorrectly assembled document. In order to prevent such errors from going unnoticed, templates should
be tested for potential problems before users assemble documents from them.
In order to verify a template, you must first convert the template to HotDocs 2009-10 format. (See Convert Multiple
Templates to Work with HotDocs 10) Then you must test the template. While at the test assembly window, you can view
the Test Panel, which includes a Warnings tab that tells you of potential problems in your template, including incorrectly
used SET instructions, incorrectly asked variables, and improperly referenced variables. (See Overview: Use the Test
Panel for information on using the Test Panel.)
To verify a HotDocs 5 template for use with HotDocs 10

1. At the template library, select the converted template you want to verify and click

Edit. (See Convert Multiple

Templates to Work with HotDocs 10 The template appears in the template development window.

2. Test assemble the template and verify that it does not contain any automation or scripting that may cause problems.
(See Check Interviews for Improper Scripting.)

3. In addition to reviewing any reported warnings, make sure the converted template looks and functions correctly. For
example, you should check for the following:
Any syntax errors reported by HotDocs have been fixed. (See Understand and Resolve Syntax Errors in a
Template or Script.)
The interview outline looks right and operates properly.
Dialogs look right and operate properly.
The document is assembled correctly.

Copyright 2010 HotDocs Ltd. All rights reserved

61

Help Topics for HotDocs Developer 10

Use HotDocs with Microsoft Word 2007 and 2010

If you are using HotDocs with Microsoft Word 2007 or 2010, you should be aware of a few differences between earlier
versions of Word and Word 2007/2010:
Location of HotDocs toolbar: To access the HotDocs editing and navigation toolbar buttons, you must click the
HotDocs tab of the Word ribbon. This displays each of the editing and navigation commands.
Accessing the HotDocs button: The HotDocs button is located on the HotDocs tab of the Word ribbon.
File formats: Word 2007/2010 includes two new XML-based template formats.DOTX (indicates the file does not
use macros) and .DOTM (indicates the file does use macros). These template formats are not supported in HotDocs.
However, if you are using Word 2007/2010 to save assembled documents, you can save in these formats: .DOCX
and .DOCM.
Compatibility Mode: When you edit existing templates in Word 2007/2010, the template opens in Compatibility
Mode. According to the Microsoft Word 2010 Help file, "Compatibility Mode makes sure that no new or enhanced
features in Word 2010 are available while you work with a document, so that people who are using previous versions
of Word will have full editing capabilities."
If you plan to use your templates with just Word 2007/2010, you can convert your templates to Word 2007-10 format
using the Word conversion tool. (See the Word Help file for additional information on doing this.) If you plan to
distribute or share your templates with users who are using earlier versions of Word, however, you should either
continue to work in Compatibility Mode, or you should take care not to use features specific to Word 2007/2010.
(The Word Help file has a full list of Word 2007/10 elements.)
Styles: When you create a new, empty Word template, HotDocs applies whatever styles are in HotDocs.dotx to the
new template. When you create a new template based on another template or document, HotDocs applies the styles
used in that template or document to the new template.

Copyright 2010 HotDocs Ltd. All rights reserved

62

Help Topics for HotDocs Developer 10

List of HotDocs File Name Extensions

The following is a list of all file types used by HotDocs:
File Name Extension

Type of File

.RTF

Word RTF Template

.DOT

Word Template

.WPT

WordPerfect Template

.HFT

HotDocs Envoy-based Form Template

.HPT

HotDocs PDF-based Form Template

.HFD

HotDocs Envoy-based Form Document

.HPD

HotDocs PDF-based Form Document

.DOC

Word Document

.WPD

WordPerfect Document

.CMP

HotDocs Component File

.CMP

HotDocs Interview Template

.HDL

HotDocs Template Library

.HDL

HotDocs Clause Library

.HCL

HotDocs Clause Archive

.HDP

HotDocs Publish Settings File

.HDA

HotDocs Auto-Assemble File

.HDI

HotDocs Auto-Install File

.HDK

HotDocs Registration File (required when publishing templates for commercial use with
HotDocs Player)

.HAL / .HDL

HotDocs Answer Library

Note:
HotDocs 6 through HotDocs 2008 supported binary answer libraries (or answer
libraries with the .HAL file name extension). Starting with the release of HotDocs
2009, however, HotDocs now supports both binary answer libraries and XML-based
answer libraries (which use the .HDL file name extension). By default, HotDocs will
continue to use binary answer libraries as long as the file properties of items in the
library use characters that are compatible with your system's default language. If you
define answer file properties that contain foreign characters, HotDocs will create an
XML-based answer library (so that it can properly display these characters in the
Properties tab of the library window.)

.ANS / .ANX

HotDocs Answer File

Note:
HotDocs 6 through HotDocs 2008 supported two types of answer filesbinary
answer files and XML answer files. These files were typically named using the .ANS
and .ANX file name extensions, respectively. Starting with the release of HotDocs
2009, however, HotDocs can save answer files in only XML format. This means that

Copyright 2010 HotDocs Ltd. All rights reserved

63

Help Topics for HotDocs Developer 10

if you open a binary answer file (such as an .ANS file) in HotDocs 2009, make a
change to the file, and then save it, the contents of the answer file will be converted to
and saved as XML. (The file name, however, will continue to use the ANS file name
extension.) If you want the answer file to be compatible with versions of HotDocs
prior to HotDocs 2009, see Compatibility of HotDocs 10 Files with Earlier Versions of
HotDocs.
.HPL

HotDocs Answer Source

.JS and .HVC

JavaScript interview file and HotDocs Variable Collection file (These files are used when
generating HotDocs Server interviews.)

.HDPMX

Publisher Answer Source Mapping File (This file is used to save variable mapping
information created and used by other third-party applications.)

.HDUMX

User Answer Source Mapping File (This file is used to save variable mapping information
created and used by other third-party applications.)

Copyright 2010 HotDocs Ltd. All rights reserved

64

Help Topics for HotDocs Developer 10

Complete the HotDocs Tutorials

When you purchased your license for HotDocs, you should have received a copy of the HotDocs Installation Guide and
Tutorial in PDF format on the installation CD. In addition to providing instructions for installing HotDocs, this manual also
contains several lessons that teach the basics of template automation. To complete these lessons, you should refer
to this manual. (You can also find a copy of the HotDocs Installation Guide and Tutorial at http://www.hotdocs.com/
documentation/guides.)
Once you complete the lessons in the HotDocs Installation Guide and Tutorial, you may download additional tutorials from
the HotDocs Web site. (See http://www.hotdocs.com/documentation/tutorials/.)

Copyright 2010 HotDocs Ltd. All rights reserved

65

Help Topics for HotDocs Developer 10

Documentation Feedback
To improve the quality of the tutorials and the help files, we invite you to make comments or suggestions. When doing so,
please include as much information about your experience using the documentation as possible. For example, include
which version of the product you are using, as well as whether your suggestion is in regards to the Installation Guide and
Tutorial or the electronic help file. If commenting about a specific topic, include that information as well.
Caution:
The HotDocs Publications team cannot respond to technical support or project consulting questions. We are mainly
interested in problems with the documentation itselfsuch as erroneous information, grammatical and spelling errors,
or suggestions for topics to include in the next release of the software.
E-mail your comments and suggestions to [email protected].

Copyright 2010 HotDocs Ltd. All rights reserved

66

Help Topics for HotDocs Developer 10

Chapter 5: Using the Keyboard in HotDocs

Use the Keyboard to Work in HotDocs
You can use the keyboard to complete many tasks in HotDocs. The following describes some of these keyboard options.
Caution:
The options described below refer to using a standard U.S. keyboard. Commands that require you to press two keys
simultaneously are displayed using a plus (+) character. For example, to describe the Print command, the keyboard
shortcut would appear as Ctrl+P.
There are four ways you can use the keyboard to work in HotDocs:

Tab Between the Elements in a Window, Dialog Box

Press the Tab key to move between the different elements of a HotDocs window or dialog box. Similarly, press Shift+Tab
to move through the different elements in reverse order.
If certain elements don't appear in the tab order, use one of the other methods described in this topic, such as use an
accelerator key.
For example, if you're viewing the template library and you want to assemble a document, you can press the Tab key to
move focus to the item list of the library. Then press the Up Arrow or Down Arrow key to move between items in the
library. Once the template you want to assemble is selected, press Alt+M (to view the Template menu). Finally, either
press the Down Arrow key to select Assemble from the menu, or press the A key to activate the accelerator key in the
Assemble command. The assembly window appears.

Use Accelerator Keys

Many commands and options in HotDocs can be accessed using an accelerator key. Accelerators appear as underlined
letters in a command name or prompt. To access them, press the Alt key while also pressing the underlined letter. If you
aren't in a text box (or a field where you can enter or select text), you can simply press the underlined letter and HotDocs
will move you to that element or command.
For example, to save an answer file during an interview, at the assembly window, press Alt+F. The File menu appears.
Then press S. The Save Answer File dialog box appears.
Caution:
For some Windows 2000 and XP users, accelerator keys aren't identified until the Alt key is pressed. To always
view accelerator keys, go to Start menu > Settings > Control Panel > Display. Click the Advanced tab, and then
click Effects. Clear Hide underlined letters for keyboard navigation until I press the Alt key. To always view
accelerator keys on Windows Vista, go to Control Panel > Ease of Access > Ease of Access Center > Make the
keyboard easier to use and select Underline keyboard shortcuts and access keys.

Use the Shortcut Menu

When working with specific elements in a window or dialog, you can frequently access a list of commands for that element
by displaying the shortcut menu. To access the shortcut menu, place focus on the element and then either press the
Windows Application key on your Windows keyboard, or press Shift+F10. Use the arrow keys to move between
options in the menu.
For example, to view where the answer to a specific question is used in the assembled document, while your cursor is
in an answer field, press the

Windows Application key on your keyboard. (Or, press Shift+F10.) A shortcut menu

Copyright 2010 HotDocs Ltd. All rights reserved

67

Help Topics for HotDocs Developer 10

appears. Then, either press the Down Arrow key to select Go to Answer in Document (and then press Enter), or press
the G key to issue the command.
Note:
To close a shortcut menu without choosing an option in it, press the Esc key.

Use Shortcut Keys

Several commands within HotDocs can be accessed using a shortcut key, which is a key or a combination of keys you
can press that will quickly execute the command. (Accelerator keys can be considered shortcut keys.)
For example, to send an assembled document to the word processor, press the F11 key. Or, to move between the
different tabs of the assembly window, press Ctrl+Tab. (Pressing Ctrl+Shift+Tab moves through the tabs in reverse
order.)
Click here for a complete list of shortcut keys.

Copyright 2010 HotDocs Ltd. All rights reserved

68

Help Topics for HotDocs Developer 10

Full List of Keyboard Shortcuts

You can use keyboard shortcuts to complete many tasks in HotDocs. A keyboard shortcut is a key or a combination of
keys you can press that will quickly execute the command.
For example, to send an assembled document to the word processor, press the F11 key. Or, to move between the
different tabs of the assembly window, press Ctrl+Tab. (Pressing Ctrl+Shift+Tab moves through the tabs in reverse
order.)
Click one of the links below to see the keyboard shortcuts for that specific part of HotDocs:

Keyboard Shortcuts at Template Library

To Do This

Press This

Tab between the item list

and the Find options

Tab / Shift+Tab

Switch between Properties

and Preview tabs

Ctrl+Tab

Assemble the currently

selected template

Enter

Edit the currently selected

template

Shift + Enter

Create a new template

Ctrl+Enter

Open the Item Properties

dialog box for the currently
selected folder or item

Alt+Enter

Remove the template from

the library

Delete

Collapse and expand the

currently selected folder

Left Arrow / Right Arrow

Move through items in the

library list

Up Arrow / Down Arrow

Move the selected item up

or down in the list

Alt+Up Arrow / Alt+Down Arrow

Copy the selected item

Ctrl+C

Create a new library

Ctrl+N

Open an existing library

Ctrl+O

Print a copy of the item list

Ctrl+P

Cut the selected item or text Ctrl+X

and place a copy of it on the
Clipboard
Open the HotDocs Help file

F1

Display the What's This?

Help cursor

Shift+F1

Copyright 2010 HotDocs Ltd. All rights reserved

69

Help Topics for HotDocs Developer 10

Display the What's This?

Help text for the currently
selected interface element

Ctrl+F1

Close the template library

Alt+F4

Move focus to a different

pane in the library

F6

Move between HotDocs

windows

Alt+F6

Resize the pane you are

currently viewing

Ctrl+F6

Access the library menu bar

F10

Display a shortcut menu

Shift+F10

Save a new copy of the

library

F12

This option selects the split bar so you can use the arrow keys to move it. Press Enter to
set the placement.

Keyboard Shortcuts at Component Manager

To Do This

Press This

Move between the different

elements in Component
Manager

Tab / Shift Tab

Edit the selected

component

Enter

Open the Component File

Properties dialog box

Alt+Enter

Insert the selected

component in the template

Insert

Remove the selected

component(s) from the
component file

Delete

Open the Components

drop-down list to view all
available options

Alt+Down Arrow

Copy components between

two open component files

Alt+Left Arrow / Alt+Right Arrow

Select all components in the Ctrl+A

list
Create a copy of a
component (or group of
components, if multiple
components are selected)

Ctrl+C

Copyright 2010 HotDocs Ltd. All rights reserved

70

Help Topics for HotDocs Developer 10

Edit the currently selected

component

Ctrl+E

Search each component in

the list for a specific word or
phrase

Ctrl+F

Search each component in

the list for a specific word or
phrase and replace it with a
new word or phrase

Ctrl+H

Create a new component

Ctrl+N

Print a list of components

and their properties

Ctrl+P

Close Component Manager

Ctrl+W or Alt+F4

Open the HotDocs Help

window

F1

Display the What's This?

Help cursor

Shift+F1

Display the What's This?

Help text

Ctrl+F1

Rename the selected

component(s)

F2

Check the spelling of text

used in components

F7

Access the Component

Manager toolbar

F10

Display the Component

Manager shortcut menu

Shift+F10

Keyboard Shortcuts at the Script Editor

To Do This

Press This

Move through the elements

in the editor

Tab / Shift+Tab

Merge a paragraph break in

a script

Ctrl+Enter

Merge just the highlighted

component or model in the
Script box

Insert

Display an Auto Complete

list of keywords and
component names so you
can more easily enter the
correct syntax for a script

Ctrl+Space

Copyright 2010 HotDocs Ltd. All rights reserved

71

Help Topics for HotDocs Developer 10

Switch between the different Ctrl+Tab

tabs of the component
editor
Highlight all of a script

Ctrl+A

Copy the highlighted script

to the Clipboard

Ctrl+C

Edit the currently selected

component

Ctrl+E

Search through the Script

box for a specific word or
phrase

Ctrl+F

Go to a specific line number

or character position in the
script

Ctrl+G

Search through the Script

box for a specific word or
prhase and replace it with a
different word or phrase

Ctrl+H

Indent the selected script

text

Ctrl+I

Place comment markers

before the selected text

Ctrl+K

Remove any comment

markers from the selected
text

Ctrl+Shift+K

Find the matching IF or

REPEAT instruction

Ctrl+Shift+M

(Use F3 to find the next instance of text for which you are searching.)

(Place your cursor in the

instruction before issuing
the command)
Highlight a block of script
starting with the opening
instruction and ending with
the closing instruction

Ctrl+Shift+M

Place your cursor in the

instruction before issuing
the command)
Create a new component

Ctrl+N

Insert a tab in the selected

block of script

Ctrl+T

Paste the text on the

Clipboard in the script

Ctrl+V

Copyright 2010 HotDocs Ltd. All rights reserved

72

Help Topics for HotDocs Developer 10

Close the Computation

Editor without saving your
changes

Ctrl+W or Alt+F4

Cut the selected script and

place it on the Clipboard

Ctrl+X

Reapply a change you just

undid

Ctrl+Y

Undo a change

Ctrl+Z

View an auto-complete list

of just components

F5

View an auto-complete list

of just scripting keywords

Shift+F5

View a status hint for the

F7
component or keyword you
are currently viewing (where
your cursor is)
Indent all pairs of IF and
REPEAT instructions,
based on their level of
insertion

F8

Access the script editor

toolbar

F10

Keyboard Shortcuts for the Interview Tab of the Assembly Window

To Do This

Press This

Tab through answer fields in Tab / Shift+Tab

a dialog
Move to the next dialog in
the interview

Enter

Insert a paragraph end in a

multi-line answer

Ctrl+Enter

Move to the next dialog or

the previous dialog in the
interview

Page Down / Page Up

Move to the next

unanswered dialog or
previous unanswered dialog
in the interview

Ctrl+Page Down / Ctrl+Page Up

Move through each

unanswered question in a
dialog

Ctrl+Down Arrow / Ctrl+Up Arrow

View all answers in a dropdown list

Ctrl+Down Arrow

Copyright 2010 HotDocs Ltd. All rights reserved

73

Help Topics for HotDocs Developer 10

Display the calendar for a

date field

Alt+Down Arrow

Collaps or expand dialogs in Left Arrow / Right Arrow

the interview outline
Use a new, untitled answer
file during the current
interview

Ctrl+N

Open Answer File Manager

Ctrl+O

Save the current answer file

Ctrl+S

Indent the text in a multi-line Ctrl+T

answer file
Close the assembly window

Ctrl+W or Alt+F4

Display the resource for a

field in a pop-up window

Alt+F1

Switch between the Answer

File drop-down menu, the
interview outline, the dialog
pane, and the resource
pane

Alt+Enter

Resize the pane you are

currently viewing

Ctrl+F6

Check the spelling of

answers in the interview

F7

Access the assembly

window menu bar

F10

Send the assembled

document to the word
processor or HotDocs Filler

F11

Copy the assembled

document to the currently
open word processor
document

Shift+F11

Copy the assembled

document to the Clipboard

Ctrl+F11

Save the assembled

document to disk

F12

Send the assembled

document to the word
processor and close
HotDocs

Ctrl+F12

This option selects the split bar so you can use the arrow keys to move it. Press Enter to
set the placement.

Copyright 2010 HotDocs Ltd. All rights reserved

74

Help Topics for HotDocs Developer 10

Keyboard Shortcuts for the Document Preview Tab of the Assembly Window
To Do This

Press This

Tab through answers field in Tab / Shift+Tab

the document
Switch between tabs of the
assembly window

Ctrl+Tab

Open a pop-up interview

for the current answer field
(Word users only)

Enter

Open the Document Text

Editor for the section of
editable text (Word users
only)

Enter

Move through each

Ctrl+Down Arrow / Ctrl+Up Arrow
unanswered question in the
document (Word users only)
Move through each section
of editable text (Word users
only)

Ctrl+Shift+Down Arrow / Ctrl+Shift+Up Arrow

Select all of the text in the

document

Ctrl+A

Copy the selected text to

the Clipboard

Ctrl+C

Search through the

document text for a specific
word or phrase

Ctrl+F

Move your cursor to a

specific line number or
character position in the
document

Ctrl+G

Use a new, untitled answer

file during the current
interview

Ctrl+N

Open Answer File Manager

Ctrl+O

Save the current answer file

Ctrl+S

Close the assembly window

Ctrl+W or Alt+F4

Print a copy of the

assembled document

Ctrl+P

Zoom in or out on the

document text

Ctrl+= / Ctrl+-

Access the assembly

window menu bar

F10

(Press F3 to find the next instance)

Copyright 2010 HotDocs Ltd. All rights reserved

75

Help Topics for HotDocs Developer 10

Send the assembled

document to the word
processor or HotDocs Filler

F11

Copy the assembled

document to the currently
open word processor
document

Shift+F11

Copy the assembled

document to the Clipboard

Ctrl+F11

Save the assembled

document to disk

F12

Keyboard Shortcuts for the Form Document Tab of the Assembly Window
To Do This

Press This

Move between the different

answer fields of the form
document

Tab / Shift+Tab

View a pop-up interview for

the selected field

Enter

View the Field Properties

dialog box for the current
field

Alt+Enter

Display the full list of

options for a drop-down
field

Alt+Down Arrow

Move between unanswered

fields on the form

Ctrl+Down Arrow / Ctrl+Up Arrow

Select all of the text in a

field, or, if your cursor isn't
on a field, select all of the
fields on the form page

Ctrl+A

Copy the selected text or

fields to the Clipboard

Ctrl+C

Change the font properties

of the selected field(s)

Ctrl+D

Go to a specific page in the

form

Ctrl+G

Move between the fields

in the document where the
same answer is merged

Ctrl+M / Ctrl+Shift+M

Create a new answer file

for use during the current
interview

Ctrl+N

Copyright 2010 HotDocs Ltd. All rights reserved

76

Help Topics for HotDocs Developer 10

Open Answer File Manager

so you can choose a
different answer file for the
current interview

Ctrl+O

Print a copy of the form

document

Ctrl+P

Save the current answer file

Ctrl+S

Paste the contents of the

Clipboard

Ctrl+V

Close the assembly window

Ctrl+W

Cut the selected text or field

to the Clipboard

Ctrl+X

Zoom in or out on the form

Ctrl+= / Ctrl+-

Switch between the

document pane and the
resource pane

F6

Resize the pane you are

currently viewing

Ctrl+F6

Check the spelling of

answers on the form

F7

Display the page width of

the form

F9

Display the full page of the

form

Shift+F9

Access the assembly

window menu bar

F10

Send the assembled

document to HotDocs Filler

F11

Save a copy of the

assembled document to
disk

F12

This option selects the split bar so you can use the arrow keys to move it. Press Enter to
set the placement.

Keyboard Shortcuts for the Comparison Tab of the Assembly Window

The shortcut commands for the Comparison tab are identical to those for the Document Preview tab, with the following
changes:
To Do This

Press This

Move to the next difference

in the document

Tab

Move to the previous

difference in the document

Shift+Tab

Copyright 2010 HotDocs Ltd. All rights reserved

77

Help Topics for HotDocs Developer 10

Send the comparison

document to the word
processor

F11

Save the comparison

document to disk

F12

Keyboard Shortcuts for a Clause Library at the Assembly Window

To Do This

Press This

Move a clause from the

Insert
Available list to the Selected
list
Remove a clause from the
Selected list

Delete

Move to the top of the

clause list

Home

Move to the bottom of the

clause list

End

Move the selected clause

up in the Selected list

Alt+Up Arrow

Move the selected clause

down in the Selected list

Alt+Down Arrow

Keyboard Shortcuts for Answer File Manager

To Do This

Press This

Tab between the item list

and the Find options

Tab / Shift+Tab

Switch between Properties

and Contents tabs

Ctrl+Tab

Open the Item Properties

dialog box for the currently
selected answer file

Alt+Enter

Remove the answer file

from the library

Delete

Move the selected item up

or down in the list

Alt+Up Arrow / Alt+Down Arrow

Expand or collapse a folder

Right Arrow / Left Arrow

Copy the selected answer

file

Ctrl+C

Create a new answer file

Ctrl+N

Cut the selected item or text

Ctrl+X

Copyright 2010 HotDocs Ltd. All rights reserved

78

Help Topics for HotDocs Developer 10

Close Answer File Manager

Ctrl+W or Alt+F4

Switch between the answer

file list and the Preview
pane

F6

Resize the pane you are

currently viewing

Ctrl+F6

Access the Answer File

Manager toolbar

F10

This option selects the split bar so you can use the arrow keys to move it. Press Enter to
set the placement.

General Keyboard Shortcuts

To Do This

Press This

Display all of the options in

a drop-down list

Alt+Down Arrow

Move items up or down

within a list (for example,
the Contents list of the
Dialog Editor)

Alt+Down Arrow / Alt+Up Arrow

Edit the selected

component

Ctrl+E

Create a new component

Ctrl+N

Close the open component

editor and cancel your
changes

Ctrl+W

Move between HotDocs

windows

Alt+F6

View a shortcut menu

Shift+F10

Move between the different

tabs of a window

Ctrl+Tab

Access the buttons in a

toolbar (when no menu is
provided)

F10

Open the HotDocs Help

F1

Display the What's This?

Help cursor

Shift+F1

Display the What's This?

Help text for a selected
element

Ctrl+F1

Keyboard Shortcuts for JavaScript Interviews

Navigation Bar
Copyright 2010 HotDocs Ltd. All rights reserved

79

Help Topics for HotDocs Developer 10

To Do This

Press This

Go to First dialog

Ctrl+Home

Previous Unanswered
dialog

Ctrl+PgUp

Previous dialog

PgUp

Next dialog

PgDn

Next Unanswered dialog

PgUp

Go to Last Dialog

Ctrl+End

Spreadsheet Bar
To Do This

Press This

Edit Row

Ctrl+Enter

Insert Row

Ctrl+Insert

Delete Row

Ctrl+Del

Keyboard Shortcuts for Silverlight Interviews

Navigation Bar
To Do This

Press This

Go to First dialog

Ctrl+Home

Previous Unanswered
dialog

Ctrl+PgUp

Previous dialog

PgUp

Next dialog

PgDn

Next Unanswered dialog

PgUp

Go to Last Dialog

Ctrl+End

Spreadsheet Bar
To Do This

Press This

Edit Row

Ctrl+Enter

Insert Row

Ctrl+Insert

Delete Row

Ctrl+Del

Copyright 2010 HotDocs Ltd. All rights reserved

80

Help Topics for HotDocs Developer 10

SECTION 3:
SETTING HOTDOCS OPTIONS

Copyright 2010 HotDocs Ltd. All rights reserved

81

Help Topics for HotDocs Developer 10

Chapter 6: Setting HotDocs Options

Overview: HotDocs Options
You can change the way HotDocs looks and works by changing your preferences at HotDocs Options. These changes
affect the program regardless of which template you are using. (Some options, however, can be controlled at the template
or component file level.)
For example, from the HotDocs Options dialog box, you can specify several options that will help you develop templates
more efficiently. You can also control the way HotDocs presents interview information during assembly, and you can
control the way the information is presented in an assembled document. Finally, some options let you control where you
save your HotDocs filesboth program files as well as word processor files.
Note:
Settings specified at HotDocs Options are user-specific and are saved in the Current User key of the Windows System
Registry. For information on working with the registry, see the Windows Help file.

Copyright 2010 HotDocs Ltd. All rights reserved

82

Help Topics for HotDocs Developer 10

Interviews and Dialogs

The following topics discuss the options available in the Interviews and Dialogs folder of HotDocs Options:

Display Repeated Dialogs Using a Special Icon

When HotDocs starts an assembly, it displays an interview outline as well as a dialog pane. The interview outline contains
a list of all the dialogs in a given template. These appear as icons, followed by the name of the dialog. If HotDocs
encounters a repeated dialog, it can display an icon that more closely represents a repeated dialog ( ). When you click
this icon, the interview outline expands to show each repeated dialog as entries underneath the dialog title. These entries
are numbered to show which repetition you are on.
To display repeated dialogs using a special icon

1. At the HotDocs library, click the

Options button. The HotDocs Options dialog box appears.

2. Click the Interviews and Dialogs folder. The window changes to show several options relating to the way variables
and dialogs appear and are processed during the interview.

3. In the Interview Outline group, select Display repeat icons in interview outline.
Note:
To have HotDocs show repeated dialogs in the main level of the interview outline, clear Display repeat icons in
interview outline.

Control How Child Dialogs Appear in the Interview Outline

As you assemble documents, HotDocs displays the dialogs from the template in the interview outline. Some dialogs
contain inserted dialogs (or child dialogs) that are also represented visually in the interview outline. You can control just
how much detail the outline shows for each parent and child dialoga full view of all dialogs, a view of just the current
dialog, or a view of just the parent dialog.
To change the appearance of child dialogs in the interview outline

1. At the HotDocs library, click the

Options button. The HotDocs Options dialog box appears.

2. Click the Interviews and Dialogs folder. The window changes to show several options relating to the way variables
and dialogs appear and are processed during the interview.

3. In the Interview Outline group, click the Automatically expand child dialog entries drop-down button and select
one of the following options:
Choose Completely to have HotDocs expand the interview outline to show the relationship between all related
dialogs.
Choose Partially to have HotDocs expand the interview outline to show only the dialog you are currently
answering.
Choose Not at all to have HotDocs not expand the interview at all and show only the parent dialog in the
interview outline.
Note:
These views are controlled when you use the navigation bar or shortcut keys to complete an interview. Once you click
in the interview outline, expansion of the outline is controlled by the mouse.

Control the Tab Order of Buttons on the Navigation Bar

Sometimes as you navigate through an interview, you may press the Tab key to move between options in a dialog
including the buttons on the Navigation Bar. You can select an option that causes the
Copyright 2010 HotDocs Ltd. All rights reserved

Next button to always be the first

83

Help Topics for HotDocs Developer 10

button on the navigation bar to which you tab after answering questions in the interview. When this option is cleared and
you press Tab after the last question in the interview, HotDocs will tab to the first active button in the Navigation Bar.
To control the Navigation Bar tab order

1. At the HotDocs library, click the

Options button. The HotDocs Options dialog box appears.

2. Click the Interviews and Dialogs folder. The window changes to show several options relating to the way variables
and dialogs appear and are processed during the interview.

3. In the Dialog Navigation group, select Next button first in Navigation Bar tab order.
Now when tabbing from the last answer field in the dialog to the Navigation Bar, you will automatically tab to the
button, regardless of whether the

First Dialog,

Previous Unanswered, or

Next

Previous buttons are active.

Select Existing Answers When Tabbing Between Answer Fields

During an interview, you can have HotDocs automatically highlight existing text in an answer field when you tab to it.
When you do this, you can immediately type a new answer without having to select the text first. If you need to edit part of
an answer, rather than replace it entirely, you can clear this option.
To control text selection during the interview

1. At the HotDocs library, click the

Options button. The HotDocs Options dialog box appears.

2. Click the Interviews and Dialogs folder. The window changes to show several options relating to the way variables
and dialogs appear and are processed during the interview.

3. In the Dialog Navigation group, select Select existing answers when tabbing between fields to have existing
text highlighted when you tab to a field.

Display Warning When Trying to Add a New Repetition

When answering repeated dialogs, you click the Add Another button to add a new, empty repetition to the series of
dialogs. However, if you are already in a new, empty dialog, clicking this button has no effect. You can have HotDocs
display a warning the reminds you that you must first answer at least one question in the current dialog before you can
add a new repetition.
To display a warning when trying to add a new repetition to a dialog

1. At the HotDocs library, click the

Options button. The HotDocs Options dialog box appears.

2. Click the Interviews and Dialogs folder. The window changes to show several options relating to the way variables
and dialogs appear and are processed during the interview.

3. Select Display warning when clicking Add Another button at empty dialog.
Control the Functionality of the Enter Key During the Interview
You can control the functionality of the Enter key as you enter answers in a dialog. For example, if you want to use the
Enter key to advance to the next dialog instead of the next answer field, you can specify an option that will make this
possible.
To specify how the Enter key functions during assembly

1. At the HotDocs library, click the

Options button. The HotDocs Options dialog box appears.

2. Click the Interviews and Dialogs folder. The window changes to show several options relating to the way variables
and dialogs appear and are processed during the interview.
Copyright 2010 HotDocs Ltd. All rights reserved

84

Help Topics for HotDocs Developer 10

3. In the Dialog Navigation group, click the Enter key action in single-line fields drop-down button and select an
option:
Choose Next dialog to have the Enter key display the next dialog.
Choose Next answer field to have the Enter key move your cursor to the next answer field.
Choose No action to make the Enter key not do anything.
Note:
Pressing Enter in a multi-line text field will insert a line break, while pressing Ctrl+Enter will insert a paragraph end.
(This affects Word users only.)

Display Resource Buttons Next to Answer Fields

In addition to viewing helpful information in the resource pane, you can specify an option that will display a
Resource
button next to answer fields in the dialog pane. (Clicking this button causes the resource text to appear in a pop-up
dialog.) You can also control when the button appears.
To have HotDocs display a resource button next to an answer field

1. At the HotDocs library, click the

Options button. The HotDocs Options dialog box appears.

2. Click the Interviews and Dialogs folder. The window changes to show several options relating to the way variables
and dialogs appear and are processed during the interview.

3. In the Dialog Navigation group, click the Show answer field resource button drop-down button and select an
option:
For the current field only causes HotDocs to display a resource button next to an answer field only when that
field is active (or when you are answering it).
For all fields with a resource causes HotDocs to simultaneously display resource buttons for all answer fields
in the dialog that contain a resource. The buttons appear regardless of which answer field is active.

Warn When HotDocs Reformats Date and Number Answers

When you type an answer in an answer field, HotDocs sometimes reads the answer and reformats it to appear a certain
way. For example, if you type February 6, 2006 in a date field, HotDocs will reformat the answer to appear as 6 Feb
2006. Sometimes this reformatting can reveal an incorrectly interpreted answer, especially if the answer you typed is
ambiguous. For example, the date 05/06/2006 may either be interpreted as June 5, 2006 or as May 6, 2006.
Depending on where the reformatted answer appears in the dialog, you may not even be aware that it has been
reformatted. For example, when you enter an answer in one of the first answer fields in a dialog and then move to the next
field, you will most likely see that your answer has been reformatted. However, if you enter an answer in the last answer
field and click Next to advance to the next dialog, you may not see that the answer has been reformatted.
You can specify an option that forces HotDocs to alert you that an answer has changed before HotDocs advances to the
next dialog.
To have HotDocs tell you it has reformatted an answer before advancing to the next dialog

1. At the HotDocs library, click the

Options button. The HotDocs Options dialog box appears.

2. Click the Interviews and Dialogs folder. The window changes to show several options relating to the way variables
and dialogs appear and are processed during the interview.

3. Click the When answers are reformatted drop-down button and select one of the following options:
Choose Leave dialog anyway to have HotDocs immediately advance to the next dialog in the interview
without showing you the reformatted answer.

Copyright 2010 HotDocs Ltd. All rights reserved

85

Help Topics for HotDocs Developer 10

Choose Pause before leaving dialog to cause HotDocs to reformat the variable and re-display it for one
second before advancing to the next dialog.
Choose Don't leave dialog to cause HotDocs to reformat the variable and stay at the current dialog until you
click Next again.
Note:
This answer reformatting affects only how answers are displayed in the dialog pane. Answers in the assembled
document are formatted as the developer specifies or according to the Default date format property.

Specify How HotDocs Should Process the Date Order

When you type an answer for a Date variable, the first thing HotDocs does to process the information is to separate
what you type into the different parts of a date, for example, the month, the day of the month, and the year. Once it has
determined this, it formats the date and then merges the answer into the assembled document. Often, if the user spells
out the month when typing a date (for example, May 6, 2006), HotDocs can easily distinguish between the different parts.
However, if a user enters an all-digit value, such as 05/06/2006, HotDocs could process the date one of two wayseither
as May 6, 2006 or as 5 June 2006.
You can specify an option that tells HotDocs the order in which you want months and days of months to be processed
either as Month Day Year, or as Day Month Year.
To specify a date order format for Date variables

1. At the HotDocs library, click the

Options button. The HotDocs Options dialog box appears.

2. Click the Interviews and Dialogs folder. The window changes to show several options relating to the way variables
and dialogs appear and are processed during the interview.

3. At the Answer Entry group, click the Date Detection drop-down list and select a format:
Choose Month Day Year to have HotDocs assume the first set of numbers in an answer is the month while the
second set is the day of the month.
Choose Day Month Year to have HotDocs assume the first set of numbers in an answer is the day of the
month while the second set represents the month.
Note:
For HotDocs users in the United States, the default option is Month Day Year. For HotDocs users outside the
U.S., the default option is Day Month Year.
To specify the format for the answer when it is merged into the assembled document, see Specify a Default Date
Format.

Control How HotDocs Handles Two-Digit and Four-Digit Years

As a safety precaution, HotDocs requires you to enter four digits when entering the year portion of a date. If you enter a
two-digit date, such as 7/9/99, HotDocs responds with this message: You must enter a four-digit year.
You can override this default option by specifying a century rollover year at the HotDocs Options dialog box. The number
you enter controls how HotDocs interprets two-digit years. Two-digit years less than or equal to the number you enter are
understood as 2000-century years. Two-digit years greater than the number you enter are understood as 1900-century
years.
For example, if you specify a rollover value of 34, dates entered as 5/14/34 will appear as 14 May 2034. A date entered as
5/14/35 will appear as 14 May 1935.
To set a century rollover preference

Copyright 2010 HotDocs Ltd. All rights reserved

86

Help Topics for HotDocs Developer 10

1. At the HotDocs library, click the

Options button. The HotDocs Options dialog box appears.

2. Click the Interviews and Dialogs folder. The window changes to show several options relating to the way variables
and dialogs appear and are processed during the interview.

3. In the Answer Entry group, clear Require four-digit year in dates. The Century rollover year option becomes
available, with the default rollover value of 50 selected.

4. Type a new two-digit number value in the Century rollover year box (or click the up or down arrows to select a
number.) Dates you enter where the year is greater than this value will appear as 19??, while dates where the year
is less than this value will appear as 20?? (where ?? represents the year you type at the answer field.)

Change the Way Dates Appear in Answer Fields

As you enter dates during an interview, HotDocs reformats the date to appear a certain way in the answer field. You can
change this format. (To change the format of dates in the assembled document, see Specify a Default Date Format.)
To change the way dates appear in an answer field

1. At the HotDocs library, click the

Options button. The HotDocs Options dialog box appears.

2. Click the Interviews and Dialogs folder. The window changes to show several options relating to the way variables
and dialogs appear and are processed during the interview.

3. At the Answer Entry group, select a date format from the Date display format drop-down list. Your options include
3 Jun 1990; June 3, 1990; 6/15/1990; and 15/6/1990.
Note:
Whether the 6/15/1990 format or the 15/6/1990 format is available depends on your date detection format.

Customize the Look of the Dialog Pane

You can change the appearance of the dialog pane. Specifically, you can change background colors and text properties
(such as font face, size, and color). You can also change some of the properties of the resource pane as well as the
interview outline.
Note:
To restore all default properties after you have changed them, at the Appearance window, click Restore Default
Fonts and Colors.
To change the appearance of the dialog, resource pane, or interview outline of the assembly window

1. At the HotDocs library, click the

Options button. The HotDocs Options dialog box appears.

2. Double-click the Interviews and Dialogs folder. The folder expands to show subfolders.
3. Click the Appearance subfolder. The window changes to show a visual representation of the dialog pane.
4. Make any changes, based on the following options:
To change the font or font size for text in the dialog, click the Dialog font drop-down button and choose the
font from the list and enter a size in the Font size box.
To change the font or font size for text in the resource pane, click the Resource font drop-down button and
choose the font from the list and enter a size in the Font size box.
To change the font or font size for text in the interview outline, click the Outline font drop-down button and
choose the font from the list and enter a size in the Font size box. (To see these changes take effect, you
must start a new assembly.)
To change the color of an item in the assembly window, click the Item color drop-down button and choose the
item from the list. Then click the color drop-down button and choose the color.
Copyright 2010 HotDocs Ltd. All rights reserved

87

Help Topics for HotDocs Developer 10

To have HotDocs mark required questions with an asterisk, select Show asterisk for required fields .
Note:
In addition to choosing the item whose properties you want to change using the drop-down lists, you can also click on
an area in the dialog preview. This automatically selects the item (in the corresponding drop-down list) so you can then
change the properties.

Customize the End of Interview Dialog

Options in the End of Interview dialog allow you to work with assembled documents. Such options include sending
documents to the word processor, saving them to disk, or closing the assembly window without doing anything. You can
choose which of these options appear in the End of Interview dialog.
To choose which options appear in the End of Interview dialog

1. At the HotDocs library, click the

Options button. The HotDocs Options dialog box appears.

2. Double-click the Interviews and Dialogs folder. The folder expands to show subfolders.
3. Click the End of Interview subfolder. The window changes to show which buttons you can choose to have appear in
the End of Interview dialog.

4. In the End of Interview Buttons group, choose which buttons you want on the End of Interview dialog by selecting
the corresponding check box.
Caution:
Buttons will be included only if they are selected and if they are relevant to the current interview. For example,
HotDocs will display the
Go to the first unanswered question in the interview button only if there is at least one
unanswered question in the interview.
Note:
To customize the list of buttons while viewing the End of Interview dialog, you can right-click anywhere in the dialog
and choose Change Options from the shortcut menu.

Control What Happens When You Finish an Interview

By default, when you click
Next at the last dialog in an interview, HotDocs displays the End of Interview dialog,
which gives you options for working with the assembled document. For example, you can choose to send the assembled
document to the word processor or Filler, or you can return to the interview and answer any unanswered questions.
However, if the End of Interview dialog is hidden (see Use the End of Interview Dialog), clicking Next simply displays
the assembled document. Where you view the document--either in the assembly window or in the word processor or
HotDocs Filler--depends on which options you select.
Likewise, when you click the
Finish button in the navigation bar, HotDocs displays the assembled document. Again,
you can choose where you view the document.
To define how HotDocs should finish an interview

1. At the HotDocs library, click the

Options button. The HotDocs Options dialog box appears.

2. Double-click the Interviews and Dialogs folder. The folder expands to show subfolders.
3. Click the End of Interview subfolder. The window changes to show options for working with the End of Interview
dialog.

4. In the Finish Interview Action group, select an option for text documents:

Copyright 2010 HotDocs Ltd. All rights reserved

88

Help Topics for HotDocs Developer 10

To send all assembled text documents directly to the word processor, select Send assembled text
documents to the word processor and close.
To view all assembled text documents directly at the Document Preview tab of the assembly window, select
Proceed to the Document Preview tab.

5. Select an option for form documents:

To send all assembled form documents directly to HotDocs Filler, select Send assembled form documents
to HotDocs Filler and close .
To view all assembled form documents at the Form Document tab of the assembly window, select Proceed to
the Form Document tab.
Now, whenever the End of Interview dialog is hidden and you click

Next at the last dialog in the interview, HotDocs

will perform the action you specified. Additionally, whenever you click the
performed.

Copyright 2010 HotDocs Ltd. All rights reserved

Finish button, the same action will be

89

Help Topics for HotDocs Developer 10

Document Assembly
The following topics discuss the options available in the Document Assembly folder of HotDocs Options:

Make Assembly Window Toolbars Automatically Wrap

The HotDocs assembly window includes several toolbars to help you accomplish the work you need. At times, the width of
the assembly window won't allow all of the toolbars to be displayed at oncesome of the toolbars scroll off the right edge
of the window. You can select an option that allows those toolbars to wrap to a new line of the assembly window so you
can view all of them at once.
To auto-wrap assembly window toolbars

1. At the HotDocs library, click the

Options button. The HotDocs Options dialog box appears.

2. Click the Document Assembly folder. The window changes to show several assembly options
3. Select Auto-arrange toolbars.
Display Warning When Questions are Unanswered
As you complete a HotDocs interview, HotDocs keeps track of which questions you have answered. You can have
HotDocs display a warning message if you attempt to send the document to the word processor without answering one
or more questions. (The warning also appears when you save or print the document.) Leaving questions in an interview
unanswered may result in an incorrectly assembled document. Heeding these warnings can help you ensure the accuracy
of the document.
To have HotDocs display a warning when variables are unanswered

1. At the HotDocs library, click the

Options button. The HotDocs Options dialog box appears.

2. Click the Document Assembly folder. The window changes to show several assembly options.
3. Select Display unanswered warning before saving documents.
Note:
If you don't want HotDocs to warn you about unanswered questions, clear Display unanswered warning before
saving documents. Unanswered questions will still be reported in the End of Interview dialog, but HotDocs will no
longer display warning messages.

Prompt to Save the Assembled Document When Closing the Assembly Window
Whenever you close an assembly window, either before or after you send the assembled document to the word
processor, HotDocs can ask if you want to save a copy of the assembled document.
To have HotDocs prompt you to save the assembled document

1. At the HotDocs library, click the

Options button. The HotDocs Options dialog box appears.

2. Click the Document Assembly folder. The window changes to show several assembly options.
3. Select Prompt to save document when closing assembly window. HotDocs will prompt you to save a copy of the
assembled document whenever you close the assembly window.

4. Optionally, select Prompt to save documents sent to word processor to have HotDocs prompt you to save a
copy of the assembled document when you close the assembly window, even if you have sent the document to the
word processor.

Copyright 2010 HotDocs Ltd. All rights reserved

90

Help Topics for HotDocs Developer 10

Note:
Depending on your project needs, you may not need to save electronic versions of your documents. In such cases,
you can clear both of these options.

Warn When Printing Assembled Text Documents

When you print an assembled text document from the assembly window, HotDocs opens the document in the word
processor, prints it using the default printing options, and then closes the word processor without ever displaying a Print
dialog box.
Frequently, you may need to change the default printing options, which you can only do by sending the assembled
document to the word processor and then by printing from the word processor's File menu. To help you remember this
sequence of steps, you can have HotDocs warn you when it's about to print a document without displaying the Print
dialog box. If you choose, you can stop the print job.
To display the Print warning

1. At the HotDocs library, click the

Options button. The HotDocs Options dialog box appears.

2. Click the Document Assembly folder. The window changes to show several assembly options.
3. From the Assembly Window group, select Prompt before printing assembled document via word processor.
Prompt to Select an Answer File Before Assembly
You can have HotDocs prompt you to select an answer file when you assemble a document. When it does, you can
choose to use an existing answer file; specify a new, untitled answer file; or use the answer file from your last assembly.
To have HotDocs prompt you for an answer file

1. At the HotDocs library, click the

Options button. The HotDocs Options dialog box appears.

2. Click the Document Assembly folder. The window changes to show several assembly options.
3. Select Prompt for answer file when beginning an assembly.
Note:
Clear Prompt for answer file when beginning an assembly to have HotDocs bypass this option and start the
interview immediately using an untitled answer file. Once the interview has started, you can save the current answer
file at any time.

Specify a Default Date Format

You can specify a default format for dates that are merged in assembled documents. This default format is used if no
format has been assigned by the template provider. It controls how dates are merged into the assembled documentnot
how dates are formatted for display during the interview. (See Change the Way Dates Appear in Answer Fields.)
To specify a default date format

1. At the HotDocs library, click the

Options button. The HotDocs Options dialog box appears.

2. Click the Document Assembly folder. The window changes to show several assembly options.
3. Type a date format in the Default date format box. (Use one of the following example formats: June 3, 1990; 3
June 1990; 03 JUN 90; 06/03/90; or 3rd day of June, 1990.)

Copyright 2010 HotDocs Ltd. All rights reserved

91

Help Topics for HotDocs Developer 10

Format Unanswered Variables in a Document

You can specify how an unanswered variable will appear in an assembled text document. (If a variable is left unanswered
in a form document, the form field is left empty, regardless of which unanswered variable placeholder you have selected.)
To specify an unanswered variable format

1. At the HotDocs library, click the

Options button. The HotDocs Options dialog box appears.

2. Click the Document Assembly folder. The window changes to show several assembly options.
3. At the Unanswered variable placeholder drop-down list, make a selection based on the following information:
Select ***Variable*** to insert the name of the variable with three asterisks on both sides of the variable name.
Select [Variable] to insert the name of the variable between two brackets.
Select Underscores to insert a blank line where the answer should be.
Select Asterisks to insert three asterisks.
Select Nothing to insert nothing in the unanswered field, not even a space.
Note:
Sometimes a template developer may assign a placeholder to be used with a variable. If so, the document may
show a placeholder that is different than what you select here.
If you are using Microsoft Word (and the template developer has enabled answer editing at the Document
Preview tab), you can edit answers while viewing the document. See Edit Answers at the Document Preview
Tab.

Set Properties for Viewing Answers and Editable Text in the Assembled Document
If you are using Microsoft Word, you can view answers and assembled document text that can be edited while viewing the
Document Preview tab. (See Edit Answers at the Document Preview Tab for details.) When doing this, you can control
whether the answers and text are marked by a special color, which you can also define.
Caution:
Some template developers choose to disable these features in their templates. If the options for editing answers and
text are not available at the assembly window, this is why.
To always highlight answers and editable text in a document

1. At the HotDocs library, click the

Options button. The HotDocs Options dialog box appears.

2. Click the Document Assembly folder. The window changes to show several assembly options.
3. Select Highlight fields at Document Preview tab. This will mark answers in the document with the color you define
at the Color drop-down. It will also mark editable document text as well as edited document text.

4. Optionally, to change the color for answer fields or sections of editable text, click the Document field drop-down
button, and choose the appropriate option. Then click the Color drop-down button and choose a color.
Note:
To restore the default colors, choose the field type and then click the Color drop-down button. Choose Default from
the top of the Palette tab.

Warn When Adding Assemblies to Assembly Queue

HotDocs will only allow you to assemble one document at a time. If you are currently assembling a document and you
attempt to assemble another one, HotDocs will add it to the assembly queue and it won't be assembled until the current
Copyright 2010 HotDocs Ltd. All rights reserved

92

Help Topics for HotDocs Developer 10

assembly is complete. If there are multiple assemblies in the queue, HotDocs will assemble them in the order they are
added. (See Use the Assembly Queue.) You can have HotDocs warn you when you attempt to assemble a document and
one is already being assembled.
To have HotDocs warn you when you add an assembly to the queue

1. At the HotDocs library, click the

Options button. The HotDocs Options dialog box appears.

2. Click the Document Assembly folder. The window changes to show several assembly options.
3. In the Assembly Queue group, select Prompt before adding an assembly to the queue.
Include List of Completed Assemblies in Assembly Queue
As you assemble documents during a given session of HotDocs, you can have HotDocs create a list of each document
you have assembled in the assembly queue. This list remains active during a particular session of HotDocs. (A session is
the time between when you start HotDocs and when you close it.)
To list completed assemblies in the assembly queue

1. At the HotDocs library, click the

Options button. The HotDocs Options dialog box appears.

2. Click the Document Assembly folder. The window changes to show several assembly options.
3. In the Assembly Queue group, select List completed assemblies.
Note:
If you are assembling large numbers of documents and you don't want HotDocs to track completed assemblies, clear
List completed assemblies. Then, once assembly has finished, the assembly is removed from the queue.

Copyright 2010 HotDocs Ltd. All rights reserved

93

Help Topics for HotDocs Developer 10

Document Markup
The following topics discuss the options available in the Document Markup folder of HotDocs Options:

Specify How Documents Should Be Marked Up

Note:
This feature is available to Word users only.
As you automate a Microsoft Word template and create within it variable and instruction fields, the template can be
complicated to read and understand, especially to someone unfamiliar with automation. At times, however, you may
need for a subject matter expert to review the text of the template for accuracy or to make changes or edits. To make the
template easier for non-HotDocs users to review, you can provide them a marked up copy of the template. (See View an
Assembled Document in Markup View for details.)
How the template is marked up depends on your preferences. You can choose which fields HotDocs marks as well
as define how much information is included in the field. For example, say you have a template with a series of IF
expressions. You can assign comments to each IF Field describing, in layman's terms, the conditions surrounding the
inclusion of the text in the document. Then, when you view the template in Markup View, the comments can be used to
mark the expressions. The instructions themselves can then be viewed in an annotation.
In addition to viewing markup in the template, you can also view markup at the Preview tab of the template library and
at the Document Preview tab of the assembly window. To view markup in either of these places, choose Markup View
from the respective window's View menu. (See View an Assembled Document in Markup View for details.)
To specify how documents should be marked up

1. At the HotDocs library, click the

Options button. The HotDocs Options dialog box appears.

2. Click the Markup View (Word) folder. The window changes to show several markup options.
3. Complete any of the tasks, described in the following table:
To

Do This

Choose the character or

characters that should be
used to mark fields in the
template

Enter the opening and closing characters in the boxes next to the field type:
Answers field = variable fields
Insertion field = INSERT instructions
Editable text = SPAN / END SPAN instructions
Conditional text = IF/ END IF instructions
Alternative text = ELSE IF / ELSE instructions
Repeated text = REPEAT / END REPEAT instructions

Mark variable answer

fields with any comments
entered for the variable

Select Use developer comments to label answer fields. If comments have been
entered for a variable field, they will be merged in the markup field.

Use a Multiple Choice

variable's merge text
options as the label for its
field

Select Use option text to label multiple choice answer fields.

Copyright 2010 HotDocs Ltd. All rights reserved

94

Help Topics for HotDocs Developer 10

To

Do This

If you've named your

merge text, the name will
be used instead.
Mark text blocks (such
as IF, REPEAT, and
SPAN instructions) using
developer comments
entered for the instruction

Select Use developer comments to label beginning of text blocks.

Include both opening and

closing markers when
merging a field label
(which includes developer
comments)

Select Enclose text block labels in markers.

By default, when HotDocs

marks text blocks, an
opening field marker is
merged before the opening
instruction and the closing
marker is merged after the
closing instruction.
Include text block
instructions in either a
footnote or endnote

To merge the same comment in the closing markup field, select and end of text
blocks.

Selecting this option causes HotDocs to use the closing marker after the opening
label. The closing marker will also be used at the end of the text block.
In the following example, [* is the opening marker for conditional text while *] is the
closing marker. The following is what will be merged in the marked up document:
[*Insert paragraph if employee must complete a trial
period*]
The length of [Employee Name]'s employment will be an
initial term of six months.*]

Select Add Footnote/Endnote at beginning of text blocks. Then select whether the
annotation will be marked using Letters or Numbers.
To annotate the closing field label, select and end of text blocks.

Apply font attributes, such

as bold and italics, to a
markup field

Select Bold or Italic.

Define the color scheme

used for marking the
different fields in the
template

Select Color and click the Color drop-down button. Then choose the color scheme.
(See Define Field Colors for details.)

Include editable text

markers when showing a
template in Markup View

Select Mark editable text blocks.

Caution:
Merge fields in the document are italicized by default. If you've used international
characters in your answers, the italicized version of the font used in the document
may not display the foreign characters correctly. If this is the case, clear the Italic
attribute.

Caution:
Editable text blocks are not visible when viewing the markup of an assembled
document.
Caution:
By default, HotDocs does not show SPAN instructions when you switch to Markup
View.

Show only basic markup

when previewing the

Select Use minimal markup at the HotDocs library Preview tab.

Copyright 2010 HotDocs Ltd. All rights reserved

95

Help Topics for HotDocs Developer 10

To

Do This

template at the HotDocs

library

When this option is selected, HotDocs will simply mark fields using field markers. If
comments have been assigned to variable fields, those comments will be merged.
(They will not be merged for instruction fields, however.)
To assign font formatting and color to markup fields at the Preview tab, select Apply
attributes to answer fields when minimal markup is used .

Define Field Colors

By default, when you insert fields in a HotDocs text template, HotDocs applies certain colors to the fields, depending on
the field type. For example, all variable fields will be merged using a specific color, while all REPEAT instructions will be
merged using a different color, and so forth.
Depending on the complexity of the template, there may be times when you want to use field coloring to view relationships
between SPAN, IF and REPEAT instructions in the template. For example, when working with nested instructions, you
may want all first-level instructions to be marked by one color, all second-level instructions to be marked by another color,
and so forth. Additionally, you may want to view instructions in the template sequentially, meaning each instruction pair is
marked with its own color.
At the Field Colors page, you can assign the colors HotDocs will use for marking fields and instructions in a template.
To customize the field colors in a text template

1. At the HotDocs library, click the

Options button. The HotDocs Options dialog box appears.

2. Double-click the Markup View (Word) folder. The folder expands to show subfolders.
3. Click the Field Colors folder. The window changes to show lists of field types and instructions with their
corresponding colors.

4. Complete any of the following steps:

To specify the color for all field types in a template, click that particular field in the Regular column and choose
the color you want from the palette.
To specify the color for each nested level of instruction, click that particular level in the Nested column and
choose the color you want from the palette.
To specify the color for each matching pair of instructions, click that field in the Sequential column and choose
the color you want from the palette.

5. Repeat this process for each field type or level of instruction you want to change.
Once you have made these changes, you must click the
colors to any existing fields.

Apply Colors button within your template to apply the new

Note:
HotDocs allows you to assign up to 20 Nested and Sequential colors. If you want to use fewer color schemes,
select the Level or Field after the last color you want used and assign black as the text color and white as the
highlight color. (So, for example, if you want to show only four levels of nesting, click on Level 5 and assign the
black/white color combination.)
If using the keyboard, tab to the row you need to access and press the Spacebar to show the foreground color
palette. Press Shift+Spacebar to show the background color palette.
To restore default colors, click the Color drop-down button and choose Default at the top of the Palette tab.
To choose the colors used for form fields, see Change Colors in Form Fields.

Copyright 2010 HotDocs Ltd. All rights reserved

96

Help Topics for HotDocs Developer 10

Model Documents
The following topics discuss the options available in the Model Documents folder of HotDocs Options:

Allow Non-Standard Names in Model Documents

When marking up model documents, you must adhere to the Model Document Markup Language, which requires you to
follow certain rules when naming variables. For example, variable names can include letters, numbers, and underscores,
but they cannot include spaces or other special characters.
Because of this requirement, you may receive errors either when you convert templates to models where spaces and
non-alphanumeric characters are used in a variable name, or when you assemble model documents that use this naming
scheme. If your model document contains these non-standard variable names, you can select a HotDocs Option that
allows HotDocs to still convert or assemble a model, regardless of how you've named your variables.
To allow spaces and other non-alphanumeric characters in variable names

1. At the HotDocs library, click the

Options button. The HotDocs Options dialog box appears.

2. Click the Model Documents folder. The window changes to show options for working with model documents.
3. Clear Enforce model document naming standards.
Caution:
Currently in HotDocs, template developers can include spaces and non-alphanumeric characters in variable
names. In some future version, however, HotDocs may require users to follow a newer, more standard practice of
naming variables that includes using only letters, numbers, and underscores.
See Model Document Naming Standards for more details.

Copyright 2010 HotDocs Ltd. All rights reserved

97

Help Topics for HotDocs Developer 10

Form Documents
The following topics discuss the options available in the Form Documents folder of HotDocs Options:

Change the Units of Measurement for Forms

HotDocs Automator measures the fields you create to identify whether they should be treated as check-box fields or edit
fields. In addition, the units of measurement affect the margins around all fields and the amount of space used by the
header and footer sections of the addendum.
To change the units of measurement

1. At the HotDocs library, click the

Options button. The HotDocs Options dialog box appears.

2. Click the Form Documents folder. The right pane changes to show options for working with forms.
3. Click the Show measurements in drop-down button and select Inches, Points, Centimeters, Picas, or
Millimeters.

Change Colors in HotDocs Forms

You can change the colors for field backgrounds and borders in HotDocs Automator. Changes affect all forms edited or
assembled using HotDocs. There are several custom color schemes from which you can choose.
To change colors

1. At the HotDocs library, click the

Options button. The HotDocs Options dialog box appears.

2. Click the Form Documents folder. The view changes to show general form options.
3. Click the Color theme drop-down button and select a color scheme.
Note:
To change the colors used for text template fields, see Define Colors for Fields and Instructions.

Send Assembled PDF Documents to Adobe

You can select an option that allows you send an assembled PDF-based document to Adobe Acrobat. When this option
is selected, you can click the
Send Document to Adobe Acrobat button and HotDocs will send the form document to
Acrobat rather than HotDocs Filler. (If you want to view the assembled form document in Filler, you can still choose this
option, too.)
To send assembled PDF-based documents to Adobe

1. At the HotDocs library, click the

Options button. The HotDocs Options dialog box appears.

2. Click the Form Documents folder. The right pane changes to show options for working with forms.
3. Click Send assembled PDF-based forms to drop-down button and choose Adobe Acrobat.
Note:
To always send PDF-based forms to HotDocs Filler, click Send assembled PDF-based forms to and choose
HotDocs Filler.

Copyright 2010 HotDocs Ltd. All rights reserved

98

Help Topics for HotDocs Developer 10

Control How Forms Appear When Opened

When you open a form in HotDocs Automator, different views of the form can be shown, such as fields, variable names in
fields, and thumbnail views of form pages. You can control which views appear, as well as what level of magnification is
used. These settings are used each time you open a form.
To control how forms appear when opened

1. At the HotDocs library, click the

Options button. The HotDocs Options dialog box appears.

2. Click the Form Documents folder. The right pane changes to show options for working with forms.
3. In the On Open group, select options that control the view when you open a form, as described in the following
table:
To

Do This

Display the colored fields

Select Highlight Fields.

Display the names of

variables attached to each
field

Click Show Variables.

Display thumbnail images

of each page of the form

Click Show Thumbnails.

Display forms at actual

size.

Click Zoom and select 100%

Match form width to the

left and right edges of the
window

Click Zoom and select Fit to Width.

Matches form height to the

top and bottom edges of
the window

Click Zoom and select Fit to Height.

The thumbnails appear in a separate pane in the window. You can click on the
thumbnail images to move through the form.

Note:
You can hide the fields, variables, and thumbnails by clearing these options.
To change the colors used for form fields, see Change Colors in HotDocs Forms.

Control Warnings During Assembly

When you assemble form documents, situations may arise where your answers may be altered. These situations include
when answers overflow the field, or when field settings are different. HotDocs can warn you in such situations.
To control warnings that display during assembly

1. At the HotDocs library, click the

Options button. The HotDocs Options dialog box appears.

2. Click the Form Documents folder. The right pane changes to show several options for working with forms.
3. In the While Filling group, make selections based on the following information:
Select Warn when leaving a field that overflows to display the Overflow Options dialog box when an
answer needs more space than the field allows.
Select Warn when typing in a restricted field to display the Restricted Field dialog box when you type in a
field that can't be answered until other fields have valid answers.
Copyright 2010 HotDocs Ltd. All rights reserved

99

Help Topics for HotDocs Developer 10

Select Warn when overriding a field to display the Override Field dialog box when you choose to override a
field.
Select Warn when attempting to create a field using the Fill tool to display a message explaining how to
create a field when viewing the Form Document tab of the assembly window.
Note:
You can choose to have no warnings appear by clearing these options. This will not automatically resolve answer
overflow or allow you to type answers in inactive fields. It only means no warnings will be displayed during the
interview or direct-fill. When you attempt to save or print the document, you must resolve the overflow.

Save Printer Information for Printing Forms

Forms may need to be printed using a specific printer. You can have HotDocs remember which printer you use to print
form documents, saving you the task of manually selecting the printer each time, especially when the printer you use for
forms is different than your default printer.
To save information about the printer you use to print forms

1. At the HotDocs library, click the

Options button. The HotDocs Options dialog box appears.

2. Click the Form Documents folder. The right pane changes to show several options for working with forms.
3. From the Printing group, select Remember the printer used for forms.
4. Print a form document, selecting the printer you want to associate with forms.
Note:
You can have HotDocs not remember printer information by clearing this option. This means HotDocs will suggest the
default printer you have selected for all printing.

Specify How PDF-based Forms Should Be Printed

When you print an assembled PDF-based form document, you can choose the program that controls the printing process
either HotDocs or Adobe Acrobat.
To specify how PDF-based form documents should always be printed

1. At the HotDocs library, click the

Options button. The HotDocs Options dialog box appears.

2. Double-click the Form Documents folder. The folder expands to show several sub-folders, and the right pane
changes to show several options for working with forms.

3. At the Print PDF-based forms using drop-down list, do one of the following:
Select Always Ask to have HotDocs prompt you for your choice each time you print a PDF form.
Select HotDocs to always print the assembled document using HotDocs' printing technology.
Select Adobe Acrobat to always print the document using Adobe's printing technology.
Note:
Click here for tips on which printing option you should choose.

Protect Forms By Backing Them Up

In HotDocs Automator, you can choose safety precautions to protect your work from system failure.
To protect your work from system failure

1. At the HotDocs library, click the

Options button. The HotDocs Options dialog box appears.

Copyright 2010 HotDocs Ltd. All rights reserved

100

Help Topics for HotDocs Developer 10

2. Click the Form Documents folder. The right pane changes to show several options for working with forms.
3. From the Recovery (HotDocs Automator only) group, make selections based on the following information:
Select Create backup copies of original templates to have HotDocs create a backup file when you first
create a new form template. If ever you need to revert to the file as it was when you created it, you can open
the backup file and save it using the original file name.
Select Maintain auto-recovery files while editing templates to have Automator create a log file that lists all
changes made directly in the form. If there is a system failure while you are working, the next time you open
the file, it will use the log file to reapply all changes made to the form, so you won't lose any work. (The log file,
however, doesn't back up the component file.)
Note:
Backup files are created in the same folder as the original file. If the folder is write-protected, the backup file is created
in the temporary folder defined by your TMP or TEMP system variable. The backup file has the same name as the
original file but with the extension ~FT, or ~PT. (If, for some reason, the backup file can't be created with that name, it
will have a number instead of the F or P in the extensionfor example, ~2T.) Each time you open the original file, its
current content will be saved to the backup file, overwriting the previous content.

Set Properties for New Edit Fields

You can specify the default properties that will be used each time you create an edit field in a HotDocs form. You can
control font sizes, text alignment and spacing, and field margins.
To set the properties for all new edit fields

1. At the HotDocs library, click the

Options button. The HotDocs Options dialog box appears.

2. Double-click the Form Documents folder. The folder expands to show several subfolders.
3. Open the Properties for New Fields folder. The window changes to show options that control how edit fields
appear.

4. Make changes in the Edit Fields group, based on information in the following table:
To

Do This

Set font properties for text

in edit fields

Click Font and make your changes at the Font dialog box.

Set the horizontal

alignment for text in edit
fields

At the Horizontal alignment drop-down list, select Left, Right, Center, or Justified.

Set the vertical alignment

for text in edit fields

At the Vertical alignment drop-down list, select Left, Right, Center, or Justified.
Note:
Vertical alignment is only apparent in multiple-line fields.

Align the text in multi-line

Select Set to Top for multi-line fields.
fields with the top border of
the field
Change the distance
between lines of text in a
multiple-line field

At the Lines per inch box, type a number (or click the up or down arrows to select a
number).

Keep the user from

manually entering multiple
lines of text in a single-line
answer field

Select Max lines 1 for single-line fields.

Copyright 2010 HotDocs Ltd. All rights reserved

101

Help Topics for HotDocs Developer 10

To

Do This

Changes the distance

between the text and the
edges of the field

At the Margins group, type a number (or click the up or down arrows to select a
number) for the left, right, top, and bottom margins.

Caution:
The changes you make are not applied to existing fields. The changes won't take effect until you create a new field.
To change the appearance of existing edit fields, right-click on a field in the form and select Field Properties from the
shortcut menu.
Note:
Some changes you make to these edit field properties may not affect specific fields because of settings assigned to
these fields. For example, if the Max Lines setting for a field is set to 1, the Lines per inch property will have no effect
this property only affects multiple lines of text, but the Max lines setting limits the field to one line of text.

Set Properties for New Check-Box Fields

When you create a field in a form template or document, HotDocs checks the size to see if it should be a check-box field.
You can adjust the measurement that is used to distinguish check-box fields from edit fields. If a new field is identified as
an edit field, HotDocs assigns standard formatting to the field that controls how answers appear in the field. You can also
assign other default properties of a check-box field, such as assign the character that will be used when a field is selected,
as well as set the alignment and margins of a field.
To set the properties for all new check-box fields

1. At the HotDocs library, click the

Options button. The HotDocs Options dialog box appears.

2. Double-click the Form Documents folder. The folder expands to show several subfolders.
3. Click the Properties for New Fields folder. The window changes to show field detection options that affect what
kind of fields are created.

4. Make changes in the Check-Box Fields group, based on information in the following table:
To

Do This

Set font properties for text

in check-box fields

Click the Font button, then make changes at the Font dialog box.

Sets the minimum size

for edit fields so that all
fields created smaller than
this size will be created as
check-box fields.

Enter a number in the Check-box detection threshold box.

Specify the character that

will be inserted in a check
box

Enter the character in the Character box.

Specify the smallest size

that will be used for the
check-box character

Enter a font size in the Minimum size box.

Note:
If you specify 0.00 as the value of this box, no new fields will be created as checkbox fields.

Set the horizontal

At the Horizontal alignment drop-down list, select Left, Right, Center, or Justified.
alignment for text in checkbox fields
Set the verticalalignment
for text in check-box fields

At the Vertical alignment drop-down list, select Left, Right, Center, or Justified.

Copyright 2010 HotDocs Ltd. All rights reserved

102

Help Topics for HotDocs Developer 10

To

Do This

Change the distance

At the Margins group, type a number (or click the up or down arrows to select a
between the check-box
number) for the left, right, top, and bottom margins.
character and the edges of
the field
Caution:
The changes you make are not applied to existing fields. The changes won't take effect until you create a new field.
To change the appearance of existing check-box fields, right-click on a field in the form and select Properties from the
shortcut menu.

Set Rules for Handling Answer Overflow

An answer overflows when it takes more space than is available in the answer field of a form document. This often
requires that some or all of the answer be sent to the addendum. You can set rules that automatically control what
happens when answers overflow.
To control what happens when answers overflow

1. At the HotDocs library, click the

Options button. The HotDocs Options dialog box appears.

2. Double-click the Form Documents folder. The folder expands to show several subfolders.
3. Open the Properties for New Fields folder, then select the Overflow Properties subfolder. The window changes to
show options that control answer overflow.

4. Make selections for handling edit field overflow, based on the following options:
Select Shrink answer as needed to and then enter the point size in the points box. HotDocs will attempt to
reduce the answer to this font size before warning of overflow.
Select Send answer to addendum to have HotDocs automatically resolve all overflow by sending answers to
the addendum.
Select Split multi-line answer between form field and addendum to have HotDocs send only the part of the
answer that overflows in a multi-line field to the addendum.

5. Make selections for handling table overflow, based on the following options:
Select Send entire table to send all answers in the table to the addendum.
Select Send complete rows to send answers from each row that contains a cell which overflows to the
addendum.
Select Send individual cells to send answers from individual cells that overflow to the addendum.
Caution:
The changes you make are not applied to existing fields. The changes won't take effect until you create a new field.
Note:
You can customize the reference that appears in the overflowed answer field. This can help you determine where
the answer is located in the addendum. (See Specify Addendum References and Labels for Answer Overflow.)
You can remove the rules that automatically handle answer overflow by clearing these options. This will require
you to manually resolve each instance of answer overflow.

Specify Addendum References and Labels for Answer Overflow

In a form document, when an answer overflows its answer field, the entire answer can be sent to an addendum. When
this happens, HotDocs inserts text into the answer field, cross referencing you to the addendum for the full answer. You
Copyright 2010 HotDocs Ltd. All rights reserved

103

Help Topics for HotDocs Developer 10

can specify what text is used in creating the cross reference as well as specify the text that identifies the answer once it
has been sent to the addendum.
To control what information appears in overflow references and in the addendum

1. At the HotDocs library, click the

Options button. The HotDocs Options dialog box appears.

2. Double-click the Form Documents folder. The folder expands to show several subfolders.
3. Open the Properties for New Fields folder, then select the Overflow Properties subfolder. The window changes to
show options that control answer overflow.

4. In the Cross-reference text box, enter the cross-reference text you want to merge in the field if the answer
overflows. (See Use Answer Overflow and Addendum Text Codes.)

5. In the Addendum label text box, enter the text you want to appear as the label for the entry in the addendum.
6. At the Table answer column indent box, enter a number (or click the up or down arrows to select a number) to
control the distance between the label for that specific entry in the list of answers and the actual answer.
Caution:
The changes you make are not applied to existing fields. The changes won't take effect until you create a new field.
Note:
If you leave the Cross-reference text box empty, HotDocs uses a default reference, See # in Addendum.

Automatically Generate Default Interviews for Form Templates

By default, when you create a new form template, the only option for assembling it is by entering your answers directly in
the fields on the form. You can, however, specify an option that causes HotDocs to generate a default interview for the
template, based on variables used in the template. If variables are grouped in custom dialogs, HotDocs will display the
dialog instead. (This is how interviews are created for text templates.)
To have HotDocs always create default interviews for all new form templates

1. At the HotDocs library, click the

Options button. The HotDocs Options dialog box appears.

2. Double-click the Form Documents folder. The folder expands to show several subfolders.
3. Click the Properties for New Forms folder.
4. Select Generate default interview from form fields.
Caution:
The changes you make are not applied to existing templates. The changes won't take effect until you create a new
template.
Note:
You can generate default interviews on a template-by-template basis (see Have HotDocs Generate a Default
Interview), or even create custom interviews for your form templates (see Define a Custom Interview).
You can prevent users from using the interview outline by clearing this option. This will force users to directly fill
the document at the Form Document tab.

Set Paper Size and Paper Source Defaults for Printing Forms
You can specify the paper size and paper source to be used when forms are printed.
To set paper size and paper source properties for a form

Copyright 2010 HotDocs Ltd. All rights reserved

104

Help Topics for HotDocs Developer 10

1. At the HotDocs library, click the

Options button. The HotDocs Options dialog box appears.

2. Double-click the Form Documents folder. The folder expands to show several subfolders.
3. Click the Properties for New Forms folder. The window changes to show options that control the properties of
newly created forms.

4. At the Sides drop-down list, select one of the available options:

Choose Single-sided to print the form on one side of the paper.
Choose Double-sided, side-to-side to print the form on both sides of the paper, so consecutive pages read
like a book.
Choose Double-sided, top-to-bottom to print the form on both sides of the paper, so consecutive pages read
like a flip-chart.

5. At the Paper Size drop-down list, select one of the available options.
6. At the Paper Source drop-down list, select one of the available options.
Caution:
The changes you make are not applied to existing templates. The changes won't take effect until you create a new
template.
Note:
You can use command-line options to specify these printing properties. See the Paper Tray and Paper Size commandline options.

Customize the Appearance of Addenda

You can format the form addendum to fit your project requirements.
To change the addendum's appearance

1. At the HotDocs library, click the

Options button. The HotDocs Options dialog box appears.

2. Double-click the Form Documents folder. The folder expands to show several subfolders.
3. Double-click the Properties for New Forms folder, then select the Addendum Properties subfolder. The window
changes to show options that control the format of the addendum.

4. In the Page Margins group, enter margin widths (or click the up or down arrows to select a number). These
numbers control the spacing between the answer text and the edges of the field.

5. In the Header Properties and Footer Properties groups, specify the header or footer text you want to appear in the
addendum:
At the Header text or Footer text box, type the text you want displayed in the addendum header or footer.
(See Use Answer Overflow and Addendum Text Codes.)
At the Height box, type a number (or click the up or down arrows to select a number). This number controls the
vertical height of the header section.
Click Font to display the Font dialog box, where you can change font properties of the header text.
At the Alignment drop-down list, select one of the available options: Left, Center, Right, or Justified.

6. In the Addendum Entries group, make the following changes:

To change the font properties of the addendum entries, click Font to display the Font dialog box.
To control the distance between the label and the actual answer, enter a number (or click the up or down
arrows to select a number) in the Indent box.
To control the distance between answers in the addendum, enter a number (or click the up or down arrows to
select a number) in the Spacing box.
Copyright 2010 HotDocs Ltd. All rights reserved

105

Help Topics for HotDocs Developer 10

7. Select Number lines to format as pleading paper to place lines on the right and left side of the addendum, with
numbers along the entire left edge.
Caution:
The changes you make are not applied to existing forms. The changes won't take effect until you create a new
template.

Copyright 2010 HotDocs Ltd. All rights reserved

106

Help Topics for HotDocs Developer 10

Question and Answer Summaries

The following topics discuss the options available in the Question and Answer Summaries folder of HotDocs Options:

Change the Way Question and Answer Summaries Appear

In question and answer summaries, you can specify a one-column or a two-column format:
The one-column format displays a simple list of variable prompts and answers (if you're generating an answer
summary) or empty answer fields (if you're generating a question summary). Prompts and answers are grouped by
dialogs. To make these summaries easier to read, you can indent these lists or use bullets.
The two-column format displays a list of variable prompts in one column and their associated answers (if you're
generating an answer summary) or empty answer fields (if you're generating a question summary) in a second
column. Prompts and answers are grouped by dialogs. You can control the appearance of these columns by
specifying borders and choosing the width of the column that contains the prompt.
To format question or answer summaries

1. At the HotDocs library, click the

Options button. The HotDocs Options dialog box appears.

2. Click the Question and Answer Summaries folder. The right pane changes to show the summary options.
3. If you want the summary to appear in one-column format, click the Format drop-down button, choose One-Column,
and select from the following options:
Select Indent prompts under dialog titles to include a tab between the column's margin and the prompt.
Selecting this option makes the dialog titles and variable prompts appear hierarchical.
Select Precede prompts with bullet to insert a bullet character next to each prompt.
Select Indent answers under prompts to include a tab between the column's margin and the answer.
Selecting this option makes the prompts and the answers appear hierarchical.
Select Precede answers with bullet to insert a bullet character next to each answer.

4. If you want the summary to appear in two-column format, click the Format drop-down button, choose Two-Column,
and select from the following options:
Select a border style from the Borders drop-down list. Your options include None, Plain, and Sculptured.
Specify a percentage in the Percent of width taken by prompt box. This percentage determines how much
of the viewable window is used to display the prompt. You can change this number by clicking the up or down
arrows, or by typing a number directly in the field.

5. Optionally, change the number in the Maximum multiple-choice options to display box to control the number of
multiple-choice options that appear in a question or answer summary.

Control Which Variables are Asked in a Question Summary

Typically question summaries include all questions in a template. However, some questions may not be asked unless
certain conditions are met or certain answers are entered. These kinds of questions are called conditional variables. You
can limit question summaries so they show only the questions that are applicable, based on certain answers you provide.
An example of a conditional variable might be the section of an employee agreement template that deals with employee
benefits. Questions relating to employee benefits are asked only if the employee qualifies for benefits. If you assemble
a question summary for an employee who does not meet the conditions, the benefits questions should not appear in the
summary.
To control conditional variables in a question summary

1. At the HotDocs library, click the

Options button. The HotDocs Options dialog box appears.

Copyright 2010 HotDocs Ltd. All rights reserved

107

Help Topics for HotDocs Developer 10

2. Click the Question and Answer Summaries folder. The window changes to show several summary options.
3. In the Question Summaries group, select Honor IF instructions when answered.
This setting will take effect when you assemble a document, answer the conditional variables, and then view the question
summary.
Note:
To once again generate a question summary that shows all the document questions, clear Honor IF instructions
when answered.

Copyright 2010 HotDocs Ltd. All rights reserved

108

Help Topics for HotDocs Developer 10

Personal Information
The following topics discuss the options available in the Personal Information folder of HotDocs Options:

Create Personal Information Variables

Personal Information variables gather basic information, such as your name, company, and phone number. This
information is stored in the Current User section of the system registry so it can be used in assembled documents without
you having to re-enter it.
You can create your own Personal Information variables for use in templates you automate. (See Insert a Personal
Information Variable for details on how to do this.) You can also remove any custom Personal Information variables you
create.
To create a new Personal Information variable

1. At the HotDocs library, click the

Options button. The HotDocs Options dialog box appears.

2. Click the Personal Information folder. The right pane changes to show several Personal Information variables.
3. With the contents of the Personal Information folder displayed, click Add. The Add Personal Information dialog
box appears.

4. Type the name of the variable in the Variable box.

5. If you know the value you want assigned to the variable, type it in the Answer box and click OK.
Note:
To remove custom Personal Information variable you have created, select the variable and click Delete. Click Yes to
confirm the deletion.

Edit Answers for Built-In Personal Information Variables

Personal Information variables gather basic information, such as your name, company, and phone number. This
information is stored in the Current User section of the system registry so it can be used in assembled documents without
you having to re-enter it.
When you assemble a document using a template that has Personal Information variables, HotDocs asks for any personal
information required by the template that you havent already entered. If you want to specify this information before
document assembly, however, or if you want to change existing answers, you can do this at the HotDocs Options dialog
box.
Because built-in variables are shared between all users of your workstation, you cannot delete the variable. You can,
however, remove any personal information that has been entered for it.
To edit answers for Personal Information variables

1. At the HotDocs library, click the

Options button. The HotDocs Options dialog box appears.

2. Click the Personal Information folder. The right pane changes to show several Personal Information variables.
3. Select the variable you want to modify and click Edit. The Edit Personal Information dialog box appears.
4. Enter an answer in the Answer box and click OK. The value is now listed in the Answer column.
Note:
To remove an answer for a Personal Information variable, select the variable that contains the answer and click
Delete. Click Yes to confirm the deletion.

Copyright 2010 HotDocs Ltd. All rights reserved

109

Help Topics for HotDocs Developer 10

Spell Checking
The following topics discuss the options available in the Spell Checking folder of HotDocs Options:

Change Your Spell Checking Options

HotDocs can spell check text used in component files as well as answers entered during an interview.
As HotDocs spell checks, it looks at the spell checking settings stored in the HotDocs section of the system registry to
determine what words the spell checker looks at and how it decides on words to suggest as possible alternatives to words
not in the dictionary. You can change these settings.
To change your spell checking options

1. At the HotDocs library, click the

Options button. The HotDocs Options dialog box appears.

2. Click the Spell Checking folder. The contents of the window change to show your spell checking options.
3. Select appropriate options, as described in the following table:
To

Do This

Cause HotDocs to ignore

Select Ignore capitalized words (e.g. Canada).
capitalized words, such as
names, cities, titles, and so
on
Cause HotDocs to ignore
words that contain all
capital letters, such as
acronyms or abbreviations

Select Ignore words in all capitals (e.g. ASAP).

Cause HotDocs to ignore

words that contain both
uppercase and lowercase
letters

Select Ignore words with mixed case (e.g. InLine).

Cause HotDocs to ignore

words that also contain
digits

Select Ignore words with digits (e.g. Win95).

Cause the replacement

words HotDocs suggests
to match the case of the
misspelled word

Select Match case when comparing.

Cause HotDocs to match

the case of misspelled
words when replacing
them

Select Match case when replacing.

Cause HotDocs to
provide a list of possible
replacements for
misspelled words

Select Always suggest replacements.

Cause HotDocs to
provide a list of possible
replacements based on
words that sound like the
misspelled word

Select Make phonetic suggestions.

Copyright 2010 HotDocs Ltd. All rights reserved

110

Help Topics for HotDocs Developer 10

To

Do This

Cause HotDocs to
provide a list of possible
replacements based
on words that are
typographically similar

Select Make typographical suggestions.

Cause HotDocs to
provide a list of possible
replacements that are
made up of more than one
word

Select Make split word suggestions.

Cause HotDocs to check

the spelling only if the text
is more than 1 line

Select Check multiple-line text only.

Cause HotDocs to use the

British spelling dictionary
rather than the English
dictionary

Select Use UK spelling dictionary.

When a word is not in the spelling checkers dictionary, HotDocs checks for it in your personal dictionary, Personal
Dictionary.TLX. If it is not found there, you can add it by clicking Add at the Check Spelling dialog box.
Note:
You can change these settings whenever you are spell checking. To do this, click Options at the Check Spelling
dialog box.

Copyright 2010 HotDocs Ltd. All rights reserved

111

Help Topics for HotDocs Developer 10

Template Development
The following topics discuss the options available in the Template Development folder of HotDocs Options:

Have HotDocs Automatically Complete Component Names

You can have HotDocs suggest existing component names as you type. HotDocs can also suggest example formats and
text patterns.
To turn on Auto Complete in Component Editors

1. At the HotDocs library, click the

Options button. The HotDocs Options dialog box appears.

2. Click the Template Development folder. The window changes to show several different template development
options.

3. Select Auto complete while typing component names.

Have HotDocs Automatically Generate Dialog Element Component Names
When creating dialog elements, you can have HotDocs automatically name the component for you, based on information
about the type of element you are creating. Specifically, HotDocs includes in the name the type of element you are
creating, followed by any additional information you enter about the element, such as the display text or caption. For
example, if you are creating a Script Link element that links to a Computation variable named Tax Calculator, HotDocs will
name the component Script Link Tax Calculator.
When you select this option, the Generate name automatically property will be set at the Dialog Element Editor for
each new dialog element you create.
To auto-generate dialog element component names

1. At the HotDocs library, click the

Options button. The HotDocs Options dialog box appears.

2. Click the Template Development folder. The window changes to show several different template development
options.

3. Select Always generate name automatically when dialog element created.

Choose Icon Style for Component Lists
When HotDocs displays lists of components, it uses an icon, followed by the name of the component. You can change the
icon to show either a symbol of the component, or an abbreviation for the type of component it is. For example:
Displays all components with a short text abbreviation representing the component type.
For example, this icon represents a Text variable.
Displays all components with a graphic image representing the component type. For
example, this icon represents a Text variable.
To change the component icon style

1. At the HotDocs library, click the

Options button. The HotDocs Options dialog box appears.

2. Click the Template Development folder. The window changes to show several different template development
options.

3. At the Component type icons in component lists drop-down list, select either Graphic or Text.

Copyright 2010 HotDocs Ltd. All rights reserved

112

Help Topics for HotDocs Developer 10

Control When Returns Are Inserted After Instructions in Text Templates

By default, when inserting instructions in a template, HotDocs inserts a return after the instruction. Then, as the instruction
is processed and removed from the assembled document during assembly, HotDocs removes the return it inserted as
well.
One reason why HotDocs includes these returns after instructions is to make it easier to view template text in relation to
the instructions, particularly when the instruction controls the appearance of an entire paragraph of text.
In this example, returns are inserted after the instruction. This keeps instructions on their own lines and makes it easier to
view how the instructions relate to the text.
SHIPPED TO
IF Different Shipping Address
Shipping Name
Shipping Street
Shipping City, Shipping State Shipping ZIP
ELSE
Billing Name
Billing Street
Billing City, Billing State Billing ZIP
END IF
In this example, returns are not included after each instruction. This makes it more difficult to see the conditions in relation
to the text.
SHIPPED TO
IF Different Shipping AddressShipping Name
Shipping Street
Shipping City, Shipping State Shipping ZIP
ELSEBilling Name
Billing Street
Billing City, Billing State Billing ZIPEND IF
In some situations, however, having this return in the template text may actually make the text more difficult to read, for
instance, because the instructions control the appearance of text within a paragraph and not the paragraph as a whole.
In this example, the returns after the instructions force text within a paragraph to a new line. This may be confusing to
understand.
Health insurance is provided as one of the benefits of your employment with Hobble
Creek Publishing. The insurance policy is through TLC Insurance and will cover you,
your spouse, and any minor children. Your insurance coverage will begin IF DAY
OF( Hire Date ) = 1
Hire DateELSE
Coverage Start DateEND IF
.
In this example, the returns after the instructions are omitted, allowing all of the text to remain in the same paragraph.
Health insurance is provided as one of the benefits of your employment with Hobble
Creek Publishing. The insurance policy is through TLC Insurance and will cover you,
your spouse, and any minor children. Your insurance coverage will begin IF DAY
OF( Hire Date ) = 1Hire DateELSECoverage Start DateEND IF.
In most cases, you most likely want returns inserted when merging an entire paragraph, and you want returns omitted
when inserting just short blocks of inline text. Whatever your preference, you can choose an option that best suits your
needs.
To determine whether (and when) HotDocs inserts returns after instructions

1. At the HotDocs library, click the

Options button. The HotDocs Options dialog box appears.

Copyright 2010 HotDocs Ltd. All rights reserved

113

Help Topics for HotDocs Developer 10

2. Click the Template Development folder. The window changes to show several template development options.
3. Click the Insert returns after instructions in text templates drop-down button and choose an option, based on the
following information:
Choose Always to have HotDocs always insert a return character after an instruction. (Remember, HotDocs
will remove the return during assembly.)
Choose Smart to have HotDocs determine whether it should insert a return character or not. It determines
how to insert these returns based on surrounding characters (such as paragraph breaks) in the text. (See
Understand How Smart Returns are Inserted After Instructions for a complete description.)
Choose Never to have HotDocs never insert a return character after an instruction.
Caution:
WordPerfect 8 and WordPerfect 9 users: Because of some problems with underlying text selection when inserting
instructions in a template, you should set Insert returns after instructions in text templates to Always. Selecting
Smart or Never will cause errors during assembly.

Enable Document Editing Options for All New Templates

Note:
Document editing options are currently available for Microsoft Word users only.
Often, as users are reviewing their assembled documents, they may need to see exactly where their answers have been
merged. Sometimes they may need to edit or change those answers as well. To allow this functionality for your users,
you must specify the component file property for each of the templates in your set. Rather than set it in each template
individually, you can specify an option that will set this property in each new template you create.
Specifically, these options allow the user to highlight where answers in the document have been merged, and edit the
answer while at the Document Preview tab.
For more information on working with the assembled document, see Edit Answers at the Document Preview Tab.
To set the component file properties for editing text documents

1. At the HotDocs library, click the

Options button. The HotDocs Options dialog box appears.

2. Click the Template Development folder. The window changes to show several different template development
options.

3. In the Component File Properties for New Templates group, select Mark answers in assembled documents.
4. Optionally, select Enable Edit Answer at Document Preview tab.
Now, in each new template you create, these component file properties will be set.
To set the properties for existing templates, change them at the Component File Properties dialog box (see Change
Component File Properties) or change the properties in multiple templates at once using Template Manager (see Modify
Component File Properties Across Multiple Files).

Enable All New Templates for Use with HotDocs Server

When creating templates for use with HotDocs Server, some features (such as clause libraries and database
components) are not allowed. You can have HotDocs warn you of this when you are creating templates and you attempt
to use such a feature.
Additionally, when templates are enabled for HotDocs Server, you can test assemble the template in a Web browser as
well as publish the files required for the template to reside on the server.
To allow all new templates you create to be used with HotDocs Server
Copyright 2010 HotDocs Ltd. All rights reserved

114

Help Topics for HotDocs Developer 10

1. At the HotDocs library, click the

Options button. The HotDocs Options dialog box appears.

2. Click the Template Development folder. The window changes to show several different template development
options.

3. In the Component File Properties for New Templates group, select Enable for use with HotDocs Server.
Now, in each new template you create, this component file property will be set. To set the properties for existing
templates, change them at the Component File Properties dialog box (see Change Component File Properties). Or
change the properties in multiple templates at once using Template Manager (see Modify Component File Properties
Across Multiple Files).
Note:
If you don't want every template you create to be enabled for server-based assembly, you can set this option on
a per-template basis by changing the specific template's component file properties. (See Change Component File
Properties.)

Display HotDocs Warning Messages

Sometimes HotDocs warns you when it is about to perform an operation that could impact the work you are doing. When
HotDocs displays these warnings, it gives you the option of suppressing the warnings the next time you perform a similar
operation. You can have HotDocs re-display these warnings after you have suppressed them.
To cause HotDocs to display warnings

1. At the HotDocs library, click the

Options button. The HotDocs Options dialog box appears.

2. Click the Template Development folder. The window changes to show several different template development
options.

3. In the Warning Messages group, make your selection, based on the following information:
To have HotDocs warn you when it is about to convert a template to the current version of HotDocs, select
Warn before automatically converting templates. (See Compatibility of HotDocs 10 Files with Earlier
Versions of HotDocs and Convert a Single Template to a New File Format.)
To have HotDocs warn you when you edit a template that is using a shared component file, select Warn when
editing pointed component files.
To have HotDocs warn you when you are moving a variable from one dialog to another, select Warn when
variables automatically removed from dialogs. (See Use the Same Variable or Clause in Two or More
Dialogs.)
To have HotDocs remind you that changes are saved when you close a Component Editor using buttons in the
title bar, select Warn when component editors closed via title bar.
Now, when HotDocs performs related actions, it will display the associated warning.

Change Script Editing Options

You can control the formatting HotDocs uses when you write scripts. For example, you can designate the font size of the
text used in the script editor, as well as associate colors with certain types of script keywords, placeholders, components,
or operators.
To change the options available for writing scripts

1. At the HotDocs library, click the

Options button. The HotDocs Options dialog box appears.

2. Double-click the Template Development folder. The folder expands to show a subfolder named Script Editor.
3. Click the Script Editor folder. The window changes to show several options for customizing HotDocs scripts.
Copyright 2010 HotDocs Ltd. All rights reserved

115

Help Topics for HotDocs Developer 10

4. Perform any of the following tasks:

To

Do This

Have HotDocs start the

next line of a script (after
you enter a return) at the
same level of indentation

Select Automatic indentation.

Include keywords for

months, language codes,
and so forth in the autocomplete list

Select Include seldom-used keywords in auto-complete list. (If you'd rather

exclude these keywords from the list, clear this option.)

Allow the Tab key to insert

a tab in a script, rather
than move you to the next
field in the component
editor

Select Tab key inserts a tab in scripts. Now, whenever you press Tab or Shift
+Tab, HotDocs will insert a tab in the script.
Caution:
If you select this option, you can no longer use keyboard commands to move
from the Script box to another field in the component editoryou must use your
mouse to click out of the Script box.

Specify the number of

Enter a number in the Tab width box.
characters HotDocs should
use when you insert a tab
in the script
Have HotDocs use colors
to differentiate between
instruction and expression
keywords, operators, and
component names

Select Syntax coloring. (You can then either accept the default colors HotDocs
assigns to these, or you can designate your own colors at the Colors and Attributes
list.)

Assign colors and other

formatting attributes to the
various parts of a script

Select the item, click the Color drop-down button, and choose a color. You can also
select Bold to make the item bolded, and you can select Italic to italicize the item.

These "parts" include

instruction keywords,
expression keywords,
components (such as
variables and dialogs),
text values (literal text
strings), other values
(such as literal number
and date values and
language codes),
placeholders, operators,
commented scripts, and
any syntax HotDocs
doesn't recognize.
Specify the font used for
the script

To restore the HotDocs defaults, select the script element, click the Color drop-down
button, and choose Default from the top of the Palette tab.

Click Select Font and make your selection. You can also specify the size of the
script text.

Copyright 2010 HotDocs Ltd. All rights reserved

116

Help Topics for HotDocs Developer 10

Set Template Manager Options

You can change the way Template Manager displays the information it generates about components it is showing.
To change the way Template Manager displays component information

1. At the HotDocs library, click the

Options button. The HotDocs Options dialog box appears.

2. Double-click on the Template Development folder to expand it. The window changes to show several template
development options.

3. Click the Template Manager folder. The window shows Template Manager options.
4. Complete any of the tasks listed in the following table:
To

Do This

Expand the list of

components to include
example formats, patterns,
and so forth.

Select Include supplemental components in component list.

Include a column in the

component list that shows
component types

Select Show component type column.

Include a column in
the component list that
shows the status of the
components

Select Show component status column. The status tells you whether the
component is OK (used in both the template and component file), unused (the
component is not referenced in any templates), or missing (the component is
referenced in a template, but not found in the component file).

Have Template Manager

overlay a graphic
reminder of what the
component's status is on
the component's icon

Select Overlay status hint on component icons.

Note:
You can also access these options by clicking the Options button in the Template Manager toolbar.

Copyright 2010 HotDocs Ltd. All rights reserved

117

Help Topics for HotDocs Developer 10

Word Processors
The following topics discuss the options available in the Word Processors folder of HotDocs Options:

Install Support for New Word Processors

Caution:
Before installing support for a new word processor, make sure you run the newly installed word processor program at
least once. This creates entries for the new word processor in the Windows System Registry that HotDocs needs to
properly integrate with the word processor.
When you install a new word processor and you want to use it with HotDocs, you can install support for it through
HotDocs Options. If multiple users use the workstation, support for the word processor will be installed for them as well.
To install new word processor support

1. Install the new word processor and run it at least once.

2. Start HotDocs. (See Start HotDocs.)
3. At the HotDocs library, click the

Options button. The HotDocs Options dialog box appears.

4. Click the Word Processors folder. The right pane changes to show a list of word processors which HotDocs
supports. (Word processors for which you have already installed support are selected, while word processors that
are not installed are disabled.)

5. Select the word processor for which you want to install support.
6. Click OK. The HotDocs Options dialog box closes.
Once you close the HotDocs Options dialog box, HotDocs runs the Current User Setup, which copies the required files to
the correct program folders. (See Understand HotDocs Installation.)
Note:
Click here to see a list of which word processors are supported for this release.
To make the newly installed word processor the default word processor, you must manually select it after you
install support for it. See Change Your Default Word Processor for details.
You may need to restart the word processor to add the correct HotDocs buttons and toolbars to it.

Change Your Default Word Processor

If you have both Microsoft Word and WordPerfect installed for HotDocs, you must choose which word processor HotDocs
should use as the default. The default word processor controls which word processor file type will be suggested when you
create a new template. It also determines which word processor will be opened when you finish the interview and send
the assembled document to it.
To specify a default word processor

1. At the HotDocs library, click the

Options button. The HotDocs Options dialog box appears.

2. Click the Word Processors folder. The right pane changes to show supported word processors.
3. Click the Default word processor drop-down button and select a word processor.
4. Optionally, to send assembled documents to the word processor that matches the template file type, select Send
assembled documents to word processor based on template type.

5. Optionally, to start Word before you send the assembled document to it, select Launch Word before sending
to word processor (allows auto macros to run). (This is useful if the underlying template uses AutoExec or
Copyright 2010 HotDocs Ltd. All rights reserved

118

Help Topics for HotDocs Developer 10

AutoOpen macros, since HotDocs explicitly disables the execution of Auto macros in Word before it sends a
document to Word after assembly.)
Note:
Click here to see a list of which word processors are supported for this release.

Change Word Processor File Locations

By default, HotDocs uses certain folders that were specified during installation to store text templates and assembled text
document files that are used with HotDocs. These folder names and file paths become the default location HotDocs looks
when no specific path is assigned at the file's properties.
At the library, you can check whether a full path is given by selecting the template and clicking the
Properties button.
If a full path is given, HotDocs uses that information when accessing the file. Otherwise, HotDocs uses the default file
location specified here.
You can change the locations HotDocs looks for these files.
To change the location of word processor files

1. At the HotDocs library, click the

Options button. The HotDocs Options dialog box appears.

2. Double-click the Word Processors folder so that it expands to show subfolders for each word processor that is
installed.

3. Click the word processor folder for which you want to make changes. The right pane changes to show the different
file locations of the document, template, and startup files (or macro files for WordPerfect users).

4. For each file location you want to change, click the

Browse button next to the file location path and navigate to

the new location.

If templates in your library use the default file path for its templates, you must move your templates to this new location or
HotDocs will not be able to find them. See Move Items to New Locations on Disk.

Copyright 2010 HotDocs Ltd. All rights reserved

119

Help Topics for HotDocs Developer 10

File Locations
The following topics discuss the options available in the File Locations folder of HotDocs Options:

Change HotDocs Program File Locations

When you install and use HotDocs, the program makes several entries in the System Registry that indicate to HotDocs
where to look for files, as well as where to suggest you save files. (See Understand HotDocs Installation.) In most
situations, HotDocs uses this information each time you perform a task in HotDocs. For example, each time you create a
new template, HotDocs suggests a default location for the new template, based on the information it finds in the System
Registry. If you ever need to change these default locations, you can do so at HotDocs Options.
If a full path is specified for the file you are attempting to access, that file path will be used, rather than the default file
path. (To check whether a full path is given, select the item and click the

Properties button.)

You can change the default location HotDocs looks for the following files:
Library files (HDL files).
Template files (HFT, HPT, and CMP files). (To change the default location for text templates, see Change Word
Processor File Locations.)
Template Sets (installed HDI files).
Catalog Files (files used to keep published template sets up to date).
Answer files (ANX files).
Form document files (HFD, HPD, and PDF files).
Publish Settings files (HDP files).
To change the default location of HotDocs files

1. At the HotDocs library, click the

Options button. The HotDocs Options dialog box appears.

2. Click the File Locations folder. The window changes to show a listing of the different HotDocs file paths.
3. In the HotDocs Folders group, select a file type and click Edit. The Browse for Folder dialog box appears
4. Browse to the new location and click OK. HotDocs will use this location as the new default.
Caution:
You must restart HotDocs for these changes to take effect.

Assign Reference Paths to HotDocs Files

A HotDocs library will work only if each template listed in the library is located in the exact path specified in the Item
Properties dialog box for that template. This makes it difficult to create a library that will work for multiple users who will
not store the templates in the same locations. A reference path lets you create a library that will work, regardless of where
users store their templates.
A reference path is a folder path for a template in which the drive letter and some or all of the folder names have been
replaced with a caret (^) and a keyword. The keyword is associated with an actual folder path in the user's HotDocs
settings. When HotDocs needs to open a template, it replaces the caret and keyword in the folder path for the template
with the folder path that is associated with the keyword in the user's HotDocs Options.
Some common uses of reference paths are:
With distributed template sets which allow users to choose where they install the templates (even if they can only
choose the drive to which the templates are installed).
Copyright 2010 HotDocs Ltd. All rights reserved

120

Help Topics for HotDocs Developer 10

With templates located on a network drive that is mapped to a different letter for some of the users.
In order for your library to work for users regardless of where they store the templates, you need to enter a reference path
for all templates and clause libraries in the library. You should use the same keyword for all the items in the library.
If you know the library items won't all be stored in the same subfolders, use the keyword only in place of the part of the
path that is identical for all items. For example, if some of the templates will be stored in a General subfolder and others
will be stored in a Family Law subfolder, you would use the reference path ^keyword\General\template.ext for those
templates in the General subfolder and ^keyword\Family Law\template.ext for those templates in the Family Law
subfolder (where keyword is a placeholder for the keyword you use and template.ext is a placeholder for the file name and
extension of the template).
To associate a keyword with a path and assign the reference path

1. At the HotDocs library, click the

Options button. The HotDocs Options dialog box appears.

2. Click the File Locations folder. The window changes to show a listing of the different HotDocs file paths.
3. In the Reference Paths section, click Add. The Add/Edit Reference Path dialog box appears.
4. Type a keyword for the reference path in the Keyword box.
5. Click the

Browse button next to the Path box, and specify the path to the subfolder you want to use.

6. Click OK.
Once you have designated the keywords and paths that HotDocs needs to know about your files, you can assign
reference paths to the templates. (These templates must be saved to the subfolder you specified in Step 5, above.)

7. At the HotDocs library window, select the template for which you want to specify a reference path and click the
Properties button. The Item Properties dialog box appears.

8. If the File name box contains a folder path as well as a file name, delete the part of the path that is the same for all
items in the library.

9. Place your cursor before the first letter in the File name box and type caret (^), the keyword, and a backslash (\).
10. Click OK.
Note:
When publishing your template set as an auto-install (.HDI) file, HotDocs automatically creates the reference paths and
enters the correct information in the user's HotDocs settings during installation.
Note:
For instructions on assigning reference paths to multiple library items, see Change the Properties for Multiple Items in
a Library.

Copyright 2010 HotDocs Ltd. All rights reserved

121

Help Topics for HotDocs Developer 10

File Management
The following topics discuss the options available in the File Management folder of HotDocs Options:

Manage Answer Files

To work with answer files, you can either use Answer File Manager, or you can use Windows Explorer. (See Overview:
Use Answer Management.) Answer File Manager uses an answer library (.HAL) file to create, store, and select answer
files. Windows Explorer allows you to work with answer files using the common File > Open or File > Save dialog boxes.
Which option you choose depends on your preference. For example, Answer File Manager works well if you are the only
user and you like the functionality available with a library. However, Windows Explorer makes more sense for managing
answer files in a multi-user setting. Windows Explorer also lets you see more clearly where the actual answer files are
saved.
To change how HotDocs locates and manages answer files

1. At the HotDocs library, click the

Options button. The HotDocs Options dialog box appears.

2. Click the File Management folder. The window changes to show file management options.
3. Click the Manage answer files using drop-down button and select an option:
HotDocs Answer File Manager uses an answer library to create, store, and select answer files.
Caution:
The first user to open an answer library is the only one who has write access to it. That means only one
person can modify items in the library at any given time. If multiple users must access the answer files, use
Windows Explorer to manage the files.
Windows Explorer uses Windows Explorer to create, save, and select answer files.
Document Manager uses a third-party document management program to manage the use of answer files.
(To use this option, make sure you specify the ODMA DLL file name and path in the Document manager
ODMA DLL location box.)

4. If you selected Document Manager, choose one of the following options from the Answer file save format dropdown list:
Ask Before Saving causes HotDocs to prompt for the file format each time an answer file is saved.
HotDocs Answer File (.anx) automatically saves the file in HotDocs 2009-10 format.
HotDocs 2005-2008 Answer File (.anx) automatically saves the file in HotDocs 2005-2008 file format. (See
Compatibility of HotDocs 10 Files with Earlier Versions of HotDocs.)

Manage Assembled Document Files

You can use a document management program to control how assembled documents are saved. You can also specify
the format HotDocs uses when it saves the document to the document manager.
To manage assembled documents

1. At the HotDocs library, click the

Options button. The HotDocs Options dialog box appears.

2. Click the File Management folder. The window changes to show file management options.
3. Click the Manage assembled documents using drop-down button and select an option:
Windows Explorer uses Windows Explorer to save and access assembled document files.

Copyright 2010 HotDocs Ltd. All rights reserved

122

Help Topics for HotDocs Developer 10

Document Manager uses a third-party document management program to manage assembled document
files. (To use this option, make sure you specify the ODMA DLL file name and path in the Document manager
ODMA DLL location box.)

4. If you select Document Manager, you can specify the format of the assembled document by clicking the Save
format drop-down button next to the types of documents you are saving and making a selection.

Specify Document Management Settings

You can use a third-party document management program to manage documents and answer files you create using
HotDocs.
When creating these third-party integrations, you must define several settings that indicate how HotDocs should
"communicate" with the document manager. This includes providing application IDs for each of the applications used by
HotDocs as well as providing file formats for the different files generated by a HotDocs assembly.
By default, HotDocs suggests values for each of these settings; however, you can change these values to match those
values defined by the document manager.
To define advanced ODMA settings

1. At the HotDocs library, click the

Options button. The HotDocs Options dialog box appears.

2. Click the File Management folder. The window changes to show file management options.
3. Choose one or both of the following options:
Click the Manage answer files using drop-down button and select Document Manager.
Click the Manage assembled documents using drop-down button and select Document Manager.

4. Click the Advanced ODMA Settings folder in the list on the left. The view changes to show advanced ODMA
settings.

5. In the Application IDs group, accept the default suggestions, or change the different IDs to match those defined by
your document manager.

6. In the Format Names group, accept the default file name suggestions, or change the file name extensions to match
those defined by your document manager.
Caution:
ODMA integrations do not support the use of foreign characters (for example, international characters that are not
represented in your computer system's default language). If you use foreign characters in the advanced ODMA
settings, or when profiling a document in the DMS, the ODMA integration will not work correctly.

Copyright 2010 HotDocs Ltd. All rights reserved

123

Help Topics for HotDocs Developer 10

Template Set Updates

The following topics discuss the options available in the Template Set Updates folder of HotDocs Options:

Determine How Frequently HotDocs Checks for Template Set Updates

If you are using a published template set and the template publisher provides automatic updates, you can have HotDocs
check for these updates each time you start HotDocs. (Please check with your template set publisher to determine if your
template set includes automatic updates.)
To check for template set updates

1. At the HotDocs library, click the

Options button. The HotDocs Options dialog box appears.

2. Click the Template Set Updates folder. The window changes to show update options.
3. Complete any of the following optional steps:
To

Do This

Always check for updates

when you start HotDocs

Select Perform scheduled checks for updates when HotDocs is started. (If
HotDocs detects an update, it displays a warning icon in the status bar of the
HotDocs window.)

Display a window that

shows the progress
HotDocs makes in
installing the updates

Select Show progress window when checking for updates.

Choose the template sets

for which you want to
check for updates

Select the set in the Select the template sets you want to keep up-to-date list.

Copyright 2010 HotDocs Ltd. All rights reserved

124

Help Topics for HotDocs Developer 10

SECTION 4:
USING LIBRARIES

Copyright 2010 HotDocs Ltd. All rights reserved

125

Help Topics for HotDocs Developer 10

Chapter 7: Using HotDocs Libraries

Overview: Use HotDocs Libraries
HotDocs filessuch as templates, clause libraries, and answer filesreside in folders on your local disk or on a network.
To make it easier to organize templates and clause libraries, you can use a HotDocs template library or, for answer files,
the Answer File Manager. Using a library lets you assign titles and descriptions to files, and, in the case of answer files,
track the history of when a file is used.
Template libraries help you organize template files and provide quick access to many HotDocs tools, such as the
Assembly Queue and HotDocs Options:

The Answer File Manager is a library of answer files. You can group answer files as well as sort them. You can also view
a history of when a specific answer file was used:

Copyright 2010 HotDocs Ltd. All rights reserved

126

Help Topics for HotDocs Developer 10

Both the template library and Answer File Manager are divided into two panes. The left pane shows a list of the items
referenced in the library. Depending on what kind of library it is, these items can include folders, templates, clause
libraries, or answer files. The right pane displays information about the selected item. A different view shows the contents
of the file.
The items you see in the left pane are not the actual HotDocs files on your local disk or network. Instead, they are
references to the files, operating similar to Windows-type shortcuts. When you select an item for assembly, HotDocs
follows the assigned file path and locates the actual template or answer file.
Additionally, folders in a library help you organize the list of files in the librarynot the actual folders on the local disk or
network.
Caution:
Because the items in the library work like shortcuts to the actual files, you must be cautious when working with the
actual files. Moving an actual file without updating the reference in the library will make the file inaccessible from the
library. If you need to move the files in the library, use either the Move command or the Copy command (see Move
Items Within a Library and Copy Templates to New Locations). If you need to update references, choose Properties
or Multiple from the Edit menu. (See Change the Properties of a Single Library Item or Change the Properties for
Multiple Items in a Library.)
The library window is the starting point for many HotDocs tasks. Such tasks include organizing templates, moving
templates and component files, editing templates, assembling documents, and accessing other HotDocs tools, such as
Answer File Manager, HotDocs Options, and Component Manager.

Copyright 2010 HotDocs Ltd. All rights reserved

127

Help Topics for HotDocs Developer 10

Create a Library
You may want to use separate libraries for templates that deal with different matters. For example, you may want to
create one library for divorce templates and another library for estate planning templates. When you create a library,
you create an .HDL file on the disk. Once it's created, you can add references to templates to it as well as organize it in
whatever way you need.
By default, all new libraries you create will be saved in XML format. If you need to use the library with versions of HotDocs
prior to HotDocs 2009, you must specify this format by choosing Save Library As from the File menu and then choosing
HotDocs 2005-2008 Library from the Save as type drop-down list. (See HotDocs and XML File Formats for details.)
To create a library

1. At the HotDocs library window, click the

2. Click the

New Library button. The New Library dialog box appears.

Browse button next to the File name box. The New Library File Name dialog box appears.

3. Browse to the location where you want to save the file and enter a name in the File name box. (Click OK once you
have specified the file location.)

4. At the New Library dialog box, enter a name for the library in the Title box. This title appears as the top folder in the
library window. (Library titles can be up to 100 characters long.)

5. Optionally, type a description of the library in the Description box. The description appears in the Properties tab
when the user views the main folder in the library.
Once you create a new library, you can add templates and other files to it. See Add Templates and Other Files to a
Library.
Note:
See Change HotDocs Program File Locations for information on the default location HotDocs looks for and saves
library files.

Copyright 2010 HotDocs Ltd. All rights reserved

128

Help Topics for HotDocs Developer 10

Open a Library
Often you have templates that are located in different libraries. You can access any library by using the Open command
at the library you are currently viewing.
To open a different HotDocs library

1. Start HotDocs. (See Start HotDocs.)

2. At the library window, click the

Open Library button. The Open Library dialog box appears.

3. Locate and select the library (.HDL) file with which you want to work, then click Open. The folders, templates, and
clause libraries in the new library appear in the template list.
After opening the library, you can edit the templates, or use them to assemble documents.
Note:
See Change HotDocs Program File Locations for information on the default location HotDocs looks for and saves
library files.

Copyright 2010 HotDocs Ltd. All rights reserved

129

Help Topics for HotDocs Developer 10

Add Templates and Other Files to a Library

After you create a library, you can add files to it. This includes folders, template files, Web addresses, and so forth. You
can also add these types of files to an existing library.
When you create new templates, they are automatically added to the library. Clause libraries created at the template
library are likewise added to the library automatically.
To add an item to a library

1. At the HotDocs library window, select a folder.

2. Click the

Add button. The Add Item dialog box appears.

3. From the Type drop-down list, select the appropriate kind of library item. (Your options include Text Template,
Form Template, Interview Template, Model Document, Clause Library, Auto-Assemble File, Web Address,
and Folder.)

4. Click the

Browse button next to the File name box and locate the library item.

5. Select the item you want to add and click OK. The Add Item dialog box appears again.
6. In the Title box, enter a title for the library item (100 characters or less). The title will identify the item in the library.
7. Optionally, enter a description in the Description box. The description appears in the Properties tab when the
library item is selected.
Note:
You can add multiple files to a library simultaneously. However, doing this doesn't allow you to assign properties
(such as titles and descriptions) to each individual file. To add multiple files, select all the files you want to add in
the folder you are browsing. Once they are added, you can modify the properties. See Change the Properties of a
Single Library Item for details.
You can also add items by dragging files from a Windows Explorer folder to the library. This method allows you
to add files like PDF files, word processor documents, and so forth to the library. Once you add the file, you may
need to update the item properties (such as add a title or description). See Change the Properties of a Single
Library Item for details.
Adding an item to a library does not affect the files on your local disk or network. For example, you could select
a form template from a library on your network and add it to a library on your local disk. However, the actual file
would remain on the network.

Copyright 2010 HotDocs Ltd. All rights reserved

130

Help Topics for HotDocs Developer 10

Work with Templates and Other Files in a Libary

You use a HotDocs library to organize and maintain your template set, including adding and removing templates from the
library and changing the properties of templates in the library. (See Organize the Contents of a Library.) You can also use
commands in the library to work directly with the templates. For example, you can select a template and assemble it.
To use the library to access the templates and clause libraries

1. At the HotDocs library window, open the desired HotDocs library. (See Open a Library.)
2. Perform tasks as explained in the following table:
To

Do This

Assemble the selected

document

Select the template and click the

Create a new template or

clause library and add its
reference to the library.

Click the
New Template button. (See Create a New Text Template File or Create
a Form Template.)

Create a new folder in the

library

Choose Add Folder (Edit menu).

Edit an existing template

or clause library

Select the item and click

Library.)

Add an existing item to the

library

Click the

Add Item button. (See Add Templates and Other Files to a Library.)

Remove the selected item

from a library

Click the

Remove Item button. (See Remove Items from a Library.)

Move items up or down in

the library list

Click on the item and drag it up or down in the list. HotDocs displays a horizontal bar
indicating where the item will be placed when you release the mouse.

Modify the selected

item's file name, title, or
description

Click the

View or hide all of the

items within a folder in the
library list

Choose Expand All (View menu). (To hide the list again, choose Collapse All.)

Copyright 2010 HotDocs Ltd. All rights reserved

Assemble button.

Edit. (See Edit a Template or Customize a Clause

Properties button. (See Change the Properties of a Single Library Item.)

131

Help Topics for HotDocs Developer 10

Remove Items from a Library

Libraries do not contain the actual files that HotDocs uses, such as template files, component files, or answer files.
Libraries only contain references to those files, similar to shortcut icons on a Windows desktop. When you remove an item
from a library, you can choose to remove just the reference, or you can choose to delete the actual file from disk.
The available options for removing items in a library depend on the type of item:
When you remove the reference for a template, you can choose to also delete the associated template file,
component file, and clause library file (if any) from disk. If you do this, the files you delete are either sent to the
Windows Recycle Bin (if the template is stored on your local disk) or permanently deleted (if it's stored on a network
drive). Or, you can delete only the reference, leaving the template, component file, and clause library file in place on
the diskperhaps for use in another library.
When you remove the reference for a folder, you can choose to delete the items within the folder. If you choose to
remove the items in the folder, all of the items in that folder and in all subfolders will be removed. If you choose to
leave the files, they will be moved to the next higher folder.
To remove items from a library

1. At the HotDocs library window, select the item (or items).

2. Click the

Remove Item button. The Remove Item dialog box appears, asking if you want to remove the reference
to the file from the library.

3. Optionally, if you have selected a folder and you want to remove items within the folder, select Remove the
unselected items contained in selected folders.

4. Optionally, if you want to delete the actual files from disk, select Permanently delete the files for selected items
from the disk.

5. Click Yes.
Note:
If the template you are deleting is in the same folder as another template with the same file name but a different file
name extension (for example, you are deleting Invoice.rtf and the same folder also contains Invoice.wpt), HotDocs
doesn't delete the associated files, like the component file. You need these files for the other template.

Copyright 2010 HotDocs Ltd. All rights reserved

132

Help Topics for HotDocs Developer 10

Change the Properties of a Single Library Item

You can change the title and description of a library item. If the item is a template or clause library, you can also change
the file name and add command-line options.
Caution:
Changes made at the Item Properties dialog box affect only the reference to the itemnot the template or clause
library files themselves. For example, if you change a template's file name at the Item Properties dialog box, it
does not change the template's name on your local disk or network. Unless you also update the underlying file, the
template may no longer work because the reference is incorrect. (See Rename Templates Using Template Manager
for information about renaming templates and having all references to the file updatedincluding in the library.)
To modify a library item

1. At the HotDocs library window, select the item you want to modify.
2. Click the

Properties button. The Item Properties dialog box appears.

3. Make changes based on the following options:

To

Do This

Change the file path

In the File name box, type the new file path, or click the
specify a new path.

Change the item title

In the Title box, either type a new title in the box, or click the
use the default title. (Titles can be 100 characters long.)

Change the command-line

options

In the File name box, type the new options. (For example, Refund.wpt /
af=bwhittington.anx). See Overview: Command-Line Options.

Change the item

description

In the Description box, enter a new description. (The description appears in the
Properties tab when the library item is selected.)

Browse button and

Get Title button to

Note:
You can change the properties of several other library items at once. See Change the Properties for Multiple Items in a
Library.

Copyright 2010 HotDocs Ltd. All rights reserved

133

Help Topics for HotDocs Developer 10

Change the Properties for Multiple Items in a Library

You can change the folder paths, file name extensions, and command-line options for two or more library items in a folder.
For example, if you have used Windows Explorer to move templates from one folder to another, you can update all the file
paths in the library at once. (Remember, moving the files on disk does not automatically update the references to those
files in the library.)
If you select a folder, the changes affect all items in the folder and in any subfolders. For example, if you select the top
folder of a library, you will change the properties for every item in the library.
Caution:
Changing properties of library items does not affect the files on your local disk or network. For example, changing the
file path in the Multiple Item Properties dialog box does not actually move the file to a different folderyou must
manually move the files. (See Move Items to New Locations on Disk.)
To change the properties of two or more items in a library folder

1.

Select the items (or the folder that contains the items) and select
Properties dialog box appears.

Multiple (Edit menu). The Multiple Item

2. Make changes as specified in the following table:

To
Change the file path for
the selected items

Do This
Click the File path Browse button and browse to the new folder. Then click OK.
The new folder path is inserted. (Click the File path drop-down button to view a list of
all the various file paths used for the templates in your list.)
To specify the default folder the different files, choose <default> from the File path
drop-down list and click OK. (The default folder is the location HotDocs looks for
the file when no file path is given. You can specify what this default location is at
HotDocs Options. See Change HotDocs Program File Locations.)

Change the reference path

Click the
Reference path button and choose a path from the Select Reference
for the selected items
Path dialog box. When you click OK, HotDocs inserts the reference path keyword in
the File path box.
To remove all reference paths and specify the default folder for the different files,
choose <default> from the File path drop-down list and click OK. (The default folder
is the location HotDocs looks for the file when no file path is given. You can specify
what this default location is at HotDocs Options. See Change HotDocs Program File
Locations.)
The
Reference path button isn't available unless you have at least one reference
path defined in the File Locations folder of HotDocs Options. (See Assign Reference
Paths to HotDocs Files.)
Change the file name
extension for the selected
items

Click the File name extension drop-down button and make a selection. If the desired
extension is not listed, type it.
HotDocs displays a list of the file name extensions for all the items you have selected
in the File path drop-down list. If you have multiple file types selected, <various>
appears in the File name extension box.

Copyright 2010 HotDocs Ltd. All rights reserved

134

Help Topics for HotDocs Developer 10

To

Do This

Change the command-line

option or options for the
selected items

Type the command-line option (for example, /af=path and file name) in the
Command-line options box and click OK. If assigning multiple options, include
spaces between each option. (See Overview: Command Line Options.)
To remove existing command-line options, select <none> from the Command-line
options drop-down list and click OK.

3. Click OK at the Multiple Item Properties dialog box.

4. When HotDocs confirms the change, click Yes.

Copyright 2010 HotDocs Ltd. All rights reserved

135

Help Topics for HotDocs Developer 10

Sort Items in a Library

To help you locate or organize files in the library, you can sort the items in a folder in alphanumeric order.
To sort library items

1. At the HotDocs library window, select the folder whose items you want to sort.
2. Click the

Sort button. The Folder Sort Options dialog box appears.

3. Select the order for sorting the library items:

To organize them A to Z and 1 to 9, select Ascending, then click OK.
To organize them Z to A and 9 to 1, select Descending, then click OK.

4. Optionally, select Sort Subfolders to sort the folders inside the selected folder.
The template list changes to show the rearranged library items.
Note:
You can save templates you frequently use to a Favorites folder in the library for quicker access, select the template
and click Add to Favorites (View menu). See Create a Favorites Folder in the Template Library.

Copyright 2010 HotDocs Ltd. All rights reserved

136

Help Topics for HotDocs Developer 10

Organize the Contents of a Library

Once you create a library and add templates to it, you often want to organize the contents of the library into logical groups.
This may include grouping items by subject matter in folders, or grouping items alphabetically. Additionally, you may need
to print a list of templates in the library or remove templates you no longer need.
To organize the contents of a HotDocs library

1. At the HotDocs library window, open the desired HotDocs library. (See Open a Library.)
2. Use any of the following commands to work with files in the library:
To

Do This

Add a folder to the library

so you can group library
items

Choose Add Folder (Edit menu). The Add Item dialog box appears where you can
specify the folder name and a description. (Once you create a folder, you can move
items to it.)

Print a list of the titles, file

Click the
names, and descriptions of
templates and folders in a
library

Print Library button. (See Print a List of Items in a Library.)

Remove an item from the

library

Select the item and click

Library.)

Remove an item from the

library and places a copy
of it on the Clipboard so
you can paste it elsewhere
in the library

Select the item and click the

Cut button.

Copy an item in the library

to the Clipboard so you
can paste it elsewhere in
the library

Select the item and click the

Copy button.

Paste an item to a new

location in the library

Select the folder in the library where you want the item pasted and click the
button.

Sort items in a library in

ascending or descending
order based on their titles

Select the folder on which you want to sort, and click the
Items in a Library.)

Change an item's file

name, title, or description

Select the item and click the

View the file names for

templates in the library
(rather than the template
titles)

Choose File Names (View menu). (To view template titles again, choose Template
Titles.)

Search for a specific

template in the library list

Type the text for which you are searching in the Find box. HotDocs will show only
those files that contain the search text in the template title, file name, or description.
(See Search for a Specific Template in a Library.)

Group templates you

use most frequently in a
Favorites folder

Select the template and choose Add to Favorites (Edit menu). (See Create a
Favorites Folder in the Template Library.)

Copyright 2010 HotDocs Ltd. All rights reserved

Remove Item button. (See Remove Items from a

Paste

Sort button. (See Sort

Properties button.

137

Help Topics for HotDocs Developer 10

Create a Favorites Folder in the Template Library

You can create a Favorites folder in your template library and add templates to it. This may be useful if you find you
assemble some documents more than others and you want to access them quickly each time you view the library.
To add templates to a Favorites folder in the library

1. At the template library, select the template you want to add to the Favorites folder.
2. Click Add to Favorites (Edit menu).
If no Favorites folder exists, HotDocs creates the folder and adds the template to it.

Copyright 2010 HotDocs Ltd. All rights reserved

138

Help Topics for HotDocs Developer 10

Create a New Library By Exporting Part of an Existing Library

You can create smaller libraries by exporting some of the folders and files of a larger, existing library. Creating a library
this way eliminates the need to manually create a new library and then add each folder, template, or clause library to it.
When you export part of a library, HotDocs asks you for the file name and title of the new library. Then it creates the
library, and finally creates the library references in it. During the process, you can choose to have HotDocs copy the files
in the library you are exporting to the new location, or you can choose to have the library reference the original files.
Caution:
Exporting will only export the files you select at the library. This means that if a template you are exporting contains
references to other templates or files not listed in the library, those items will not be exported and you may receive
errors when you attempt to use the template for assembly.
To export part of an existing library

1. At the HotDocs library window, select the library items you want to export. (If you select a folder, all the items in the
folder will be exported.)

2. Choose File > Export Library To > HotDocs Library File. The Export HotDocs Library File dialog box appears.
3. At the File name box, click

Browse, select a location for the new library, and enter a library name in the File
name box. (Click OK when you are finished.)

4. At the Export HotDocs Library File dialog box, enter a name for the new library in the Title box, or accept the
suggestion HotDocs makes. This title will appear in the Properties tab of the HotDocs library window.

5. Optionally, in the Description box, type a description of the library. (The description appears in the Properties tab
when a library (or folder) is selected.)

6. Click OK. HotDocs asks if you want to export the selected files:
Click Yes to copy the selected files to the same folder as the new library.
Click No to have the new library refer to the files in their current location.
After exporting the items, the original library items are still available. (HotDocs does not delete the references from the
original librarytemplates can be referenced in multiple libraries.) If you want the old references deleted, select the library
items and click

Remove Item.

HotDocs does not automatically display the new library. To open it, click
library. (See Open a Library.)

Copyright 2010 HotDocs Ltd. All rights reserved

Open and select the file name for the new

139

Help Topics for HotDocs Developer 10

Import One Library Into Another

You can import a copy of another library into the current library. The imported library will become a folder in the current
library.
There are three types of imported libraries. Which type you choose depends on how you need to use the library and its
contents:
Assembly Only: You can use the library to assemble documents, but you can't change the librarys (or folder's)
structure or edit a template. This type of import is useful, for example, when you want to access company templates
stored on a network drive, but you don't have authorization to edit the templates or the imported library's structure.
Editing and Assembly Using Original Files: You can use the library to assemble documents and edit templates.
You can also modify the structure of the library. The imported library references the same files as the original library.
(Templates and clause libraries can be referenced in more than one library.) If you edit a template from either the
imported library or the original library, changes you make will appear in documents produced from either library. This
type of import is useful when you are maintaining company templates stored on a network.
Editing and Assembly Using Copies: You can use the library to assemble a document and edit templates. You
can also modify the structure of the library. However, this method copies the files to a new location, rather than
refers to the originals. Any changes you make to the templates are applied only to the copies and not the original
files. This is useful if you are copying a library from a removable disk or network on your local disk.
Caution:
When importing a library, HotDocs looks for the items referenced in the library in the same folder as the library itself. If
they are not saved together, importing will not work.
To import one library into another

1. At the HotDocs library window, select the folder where you want the imported library to be located.
2. Click Import Library (File menu). The Import Library dialog box appears.
3. Select the library you want to import and click Import. The Import Library dialog box appears.
4. Choose how you want to import the templates:
Click Assembly Only to assemble documents from the templatesand nothing else.
Click Editing and Assembly to edit the templates and assemble documents from them.

5. If you select Editing and Assembly, HotDocs displays another dialog box, prompting you to choose whether to
copy the associated files or use the originals:
Click Yes to import copies of the files to a new location you specify. Changes you make to the templates will
affect files in the new location only. The Browse for Folder dialog box appears, prompting you to specify
where the copied files should be placed.
Click No to have the library reference the original files. Changes you make to the templates will affect everyone
using those files to assemble documents.

Copyright 2010 HotDocs Ltd. All rights reserved

140

Help Topics for HotDocs Developer 10

Print a List of Items in a Library

You can print a list of the files and folders in the library currently displayed in the HotDocs library window, allowing you to
see the library structure, as well as the file path and the description of each item.
To print a HotDocs library

1. At the HotDocs library window, open the library whose contents you want to print. (See Open a Library.)
2. Click the

Print Library button. The Print dialog box appears.

3. Click OK. The list of titles, file names, and descriptions are printed at the selected printer.
Note:
To preview what the printout will look like before you print it, select
library window, click Close.

Copyright 2010 HotDocs Ltd. All rights reserved

Print Preview (File menu). To return to the

141

Help Topics for HotDocs Developer 10

Save a Library
HotDocs saves all changes you make to a library immediately after you make the change. Clicking Save (File menu)
simply displays a message confirming this.

Copyright 2010 HotDocs Ltd. All rights reserved

142

Help Topics for HotDocs Developer 10

Save the Contents of a Library as a Text File

You can save the contents of a HotDocs libraryincluding folder names, template file names, titles, and descriptionsas
a text file. The hierarchy of the library is preserved within the text file. This is useful if you want to spell check the text used
in your library. (To do this, you must open the text file in a word processor with spell-checking capabilities).
To save the library as a text file

1. At the HotDocs library, select Export Library To > Plain Text File (File menu). The Save As dialog box appears.
2. Select a location to save the text file to, enter a name for the file, then click Save. A .TXT file containing a tabbed list
of the folder names and template titles is saved to the location you choose.

Copyright 2010 HotDocs Ltd. All rights reserved

143

Help Topics for HotDocs Developer 10

Move Items Within a Library

To organize your library, you can move an item to a different location in the same library by dragging, by cutting and
pasting, or by copying and pasting.
Caution:
These methods do not move the actual file to a different location on your local disk or network. See Move Items to New
Locations on Disk for information on doing this.
To drag library items to a new location
At the HotDocs library window, select the library item and drag it to the new location using the mouse. (As you drag,
HotDocs uses a horizontal bar to indicate where the item will be placed when you release the mouse button.)
To cut and paste several library items

1. At the HotDocs library window, select the items you want to move.
2. Click the

Cut button (or press Ctrl+X.)

3. Select the new location and click the

Paste button (or press Ctrl+V).

To copy and paste several library items within the library

1. At the HotDocs library window, select the items you want to copy.
2. Click the

Copy button (or press Ctrl+C).

3. Select the new location and click the

Copyright 2010 HotDocs Ltd. All rights reserved

Paste button (or press Ctrl+V).

144

Help Topics for HotDocs Developer 10

Move Items to New Locations on Disk

Using the Move command (Template menu) at the HotDocs library window, you can move template and clause library
files to new locations on your local disk or network. Using this command also updates the library reference to the file.
(Moving files in other ways, for example, by using Windows Explorer, requires that you manually update the library
reference. See Change the Properties of a Single Library Item or Change the Properties for Multiple Items in a Library.)
To move template and clause library files

1. At the HotDocs library window, select the templates and clause libraries you want to move.
2. Select

Move (Template menu). The Browse for Folder dialog box appears.

3. Select the folder where you want to move the files.

4. Click OK. HotDocs automatically removes all associated files (component files, default answer files, and so forth)
from the old location, pastes them at the new location, and then updates the references to the files in the HotDocs
library.
HotDocs handles the Move command a little differently if you are moving the template from a folder that contains another
template with the same file name but different file name extension (for example, if you are moving Invoice.rtf from a folder
that also has Invoice.wpt). In such a case, HotDocs copies the associated component file to the new folder, but does not
delete it from the original folder because it is still needed by the other template.
Note:
You can also copy templates to new locations on disk and have the library reference updated. See Copy Templates to
New Locations for details.

Copyright 2010 HotDocs Ltd. All rights reserved

145

Help Topics for HotDocs Developer 10

Copy Templates to New Locations

Often you need to make a copy of a template and save it to a new location on disk. You can use the Copy command at
the template library to do this. As you are copying, you can choose to make the template and component file read-only.
You can also choose to update the reference to the file in the library so the library refers to the copied template rather
than the original.
To copy the template to a different location

1. At the HotDocs library window, select the templates and clause libraries you want to copy. (Press Ctrl or Shift to
select multiple items.)

2. Choose Copy (Template menu). The Folder for Copied Templates dialog box appears.
3. Browse to the folder where you want to copy the template or templates and click OK. The Copy Templates dialog
box appears, asking you to set some properties for the copied templates:
Select Mark newly created templates as read-only to keep users from editing the template. (This assigns the
read-only property to both the template and the component file.)
Select Update library entries to refer to the newly created templates to have HotDocs change the file path for
the library item so that it uses the file path for the copied template.

Copyright 2010 HotDocs Ltd. All rights reserved

146

Help Topics for HotDocs Developer 10

SECTION 5:
AUTOMATING TEXT TEMPLATES

Copyright 2010 HotDocs Ltd. All rights reserved

147

Help Topics for HotDocs Developer 10

Chapter 8: Creating and Working with Template Files

Overview: Template and Component Files
The Template File
The first step in automating a new HotDocs template is to create a template file. You can create three types of template
files: text templates, form templates, and interview templates.
A text template is created and automated in Microsoft Word or WordPerfect. You can modify the underlying text of a
text template both as you automate the template and as you view the assembled document in the word processor.
(See Create a New Text Template File.)
HotDocs assembles all Word templates using an RTF-based assembly process. This means that if your template
is in DOT format, HotDocs must open it, convert it to RTF, and then assemble it. By developing the templates in
RTF, you can reduce the number of steps in this process, thus decreasing the amount of time it takes to assemble a
document. In larger, more complex templates, this difference in speed will be quite noticeable.
A form template uses a Windows program (such as a draw program) to create a static form, or one in which the
user will not be able to change or modify the underlying text. Once designed, you then use HotDocs to create a PDF
version of the form. Finally, you use HotDocs Automator to place fill-in fields on the form where users' answers will
be inserted. (See Create a Form Template.)
An interview template gathers common information (such as court, attorney, or client information) and saves the
answers for use in assembling other documents. Unlike text and form templates, users cannot generate documents
from an assembled interview templatethey can only generate an answer file. (The interview template is really a
component file that contains ASK instructions. See Create an Interview Template.)

The Component File

When you create a new template file, HotDocs automatically creates a companion file called the component file. The
component file contains information about variables and other components used in the template. Both the template file
and the component file are necessary for a template to work. Whenever you copy a HotDocs templatefor example, to
share a template with another useryou must be sure to copy both the template file and the component file.
HotDocs gives the component file the same name as the template file, except that the file name extension for the
component file is .CMP. For example, if the template file name is Insure.rtf (for a Word template), the component file
name will be Insure.cmp.
The following example shows a fully automated text template with its component file.

Copyright 2010 HotDocs Ltd. All rights reserved

148

Help Topics for HotDocs Developer 10

The component file works automatically in the backgroundas you create various components in the template, they are
automatically stored in the component file. Normally each template uses its own component file, but you can make two or
more templates share one component file.
You work with components in the component file using Component Manager. For example, you can copy variables or
other components from one component file to another, create variables, and drag variables from Component Manager
directly into the template. You can also edit, print, search, and spell check components within your component file. Finally,
if you need to edit components in several component files at once, you can use Template Manager.

Copyright 2010 HotDocs Ltd. All rights reserved

149

Help Topics for HotDocs Developer 10

HotDocs Editing and Navigation Toolbar Buttons

When you create a text template, HotDocs adds an editing toolbar as well as a navigation toolbar to the word processor
window. This toolbar lets you perform basic HotDocs tasks, such as inserting variables, opening Component Manager,
test assembling the template, or matching REPEAT and IF instructions with their END instructions.
Since HotDocs works inside your word processor, you use word processor commands for many basic tasks, such as
typing text in the template, assigning font attributes and page formatting, and printing. Tasks that are specific to HotDocs
are performed by using the HotDocs buttons. The following is a list of these buttons, followed by a description of what
each button does:
Note:
To access these buttons in Word 2007 and later, click the HotDocs tab on the Word ribbon.
Button Name

Description

HotDocs

Either starts HotDocs and opens the HotDocs library window, or brings it to the front if
it is already open. (This button is always in the word processor toolbar, regardless of
whether HotDocs is running.)

Variable Field

Opens the Variable Field dialog box where you can select the type of variable field you
want to create and insert. If the cursor is in a variable reference, HotDocs opens the
Variable Field dialog box with that information already appearing.
Note:
If you're using Word 2000 or higher, you can double-click in a variable field and the
Variable Editor will appear.

IF Field

Opens the IF Field dialog box where you can create a true/false test for conditional text.
If you need a more complex test, click IF Expression at the IF Field dialog box.

ASK Field

Opens the ASK Field dialog box where you can create and insert an ASK instruction in
the template. An ASK instruction causes either a dialog or a database to be asked at a
specific place in the template.

INSERT Field

Opens the INSERT Field dialog box where you can choose to insert a clause, clause
library, or template. You can also convert a selected section of template text into an
inserted template or clause component.

REPEAT Field

Opens the REPEAT Field dialog box where you can specify a dialog to gather
information for a list. At this dialog box, you can also specify a sort order, filter, and
format for merging the list of answers into the document. You can also REPEAT a
database component.

SPAN Field

Opens the SPAN Field dialog box where you can enter a name for the Span component
you are creating. SPAN fields represent the section of text you want to allow the user to
edit while viewing the Document Preview tab. (Giving users access to the assembled
document from the assembly window lets users save document text changes to an
answer file so they can reassemble the document later and still maintain those changes.)

Edit Component

Opens the Component Editor where you can modify the properties of an existing
component. (If your cursor is outside a component field, HotDocs will allow you to create
a new component. However, if you create a new component, it will only be saved to the
component fileit will not be inserted into the template.)

Assemble

Test assembles the document or a selected portion of the document.

Copyright 2010 HotDocs Ltd. All rights reserved

150

Help Topics for HotDocs Developer 10

Component Manager

Opens the Component Manager window where you can create, edit, delete, rename, and
copy components.

Clause Library

Opens a clause library where you can create new clauses or add existing clauses.

Save Template and

Component File

Saves the template and component file you are currently editing.

Save and Close Template

Saves and closes the template and component file you are currently editing.

HotDocs Help

Displays the HotDocs Help viewer, which contains information on automating templates
and assembling documents.

Apply Colors

Assigns custom colors to the different field types in the template. This can help you
more quickly identify sections or parts of your template as you are automating. (You can
choose the colors at HotDocs Options.)

Label Fields

Opens the Label Fields dialog box where you can choose to label matching IF and END
IF instructions, REPEAT and END REPEAT instructions, and SPAN and END SPAN
instructions. Additionally, where you've nested these instructions, you can identify the
level of nesting. Finally, you can assign the word processor's hidden text property to
these comments and labels so that you can show and hide them during automation.

Match Fields

Moves your cursor between opening IF, REPEAT, and SPAN instructions and closing
END IF, END REPEAT, and END SPAN instructions. This can help you troubleshoot
problems where one of the instructions is accidentally moved or deleted.

Go to Field

Moves you cursor to a specific variable or instruction field in the template. This can
be useful when you receive errors and need to quickly locate the field in the template
containing the error.

Previous Field / Next Field

Allows you to navigate through the template, field by field. This may be useful if you have
several pages in a template without any variable fieldsnavigating by fields allows you to
skip these pages, rather than scrolling through them until you find the next field.

/
Markup View / Developer
View
/
HotDocs Outliner

Switches the look of the template between Markup View and Developer View. Markup
View provides a simpler view of the template (which can then be saved and shared with
a non-HotDocs user who needs to review the content of the template, for example).
Developer View is the mode in which you automate the template.
Opens the HotDocs Outliner so you can review an outline of scripting (and variables)
used in the template.

Copyright 2010 HotDocs Ltd. All rights reserved

151

Help Topics for HotDocs Developer 10

Note:
You should always use the HotDocs
Save and
Save and Close buttons to save and close a template rather
than the word processor's buttons. The HotDocs buttons ensure the template and component files are properly saved
and closed.

Copyright 2010 HotDocs Ltd. All rights reserved

152

Help Topics for HotDocs Developer 10

Create a New Text Template File

A text template is a word processor file that contains text as well as HotDocs components, such as variables, dialogs,
instructions, scripts, and formats. The first step in automating a HotDocs text template is to create a new template file that
contains your document text.
Caution:
Do not create your templates in the tutorial library that installs with HotDocs. If you ever reinstall HotDocs, the library
will be overwritten and you will have to add your templates to the library again. Instead, create a new library for your
templates. (See Create a Library.)
To create a new text template

1. At the HotDocs template library, click the folder in which you want the template.
2. Click

New Template. The New Template dialog box appears.

3. Select the type of text template you want to create from the Type drop-down list. Depending on which word
processor(s) you have installed, your options include Word RTF Template (.rtf), Word Document Template (.dot),
and WordPerfect Template (.wpt).

4. Type a file name in the File name box. HotDocs automatically adds the correct extension to the file name based on
the type you have selected. (To save the template in a location other than the default Templates folder, include the
folder path with the file name in the File name box. You can check the default Templates location at the HotDocs
Options dialog box. See Change Word Processor File Locations.)

5. Type a title for the template in the Title box (or accept the suggestion HotDocs makes). The title is what identifies
the file in the library.

6. Optionally, enter a description in the Description box. Descriptions appear in the Properties tab of the library when
the template is selected.

7. Select the contents for the new template:

To create an empty template file, select Empty. (You can type or copy and paste text into your template later.)
To copy the contents of the currently open word processor file into the new template, select Current open
word processor document.
To copy the contents of some other file (for example, a word processor document or another HotDocs
template) into the new template, click the

Browse button next to Other file box and locate the file.

8. Click OK at the New Template dialog box. HotDocs opens your selected word processor and displays the template.
You can use the HotDocs editing toolbar to begin automating the template. (See HotDocs Editing and Navigation
Toolbar Buttons.)
Note:
If you are using Microsoft Word to develop your templates, it is recommended that you create RTF (Rich Text
Format) templates. RTF templates assemble much faster than .DOT templates. (See Overview: Template and
Component Files for more details.)
When you create a new, empty Word template, HotDocs applies whatever styles are in HotDocs.dot to the new
template. When you create a new template based on another template or document, HotDocs applies the styles
used in that template or document to the new template.
You can include command-line options (in the File name box) that allow you to specialize the assembly process
for a given template. See Overview: Command-Line Options.
If you have multiple word processors installed, you can have HotDocs always suggest a specific template type
when you create a new template. See Change Your Default Word Processor.
If you need to use your template with earlier versions of HotDocs, you must specify which version at Component
File Properties. See Change Component File Properties for details.

Copyright 2010 HotDocs Ltd. All rights reserved

153

Help Topics for HotDocs Developer 10

Create a Text Template Based on an Existing Template

You can create a new text template based on the contents of a text template already in the library. When you create a
new template based on another template or document, HotDocs applies the styles in that file to the new template. It also
copies the template text (including components) into the new template (and component) file.
Caution:
Do not create your templates in the tutorial library that installs with HotDocs. If you ever reinstall HotDocs, the library
will be overwritten and you will have to add your templates to the library again. Instead, create a new library for your
templates. (See Create a Library.)
To create a new template based on an existing one

1. At the HotDocs library, select the existing template from the template list.
2. Click

New Template. The New Template dialog box appears.

3. Change the file name and title for the new template (at the File name and Title boxes).
4. Do not change the existing templates file path and name in the Other file box.
5. Click OK. HotDocs opens a new template file and copies the text and variables from the Other file into it. It also
creates a new component file and copies the existing components into it.
Note:
Another way to create a new template based on an existing template is to use the Copy Templates command. (See
Copy Templates to New Locations.) Once you have copied the template and component file, simply rename the files
using Template Manager. See Rename Templates Using Template Manager.

Copyright 2010 HotDocs Ltd. All rights reserved

154

Help Topics for HotDocs Developer 10

Convert a Single Template to a New File Format

Note:
To convert multiple files at once or to convert all templates to RTF, use Template Manager. (See Convert Multiple
Templates to Work with HotDocs 10 and Convert Templates and Clauses to Microsoft RTF.)
HotDocs 10 uses a file format for component files that is different from earlier versions of HotDocs. To take full advantage
of the features available in this latest version of HotDocs, you must convert your component file to the current format.
However, if users of your templates are still using previous versions of HotDocs, you can keep the files in their existing
formats.
Additionally, perhaps you've changed word processors and need to convert all your templates from one file type to
another.
Caution:
It is a good idea to back up templates, component files, or other HotDocs files before making major changes to them.
To convert an older HotDocs template to the latest version of HotDocs

1. At the template library, select the template you want to convert and click

Edit Template. HotDocs displays a

message box asking how you would like to convert the template.

2. Make your choice, based on the following options:

Click Convert to Current Format to convert the template to HotDocs 2009-10 format. If you select this option,
the format shown at Component File Properties will continue to be set to Current.
Click Keep Existing Format to leave the component file in the format it is already in. If you select this option,
HotDocs will set that specific format for the component file at Component File Properties.
Click Cancel to close the message box and cancel the conversion process.
Note:
If you need to keep several templates in their existing pre-2009 format and you don't want to be prompted to make this
selection on a template-by-template basis, you can use Template Manager to change the component file format for
several files at once. See Modify Component File Properties Across Multiple Files for details.
If you are converting a HotDocs 5 template, you should verify the template works correctly in HotDocs. For details about
this, see Verify HotDocs 5 Templates for Use with HotDocs 10.
To convert a template to a new word processor format

1. Select the template at the HotDocs library and click

New Template. The New Template dialog box appears.

2. Click the Type drop-down button and select the new word processor. The file name extension in the File name box
is changed to the new word processor format.

3. Optionally, change the Title and Description of the template.

4. Do not change the information in the Other file box.
5. Click OK. HotDocs converts the template to the new format and displays it in the appropriate word processor.
The quality of the template conversion depends on your word processors conversion capabilities. Complex text
formatting, unusual fonts, and so forth, may not be converted correctly. You should check new versions of templates
for conversion errors.
Once you have updated your template, the old template may still be listed in the library. This happens when old and new
versions of the template have different file name extensions. Delete the old version from the library. (See Remove Items
from a Library.)
Note:
You can designate that component files always be compatible with a specific version of HotDocs (starting with
HotDocs 6). See Change Component File Properties for details. When doing this, however, you must be careful not
Copyright 2010 HotDocs Ltd. All rights reserved

155

Help Topics for HotDocs Developer 10

to use features in the template that are not backwards compatible. For example, if you are using HotDocs 10 to edit a
template that you want to be compatible with HotDocs 2005, you should not use any features that were introduced in
HotDocs 2006, HotDocs 2007, HotDocs 2008, HotDocs 2009, or HotDocs 10 because they may not work with HotDocs
2005.

Copyright 2010 HotDocs Ltd. All rights reserved

156

Help Topics for HotDocs Developer 10

Edit a Template
Once you have automated a text or form template, you may need to make changes to your work. You can edit variables,
dialogs, instructions, and other features.
To edit a template

1. At the HotDocs library, select the template and click

Edit. The template opens and the HotDocs Edit toolbar

appears.

2. Once the template is open, you can edit variables, custom dialogs, REPEAT instructions, INSERT instructions, and
IF instructions.

3. When you finish, click the

Close Template button to save your work and close the template.

Copyright 2010 HotDocs Ltd. All rights reserved

157

Help Topics for HotDocs Developer 10

Assign Colors to Fields and Instructions in Templates

Note:
Click here if you are using WordPerfect and the HotDocs Navigation toolbar doesn't appear in your template.
You can assign custom colors to the different types of fields in a template. This can help you more quickly identify
sections or parts of your template as you are automating. Additionally, you can assign colors to IF, REPEAT, and SPAN
instructions in your templates. Assigning different combinations of these colors can help you differentiate levels of nesting
as well as help you better view individual pairs of instructions.
By default, HotDocs assigns its own colors; however, you can customize the colors at the HotDocs Options dialog box.
(See Define Field Colors.)
To apply custom colors to template fields and instructions

1. Open the template for editing. (See Edit a Template.)

2. Click the

Apply Colors button. The Apply Colors dialog box appears.

3. Select one of the following options:

Choose None to make all variable and instruction fields black.
Choose Regular to mark all variable and instruction fields using a custom color specific to that field type. For
example, all variables will be marked with one color, all IF instructions will be marked with a different color, all
REPEAT instructions will use a different color, and so forth.
Choose Nested to mark each level of IF and REPEAT instructions using a custom color. (For example, all firstlevel IF instructions will use a specific color, while all second-level instructions will use a different color, and so
on.)
Choose Sequential to mark each IF and REPEAT instruction field using a custom color. (For example, the
first instruction in a template will be marked using one color, while the next instruction will be marked using a
different color, and so on.)
Note:
If you change your default colors, or if you receive templates from other developers whose colors are different
from yours, you can click the

Apply Colors button to update existing templates with your custom colors.

If you're using Microsoft Word, you can also apply colors by clicking on the HotDocs drop-down menu in the
HotDocs toolbar and choosing Apply Colors. (To access this menu button in Word 2007 and later, click the
HotDocs drop-down button.)

Copyright 2010 HotDocs Ltd. All rights reserved

158

Help Topics for HotDocs Developer 10

Move Between Fields in a Template

Note:
Click here if you are using WordPerfect and the HotDocs Navigation toolbar doesn't appear in your template.
You can navigate through the template, field by field, using the Next Field and Previous Field buttons in the
HotDocs Navigation toolbar. This may be useful if you have several pages in a template without any variable fields
navigating by fields allows you to skip these pages, rather than scrolling through them until you find the next field.
To move between fields in the template

1. Open the template for editing. (See Edit a Template.)

2. Place your cursor somewhere in the template and click either the

Next Field or Previous Field button. HotDocs

moves your cursor to the next or previous field in the template and highlights it. (If you're using Word 2000 or later,
you can quickly edit the variable field by double-clicking in the field.)

Note:
If you're using Microsoft Word, you can also move between fields by clicking on the HotDocs drop-down menu in the
HotDocs toolbar and choosing Next Field or Previous Field.

Copyright 2010 HotDocs Ltd. All rights reserved

159

Help Topics for HotDocs Developer 10

Use Labels to Identify Instructions

Note:
Click here if you are using WordPerfect and the HotDocs Navigation toolbar doesn't appear in your template.
You can assign labels to IF, REPEAT, and SPAN instructions to help you identify pairs or groups of instructions in a text
template. When you label fields, you can choose to merge just a numeric name in a field or you can choose to merge
a name as well as the level of nesting. This can help you match opening instructions with closing, as well as help you
determine the level of nesting within an instruction.
Field labels are merged as comments in the field.
The following example shows a series of nested REPEAT instructions that have been labeled. The first instruction,
REPEAT Editor Information, is labeled with the number 1, since it's the first REPEAT in the template. This same
instruction is also assigned the level number of L1, since it's the first level of the REPEAT instruction. The END REPEAT
is likewise labeled so that you can easily match them when examining the contents of the template.
For each subsequent instruction, HotDocs increments the field number. Additionally, if the next REPEAT instruction is
nested (which, in this example, it is), HotDocs increments the nesting level number. Each END REPEAT instruction is
likewise labeled.
REPEAT Editor Information // [1:L1]
Editor: Editor First Name Editor Last Name
REPEAT Author Information // [2:L2]
Author: Author First Name Author Last Name
REPEAT Book Information // [3:L3]
Title Edited / Date Completed: Book Title / Date Completed:03 JUN 90
END REPEAT // [3:L3]
END REPEAT // [2:L2]
END REPEAT // [1:L1]
When assigning labels to fields, you can choose whether to include both the field number and the nesting level. You can
also choose to merge just one or the other.
Finally, you can have HotDocs assign the hidden text property to these labels (as well as any other comments you've
assigned to fields in the template.) When this property is assigned, comments and labels will be hidden and shown,
depending on whether you are viewing hidden text in the template. (For information on viewing hidden text, see your word
processor's documentation.)
To label instructions

1. At the text template, click the

Label Fields button. The Label Fields dialog box appears.

2. Select an option, based on the following information:

To assign a numeric name to each instruction, select Label IF, REPEAT, and SPAN instructions.
To have HotDocs identify the level of nesting for each instruction, select Identify level of nested IF, REPEAT,
and SPAN instructions.
To apply the hidden text property to comments and labels, select Place comments (including field labels)
in hidden text. Once applied, you can quickly show and hide your comments and labels by choosing the
appropriate command at the word processor.

3. Click OK. HotDocs applies the labels you have selected to any instructions in the template.
Note:
SPAN fields are supported in Microsoft Word only.
To clear labels from fields or show comments once again, click the
options, and click OK.
Copyright 2010 HotDocs Ltd. All rights reserved

Label Fields button, clear all of the

160

Help Topics for HotDocs Developer 10

If you're using Microsoft Word, you can also label fields by clicking on the HotDocs drop-down menu in the
HotDocs toolbar and choosing Label Fields.

Copyright 2010 HotDocs Ltd. All rights reserved

161

Help Topics for HotDocs Developer 10

Go to a Specific Field in the Template

As you test assemble your templates, you may occasionally receive HotDocs error messages that instruct you to correct
a problem in a specific field in the template. If you know the field number, you can have HotDocs move your cursor to the
specific field in question.
To move your cursor to a specific variable field

1. At the template, click the

Go to Field button. The Go To Field dialog box appears.

2. Enter a number in the Field number box.

3. Click OK. Your cursor is taken to that field.

Copyright 2010 HotDocs Ltd. All rights reserved

162

Help Topics for HotDocs Developer 10

View the Template in Markup View

Note:
Markup View is supported in Microsoft Word templates only.
As you automate a Microsoft Word template and create within it variable and instruction fields, the template can be
complicated to read and understand, especially to someone unfamiliar with automation. At times, however, you may
need for a subject matter expert to review the text of the template for accuracy or to make changes or edits. To make the
template easier for a non-HotDocs user to review, you can change the formatting of the template to Markup View and then
provide the reviewer a copy of it.
When displaying markup, HotDocs replaces variables and instructions in the template with markup fields, which include
markers (such as brackets) and a name. How the resulting markup field looks depends on the type of field it is:
Variables: By default, variables are marked using brackets. If a comment is assigned to a variable, it will be used as
the field name. If no comment is assigned, HotDocs will use either the variable's title or name.
IF, REPEAT and SPAN instruction blocks: By default, IF, REPEAT, and SPAN instruction blocks are marked
using brackets. If a comment is assigned to these text blocks, the comment can be merged in the field label. If no
comment is assigned, HotDocs will simply merge the field markers around the text block. The instruction text can
appear as an annotated footnote or endnote (depending on your preferences). (By default, SPAN instructions are
not included in the Markup View. You can select an option to display them, however.)
INSERT instructions: HotDocs will merge the file name of the template you are inserting.
All other instructions (such as ASK, LANGUAGE, etc.) will be hidden when the template is changed to Markup View.
Once you finish automating a template and switch to Markup View, you can save the template as a document file and
provide a copy of it to the reviewer. Please note, however, that when you (or the reviewer) are viewing a marked up
template (in HotDocs), you cannot edit existing variable fields or instructionsyou must switch back to Developer View to
edit those fields.
To view a template in Markup View

1. Define the Markup View options you want to use in the template. (See Specify How Documents Should Be Marked
Up.)

2. Edit the template you want to mark up. (See Edit a Template.)
3. Click the

Markup View button. The template changes to show the marked up template.

Note:
To view a developer version of the template again, click the

Developer View button.

You can also view a marked up version of your assembled document. See View an Assembled Document in
Markup View for details.
Sometimes as you automate a template, you create Computation variables that perform some function, rather
than merge values. To keep these types of Computation variables from appearing in a marked up document,
enter NONE as the variable's title.

Copyright 2010 HotDocs Ltd. All rights reserved

163

Help Topics for HotDocs Developer 10

View an Outline of Scripting in the Template

Note:
The HotDocs Outliner is supported in Microsoft Word 2000 and later only.
Using the HotDocs Outliner, you can generate an outline of scripting in the template. This outline can include just a list of
instructions used in the template, or it can include variables as well. Items in the outline appear in the same order as they
are used in the template. Viewing this outline may help you better understand the logic used in the template.
You can expand the outline to view all nested instructions in the template. You can also click on entries in the outline and
view where that particular variable or instruction is merged in the template (and vice-versa). You can also view a single
variable or instruction and see just the conditions or instructions surrounding that particular instance.
To view a scripting outline

1. Edit a Word text template. (See Edit a Template.)

2. In the HotDocs Edit toolbar, click the

HotDocs Outliner button. The HotDocs Outliner window appears.

3. Perform any tasks, as described in the following table:

To

Do This

Arrange the Outliner with

Adjust the Outliner to the width you want and click the
the Microsoft Word window
View all instructions in the
templateincluding all
nested instructions

Click the

Arrange Windows button.

Expand All button. The outline expands to show all levels of instructions.

To collapse the interview outline, click the

Collapse All button.

Update the Outliner after

making changes in the
template

Click the
Refresh Outline button. The outline updates and displays any changes
you've made to the template text.

View the template's cursor

location in the outline

Click the
Synch Template button. Now, when you click in the template, entries in
the outline are highlighted to show where in the outline your cursor position is.

View variables used in the

template

Click the
Show Variables button. The outline expands to include all variables
merged in the template.
Viewing variables allows you to see relationships between variables and any
surrounding instructions.

Apply color coding to

instructions in the outline

Click the
Apply Colors button. The Apply Colors dialog box appears, where you
can choose the color scheme you want to use in the outline:
Choose None to make all variable and instruction entries black.
Choose Regular to mark all variable and instruction entries using a custom
color specific to that field type. For example, all variables will be marked with
one color, all IF instructions will be marked with a different color, all REPEAT
instructions will use a different color, and so forth.
Choose Nested to mark all instructions using a custom color. Where pairs of
REPEAT, IF, or SPAN instructions are nested, each level of nesting will be
marked with its own color.
Choose Sequential to mark all instructions using a custom color. Each pair
of REPEAT, IF, and SPAN instructions in the template will be marked by a
different color.

Copyright 2010 HotDocs Ltd. All rights reserved

164

Help Topics for HotDocs Developer 10

To

Do This

Copy the contents of

the script outline to the
Windows Clipboard so you
can paste it into another
application

Click the
Copy to Clipboard button. The entire outline is copied. Open another
application and then paste the script using that application's Paste command.

View all conditions or other Select Limit to and then click the drop-down button to select the variable you want
instructions surrounding
to view. The outline changes to show any REPEAT or IF instructions that affect that
the inclusion of a specific
particular variable.
variable in the outline
View the conditions
or other instructions
surrounding the cursor
position in the template

Select Limit to and then choose <cursor position> from the drop-down list. Click in
the template where you want to view these instructions or conditions.

Edit or test an instruction

or variable in the outline

Right-click on the instruction or variable in the outline and choose Edit or Test.

Have HotDocs show you

where in the template
a REPEAT, IF, or
SPAN instruction's END
instruction is inserted

Right-click on the instruction in the outline and choose Find Matching END. In the
template, the instruction is highlighted.

Copyright 2010 HotDocs Ltd. All rights reserved

165

Help Topics for HotDocs Developer 10

Create a Foreign Language Template

You can automate templates in languages other than English. There are requirements for doing so, however. Specifically,
you must create a LANGUAGE instruction in the template that, in turn, calls a special runtime DLL that lets you format
dates and numbers in the template so they appear correctly in the assembled document.
Note:
Contact a HotDocs sales representative for information about obtaining these free DLLs. Once you have the DLL, it
must be saved to the HotDocs program folder.
When formatting date and number variables in your template, you must manually enter example formats in the language
you have chosen for your template. If you attempt to use English-language formats, your date and number variables will
not be processed correctly.
Caution:
HotDocs supports formatting dates and numbers only in the languages listed below. If you are automating templates
in a languages other than these and need specially formatted dates or numbers, you must use Text variables to
represent these variables.
To create a template using a foreign language instruction

1. Create your template, using document text in the language you have chosen.
2. Create variables and dialogs, using variable names and prompts in the language you have chosen.
3. When inserting Date and Number variables, type the example formatin the foreign languagein the Format box.
For example, if you have a French Date variable, you would type 3 Juin 2000. (Where you assign this formateither
at the Date Variable Editor or at the Variable Field dialog boxdepends on your project. See Format the Variable for
ideas.)

4. Position the cursor in the template where you want the LANGUAGE instruction to take effect.
5. If you are using Microsoft Word, click the HotDocs drop-down menu in the HotDocs toolbar and choose Other Field
from the list of options. The Other Field dialog box appears. (WordPerfect users, see step 10.)

6. Click the Field type drop-down button and choose LANGUAGE.

7. Click the Language drop-down button and choose the language you are using for the template. Your options
include:
Language

Code

English

ENG

German

DEU

Swiss German

DES

Austrian German

DEA

French

FRA

Dutch

NLD

Spanish

ESN

Italian

ITA

8. Optionally, enter the punctuation character you want to use for the Thousands separator and the Decimal
separator in the appropriate boxes.

9. Click OK. The instruction is merged in the template.

Copyright 2010 HotDocs Ltd. All rights reserved

166

Help Topics for HotDocs Developer 10

10. If you are using WordPerfect, copy and paste an existing variable and then replace the text between the chevrons (
) with the language instruction. For example: LANGUAGE FRA.
Once the instruction is in the template and the document is assembled, all Date and Number variables after the
LANGUAGE instruction are processed in that specific language.
Note:
Only the Spanish language DLL recognizes the gender-specific use of the word one. Options for that language
include uno, una, and un.
The LANGUAGE instruction only affects date and number formats. You can use the default formats for the other
types of variables or create your own. For example, if you want to use a Spanish True/False variable format, type
S/No in the Format box.

Copyright 2010 HotDocs Ltd. All rights reserved

167

Help Topics for HotDocs Developer 10

Tips on Using Graphics in Word Templates

When automating templates, you often need to include graphics in the template. These graphics can represent company
logos, illustrations, signatures, and so forth.
As you work with these files in the template, you may notice that their inclusion adversely affects template size and
performance. A template without any graphics can easily jump in size from, say, 100K to 4 MB when you add a graphic
file. This may happen because the size of the original graphic file is large even before you insert it, or it may happen
because Word is copying the graphic and inserting it again as a metafile object. Additionally, sometimes graphics you
insert in a header/footer may inadvertently be left in the header/footer, even if you think you have removed them.
Note:
Word stores any graphics in a .DOC file in a compressed format that is close to the size of the original imported image.
The RTF format, however, is a character-based document format, so graphic images must be converted to character
strings. When images are large, have high resolution, or are of certain difficult-to-represent formats (particularly
bitmaps), they become very large in RTF files.
Proper use of graphics in templates can minimize and even eliminate many of these problems. The following sections
describe some steps you can take to improve your experience.

Minimize the File Size of the Graphic Outside of Word

When adding graphics to your template, you should do all you can to minimize the size of the file before you insert it into
the document. The following tips should help:
Save the file in one of the following compressed formats: JPG, PNG, or GIF. Which format you choose depends on
the type of graphic you are inserting. For example, if you are inserting a picture, you should use JPG. For simpler
images, like illustrations or icons, you can use GIF. Do not insert uncompressed files such as Bitmaps (.BMP) in the
template.
Save graphic files in the lowest acceptable resolution. Resolution for an image printed on a laser printer should
display well at 120 dpi (or dots per inch), but some may wish to go as high as 150 dpi.
Crop and/or resize the file using a graphics-editing application. Even though Word includes tools for cropping or
resizing the graphic directly in the document, these tools do not reduce the actual size of the file that is embedded in
the template.

Keep Word from Storing Metafile Versions of Your Graphics

According to a Microsoft Knowledge Base article, "if an EMF, a PNG, a GIF, or a JPEG graphic is inserted into a Word
[RTF] document, when the document is saved, two copies of the graphic are saved in the document. Graphics are saved
in the applicable EMF, PNG, GIF, or JPEG format and are also converted to WMF (Windows Metafile) format." Graphics
stored in an RTF file in Windows Metafile format can be extremely large.
To resolve the problem, you can specify a Windows registry setting that keeps Word from saving two copies of the image.
Caution:
You must be extremely careful when working in the Windows registry. Failure to follow the instructions below exactly
could result in your making changes that negatively affect all of the programs on your computer. You may want to ask
your system administrator for help if you are unsure of what you are doing.
To keep Word from saving two copies of graphics in your templates

1. Close Word (if it's running.)

2. Click Start > Run. The Run dialog box appears.
3. In the Open box, type regedit and click OK. The Registry Editor opens.
Copyright 2010 HotDocs Ltd. All rights reserved

168

Help Topics for HotDocs Developer 10

4. Navigate to HKEY_CURRENT_USER > Software > Microsoft > Office > Version > Word > Options. (Replace
Version with the version of Word you are using.)

5. In the right pane of the window, right-click and choose New > String Value from the shortcut menu. A new string is
created called New Value #1.

6. Rename the value to ExportPictureWithMetafile. (To do this, you can choose Rename from the shortcut menu.)
7. Once the name is changed, right-click on the string and choose Modify. The Edit String dialog box appears.
8. In the Value data box, enter 0.
9. Click OK.
If templates already contain these extra metafile images, you can remove them using the Hidden Data Remover tool in
HotDocs. See the HotDocs Help for more information on using this tool.

Use Graphics in Headers and Footers Correctly

Often, you design your templates using company letterhead. Frequently this letterhead includes a company logo or
icon, which you choose to include on the first page of the document only. In this situation, you would typically select the
Different First Page option, and then remove the graphic from any subsequent pages in the document. Problems come
if you later decide you dont want a different first page header and you then clear the Different First Page option without
first removing the graphic from the first page header. What happens is, Word assigns the headers from page 2+ to the first
page so you can no longer see the graphic, but the graphic is still there. If you do not want graphics in your headers or
footers, you must manually delete them before changing your header/footer options.
Note:
This same behavior can also happen when selecting the Different Odd & Even Pages option.

Conclusion
In short, make sure you adhere to the following rules:

1. Use an image file format that works well in RTF files. Generally this is JPG, although some types of images (e.g. line
drawings) may be smaller in another format.

2. Size and crop images as required in the template before inserting them. Dont use Words sizing/cropping or other
picture manipulation features.

3. Use the lowest acceptable resolution for images (in order to decrease file size).
4. Insert images only where needed; avoid putting images in first page or odd/even headers that arent used in the
template.

5. Implement the registry setting that keeps Word from creating Windows Metafile Format copies of images in
documents.

Copyright 2010 HotDocs Ltd. All rights reserved

169

Help Topics for HotDocs Developer 10

Chapter 9: Inserting Variables in Text Templates

Overview: Create and Customize Variables
Once your document text is in a template file, you must replace variable text (text that changes each time you assemble a
document) with HotDocs variables. Examples of variable text include names, dates, pronouns, numbers, and calculations.
A variable is what prompts HotDocs to ask for that information when the template is used to assemble a document.
You can create seven types of variables: Text, Date, Number, True/False, Multiple Choice, Computation, and Personal
Information. The variable type determines what information users can enter when they complete an interview. For
example, if you create a Date variable, users must enter a valid datethey cannot enter text, such as a name, for an
answer.
The following graphic shows a paragraph that contains two items that change depending on the userthe name (Aaron
Jameson) and the date (12th day of October, 2002):

You replace both of these items with variables:

There are two parts to creating variablescreating the variable component, and creating the variable field:
Variable Component: The variable component is the core part of a HotDocs variable. It contains all the information
about a variable and how it should be processed, including the component name and prompt, any resource
information, and any special patterns or other options that help control how the variable appears during the
interview and how it will be processed when the final document is assembled. A variable component also creates
an association between the components and the answers the user enters, so that the answer can be saved in an
answer file. (Answer files can be reused when assembling other documents.)
Variable Field: When you insert a variable into a HotDocs template, HotDocs creates a field where the user's
answer is merged into the assembled document. In a text template, the field is denoted by HotDocs chevrons ( ),
while in a form template, the field is denoted by a colored box that is overlaid on the form's static text. There are
certain properties that are assigned to a variable's field that affect the way the variable is merged into the document
specifically, formats and merge text for Multiple Choice variables. You can also include fill characters that force the
answer to be a certain number of characters, regardless of how long the answer is.
When you insert a variable into the template, you automatically create a merge field for the variable. However, when you
create a variable using Component Manager, there is not a merge field associated with the variable until the variable is
inserted into the template.

Copyright 2010 HotDocs Ltd. All rights reserved

170

Help Topics for HotDocs Developer 10

Insert a Variable Field in a Text Template

To insert a variable in your template text, you have two options: you can select a portion of the text that will change
(such as a name, date, number, and so forth) and replace it with a variable field, or you can insert a variable field without
selecting any text at all. If you select text, once HotDocs replaces the text with a HotDocs variable, it searches for other
instances of the text and gives you the chance to replace those instances with the same variable. If you choose to simply
insert a variable in the template without replacing template text, HotDocs inserts the variable only once.
To replace template text with a variable

1. Select the text you want to replace and click the

Variable Field button. The Variable Field dialog box appears.

2. Select the type of variable you want to insert. Your options include Text, Date, Number, True/False, Multiple Choice,
Computation, and Personal Information.

3. Type a variable name in the Variable box. (If the variable already exists, select it from the drop-down list.) (See Tips
on Naming Your Variables.)

4. Optionally, clear Use defaults and select an example format from the Format drop-down list. This format will
determine how the answer appears in the assembled document. It is applied to this instance of the variable only.
(See Format the Variable.)

5. Click the

Edit Component button to modify the variable's component properties. (Click any of the following
links for information on customizing a specific variable type: Text, Date, Number, True/False, Multiple Choice, and
Computation.) When finished making changes, click OK. The Variable Field dialog box appears again.

6. Click either Replace Once (replaces this instance of the variable only), or Replace Multiple (displays the Find and
Replace dialog box where you can choose which instances you want to replace).

7. If you selected Replace Multiple, the Find and Replace dialog box appears.
8. Click the appropriate replacement option: Replace, Replace All, or Find Next. HotDocs replaces the text. (See
Replace Other Instances of Selected Text with a Variable.)
Caution:
WordPerfect users: When replacing multiple instances of text in a template, HotDocs will not replace those instances
found in headers, footers, footnotes, and text boxes. You must manually replace those.
To insert a variable without replacing any text

1. At the HotDocs template, insert the cursor where you want the variable to be.
2. Click the

Variable Field button. The Variable Field dialog box appears.

3. Select the type of variable you want to insert. Your options include Text, Date, Number, True/False, Multiple Choice,
Computation, and Personal Information.

4. Type a name in the Variable box. (If the variable already exists, select it from the drop-down list.) (See Tips on
Naming Your Variables.)

5. Optionally, clear Use default and select an example format from the Format drop-down list. This format will
determine how the answer appears in the assembled document. It is applied to this instance of the variable only.
(See Format the Variable.)

6. Click the

Edit Component button to modify the variable's component properties. (Click any of the following
links for information on customizing a specific variable type: Text, Date, Number, True/False, Multiple Choice, and
Computation.)

7. When finished making changes, click OK at both the Variable Editor and Variable Field dialog boxes. HotDocs
inserts the variable.

Copyright 2010 HotDocs Ltd. All rights reserved

171

Help Topics for HotDocs Developer 10

Note:
You can assign text formattingsuch as font, style, and sizeto a specific occurrence of a variable. To do
this, select the variable reference (including the chevrons) and use your word processor commands to assign
the format. When the document is assembled, the text will be formatted the way you specify. If you must use a
symbolic font, assign the font properties at the Variable Field dialog box. See Control How Answers Appear in
the Assembled Document.
In Microsoft Word, you can also insert variables either by clicking on the HotDocs drop-down menu in the
HotDocs toolbar and choosing Variable Field, or by right-clicking in the template and choosing Variable Field
from the shortcut menu.

Copyright 2010 HotDocs Ltd. All rights reserved

172

Help Topics for HotDocs Developer 10

Replace Other Instances of Selected Text with a Variable

When you replace text with a variable, HotDocs allows you to search forward through the template and replace other
instances of the text with the variable. You can control this process.
To replace selected text with the variable

1. Select the template text and create the variable. (See Insert a Variable Field in a Text Template.) When finished,
click either Replace Once (replaces this instance of the text only), or Replace Multiple (displays the Find and
Replace dialog box where you can control the replacement process).

2. If you clicked Replace Multiple, the Find and Replace dialog box appears. The Find what box shows what text
HotDocs is searching for. The Replace with box shows the name of the variable HotDocs is inserting.

3. Make a selection, based on the following information:

To

Do This

Replace this instance of

text and move to the next
instance

Click Replace.

Have HotDocs replace

all instances of text from
the selected instance to
the end of the template
(without confirmation)

Click Replace All.

Have HotDocs skip this

instance and search for
the next

Click Find Next.

Replace only those

instances of text that
are complete words (for
example, prevent HotDocs
from replacing the his in
this with a variable for a
pronoun)

Select Find whole words only.

Replace only those

instances of text that have
the same capitalization as
the selected instance

Select Match case.

Change the properties of

the variable

Click Modify and make the changes.

Copyright 2010 HotDocs Ltd. All rights reserved

173

Help Topics for HotDocs Developer 10

Create and Insert a Variable Using Component Manager

At times you might want to create a variable that might not appear in the template at all (such as a temporary variable that
helps process a computation.) Or, perhaps you want to create several variables consecutively but you might not be sure
where to use them in the template. You can use Component Manager to do this.
To create a variable using Component Manager

1. Open Component Manager. (See Open and Close Component Manager.) The Component Manager window
appears.

2. Select a variable type by clicking the Components drop-down button.

3. Click the

New Component button. The Variable Editor appears to gather information about the new variable.

4. Assign a name and any other properties to the variable and click OK.
If you use Component Manager to create variables, you can likewise use Component Manager to insert the variables
directly in the template.
To insert a variable into the template using Component Manager

1. Open Component Manager. (See Open and Close Component Manager.) The Component Manager window
appears.

2. Select the variable you want to insert from the component list. (To show only that certain type of variable in the list,
click the Components drop-down button and select the variable type.)

3. Either place your cursor in the template where you want the variable and click the

Insert Variable button (in

Component Manager), or drag the variable from the Components list into the template.

Copyright 2010 HotDocs Ltd. All rights reserved

174

Help Topics for HotDocs Developer 10

Add a Comment to a Variable or Instruction Field

When you insert a variable or instruction in a template, you can add a comment to the insertion field. Comments are
useful when you want to document information about the variable or instruction you are inserting and you want those
comments to be viewable by anyone editing the text of the template.
Comments can also be useful when viewing a markup view of the templatethe comment can describe (in easy-tounderstand terms) the purpose of the field or provide a more reader-friendly name for the field.
Note:
If you want to add comments to a specific component, enter it at the Notes tab of the component editor. See Add
Notes to Components for details.
To add a comment to a variable or instruction field

1. Insert a new variable or edit an existing variable. (See Insert a Variable Field in a Text Template or Edit a Variable.)
The Variable Field dialog box appears. Or, insert a new instruction or edit an existing instruction. The instruction
field dialog box appears.

2. Click Show Advanced. The view expands to show advanced options.

3. Enter your comments in the Comment box.
When you click OK, HotDocs merges the field, with the comments merged after the variable name, like this: Employee
Salary //Calculates biweekly salary based on hourly rate.
Note:
To merge a comment in an END instruction (such as END IF, END REPEAT, OR END SPAN), place your cursor
before the closing chevron, enter two forward slashes (//), and type your comment, like this: END IF //Closing.
If the END instruction contains a Keep Return code ( | ), enter the comment before the return code, like this: END
IF //Closing |.

Copyright 2010 HotDocs Ltd. All rights reserved

175

Help Topics for HotDocs Developer 10

Edit a Variable
You can edit a variable, including changing a variable's properties. Changes to the component properties of a variable
affect all instances of the variable in the template.
Note:
To edit a variable's field-specific properties, edit them at the Variable Field dialog box. To do this, place your cursor in
the variable field (at the template) and click the

Variable Field button. Make sure Use default is cleared.

You can edit a variable directly at the template, or you can edit it using Component Manager.
To edit a variable at the template

1. In the text template, click in the variable field and click the
the field and click the

Edit Component button. Or, in a form template, select

Edit Component button. The Variable Editor appears.

2. Make any changes. (Click any of the following links for information on customizing specific variable types: Text,
Date, Number, True/False, Multiple Choice, and Computation.)
To edit a variable at Component Manager

1. Open Component Manager. (See Open and Close Component Manager.) The Component Manager window
appears.

2. Select the variable from the list and click the

Edit Component button. The Variable Editor appears.

3. Make any changes. (Click any of the following links for information on customizing specific variable types: Text,
Date, Number, True/False, Multiple Choice, and Computation.)
Note:
If you're using Microsoft Word 2000 and above, you can double-click in a variable field in the template to open the
Variable Field dialog box.
For instructions on renaming a variable, see Rename Components in a Single Template.

Copyright 2010 HotDocs Ltd. All rights reserved

176

Help Topics for HotDocs Developer 10

Chapter 10: Using Variable Types

Overview: Create and Customize Variables
Once your document text is in a template file, you must replace variable text (text that changes each time you assemble a
document) with HotDocs variables. Examples of variable text include names, dates, pronouns, numbers, and calculations.
A variable is what prompts HotDocs to ask for that information when the template is used to assemble a document.
You can create seven types of variables: Text, Date, Number, True/False, Multiple Choice, Computation, and Personal
Information. The variable type determines what information users can enter when they complete an interview. For
example, if you create a Date variable, users must enter a valid datethey cannot enter text, such as a name, for an
answer.
The following graphic shows a paragraph that contains two items that change depending on the userthe name (Aaron
Jameson) and the date (12th day of October, 2002):

You replace both of these items with variables:

There are two parts to creating variablescreating the variable component, and creating the variable field:
Variable Component: The variable component is the core part of a HotDocs variable. It contains all the information
about a variable and how it should be processed, including the component name and prompt, any resource
information, and any special patterns or other options that help control how the variable appears during the
interview and how it will be processed when the final document is assembled. A variable component also creates
an association between the components and the answers the user enters, so that the answer can be saved in an
answer file. (Answer files can be reused when assembling other documents.)
Variable Field: When you insert a variable into a HotDocs template, HotDocs creates a field where the user's
answer is merged into the assembled document. In a text template, the field is denoted by HotDocs chevrons ( ),
while in a form template, the field is denoted by a colored box that is overlaid on the form's static text. There are
certain properties that are assigned to a variable's field that affect the way the variable is merged into the document
specifically, formats and merge text for Multiple Choice variables. You can also include fill characters that force the
answer to be a certain number of characters, regardless of how long the answer is.
When you insert a variable into the template, you automatically create a merge field for the variable. However, when you
create a variable using Component Manager, there is not a merge field associated with the variable until the variable is
inserted into the template.

Copyright 2010 HotDocs Ltd. All rights reserved

177

Help Topics for HotDocs Developer 10

Customize a Text Variable

Text variables are used to merge text, such as names or descriptions, into assembled documents. They also merge
numbers that are never added, subtracted, and so on, such as telephone numbers, U.S. Social Security numbers, and
times of day.
When you create a Text variable, you can add a title or prompt to help the user know what information is required. You
can also decide how answers will be formatted when they are merged into the assembled document. Finally, you can add
a resource or select advanced options that determine how the variable will be processed and merged into the document.
Once a variable is created, you can edit it at any time. See Edit a Variable.
To edit the properties of a Text variable

1. Follow the instructions for inserting a variable, selecting Text as the variable type. (See Insert a Variable Field in a
Text Template.)

2. At the Variable Field dialog box, click the

Edit Component button. The Text Variable Editor appears.

3. Make any changes, as described in the following table:

To

Do This

Specify a default format

that will be applied to all
instances of the variable
(except when a fieldspecific format has been
assigned)

Select a format from the Default format drop-down list. (See Format the Variable
and How Example Formats are Interpreted.)

Specify an alternate name

for the variable

Enter a title in the Title box.

Provide users with

additional information
about the variable

Enter a prompt in the Prompt box. This information replaces the Variable name and
Variable title when the variable is presented during the interview. (See Create a
Prompt for a Variable.)

Change the height of the

answer field that appears
in the interview, allowing it
to show more than a single
line

Either type the number of answer field lines (up to 12) in the Field height box, or
click the up or down arrows to select a number.

Control how an answer

is merged in a Word
document when the user
presses Enter in a multiline answer field

Select Enter key in multi-line answers inserts new paragraph mark ( ).

Optionally, to keep the answer from breaking across lines in the document, select
Non-breaking.

See Understand How Component Titles and Prompts are Used for a description of
how and when variable titles are used.

Changing the answer field height affects only how large the answer field appears in
the interviewnot how long the answer can be. To limit the answer length, enter a
number in the Maximum characters box.

To control whether line or paragraph breaks are inserted in literal text strings
used in computation scripts, see Use Line Breaks, Paragraph Ends, and Tabs in
Computation Scripts.

The type of answer

required determines which
break should be used. For
example, if the user must
enter separate paragraphs
of text, HotDocs should
merge a paragraph break.
Copyright 2010 HotDocs Ltd. All rights reserved

178

Help Topics for HotDocs Developer 10

To

Do This

However, if the user must

enter separate lines in a
single paragraph (such
as lines in an address),
HotDocs should insert a
line break.
Control the number of
characters allowed in the
answer

Either type a value in the Maximum characters box, or click the up or down arrows
to select a value (up to 15,000 characters).

Control what type of

information a user types
and format it as they type

Select a pattern from the Pattern drop-down list. (HotDocs provides a telephone
number pattern, time of day patterns, and a Social Security number pattern. You can
also create your own. See Use Pattern Codes to Create a Custom Pattern.)

Control how the variable

is processed during
assembly, as well as how
its answer appears in
the interview and in the
assembled document

Click the Advanced tab and select any of the options. (See Control How HotDocs
Processes a Variable, Specify the Width of Answer Fields in the Interview, and
Control How HotDocs Processes a Variable, respectively.)

Provide users with helpful

information that can assist
them in providing the
correct answer

Click the Resource tab and provide a resource option. (See Add Resource
Information to a Variable or Dialog.)

View a list of all

components that refer to
this variable

Click the Used In tab. (See View Relationship Between the Current Component and
Other Components.)

Enter notes about the

component, such as an
explanation about why the
component was created or
how it should function in
the interview

Click the Notes tab and enter your comments. (See Add Notes to Components for
details.)

Save changes to the

Click Save.
variable without closing the
variable editor

Copyright 2010 HotDocs Ltd. All rights reserved

179

Help Topics for HotDocs Developer 10

Customize a Number Variable

You can merge numbers into your assembled document using Number variables. You can format numbers as currency,
use decimals, and specify minimum and maximum values.
Typically you use a Number variable to represent text in your template that can be calculatedfor example, dollar
amounts or other sums. Even though Social Security numbers, telephone numbers, and times are numbers, you must use
a Text variable with the appropriate pattern to merge one of these numbers into your document. (See Customize a Text
Variable.)
When you create a Number variable, you can add a title or prompt to help the user know what information is required. You
can also decide how answers will be formatted when they are merged into the assembled document. Finally, you can add
a resource or select advanced options that determine how the variable will be processed and merged into the document.
Once a variable is created, you can edit it at any time. (See Edit a Variable.)
To edit the properties of a Number variable

1. Follow the instructions for inserting a variable, selecting Number as the variable type. (See Insert a Variable Field in
a Text Template.)

2. At the Variable Field dialog box, click the

Edit Component button. The Number Variable Editor appears.

3. Make any changes, as described in the following table:

To

Do This

Specify a default format

that will be applied to all
instances of the variable
(except when a fieldspecific format has been
assigned)

Select a format from the Default format drop-down list. (See Format the Variable
and How Example Formats are Interpreted.)

Specify an alternate name

for the variable

Enter a title in the Title box.

Provide users with

additional information
about the variable

Enter a prompt in the Prompt box. This information replaces the Variable name and
Variable title when the variable is presented during the interview. (See Create a
Prompt for a Variable.)

Force users to enter a

number that falls within a
certain numeric range

Type numbers in the Minimum and Maximum boxes.

Specify a certain number

of decimal places allowed
in the users' answer

Either type a number (0-7) in the Decimal places box, or click the up or down arrows
to select a number.

Make HotDocs show a

currency symbol next to
the answer field when it
displays the variable in the
interview

Select a symbol from the Currency drop-down list.

Control how the variable

is processed during
assembly, as well as how
its answer appears in

Click the Advanced tab and select any of the options. (See Control How HotDocs
Processes a Variable, Specify the Width of Answer Fields in the Interview, and
Control How HotDocs Processes a Variable, respectively.)

Optionally, to keep the answer from breaking across lines in the document, select
Non-breaking.

See Understand How Component Titles and Prompts are Used for a description of
how and when variable titles are used.

Copyright 2010 HotDocs Ltd. All rights reserved

180

Help Topics for HotDocs Developer 10

To

Do This

the interview and in the

assembled document
Provide users with helpful
information that can assist
them in providing the
correct answer

Click the Resource tab and provide a resource option. (See Add Resource
Information to a Variable or Dialog.)

View a list of all

components that refer to
this variable

Click the Used In tab. (See View Relationship Between the Current Component and
Other Components.)

Enter notes about the

component, such as an
explanation about why the
component was created or
how it should function in
the interview

Click the Notes tab and enter your comments. (See Add Notes to Components for
details.)

Save changes to the

Click Save.
variable without closing the
variable editor
Note:
If you are creating a list of answers, you can use a built-in Number variable called COUNTER to count the
number of entries in a list. See Count the Number of Entries in a List.
You can automatically number paragraphs or other blocks of text. See Use Automatic Paragraph Numbering.

Copyright 2010 HotDocs Ltd. All rights reserved

181

Help Topics for HotDocs Developer 10

Customize a Date Variable

You can create variables that merge dates into your assembled document. When you create a Date variable, you can add
a title or prompt to help the user know what information is required. You can also decide how answers will be formatted
when they are merged into the assembled document. Finally, you can add a resource or select advanced options that
determine how the variable will be processed and merged into the document.
Once a variable is created, you can edit it at any time. See Edit a Variable.
To edit the properties of a Date variable

1. Follow the instructions for inserting a variable, selecting Date as the variable type. (See Insert a Variable Field in a
Text Template.)

2. At the Variable Field dialog box, click the

Edit Component button to open the Date Variable Editor.

3. Make any changes, as described in the following table:

To

Do This

Specify a default format

that will be applied to all
instances of the variable
(except when a fieldspecific format has been
assigned)

Select a format from the Default format drop-down list. (See Format the Variable
and How Example Formats are Interpreted.)

Specify an alternate name

for the variable

Enter a title in the Title box.

Provide users with

additional information
about the variable

Enter a prompt in the Prompt box. This information replaces the Variable name and
Variable title when the variable is presented during the interview. (See Create a
Prompt for a Variable.)

Control how the variable

is processed during
assembly, as well as how
its answer appears in
the interview and in the
assembled document

Click the Advanced tab and select any of the options. (See Control How HotDocs
Processes a Variable, Specify the Width of Answer Fields in the Interview, and
Control How HotDocs Processes a Variable, respectively.)

Provide users with helpful

information that can assist
them in providing the
correct answer

Click the Resource tab and provide a resource option. (See Add Resource
Information to a Variable or Dialog.)

View a list of all

components that refer to
this variable

Click the Used In tab. (See View Relationship Between the Current Component and
Other Components.)

Enter notes about the

component, such as an
explanation about why the
component was created or
how it should function in
the interview

Click the Notes tab and enter your comments. (See Add Notes to Components for
details.)

Optionally, to keep the answer from breaking across lines in the document, select
Non-breaking.

See Understand How Component Titles and Prompts are Used for a description of
how and when variable titles are used.

Copyright 2010 HotDocs Ltd. All rights reserved

182

Help Topics for HotDocs Developer 10

To

Do This

Save changes to the

Click Save.
variable without closing the
variable editor

Copyright 2010 HotDocs Ltd. All rights reserved

183

Help Topics for HotDocs Developer 10

Customize a True/False Variable

Using a True/False variable, you can merge a word or phrase into an assembled document based on the user's answer to
a yes/no question.
Likewise, if you are developing a form template using HotDocs Automator, you can use True/False variables to select and
clear check boxes.
When you create a True/False variable, you can add a title or prompt to help the user know what information is required.
You can also decide how answers will be formatted when they are merged into the assembled document. Finally, you
can add a resource or select advanced options that determine how the variable will be processed and merged into the
document.
Once a variable is created, you can edit it at any time. See Edit a Variable.
To edit the properties of a True/False variable

1. Follow the instructions for inserting a variable, selecting True/False as the variable type. (See Insert a Variable Field
in a Text Template.)

2. At the Variable Field dialog box, click the

Edit Component button to open the True/False Variable Editor.

3. Make any changes, as described in the following table:

To

Do This

Specify a default format

that will be applied to all
instances of the variable
(except when a fieldspecific format has been
assigned)

Select a format from the Default format drop-down list.

You can customize this format by entering other true/false text to the left and right of
the slash. If the user chooses yes, the text entered to the left of the slash merges. If
the user chooses no, the text entered to the right of the slash merges. If you do not
enter a format, either true or false is merged. (See Format the Variable.)
Optionally, to keep the answer from breaking across lines in the document, select
Non-breaking.
Note:
The total number of characters you can use in a merge format is 1,000, but only
the first 50 characters appear in the template.

Specify an alternate name

for the variable

Enter a title in the Title box.

Provide users with

additional information
about the variable

Enter a prompt in the Prompt box. This information replaces the Variable name and
Variable title when the variable is presented during the interview. (See Create a
Prompt for a Variable.)

Have Yes and No appear

on the same line in the
interview

Select Yes/No on same line.

Control how the variable

is processed during
assembly, as well as how
its answer appears in
the interview and in the
assembled document

Click the Advanced tab and select any of the options. (See Control How HotDocs
Processes a Variable, Specify the Width of Answer Fields in the Interview, and
Control How HotDocs Processes a Variable, respectively.)

See Understand How Component Titles and Prompts are Used for a description of
how and when variable titles are used.

Copyright 2010 HotDocs Ltd. All rights reserved

184

Help Topics for HotDocs Developer 10

To

Do This

Provide users with helpful

information that can assist
them in providing the
correct answer

Click the Resource tab and provide a resource option. (See Add Resource
Information to a Variable or Dialog.)

View a list of all

components that refer to
this variable

Click the Used In tab. (See View Relationship Between the Current Component and
Other Components.)

Enter notes about the

component, such as an
explanation about why the
component was created or
how it should function in
the interview

Click the Notes tab and enter your comments. (See Add Notes to Components for
details.)

Save changes to the

Click Save.
variable without closing the
variable editor
Note:
If you have multiple True/False variables in a dialog, you can group them so that each variable is preceded with a
check box or option button. This allows users to select either one option or multiple options from a list of possible
answers. See Change a Dialog's Options.
You can use True/False variables to determine whether sections of text should be included in a document. See
Include or Exclude a Single Version of Text Using a Simple IF Instruction or Expression.

Copyright 2010 HotDocs Ltd. All rights reserved

185

Help Topics for HotDocs Developer 10

Customize a Multiple Choice Variable

You can let users select one or more answers from a list of possible options by using a Multiple Choice variable. The
selected option or its corresponding merge text is merged into the assembled document. (Merge text can be specified
either at a variable field or at the variable editor. See Specify Merge Text Options as Default or Field-Specific Properties.)
When you create a Multiple Choice variable, you can add a title or prompt to help the user know what information is
required. You can also decide how answers will be formatted when they are merged into the assembled document.
Finally, you can add a resource or select advanced options that determine how the variable will be processed and merged
into the document.
Once a variable is created, you can edit it at any time. See Edit a Variable for details.
To edit the properties of a Multiple Choice variable

1. Follow the instructions for inserting a variable, selecting Multiple Choice as the variable type. (See Insert a Variable
Field in a Text Template.)

2. At the Variable Field dialog box, click the

Edit Component button to open the Multiple Choice Variable Editor.

3. Type the options (at least two) you want users to choose from in the Option column. (Do not create an option with
the exact text None of the Above or Other. Instead, select None of the Above or Other from the Select option.)

4. Optionally, type a prompt for the option in the Prompt column. The prompt (instead of the corresponding Option
text) appears for the options during the interview. (If you need more space for the prompt, click the Options tab and
type the text there. See Work with Multiple Choice Options.)

5. Optionally, type the text you want merged into the assembled document in the Default Merge Text column. (If you
need more space for the merge text, click the Options tab and type the text there. See Work with Multiple Choice
Options.)

6. From the Select drop-down list, select either One Only or All That Apply.
7. Depending on your selection in Step 6, you can select Other or None of the Above. (These options allow users to
either type an answer not in the list or specify that the answer needed is not available in the list.)

8. Choose a display style from the Style drop-down list. The available styles depend on the selection style.
9. Make any other changes, as described in the following table:
To

Do This

Add longer prompts and

Click the Options tab and make your changes. (See Work with Multiple Choice
merge text for each option, Options.)
as well as suggest an
answer for the user
Specify a default format
that will be applied to all
instances of the variable
(except when a fieldspecific format has been
assigned)

Select a format from the Default format drop-down list. (See Format the Variable
and How Example Formats are Interpreted.)

Specify an alternate name

for the variable

Enter a title in the Title box.

Provide users with

additional information
about the variable

Enter a prompt in the Prompt box. This information replaces the Variable name and
Variable title when the variable is presented during the interview. (See Create a
Prompt for a Variable.)

Optionally, to keep the answer from breaking across lines in the document, select
Non-breaking.

See Understand How Component Titles and Prompts are Used for a description of
how and when variable titles are used.

Copyright 2010 HotDocs Ltd. All rights reserved

186

Help Topics for HotDocs Developer 10

To

Do This

Control how the variable

is processed during
assembly, as well as how
its answer appears in
the interview and in the
assembled document

Click the Advanced tab and select any of the options. (See Control How HotDocs
Processes a Variable, Specify the Width of Answer Fields in the Interview, and
Control How HotDocs Processes a Variable, respectively.)

Provide users with helpful

information that can assist
them in providing the
correct answer

Click the Resource tab and provide a resource option. (See Add Resource
Information to a Variable or Dialog.)

View a list of all

components that refer to
this variable

Click the Used In tab. (See View Relationship Between the Current Component and
Other Components.)

Enter notes about the

component, such as an
explanation about why the
component was created or
how it should function in
the interview

Click the Notes tab and enter your comments. (See Add Notes to Components for
details.)

Save changes to the

Click Save.
variable without closing the
variable editor
Note:
You can control whether merge text is a default property of the variable component, or whether it's a field-specific
property of a variable field. See Specify Merge Text Options as Default or Field-Specific Properties for details.
You can add and delete rows of options by clicking Insert or Delete.
You can use existing option or merge text lists when you create other Multiple Choice variables in the template.
To do this, click the Option and Merge Text column headings and choose the group.
You can copy and paste options either to or from the Multiple Choice Variable Editor. See Copy and Paste
Columns in a Multiple Choice Variable Spreadsheet.
To SET two or more options for a Multiple Choice variable in a computation script, separate each option with
a vertical bar (for example, SET MC Variable TO "Option1|Option2|Option3"). (The Multiple Choice
variable must have the Select All That Apply property selected.)
You frequently use Multiple Choice variables to insert gender references, such as pronouns. HotDocs
automatically includes common pronoun sets in the Merge Text list. Click the Merge Text column heading and
select an option.
You can customize Multiple Choice option prompts and merge text based on answers the user enters in the
interview. See Use Variables and Scripts in Prompts, Dialog Element Text, and Resources for details.

Copyright 2010 HotDocs Ltd. All rights reserved

187

Help Topics for HotDocs Developer 10

Customize a Computation Variable

You can use a Computation variable to calculate number, date, true/false, and text values based on answers a user
enters. The computed value can then be merged into the assembled document. Computation variables can also be used
to group several instructions or expressions for insertion into a template, which results in quicker assembly.
Creating a computation requires you to write a script using the HotDocs scripting language. The actual process of writing
a script depends on your skill level in using this languageif you're a beginner, you can drag scripting models into the
Script box and allow HotDocs to guide you in filling in the required information. With experience, you can type the script
directly in the box. (See Understand the HotDocs Scripting Language and Use the Script Editor.)
The title bar of the Computation Editor contains information that can help you evaluate the correctness of the script
as you write it. When a script is invalid (meaning it does not adhere to the rules of the HotDocs scripting language),
HotDocs includes the word [Invalid] in the title bar. Once a script is valid, HotDocs then notes what type of result the
script produces (for example, [Text] or [Number]).
Once a variable is created, you can edit it at any time. See Edit a Variable for details.
To edit the properties of a Computation variable

1. Follow the instructions for inserting a variable, selecting Computation as the variable type. (See Insert a Variable
Field in a Text Template.)

2. At the Variable Field dialog box, click the

Edit Component button to open the Computation Editor.

3. In the Script box, enter a computation script. (See Use the Script Editor for specific instructions.)
4. Make any other changes, as described in the following table:
To

Do This

Indent matching pairs of IF

and REPEAT instructions

Click the
Auto Format button. HotDocs indents the instructions based on the level
of their insertion.

Specify a default format

that will be applied to all
instances of the variable
(except when a fieldspecific format has been
assigned)

Select a format from the Default format drop-down list. (See Format the Variable
and How Example Formats are Interpreted.)

Control how the variable

is processed during
assembly, as well as how
its answer appears in
the interview and in the
assembled document

Click the Advanced tab and select any of the options. (See Control How HotDocs
Processes a Variable, Specify the Width of Answer Fields in the Interview, and
Control How HotDocs Processes a Variable, respectively.)

Add a title to the

Computation variable

Click the Advanced tab and enter the title in the Title box.

Provide users with helpful

information that can assist
them in providing the
correct answer

Click the Resource tab and provide a resource option. (See Add Resource
Information to a Variable or Dialog.)

View a list of all

components that refer to
this variable

Click the Used In tab. (See View Relationship Between the Current Component and
Other Components.)

Optionally, to keep the answer from breaking across lines in the document, select
Non-breaking.

Copyright 2010 HotDocs Ltd. All rights reserved

188

Help Topics for HotDocs Developer 10

To

Do This

Enter notes about the

component, such as an
explanation about why the
component was created or
how it should function in
the interview

Click the Notes tab and enter your comments. (See Add Notes to Components for
details.)

Save changes to the

Click Save.
variable without closing the
variable editor
Note:
You can create new variables directly at the Computation Editor. Make sure the Components list contains the
type of variable you want to create, and then click the
existing variable in the list by double-clicking it.

New Component button. Similarly, you can edit an

If you experience errors when writing a script, it may be because you are using the instruction and expression
keywords incorrectly. See Understand and Resolve Syntax Errors in a Template or Script for troubleshooting tips.
If you aren't receiving errors, but the script produces results you don't expect, you can examine the script line by
line to see where the logic is flawed. See Overview: Debugging Templates for information.
HotDocs will not let you close the Computation Editor or save a script if the script is invalid. If you need to close
or save, you must either comment out the script (by highlighting the script and clicking the
button) or place a QUIT instruction at the beginning of the script (see QUIT).

Copyright 2010 HotDocs Ltd. All rights reserved

Comment Block

189

Help Topics for HotDocs Developer 10

Insert a Personal Information Variable

Personal Information variables store basic information about the user, such as a name, a company name, and a phone
number in the Current User key of the Windows System Registry. Those answers can then be used in any document
that uses the same Personal Information variables, regardless of which answer file is being used. HotDocs provides 12
Personal Information variables, but you can also create your own.
To insert a Personal Information variable

1. At the template, place your cursor where you want the Personal Information variable and click the

Variable Field

button. The Variable Field dialog box appears.

2. Select Personal Information.

3. Either type a name for a new Personal Information variable in the Variable box, or click the Variable drop-down
button to select an existing Personal Information variable.

4. Optionally, clear Use default and select an example format from the Format drop-down list. This format will be
applied to this instance of the variable only. (See Format the Variable.)

5. Optionally, click Show Advanced to assign options that control how that specific instance of the variable is merged
into the assembled document. See Control How Answers Appear in the Assembled Document for information about
each option.
When a Personal Information variable is inserted in the template, its name is preceded by the word MY. This notation
distinguishes it from other variables in the template.
When users assemble documents that use Personal Information variables, HotDocs asks for the information and then
stores it in the HotDocs section of the system registry. Once entered, the variable is never asked again; however, users
can change their information at the HotDocs Options dialog box. See Edit Answers for Built-In Personal Information
Variables.

Copyright 2010 HotDocs Ltd. All rights reserved

190

Help Topics for HotDocs Developer 10

Create a Date Variable that Inserts the Current Date

You can insert the current date in a template using the built-in variable, TODAY. The variable wont be asked during the
interviewinstead TODAY automatically merges the current date, based on the Windows System Clock.
To insert the TODAY variable

1. Follow the instructions for inserting a variable, selecting Date as the variable type. (See Insert a Variable Field in a
Text Template.)

2. At the Variable Field dialog box, click the Variable drop-down button and select TODAY.
3. Optionally, clear Use default and select a format from the Format drop-down list. This format will be applied to this
instance of the variable only. (See Format the Variable.)

Copyright 2010 HotDocs Ltd. All rights reserved

191

Help Topics for HotDocs Developer 10

Merge the Name of the Answer File in the Document

In some documents, you may need to include the name of the answer file that was used to assemble the document. You
can insert an instruction that merges the path and file name of the answer file directly in the document. If the answer file is
new and unsaved, the text, New Answer File, is merged into the assembled document.
To create an answer file variable

1. Open a template for editing. (See Edit a Template.)

2. Position the cursor in the template where you want to merge the name of the answer file.
3. Click the Variable Field dialog box and choose Text as the Variable type.
4. Click the Variable drop-down button and choose ANSWER FILE NAME.

Copyright 2010 HotDocs Ltd. All rights reserved

192

Help Topics for HotDocs Developer 10

Use Automatic Paragraph Numbering

You can create Number variables that supply automatic paragraph numbering to lists of answers in your HotDocs text
template. This feature is not available in JavaScript or Silverlight interviews.
Caution:
HotDocs paragraph numbering values are merged into an assembled document as text, not codes. This means
that if users add or delete a paragraph after the document has been assembled and sent to the word processor, the
numbering will not adjust. To have automatic paragraph numbering that adjusts to changes made in the assembled
document, use your word processors numbering codes.
To create automatic paragraph numbering

1. Position your cursor at the place in the template where you want the paragraph numbering to take effect.
2. Follow the instructions for inserting a variable, selecting Number as the variable type. (See Insert a Variable Field in
a Text Template.)

3. With the Variable Field dialog box displayed, type PN# in the Variable box. (Replace # with a number representing
the paragraph level. Numbers 19 can be entered.)

4. Optionally, clear Use default and select one of the following formats: 9.9, 9.9.a, abc, or IX. (If no example format is
selected, the default9is used.)

5. Insert this Number variable before every paragraph of that level.

Note:
You can use SET instructions to customize HotDocs paragraph numbering. For example, the computation script, SET
PN1 TO 10, would automatically start the paragraph numbering at 10. Additionally, if you assign the abc example
format to the PN1 variable, HotDocs will merge in the alphabetic character that corresponds with the number used
in the SET instruction. For example, the computation script, SET PN1 TO 10, would start numbering the variable
PN1:ABC with the letter J.

Copyright 2010 HotDocs Ltd. All rights reserved

193

Help Topics for HotDocs Developer 10

Count the Number of Entries in a List

You can use a computation script to determine how many times a user answers a repeated dialog. You can also use a
built-in Number variable that numbers a list of answers automatically.
To determine the number of entries in a list

1. Create a Computation variable containing the expression COUNT( DIALOG ). (See Customize a Computation
Variable.)

2. Replace the DIALOG placeholder with the name of the repeated dialog.
3. Optionally, insert this Computation variable wherever you want the number of entries to appear. (You don't have
to insert the Computation variable in the template. Often, template developers simply use the COUNT( DIALOG )
expression as a way to keep track of the number of answers without ever inserting the actual number in the
template.)
To number a list automatically

1. At the template, position your cursor before the variable in the list you want to number.
2. Insert a Number variable. (See Insert a Variable Field in a Text Template and Customize a Number Variable.)
Instead of typing a variable name, however, click the Variable drop-down button and select COUNTER.

3. Click OK.
4. Add any punctuation or spaces you want to go with the number. For example:
The children are listed, as follows:
REPEAT Childrens Names
COUNTER. Name of Child, Age of Child
END REPEAT

Copyright 2010 HotDocs Ltd. All rights reserved

194

Help Topics for HotDocs Developer 10

Chapter 11: Editing Variables

Overview: Create and Customize Variables
Once your document text is in a template file, you must replace variable text (text that changes each time you assemble a
document) with HotDocs variables. Examples of variable text include names, dates, pronouns, numbers, and calculations.
A variable is what prompts HotDocs to ask for that information when the template is used to assemble a document.
You can create seven types of variables: Text, Date, Number, True/False, Multiple Choice, Computation, and Personal
Information. The variable type determines what information users can enter when they complete an interview. For
example, if you create a Date variable, users must enter a valid datethey cannot enter text, such as a name, for an
answer.
The following graphic shows a paragraph that contains two items that change depending on the userthe name (Aaron
Jameson) and the date (12th day of October, 2002):

You replace both of these items with variables:

There are two parts to creating variablescreating the variable component, and creating the variable field:
Variable Component: The variable component is the core part of a HotDocs variable. It contains all the information
about a variable and how it should be processed, including the component name and prompt, any resource
information, and any special patterns or other options that help control how the variable appears during the
interview and how it will be processed when the final document is assembled. A variable component also creates
an association between the components and the answers the user enters, so that the answer can be saved in an
answer file. (Answer files can be reused when assembling other documents.)
Variable Field: When you insert a variable into a HotDocs template, HotDocs creates a field where the user's
answer is merged into the assembled document. In a text template, the field is denoted by HotDocs chevrons ( ),
while in a form template, the field is denoted by a colored box that is overlaid on the form's static text. There are
certain properties that are assigned to a variable's field that affect the way the variable is merged into the document
specifically, formats and merge text for Multiple Choice variables. You can also include fill characters that force the
answer to be a certain number of characters, regardless of how long the answer is.
When you insert a variable into the template, you automatically create a merge field for the variable. However, when you
create a variable using Component Manager, there is not a merge field associated with the variable until the variable is
inserted into the template.

Copyright 2010 HotDocs Ltd. All rights reserved

195

Help Topics for HotDocs Developer 10

Edit a Variable
You can edit a variable, including changing a variable's properties. Changes to the component properties of a variable
affect all instances of the variable in the template.
Note:
To edit a variable's field-specific properties, edit them at the Variable Field dialog box. To do this, place your cursor in
the variable field (at the template) and click the

Variable Field button. Make sure Use default is cleared.

You can edit a variable directly at the template, or you can edit it using Component Manager.
To edit a variable at the template

1. In the text template, click in the variable field and click the
the field and click the

Edit Component button. Or, in a form template, select

Edit Component button. The Variable Editor appears.

2. Make any changes. (Click any of the following links for information on customizing specific variable types: Text,
Date, Number, True/False, Multiple Choice, and Computation.)
To edit a variable at Component Manager

1. Open Component Manager. (See Open and Close Component Manager.) The Component Manager window
appears.

2. Select the variable from the list and click the

Edit Component button. The Variable Editor appears.

3. Make any changes. (Click any of the following links for information on customizing specific variable types: Text,
Date, Number, True/False, Multiple Choice, and Computation.)
Note:
If you're using Microsoft Word 2000 and above, you can double-click in a variable field in the template to open the
Variable Field dialog box.
For instructions on renaming a variable, see Rename Components in a Single Template.

Copyright 2010 HotDocs Ltd. All rights reserved

196

Help Topics for HotDocs Developer 10

Format the Variable

You can cause an answer to be formatted a certain way in an assembled documenteven if the user types the answer
using a different format. For example, a number can be merged as ONE HUNDRED DOLLARS in the assembled
document, even if the user types 100. (See How Example Formats are Interpreted.)
You can assign the format either when you insert the variable field or when you create the variable component.
Specifically, if you assign a format at the Variable Field dialog box, the format applies to that specific instance of the
variable onlythe format is a property of the field. However, if you assign a format to the component, that format is used
each time the variable is inserted into the template. The format becomes a property of the component.
When you insert a new variable in a template (without replacing any template text), you can specify which format you
want HotDocs to use for that instance. However, when you create a variable by replacing existing template text (see
Insert a Variable Field in a Text Template), HotDocs looks at the text you have selected and attempts to suggest a fieldspecific format based on what it sees. For example, if you select the template text, 14 November 1973 and then create a
Date variable, HotDocs suggests a field-specific format of 3 June 1990. This format will be applied to this instance of the
variable only.
Finally, if users' answers shouldn't break across lines in the document, you can force the answer to be non-breaking. You
do this by selecting the Non-breaking property next to the Format drop-down list at either the Component Editor or at
the Variable Field dialog box.
To assign a field-specific format to a variable

1. At the template, place your cursor inside a variable field and click the

Variable Field button. The Variable Field

dialog box appears.

2. If it's selected, clear Use default. The format options become available.
3. Click the Format drop-down button and select an appropriate format.
4. Optionally, select Non-breaking. This keeps the answer from breaking across lines in the document. (You can
assign this property to a variable field even if you do not assign a specific format.)

5. Click OK.
When you assign a field-specific format to the variable, the example format is merged with the variable name in the field.
To assign a default format to a variable

1. At the template, place your cursor inside a variable field and click the

Edit Component button. The Variable

Editor appears.

2. Click the Default format drop-down button and select an example format.
3. Optionally, select Non-breaking to keep the answer from breaking across lines in the document. (You can assign
this property to a variable field even if you do not assign a specific format.)

4. Click OK.
Now, when you insert this variable in other places in the template, the format you have specified will be used. (You can, of
course, override this by assigning a field-specific format.)
When you view the Variable Field dialog box, the default example format you have selected appears grayed in the
Format box, and Use default is selected. If you clear this check box, the default format is suggested as the field-specific
format. It also becomes a property of the field.
Note:
The Use defaults option at a Variable Field dialog box controls all field properties of a variable. (Field properties
include answer formats, Multiple Choice merge text, and field formats.) This means that you cannot assign a
Copyright 2010 HotDocs Ltd. All rights reserved

197

Help Topics for HotDocs Developer 10

field-specific property to a field and then assign a default property to the variable component. If you choose one
type of property, all other properties must be the same type.
You can create your own formats by typing an example in the Format box. Follow the format of the existing
examplesfor example, use a variation on the number nine for number examples, and use a variation on the
date June 3, 1990 for date examples.

Copyright 2010 HotDocs Ltd. All rights reserved

198

Help Topics for HotDocs Developer 10

Create a Prompt for a Variable

By default, when you assign a name to a variable, that name is what appears in the interview to guide users in providing
an answer. However, sometimes you may name your variables using a scheme that would be confusing for your users
to understand. Likewise, some situations require more detailed instructions. HotDocs allows you to provide longer
explanations by using a prompt. During the interview, the prompt replaces the variable name (and title, if one has been
provided).
To create a prompt for a variable

1. Edit the variable. (See Edit a Variable.) The Variable Editor appears.
2. In the Prompt box, type the information about the variable you want the user to see.
3. Optionally, to assign font properties to the prompt text (such as bold or underline), enter a formatting dot code. (See
Overview: Dot Codes.)
Note:
You can include a variable in the Prompt box, which will merge the user's answer into the prompt during the
interview. See Use Variables and Scripts in Prompts, Dialog Element Text, and Resources.
When you group variables in a dialog, you can specify the visual relationship between variable prompts and
answer fields by choosing an alignment option at the Options tab of the Dialog Editor. See Change a Dialog's
Options.
You can make HotDocs show only an answer fieldwith no prompt or variable namein the interview. To do
this, type NONE in the Prompt box.
To make a character in your prompt an accelerator key, type an ampersand (&) character immediately before the
letter you want as an accelerator. Then, during the interview, users can press the Alt key while also pressing the
underlined character in the prompt, which moves the cursor to that answer field.

Copyright 2010 HotDocs Ltd. All rights reserved

199

Help Topics for HotDocs Developer 10

Control How HotDocs Processes a Variable

You can have greater control over how HotDocs processes a variable. For instance, you can control whether a variable
appears during the interview, whether the answer is saved, and whether users are warned when they leave the question
unanswered. These options are properties of the variable component, and not the variable field.
By clearing Ask automatically, you cause a variable to be asked only when it is in a dialog that is specifically asked. (See
How Variables and Dialogs Are Asked for details on how variable and dialogs are asked.)
When users leave questions unanswered during the interview, HotDocs leaves the dialog's icon in the interview outline
partially answered and notes the unanswered question in the End of Interview dialog. When you clear Warn when
unanswered, HotDocs suppresses these warnings. You might want to assign this option to variables that wont always be
answered in all casesfor example, a variable that asks a middle name or a second address line.
Clearing Save in answer file prevents a variables answer from being saved. You might use this feature if the variable
is a temporary variable (for example, a variable that has its value SET to a temporary value for use in a script). This will
keep HotDocs from marking the variable as answered and prompting the user to save the answer file.
Note:
These options are not available for Computation variables.
To control how HotDocs processes a variable

1. At the HotDocs template, edit a variable. (See Edit a Variable.)

2. Click the Advanced tab. The dialog box changes to show several advanced options.
3. Clear any of the following options, as explained in the following table:
To

Do This

Prevent the variable

question from appearing
in an interview unless the
variable is used in a dialog
that is specifically asked

Clear Ask Automatically.

Prevent the unanswered

variable warning from
appearing for this variable
when a user finishes the
interview. (The warning
appears in both the End
of Interview dialog and
when you attempt to close
an assembly window.
HotDocs also uses the
unanswered or partially
answered dialog icon in
the interview outline.)

Clear Warn when unanswered.

Prevent the variables

answer from being saved
in an answer file

Clear Save in answer file.

Copyright 2010 HotDocs Ltd. All rights reserved

200

Help Topics for HotDocs Developer 10

Specify the Width of Answer Fields in the Interview

You can control the width of an answer field in an interview. This includes controlling column widths if the variable is
repeated in a spreadsheet dialog.
To control the appearance of the variable's answer field

1. At the HotDocs template, edit a variable. (See Edit a Variable.)

2. At the Variable Editor, click the Advanced tab. The dialog box changes to show several advanced options,
including answer field widths.

3. Click the Regular drop-down button and choose one of the following options:
Select Full to have HotDocs use the full width of the dialog pane to display the answer field.
Select Calculated to have HotDocs calculate an approximate width, based on the possible answer length.
Select Exactly and enter the specific number of units you want HotDocs to use for the answer field width.

4. Click the Spreadsheet drop-down button and choose one of the following options:
Select Calculated to have HotDocs calculate an approximate column width, based on the possible length of
the answer and the actual width of the dialog pane.
Select At Least and then enter the minimum number of characters that should determine the column width.
Note:
These options are not available for Computation variables.
The Exactly field width measurement takes into account the width of the entire field, including field borders,
group boxes (on True/False and Multiple Choice variables), and the calendar icon for Date variables. One unit is
about equal to the width of the character 5.
For text fields, Calculated field widths are calculated by looking at the Maximum units setting. If this isn't set,
HotDocs will assume 30 units. For date and number fields, HotDocs figures out the longest field required to
accept the date or maximum number. For multiple choice and true/false answer fields (or group boxes), HotDocs
uses the width required to show all the options. One unit is about equal to the width of the character 5.

Copyright 2010 HotDocs Ltd. All rights reserved

201

Help Topics for HotDocs Developer 10

Control How Answers Appear in the Assembled Document

You can control some of the ways a variable's answer is merged into an assembled document. For example, you can
control the characters that are filled in when you need to "lengthen" an answer. You can also control the text that is
merged if the user chooses not to provide an answer.
Specifically, with the Fill character and Field width fields, you can specify how many characters wide an answer should
be, and which character will be used to fill spaces the answer doesn't use. If the answer is longer than the width of the
field, the entire answer is merged into the document. If the answer is shorter than the field width, HotDocs inserts the
necessary number of fill characters. (The default fill character is a space.) If no answer is given, the minimum number
of spaces doesn't affect the merge field. However, you can specify text you want merged into the document when the
variable is unanswered by entering it in the Unanswered text box. This text will override the Unanswered variable
placeholder users can select at HotDocs Options. (See Tips on Using Unanswered Variable Placeholders.)
The Align answer option lets you align the merged answer, based on the fill characters that are given. For example, if
you select Left, the answer appears first, followed by any fill characters. If you select Right, the answer appears after any
fill characters.
Finally, at times you may need to format the answer using a symbolic font. (For example, perhaps you need to merge a
bar code.) To do this, you can assign a Font at the Variable Field dialog box.
To control how the variable's answer is merged into the assembled document

1. At the template, edit a variable by placing your cursor in the field and clicking the

Variable Field button. The

Variable Field dialog box appears.

2. If it's selected, clear Use defaults. All the merge field properties become active.
3. Click Show Advanced. The dialog box changes to show several advanced options.
4. Select the options that apply, as explained in the following table:
To

Do This

Specify the minimum

number of character
spaces you want the
merge field to use

Type a number in the Field width box, or use the up or down arrows to select a
number

Specify the alignment

of the answer within the
merge field. (For example,
if you are creating a
column of dollar amounts,
you can right-align the
numbers.)

Choose Right or Left from the Align answer drop-down list.

Fill extra spaces in an

answer field with a specific
character (instead of a
space character, which is
the default)

Type a character in the Fill character box.

When aligning Number variables, HotDocs will align the answer in the answer field as
well as in the merge field in the assembled document.

Merge specific text when

Type the text in the Unanswered text box. (See Tips on Using Unanswered Variable
the variable is unanswered Placeholders.)
Format answers using
symbolic character fonts,
such as bar code fonts

Click the Font drop-down button and choose a font from the list.
This is a field-specific property available only in text templates. Additionally, you can
assign this property only at the Variable Field dialog box.

Copyright 2010 HotDocs Ltd. All rights reserved

202

Help Topics for HotDocs Developer 10

To

Do This
Caution:
Make sure your users have the same fonts installed on their computers.

Note:
The Use default option at a Variable Field dialog box controls all of the properties of a variable field. (Fieldspecific properties include variable formats, Multiple Choice merge text, and formatting styles for answer fields.
These options are visible when you click Show Advanced.) This means that you cannot assign a field-specific
property to a field and then assign a default property to the variable component. If you choose one type of
property, all other properties must be the same type.
Where you specify the Advanced options determines where the formatting occurs. If you change them at the
Variable Field dialog box, the changes will apply to that instance of the variable only. If you change the options
at the Advanced tab of the Variable Editor, the changes are used as defaults for every instance of the variable.

Copyright 2010 HotDocs Ltd. All rights reserved

203

Help Topics for HotDocs Developer 10

Add Resource Information to a Variable or Dialog

Sometimes including additional information about questions users are answering during an interview can make it easier
for them to enter the correct answer. To provide this extra information, you can assign resources either to variables or to
dialogs. Users can view this information by viewing the Resource pane during the interview.
By default, resources are displayed as plain text. However, you can use any of the following other formats or programs to
create and display resources. (Click the associated link for instructions on creating the resource type.)
WinHelp
HTML Help
Folio infobase
Custom program
Web page
To add a plain text resource to a variable or dialog

1. Open the variable or dialog to which you want to assign resources. (See Edit a Variable or Edit a Custom Dialog.)
2. Click the Resource tab.
3. Click the Resource type drop-down button and select Plain Text.
4. Type the information in the Text box.
5. Optionally, to use variables in the resource or make text in the resource conditional, enter the variable name,
or enter an IF instruction or expression. (See Use Variables and Scripts in Prompts, Dialog Element Text, and
Resources.)

6. Optionally, select Pop-up to display the information in a What's This? help-style window, rather than a typical
window. (The pop-up window only appears when the user clicks the Resource button next to the answer field.)
During assembly, HotDocs displays the resource text either in the resource pane or in a text-only pop-up window,
depending on your selection. (Pop-up windows stay open only until the user clicks somewhere else.)
Caution:
You cannot use angle brackets with text between them in a plain-text resource (for example, <Your Name>). Instead,
you must use the codes &lt; and &gt; to insert the brackets (for example, &lt;Your Name&gt;). (You can use
brackets, however, if you put a space immediately after the opening angle bracket and immediately before the closing
angle bracket, like this < Your Name >.)
Note:
When editing Multiple Choice variables, you can assign resource text to the entire variable or to individual options. At
the Multiple Choice Variable Editor, click the Resource tab and make your selection at the Resource for drop-down
list.

Copyright 2010 HotDocs Ltd. All rights reserved

204

Help Topics for HotDocs Developer 10

View Relationship Between the Current Component and Other Components

When editing a component (such as a variable or a dialog), you can view a list of other components in the template that
refer to it. You can view this list at the Used In tab of the component editor.
By default, when you first click the Used In tab, HotDocs displays only the dialog or database component to which the
variable is linked, as well as any other dialogs in which the variable is used. To generate a complete list of component
references (including other components that refer to the current component), you can click the List All Components
button. If you want a complete list to be displayed every time you click the Used In tab, you must select Always list all
components when viewing this tab . (Depending on the complexity of your template, you may experience a slight delay
each time you view this list, which is why displaying it is optional.)
To view component relationships

1. At the template or at Component Manager, select the component and edit it. (See Edit a Variable.) The Component
Editor appears.

2. Click the Used In tab. The window changes to show a box listing the dialog(s) (and database components) in which
the component is used.

3. Optionally, to view a list of other components that refer to this component, click List All Components. HotDocs
creates a list of all components that refer to this particular component. (Depending on the complexity of your
template, this may take several seconds.)

4. Optionally, to always view this list of component cross-references each time you view the Used In tab (regardless of
the component you are editing), select Always list all components when viewing this tab.
Note:
The dialog to which the variable is linked is marked with a red arrow. Dialogs that simply use the component are
marked with a plain arrow. See Use the Same Variable or Clause in Two or More Dialogs.
If you make changes to other components in the component file while you have the component editor open, you
can click List All Components again to regenerate the list of used components.

Copyright 2010 HotDocs Ltd. All rights reserved

205

Help Topics for HotDocs Developer 10

Add Notes to Components

As you create components, you may want to include notes about the component. For example, maybe you need to
include information about restrictions you applied to a Number variable, or maybe you need to explain the purpose of the
variable or dialog or how it should be used in the template. To do this, you can add a note to the component. You add
notes at the Notes tab of the component editor. Notes can be viewed by anyone editing the component.
Note:
You can add a comment to a variable field or instruction field so it can be visible by anyone editing the template text.
See Add a Comment to a Variable or Instruction Field for details.
To add development notes to a component editor

1. Edit the component. (See Edit a Variable or Edit a Custom Dialog.) The component editor appears.
2. Click the Notes tab. The view changes to show a multi-line text box.
3. Enter the notes you want associated with the component.

Copyright 2010 HotDocs Ltd. All rights reserved

206

Help Topics for HotDocs Developer 10

Add a Comment to a Variable or Instruction Field

When you insert a variable or instruction in a template, you can add a comment to the insertion field. Comments are
useful when you want to document information about the variable or instruction you are inserting and you want those
comments to be viewable by anyone editing the text of the template.
Comments can also be useful when viewing a markup view of the templatethe comment can describe (in easy-tounderstand terms) the purpose of the field or provide a more reader-friendly name for the field.
Note:
If you want to add comments to a specific component, enter it at the Notes tab of the component editor. See Add
Notes to Components for details.
To add a comment to a variable or instruction field

1. Insert a new variable or edit an existing variable. (See Insert a Variable Field in a Text Template or Edit a Variable.)
The Variable Field dialog box appears. Or, insert a new instruction or edit an existing instruction. The instruction
field dialog box appears.

2. Click Show Advanced. The view expands to show advanced options.

3. Enter your comments in the Comment box.
When you click OK, HotDocs merges the field, with the comments merged after the variable name, like this: Employee
Salary //Calculates biweekly salary based on hourly rate.
Note:
To merge a comment in an END instruction (such as END IF, END REPEAT, OR END SPAN), place your cursor
before the closing chevron, enter two forward slashes (//), and type your comment, like this: END IF //Closing.
If the END instruction contains a Keep Return code ( | ), enter the comment before the return code, like this: END
IF //Closing |.

Copyright 2010 HotDocs Ltd. All rights reserved

207

Help Topics for HotDocs Developer 10

Format an Answer as the Time of Day

You can merge an answer that is formatted as a time of day. To do this, you assign a pattern to a Text variable. During
the interview, users will be prompted to enter the hours and minutes in 12-hour or 24-hour format.
To assign a time pattern to a Text variable

1. Follow the instructions for inserting a variable, selecting Text as the variable type. (See Insert a Variable Field in a
Text Template.)

2. At the Variable Field dialog box, click the

Edit Component button. The Text Variable Editor appears.

3. Click the Pattern drop-down button and choose the time of day pattern you wish to use, based on the following
information:
Choose 99:99 to insert a time in 24-hour format.
Choose 99:99 am to insert a time in 12-hour format. The morning or afternoon designation will not include
periods (for example, am or pm).
Choose 99:99 a.m. to insert a time in 12-hour format. The morning or afternoon designation will include periods
(for example, a.m. or p.m.).
Note:
If your component file was created before the release of HotDocs 2006, you must create the time-of-day pattern. To do
this, type 99:99, 99:99 a.m., or 99:99 a.m. in the Pattern box.

Copyright 2010 HotDocs Ltd. All rights reserved

208

Help Topics for HotDocs Developer 10

Use Pattern Codes to Create a Custom Pattern

HotDocs provides Text variable patterns: a telephone number pattern, time of day patterns, and a U.S. Social Security
number pattern. You can also create your own pattern by typing it directly in the Pattern box (at the Text Variable Editor)
or by clicking the
clicking the

Component Manager button at the template, selecting Text Pattern from the Components list, and

New Component button.

Use the following codes to create patterns. These codes represent the types of characters the user can enter.
Additionally, you can insert hyphens, periods, static text, and so forth with these codes.
Code

What HotDocs Will Require and Insert in the Document

any character

any numeric character

any alphabetic character

uppercase alphabetic character

lowercase alphabetic character

alphanumeric character (9 and A)

hexadecimal character (0-9, A-F, a-f)

Note:
If you need a character in your pattern that HotDocs may interpret as a code, you can force the character to appear as
part of the pattern and not as a code by typing a forward slash (/) and then the character. For example, if you need a
pattern to use the X character, you must place the forward slash before the X so that HotDocs doesn't try to replace
the X with a character the user types.

Copyright 2010 HotDocs Ltd. All rights reserved

209

Help Topics for HotDocs Developer 10

Work with Multiple Choice Options

By default, when you first create a Multiple Choice variable, you have limited space for entering prompts and merge text.
If you require more space, you can click the Options tab and enter the information there. You can also have HotDocs
suggest one of the options as a possible answer for the user.
To provide additional information for option prompts and merge texts

1. Create a Multiple Choice variable. (See Customize a Multiple Choice Variable.)

2. After specifying all the variable properties at the Properties tab of the Multiple Choice Variable Editor, click the
Options tab.

3. Click the Option drop-down button and select the option you want to modify.
4. Perform any of the following optional tasks:
Type a new prompt in the Prompt box or edit the existing prompt. (500-character limit)
Type a new merge text option in the Default merge text box or edit the existing merge text. (1,000-character
limit)
Select Automatically select this option if variable is unanswered when displayed to have HotDocs preselect one or more options for the user. During the interview, the user can either accept this selection, or make
a different selection.
Caution:
Do not use the Automatically select this option if variable is unanswered when displayed if you are using the
Multiple Choice variable in a repeated dialog. Because of the way HotDocs processes dialogs, whenever you default
a value for a variable, there will always be one extra repetition in the dialog. To set a default option for a repeated
Multiple Choice variable, you should use a computation script that conditions the default value. See DEFAULT VAR
TO VALUE for more details.
Note:
You can assign resources to each specific option of a Multiple Choice variable. See the note at the end of Add
Resource Information to a Variable or Dialog.
If you are using a SET instruction, you can set two or more options for a Multiple Choice variable. To do
this, separate each option with a vertical bar (for example, SET MC Variable TO "Option1|Option2|
Option3"). (The Multiple Choice variable must have the Select All That Apply property set.)

Copyright 2010 HotDocs Ltd. All rights reserved

210

Help Topics for HotDocs Developer 10

Specify Merge Text Options as Default or Field-Specific Properties

When you create a Multiple Choice variable, you can control whether merge text options are automatically available each
time you insert the variable, or whether they are only available for a specific instance of the variable. You determine this
by typing your merge text either at the Multiple Choice Variable Editor or at the Variable Field dialog box.
To assign default merge text to a Multiple Choice variable

1. Create or edit a Multiple Choice variable. (See Customize a Number Variable.)

2. At the Multiple Choice Variable Editor, enter your options in the Option column and enter the corresponding
merge text in the Default Merge Text column.

3. Click OK. The merge text options you just entered are now saved with the other component properties.
4. At the Variable Field dialog box for the Multiple Choice variable, select Use default. HotDocs grays all field
properties for the variable.
To assign field-specific merge text to a Multiple Choice variable

1. Create or edit a Multiple Choice variable (see Customize a Multiple Choice Variable and Edit a Variable.)
2. At the Variable Field dialog box, clear Use defaults. HotDocs ungrays the Merge Text column.
3. Enter the merge text that corresponds with the Options you have specified.
Note:
The Use defaults option at a Variable Field dialog box controls all field properties of a variable. (Field-specific
properties include variable formats, Multiple Choice merge text, and formatting styles for answer fields, which are
visible when you click Show Advanced.) This means that you cannot assign a field-specific property to a field
and then assign a default property to the component. If you choose one type of property, all other properties must
be the same type.
When assigning merge text to a variable, you can assign an existing merge text group by clicking the Default
Merge Text column heading and choosing the option from the drop-down list.

Copyright 2010 HotDocs Ltd. All rights reserved

211

Help Topics for HotDocs Developer 10

Copy and Paste Columns in a Multiple Choice Variable Spreadsheet

At times, you may have an Excel spreadsheet or Microsoft Word table that contains the data you want to use as options,
prompts, and merge text for a Multiple Choice variable. Other times you may want to copy this information from a Multiple
Choice variable to a spreadsheet or table. Using the shortcut menu at the Multiple Choice Variable Editor, you can do this.
To copy data from a spreadsheet or table and paste it into the Multiple Choice Variable Editor

1. In the spreadsheet or table, select or highlight the columns and rows that contain the information you want to copy
and copy them. (See the application's help for information on copying.)

2. Edit the Multiple Choice variable. (See Edit a Variable.) The Multiple Choice Variable Editor appears.
3. Place your cursor in the spreadsheet column where you want the new data to be used.
4. Right-click and choose Paste Multiple from the shortcut menu. The data is pasted into the spreadsheet.
To copy data from the Multiple Choice Variable Editor and paste it into a spreadsheet or table

1. In the Multiple Choice Variable Editor, place your cursor in the spreadsheet column where you want to copy the
data.

2. Right-click and choose Copy Column (copies the text from the current cell down for this column only) or Copy All
Columns (copies the text from the current cell down in all columns) from the shortcut menu.

3. In the spreadsheet or table, place your cursor where you want to paste the data and paste it. (See the application's
help for information on pasting.)
Note:
To copy the spreadsheet from one Multiple Choice variable and paste it into another Multiple Choice variable, rightclick on the first cell in the spreadsheet and choose Copy All Columns from the shortcut menu. Then edit the second
variable, place your cursor in the first cell of the spreadsheet, and choose Paste Multiple from the shortcut menu.

Copyright 2010 HotDocs Ltd. All rights reserved

212

Help Topics for HotDocs Developer 10

Name a Group of Merge Text Values

When you add merge text values to a Multiple Choice variable, the list of values you enter becomes a separate HotDocs
component, which can be used in other Multiple Choice variables. By default, HotDocs names this component using all
the values separated by slashes (for example, Boise/Olympia/Salem/Helena/Etc.) Sometimes, the merge text list can be
quite long. In these situations, it may work to assign a different component name (for example, Western States Region) to
the merge text values. You must use Component Manager to assign this new name.
To edit merge text and assign a new name

1. Open Component Manager. (See Open and Close Component Manager.) The Component Manager window
appears.

2. Click the Components drop-down button and select Merge Text. HotDocs displays the different merge text groups
available in your component file.

3. Select a merge text group and click the

Rename Component button. The Rename Component dialog box

appears.

4. Enter a name for the merge text group in the New name box.
5. Click Rename. The component is renamed.

Copyright 2010 HotDocs Ltd. All rights reserved

213

Help Topics for HotDocs Developer 10

Use Variables and Scripts in Prompts, Dialog Element Text, and Resources
You can further customize the interview process by including variables in prompts, in plain text resources, and in dialog
element text. You can also include variables in dialog titles and Multiple Choice option prompts and merge text.
Additionally, you can include IF and REPEAT instructions in plain text resources. You should note, however, that
placing an instruction in a resource will not cause variables used in the instruction to be asked during the interview. If an
instruction relies on a variable being asked in order to be processed, you must make sure those references are resolved
earlier in the interview, before the resource is displayed.
Referring to variables and instructions in other components can provide users with more specific information about the
answer they need to enter during the interview. For example, if you ask for a defendant's name at the beginning of an
interview, whatever name the user enters can appear in a prompt or resource later in the interview.
To customize prompts, dialog element text, dialog titles, plain-text resources, and Multiple Choice merge text
and prompts

1. Edit the component where you want to merge the variable reference or script. (See Edit a Variable or Gather
Questions into a Custom Dialog.)

2. Place your cursor where you want the variable reference (for example, a prompt, title, or dialog element text box),
right-click, and choose Variable Field. The Variable Field dialog box appears.
Note:
To include variable answers in Multiple Choice merge text and prompts, you must either enter the variables at the
Options tab, or you must manually enter the variable references in the options spreadsheet.

3. Enter the variable information and click OK. The variable is merged in the field.
4. Optionally, to enter a script in a plain-text resource, right-click in the Text box and choose IF Field or REPEAT Field
from the shortcut menu, depending on the type of instruction you are inserting.
Note:
You can also merge variable field references by typing double-angle brackets (<< >>), followed by the variable
name or instruction keyword. HotDocs will convert the double-angle brackets to HotDocs chevrons ( ).
If Component Manager is open, you can also drag a variable from Component Manager and HotDocs will
automatically include the chevrons.

Copyright 2010 HotDocs Ltd. All rights reserved

214

Help Topics for HotDocs Developer 10

Use the Script Editor

When writing a computation script, there are several tools you can use to make the process easier.
To use the script editor

1. Edit the script or expression.

2. At the Script or Expression box, complete any of the following tasks:
To

Do This

Have HotDocs
automatically complete
keywords, component
names, and Multiple
Choice options as you type

Place your cursor in the Script box and press Ctrl+Spacebar. HotDocs displays
a list of instruction and expression keywords, constant values (such as month
abbreviations), and components. Type a portion of the keyword, component name, or
Multiple Choice option for which you are searching. As you type, HotDocs filters the
list to show only those keywords that contain the text you have typed. Once selected,
press Enter to merge it into your script.
To keep seldom-used keywords out of the auto-complete list, click the
Options
button and clear Include seldom-used keywords in auto-complete list.

Access just a list of

components

Press the F5 key, select the component, and press Enter.

Access just a list of

keywords

Press Shift+F5, select the keyword, and press Enter.

Display a syntactical hint

Place your cursor inside the keyword and press the F7 key. HotDocs displays a small
of how an instruction or
ToolTip that shows the entire model as well as the type of value it produces, if it's an
expression should be used expression.
Indent matching pairs of IF
and REPEAT instructions
based on the level of their
insertion

Click the

Auto Format button.

Undo (or cancel) an action

you just performed

Click the

Undo button. HotDocs reverses the change you made.

Redo (or re-implement) an

action you just performed

Click the

Redo button. HotDocs reapplies the change you made.

Cut or copy and paste a

selected portion of the
script

Select the portion of the script you want to cut or copy, and then click the
button or the

Copy button. The script is copied to the Clipboard. To paste the

script in a new location, insert your cursor at that location and click the
button.
Find a specific string of
text in the script

Click the

Cut
Paste

Find button and enter your search text in the Find what box. To find the

next instance of the text, click the

Find Next button.

Note:
To find only those instances of text that are complete words, select Find whole
words only. To find only those instances that have the same capitalization as the
text for which you are searching, select Match case.
Find a specific string
of text in the script and

Click the
Find and Replace button. Enter the search text for which you are
searching in the Find what box, and then enter the replacement text in the Replace

Copyright 2010 HotDocs Ltd. All rights reserved

215

Help Topics for HotDocs Developer 10

To

Do This

replace it with another

string of text

with box. Once you have entered the required text, click Replace, Replace All, or
Find Next.
To find and replace script text in a specific block of script, select the block of script
first and then click the
Find and Replace button. At the Find and Replace dialog
box, select Replace only in selected text.

Move your cursor to a

specific location in the
script

Click the
Go To button. This displays the Go To dialog box, where you can enter
the line number or character position of where you want your cursor to move.

Indent or outdent a block

of the script

Select the portion of the script you want to indent or outdent and click the
button or the
indent.)

Indent

Outdent button. (Click repeatedly to increase or decrease the

Cause HotDocs to ignore a Highlight the block of the script you want to comment and click the
Comment
section of the script when
Block button. This puts two forward slashes in front of each line of the script, which
it processes it, or insert a
instructs HotDocs to ignore this section. To uncomment it, highlight the text and click
comment in the script
the
Uncomment Block button.
Match an IF or REPEAT
instruction with its END
IF or END REPEAT
instruction (or vice versa)

Place your cursor inside the instruction, right-click, and select Match IF/REPEAT
from the shortcut menu. (You can also press Ctrl+M.)

Highlight an entire IF
or REPEAT instruction
block (meaning everything
between a beginning
and ending IF/REPEAT
instruction)

Place your cursor inside the instruction, right-click, and select Select IF/REPEAT
from the shortcut menu. (You can also press Ctrl+Shift+M.)

View helpful information

while using the script
editor, including accessing
help topics for the
different instructions and
expressions you can use
in your script

Click the

Customize the way the

script editor works

Click the
Options.)

Insert line breaks and tab

characters in a script

See Use Line Breaks, Paragraph Ends, and Tabs in Computation Scripts.

Assign formatting
characteristics to literal
text strings in a script

Insert the corresponding dot code. See one of the following topics for details:

HotDocs Help button.

Options button and make your changes. (See Change Script Editing

Change Font Properties of Text

Insert Characters in Text Strings
Add Punctuation and Capitalization to Sentences

Note:
To access the script editor toolbar using the keyboard, press F10.
To access help for each instruction or expression, first select the model in one of the lists and then press Ctrl+F1.
Copyright 2010 HotDocs Ltd. All rights reserved

216

Help Topics for HotDocs Developer 10

For an explanation of the HotDocs scripting language, see Understand the HotDocs Scripting Language. For
details on creating a Computation variable, see Customize a Computation Variable. For a list of instruction and
expression models, see Overview: Instruction and Expression Models.

Copyright 2010 HotDocs Ltd. All rights reserved

217

Help Topics for HotDocs Developer 10

Chapter 12: Setting Values for Variables

Automatically Assign Answers to a Variable
Variables normally get their values from the answers users enter during an interview, but sometimes you may want to
assign an answer to a variable instead of allowing the user to specify the answer.
For example, a document might include the address of the client and, in another place, the address of the clients spouse.
Once the clients address has been entered by the user, you could use a SET instruction to automatically fill in the same
address for the spouse, since it will be the same.
SET instructions are inserted using a Computation variable, which you can insert in the template where you want the SET
instruction to take effect.
When you set a variable to a value, you should clear the Save in answer file option for the variable (Advanced tab of the
variable editor). That way, when HotDocs builds the interview, the answer can be set without prompting the user to save
the answer file. (A changed answer file warning like this could be puzzling to users, especially if users don't add or change
any answers in the interview.)
To set a variable to a value

1. Create a Computation variable. (See Customize a Computation Variable.)

2. From the Instruction models list, drag the SET VAR TO VALUE instruction into the Script box.
3. Drag a variable you want to receive the new answer from the Variables list onto the VAR placeholder.
4. Replace the VALUE placeholder with the answer you are assigning to the variable. You can do this by dragging
a variable name from the Variables list, by dragging another instruction or expression into the Script box, or by
entering an actual value. (See Values in SET Instructions for more details about these different types of values.)

5. Click OK after the placeholders have been replaced with actual values.
Note:
You should never SET a variable's value and then cause the variable to be asked later in the template. If you do
this, the value assigned by the SET instruction will always overwrite users' answers. If you want to suggest an
answer for users but allow them to change it, use the DEFAULT instruction. (See DEFAULT VAR TO VALUE
instruction model and Differences Between SET and DEFAULT Instructions.)
To set two or more options for a Multiple Choice variable, separate each option with a vertical bar (for example,
SET MC Variable TO "Option1|Option2|Option3").

Copyright 2010 HotDocs Ltd. All rights reserved

218

Help Topics for HotDocs Developer 10

Chapter 13: Tips on Using and Editing Variables

Tips on Naming Your Variables
How you name variables in your templates depends largely on personal preference or your project guidelines. However,
there are a few rules and suggestions that can make the automation and assembly process easier.

Assign Common, Useful Names

A variable name guides the user in answering each question, so you should choose meaningful names as you design
your templates. A variable name can have up to 50 characters, including letters, numbers, and some symbols. However,
the first character must be a letter. Each variable name must be uniqueeven if the variables are different types, their
names cannot be identical.
Caution:
Do not use all uppercase letters in your variable names. Because HotDocs instruction and expression keywords
use uppercase letters, you may inadvertently use a word that may someday be used as a keyword, which will cause
HotDocs to read your variable name incorrectly. (See Overview: Instruction and Expression Models.)
Finally, there are certain characters you cannot use when naming your components. They are:
. (period)
$ (dollar sign)
" (quotation mark)
: (colon)
[ ] (brackets)
, (comma)
( ) (parenthesis)
% (percent)
The next set of characters can be used only if there is a character other than a space immediately before or after it:
+ (plus)
- (hyphen)
* (asterisk)
/ (forward slash)
> < (greater than and less than signs)
>= <= (greater than or equal to and less than or equal to signs)
= (equals)
!= (does not equal)

Share Answers Between Templates

If you have multiple templates that use the same information, your users can share answers across a set of templates.
To do this, you must create variables with the same names in each template, and users must use the same answer file
when assembling documents. (See Assemble a Text or Form Document and Create a New Answer File.) When the
variable names are identical, the answers in separate documents are also identical. However, variable names are contextCopyright 2010 HotDocs Ltd. All rights reserved

219

Help Topics for HotDocs Developer 10

sensitive and any limits entered for the first variable (such as maximum number of characters, patterns, and decimal
places) must be entered for each duplicate variable or the answers will not flow from one document to the next.
When many variables are shared throughout your template set, you may find it easier to use one component file for
all of your templates. (See Use One Component File for Multiple Templates.) Or, if you want each template to use an
independent component file, copy the contents from the first templates component file into each subsequent component
file. (See Copy Components From One File to Another.) Using either method, you can use variables you have already
created, rather than recreating each variable.

Copyright 2010 HotDocs Ltd. All rights reserved

220

Help Topics for HotDocs Developer 10

How Example Formats are Interpreted

The following describes how answers will be formatted, based on the assigned example format:

Text Variables
Example Format

User's Answer

How Answer is Formatted in Document

like this

Marianne Stevens

marianne stevens

Like this

Marianne Stevens

Marianne stevens

Like This

Marianne Stevens

Marianne Stevens

LIKE THIS

Marianne Stevens

MARIANNE STEVENS

Like a This

our client, Marianne Stevens, is the Plaintiff

in the case

Our client, Marianne Stevens, is the

Plaintiff in the case

Example Format

User's Answer

How Answer is Formatted in Document

09

04

78

78

7,898

7,898

9 1/8

2.3

2 1/4

9,999.00

9214

9,214.00

9214.36

9.214.36

9,999.99999

87.5984

87.5984

9.9

87.6

87.6

9.9.a

287.3

287.3.a

9999

12587

12587

9th

23

23rd

nine

1,278

one thousand two hundred seventy-eight

NINE

1,278

ONE THOUSAND TWO HUNDRED

SEVENTY-EIGHT

Nine Dollars and Twelve

Cents

5.36

Five Dollars and Thirty-Six Cents

ninth

782

seven hundred eighty-second

alpha

12

twelve

Number Variables

(this format is best used

with PN variables)

Alpha
Copyright 2010 HotDocs Ltd. All rights reserved

Twelve
221

Help Topics for HotDocs Developer 10

ALPHA
ordinal

TWELVE
25

twenty-fifth

Ordinal

Twenty-Fifth

ORDINAL

TWENTY-FIFTH

Caution:
Many of these formats will change depending on whether you assign decimal places to the answer. How many decimal
places you assign also affects the outcome.

Date Variables
Example Format

User's Answer

How Answer is Formatted in Document

03 JUN 90

November 6, 2000

06 NOV 00

06/30/90

November 6, 2000

11/06/00

3 June 1990

November 6, 2000

6 November 2000

3rd day of June, 1990

November 6, 2000

6th day of November, 2000

6/3/90

November 6, 2000

11/6/00

June 3, 1990

November 6, 2000

November 6, 2000

June 3rd

November 6, 2000

November 6th

June Third, One Thousand

Nine Hundred Ninety

November 6, 2000

November Sixth, Two Thousand

Sunday

November 6, 2000

Monday

Sunday, June 3, 1990

November 6, 2000

Monday, November 6, 2000

Third day of June, 1990

November 6, 2000

Sixth day of November, 2000

Note:
For additional date formats, please see Additional Date Formats.

True/False Variables
Example Format

User's Answer

How Answer is Formatted in Document

/x

Yes

(nothing)

No

Yes

true

No

false

Yes

No

(nothing)

Yes

yes

No

no

true/false

x/

yes/no

Copyright 2010 HotDocs Ltd. All rights reserved

222

Help Topics for HotDocs Developer 10

Multiple Choice Variables

The format assigned to a Multiple Choice variable depends on whether the variable is set to allow only one selection
(Select One) or multiple selections (Select All That Apply). If set to Select One, the answer will be formatted like Text
variables are formatted. Please see the formats table for Text Variables for a description of each option. If the variable is
set to Select All That Apply, the answer will be formatted like repeated answer lists are formatted. Please see the table
for answer lists for a description of each option.

Computation Variables
Formats for Computation variables depend on the type of computation script you are creating. If you are calculating
numbers, the formats are the same as Number variables. If you are working with text, the formats available are the same
as Text variables.

Answer Lists
To create a list of answers, you can either create a Multiple Choice variable and assign the Select All That Apply
property for it, or you can create a REPEAT instruction. The following list of formats describes the format for each type of
list.
Caution:
When creating lists of answers using a REPEAT instruction, the formats with all capital letters only capitalize the
conjunction in the sentence, for example, the word AND. Individual answers in the list are either merged as the user
types them or as you have specified for each variable.
Example Format

User's Answer

How Answer is Formatted in Document

a, and b

apples and oranges

Multiple Choice: apples, and oranges

Repeated List: apples, and oranges

a, b

apples, oranges, and cherries

Multiple Choice: apples, oranges, cherries

Repeated List: apples, oranges, cherries

a, b and c

apples, oranges, and cherries

Multiple Choice: apples, oranges and

cherries
Repeated List: apples, oranges and
cherries

A, b and c

apples, oranges, and cherries

Multiple Choice: Apples, oranges and

cherries
Repeated List: apples, oranges and
cherries

A, B and C

apples, oranges, and cherries

Multiple Choice: Apples, Oranges and

Cherries
Repeated List: apples, oranges and
cherries

A, B AND C

apples, oranges, and cherries

Copyright 2010 HotDocs Ltd. All rights reserved

Multiple Choice: Apples, Oranges AND

Cherries

223

Help Topics for HotDocs Developer 10

Repeated List: apples, oranges AND

cherries
A, b or c

apples, oranges, and cherries

Multiple Choice: Apples, oranges or

cherries
Repeated List: apples, oranges or cherries

a, b, and c

apples, oranges, and cherries

Multiple Choice: apples, oranges, and

cherries
Repeated List: apples, oranges, and
cherries

a; b; and c

apples, oranges, and cherries

Multiple Choice: apples; oranges; and

cherries
Repeated List: apples; oranges; and
cherries

Copyright 2010 HotDocs Ltd. All rights reserved

224

Help Topics for HotDocs Developer 10

Understand the HotDocs Scripting Language

Learning the Language
As you use HotDocs, you may need to tell HotDocs to perform a particular task, such as insert one template into another,
hide variables in dialogs, or perform some action based on an answer the user provides. Similarly, you may need to add
up several dollar amounts, or find the number of years between two given dates. Or, you may need to search a users
answer for a certain block of text.
To accomplish this, you must use the HotDocs scripting language, which consists of instructions, expressions, operators,
and valuessuch as text, numbers, dates, or answers users enter. To help you learn this language, HotDocs provides
you with instruction and expression models.
Specifically, an instruction model tells HotDocs to perform some sort of function, while an expression model retrieves
a special value. Most models also include placeholders, which you must replace with a value. Possible values include
text strings, number amounts, other models, and HotDocs variables. A model will not work until all its placeholders are
replaced.
In addition to using instructions and expressions, you can use operators to control how the script is processed. Most
operators are common mathematical signs, but there are also Boolean operators such as AND and OR. The operator
AND means the statement to the left and the statement to the right must both be true. The operator OR means either the
statement to the left or the statement to the right must be true. The operator ( ) means to perform the operation between
the parentheses first. (See Use Operators When Scripting.)

Rules for Writing Scripts

Instruction and expression models are designed to help you accurately write scripts. However, there are still certain rules
you must follow, particularly when it comes to replacing placeholders with values. Failure to follow these rules may result
in syntax errors when HotDocs attempts to process the script during assembly.
When using literal values:
Decimal numbers less than one must have a zero before the decimal point (0.125 not .125).
Numbers cannot contain commas (1250 not 1,250).
Dates must be in the form 3 JUN 1990.
Text strings must be inside quotation marks.
To help you format these numbers correctly, use the Enter a Date, Enter a Number, Enter some Text, and Enter True
or False expression models.
When manually typing the script:
Component names must be entered exactly as they appear in the Components list, including capitalization.
Components and operators must be separated by spaces.
Operators must be entered exactly as they appear in the Operators list, including capitalization.
Variables used inside a literal text string (or between quotation marks) in a computation must be inside chevrons
( ). If the variable name is not inside chevrons, the variable namenot the variable's valuewill be merged
as the answer. (For example, "Employee Name must wait Number of Months months before
applying.")
Keywords, such as TRUE, FALSE, AND, END IF, and so forth, must be in all capital letters.
Only TRUE or FALSE can be used for a true/false value.
If you want the computation to return a combination of text, variables, and values, you must concatenate (or join) the
data with the Add ( + ) operator. Otherwise, HotDocs returns only the last piece of text, variable, or value.
Copyright 2010 HotDocs Ltd. All rights reserved

225

Help Topics for HotDocs Developer 10

When using the RESULT expression, you must first set the computation to a value. If the computation will return
text, set it to a specific value by typing text inside quotation marks at the start of the script. (To set a text computation
to an empty value, type nothing between the quotation marksnot even a space.) If the computation will return a
number, set it to a value by typing a number at the very beginning of the script. (To set a number computation to
nothing, type 0 (zero).)

Writing the Script

There are three places in HotDocs where you can write scripts: The Computation Editor, the Script tab of the Dialog
Editor, and the Expression box of the IF Field dialog box. Each of these places provides you with the tools you need to
write the script. Which tools you use, however, depends on personal preference, as well as your skill level.
If you are learning the scripting language, it is suggested that you select and drag instructions and expressions from the
models lists to the Script box. You can also drag operators and components from their respective lists into the Script box.
If there are placeholders, replace them by dragging components or other models onto them. To correctly format literal
values (such as text, numbers, dates, and true/false values) use the Enter... expression models.
If you prefer to use the keyboard rather than the mouse, press the Tab key to move from one field in the dialog box to
the next. Use the arrow keys to select specific components, operators, and models, and use the Insert key to bring the
selected element into the Script box. To replace placeholders in the script, insert your cursor in the placeholder text and
then locate the value you want to replace it with in the lists below and press the Insert key.
Once you become familiar with the instructions and expressions, you can type your scripts directly in the Script or
Expression box. To ensure you use the correct instruction and expression keywords and component names, you can
access lists of these things using keyboard shortcuts and other options available in the script editor. When you do this,
HotDocs displays an auto-complete list from which you can choose the instruction or expression you are typing. For
complete instructions, See Use the Script Editor.

Copyright 2010 HotDocs Ltd. All rights reserved

226

Help Topics for HotDocs Developer 10

Understand How Component Titles and Prompts are Used

In HotDocs, you can assign titles to different components, including variables, dialogs, clauses, and databases. Titles
are used in place of component names, which, when used in the context of an interview, may not make much sense to
the user. (For example, a component may be named Client Birth Date DA, but the name you want users to see in the
interview is Client's Birth Date.)
How HotDocs uses these titles, especially for components that may also have a prompt, depends on where the
component appears in the interview. Following is a description of the components, where they are used in the interview,
and the order in which titles, prompts, and names are used when identifying the component.
For example, say you have a Text variable that is used in a dialog. The first property HotDocs will try to use as the
question for the Text variable in the dialog is the prompt itself. If no prompt is specified, it will use the title. If no title is
given, it will use the variable name.
Type of Component

Where Used in Interview

Order in Which Properties are Used

Variable (used or not used

in a custom dialog)

Answer field in the dialog pane

Prompt / Title / Variable name

Variable (used in a custom

dialog)

Text in the column heading of a

Prompt / Title / Variable name
spreadsheet (including in an answer source
column)

Variable (not used in a

custom dialog)

Dialog title in the interview outline or dialog

title in the dialog pane title bar

Title / Prompt / Variable name

Variable (used or not used

in a custom dialog)

Reference in a Question or Answer

Summary

Prompt / Title / Variable name

Clause (referenced in a
clause library)

Clause title in the clause library

Title / Clause name

Clause (referenced using an Dialog title in interview outline or dialog title

IF instruction in a template; in the dialog pane title bar
is not used in a custom
dialog)

Title / Prompt / Clause name

Clause (referenced using an Answer field in the dialog pane

IF instruction in a template;
is not used in a custom
dialog)

Prompt / Title / Clause name

Database component

Dialog title in interview outline or dialog title

in dialog pane title bar

Title / Component name

Database component

Table in dialog pane

Prompt / Title / Component name

Dialog (nonrepeated)

Dialog title in interview outline or dialog title

in dialog pane title bar

Dialog title / Dialog name

Dialog (repeated as series)

Dialog title in interview outline

Repeated series label / Dialog title / Dialog

name

Dialog (repeated as series)

Dialog title in dialog pane title bar

Dialog title / Dialog name

Dialog (repeated as
spreadsheet)

Dialog title in interview outline or dialog title

in dialog pane title bar

Dialog title / Dialog name

Copyright 2010 HotDocs Ltd. All rights reserved

227

Help Topics for HotDocs Developer 10

Note:
Remember that when variables are linked to or used in dialogs, the text that appears in the interview outline and
in the dialog pane title bar comes from the dialog, not the variable.
You should always test assemble your template to make sure these combinations of titles, prompts, and variable
names make sense for the interview. See Overview: Test HotDocs Templates.

Copyright 2010 HotDocs Ltd. All rights reserved

228

Help Topics for HotDocs Developer 10

Chapter 14: Creating and Using Dialogs

Overview: Create Your Own Dialogs
When you insert variables in your templates, HotDocs automatically creates a default dialog (or a question window) for
each variable. When the user assembles the document, HotDocs presents each of these individual dialogs in the order
the variables are used in the template.
However, if you want to have more control over the information-gathering process, you can create custom dialogs. To do
this, you group related questions together and add text (and other design elements) to the dialog to help the user provide
correct answers. You can also control the order in which custom dialogs appear during the interview.
When you add a variable to a dialog, HotDocs creates a link between the variable and the dialog. When an answer is
needed for the variable during the interview, HotDocs displays the linked dialog instead of displaying the variable by itself.
When creating dialogs, you can add visual elements to the dialog, such as lines, graphics, and white space. You can also
include links to computations, applications, or even a Web page. All of these tools give your users a better experience
answering questions in the dialog.
The following shows the Dialog Editor with a list of the variables that have been linked to it.

Copyright 2010 HotDocs Ltd. All rights reserved

229

Help Topics for HotDocs Developer 10

During the interview, HotDocs displays the dialog and allows the user to enter answers.

Copyright 2010 HotDocs Ltd. All rights reserved

230

Help Topics for HotDocs Developer 10

You can also add scripts to your dialogs, which let you conditionally hide or dim variable questions and require that certain
questions be answered. You can use text from a Windows or HTML Help file, Folio Infobase, custom program, or Web
page as a resource for a dialog. You can also create an answer sourcean answer file from which a user can select
existing answers during the interview. Finally, you can change the width and placement of answer fields in the dialog.

Copyright 2010 HotDocs Ltd. All rights reserved

231

Help Topics for HotDocs Developer 10

Gather Questions into a Custom Dialog

By default, when HotDocs displays variables in a HotDocs interview, each variable is shown in a dialog by itself. This
dialog is called a default dialog. While this approach may be sufficient for some, you may want to group related variables
and present them in a custom dialog. Grouping questions together makes it easier for users to answer questions in the
interview because there are fewer dialogs to navigate through. Additionally, sometimes viewing questions in context
makes it easier to understand what information is required.
To add variables or clauses to a custom dialog

1. At the HotDocs template, click the

Component Manager button. The Component Manager window appears.

2. Select Dialogs from the Components drop-down list. This limits the list of components to show only the dialogs
used in the template.

3. Click the

New Component button. The Dialog Editor appears.

4. At the Properties tab, type a name in the Dialog name box.

5. Select the components you want from the Components list and drag them to the Contents box.
Note:
Click the Components drop-down button and select a component type to limit the list of components you
are viewing. To use a component you havent created yet, select a component type and click the
Component button.

New

6. Optionally, to change the order variables are asked in the dialog, select a variable and drag it up or down in the list.
As you do this, HotDocs displays a horizontal bar showing you where the variable will be placed when you release
the mouse.

7. Once all the variables are added, you can perform any of the following optional tasks:
To

Do This

Specify a prompt for the

dialog that is different from
the dialog name

Type the desired prompt in the Title box. The title is what will be used in the interview
outline and in the dialog title bar during the interview.
Dialog titles are useful when the dialog name you have assigned wouldn't make
sense to the user.
To make the title bold, italic, or underlined, insert the opening dot code for the style
you need. Do not include a closing dot code. (See Change Font Properties of Text.)

Add other items to a

dialog, such as text,
graphics, links, or design
elements

Click on the Create New Dialog Element icon and drag it to the Contents list. The
Dialog Element Editor opens where you can choose to add text, lines or spaces,
a link that runs a computation, a link that launches an application, a hyperlink, or a
graphic.

Choose how you want

to display a dialog if it's
repeated

Click the Style drop-down button and choose a repeated display option: Repeated
Series or Spreadsheet. (See Create a REPEAT Instruction to Gather a List of
Answers.)
To assign a label to the entire repeated series of dialogs, enter the label in the Label
box. (See Customize REPEAT Titles.)

Customize how the dialog Click the Options tab and make your selections. (See Change a Dialog's Options.)
displays variable questions
and control how the dialog
functions

Copyright 2010 HotDocs Ltd. All rights reserved

232

Help Topics for HotDocs Developer 10

To

Do This

Make the contents of your

dialog dynamic based on
answers a user enters

Click the Script tab and create a script. (See Use Scripts to Add Power to Your
Dialogs.)

Provide helpful information

about the dialog for the
user

Click the Resource tab and enter the resource text. The information you enter here
appears in the resource pane during the interview. (See Add Resource Information to
a Variable or Dialog.)

Have two or more

variables appear side by
side in the dialog

Click the Layout tab and drag variables to the line you want. (See Change the
Layout of Variables in a Dialog.)

View a list of all

components that use this
dialog

Click the Used In tab. (See View Relationship Between the Current Component and
Other Components.)

Enter notes about the

component, such as an
explanation about why the
component was created or
how it should function in
the interview

Click the Notes tab and enter your comments. (See Add Notes to Components for
details.)

See how your dialog looks

and works without closing
the Dialog Editor

Click Test. A test assembly window appears, showing the current dialog. (See Test a
Custom Dialog.)
If you want to make changes to the dialog, make your changes in the Dialog Editor
(without closing the assembly window) and click Update. When you are satisfied with
your changes, close the test assembly window and click OK.

Once your dialog is created, you can rearrange components within the dialog by dragging them up or down in the
Contents list. You can remove all components by dragging them back to the Components list. To edit a component,
double-click it (at either the Contents box or the Components list).
By default, HotDocs asks variables and dialogs in the order it "reads" them in the template (top-to-bottom, left-to-right).
If you want a dialog to be asked at a specific place in the template, you must use an ASK instruction. See Control When
Your Dialogs Appear for details.
Caution:
When you add variables to a dialog, the variables and the dialog become linked and used variables appear grayed in
the Components list of the Dialog Editor. Be careful when adding an already-linked variable to a different dialog. If
you don't first clear the Link variables to this dialog option (Options tab), you will remove the variable from the first
dialog. (See Use the Same Variable or Clause in Two or More Dialogs.)
Note:
If you don't link variables to a dialog, the variables will appear in their own default dialogs in the interview. If you
assign titles to the variables, that title will be used in the interview outline and in the dialog title bar. Otherwise, the
variable prompt or name will be used.
You can control the width of answer fields in a dialog. See Specify the Width of Answer Fields in the Interview.
To save your changes to a dialog without closing the Dialog Editor, click Save.
To move components between the Components and Contents list using the keyboard, use the Left and Right
arrow keys. To move components within the Contents list, press Alt+Up Arrow or Alt+Down Arrow.

Copyright 2010 HotDocs Ltd. All rights reserved

233

Help Topics for HotDocs Developer 10

Edit a Custom Dialog

Once you have created a dialog, you can use Component Manager to make changes to it at any time.
To edit a dialog

1. At the HotDocs template, click the

Component Manager button. The Component Manager window appears.

2. Select Dialogs from the Components drop-down list. This limits the list of components to show only the dialogs
used in the component file.

3. Select the dialog you want to edit and click the

Edit Component button. The Dialog Editor appears, showing the

contents and properties of the dialog.

4. Make changes to the dialog. (See Change a Dialog's Options for ideas.)
Note:
To edit a dialog without using Component Manager, make sure your cursor isn't in a variable field. Then, click the
Edit Component button in the HotDocs toolbar. Select Dialog and click the Component drop-down button.
Choose the dialog you want to edit from the list.

Copyright 2010 HotDocs Ltd. All rights reserved

234

Help Topics for HotDocs Developer 10

Change a Dialog's Options

You can make several changes to further customize your dialog, such as:
Put True/False variables, clauses, or inserted dialogs into single-selection or multiple-selection groups.
Decide where variable prompts appear in relation to answer fields.
Make sure variables grouped in a dialog are asked only if the dialog is specifically ASKed.
Make sure a dialog always appears, no matter how the user navigates through an interview.
Specify an answer source to be used with the dialog.
You can specify all of these options at the Options tab of a custom dialog
To change dialog options

1. Open a dialog for editing. (See Edit a Custom Dialog.) HotDocs displays the Dialog Editor.
2. Click the Options tab. The window changes to show several custom options.
3. Perform any of the following tasks:
To

Do This

Place groups of True/False

variables together, clause
components together, or
child dialogs together so
users can choose only one
option

Choose Select One from the Selection grouping drop-down list.

Place groups of True/False

variables together, clause
components together, or
child dialogs together so
users can choose from
several options

Choose Select All That Apply from the Selection grouping drop-down list.

Add a None of the Above

option to a single-selection
or multiple-selection group

Select None of the Above.

Choose the visual

relationship you want
between variable prompts
and answer fields

Select an option from the Prompt position drop-down list:

When HotDocs processes a dialog that has a selection grouping, it automatically

marks all options as false, which tells HotDocs those variables are answered. (Of
course, the user can change this by selecting an option.) The user viewing the dialog,
however, sees no visual cue that these options are false (and therefore answered),
so they might not understand why the answered status changes in the interview
outline. Because of this, you should always select None of the Above, which adds a
None of the Above option to the list. This way, the dialog can appear answered, even
if the user doesn't select an option.

When HotDocs processes a dialog that has a selection grouping, it automatically

marks all options as false, which tells HotDocs those variables are answered. (Of
course, the user can change this by selecting an option.) The user viewing the dialog,
however, sees no visual cue that these options are false (and therefore answered),
so they might not understand why the answered status changes in the interview
outline. Because of this, you should always select None of the Above, which adds a
None of the Above option to the list. This way, the dialog can appear answered, even
if the user doesn't select an option.

Note:
Providing a None of the Above option for your users gives them the chance to
answer a question without selecting any of the options you have presented.

Above places the prompt above the answer field.

Left places the prompt to the left of the answer field. The length of the prompt
text can be from 12 to 50 units, as specified in the Maximum units box. If the
prompt length exceeds this, the prompt will wrap to the next line.

Copyright 2010 HotDocs Ltd. All rights reserved

235

Help Topics for HotDocs Developer 10

To

Do This
Automatic places the prompt according to the values you specify in the
Maximum units box. Prompts that are shorter than this number will be placed
to the left of the answer field. Prompts that are longer are placed above the
answer field.
To right-align prompts, select Right-align prompts.
Note:
One unit is about equal to the width of the character 5.
When variables are placed side-by-side in a dialog, prompts will always
appear above the answer field.

Enter a prompt for a child

Enter the new prompt in the Prompt to use when displayed as child dialog box.
dialog button on the parent
The prompt you specify here will be used in the dialog onlythe dialog's name or title
dialog
will still be used in the interview outline and in the dialog itself.
(By default, child dialogs
appear on parent dialogs
as links with the child
dialog's name as the
prompt. Specifying a
prompt lets you provide
more instructive text
for accessing and then
answering questions in the
child dialog.)
Keep child dialogs from
appearing as buttons on
the parent dialog

Clear Show buttons for child dialogs. HotDocs removes any representation of
the child dialog from the parent dialog. The only reference to the dialog will be in the
interview outline, and users must manually click on the dialog to answer questions
within it.

Keep the dialog from

being asked if none of
the variables in the dialog
are active (or used by the
document)

Select Hide this dialog when all variables are inactive. (See Automatically Disable
Irrelevant Variables in Interviews for details.)

Make sure the dialog

is askedeven if it has
already been answered
when a user clicks the
Next Unanswered button

Select Always stop at this dialog when moving to next unanswered.

Control whether dialogs

are asked automatically

Clear Ask automatically. (See Control Whether Dialogs are Asked Automatically.)

Cause variables in
the dialog to be asked
separately, rather than
together in a dialog

Clear Link variables to this dialog. If this option is cleared and the dialog is not
specified in an ASK instruction, the variable questions are asked individually.

This option is also useful when you have a dialog that contains dialog element text
only. By selecting this option, you can ensure that users navigating the interview
using the Next Unanswered button will still see this dialog. (See Using a Dialog to
Display Only Dialog Element Text.)

Copyright 2010 HotDocs Ltd. All rights reserved

236

Help Topics for HotDocs Developer 10

To

Do This

Use one variable in two or

more dialogs

Clear Link variables to this dialog. (See Use the Same Variable or Clause in Two
or More Dialogs.)

Identify an answer source

file from which the user
can choose answers

Either type the name of an answer source file in the Answer source box, or click the
drop-down button and select an existing answer source. (See Suggest an Answer
Source for Dialogs.)
Click the Map Variables button to link an existing answer source to a dialog where
the variable names are not the same. (See Link an Existing Answer Source to Other
Dialogs or Link a Dialog to a List Gathered by a Repeated Dialog.)
You can also link an answer source to a Time Matters Record or an Outlook Contacts
list

Copyright 2010 HotDocs Ltd. All rights reserved

237

Help Topics for HotDocs Developer 10

Add Resource Information to a Variable or Dialog

Sometimes including additional information about questions users are answering during an interview can make it easier
for them to enter the correct answer. To provide this extra information, you can assign resources either to variables or to
dialogs. Users can view this information by viewing the Resource pane during the interview.
By default, resources are displayed as plain text. However, you can use any of the following other formats or programs to
create and display resources. (Click the associated link for instructions on creating the resource type.)
WinHelp
HTML Help
Folio infobase
Custom program
Web page
To add a plain text resource to a variable or dialog

1. Open the variable or dialog to which you want to assign resources. (See Edit a Variable or Edit a Custom Dialog.)
2. Click the Resource tab.
3. Click the Resource type drop-down button and select Plain Text.
4. Type the information in the Text box.
5. Optionally, to use variables in the resource or make text in the resource conditional, enter the variable name,
or enter an IF instruction or expression. (See Use Variables and Scripts in Prompts, Dialog Element Text, and
Resources.)

6. Optionally, select Pop-up to display the information in a What's This? help-style window, rather than a typical
window. (The pop-up window only appears when the user clicks the Resource button next to the answer field.)
During assembly, HotDocs displays the resource text either in the resource pane or in a text-only pop-up window,
depending on your selection. (Pop-up windows stay open only until the user clicks somewhere else.)
Caution:
You cannot use angle brackets with text between them in a plain-text resource (for example, <Your Name>). Instead,
you must use the codes &lt; and &gt; to insert the brackets (for example, &lt;Your Name&gt;). (You can use
brackets, however, if you put a space immediately after the opening angle bracket and immediately before the closing
angle bracket, like this < Your Name >.)
Note:
When editing Multiple Choice variables, you can assign resource text to the entire variable or to individual options. At
the Multiple Choice Variable Editor, click the Resource tab and make your selection at the Resource for drop-down
list.

Copyright 2010 HotDocs Ltd. All rights reserved

238

Help Topics for HotDocs Developer 10

Use Scripts to Add Power to Your Dialogs

You can create scripts for your dialogs that allow you to hide or dim variable questions, require certain questions be
answered before the user can proceed to the next dialog, and assign predetermined values to variables. You can also use
scripts to make variables within a dialog conditionaljust as they are in the underlying template text.
Caution:
Before creating a dialog script, see Special Instructions for Dialog Scripts as well as Understand the HotDocs Scripting
Language. Dialog scripts should only change the appearance of variables in a dialogthey should not be used to
compute answers.
To create a script for a dialog

1. Open a dialog for editing. (See Edit a Custom Dialog.) HotDocs displays the Dialog Editor.
2. Click the Script tab. The window changes to show scripting options.
3. Enter your dialog script. (See Use the Script Editor and Special Instructions for Dialog Scripts.)
Once you have written your script, you can make sure it works correctly by testing the dialog. The dialog appears just as it
will during regular assembly. (See Test a Custom Dialog.)
Note:
At the Script tab, the Components list shows the components (including dialog element components) in the order
they are used in the dialog. This makes it easier to see exactly which components you can use in the script.

Copyright 2010 HotDocs Ltd. All rights reserved

239

Help Topics for HotDocs Developer 10

Change the Layout of Variables in a Dialog

You can change the appearance of dialogs, including placing variables side by side in the dialog and changing the width
of variables already placed side by side. Changes can only be made in dialogs that have the Regular and Repeated
Series styles applied. You cannot change the layout of Spreadsheet dialogs.
To place variables side by side on a dialog

1. Open a dialog for editing. (See Edit a Custom Dialog.) HotDocs displays the Dialog Editor.
2. Click the Layout tab. The window changes to show icons representing each component in the dialog.
3. Click a component icon and drag it to another location in the window.
When you do this, HotDocs displays either a vertical or a horizontal bar, which tells you where the variable will be
moved when you release the mouse button. A vertical bar shows that the variable will be placed to the right or left of
variables already on that line. A horizontal bar shows that the variable will be placed above or below that line. You
can place up to three variables on the same line.

4. Optionally, click Test. HotDocs displays the variables in a test assembly window. (You can leave this window open
and return to the Dialog Editor to make additional changes, which are immediately updated in the window.)
Note:
If you place only two components on the same line, you can make one of the components wider than the other by
right-clicking on the component and selecting Wide from the shortcut menu. To further adjust the width of answer
fields, at the Variable Editor, click the Advanced tab and make your changes. (See Specify the Width of Answer
Fields in the Interview for further instructions.)
To edit a component or remove it from the dialog, right-click on the component and select Edit or Remove from
the shortcut menu.
When two or more components appear on the same line, the prompts will automatically appear above the answer
fieldyou cannot specify a different prompt alignment.

Copyright 2010 HotDocs Ltd. All rights reserved

240

Help Topics for HotDocs Developer 10

View Relationship Between the Current Component and Other Components

When editing a component (such as a variable or a dialog), you can view a list of other components in the template that
refer to it. You can view this list at the Used In tab of the component editor.
By default, when you first click the Used In tab, HotDocs displays only the dialog or database component to which the
variable is linked, as well as any other dialogs in which the variable is used. To generate a complete list of component
references (including other components that refer to the current component), you can click the List All Components
button. If you want a complete list to be displayed every time you click the Used In tab, you must select Always list all
components when viewing this tab . (Depending on the complexity of your template, you may experience a slight delay
each time you view this list, which is why displaying it is optional.)
To view component relationships

1. At the template or at Component Manager, select the component and edit it. (See Edit a Variable.) The Component
Editor appears.

2. Click the Used In tab. The window changes to show a box listing the dialog(s) (and database components) in which
the component is used.

3. Optionally, to view a list of other components that refer to this component, click List All Components. HotDocs
creates a list of all components that refer to this particular component. (Depending on the complexity of your
template, this may take several seconds.)

4. Optionally, to always view this list of component cross-references each time you view the Used In tab (regardless of
the component you are editing), select Always list all components when viewing this tab.
Note:
The dialog to which the variable is linked is marked with a red arrow. Dialogs that simply use the component are
marked with a plain arrow. See Use the Same Variable or Clause in Two or More Dialogs.
If you make changes to other components in the component file while you have the component editor open, you
can click List All Components again to regenerate the list of used components.

Copyright 2010 HotDocs Ltd. All rights reserved

241

Help Topics for HotDocs Developer 10

Add Notes to Components

As you create components, you may want to include notes about the component. For example, maybe you need to
include information about restrictions you applied to a Number variable, or maybe you need to explain the purpose of the
variable or dialog or how it should be used in the template. To do this, you can add a note to the component. You add
notes at the Notes tab of the component editor. Notes can be viewed by anyone editing the component.
Note:
You can add a comment to a variable field or instruction field so it can be visible by anyone editing the template text.
See Add a Comment to a Variable or Instruction Field for details.
To add development notes to a component editor

1. Edit the component. (See Edit a Variable or Edit a Custom Dialog.) The component editor appears.
2. Click the Notes tab. The view changes to show a multi-line text box.
3. Enter the notes you want associated with the component.

Copyright 2010 HotDocs Ltd. All rights reserved

242

Help Topics for HotDocs Developer 10

Use the Same Variable or Clause in Two or More Dialogs

When you add a variable to a dialog, HotDocs creates a link between the two so that when HotDocs processes the
variable during the interview, it knows to display the dialog to which the variable is linked. However, this linking limits your
ability to use a variable in more than one dialog. To use a variable in two different dialogs, one of the dialogs must not be
linked to its variables.
One reason you may want to include variables in two or more dialogs is so you can have two different versions of a
dialog, only one of which should be displayed, based on answers a user enters. Otherwise, when you add the variable
to the second dialog, it is automatically removed from the first dialog. This is because a variable can be linked to only
one dialog. You can, however, specify an option that allows the variables and clauses in that dialog to be used in another
dialog.
To use the same variable or clause in two or more dialogs

1. Open a dialog for editing. (See Edit a Custom Dialog.) HotDocs displays the Dialog Editor. (At the Components list
of the Dialog Editor, variables and clauses that are already linked to other dialogs are grayed out.)

2. Click the Options tab. The window changes to show several custom options.
3. Clear Link variables to this dialog.
Caution:
If you clear this option for a dialog, you must specifically ASK the dialog in the template or else it will not be displayed
during the interview. (See Control Whether Dialogs are Asked Automatically.)

Copyright 2010 HotDocs Ltd. All rights reserved

243

Help Topics for HotDocs Developer 10

Control Whether Dialogs are Asked Automatically

You can control whether a dialog is asked automatically during an interview. You can do this by selecting an option at the
Options tab of the Dialog Editor.
Dialogs that are not asked automatically must be asked using an ASK instruction. (See Control Whether Dialogs are
Asked Automatically.)
By default, HotDocs asks a dialog automatically: 1) when the dialog has not been asked before in the interview, and 2)
when a variable to which the dialog is linked is asked automatically. Also, a dialog will be asked automatically when it is
used in a REPEAT instruction. (See How Variables and Dialogs Are Asked for details on how variables and dialogs are
asked.)
One example of why clearing this option may be useful is when you've created a list of answers by merging two different
lists together (see WHILE EXPRESSION; END WHILE). When doing this, you often need to merge the new list into the
document using a third repeated dialog. Since you've already gathered all the applicable answers, you don't want this
repeated dialog to be asked.
To specify an option that controls when a dialog is asked

1. Edit a custom dialog. (See Edit a Custom Dialog.) The Dialog Editor appears.
2. Click the Options tab. The window changes to show several custom options.
3. Clear Ask automatically.
Note:
This option replaces the need for using ASK NONE / ASK ALL instructions. However, instructions for using them are
still available.

Copyright 2010 HotDocs Ltd. All rights reserved

244

Help Topics for HotDocs Developer 10

Chapter 15: Inserting Dialog Elements in Dialogs

Add Text to Your Dialogs
You can add text to a dialog to guide the user in answering questions. Dialog text can be inserted above or below
variables or other items in the dialog.
To add text to a dialog

1. Open a dialog for editing. (See Edit a Custom Dialog.) HotDocs displays the Dialog Editor.
2. At the Properties tab of the Dialog Editor, click the

Dialog Element button and drag it to the Contents list. The

Dialog Element Editor appears.

3. Enter a name for the component in the Dialog element name box, or select Generate name automatically, which
allows HotDocs to name the component.

4. In the Style group, make sure Text is selected.

5. In the Display text box, enter the text you want to appear in the dialog.
6. Optionally, to assign font properties to the prompt text (such as bold or underline), enter a formatting dot code. (See
Overview: Dot Codes.)

7. Optionally, if the dialog is repeated as a spreadsheet, click the Options tab and select one of the following options:
Spreadsheet view only displays the text on the dialog only when users view the spreadsheet and not when
they edit individual rows in the spreadsheet.
Edit Row view only displays the text on the dialog only when users edit individual rows of the spreadsheet. No
text will appear when they are viewing the spreadsheet.

8. Move the dialog element within the dialog by dragging it up or down in the Contents list.
Note:
To edit the dialog element, double-click it in the Contents list. To remove the element, drag it back to the
Components list.
You can use a dialog to display just text and no variables. For example, you may want to include a dialog that
contains only instructions for completing the interview. See Using a Dialog to Display Only Dialog Element Text.
You can customize dialog element text based on users' answers by including variables and other scripting
instructions in the element text. See Use Variables and Scripts in Prompts, Dialog Element Text, and Resources
for details.

Copyright 2010 HotDocs Ltd. All rights reserved

245

Help Topics for HotDocs Developer 10

Add the Ability to Launch an Application from a Dialog

At times, you may want your users to launch a separate application while answering questions in a specific dialog. You
can add an option to a dialog that lets users either click a hyperlink or click a button to start the application.
For example, perhaps your users may need to calculate a number before entering their answer in an interview. You can
provide a link on the dialog that launches the Windows Calculator so they can calculate their answer.
To place the link on a dialog

1. Open a dialog for editing. (See Edit a Custom Dialog.) HotDocs displays the Dialog Editor.
2. At the Properties tab of the Dialog Editor, click the

Dialog Element button and drag it to the Contents list. The

Dialog Element Editor appears.

3. Enter a name for the component in the Dialog element name box, or select Generate name automatically , which
allows HotDocs to name the component.

4. In the Style group, select Application link.

5. In the Executable file box, click the

Browse button and locate the application's .EXE file.

6. In the Link text box, enter the text you want to use as the link.
7. Click the Options tab and select how you'd like the link to appear on the dialog, based on the following information:
In the Display as group, select whether the link should be a Button or Hyperlink. (If you select Button, you
can specify a custom button size in the Button size group.)
If you select Hyperlink, select whether the link should include text, an image, or both in the Display using
group. (Enter the name of the image file in the Image file box if you select Image.)
In the Display in group, select Desktop interviews. (Application links are not allowed in HotDocs Server
interviews.)

8. Click OK. The Dialog Element Editor is closed.

9. Drag the component up or down in the Contents list, depending on where you want the hyperlink placed on the
dialog.
Note:
When specifying the executable file, if you include just the program's file name and not a folder path, HotDocs
looks for the executable file in the same folder as the template. If it doesn't find the file there, it looks in the
HotDocs program folder. Finally, if the file is still not found, HotDocs uses information from the Windows Path
Environment variable to search for it.
You may include command-line options in the file path of the executable, for example, "C:\Windows\Notepad.exe"
c:\Temp\MyTextFile.txt.

Copyright 2010 HotDocs Ltd. All rights reserved

246

Help Topics for HotDocs Developer 10

Add a Link to a Dialog That Runs a Computation

You can add a link that processes a Computation variable to a HotDocs dialog. This may be useful if you want users to
execute a calculation or other type of command and have the result immediately take effect.
To add a button to a dialog that runs a Computation variable

1. Open a dialog for editing. (See Edit a Custom Dialog.) HotDocs displays the Dialog Editor .
2. At the Properties tab of the Dialog Editor, click the

Dialog Element button and drag it to the Contents list. The

Dialog Element Editor appears.

3. Enter a name for the component in the Dialog element name box, or select Generate name automatically , which
allows HotDocs to name the component.

4. In the Style group, select Script link.

5. In the Computation box, enter the name of the Computation variable you want to run. (Click the

New

Component button to create or edit the computation.)

6. In the Link text box, enter the text you want to use as the link.
7. Click the Options tab and select how you'd like the link to appear on the dialog, based on the following information:
In the Display as group, select whether the link should be a Button or Hyperlink. (If you select Button, you
can specify a custom button size in the Button size group.)
If you select Hyperlink, select whether the link should include text, an image, or both in the Display using
group. (Enter the name of the image file in the Image file box if you select Image.)
Caution:
Any images displayed in a browser-based (HotDocs Server) interview must be located in the same folder
as the template. Also, bitmap (.BMP) files are not supported in browser-based interviews. Additionally,
Silverlight does not support all possible color depths that are included in the PNG specification. Specifically,
gray scale and 64-bit true color are not supported in Silverlight.
In the Display in group, select whether the link should appear when the dialog is displayed in Desktop
interviews, Server interviews, or both.

8. Click OK. The Dialog Element Editor is closed.

9. Drag the component up or down in the Contents list, depending on where you want the hyperlink placed on the
dialog.

Copyright 2010 HotDocs Ltd. All rights reserved

247

Help Topics for HotDocs Developer 10

Add a Hyperlink to a Dialog

You can include a hyperlink on a dialog, which can point to any URL. When the user clicks the hyperlink, the Web page
will open. This may be useful if you need users to refer to a specific Web page when answering questions in a dialog.
One reason you may want to add a hyperlink to a dialog is to let HotDocs Server users retrieve answers from a database.
For example, the site administrator can create a Web page at the specified URL that presents information from a
database and allows users to select the appropriate data. Once the data is selected, the Web page is closed and the
answer fields in the dialog are filled with answers from the database. If you create such a Web page, it will only be
accessible in HotDocs Server.
To add a hyperlink to a dialog

1. Open a dialog for editing. (See Edit a Custom Dialog.) HotDocs displays the Dialog Editor.
2. At the Properties tab of the Dialog Editor, click the

Dialog Element button and drag it to the Contents list. The

Dialog Element Editor appears.

3. Enter a name for the component in the Dialog element name box, or select Generate name automatically, which
allows HotDocs to name the component.

4. In the Style group, select Web link.

5. In the URL box, enter the complete Web address for the page you want the hyperlink to open. (Make sure the URL
is entered correctly. Include http:// or https:// or ftp://, depending on the type of URL it is.)

6. In the Link text box, enter the text you want to use as the hyperlink.
7. Click the Options tab and select how you'd like the link to appear on the dialog, based on the following information:
In the Display as group, select whether the link should be a Button or Hyperlink. (If you select Button, you
can specify a custom button size in the Button size group.)
If you select Hyperlink, select whether the link should include text, an image, or both in the Display using
group. (Enter the name of the image file in the Image file box if you select Image.)
Caution:
Any images displayed in a browser-based (HotDocs Server) interview must be located in the same folder
as the template. Also, bitmap (.BMP) files are not supported in browser-based interviews. Additionally,
Silverlight does not support all possible color depths that are included in the PNG specification. Specifically,
gray scale and 64-bit true color are not supported in Silverlight.
In the Display in group, select whether the link should appear when the dialog is displayed in Desktop
interviews, Server interviews, or both.

8. Optionally, to control the appearance of the browser window when it opens, enter the JavaScript parameters in the
Window.open features string (HotDocs Server only) box.
This value corresponds to the third parameter of the JavaScript window.open method (sFeatures). For example, to
open the resource in a window that is 200 pixels high, 400 pixels wide, includes the status bar, and does not include
the toolbar, menu bar, and location bar, use this string:
height=200,width=400,status=yes,toolbar=no,menubar=no,location=no

9. Click OK. The Dialog Element Editor is closed.

10. Drag the component up or down in the Contents list, depending on where you want the hyperlink placed on the
dialog.
Note:
Rather than create a hyperlink that opens a Web browser, you can create an e-mail link. To do this, include mailto: in
the URL, followed by an e-mail address, like this: mailto:[email protected].

Copyright 2010 HotDocs Ltd. All rights reserved

248

Help Topics for HotDocs Developer 10

Caution:
If your hyperlink is designed to allow HotDocs Server users to access a database via a Web page, you must select
Server interviews in the Display in group. Note that the hyperlink will not work in a desktop interview.

Copyright 2010 HotDocs Ltd. All rights reserved

249

Help Topics for HotDocs Developer 10

Add Spacing and Separator Lines to a Dialog

Sometimes you need to add white (or empty) space or separator lines to a dialog. This can help you better organize the
dialog.
When adding empty space to a dialog, you can control how much space will be used.
When adding a separator, you can include a caption with the separator. For example, if you have two groups of questions
in a dialogone about the plaintiffs and the other about the defendants in a caseyou can separate each group with a
line and include the text Plaintiff Information or Defendant Information on each separator line.
To add white space to a dialog

1. Open a dialog for editing. (See Edit a Custom Dialog.) HotDocs displays the Dialog Editor.
2. At the Properties tab of the Dialog Editor, click the Dialog Element button and drag it to the Contents list. The
Dialog Element Editor appears.

3. Enter a name for the component in the Dialog element name box, or select Generate name automatically, which
allows HotDocs to name the component.

4. In the Style group, select Vertical spacing.

5. In the Spacing box, enter a percentage. (For example, if you want the space to be equal to the space taken by text
in the dialog, enter 100 in the Spacing box. If you want it to be larger or smaller, enter the appropriate number in the
box.)

6. Click OK. The Dialog Element Editor is closed.

7. Drag the component up or down in the Contents list, depending on where you want the white space placed on the
dialog.
To add lines to a dialog

1. Open a dialog for editing. (See Edit a Custom Dialog.) HotDocs displays the Dialog Editor.
2. At the Properties tab of the Dialog Editor, click the Dialog Element button and drag it to the Contents list. The
Dialog Element Editor appears.

3. Enter a name for the component in the Dialog element name box, or select Generate name automatically, which
allows HotDocs to name the component.

4. In the Style group, select Horizontal divider.

5. Optionally, enter a short description or phrase in the Caption box.
In the Font size box, enter a font size for the caption, based on the percentage of the rest of the dialog text's
size. (For example, if you want the caption to be the same size as the rest of the text in the dialog, enter 100 in
this box.)
Click the Justification drop-down button and select which side of the dialog the caption will be aligned with.

6. Click OK. The Dialog Element Editor is closed.

7. Drag the component up or down in the Contents list, depending on where you want the divider placed in the dialog.
Note:
To format the caption text (for example, to make the text bold), highlight the text, right-click, and then choose a
formatting option from the Character Format shortcut menu.

Copyright 2010 HotDocs Ltd. All rights reserved

250

Help Topics for HotDocs Developer 10

Add a Graphic File to a Dialog

Sometimes you may want to include images in your dialogs. Images may help users better understand questions
in the dialog, or they may allow you to display your company logo or other icon. The types of files you can add
include .BMP, .JPG, .GIF, and .PNG.
Caution:
Images with transparency may not appear correctly in dialogs.
To add an image to a dialog

1. Open a dialog for editing. (See Edit a Custom Dialog.) HotDocs displays the Dialog Editor.
2. At the Properties tab of the Dialog Editor, click the Dialog Element button and drag it to the Contents list. The
Dialog Element Editor appears.

3. Enter a name for the component in the Dialog element name box, or select Generate name automatically, which
allows HotDocs to name the component.

4. In the Style group, select Image.

5. In the Image file box, click the

Browse button and locate the image file.

Caution:
Any images displayed in a browser-based (HotDocs Server) interview must be located in the same folder as the
template. Also, bitmap (.BMP) files are not supported in browser-based interviews. Additionally, Silverlight does
not support all possible color depths that are included in the PNG specification. Specifically, gray scale and 64-bit
true color are not supported in Silverlight.

6. Optionally, select an alignment option: Left, Center, and Right.

7. Click OK. The Dialog Element Editor is closed.
8. Drag the component up or down in the Contents list, depending on where you want the graphic placed on the
dialog.

Copyright 2010 HotDocs Ltd. All rights reserved

251

Help Topics for HotDocs Developer 10

Chapter 16: Using Scripts to Make Dialogs Dynamic

Automatically Disable Irrelevant Variables in Interviews
When creating dialogs, you frequently need variables within a dialog to be dynamic. For example, you may want to
disable some questions in a dialog until a user answers a different question in the dialog a specific way. To accomplish
this, you can either write a script (see Use Scripts to Add Power to Your Dialogs) or you can have HotDocs automatically
hide or disable variables, based on whether they are used in the document.
For example, say you have a dialog that asks (using True/False variables) whether a client has any pre-existing health
conditions. If the client does, he or she must enter an explanation for each health condition. You can set variable
preferences that keep the explanations from being asked unless the corresponding True/False questions are answered
affirmatively. Then, if a dialog contains all inactive variables, you can keep the dialog from being asked in the interview.
Note:
When you start an assembly, HotDocs processes the template and determines which variables are referred to in
instructions, merged in the document, and so forth, based on the current answers. If a variable is unused, for example,
if you answer a conditional True/False variable such that it doesn't merge the associated Text variable, the Text
variable will be grayed or hidden in the dialog. (A third option lets you always show the variable, even if it's unused.)
Once this "usage pass" is done in the template, HotDocs does another pass through the template and generates the
interview.
There are three steps to automatically disabling unused variables:
Specifying at the variable level whether variables should be grayed or hidden if they're not needed in the document.
Specifying at the dialog level whether dialogs that contain only irrelevant variables should be left out of the interview
entirely.
Selecting a component file property that automatically disables irrelevant variables in the interview.
To mark how variables should be treated if they're not needed in the document

1. Edit the variable. (See Edit a Variable.)

2. At the Advanced tab of the Variable Editor, click the When irrelevant drop-down button and choose an option:
Default causes the variable to use the default setting, which you define at Component File Properties.
Gray causes the variable to appear grayed out if it is unused in the document. (This is the default option for all
variables.)
Hide causes the variable to be hidden if the variable is unused in the document. If the answer file changes and
the variable is needed, the variable will be shown in the dialog.
Show causes the variable to always appear in the dialog, regardless of whether it's used or not.
To automatically exclude dialogs that contain only irrelevant variables

1. Edit the dialog. (See Edit a Custom Dialog.)

2. Click the Options tab. The view changes to show the different options for displaying a dialog.
3. Select Hide this dialog when all variables are inactive.
To automatically disable unused variables in the interview

1. Open Component Manager for the template. (See Open and Close Component Manager.)
2. Click the

Component File Properties button. The Component File Properties dialog box appears.

3. Click the Interview tab. The view changes to show interview options.
4. Select Automatically disable irrelevant variables and dialogs.
Copyright 2010 HotDocs Ltd. All rights reserved

252

Help Topics for HotDocs Developer 10

5. Click the Default drop-down button and choose one of the options from the list:
Gray causes all variables with their irrelevant status set to Default to be grayed.
Hide causes all variables with their irrelevant status set to Default to be hidden.
Show causes all variables with their irrelevant status set to Default to always be asked, even if the variable is
irrelevant.
Note:
Model documents assembled from markup are set to automatically disable unused variables. For information on
marking up model documents, see Overview: Create a Model Document.
Caution:
Even when variables are automatically disabled, they will always be visible in pop-up dialogs users view when they
click a form field wizard button.

Copyright 2010 HotDocs Ltd. All rights reserved

253

Help Topics for HotDocs Developer 10

Use Scripts to Add Power to Your Dialogs

You can create scripts for your dialogs that allow you to hide or dim variable questions, require certain questions be
answered before the user can proceed to the next dialog, and assign predetermined values to variables. You can also use
scripts to make variables within a dialog conditionaljust as they are in the underlying template text.
Caution:
Before creating a dialog script, see Special Instructions for Dialog Scripts as well as Understand the HotDocs Scripting
Language. Dialog scripts should only change the appearance of variables in a dialogthey should not be used to
compute answers.
To create a script for a dialog

1. Open a dialog for editing. (See Edit a Custom Dialog.) HotDocs displays the Dialog Editor.
2. Click the Script tab. The window changes to show scripting options.
3. Enter your dialog script. (See Use the Script Editor and Special Instructions for Dialog Scripts.)
Once you have written your script, you can make sure it works correctly by testing the dialog. The dialog appears just as it
will during regular assembly. (See Test a Custom Dialog.)
Note:
At the Script tab, the Components list shows the components (including dialog element components) in the order
they are used in the dialog. This makes it easier to see exactly which components you can use in the script.

Copyright 2010 HotDocs Ltd. All rights reserved

254

Help Topics for HotDocs Developer 10

Chapter 17: Assigning Answer Sources to Dialogs

Suggest an Answer Source for Dialogs
You can suggest an answer source (a list of answers from which a user can select one) for a dialog. Users open the list
when answering questions in a dialog and pick an existing set of answers, instead of entering one manually. For example,
perhaps you have a large number of attorneys in your firm. Rather than enter information for a specific attorney each time
you need to assemble a document, you can enter this information once and then retrieve it on a document-by-document
basis.
An answer source file contains sets of answers for one or more variables in a dialog. For example, a dialog may require
information about an attorney, such as a name, address, and telephone number. If there are multiple attorneys in a firm,
all of this information for each attorney could be saved in an answer source. During an interview, the user opens the
answer source, selects the appropriate attorney, and that information will be merged into the document.
You must group all of the variables you want answered by a selected record in the same dialog. If your template contains
variables that must be answered by different records, you can group all the variables to be answered by one record
together in one dialog, all the questions for another record in another dialog, and so on.
If you are integrating HotDocs with another program you can also specify a DLL file as an answer source that will link
the dialog to the third-party program. (Contact your HotDocs sales representative for more information about using the
HotDocs API.)
See Tips for Working with Answer Sources for more information on answer source files.
To create an answer source

1. Edit or create a dialog that contains the variables you want to associate with an answer source file. The Dialog
Editor appears.
Caution:
Remember that variables in each dialog can be answered by only one record. If you have variables that must be
answered by a different answer source, place those variables in a different dialog.

2. Click the Options tab. The window changes to show several custom options.
3. Select an existing answer source file by clicking the Answer source drop-down button, or create an answer source
by typing a file name with a three-letter extension, such as .ANX or .HPL, in the Answer source box. (You can use
an existing answer source by clicking the

Open button and then searching for the file.)

4. If you are linking an existing answer source to a dialog, and the variable names used in the answer source don't
match the variable names in the dialog, you must associate the variables so they can share information. Click Map
Variables to do this. (See Link an Existing Answer Source to Other Dialogs or Link a Dialog to a List Gathered by a
Repeated Dialog.)

5. Click OK to close the Dialog Editor.

Once your answer source is created, a
Select button appears on the dialog during the interview. The user can click
this button, select an answer or enter new answers, and the answers are saved to the answer source file you specified.
Caution:
Be careful about using an answer source with a dialog other than the one for which it was created. Each variable
in the answer source must have a corresponding variable in every dialog with which it is used. Otherwise, if
records are added or deleted, the records are added or deleted incorrectly and existing records will be damaged.
(You can use the HIDE instruction to hide variables so they wont be visible in the dialog. If you dont want them
to be visible in the answer source record, use either the CONCEAL or OMIT instruction in the same script.)

Copyright 2010 HotDocs Ltd. All rights reserved

255

Help Topics for HotDocs Developer 10

When associating an answer source with a repeated child dialog, the child dialog cannot be repeated as a
spreadsheet on the parent. If you do this, the

Copyright 2010 HotDocs Ltd. All rights reserved

Select button will not appear in the interview.

256

Help Topics for HotDocs Developer 10

Tips for Working with Answer Sources

You should keep the following tips in mind when creating and using answer sources for dialogs:
Since answer source files are saved to the default Answers folder, be careful giving them an .ANX extension, or
you may not be able to tell them apart from your regular answer files. Its best to choose a file name extension such
as .HPL ("HotDocs pick list"), so you can distinguish them from other types of files.
If an answer source file is not found in the default Answers folder, HotDocs looks for it in the default template folder
next. If you want to store the file somewhere else, enter a folder path along with the file name in the Answer source
box.
Answer sources are automatically saved as you enter answers in them.
When you view the Answer source drop-down list, you may see several options listed. One option, CURRENT
ANSWER FILE, allows you to link variables in the current dialog to variables used in a repeated dialog. (See Link an
Existing Answer Source to Other Dialogs or Link a Dialog to a List Gathered by a Repeated Dialog.) Other options
you may see, including external programs such as the Corel Address Book, allow you to link dialogs directly to an
application and associate variable names to use the information stored in the program to answer variables. (Only
programs you have installed that support this type of integration will be listed.)

Copyright 2010 HotDocs Ltd. All rights reserved

257

Help Topics for HotDocs Developer 10

Link a Dialog to a List Gathered by a Repeated Dialog

At times, you may want to allow users to choose answers for a dialog from a list of answers they've already provided
earlier in the interview.
To link a dialog to a list of answers

1. Edit the dialog whose answers you want to retrieve from an existing list. (See Edit a Custom Dialog.)
2. Click the Options tab. The window changes to show several custom options.
3. Click the Answer source drop-down button and choose CURRENT ANSWER FILE.
4. Click Map Variables. The HotDocs Variable Mapping dialog box appears.
5. In the Map To column, click the drop-down button corresponding to the first variable and select the variable that
should share the same answer. (The drop-down list contains the variables in the current template that are the same
type as the variables in the dialog.)

Copyright 2010 HotDocs Ltd. All rights reserved

258

Help Topics for HotDocs Developer 10

Link an Existing Answer Source to Other Dialogs

You can use an answer source with a dialog other than the one it was created for. You must know the answer source file
name (and location) as well as the names of the variables referenced in it.
To use an existing answer source

1. Edit the dialog you want to link to the answer source. (This dialog can be in any template.) (See Edit a Custom
Dialog.)

2. Click the Options tab. The window changes to show several custom options.
3. In the Answer source box, enter the answer source file name. (If the answer source is saved in a location other
than the HotDocs Answers folder or the current template's folder, enter a full folder path along with the file name.)

4. If the variable names in the current dialog match those in the answer source, click OK. If not, continue this process.
5. If the variable names in the current dialog don't match those in the answer source, click Map Variables. The
HotDocs Variable Mapping dialog box appears. The variable names in the current dialog are listed in the Variable
Name column.

6. In the Map To column, click the drop-down button corresponding to the first variable whose answer you want to
come from the answer source. (The drop-down list contains the variables in the answer source that are the same
type as the variables in the dialog.)

7. From the list, select the variable you want to map to the variable in the current dialog.
8. Continue selecting corresponding variables for each variable in the dialog you want to map.

Copyright 2010 HotDocs Ltd. All rights reserved

259

Help Topics for HotDocs Developer 10

Let Users Retrieve Answers from an Outlook Contacts List

Note:
This feature is supported in Microsoft Outlook 2000 and later.
You can link dialogs in your template to a Microsoft Outlook Contacts list. This allows your users to retrieve information
they already know from Outlook, rather than typing it in manually.
To do this, you must first specify Outlook as an answer source for a specific dialog. Then you must map variables in the
dialog to fields in the Contacts list. Like most variable mappings, data types must match. For example, you cannot map a
Text variable to a date field, and vice versa.
To map variables in a dialog to fields in Outlook

1. Edit the dialog you want to link to the Contacts list. (This dialog can be in any template.) (See Edit a Custom Dialog.)
2. Click the Options tab. The window changes to show several custom options.
3. Click the Answer source drop-down button and choose Outlook.
4. Click Map Variables. The HotDocs Variable Mapping dialog box appears. The Variable Name column lists the
variables in the current component file.

5. In the Map To column, click the drop-down button and choose the Outlook field that corresponds to the variable.
6. Repeat Step 5 for each variable you want to map.
Now, when users view this dialog during the interview, a
Select button will appear on the dialog. When they click
the button, HotDocs will display the Contacts list in Outlook where users can select the name of a contact and have the
appropriate information merged into answer fields in the interview.

Copyright 2010 HotDocs Ltd. All rights reserved

260

Help Topics for HotDocs Developer 10

Let Users Retrieve Answers from a Time Matters Record

Note:
To link your dialog to a Time Matters answer source, you must be using Time Matters 7.0 or later. Additionally, you
must select the Activate Answer Source Integration option when you enable the HotDocs link in Time Matters. (See
the Time Matters documentation for complete instructions on enabling this link.)
You can link dialogs in your template to a Time Matters Contacts or Matters record. This allows your users to retrieve
information they already know from Time Matters, rather than entering it manually.
To do this, you must first choose whether to link to a Time Matters Contacts record or a Matters record as the answer
source. You then must map variables in the dialog to fields in the record. Like most variable mappings, data types must
match. For example, you cannot map a Text variable to a date field, and vice versa.
When linking to Time Matters, you can also designate whether the user has write-back capabilities. This means that if the
user changes an answer once it has been selected from Time Matters and entered in the interview, HotDocs can either
always save the answer back to Time Matters, or it can allow the user to choose whether the answer should be saved
back. If changes should never be reflected in the original Time Matters record, you can choose to disallow write-back.
To map variables in a dialog to a Time Matters record

1. Edit the dialog you want to link to the Time Matters record. (This dialog can be in any template.) (See Edit a Custom
Dialog.)

2. Click the Options tab. The window changes to show several custom options.
3. Click the Answer source drop-down button and choose Time Matters - Contact or Time Matters - Matter.
4. Click Map Variables. The HotDocs Variable Mapping dialog box appears. The Variable Name column lists the
variables in the current component file.

5. In the Map To column, click the drop-down button and choose the Time Matters field that corresponds to the
variable.

6. Optionally, click the Write Back drop-down button and choose the option you need:
Never keeps the answer from being written back to Time Matters if it is changed.
Always always writes the answer back to Time Matters if it is changed. The user will not be notified or
prompted of the change.
Prompt displays a dialog box that lets the user decide if the changed answer should be written back to Time
Matters.

7. Repeat steps 5 and 6 for each variable you want to map.

Now, when users view this dialog during the interview, a
Select button will appear on the dialog. When they click
the button, HotDocs will display the Time Matters records list where they can select the specific record and have the
appropriate information merged into answer fields in the interview. If users change an answer, the write-back options you
selected will take effect when they save the answer file.

Copyright 2010 HotDocs Ltd. All rights reserved

261

Help Topics for HotDocs Developer 10

Chapter 18: Inserting Dialogs into Other Dialogs

Insert Dialogs Into Dialogs
You can insert dialogs into other dialogs. For example, you could create a dialog that collects basic client information and
then, if the client is married, add that dialog to the client dialog to collect spouse information. Dialogs inserted into other
dialogs are called child dialogs.
During an interview, a child dialog appears on its parent dialog as a button followed by the name or title of the dialog.
When the user clicks the button, the inserted dialog appears and the interview outline expands to show the inserted
dialog.
If you are inserting multiple child dialogs in a parent dialog and you specify a Selection grouping style, HotDocs places a
check box or option button next to each inserted dialog. When this check box or option button is selected, HotDocs places
the child dialog in the interview outline so that its contents can be answered. Otherwise, HotDocs will treat the child dialog
as if it doesn't existeven if there are required variables in it. In the interview, the user can either select the check box or
option button and then click the child dialog icon, or the user can click the child dialog icon, which automatically selects
the check box or option and then displays the child dialog.
You can insert as many levels of regular dialogs as you want. If you are nesting repeated dialogs, however, you can nest
up to 3 levels of repeated child dialogs. See Create a List Within a List for details.
To insert one dialog in another

1. Create the parent dialog as well as the child dialog. (See Gather Questions into a Custom Dialog.)
2. Once both dialogs are created, edit the parent dialog. (See Edit a Custom Dialog.)
3. At the Properties tab, click the Components drop-down button and select Dialogs from the list. HotDocs limits the
contents of the list to just dialogs.

4. Drag the dialog you want to insert to the Contents list.

5. Optionally, click the Options tab and select a grouping option from the Selection grouping drop-down list. (See
Group Child Dialogs in a Parent Dialog.)
Note:
By default, child dialogs appear on parent dialogs as links with the child dialog's name as the prompt. If you want to
provide more instructive text for accessing and then answering questions in the child dialog, enter a prompt in the
Prompt to use when displayed as child dialog box. (The prompt you specify here will be used in the dialog only
the dialog's name or title will still be used in the interview outline and in the dialog itself.)

Copyright 2010 HotDocs Ltd. All rights reserved

262

Help Topics for HotDocs Developer 10

Group Child Dialogs in a Parent Dialog

When you add two or more child dialogs to a parent dialog, you can group the child dialogs so users can more easily
specify which dialog they want to answer. When you group child dialogs, HotDocs places a check box or option button
in front of the child dialog icon. When this check box or option button is selected, HotDocs places the child dialog in the
interview outline so that its contents can be answered. Otherwise, HotDocs will treat the child dialog as if it doesn't exist
even if there are required variables in it. In the interview, users can either select the check box or option button and then
click the child dialog icon, or they can click the child dialog icon, which automatically selects the check box or option and
then displays the child dialog.
Caution:
If child dialogs are not grouped, each child dialog will appear in the interview outline, regardless of whether the dialog
is optional to answer. If the user does not answer every question in every dialog, HotDocs will report in the End of
Interview dialog that there are unanswered questions.
To group child dialogs in a dialog

1. Create the parent dialog as well as the dialogs you want to insert. (See Gather Questions into a Custom Dialog.)
2. Once your dialogs are created, edit the parent dialog and add the child dialogs to it. (See Edit a Custom Dialog and
Insert Dialogs Into Dialogs.)

3. While editing the parent dialog, click the Options tab. The window changes to show options for working with the
dialog.

4. Click the Selection grouping drop-down button and select Select One or Select All That Apply.
Note:
When child dialogs are grouped, you can use a SET instruction to automatically select a child dialog for answering.
Doing this will automatically add the correct child dialog to the interview outline. You can also test whether a child
dialog has been selected for answering by using a True/False expression.

Copyright 2010 HotDocs Ltd. All rights reserved

263

Help Topics for HotDocs Developer 10

Chapter 19: Using ASK Instructions to Control Dialog Order

Control When Your Dialogs Appear
When HotDocs creates an interview for the user, it reads through the template and displays dialogs based on the order it
encounters variables and instructions in the template. However, if you want your dialogs to appear in a different orderfor
instance, if you want a certain dialog to appear first, even though variables that prompt the dialog to be asked appear at
the end of the templateyou can use an ASK instruction to force HotDocs to display the dialog.
To insert an ASK instruction

1. Position the cursor at the point in the template where you want the dialog to appear (for example, at the top of the
template).

2. Click the

ASK Field button. The ASK Field dialog box appears.

3. Select a dialog from the Dialog drop-down list, or click the

Edit Component button to create a new dialog. (See

Gather Questions into a Custom Dialog.)

4. Click OK. The ASK instruction is inserted in the template.

Note:
You can place several ASK instructions in a single computation script to control the order all dialogs are asked in
the interview. See Put ASK Instructions in a Computation Variable and Define a Custom Interview.
Sometimes you want to restrict a dialog so it only appears in the interview when it is specifically asked (using an
ASK instruction). To do this, clear Link variables to this dialog (at the Options tab). If a dialog that has this
option cleared is not specifically asked, variables in the dialog will be asked individually.
In Microsoft Word, you can also insert ASK instructions either by clicking on the HotDocs drop-down menu in the
HotDocs toolbar and choosing ASK Field, or by right-clicking in the template and choosing ASK Field from the
shortcut menu.

Copyright 2010 HotDocs Ltd. All rights reserved

264

Help Topics for HotDocs Developer 10

Put ASK Instructions in a Computation Variable

When you insert an ASK instruction directly in a template, the instruction can ask only one dialog at a time. If you want
to ask several dialogs in a specific order, you must insert individual ASK instructions for each dialog. Some template
developers like this approach to asking dialogs. Others, however, prefer to group ASK instructions together by creating
one computation that asks all the dialogs, and then inserting just the Computation variable into the template. In either
case, during assembly, the dialogs appear in the interview outline in the order of the ASK instructions.
To put ASK instructions in a Computation variable

1. Create the dialogs you want to ask. (See Gather Questions into a Custom Dialog.)
2. At the template, position your cursor where you want to insert the Computation variable that asks the series of
dialogs.

3. Create a Computation variable. (See Customize a Computation Variable.)

4. At the Computation Editor, drag ASK DIALOG from the Instruction models list to the Script box.
5. Replace the DIALOG placeholder with the name of a dialog you want asked. (See Use the Script Editor.)
6. Repeat Steps 4 and 5 for each ASK instruction. Your computation script may look something like this:
ASK Attorney Information
ASK Court Information
ASK Client Information

7. When you are finished, click OK.

Copyright 2010 HotDocs Ltd. All rights reserved

265

Help Topics for HotDocs Developer 10

Use ASK Instructions to Control the Interview

Caution:
HotDocs 5 users: If your HotDocs 5 templates use ASK UNANSWERED or ASK DEFAULT instructions, those
instructions will be treated as ASK ALL in HotDocs 10. Command-line options that once controlled these are no longer
functional.
In addition to using an ASK instruction to ask dialogs or variables, an ASK instruction can control whether variables and
dialogs required to assemble a document are asked during assembly. Changing ASK instructions lets you work with
answers behind the scenesassigning values without displaying the variables to the users. Specifically, ASK NONE
keeps HotDocs from asking variables or dialogs that would otherwise be asked automatically.
Note:
See How Variables and Dialogs Are Asked for details on how HotDocs determines when to ask variables and dialogs.
Using ASK instructions is particularly useful if you need to repeat a dialog but you don't want the dialog to be asked during
the interview.
You can insert an ASK instruction directly in a template or place it in a Computation variable and insert the variable in the
template.
To change the ASK mode in a text template

1. Place your cursor at the point in the template where you want HotDocs to control what gets asked.
2. Insert an ASK instruction (see Control When Your Dialogs Appear). Once the instruction is inserted, replace the
dialog name with one of the following keywords: ALL or NONE.
To change the ASK mode in a computation script

1. Open a Computation variable for editing. (See Customize a Computation Variable.) The Computation Editor
appears.

2. Drag ASK DIALOG from the Instruction models list into the Script box.
3. Replace DIALOG with one of the following keywords: ALL or NONE.
Caution:
If you change the ASK mode in a computation, you should always change it back to what it was originally (ALL or
NONE).

Copyright 2010 HotDocs Ltd. All rights reserved

266

Help Topics for HotDocs Developer 10

Chapter 20: Working with Component Files

Open and Close Component Manager
You can edit components in a template by using Component Manager.
To open Component Manager

1. At the HotDocs template, click the

Component Manager button. The Component Manager window appears.

2. Optionally, adjust the Component Manager window to the desired width and click the

Arrange Windows button.

The Component Manager window appears to the left of the template development window.

3. Once Component Manager is opened, you can perform any number of tasks, including:
Using Component Manager to work with components.
Creating and inserting a variable using Component Manager.
Creating and editing multiple components simultaneously.
Changing component file properties.
To close Component Manager, click the X in the upper-right corner of Component Manager.
Note:
You can also open Component Manager at the template library. This allows you to create and edit components without
actually opening the corresponding template. It also allows you to more easily edit the component file of a clause
library or interview template. (See Open Component Manager at the Template Library.)

Copyright 2010 HotDocs Ltd. All rights reserved

267

Help Topics for HotDocs Developer 10

Open Component Manager at the Template Library

In addition to using Component Manager while you are editing a template (see Open and Close Component Manager),
you can use Component Manager to modify the contents of a component file when you are at the HotDocs template
library. This may be useful if you need to make changes in the component file, but don't want to open the corresponding
template to do it. It is also useful if you need to edit an interview template (see Create an Interview Template), as well as
edit clause components in a clause library.
Caution:
Some changes you make in the component file are not always reflected in the template. For example, if you rename
a component at Component Manager without also renaming it in the template, you will receive errors when you
assemble the document. Update your template with changes as necessary to avoid such problems.
To open Component Manager at the template library

1. At the HotDocs library, select the template or clause library whose component file you want to open.
2. Click the

Component Manager button. The Component Manager window appears.

3. Make changes to the component file as necessary, such as create new components, edit existing components, and
rename components. (See Use Component Manager to Work with Components.)

Copyright 2010 HotDocs Ltd. All rights reserved

268

Help Topics for HotDocs Developer 10

Use Component Manager to Work with Components

Using Component Manager allows you to work with individual components in a HotDocs template, including copying
components between component files, creating new components, and editing existing components.
You can open and close Component Manager as needed, or you can leave it displayed as you work in the template,
switching between the two windows. One advantage of leaving Component Manager open is the ability to view all the
components in your template at once, and edit them simultaneously as needed.
To work with individual components in a component file

1. Open Component Manager. (See Open and Close Component Manager.) The Component Manager window
appears.

2. Perform any tasks, as described in the following table:

To
Sort components in
Component Manager
either by alphabetical
name or by component
type

Do This
Click the
by Type.

Sort Components button and then choose either Sort by Name or Sort

To sort component lists that appear in the Dialog Editor and Computation Editor,
right-click on the list and then choose your sorting option from the shortcut menu.

Display Component
Manager side by side with
the template development
window

Adjust Component Manager to the width you want and click the
Arrange
Windows button. HotDocs adjusts the size of the template development window so
that both windows can be viewed in full.

Save changes you have

made to the component
file

Click the

Specify certain assembly

and interview preferences
for the template and
component file

Click the
Component File Properties button. (See Change Component File
Properties.)

Use Component Manager

to insert a variable in the
template text

Place your cursor in the template where you want the variable, select the variable

Create a new component,

including a variable,
dialog, or clause

Click the Components drop-down button, select the type of component you want to

Make changes to an
existing component

Select the component from the component list and click the
button. (You can also double-click the component.)

Remove a component
from the component file

Save Components button.

from the Components list, and click the

Insert Variable button. (See Create and
Insert a Variable Using Component Manager.)

create, and click the

New Component button.

Select the component in the component list and click the

button.

Edit Component

Delete Component

Caution:
The component is removed from the component file and any associated dialogs,
but references to it in the template and other components (such as scripts,
prompts, or dialog text elements) will not be updated. If you've referred to this
component in any of these ways, you must manually update these references or
your template may not work.

Copyright 2010 HotDocs Ltd. All rights reserved

269

Help Topics for HotDocs Developer 10

To

Do This

Assign a new name to a

component

Select the component(s) and click the

Components in a Single Template.)

Make a duplicate copy

of a variable or group of
variables

Select the variable(s) and click the

Duplicate Copy of a Variable.)

Bring all open Component

Editors to the front

Click the
Restore All button. HotDocs brings all open Component Editors to the
front so you can view and edit them.

Minimize all open

Component Editors to the
Windows taskbar

Click the
Minimize All button. All open Component Editors are then minimized.
However, you can still access them by clicking their icon in the Windows taskbar.

Close all open Component

Editors

Click the
Save and Close All button. All changes made to components are saved
and all open Component Editors are closed.

Rename Component button. (See Rename

Duplicate Variables button. (See Make a

Note:
To access the Component Manager toolbar using the keyboard, press F10.
You can open a component file for another template while viewing the current component file. Once opened,
you can edit components or assign other properties. To do this, click the Expand button, and then select the
component file. Once open, edit the component. You can also copy components between the open component
files. See Copy Components From One File to Another.
For information on searching and replacing text strings in the component file, spell checking components, and
printing lists of component properties, see Search Component Files, Print a List of Components, and Spell Check
Components.

Copyright 2010 HotDocs Ltd. All rights reserved

270

Help Topics for HotDocs Developer 10

Create and Edit Multiple Components Simultaneously

Using Component Manager, you can create and edit as many components in a given component file as you wantat the
same time. This allows you to compare the properties, advanced options, selection options, and computation scripts of
many variables and dialogs. To manage all the open component editing windows, you can either use the

Restore All,

Minimize All, and

Save and Close All buttons in Component Manager; or you can use the Windows taskbar to
switch between open windows.
To edit multiple components simultaneously

1. Open Component Manager. (See Open and Close Component Manager.)

2. At the Component Manager window, you can either edit existing components or create new ones:
To edit an existing component, select it from the list of components and click the
Edit Component button.
Do this for each component you want to edit. (HotDocs adds the component window to the Windows taskbar so
you can more quickly access it.)
To create a new component, click the
create.

New Component button. Do this for each component you want to

3. Make changes to each variable as necessary, using the following tools to help you manage the open windows:
To bring all open Component Editors to the front, click the
To minimize all open Component Editors, click the

Restore All button.

Minimize All button.

To save and close all open Component Editors, click the

Save and Close All button. (Any changes you
have made to component properties will automatically be savedyou will not be prompted to save them.)
To switch between open Component Editor windows, select the component in the Windows taskbar. HotDocs
will bring that Component Editor to the front.
Note:
If you create new components using Component Manager, they are not immediately inserted into the template
they are only saved in the component file. You must insert the variables into the template. See Insert a Variable
Field in a Text Template.
How quickly HotDocs minimizes and restores component editing windows depends on your Windows settings.
To restore instantaneously, right-click on the Windows desktop, choose Properties from the shortcut menu, click
the Appearance tab, click Effects, and then clear Use transition effects for menus and tooltips. (This process
may differ, depending on the version of Windows.)
To change a component in several component files, use Template Manager. (See Overview: Use Template
Manager.)

Copyright 2010 HotDocs Ltd. All rights reserved

271

Help Topics for HotDocs Developer 10

Change Component File Properties

You can change certain template and component file properties at the component file level. Component file properties
allow you to, among other things:
Specify default titles and descriptions for the template.
Define the interview for the template.
Control which parts of the assembly window (such as the interview outline and End of Interview dialog) appear for a
given template.
Enable answer-editing at the Document Preview tab.
Choose which hidden data can be removed from an assembled document.
Define properties for how the interview will be displayed in a Web browser.
When you change component file properties, those changes usually affect a single template. However, if you are sharing
component files (see Use One Component File for Multiple Templates), some properties may be applied to the shared file
while others may be applied to the pointed component file. (See Specify Whether Component File Properties are Shared.)
To change component file properties

1. Open Component Manager. (See Open and Close Component Manager.)

2. Click the

Component File Properties button. The Component File Properties dialog box appears.

3. Change any of the following options at the General tab:

To

Do This

Specify a default title for

the template

Enter the template title in the Template title box. This title is used to identify the
template in the template library file list.

Include a short description

of the template, such as
how the template should
be used or when it was
created

Enter a description in the Template description box. The description appears when
the user views its properties at the library Properties tab.

Specify with which version

of HotDocs the template
will be used

Click the Component file format drop-down button and choose the version of
HotDocs you need:
Choose Current Format to save it in the latest version of HotDocsin this
case, HotDocs 2009-10. When you upgrade to a future version of HotDocs,
HotDocs automatically upgrades the component file version so you don't have
to (as you do if you choose one of the other options).
Choose HotDocs 6, HotDocs 2005, HotDocs 2006-2008, or HotDocs 2009-10
to save the component file in that specific version. To upgrade or downgrade
the version, you must manually choose the new version here.
Caution:
Be careful not to use new features that aren't supported in the older versions of
HotDocs or you may experience errors during assembly.

Specify a shared
component file for the
template

Click the Shared component file drop-down button and choose the component file
from the list. (Shared and pointed component files must be stored in the same folder.)

To point a template to a
shared component file,
make sure you first close
Copyright 2010 HotDocs Ltd. All rights reserved

272

Help Topics for HotDocs Developer 10

To

Do This

the template and then edit

the component file from
the template library.

4. Change any of the following options at the Interview tab:

To

Do This

Choose whether to use

your own interview script
or have HotDocs generate
a default interview

If you choose to create and use your own interview component, select Use custom
interview and enter the name of the computation in the Interview component box.
(In HotDocs 2005 and earlier, this component's name was INTERVIEW. You can
continue to use this name, or you can use any nameas long as it's specified here.)
If you choose to let HotDocs generate a default interview, select Generate default
interview. HotDocs then asks the variables and processes the instructions in the
template in the order it "reads" them. If a variable is linked to a dialog, the dialog is
displayed instead.

Automatically disable
variables in dialogs that
aren't referred to in the
document

Select Automatically disable irrelevant variables and dialogs. (See Automatically

Disable Irrelevant Variables in Interviews.)

Display just answergathering dialogs without

showing the interview
outline

Select Hide interview outline. The only way the user can navigate the interview is

Keep the End of Interview

dialog from appearing

Select Hide End of Interview dialog. When the user clicks Next at the last dialog
in the interview, HotDocs will either send the assembled document to the word
processor or it will display the Document tab, depending on which End of Interview
action the user has defined. (See Control Whether Users See the End of Interview
Dialog and Control What Happens When You Finish an Interview.)

Have HotDocs
automatically generate
titles for dialogs based on
the contents of the dialog

Select Generate default titles for dialogs.

You can specify the default action for variables in the template. Click the Default
drop-down button and choose an option. (To make use of this setting, at each
variable's Advanced tab, click the When irrelevant drop-down button and choose
Default.)

by using the

Previous and

Next commands.

If you want to create your own custom dialog titles, assign them at each dialog's
Dialog Editor. (See Change a Dialog's Options.) Once you specify a title for a dialog,
HotDocs will not generate them.

The way HotDocs

generates default dialog
titles is by seeing if the
first item in a dialog is
dialog element text. If
so, it displays that text
as the dialog title in the
interview outline. If not,
it uses the prompt from
the first variable and
appends the word "etc."
For example, if you have a
Copyright 2010 HotDocs Ltd. All rights reserved

273

Help Topics for HotDocs Developer 10

To

Do This

dialog gathering personal

information about an
employee and you have
not used any additional
text to introduce the
dialog, HotDocs looks
at the prompt of the first
variable in the dialog,
Employee name, and
creates a dialog title called
Employee name, etc.
Specify the text that will
be used for the resource
button ToolTip

Enter the text in the Resource button label box that you want users to see when
they hover their mouse cursor over the resource button during the interview.

5. Change any of the following options at the Assembly tab:

To

Do This

Specify a product title or

template set name that
appears in the assembly
window title bar

Enter a title in the Product title box. (If you leave this field empty, HotDocs will use
the text HotDocs Developer 10.)

Keep users from saving

their answers or using an
existing answer file for this
particular template

Select Do not use answer files.

Use variable names

instead of prompts when
generating Question and
Answer Summaries

Select Use variable names in summaries.

Position the cursor at

a certain place in the
document after it has been
assembled

Create a word processor bookmark in the template and select Move to the
"TypeHere" bookmark. (See Position the Cursor in the Assembled Document.)

Once selected, this option causes the first information-gathering dialog to appear
immediately after the template is selected for assembly. At the end of assembly,
users cannot save their answers.

Automatically update
Select Update table of contents, references, fields, etc.
the document's table of
contents and/or index once Once the document is sent to the word processor, these references will be updated
based on any changes made during assembly of the document.
the document has been
sent to the word processor
Let users see their
answers highlighted in the
assembled Microsoft Word
document

Select Mark answers in assembled documents.

Let users edit answers

while viewing the
assembled document in

Select Enable Edit Answer at the Document Preview tab.

When you do this, HotDocs marks merge fields in the Document Preview tab.
Users can then click the
Highlight Answers button in the assembly window and
answers will be highlighted with a special color.

Copyright 2010 HotDocs Ltd. All rights reserved

274

Help Topics for HotDocs Developer 10

To

Do This

the Document Preview

tab (Microsoft Word users
only)

As users change answers, answers throughout the document (and interview) will be
updated to reflect the change.

Designate what text will be

merged in the document
if the user chooses to not
answer a question

Click the Unanswered variable placeholder drop-down button and choose an

option: Default, [Variable], ***Variable***, Underscores, Asterisks, or Nothing.
See Tips on Using Unanswered Variable Placeholders for an explanation.

Specify a Word document

template where you
want to store your postassembly macros (Word
RTF users)

Click the
Browse button next to the Post-assembly macro file (Word only)
box and locate the template that contains these macros. See PLAY "MACRO" and
Specify a Word Template for Storing Post-Assembly Macros for more information.

Prevent HotDocs from

infinitely processing a
WHILE expression, which
will cause HotDocs to stop
responding.

Type a number in the Maximum WHILE iterations box. This number represents the
number of times dialogs or variables in the template or script can be looped before
HotDocs stops it from doing so.

Prevent HotDocs from

infinitely recursing (or
processing) a computation,
which will cause HotDocs
to stop responding

Type a number in the Maximum processing stack depth box. This number
represents how many instructions you want HotDocs to allow in the processing stack
(see note in previous column). When HotDocs reaches this limit, the recursion will
stop.

Note:
Recursion happens
when a computation
"calls" itself over and
over until the desired
result is achieved. For
example, you can use a
recursive computation
to scan a text string,
character by character,
for a specific value.
As HotDocs searches
for this value, it adds
information to the
processing stack. If too
much information gets
added to this stack,
HotDocs may stop
responding.

6. Change any of the following options available from the remaining tabs:
To

Do This

Have HotDocs
automatically remove
hidden data from the
assembled document

At the Hidden Data tab, select which types of data you want to remove from the
assembled document. See Remove Hidden Data from Assembled Documents for
more details.

Copyright 2010 HotDocs Ltd. All rights reserved

275

Help Topics for HotDocs Developer 10

To

Do This

Enable your templates for

server-based assembly

At the HotDocs Server tab, select Enable template for use with HotDocs Server.
See Enable Templates for Use with HotDocs Server for a description of all of these
options.
If you do not select this option, you will not be able to browser test the template or
publish it for use with HotDocs Server.

Have HotDocs upload

answer files to a Web
server

At the Answer Upload tab, fill in the information about answer uploading in the
corresponding fields. See Specify Options to Upload Answers.

Copyright 2010 HotDocs Ltd. All rights reserved

276

Help Topics for HotDocs Developer 10

Delete a Component from the Current Component File

You can delete a particular reference to a component in the template by highlighting the reference and pressing the
Delete key. However, to delete a variable from the component file (so that it wont appear in variable lists), you must use
Component Manager. You must also use Component Manager to delete formats, patterns, merge text, dialog element
text, or other components from the current component file.
Caution:
Deleting a component removes it from the component file and any associated dialogs, but references to it in the
template and other components (such as scripts, prompts, or dialog text elements) will not be updated. If you've
referred to this component in any of these ways, you must manually update these references or your template may not
work. If you are sharing components across multiple files, this must be done in each template that uses the component
file.
To permanently delete a variable, format, pattern, or merge text group

1. Open Component Manager. (See Open and Close Component Manager.) The Component Manager window
appears.

2. From the Components list, select the variable, format, pattern, or merge text you want to delete.
3. Click the

Delete Components button and click Yes when HotDocs confirms the removal. The component is
removed. If a reference to the component still exists in the template, you must remove it or you will receive errors
when you assemble the template.

Note:
To delete unused components in several templates, use Template Manager. (See Delete Components from
Multiple Component Files.)
When you are viewing the component list, you can limit the list of components that are showing by clicking the
Components drop-down button and selecting the specific component type.

Copyright 2010 HotDocs Ltd. All rights reserved

277

Help Topics for HotDocs Developer 10

Copy Components From One File to Another

You can copy components from one component file into another. Copying components makes it easy to use the same
variables, dialogs, example formats, and so forth in several templates. Once you have copied a variable from one
component file into another, you can change its properties to fit that specific template.
When you copy a component such as a dialog or a Computation variable, all of the variables associated with the
component are automatically copied as well.
To copy components from one component file to another

1. At the template, click the

Component Manager button. The Component Manager window appears.

2. Click the

Expand button in the upper-right corner of Component Manager. The window expands to show a second
component list.

3. Click the

Open button. The Open dialog box appears. (You can also click the Other component file drop-down
button and select one of the component files that is saved in the same folder as the current file.)

4. Locate the component file you want to display and click OK. HotDocs shows a list of components in that file.
5. In either the current component file or the other component file, select the components you want to copy.
6. Click the

Copy button (or the

Copy button). HotDocs copies the components. If you copy a dialog or a
Computation variable, any variables referenced by that component will also be copied.

7. If a component already exists in the file to which you are copying and contains properties that are different, complete
any of the following steps at the Copy Components dialog box:
Click Overwrite to overwrite that specific instance of an existing component with the one you are copying.
Click Don't Overwrite to not copy a specific component.
Click Rename to assign a new name to the component you are copying. Both the original and the copied
component are saved in the component file.
Click Always Overwrite to overwrite all existing components with the ones you are copying. Once you select
this option, you will not be warned when other duplicate components are found.
Click Never Overwrite to tell HotDocs to not copy (and overwrite) any existing components with ones you are
copying.
Also, at the Copy Components dialog box, you can view the components you are copying. To view the component in the
file from which you are copying, click the first View button. To see the component that exists in the component file into
which you are copying, click the second View button.
Once you have copied the components, click the
show only the current list of components.

Collapse button in the upper-right corner of Component Manager to

Note:
To copy components between several component files at once, you can use Template Manager. (See Copy and Paste
Components Across Multiple Component Files.)

Copyright 2010 HotDocs Ltd. All rights reserved

278

Help Topics for HotDocs Developer 10

Rename Components in a Single Template

Note:
If you have a template that contains several components that must be renamed, you should use Template Manager,
which changes the name in both the template file and the component file. It also updates any references to the
component if it is used by other components. (See Rename Components Across Multiple Component Files.)
You can rename variables, dialogs, example formats, merge text values, dialog elements, and so forth. When you rename
a component, it is changed everywhere it is used in the component file. For example, renaming a variable will update all
references to it in dialogs, scripts, and prompts. However, you must update references to the component in the template
text itself. This may include removing the old variable field and inserting a new variable field.
How you rename components depends on the component type. Main components can be renamed in both the template
file and the component file; however supplemental components (such as example formats, patterns, and so forth) can
only be renamed using Component Manager.
To rename a component while editing the template

1. Place the cursor in the variable field and click the

2. Click the

Variable Field button. The Variable Field dialog box appears.

Edit Component button. The Variable Editor appears.

3. In the Variable name box, type the new variable name and click OK. HotDocs verifies that you want to rename the
component.

4. Click Yes. The variable component is renamed, and the Variable Field dialog box appears again.
5. Click OK.
6. Remove any other references to the variable in the template and insert the new variable field. (See Insert a Variable
Field in a Text Template.)
To rename a single component using Component Manager

1. Open Component Manager. (See Open and Close Component Manager.) The Component Manager window
appears.

2. Select the component from the Components list and click the

Rename Component button. The Rename

Component dialog box appears.

3. Type the new component name in the New name box and click Rename. HotDocs changes the name throughout
the component file.

4. In the template, replace old component references with the new component. (See Insert a Variable Field in a Text
Template.)
To rename multiple components using Component Manager

1. Open Component Manager. (See Open and Close Component Manager.) The Component Manager window
appears.

2. Select the components from the Components list and click the

Rename Component button. The Rename

Components dialog box appears.

3. In the Existing Component Names column, select the components you want to rename.
4. Type the new name in the New Component Names column.
5. Optionally, to create multiple like-named components at once (for example, to rename two variables that use the
word Plaintiff so the new names instead use Client), type the existing word or phrase (i.e. Plaintiff) in the Replace
box, and then type the new word or phase (i.e. Client) in the with box, and click Apply. Where applicable, HotDocs
changes all the names in the New Component Names column.

6. Click Rename to rename the components.

Copyright 2010 HotDocs Ltd. All rights reserved

279

Help Topics for HotDocs Developer 10

7. In the template, replace old component references with the new components. (See Insert a Variable Field in a Text
Template.)
HotDocs lists all the components that were renamed in the Renamed Components list of Component Manager. To view
the full list of components again, click the Components drop-down button and choose All Components.

Copyright 2010 HotDocs Ltd. All rights reserved

280

Help Topics for HotDocs Developer 10

Make a Duplicate Copy of a Variable

You can copy an existing variable to create a new variable. This may be useful, for example, if you want to create a
variable that uses most (if not all) of the same properties of an existing variable, but you want the variable to have a
different name.
You must use Component Manager to duplicate variables. You can duplicate one component or many, depending on your
needs. You cannot duplicate dialogs, clauses, or database components.
To duplicate a single variable

1. Open Component Manager. (See Open and Close Component Manager.) The Component Manager window
appears.

2. Select the variable you want to copy and click the

Duplicate Variables button. HotDocs opens the Variable

Editor and displays a copy of the variable (as shown in the Variable name box).

3. Change the name and any other properties of the variable and click OK. The new variable is added to the
component file.
To duplicate multiple variables at once

1. Open Component Manager. (See Open and Close Component Manager.) The Component Manager window
appears.

2. Select the variables you want to create copies of and click the

Duplicate Variables button. The Duplicate

Variables dialog box appears.

3. In the Existing Variables column, select the variable(s) you want to duplicate.
4. Type the name of the new variable in the New Variables column.
5. Optionally, to create multiple like-named components at once (for example, to copy Defendant-related components
to create Plaintiff-related components), type the existing word or phrase (i.e. Defendant) in the Replace box, and
then type the new word or phase (i.e. Plaintiff) in the with box, and click Apply. Where applicable, HotDocs changes
all of the names in the New Variables column.

6. Click Duplicate to create the new variables.

HotDocs lists all the variables that were duplicated in the Duplicated Components list of Component Manager. To view
the full list of components again, click the Components drop-down button and choose All Components.

Copyright 2010 HotDocs Ltd. All rights reserved

281

Help Topics for HotDocs Developer 10

Edit Formats, Merge Text, Dialog Elements, and Patterns

You can edit supplemental components such as example formats, dialog elements, merge text, and patterns using
Component Manager.
To edit supplemental components

1. Open Component Manager. (See Open and Close Component Manager.) The Component Manager window
appears.

2. Click the Components drop-down button and select the type of supplemental component you want to edit. Your
options include variable formats (like Text Formats and Number Formats), Merge Text, Dialog Elements, and
Text Patterns. The list is filtered to show that kind of component.

3. Select the component you want to edit and click

Edit Component. The component is opened in its component

editor.

4. Make any necessary changes.

Note:
To create a new example format, merge text group, dialog element text, or text pattern, click the
New
Component button while viewing that specific list of supplemental components at Component Manager.
If you want to assign a name to a variable formatfor instance, because a name would be more descriptive than
the actual formattype the name in the Format name box. This name will be displayed in format lists instead of
the format itself.

Copyright 2010 HotDocs Ltd. All rights reserved

282

Help Topics for HotDocs Developer 10

Search Component Files

Using Component Manager, you can search for literal text strings in component prompts, titles, dialog element text, notes,
scripts, patterns, formats, and merge text. If necessary, you can replace any text you find with different text.
To search components for a certain text string

1. Open Component Manager. (See Open and Close Component Manager.) The Component Manager window
appears.

2. Click the

Find in Components button. The Find in Components dialog box appears.

3. From the Include list, select one of the following options: All components in list (searches all of the components
currently displayed in the Components list), Selected components in list (searches only the components that are
currently selected (highlighted) in the Components list), All components in component file (searches all of the
components in the component file, regardless of what is currently displayed (and selected) in the Components list).

4. Type the word or string of text in the Find what column. (You can include up to 10 text strings.)
5. Optionally, select any other search criteria:
Match case searches for a text string that matches the capitalization you have used.
Find whole words only excludes instances where the text in the Find column occurs as part of another word.

6. Specify which properties of a component you want to search by selecting an option. (See Component Properties for
an explanation of each property.)

7. Click Find. Once HotDocs is finished searching the components for the specified string, Component Manager
displays the Found Components list, which shows only those components that contained a match. This list
continues to show the results of your search until you either perform a new search or you close Component
Manager. To view the full list of components again, click the Components drop-down button and choose All
Components.
To search components for a certain text string and then replace the string with new text

1. Open Component Manager. (See Open and Close Component Manager.) The Component Manager window
appears.

2. Click the

Find and Replace in Components button. The Find and Replace in Components dialog box

appears.

3. From the Include list, select one of the following options: All components in list (searches all of the components
currently displayed in the Components list), Selected components in list (searches only the components that are
currently selected (highlighted) in the Components list), All components in component file (searches all of the
components in Component Manager, regardless of what is currently displayed (and selected) in the Components
list).

4. Type the text string for which you want to search in the Find what column. (You can include up to 10 strings.)
5. Type the text string with which you want to replace the found text in the Replace with column.
6. Optionally, select any other search criteria:
Match case searches for a text string that matches the capitalization you have used.
Find whole words only excludes instances where the text in the Find column occurs as part of another word.
Confirm replacements makes HotDocs ask you before it replaces the text string.

7. Specify which properties of a component you want to search by selecting an option. (See Component Properties for
an explanation of each property.)

8. Click Find. If you selected Confirm replacements, HotDocs will confirm each replacement. Once HotDocs finishes
replacing the components for the specified string, Component Manager displays the Found Components list, which
shows only those components that were modified. This list continues to show the results of your search and replace
Copyright 2010 HotDocs Ltd. All rights reserved

283

Help Topics for HotDocs Developer 10

until you either perform a new search or you close Component Manager. To view the full list of components again,
click the Components drop-down button and choose All Components.
Note:
To search for a specific component based on the component name, select the Find check box (located at the bottom
of the Component Manager window) and type the text for which you are searching.

Copyright 2010 HotDocs Ltd. All rights reserved

284

Help Topics for HotDocs Developer 10

Spell Check Components

Using Component Manager, you can spell check text-based properties of components, such as prompts, titles, notes, and
dialog element text.
To spell check components

1. Open Component Manager. (See Open and Close Component Manager.) The Component Manager window
appears.

2. Click the

Spell Check Components button. The Spell Check Components dialog box appears.

3. From the Include list, select one of the following options: All components in list, Selected components in list, or
All components in component file.

4. Select the component properties you want to spell check. (See Component Properties.)
5. Click OK. If HotDocs finds any unrecognized words, it displays the Check Spelling dialog box.
6. Make your selection, based on information in the following table:
To

Do This

Ignore the current instance Click Ignore.

of the word and continue
spell checking
Ignore all instances of the
word and continue spell
checking

Click Ignore All.

Correct only the current

instance of the word and
continue spell checking

Select an existing replacement from the Change to list (or type the replacement in
the Change to box) and click Change.

Correct all instances of

the misspelled word and
continue spell checking

Select an existing replacement from the Change to list (or type the replacement in
the Change to box) and click Change All.

Add the word to your

personal dictionary so
that the spelling checker
will not question the word
again

Click Add.

Display additional spelling

alternatives for the
unrecognized word

Click Suggest.

Change your spell

checking options, such as
which words the spelling
checker looks at and how
it determines whether
a word is a possible
replacement

Click Options. (You can also change your options at the HotDocs Options dialog
box. See Change Your Spell Checking Options.)

Note:
A deeper search takes longer but produces better possible replacements. If the
button is unavailable, HotDocs is searching at the deepest level.

When you are finished spell checking, HotDocs displays a list of components that were modified in the Changed
Components list. If HotDocs does not find any misspelled words, or if you do not correct any misspellings, this list is
empty. To view the full list of components again, click the Components drop-down button and choose All Components.
Copyright 2010 HotDocs Ltd. All rights reserved

285

Help Topics for HotDocs Developer 10

Print a List of Components

Using Component Manager, you can print lists of properties for selected components.
To print a list of properties for selected components

1. Open Component Manager. (See Open and Close Component Manager.) The Component Manager window
appears.

2. Click the

Print Components button. The Print Components dialog box appears.

3. From the Include list, select one of the following options:

All components in list, which prints all of the components currently displayed in the Components list.
Selected components in list, which prints only the components that are currently selected (highlighted) in the
Components list.
All components in component file, which prints all of the components in Component Manager, regardless of
what is currently displayed (and selected) in the Components list.

4. Select the properties you want to print. (See Component Properties for an explanation of each property.)
5. Click OK and specify any printer options.

Copyright 2010 HotDocs Ltd. All rights reserved

286

Help Topics for HotDocs Developer 10

Use One Component File for Multiple Templates

Caution:
It's a good idea to back up your shared component files on a regular basis. If a shared component file becomes
damaged, you could lose all of the components for several templates.
When you create a template file, HotDocs automatically creates a component file for that template. The component file
stores variables, dialogs, and other components you use for that specific template.
When several related templates use many of the same components, you can create all of those components just once
and store them in a shared component file. When you make a change to a shared component, (for example, if you change
a prompt or resource text), the change will appear in all templates that use that component file.
The way you share the same components in multiple templates is by pointing each template's own component file to the
shared component file. Then, as you create and edit components within the template, the template bypasses its own
component file (which is now known as the pointed component file or actual component file) and stores the information in
the shared component file instead. All templates, pointed component files, and shared component files must be saved in
the same folder.
Its a good idea to point all the templates that will share a component file to the shared component file before you start
creating components in the templates. That way, they are saved directly in the shared component file and are ready for
use when you automate other templates. Otherwise, you must copy those components to the shared file so HotDocs can
find them. (See Copy Components From One File to Another.) (Pointing the current component file to the shared file does
not automatically copy the components there.)
When specifying component file properties, properties from the shared component file are used for all templates that point
to it (except for those specified at the General tab of the Component File Properties dialog box). You can, however, use
the pointed component file's properties. Additionally, if some of the properties you want to use are specified in the shared
component file, you can copy them to the pointed component file. See Specify Whether Component File Properties are
Shared for details.
If you are pointing several templates to a shared component file, but you want each template to use its own custom
interview, at the Interview tab, clear Use interview properties stored in the shared component file, select Use
custom interview, and then specify the name of the interview computation in the Interview component box.
To unpoint a component file, see Make Templates Stop Sharing Component Files.
To point the current component file to a shared component file

1. Make sure all templates and component editors are closed. (The only window that should be open is the template
library.)

2. At the template library, select the template whose component file you want to point.
3. Click the

Component Manager button. The Component Manager window appears.

4. Click the

Component File Properties button. The Component File Properties dialog box appears.

5. At the General tab, click the Shared component file drop-down button and select the shared component file. (This
drop-down list shows all of the component files listed in the same folder as the actual component file. Remember,
pointed and shared component files must be saved to the same folder.)

6. Optionally, to use the properties of the pointed component file instead of the shared, clear Use properties stored
in the shared component file at each respective tab of the Component File Properties dialog box. To copy the
properties of the shared component file into the pointed component file, click Copy Shared. (Any properties you
change after choosing to use the pointed component file will not be updated in the shared file.)

7. Click OK. The current template's component file is now pointed and the contents of the shared component file
appear in the component list. (At Component Manager, the
appearance to indicate that the component file is pointed.)
Copyright 2010 HotDocs Ltd. All rights reserved

Component File Properties button changes

287

Help Topics for HotDocs Developer 10

Caution:
If you created variables before you pointed the component file to the shared file, you must copy those variables to the
shared file. See Copy Components From One File to Another for details.
Note:
HotDocs can display a warning when you edit a template that has a pointed component file. This warning reminds you
that changes you make will affect all templates that point to the component file you are editing. See Display HotDocs
Warning Messages for details.

Copyright 2010 HotDocs Ltd. All rights reserved

288

Help Topics for HotDocs Developer 10

Specify Whether Component File Properties are Shared

When several related templates use many of the same components, you can create all of those components just once
and store them in a shared component file. The way you share the same components in multiple templates is by pointing
each template's own component file to the shared component file. Then, as you create and edit components within the
template, the template bypasses its own component file (which is now known as the pointed component file or actual
component file) and stores the information in the shared component file instead.
When specifying component file properties (see Change Component File Properties), you can choose which component
file will provide the options for the template. By default, templates use the shared component file's properties (except
for those properties specified at the General tab of the Component File Properties dialog box). However, if a certain
number of templates in your set require their properties be different from the others, you can choose to use the pointed
component file's properties, instead.
For example, perhaps only a few of your pointed templates will be published for use with HotDocs Server. For those
specific templates, you can enable them for use with HotDocs Server and set specific properties so they can be used on
the Web.
Caution:
Properties (such as the Template title and Template description) specified at the General tab of the Component
File Properties dialog box are always stored in the pointed component file.
To choose which component file properties should be used for a pointed template

1. Point the template's component file. See Use One Component File for Multiple Templates.
2. With Component Manager open and the Component File Properties dialog box displayed, click the tab for the
properties you want to use from the pointed component file. (For example, to use the pointed file's interview options,
click the Interview tab.) The view changes to show those specific options.

3. Clear Use properties stored in the shared component file.

4. Optionally, to copy the properties of the shared component file into the pointed component file, click Copy Shared.
Any properties specified for this group at the shared component file are copied into the current (or pointed)
component file.
Note:
The ability to use pointed component file properties for templates also lets you specify custom interviews for
each template in your set. Specifically, if you are pointing several templates to a shared component file, but
you want each template to use its own custom interview, at the Interview tab, clear Use Interview properties
stored in the shared component file, select Use custom interview, and then specify the name of the interview
computation in the Interview component box.
Any properties you change after choosing to use the pointed component file will not be updated in the shared file.

Copyright 2010 HotDocs Ltd. All rights reserved

289

Help Topics for HotDocs Developer 10

Make Templates Stop Sharing Component Files

You can unpoint a component file if you decide you no longer want to share components between multiple templates.
(See Use One Component File for Multiple Templates.)
To unpoint a component file

1. Make sure all templates and component editors are closed. (The only thing that should be open is the template
library.)

2. At the template library, select the template whose component file you want to unpoint.
3. Click the

Component Manager button. The Component Manager window appears.

4. Click the

Component File Properties button. The Component File Properties dialog box appears.

5. At the General tab, click the Shared component file drop-down button and choose the blank line at the top of the
list.

6. Click OK. The component list changes to show the components used in the original component file.
Caution:
If you added or created components while the component file was pointed, you must copy those components back
to your original component file so HotDocs can find them. See Copy Components From One File to Another for
information on how to do this.

Copyright 2010 HotDocs Ltd. All rights reserved

290

Help Topics for HotDocs Developer 10

Control Whether Users See the End of Interview Dialog

By default, when users complete interviews, the last dialog they see is the End of Interview dialog, which is where
they choose what to do with the assembled document. In some situations, you may want users to view the assembled
document automatically without displaying these options. You can keep this dialog from appearing.
To hide the End of Interview dialog

1. Open Component Manager for the template whose End of Interview dialog you want to hide. (See Open and Close
Component Manager.) The Component Manager window appears.

2. Click the

Component File Properties button. The Component File Properties dialog box appears.

3. Click the Interview tab and select Hide End of Interview dialog.
When the End of Interview dialog is hidden and the user clicks Next at the last dialog in the interview, HotDocs will
perform the End of Interview action the user specifies at HotDocs Options. These options include sending the document
to the word processor or Filler, or viewing the assembled document at the Document Preview tab. (See Control What
Happens When You Finish an Interview.)
Note:
Users can choose which options appear in the End of Interview dialog by making their selections at HotDocs Options.
See Customize the End of Interview Dialog.

Copyright 2010 HotDocs Ltd. All rights reserved

291

Help Topics for HotDocs Developer 10

Position the Cursor in the Assembled Document

You can cause HotDocs to place the cursor at a specified place in the assembled document once the user has completed
an interview and sent the assembled document to the word processor. You do this by inserting a TypeHere bookmark in
your template and then by selecting a component file property.
To insert a TypeHere bookmark

1. Create a template or open an existing template for editing. (See Create a New Text Template File or Edit a
Template.)

2. Place the cursor in the template where you want your cursor to appear when the assembled document is sent to the
word processor.

3. Use your word processors functionality to create a bookmark. Name it TypeHere and insert it into the text. (See
your word processors help file for information on creating bookmarks.)

4. Open Component Manager. (See Open and Close Component Manager.) The Component Manager window
appears.

5. Click the

Component File Properties button. The Component File Properties dialog box appears.

6. Click the Assembly tab and select Move to the Type Here bookmark.
7. Click OK.

Copyright 2010 HotDocs Ltd. All rights reserved

292

Help Topics for HotDocs Developer 10

Specify a Word Template for Storing Post-Assembly Macros

You can insert PLAY instructions in templates to play macros after assembly is complete. Such macros are used to
update references in the document, remove unused markup coding, apply custom formatting to answers, and so forth.
With a DOT template, the macro to be PLAYed can simply be included in the HotDocs template itself. After assembly,
HotDocs temporarily attaches the original template to the assembled document so that when the PLAY instruction is
processed, Word automatically finds the macro to be PLAYed.
With an RTF template, however, you can't store macros in the template. While you can place macros to be PLAYed in a
global template saved in Word's Startup folder, or add the macros to Normal.dot, this can be inconvenient, since you must
either provide instructions for the user on how to save the global template to the Startup folder or you must instruct them
on how to modify Normal.dot.
To accommodate this, you can store your post-assembly macros in a Word template, which you can then associate with
the HotDocs template. You specify the name of this Word template file at the Component File Properties dialog box for
the template. This Word template must be stored in the same folder as the HotDocs template that uses it.
To use a post-assembly macro template

1. Create a Word DOT template and store your macro in it. (See the Microsoft Word documentation for instructions on
doing this.)

2. Edit the template to which you want to attach the macro. (See Edit a Template.)
3. Insert the PLAY MACRO instruction in the template. (See PLAY "MACRO".)
4. Open the Component File Properties dialog box for the template. (See Change Component File Properties.)
5. Click the Assembly tab, and, in the Post-assembly macro file box, enter the name of the template you created in
Step 1. (Remember, the Word macro template must be stored in the same folder as the HotDocs template.)
Note:
Post-assembly macros are played whenever the user creates a document from the template, specifically when the
user prints the document, saves the document to disk, or sends the document to the word processor.

Copyright 2010 HotDocs Ltd. All rights reserved

293

Help Topics for HotDocs Developer 10

Remove Hidden Data from Assembled Documents

Note:
Removing hidden data from an assembled document is supported in Microsoft Word only.
As you work in Microsoft Word templates or documents, some personal information as well as some hidden document
properties are stored in the document. This information may compromise the security of the assembled document as well
as affect the size of the document file. To keep others from reviewing this information, or to reduce the size of the file, you
can choose which of these Word properties should be removed from an assembled document.
Properties you select at the Hidden Data tab of the Component File Properties dialog box will be removed from the
assembled document when users send the document to Microsoft Word.
Note:
In addition to removing hidden data from assembled documents, you can also remove hidden data from Word RTF
templates you're automating. See Remove Hidden Data from Word RTF Templates for details.
To choose which properties will be removed from an assembled Word document

1. Open Component Manager. (See Open and Close Component Manager.)

2. Click the

Component File Properties button. The Component File Properties dialog box appears.

3. Click the Hidden Data (Word) tab. The view changes to show the properties you can remove.
4. Select the types of data you want removed from the assembled document. You can remove content as well as
properties from the assembled document. Specifically:
Options in the Document Data to Remove group include marks or other types of data Word uses to manage
information in the document:
o

Invisible merge ID marks: Word merges revision ID numbers in the template each time you edit the
template text. (Word uses these numbers to improve accuracy when merging or comparing related
documents.) Each time you edit the text of a template, more IDs are added to the template and the size of
the file increases. Removing these IDs reduces the size of the document.

Redundant metafile graphics: When you insert a graphic image in your RTF template, Word merges a
Windows Metafile copy of the graphic in the template as well. This means there are two versions of the
graphic in the template. Removing the metafile version can significantly reduce the size of the document.

Unused property codes: When you apply formatting properties (such as bold, underline, alignment, etc.)
to text in a template, these codes are stored in the template. Selecting this property removes any codes
that may be left in the assembled document after the section of text to which the property was applied has
been removed through the use of IF instructions.

Options in the Document Properties to Remove group include information stored about the document,
including information about who created the document. (Document properties typically appear on the
Properties dialog box for a given document.)
Options in the HotDocs Fields to Remove group include the bookmarks HotDocs merges in a document to
indicate editable answers and text.
Options in the Document Markup group include reviewer's comments, such as annotations or change-tracking
suggestions.
Caution:
For complete explanations of each individual property, view the What's This help for each option on the tab, or see the
Microsoft Word documentation.
Now, when the document is assembled and sent to the word processor, the data associated with each option you've
selected will be removed from the document.

Copyright 2010 HotDocs Ltd. All rights reserved

294

Help Topics for HotDocs Developer 10

Remove Hidden Data from Word RTF Templates

Note:
Removing hidden data is supported in Microsoft Word RTF templates only.
As you work in Microsoft Word RTF templates, some personal information as well as some hidden document properties
are stored in the template. This information may compromise the security of the template as well as affect the size of the
template. To keep others from reviewing this information, or to reduce the size of the file, you can choose which of these
Word properties should be removed from the template. You can remove this data from a single template or from multiple
templates at a time.
Note:
You can also remove hidden data from assembled Word documents. See Remove Hidden Data from Assembled
Documents for details.
To remove hidden data from Word RTF templates

1. Open a template library. (See Open a Library.)

2. Select the RTF templates from which you want to remove the data.
3. Choose Hidden Data Remover (Tools menu). The Hidden Data Remover dialog box appears.
4. Optionally, click Analyze. HotDocs analyzes the templates you have selected and reports how much space in the
file each option listed in this dialog box is using. (This information appears in parentheses next to each option.)

5. In the Document Data group, select any of the following options:

Invisible merge ID marks: Word merges revision ID numbers in the template each time you edit the template
text. (Word uses these numbers to improve accuracy when merging or comparing related documents.) Each
time you edit the text of a template, more IDs are added to the template and the size of the file increases.
Removing these IDs reduces the size of the template file.
Redundant metafile graphics: When you insert a graphic image in your RTF template, Word merges a
Windows Metafile copy of the graphic in the template as well. This means there are two versions of the graphic
in the template. Removing the metafile version can significantly reduce the size of the RTF template.
Caution:
Once you remove this data from a template, continued editing of the template may reintroduce the extra data
back into the template. You can prevent Word from adding this data to the template. Click here for details.

6. In the Document Properties group, select which properties you want to remove from the template. (This includes
information stored in the Properties dialog box for a given template. It usually represents information about who
created the template.)

7. In the Document Markup group, select any of the following options:

Accept all tracked changes updates the template with any additions or corrections made with Word's Track
Changes feature.
Turn off change tracking disables the Track Changes option.
Remove all comments removes comments made in the template using Word's Comment feature.

8. Once you've selected which data you want to remove, click Remove Data. HotDocs removes the data from the
selected templates.

Copyright 2010 HotDocs Ltd. All rights reserved

295

Help Topics for HotDocs Developer 10

Work with Variables in Headers, Footers, Footnotes, and Text Boxes

Depending on whether you use Word or WordPerfect, how you insert a variable in a header, footer, footnote, or text box is
different. The following table explains how to use variables in the various areas of a word processor template.
Microsoft Word

WordPerfect

Headers and footers

Create the variable directly in the field, or

create the variable in Component Manager
and drag it into the field. Edit the variable
directly in the field or use Component
Manager.

Create the variable directly in the field, or

create the variable in Component Manager
and drag it into the field. Edit the variable
directly in the field or use Component
Manager.

Footnotes

Create the variable in Component Manager

and drag it into the field. Edit the variable
using Component Manager.

Create the variable directly in the field, or

create the variable in Component Manager
and drag it into the field. Edit the variable
directly in the field or use Component
Manager.

Text Boxes

Variables in text boxes are ignored during

document assembly.

Create the variable directly in the text

box, or create the variable in Component
Manager and drag it into the text box.
Edit the variable directly in the box or use
Component Manager.

Caution:
Using buttons in the HotDocs Navigation toolbar will have no effect while editing the contents of a header or
footer.
When inserting variables or instructions in a WordPerfect header, footer, footnote, or text box, you cannot
highlight text and then replace it with the field. You must simply insert the variable by clicking in the text.
HotDocs 5 users: In HotDocs 5, you had to specify a component file property that instructed HotDocs to
assemble variables in Word headers and footers. HotDocs 10 automatically assembles these, so the option has
been removed from the Component File Properties dialog box.
Note:
If a Word RTF template contains headers and footers with variables, you may find your variables being asked "out
of order." You can create a custom interview to control the order your variables and dialogs are asked. See Define a
Custom Interview for details.

Copyright 2010 HotDocs Ltd. All rights reserved

296

Help Topics for HotDocs Developer 10

Chapter 21: Using IF Instructions

Overview: Make Parts of Templates Conditional
Sometimes your templates contain optional text, or text that should be included only when certain conditions are met.
To include or exclude text based on these conditions, either you create an IF instruction, which is based on a True/False
variable, or you create an IF expression, which is based on other conditional tests. In either situation, the IF instruction or
expression must result in a true/false (or yes/no) result.
For example, in an estate planning document, there may be a paragraph that lists children who stand to inherit part of
the client's estate. However, if the client doesn't have children, this paragraph should not be included. To keep it from
being merged in cases where it's not relevant to the client, you can condition the paragraph on a True/False variable that
determines whether the client has children. If a simple True/False variable doesn't accomplish what you need, you can
create a more complicated expression. Types of expressions include testing against which option of a Multiple Choice
variable was selected, whether the value of an answer is equal to (or greater than or less than) another value, and so
forth.
In this example, the sentence Buyer and Spouse will be joint purchasers will be merged into the document only when the
answer to the True/False variable, Buyer is Married, is true.
Also, the sub-template, bos-009.rtf (which contains special insurance provisions) will be inserted only if the answer to the
variable BOS Consideration is greater than $250,000.

In addition to using a single instruction or expression to merge or remove a single block of text, there may be times when
you have multiple versions of a paragraph or other text, only one version of which should be merged into the assembled
document. To accomplish this, you can use a series of ELSE IF instructions or expressions. If you have a paragraph that
should be merged when no conditions are met, you can use an ELSE instruction.
Copyright 2010 HotDocs Ltd. All rights reserved

297

Help Topics for HotDocs Developer 10

Include or Exclude a Single Version of Text Using a Simple IF Instruction or

Expression
Often you have text in your template that you want to include or exclude based either on users' answers or on other
conditions being met during the interview. For example, perhaps you need to include a client's shipping address. You
can use a True/False variable to determine whether the shipping address is different from the billing address. If so, the
Shipping variables will be asked and their answers will be merged into the assembled document. If not, only the Billing
variables will be asked and merged.
Sometimes the situation in which you want to merge the text requires a little more information. In this case, you can use
a True/False expression to condition the text. For example, perhaps you need to include a list of minor children in the
document; however, you only want this list to appear if the client is married and if the children are under the age of 18.
To accomplish this, you can create a True/False expression. Like a True/False variable, an expression must result in
either true or false for the text to be merged or excluded correctly. Expressions are often used when a simple True/False
variable doesn't convey the condition you need.
In some templates, you may have multiple versions of text, only one of which you want to include in the document. You
can condition each section using a series of ELSE IF and ELSE expressions. The process of creating these expressions
is similar to creating them for True/False variables. To understand how to do this, see Include or Exclude Multiple
Versions of Text Using IF and ELSE IF Instructions or Expressions.
Note:
A true expression produces a true/false value. For example, the expression YEARS FROM( Childs Birth Date,
TODAY ) produces a number (the age of a person), not a true or false valueit is not a True/False expression. But the
expression YEARS FROM( Childs Birth Date, TODAY ) <= 17 can only result in true or false. It is a True/
False expression.
By default, when HotDocs inserts an IF expression in the template, it includes a return character after the instruction.
During assembly, as the instruction is processed and removed from the assembled document, this return character is
likewise removed. If you would prefer to keep this character from being merged entirely, or if you want to merge a return
character only when working with complete paragraphs of text, you can specify an option that controls this. See Control
When Returns Are Inserted After Instructions in Text Templates and Understand How Smart Returns are Inserted After
Instructions.
To condition text using a True/False variable

1. Highlight the template text you want to make conditionala word, a sentence, a paragraph, an instruction, and so
forth.

2. Click the

IF Field button. The IF Field dialog box appears.

3. Select IF True/False Variable.

4. Type a name in the True/False variable box, or select an existing variable from the drop-down list.
5. Optionally, click the

Edit Component button to make changes to the variable's component properties. (See
Customize a True/False Variable.)

6. Click OK. HotDocs inserts an IF instruction around the text you selected.
To add or exclude text based on a True/False expression

1. Select the text in the template you want to make conditionala word, a sentence, a paragraph, an instruction, and
so forth.

2. Click the

IF Field button. The IF Field dialog box appears.

3. Select IF Expression. The window changes to let you create a script for the expression. (See Understand the
HotDocs Scripting Language.)
Copyright 2010 HotDocs Ltd. All rights reserved

298

Help Topics for HotDocs Developer 10

4. Enter the script, using models from the Expression models list. (For example, the following is an expression that
tests three different conditions: 1) the client must be married, 2) the client must be over age 25, and 3) the client
must live in Pennsylvania: Client is Married AND AGE( Client Birth Date ) > 25 AND Client
State= "Pennsylvania".)

5. Click OK. HotDocs inserts the expression around the part of the template you selected.
Note:
True/false expressions can contain only 256 characters. If longer, you must use a Computation variable.
When the True/False variable appears during the interview, the variable name is used as the prompt. You can
enter a Prompt at the True/False Variable Editor to make it more specific. (See Tips on Naming Your Variables
and Create a Prompt for a Variable.) Additionally, you can include a resource (see Add Resource Information to a
Variable or Dialog.)
To help you create the expression, you can use predefined expression models from a list of models. Two
expression models you will use frequently are MULT_CHOICE = TEXT and MULT_CHOICE != TEXTboth of
which test what the answer is for a Multiple Choice variable.
Caution:
You cannot use an IF instruction to condition a table that appears within another table. For example, if you have a table
which contains another table within one of its cells, you cannot use a condition to remove the embedded table during
assembly. (If you do, HotDocs only removes the text from the table and leaves the empty table in the assembled
document.)

Copyright 2010 HotDocs Ltd. All rights reserved

299

Help Topics for HotDocs Developer 10

Include or Exclude Multiple Versions of Text Using IF and ELSE IF Instructions

or Expressions
Often you have a simple paragraph (or other section) of text in your template that you want to include or exclude based
either on users' answers or on other conditions being met during the interview. (See Include or Exclude a Single Version
of Text Using a Simple IF Instruction or Expression.)
In other cases, however, you may have multiple versions of text, only one version of which you want to include in the
document. You can condition each section using a series of ELSE IF and ELSE instructions. For example, if you have
different versions of a paragraph you use for different field offices, you can use the ELSE IF and ELSE expressions to
insert the correct paragraph, based on a user's answers. You can use both ELSE IF and ELSE in the same IF instruction,
but ELSE must always be the last item in the instruction.
In the following example, the first part of the condition tests whether the client lives in the state of Idaho. If so, the
paragraph for Idaho sales tax is merged. If the client doesn't live in Idaho but does live in Utah, the paragraph about Utah
sales tax is merged. Finally, if the client lives in a state other than Idaho or Utah, the paragraph keeping them from paying
sales tax is merged.
IF Client Lives in Idaho
Sales tax for the State of Idaho is Sales Tax Amount% and must be paid at the time of
purchase.
ELSE IF Client Lives in Utah
Sales tax for the State of Utah is Sales Tax Amount% and must be paid at the time of
purchase.
ELSE
No sales tax must be paid.
END IF
To create these ELSE IF sections, you can use either True/False variables or you can use expressions.
Note:
HotDocs processes IF instructions by starting at the top of the IF instruction and looking for the first condition that is
true. Once it finds a true condition, it inserts the correct text and continues processing any additional instructions. But
if all the conditions are false, HotDocs doesnt insert anything at all (unless there is an ELSE instruction.) When the
True/False variable that controls the IF instruction is not answered, none of the instructions are processed and no text
is merged in the document.
To add or exclude multiple versions of text using two or more True/False variables or expressions

1. Highlight the first conditional part of the template and create an IF instruction. (See Include or Exclude a Single
Version of Text Using a Simple IF Instruction or Expression.)

2. Select the IF instructions END IF keywords together with the next section of conditional text and click the

IF

Field button. The ELSE Field dialog box appears.

3. Select ELSE IF True/False Variable or ELSE IF Expression. The dialog box changes to show the options for
defining the condition.

4. Enter a name in the True/False variable box, or enter an expression in the Expression box.
5. Click OK to complete the instruction.
6. Repeat this procedure for each section of conditional text, making sure you select the preceding sections END IF
instruction, along with the new section of text.
Optionally, if you have a paragraph or block of text you want to include if all other conditions are false, you can use
an ELSE instruction.

7. Highlight the last END IF instruction together with the part of the template you want to be used if none of the
preceding conditions in the instruction are true.

8. Click the

IF Field button. The ELSE Field dialog box opens.

Copyright 2010 HotDocs Ltd. All rights reserved

300

Help Topics for HotDocs Developer 10

9. Select ELSE and click OK. The selected section of the text is added to the IF instruction. (You don't have to specify
a condition for this sectionit will simply be used whenever all the earlier conditions are false.)
Note:
True/false expressions can contain only 256 characters. If longer, you must use a Computation variable.
When the conditions in an ELSE IF instruction are all True/False variables, you can put them together in a singleselection group in a dialog. (See Change a Dialog's Options.)
Caution:
You cannot use an IF instruction to condition a table that appears within another table. For example, if you have a table
which contains another table within one of its cells, you cannot use a condition to remove the embedded table during
assembly. (If you do, HotDocs only removes the text from the table and leaves the empty table in the assembled
document.)

Copyright 2010 HotDocs Ltd. All rights reserved

301

Help Topics for HotDocs Developer 10

Edit an IF Instruction or Expression

You can edit an IF instruction or expression.
To change the condition for an IF instruction or expression

1. At the template, place the cursor in the IF instruction or expression.

2. Click the

IF Field button. The IF Field dialog box appears.

3. Edit the condition as necessary. Optionally, you can:

Create or select a different True/False variable or create a true/false expression. (See Include or Exclude a
Single Version of Text Using a Simple IF Instruction or Expression or Include or Exclude Multiple Versions of
Text Using IF and ELSE IF Instructions or Expressions.)
Click the
Edit Component button and type a prompt in the Prompt box to help the user make a selection.
(See Create a Prompt for a Variable.)
Click the
Edit Component button and then click the Resource tab to add a resource to the instruction or
expression. (See Add Resource Information to a Variable or Dialog.)
Click the
Edit Component button and then click the Advanced tab to specify several advanced options
that control how the variable used in the instruction is processed. (See Control How HotDocs Processes a
Variable, Control How Answers Appear in the Assembled Document, and Specify the Width of Answer Fields in
the Interview.)

Copyright 2010 HotDocs Ltd. All rights reserved

302

Help Topics for HotDocs Developer 10

Nest IF Instructions
You can nest an IF instruction inside another IF instruction. HotDocs wont process the nested instruction unless the first
(or top) level of the instruction is true.
In this example, if HotDocs finds that Clients Marital Status was answered Married, HotDocs inserts the text with the
spouses name and then checks to see if Client Has Children by This Marriage was answered true. If it is, HotDocs inserts
the names of the children.
This ruling affects the client, Full Name of ClientIF Client's Marital Status
= "Married"; and spouse, Full Name of SpouseIF Client Has Children by This
Marriage; and the following children: REPEAT Children:a, b, and cFull Name of
ChildEND REPEATEND IFEND IF.
But if HotDocs finds that Clients Marital Status was not answered Married, HotDocs skips the rest of the instruction,
including the question about children in the marriage.
Note:
If you ask variables later in the template based on a nested IF instruction being true, you must make sure you use
the full conditional reference before asking the variable. See Tips on Using IF Instructions.
You can have HotDocs identify the level of nesting in your IF instructions using both labels and field coloring. See
Use Labels to Identify Instructions and Assign Colors to Fields and Instructions in Templates.

Copyright 2010 HotDocs Ltd. All rights reserved

303

Help Topics for HotDocs Developer 10

Use Conditional Instructions in a Computation Script

Just as you can insert IF instructions and expressions directly in a template, you can use a Computation variable to
control conditional text. The computation can be as complicated as it needs to be, as long as it follows the same logic
applied when you insert an instruction directly in the template. (See Include or Exclude a Single Version of Text Using a
Simple IF Instruction or Expression and Include or Exclude Multiple Versions of Text Using IF and ELSE IF Instructions or
Expressions for a reminder.)
The IF instruction keywords (IF EXPRESSION, ELSE IF EXPRESSION, and so forth) are all available at the Instruction
models list in the Computation Editor. You can either type the instructions directly in the Script box, or you can drag
the models to the Script box and replace the EXPRESSION placeholders with either True/False variables or true/false
expressions. (See Use the Script Editor.)
The following is an example of a script that uses conditional logic:
IF State = "Idaho"
Total Price + (Total Price * 0.05) + Shipping
ELSE IF State = "Utah"
Total Price + (Total Price * 0.0625) + Shipping
ELSE
Total Price + Shipping
END IF

Copyright 2010 HotDocs Ltd. All rights reserved

304

Help Topics for HotDocs Developer 10

Tips on Using IF Instructions

How HotDocs Processes IF Instructions and Expressions
HotDocs processes IF instructions by starting at the top of the IF instruction and looking for the first condition that is true.
Once it finds a true condition, it inserts the correct text and continues processing any additional instructions. But if all the
conditions are false, HotDocs doesnt insert anything at all (unless there is an ELSE instruction). When the True/False
variable or expression that controls the IF instruction is not answered or satisfied, none of the instructions are processed
and no text is merged in the document.

Line Spacing
The key to correct line spacing between paragraphs when one or more paragraphs is conditional is understanding the
process by which HotDocs inserts returns. By default, HotDocs inserts a return after each IF instruction. Then, during
assembly, it removes any returns it has inserted.
You can select an option that inserts returns after every instruction, an option that inserts returns only if a complete
paragraph is selected, or an option that doesn't insert any returns at all. (See Control When Returns Are Inserted After
Instructions in Text Templates.) If you opt to include returns after complete paragraphs, if there are blank lines between
paragraphs, be sure to consistently include either the preceding or following blank line.

Qualifying Instructions
When automating a template, you can cause certain things to happen in your interview based on answers a user
gives. You accomplish this by using IF instructions. When using IF instructions, however, you should never reference a
conditional variable outside the context of its full condition.
For example, the following script only asks Text Variable B if True/False Variable A has been answered true. Then, later
in the template, another dialog is asked based on whether Text Variable B has been answered.
IF True/False Variable A
Text Variable B
END IF

IF ANSWERED( Text Variable B)

ASK Dialog 1
END IF
However, this script is incorrect since a user can reassemble the document (using the same answer file) and change
the answer for True/False Variable A. This would keep Text Variable B from being asked again. However, a value still
exists for Text Variable B in the answer file, so when HotDocs reaches the IF expression later in the template, Dialog 1 is
asked.
To fully qualify this condition, create an IF expression that tests both True/False Variable A and Text Variable B before
asking Dialog 1. For example:
IF True/False Variable A AND ANSWERED (Text Variable B)
ASK Dialog 1
END IF

Copyright 2010 HotDocs Ltd. All rights reserved

305

Help Topics for HotDocs Developer 10

Add a Comment to a Variable or Instruction Field

When you insert a variable or instruction in a template, you can add a comment to the insertion field. Comments are
useful when you want to document information about the variable or instruction you are inserting and you want those
comments to be viewable by anyone editing the text of the template.
Comments can also be useful when viewing a markup view of the templatethe comment can describe (in easy-tounderstand terms) the purpose of the field or provide a more reader-friendly name for the field.
Note:
If you want to add comments to a specific component, enter it at the Notes tab of the component editor. See Add
Notes to Components for details.
To add a comment to a variable or instruction field

1. Insert a new variable or edit an existing variable. (See Insert a Variable Field in a Text Template or Edit a Variable.)
The Variable Field dialog box appears. Or, insert a new instruction or edit an existing instruction. The instruction
field dialog box appears.

2. Click Show Advanced. The view expands to show advanced options.

3. Enter your comments in the Comment box.
When you click OK, HotDocs merges the field, with the comments merged after the variable name, like this: Employee
Salary //Calculates biweekly salary based on hourly rate.
Note:
To merge a comment in an END instruction (such as END IF, END REPEAT, OR END SPAN), place your cursor
before the closing chevron, enter two forward slashes (//), and type your comment, like this: END IF //Closing.
If the END instruction contains a Keep Return code ( | ), enter the comment before the return code, like this: END
IF //Closing |.

Copyright 2010 HotDocs Ltd. All rights reserved

306

Help Topics for HotDocs Developer 10

Understand How Smart Returns are Inserted After Instructions

By default, each time you insert any instruction (IF/END IF, REPEAT/END REPEAT, SPAN/END SPAN, INSERT, or
ASK) in a template, HotDocs adds a return following the instruction. Then, when HotDocs assembles the template
and processes the instruction, it removes the return it inserted. To some, this insertion of returns creates problems or
confusion in automating the template because it sometimes makes the template text difficult to read and understand,
especially when instructions (and their subsequent returns) within a paragraph sometimes break the paragraph into
separate lines of text.
To accommodate this, HotDocs allows you to choose whether to insert returns following these instructions. (See Control
When Returns Are Inserted After Instructions in Text Templates.). Specifically, you can:
Always insert a return after an instruction.
Never insert a return after an instruction.
Use "smart" return insertion.
The first two options behave exactly as expectedHotDocs will either always insert a return (and remove it during
assembly) or never insert a return, depending on which of the two options you choose.
The behavior of third option, using smart returns, depends on how and where you're inserting the instruction.
If text you select represents a complete paragraph (meaning there's a paragraph mark at the end of the selected text),
HotDocs will insert a return character after the instruction. In the following example, brackets ([]) indicate where text
selection begins and ends. Note that the closing bracket ends on the line after the paragraph mark ():
Here is a paragraph.
[Here is another paragraph.
]Here is a third paragraph.
Would produce a section of conditional text that looks like this:
Here is a paragraph.
IF Instruction
Here is another paragraph.
END IF
Here is a third paragraph.
However, if the text you select is within a paragraph, HotDocs will not insert a return character. So, in the following
example, when you insert the REPEAT instruction, HotDocs does not insert a return because the insertion is happening in
the middle of a paragraph. There is no paragraph break at the end of the insertion:
The client, Client Name, has the following children: REPEAT Children:a, b, and
cChild NameEND REPEAT. These children live with the client and are covered under
the provision.
At times, you may simply insert an instruction without first selecting text, or perhaps you may select some text but not
include the paragraph mark in the selection. If HotDocs detects an existing paragraph break immediately after the
instruction, it includes a Keep Return code (or vertical bar (|) ) at the end of the instruction. The code tells HotDocs to not
delete the return when it assembles the document. So, the following example, where brackets indicate text selection:
Here is a paragraph.
[Here is another paragraph.]
Here is a third paragraph.
would produce the following automation:
Here is a paragraph.
IF InstructionHere is another paragraph.END IF|
Here is a third paragraph.

Copyright 2010 HotDocs Ltd. All rights reserved

307

Help Topics for HotDocs Developer 10

Note that the Keep Return code (|) in the END IF instruction indicates to HotDocs to keep the return character when it
assembles the document.
Caution:
HotDocs' capacity to delete both an IF instruction and the return that follows it is very important in some situations. If
an optional paragraph includes numbering, it is difficult to condition out the entire paragraph and its numbering without
putting the IF on a separate line before the paragraph. It can be done, but the template looks odd, since the IF is inside
the numbering of the paragraph.

Copyright 2010 HotDocs Ltd. All rights reserved

308

Help Topics for HotDocs Developer 10

Assign Colors to Fields and Instructions in Templates

Note:
Click here if you are using WordPerfect and the HotDocs Navigation toolbar doesn't appear in your template.
You can assign custom colors to the different types of fields in a template. This can help you more quickly identify
sections or parts of your template as you are automating. Additionally, you can assign colors to IF, REPEAT, and SPAN
instructions in your templates. Assigning different combinations of these colors can help you differentiate levels of nesting
as well as help you better view individual pairs of instructions.
By default, HotDocs assigns its own colors; however, you can customize the colors at the HotDocs Options dialog box.
(See Define Field Colors.)
To apply custom colors to template fields and instructions

1. Open the template for editing. (See Edit a Template.)

2. Click the

Apply Colors button. The Apply Colors dialog box appears.

3. Select one of the following options:

Choose None to make all variable and instruction fields black.
Choose Regular to mark all variable and instruction fields using a custom color specific to that field type. For
example, all variables will be marked with one color, all IF instructions will be marked with a different color, all
REPEAT instructions will use a different color, and so forth.
Choose Nested to mark each level of IF and REPEAT instructions using a custom color. (For example, all firstlevel IF instructions will use a specific color, while all second-level instructions will use a different color, and so
on.)
Choose Sequential to mark each IF and REPEAT instruction field using a custom color. (For example, the
first instruction in a template will be marked using one color, while the next instruction will be marked using a
different color, and so on.)
Note:
If you change your default colors, or if you receive templates from other developers whose colors are different
from yours, you can click the

Apply Colors button to update existing templates with your custom colors.

If you're using Microsoft Word, you can also apply colors by clicking on the HotDocs drop-down menu in the
HotDocs toolbar and choosing Apply Colors. (To access this menu button in Word 2007 and later, click the
HotDocs drop-down button.)

Copyright 2010 HotDocs Ltd. All rights reserved

309

Help Topics for HotDocs Developer 10

Use Labels to Identify Instructions

Note:
Click here if you are using WordPerfect and the HotDocs Navigation toolbar doesn't appear in your template.
You can assign labels to IF, REPEAT, and SPAN instructions to help you identify pairs or groups of instructions in a text
template. When you label fields, you can choose to merge just a numeric name in a field or you can choose to merge
a name as well as the level of nesting. This can help you match opening instructions with closing, as well as help you
determine the level of nesting within an instruction.
Field labels are merged as comments in the field.
The following example shows a series of nested REPEAT instructions that have been labeled. The first instruction,
REPEAT Editor Information, is labeled with the number 1, since it's the first REPEAT in the template. This same
instruction is also assigned the level number of L1, since it's the first level of the REPEAT instruction. The END REPEAT
is likewise labeled so that you can easily match them when examining the contents of the template.
For each subsequent instruction, HotDocs increments the field number. Additionally, if the next REPEAT instruction is
nested (which, in this example, it is), HotDocs increments the nesting level number. Each END REPEAT instruction is
likewise labeled.
REPEAT Editor Information // [1:L1]
Editor: Editor First Name Editor Last Name
REPEAT Author Information // [2:L2]
Author: Author First Name Author Last Name
REPEAT Book Information // [3:L3]
Title Edited / Date Completed: Book Title / Date Completed:03 JUN 90
END REPEAT // [3:L3]
END REPEAT // [2:L2]
END REPEAT // [1:L1]
When assigning labels to fields, you can choose whether to include both the field number and the nesting level. You can
also choose to merge just one or the other.
Finally, you can have HotDocs assign the hidden text property to these labels (as well as any other comments you've
assigned to fields in the template.) When this property is assigned, comments and labels will be hidden and shown,
depending on whether you are viewing hidden text in the template. (For information on viewing hidden text, see your word
processor's documentation.)
To label instructions

1. At the text template, click the

Label Fields button. The Label Fields dialog box appears.

2. Select an option, based on the following information:

To assign a numeric name to each instruction, select Label IF, REPEAT, and SPAN instructions.
To have HotDocs identify the level of nesting for each instruction, select Identify level of nested IF, REPEAT,
and SPAN instructions.
To apply the hidden text property to comments and labels, select Place comments (including field labels)
in hidden text. Once applied, you can quickly show and hide your comments and labels by choosing the
appropriate command at the word processor.

3. Click OK. HotDocs applies the labels you have selected to any instructions in the template.
Note:
SPAN fields are supported in Microsoft Word only.
To clear labels from fields or show comments once again, click the
options, and click OK.
Copyright 2010 HotDocs Ltd. All rights reserved

Label Fields button, clear all of the

310

Help Topics for HotDocs Developer 10

If you're using Microsoft Word, you can also label fields by clicking on the HotDocs drop-down menu in the
HotDocs toolbar and choosing Label Fields.

Copyright 2010 HotDocs Ltd. All rights reserved

311

Help Topics for HotDocs Developer 10

Match Opening Instructions with Closing Instructions

Note:
Click here if you are using WordPerfect and the HotDocs Navigation toolbar doesn't appear in your template.
Every IF, REPEAT, and SPAN instruction inserted in a template must include an END IF, END REPEAT, or END SPAN
instruction. Without both of these instructions, you will receive an error when you attempt to assemble a document. (The
one exception is a repeated row in a table. See Use a Word Processor Table to Display a List.) However, sometimes
during the course of editing a template, you may inadvertently delete or move part of the instruction. Doing so will cause
errors when you attempt to assemble the document. To troubleshoot errors like this, you can have HotDocs match the
different parts of the instruction. Likewise, if you have an intricate section of nested instructions, you can pair these
different parts of the instruction.
To match opening instructions with their closing instructions

1. Open the template for editing. (See Edit a Template.)

2. Place the cursor inside either the opening instruction or the closing instruction. For example, if you're trying to find
the opening instruction of a REPEAT, place your cursor in the END REPEAT instruction.

3. Click the

Match Fields button. HotDocs moves your cursor to the corresponding instruction.

Note:
When editing instructions in a computation script, you can place your cursor in either the opening or closing
instruction and press Ctrl+M. This will move your cursor to the corresponding instruction.
If you're using Microsoft Word, you can also match fields by clicking on the HotDocs drop-down menu in the
HotDocs toolbar and choosing Match Fields.

Copyright 2010 HotDocs Ltd. All rights reserved

312

Help Topics for HotDocs Developer 10

Chapter 22: Creating Lists of Answers

Overview: Include Lists in Your Documents
You can include lists of answers in your documents by repeating variables and allowing the user to enter as many
answers as necessary. You repeat variables by surrounding the variables with a REPEAT instruction. Instead of collecting
and merging a single answer, as variables normally do, the repeated variable can merge an entire list of answers into the
assembled document.
For example, the following shows a REPEAT instruction inserted into a template:

This shows the list of answers the REPEAT instruction merged into the template:

Copyright 2010 HotDocs Ltd. All rights reserved

313

Help Topics for HotDocs Developer 10

When you create a REPEAT instruction, you will be asked to create or select a custom dialog to control the instruction.
During the interview, users can answer the dialog over and over again, until they have entered all the answers for the list.
Or, you can limit the number of answers a user can enter for a repeated variable.
Additionally, you can repeat any text, instructions, or other parts of a template. Everything inside a REPEAT instruction is
repeated along with the variables.
You can make lists in a document appear the way you likeeither in sentence style with punctuation, or in column style.
You can also have HotDocs sort, number, and filter lists automatically.

Copyright 2010 HotDocs Ltd. All rights reserved

314

Help Topics for HotDocs Developer 10

Create a REPEAT Instruction to Gather a List of Answers

Sometimes you may need to collect and merge a list of answers (instead of just a single answer) into a document. You
can create such a list by inserting a REPEAT instruction around one or more variables. For example, perhaps you must
insert a list of personal property items with their associated values. You can create the two variables and then repeat
them. When users complete the interview, they can enter as many property items as they have. Those answers are
merged into the finished document.
By default, when HotDocs inserts a REPEAT instruction in the template, it includes a return character after the instruction.
During assembly, as the instruction is processed and removed from the assembled document, this return character is
likewise removed. If you would prefer to keep this character from being merged, or if you want to merge a return character
only under certain situations, you can specify an option that controls this. See Control When Returns Are Inserted After
Instructions in Text Templates and Understand How Smart Returns are Inserted After Instructions.
Caution:
Often, you must repeat information within a word processor table. To repeat a row in the table, see Use a Word
Processor Table to Display a List. To repeat the contents of a single cell, see Create a REPEAT Instruction Using a
Computation Variable.
To create a REPEAT instruction

1. Select the template text, including variables you want to repeat, and click the

REPEAT Field button. The

REPEAT Field dialog box appears.

2. Either select an existing dialog from the Dialog drop-down list, or type the name of a new dialog in the box.
3. Click the

Edit Component button. The Dialog Editor appears.

4. Click the Style drop-down button and select the format for the repeated dialog. (See Choose a Presentation Style for
the Repeated Dialog.)

5. Optionally, enter custom label text you want to use on the

Add Another button in the Add button text box. (This

button appears on a repeated series dialog. Users click it to add a new repetition to the series of answers.)

6. If you are creating a new dialog, add the variables you want repeated to the dialog. (See Gather Questions into a
Custom Dialog.)

7. Click OK at the Dialog Editor. HotDocs displays the REPEAT Field dialog box again.
8. Complete either of the following optional tasks:
Click the Format drop-down button to choose a punctuation style for a sentence-style list (for example, A, B,
and C.) (See Punctuate a Sentence-Style List.)
Click Show Advanced to select sorting and filtering options for the repeated dialog. (See Sort a List of
Answers and Filter a List of Answers.)

9. Click OK. The REPEAT instruction is inserted in the template.

You can always change punctuation, sorting, or other options by editing the instruction. See Edit a REPEAT Instruction.
(To edit the contents of the repeated dialog, see Edit a Custom Dialog.)
Note:
You can find the total sum of a series of repeated Number variables, such as a list of dollar amounts. See Get
Sum Totals for Repeated Number Variables for details.
In Microsoft Word, you can also insert a REPEAT instruction either by clicking on the HotDocs drop-down menu
in the HotDocs toolbar and choosing REPEAT Field, or by right-clicking in the template and choosing REPEAT
Field from the shortcut menu.

Copyright 2010 HotDocs Ltd. All rights reserved

315

Help Topics for HotDocs Developer 10

Edit a REPEAT Instruction

You can make changes to REPEAT instructions, including editing the repeated dialog's contents, adding a filter, choosing
an answer-sorting order, and adding punctuation to the list of answers.
To edit a REPEAT instruction

1. Position the cursor in the opening REPEAT instruction.

2. Click the

REPEAT Field button. The REPEAT Field dialog box appears with the repeated dialog already

selected.

3. Make any of the following optional changes:

Click the
Edit Component button to edit the dialog (including adding or removing variables from the dialog
and selecting presentation options for the dialog.) (See Change a Dialog's Options.)
Click the Format drop-down button and select a punctuation format. (See Punctuate a Sentence-Style List.)
Click Show Advanced to specify a sorting order and add a filter. (See Sort a List of Answers and Filter a List of
Answers.)
Note:
If you're using a complicated series of REPEAT instructions, you can match REPEAT instructions with END REPEAT
instructions. See Match Opening Instructions with Closing Instructions for details. You can also assign color coding to
REPEAT instructions to help you view relationships between them and other instructions in the template. See Assign
Colors to Fields and Instructions in Templates.

Copyright 2010 HotDocs Ltd. All rights reserved

316

Help Topics for HotDocs Developer 10

Choose a Presentation Style for the Repeated Dialog

You can choose how a repeated dialog appears during the interview, either by presenting the list as a series of dialogs or
as a single spreadsheet with multiple entry points.
Your options include:
Repeated Series causes a regular dialog to appear with an answer field for each variable. When the user answers
the questions in the dialog, they can either click the
they can click

Add Another button to add another repetition to the dialog, or

Next to move to the next dialog in the interview.

Spreadsheet causes a single dialog to appear with a column for each variable and an unlimited number of rows.
Users fill in as many rows as they need. (The spreadsheet format lets users see all the answers at one time and
makes it easier to change answers. However, a dialog with several variables can make a spreadsheet too large to
view easily.)
To make a repeated dialog appear as a series

1. Edit the REPEAT instruction. (See Edit a REPEAT Instruction.) The REPEAT Field dialog box appears.
2. Click the

Edit Component button to open the Dialog Editor.

3. Click the Style drop-down button and choose Repeated Series.

4. Optionally, assign a custom title to each repetition in the dialog. See Customize REPEAT Titles for details.
5. Optionally, enter custom label text you want to use on the

Add Another button in the Add button text box. (This

button appears on a repeated series dialog. Users click it to add a new repetition to the series of answers.)

To make a repeated dialog appear as a spreadsheet table

1. Edit the REPEAT instruction. (See Edit a REPEAT Instruction.) The REPEAT Field dialog box appears.
2. Click the

Edit Component button to open the Dialog Editor.

3. Click the Style drop-down button and choose Spreadsheet.

4. Optionally, limit the number of visible rows in the spreadsheet by entering a number in the Rows to display box.
(See Control How Many Rows are Visible in a Spreadsheet Dialog for details.)

5. Optionally, select Hide buttons to keep the Edit Row, Insert Row, and Delete Row buttons from appearing just
below the spreadsheet. (Users can still access these commands either by right-clicking on the spreadsheet row, or
by choosing the commands from the Edit menu.)
Caution:
If the repeated dialog contains a multiple-selection Multiple Choice variable, the dialog must use the Repeated Series
styleit cannot use the Spreadsheet style. (See Customize a Multiple Choice Variable.)
Note:
For information on using the Spreadsheet on Parent option, see Display a Child Dialog Directly on the Parent
Dialog.
You can control the width HotDocs uses for the columns in a spreadsheet. See Specify the Width of Answer
Fields in the Interview.

Copyright 2010 HotDocs Ltd. All rights reserved

317

Help Topics for HotDocs Developer 10

Customize REPEAT Titles

You can customize the titles used for each repetition in a repeated series of dialogs. For example, perhaps you need to
ask the user for a list of beneficiaries. By default, HotDocs displays this list in the interview outline using an incremented
number, followed by the dialog title:

This approach may work in some situations, but in others, it may be better to customize the title for each repetition so
the user knows what's in that particular dialog. For example, maybe you want the topmost icon in the list to use a generic
title (like List of Beneficiaries), but you want the name of the beneficiary to appear for each individual repetition in the
interview. This way, the user can easily review what's in each dialog, like this:

To accomplish this, you must do the following:

Assign a generic label (such as List of Beneficiaries) to the repeated series.
Create a computation script that merges the user's answer to Beneficiary Name in the title. If no answer has been
given, the script will merge other text that will help the user know the dialog is unanswered. (Otherwise, HotDocs will
merge an unanswered variable placeholder in the title.)
To customize the title of the repeated dialog

1. Edit the repeated dialog and select Repeated Series at the Style drop-down list. (See Edit a Custom Dialog and
Choose a Presentation Style for the Repeated Dialog.)

2. Enter a generic title in the Label box.

3. Right-click in the Title box and choose Variable Field from the shortcut menu.
4. Choose Computation as the Variable type and enter a name in the Name box.
5. Click the

Edit Component button. The Computation Editor appears.

6. In the Script box, enter the script that tests whether the variable you want to use in the title is answered. The script
should also merge the text you want to be used in the title. An example script would be:
VALUE(Beneficiary Name, "Next Beneficiary")
Copyright 2010 HotDocs Ltd. All rights reserved

318

Help Topics for HotDocs Developer 10

7. Click OK at both the Computation Editor and at the Variable Field dialog box. The variable is merged in the title
field.

8. Click OK to close the Dialog Editor.

Copyright 2010 HotDocs Ltd. All rights reserved

319

Help Topics for HotDocs Developer 10

Punctuate a Sentence-Style List

If youre inserting a list in sentence style, you must choose the punctuation you want for the list. If you dont choose a
punctuation style, the list runs together without any punctuation or spacesfor example, DanielNathanEmilyKate. Once
you select a punctuation style, HotDocs punctuates the list automaticallyfor example, Daniel, Nathan, Emily, and Kate.
When assigning a format, note that formats with all capital letters only capitalize the conjunction in the sentence, for
example, the word AND. Individual answers in the list are either merged as the user types them or merged as you
have formatted them using a variable-level example format. See Format the Variable and How Example Formats are
Interpreted.
To punctuate a list

1. At the template, edit the REPEAT instruction you want to punctuate. (See Edit a REPEAT Instruction.) The REPEAT
Field dialog box appears.

2. Click the Format drop-down button.

3. Select a punctuation style, as explained in the following table:
To

Do This

Insert a comma even when Choose a, and b.

there are only two items
Punctuate a list, but keep
and from being used

Choose a, b.

Keep the last comma

before and from being
inserted

Choose a, b and c.

Use or instead of and

Choose a, b, or c.

Use semicolons instead of Choose a; b; and c.

commas between list items
Enter your own
punctuation style

Type your style in the Format box. Base it on the other formats in the list. For
example, you could use or or some other text instead of and, or you could use a
semicolon instead of a comma.

Note:
If you want to create a list in a column, see Make a List Appear as one or More Columns.
You can punctuate the same list differently at another place in the document. Choose a punctuation style
separately at each REPEAT instruction field.

Copyright 2010 HotDocs Ltd. All rights reserved

320

Help Topics for HotDocs Developer 10

Sort a List of Answers

You can have HotDocs alphabetize your list automatically, in either ascending or descending alphanumeric order (for
example, A to Z and 1 to 9). You can sort based on any repeated variable. If theres more than one repeated variable in
the REPEAT instruction, you can sort on two levelsfor example, first on State, then on City (or cities within the state).
To sort a repeated list of answers

1. At the template, edit the REPEAT instruction you want to sort. (See Edit a REPEAT Instruction.) The REPEAT Field
dialog box appears.

2. Click Show Advanced. The dialog box changes to show sorting and filtering options.
3. Click the Sort by drop-down button and choose the variable on which you want to sort.
4. Select Ascending or Descending.
5. Optionally, to sort on a second level, select a variable at the Then By box and choose either Ascending or
Descending.
When you close the REPEAT Field dialog box, you will see the names of the variable(s) on which you are sorting added
to the REPEAT instruction.
Note:
You can sort the same list differently at another place in the document. Edit that specific REPEAT instruction and
specify the sort order you want, following the instructions given above.

Copyright 2010 HotDocs Ltd. All rights reserved

321

Help Topics for HotDocs Developer 10

Filter a List of Answers

You can create a computation script that filters a list so only the entries that meet some condition are merged into the
assembled document. For example, you could create a list of all the children in a family and then limit the list to include
only those who are under the age of 18.
To filter a list

1. At the template, edit the REPEAT instruction. (See Edit a REPEAT Instruction.) The REPEAT Field dialog box
appears.

2. Click Show Advanced. The dialog box changes to show sorting and filtering options.
3. Click the

Edit Component button next to the Filter by drop-down list. The Computation Editor appears.

4. Type a name for the filter in the Variable name box.

5. In the Script box, type the condition that has to be true for an entry to be included in the list. (The variable in the
condition must also be in the repeated dialog.) For example:
Dependent Age <= 17

6. Click OK to return to the REPEAT Field dialog box.

7. Optionally, if you've assigned a sorting option and you want the sorting to happen before the filter is applied, select
Sort first.

8. Click OK again to return to the template.

Note:
A filter can be as complicated as it needs to be, but it must result in either true or false. For example, the expression
YEARS FROM( Child's Birth Date, TODAY ) produces a number (the age of a person), not a true or false
valueit is not a filter. But the expression YEARS FROM( Child's Birth Date, TODAY ) <= 17 can only result
in true or false. It can correctly filter all children under the age of 18 from a list.

Copyright 2010 HotDocs Ltd. All rights reserved

322

Help Topics for HotDocs Developer 10

Control How Many Rows are Visible in a Spreadsheet Dialog

By default, when displaying a spreadsheet dialog, HotDocs always shows 10 rows of the spreadsheet. If you need to
show more or less than this number of rows, you can enter a specific number at the Dialog Editor. (This option doesn't
limit the number of answers a user can enterit only controls the number of answers that can be viewed at any given
time.)
To change the number of viewable rows in a spreadsheet

1. Edit the REPEAT instruction. (See Edit a REPEAT Instruction.) The REPEAT Field dialog box appears.
2. Click the

Edit Component button to open the Dialog Editor.

3. Click the Style drop-down button and choose Spreadsheet.

4. In the Rows to display box, either type a number, or click the up or down arrows to select a number.

Copyright 2010 HotDocs Ltd. All rights reserved

323

Help Topics for HotDocs Developer 10

Limit the Number of Answers Allowed for a Repeated Dialog

At times, you may want users to enter only a specific number of answers in a list. You can use the LIMIT instruction to
limit the number of times a dialog is repeated. Once the limit is reached, users can no longer enter anymore answers.
To limit the number of answers that can be entered

1. Open the repeated dialog for editing. (See Edit a Custom Dialog.) The Dialog Editor appears.
2. Click the Script tab. The window changes to show scripting options.
3. Drag LIMIT NUM from the Instruction models list into the Script box.
4. Replace the NUM placeholder with the maximum number of answers you want the user to enter.
Note:
You can let the user change the limit each time a document is assembled. To do this, replace NUM with a
Number variable. Make sure the Number variable gets answered before the REPEAT instruction is processed.
To control the number of viewable rows in a spreadsheet (but still allow users to enter as many answers as they
need), enter the number in the Rows to display box. (Make sure Spreadsheet is selected as the Style.)

Copyright 2010 HotDocs Ltd. All rights reserved

324

Help Topics for HotDocs Developer 10

Get Sum Totals for Repeated Number Variables

You can use a Computation variable to find the sum total of a repeated Number or Computation variable. For example,
you may need to find the grand total of a series of dollar amounts.
To total a column of number variables

1. Create a computation that contains the expression SUM( NUM_VAR ) if the repeated variable you are totaling is a
list of Number variables, or SUM( COMPUTATION VAR ) if you are totaling a list of Computation variables. (See
Customize a Computation Variable.)

2. Replace the NUM_VAR or COMPUTATION_VAR placeholder with the name of the repeated Number or
Computation variable, respectively.

3. Insert the Computation variable containing the SUM instruction where you want the total to appearfor example, at
the bottom of a column of numbers.

Copyright 2010 HotDocs Ltd. All rights reserved

325

Help Topics for HotDocs Developer 10

Use a Word Processor Table to Display a List

You can insert a list of answers into a word processor table. As the user provides answers during the interview, HotDocs
automatically adds rows to the table.
When you insert a REPEAT instruction in a table, HotDocs does not include an END REPEAT instructionthe end of the
row signifies the end of the repeat. Additionally, you can repeat only a single row of the table, and each row must have
the same number of columns. Finally, to REPEAT the contents of a single cell of a table, you must use a Computation
variable. See Create a REPEAT Instruction Using a Computation Variable.
To insert a list into a word processor table

1. Create a table in your word processor with a single row and a column for each repeating variable. (If you want to use
a row for column headings, create a two-row table and put the headings in the first row.) (See your word processor's
documentation for information on creating tables.)

2. Insert the variables in the table, with one variable per column. (See Insert a Variable Field in a Text Template.)
3. Once your variables are created, position the cursor in the first table cellbefore the first variable.
4. Click the

REPEAT Field button. The REPEAT Field dialog box appears.

5. Click the Dialog drop-down button and select the dialog you want to repeat. (To create a new dialog, click the
Edit Component button. See Gather Questions into a Custom Dialog.)

6. Select a repeat style for the dialog. (See Choose a Presentation Style for the Repeated Dialog.)
7. When you are finished, click OK at the REPEAT Field dialog box. The REPEAT instruction is inserted in the table,
like this:

Copyright 2010 HotDocs Ltd. All rights reserved

326

Help Topics for HotDocs Developer 10

Make a List Appear as one or More Columns

Sometimes it makes more sense to have your list of answers appear in columns, rather than in a punctuated sentence. If
you want to make the list appear in a column, include a hard return after the text in the REPEAT instruction.
For example, the following script, inserted directly in the template:
REPEAT Childrens Names
Name of Child
END REPEAT
would result in a list like this:
Sarah
Jackson
Madi
Adam
If there are two or more variables in the REPEAT instruction, you can separate them with tabs so they appear in multiple
columns. The following script:
REPEAT Childrens Information
Name of Child
Age of Child
END REPEAT
would create a list like this:
Sarah
14
Jackson
11
Madi
7
Adam
2
Note:
By default, when HotDocs inserts a REPEAT instruction in the template, it includes a return character after the
instruction. During assembly, as the instruction is processed and removed from the assembled document, this return
character is likewise removed. If you would prefer to keep this character from being merged, or if you want to merge
a return character only when repeating an entire paragraph, you can specify an option that controls this. See Control
When Returns Are Inserted After Instructions in Text Templates and Understand How Smart Returns are Inserted After
Instructions.

Copyright 2010 HotDocs Ltd. All rights reserved

327

Help Topics for HotDocs Developer 10

Count the Number of Entries in a List

You can use a computation script to determine how many times a user answers a repeated dialog. You can also use a
built-in Number variable that numbers a list of answers automatically.
To determine the number of entries in a list

1. Create a Computation variable containing the expression COUNT( DIALOG ). (See Customize a Computation
Variable.)

2. Replace the DIALOG placeholder with the name of the repeated dialog.
3. Optionally, insert this Computation variable wherever you want the number of entries to appear. (You don't have
to insert the Computation variable in the template. Often, template developers simply use the COUNT( DIALOG )
expression as a way to keep track of the number of answers without ever inserting the actual number in the
template.)
To number a list automatically

1. At the template, position your cursor before the variable in the list you want to number.
2. Insert a Number variable. (See Insert a Variable Field in a Text Template and Customize a Number Variable.)
Instead of typing a variable name, however, click the Variable drop-down button and select COUNTER.

3. Click OK.
4. Add any punctuation or spaces you want to go with the number. For example:
The children are listed, as follows:
REPEAT Childrens Names
COUNTER. Name of Child, Age of Child
END REPEAT

Copyright 2010 HotDocs Ltd. All rights reserved

328

Help Topics for HotDocs Developer 10

Retrieve a Specific Answer from a List

At times, you may need to retrieve a specific answer from a list of answers. For example, maybe you have created a list of
employees, but later in the document you need to merge the name of just the second employee in the list. You can do this
by using explicit indexing. To do this, you enter the index number of the answer you need between brackets, just after the
variable name.
To use explicit indexing

1. Insert the variable whose value you want to retrieve in the template text. (Make sure the variable is repeated
someplace earlier in the template.)

2. Once the variable is inserted, place your cursor immediately after the variable name and enterbetween brackets
the index number of the repetition you want to retrieve. This index should be before any additional field formatting
notations, for example:
The second alternate will be Alternate Board Member[2]:LIKE THIS.
Note:
To set an explicit index for a variable in a form field, first create the variable. Then select the field and open the
Field Properties dialog box. Enter the explicit index in the Variable box, immediately after the variable name
(like in the example above).
Normally, a repeated variable must be inside a REPEAT instruction, but when you a specify a particular list entry
this way, the REPEAT instruction should not be included.
The Maximum WHILE iterations limit controls the maximum-allowed explicit index. (You set this value at the
Component File Properties dialog box. See Change Component File Properties for details.)

Copyright 2010 HotDocs Ltd. All rights reserved

329

Help Topics for HotDocs Developer 10

Add a Comment to a Variable or Instruction Field

When you insert a variable or instruction in a template, you can add a comment to the insertion field. Comments are
useful when you want to document information about the variable or instruction you are inserting and you want those
comments to be viewable by anyone editing the text of the template.
Comments can also be useful when viewing a markup view of the templatethe comment can describe (in easy-tounderstand terms) the purpose of the field or provide a more reader-friendly name for the field.
Note:
If you want to add comments to a specific component, enter it at the Notes tab of the component editor. See Add
Notes to Components for details.
To add a comment to a variable or instruction field

1. Insert a new variable or edit an existing variable. (See Insert a Variable Field in a Text Template or Edit a Variable.)
The Variable Field dialog box appears. Or, insert a new instruction or edit an existing instruction. The instruction
field dialog box appears.

2. Click Show Advanced. The view expands to show advanced options.

3. Enter your comments in the Comment box.
When you click OK, HotDocs merges the field, with the comments merged after the variable name, like this: Employee
Salary //Calculates biweekly salary based on hourly rate.
Note:
To merge a comment in an END instruction (such as END IF, END REPEAT, OR END SPAN), place your cursor
before the closing chevron, enter two forward slashes (//), and type your comment, like this: END IF //Closing.
If the END instruction contains a Keep Return code ( | ), enter the comment before the return code, like this: END
IF //Closing |.

Copyright 2010 HotDocs Ltd. All rights reserved

330

Help Topics for HotDocs Developer 10

Understand How Smart Returns are Inserted After Instructions

By default, each time you insert any instruction (IF/END IF, REPEAT/END REPEAT, SPAN/END SPAN, INSERT, or
ASK) in a template, HotDocs adds a return following the instruction. Then, when HotDocs assembles the template
and processes the instruction, it removes the return it inserted. To some, this insertion of returns creates problems or
confusion in automating the template because it sometimes makes the template text difficult to read and understand,
especially when instructions (and their subsequent returns) within a paragraph sometimes break the paragraph into
separate lines of text.
To accommodate this, HotDocs allows you to choose whether to insert returns following these instructions. (See Control
When Returns Are Inserted After Instructions in Text Templates.). Specifically, you can:
Always insert a return after an instruction.
Never insert a return after an instruction.
Use "smart" return insertion.
The first two options behave exactly as expectedHotDocs will either always insert a return (and remove it during
assembly) or never insert a return, depending on which of the two options you choose.
The behavior of third option, using smart returns, depends on how and where you're inserting the instruction.
If text you select represents a complete paragraph (meaning there's a paragraph mark at the end of the selected text),
HotDocs will insert a return character after the instruction. In the following example, brackets ([]) indicate where text
selection begins and ends. Note that the closing bracket ends on the line after the paragraph mark ():
Here is a paragraph.
[Here is another paragraph.
]Here is a third paragraph.
Would produce a section of conditional text that looks like this:
Here is a paragraph.
IF Instruction
Here is another paragraph.
END IF
Here is a third paragraph.
However, if the text you select is within a paragraph, HotDocs will not insert a return character. So, in the following
example, when you insert the REPEAT instruction, HotDocs does not insert a return because the insertion is happening in
the middle of a paragraph. There is no paragraph break at the end of the insertion:
The client, Client Name, has the following children: REPEAT Children:a, b, and
cChild NameEND REPEAT. These children live with the client and are covered under
the provision.
At times, you may simply insert an instruction without first selecting text, or perhaps you may select some text but not
include the paragraph mark in the selection. If HotDocs detects an existing paragraph break immediately after the
instruction, it includes a Keep Return code (or vertical bar (|) ) at the end of the instruction. The code tells HotDocs to not
delete the return when it assembles the document. So, the following example, where brackets indicate text selection:
Here is a paragraph.
[Here is another paragraph.]
Here is a third paragraph.
would produce the following automation:
Here is a paragraph.
IF InstructionHere is another paragraph.END IF|
Here is a third paragraph.

Copyright 2010 HotDocs Ltd. All rights reserved

331

Help Topics for HotDocs Developer 10

Note that the Keep Return code (|) in the END IF instruction indicates to HotDocs to keep the return character when it
assembles the document.
Caution:
HotDocs' capacity to delete both an IF instruction and the return that follows it is very important in some situations. If
an optional paragraph includes numbering, it is difficult to condition out the entire paragraph and its numbering without
putting the IF on a separate line before the paragraph. It can be done, but the template looks odd, since the IF is inside
the numbering of the paragraph.

Copyright 2010 HotDocs Ltd. All rights reserved

332

Help Topics for HotDocs Developer 10

Assign Colors to Fields and Instructions in Templates

Note:
Click here if you are using WordPerfect and the HotDocs Navigation toolbar doesn't appear in your template.
You can assign custom colors to the different types of fields in a template. This can help you more quickly identify
sections or parts of your template as you are automating. Additionally, you can assign colors to IF, REPEAT, and SPAN
instructions in your templates. Assigning different combinations of these colors can help you differentiate levels of nesting
as well as help you better view individual pairs of instructions.
By default, HotDocs assigns its own colors; however, you can customize the colors at the HotDocs Options dialog box.
(See Define Field Colors.)
To apply custom colors to template fields and instructions

1. Open the template for editing. (See Edit a Template.)

2. Click the

Apply Colors button. The Apply Colors dialog box appears.

3. Select one of the following options:

Choose None to make all variable and instruction fields black.
Choose Regular to mark all variable and instruction fields using a custom color specific to that field type. For
example, all variables will be marked with one color, all IF instructions will be marked with a different color, all
REPEAT instructions will use a different color, and so forth.
Choose Nested to mark each level of IF and REPEAT instructions using a custom color. (For example, all firstlevel IF instructions will use a specific color, while all second-level instructions will use a different color, and so
on.)
Choose Sequential to mark each IF and REPEAT instruction field using a custom color. (For example, the
first instruction in a template will be marked using one color, while the next instruction will be marked using a
different color, and so on.)
Note:
If you change your default colors, or if you receive templates from other developers whose colors are different
from yours, you can click the

Apply Colors button to update existing templates with your custom colors.

If you're using Microsoft Word, you can also apply colors by clicking on the HotDocs drop-down menu in the
HotDocs toolbar and choosing Apply Colors. (To access this menu button in Word 2007 and later, click the
HotDocs drop-down button.)

Copyright 2010 HotDocs Ltd. All rights reserved

333

Help Topics for HotDocs Developer 10

Use Labels to Identify Instructions

Note:
Click here if you are using WordPerfect and the HotDocs Navigation toolbar doesn't appear in your template.
You can assign labels to IF, REPEAT, and SPAN instructions to help you identify pairs or groups of instructions in a text
template. When you label fields, you can choose to merge just a numeric name in a field or you can choose to merge
a name as well as the level of nesting. This can help you match opening instructions with closing, as well as help you
determine the level of nesting within an instruction.
Field labels are merged as comments in the field.
The following example shows a series of nested REPEAT instructions that have been labeled. The first instruction,
REPEAT Editor Information, is labeled with the number 1, since it's the first REPEAT in the template. This same
instruction is also assigned the level number of L1, since it's the first level of the REPEAT instruction. The END REPEAT
is likewise labeled so that you can easily match them when examining the contents of the template.
For each subsequent instruction, HotDocs increments the field number. Additionally, if the next REPEAT instruction is
nested (which, in this example, it is), HotDocs increments the nesting level number. Each END REPEAT instruction is
likewise labeled.
REPEAT Editor Information // [1:L1]
Editor: Editor First Name Editor Last Name
REPEAT Author Information // [2:L2]
Author: Author First Name Author Last Name
REPEAT Book Information // [3:L3]
Title Edited / Date Completed: Book Title / Date Completed:03 JUN 90
END REPEAT // [3:L3]
END REPEAT // [2:L2]
END REPEAT // [1:L1]
When assigning labels to fields, you can choose whether to include both the field number and the nesting level. You can
also choose to merge just one or the other.
Finally, you can have HotDocs assign the hidden text property to these labels (as well as any other comments you've
assigned to fields in the template.) When this property is assigned, comments and labels will be hidden and shown,
depending on whether you are viewing hidden text in the template. (For information on viewing hidden text, see your word
processor's documentation.)
To label instructions

1. At the text template, click the

Label Fields button. The Label Fields dialog box appears.

2. Select an option, based on the following information:

To assign a numeric name to each instruction, select Label IF, REPEAT, and SPAN instructions.
To have HotDocs identify the level of nesting for each instruction, select Identify level of nested IF, REPEAT,
and SPAN instructions.
To apply the hidden text property to comments and labels, select Place comments (including field labels)
in hidden text. Once applied, you can quickly show and hide your comments and labels by choosing the
appropriate command at the word processor.

3. Click OK. HotDocs applies the labels you have selected to any instructions in the template.
Note:
SPAN fields are supported in Microsoft Word only.
To clear labels from fields or show comments once again, click the
options, and click OK.
Copyright 2010 HotDocs Ltd. All rights reserved

Label Fields button, clear all of the

334

Help Topics for HotDocs Developer 10

If you're using Microsoft Word, you can also label fields by clicking on the HotDocs drop-down menu in the
HotDocs toolbar and choosing Label Fields.

Copyright 2010 HotDocs Ltd. All rights reserved

335

Help Topics for HotDocs Developer 10

Match Opening Instructions with Closing Instructions

Note:
Click here if you are using WordPerfect and the HotDocs Navigation toolbar doesn't appear in your template.
Every IF, REPEAT, and SPAN instruction inserted in a template must include an END IF, END REPEAT, or END SPAN
instruction. Without both of these instructions, you will receive an error when you attempt to assemble a document. (The
one exception is a repeated row in a table. See Use a Word Processor Table to Display a List.) However, sometimes
during the course of editing a template, you may inadvertently delete or move part of the instruction. Doing so will cause
errors when you attempt to assemble the document. To troubleshoot errors like this, you can have HotDocs match the
different parts of the instruction. Likewise, if you have an intricate section of nested instructions, you can pair these
different parts of the instruction.
To match opening instructions with their closing instructions

1. Open the template for editing. (See Edit a Template.)

2. Place the cursor inside either the opening instruction or the closing instruction. For example, if you're trying to find
the opening instruction of a REPEAT, place your cursor in the END REPEAT instruction.

3. Click the

Match Fields button. HotDocs moves your cursor to the corresponding instruction.

Note:
When editing instructions in a computation script, you can place your cursor in either the opening or closing
instruction and press Ctrl+M. This will move your cursor to the corresponding instruction.
If you're using Microsoft Word, you can also match fields by clicking on the HotDocs drop-down menu in the
HotDocs toolbar and choosing Match Fields.

Copyright 2010 HotDocs Ltd. All rights reserved

336

Help Topics for HotDocs Developer 10

Chapter 23: Using Computations to Create Lists

Create a REPEAT Instruction Using a Computation Variable
Instead of inserting a REPEAT instruction directly in a template to generate a list of answers, you can use a REPEAT
instruction in a Computation variable to create your list of answers. One reason for this is if your list of answers must
appear in a single table cell. Also, using a computation allows you to quickly insert a list in more than one location in
the template. (One drawback of this approach is that punctuating, sorting, and filtering will be applied wherever the
computation is insertedthe list won't appear differently in different parts of your assembled document.)
To use a REPEAT instruction in a computation

1. At the template, create a Computation variable. (See Customize a Computation Variable.)

2. In the Script box, type either empty quotation marks ( "" ) or a zero (0) as the starting value for the computation.
(These set the repeated value to nothing if the result will be text or zero if the result will be a number.)

3. Enter a REPEAT instruction, followed by the dialog name.

4. Enter the RESULT expression, followed by the names of the variables whose answers you want to merge. (Use the
plus ( + ) operator to add variables, text, space characters (including a hard return), and so forth, to whats being
repeated.)

5. Enter an END REPEAT instruction. An example of a possible script would be:

""
REPEAT Tour Information
RESULT + Name of City + ", " + Venue + "
"
END REPEAT
Note:
When you use a script to merge a list of answers that have been gathered using a REPEAT, you must first set the
computation to a starting value. This value must be a 0 if the result will be a number, or it must be "" if the result will be
text.

Copyright 2010 HotDocs Ltd. All rights reserved

337

Help Topics for HotDocs Developer 10

Punctuate a List Using a Computation Variable

When you use a computation to generate a repeated list, you can use the FORMAT instruction to punctuate the list in
sentence style.
To punctuate a repeated list in a computation

1. Create a Computation variable that contains your REPEAT instruction. (See Create a REPEAT Instruction Using a
Computation Variable.)

2. Drag FORMAT "LIST_FORMAT" from the Instruction models list into the Script box on a line of its own, after the
REPEAT instruction but before the RESULT expression.

3. Replace the LIST_FORMAT placeholder with a punctuation format (such as "A, B, and C"). An example would be:
""
REPEAT Tour Information
FORMAT "a; b; and c"
RESULT + Name of City + ", " + Venue
END REPEAT

Copyright 2010 HotDocs Ltd. All rights reserved

338

Help Topics for HotDocs Developer 10

Sort a List Using a Computation Variable

If you are using a Computation variable to create a list of answers, you can sort answers in the list using the ASCEND
VAR and DESCEND VAR instructions. These instructions sort a list from A to Z, and 1 to 9.
To sort a REPEAT instruction in a Computation variable

1. Create a Computation variable that contains your REPEAT instruction. (See Create a REPEAT Instruction Using a
Computation Variable.)

2. Drag ASCEND VAR or DESCEND VAR from the Instruction models list into the Script box on a line of its own,
after the REPEAT instruction but before the RESULT expression.

3. Replace the VAR placeholder with the repeated variable you want to sort on. An example would be:
""
REPEAT Tour Information
ASCEND Name of City
RESULT + Name of City + ", " + Venue + "
"
END REPEAT
Note:
When you use a script to merge a list of answers that have been gathered using a REPEAT, you must first set
the computation to a starting value. This value must be a 0 if the result will be a number, or it must be "" if the
result will be text.
To add a second sort level, insert a second ASCEND VAR or DESCEND VAR instruction below the first.

Copyright 2010 HotDocs Ltd. All rights reserved

339

Help Topics for HotDocs Developer 10

Filter a List Using a Computation Variable

If you are using a Computation variable to create a repeated list, you can filter the REPEAT instruction in a Computation
variable by using the FILTER COMPUTATION_VAR instruction. (See Filter a List of Answers.)
A filter can be as complicated as it needs to be, but it must result in either true or false. For example, the expression
YEARS FROM( Child's Birth Date, TODAY ) produces a number (the age of a person), not a true or false value
it is not a filter. But the expression YEARS FROM( Child's Birth Date, TODAY ) <= 17 can only result in true or
false. It can correctly filter all children under the age of 18 from a list.
To filter a REPEAT instruction in a Computation variable

1. Create a Computation variable that contains your REPEAT instruction. (See Create a REPEAT Instruction Using a
Computation Variable.)

2. Once you have added the REPEAT instruction to the script, drag FILTER COMPUTATION_VAR from the
Instruction models list into the Script box. (Place this model on a line of its own, after the REPEAT instruction and
any punctuation or sorting instructions but before the RESULT expression.)

3. Select Computation Variable at the Components list.

4. Click

New Component to open a second Computation Editor.

5. Assign a name to the computation.

6. Type the filtering instructions in the Script box, and click OK. HotDocs returns you to the REPEAT computation and
the new variable is added to the Components list.

7. Drag the new variable onto the COMPUTATION_VAR placeholder and complete the REPEAT instruction. An
example of a possible script would be:
""
REPEAT Tour Information
ASCEND Tour City
FILTER New York Appearances
RESULT + Tour City + ", " + Tour State + ", " + Tour Venue + "
"
END REPEAT
Note:
The New York Appearances filter contains the script, Tour State CONTAINS "new york"
Note:
When you use a script to merge a list of answers that have been gathered using a REPEAT, you must first set the
computation to a starting value. This value must be a 0 if the result will be a number, or it must be "" if the result will be
text.

Copyright 2010 HotDocs Ltd. All rights reserved

340

Help Topics for HotDocs Developer 10

Tips on Using Computations to Create Lists

There are a few things to note when using a computation to create a list of answers.
In the Script box, before the REPEAT instruction, you must set the computation to a starting value. Most often this
value will be "nothing"either two quotation marks with nothing between them ("") if the result of the computation
will be text, or a zero (0) if the result will be a number.
Inside the REPEAT instruction, begin the part that is being repeated (the part with the repeated variable or other
value in it) with RESULT followed by a plus character. This RESULT keyword updates the computation as it goes
through each repetition. For example:
""
REPEAT Decedent Information
RESULT + Decedent Name + ", " + Date of Death + "
"
END REPEAT
Also, there are four special models you can use in a computation to get information from a REPEAT instruction.
COUNT( DIALOG ) counts the number of repetitions in a list.
COUNTER gives you the number of the current repetition.
SUM( COMPUTATION_VAR ) totals a repeating Computation variable.
SUM( NUM_VAR ) totals a repeating Number variable.

Copyright 2010 HotDocs Ltd. All rights reserved

341

Help Topics for HotDocs Developer 10

Chapter 24: Creating Lists Within Lists

Overview: Create Lists Within a List
You can create a sublist of answers by nesting one REPEAT instruction inside another. For example, you could create a
list of children inside a list of parents, like this:
Paul Linares
Jack
McKenzie
Abby
Lisa White
Kevin
Logan
Savannah
Gregory Hurley
Randy
Jessica
The list of parents (Paul Linares, Lisa White, and Gregory Hurley) is the first repeat level. The sublists of children are the
second repeat level. Repeats can be nested up to four levels deep. You can nest repeats directly in a text template or you
can nest repeats using a Computation variable in a text or form template.
You can use instructions or expressions with nested REPEAT instructions if you use a Computation variable. And, you
can merge a particular answer from a nested repeat list into a text or form document.
Nested repeats cannot be used if you are retrieving answers from a database.

Copyright 2010 HotDocs Ltd. All rights reserved

342

Help Topics for HotDocs Developer 10

Create a List Within a List

Sometimes you may need to gather a list of answers that must appear within a larger list of answers. For example,
perhaps you need a list of your client's real estate holdings. For each holding, you also need property descriptions and
improvements. You can create these lists by nesting one REPEAT instruction inside another.
There are two parts to creating a list within a list:
First, you must select all the template text you want repeated and insert the required REPEAT instruction fields.
Second, you must edit the properties of the parent (or main) dialog and insert the nested dialog(s) into it.
The first step in creating a list within a list is to REPEAT each level of text in the template. (See Create a REPEAT
Instruction to Gather a List of Answers.)
To create a nested repeat

1. Create the variables you want repeated and insert them into the template. (See Insert a Variable Field in a Text
Template.)

2. Gather the variables you want repeated into dialogs. (Make sure you choose a repeat style for each dialog. See
Gather Questions into a Custom Dialog.)

3. At the template, select all the template text and variables you want repeated (including all repeat levels) and click the
REPEAT Field button. The REPEAT Field dialog box appears.

4. Select the dialog for the first (or top) level of the repeat from the Dialog drop-down list and click OK. HotDocs inserts
the REPEAT instruction in the template. (Even though you have selected all levels of the repeat in the template text,
this dialog should only contain the variables from the first level of the repeat.)

5. At the template, select the second level of repeated text and variables, as well as any subsequent levels of
information (do not select the END REPEAT instruction) and click the
dialog box appears again.

REPEAT Field button. The REPEAT Field

6. Select the dialog for the second level of the repeat from the Dialog drop-down list and click OK.
7. Repeat this process for each subsequent list.
The second part in nesting REPEAT instructions is to edit the contents of each dialog and insert each repeated
dialog (except the dialog for the first repeat level) into the preceding levels dialog.

8. Edit the dialog in the first (or top) level of the repeat. (See Edit a Custom Dialog.) The Dialog Editor appears.
9. Drag the dialog for the second repeat level from the Available Components list into the Contents box and click
OK.

10. Repeat this process until each dialog in the nested repeat (except for the first) is inserted into the preceding levels
dialog.
Note:
By default, a child dialog appears as a button on the parent dialog. You can change the style of a repeated dialog
to Spreadsheet on parent, which lets users enter the nested list of answers while viewing its parent dialog. (See
Display a Child Dialog Directly on the Parent Dialog.)
If you are nesting REPEAT instructions in a form template, the REPEAT instructions must be placed in a
Computation variable. See Nest REPEAT Instructions Using a Computation Variable for details.

Copyright 2010 HotDocs Ltd. All rights reserved

343

Help Topics for HotDocs Developer 10

Display a Child Dialog Directly on the Parent Dialog

By default, when you insert a repeated dialog on its parent dialog, it creates a button which the user must click in order to
answer the questions in the dialog. However, HotDocs can display the inserted dialog directly on its parent dialog so users
can viewand answerboth dialogs without changing the view. The inserted dialog will appear on its parent dialog as a
spreadsheet.
Note:
Any dialog elements in the inserted child dialog will not appear on the parent dialog.
The following is an example of a nested repeated dialog. The Book Information spreadsheet is inserted in the Author
Information dialog, and both are displayed simultaneously.

To display a spreadsheet dialog on its parent

1. Edit the inserted dialog (or the dialog you want to appear as a spreadsheet on its parent dialog). (See Edit a Custom
Dialog.) The Dialog Editor appears.

2. Click the Style drop-down button and select Spreadsheet on Parent.

3. Optionally, enter a number in the Rows to display box to control the number of viewable rows that appear in the
dialog.

4. Click OK.

Copyright 2010 HotDocs Ltd. All rights reserved

344

Help Topics for HotDocs Developer 10

Nest REPEAT Instructions Using a Computation Variable

You can use a Computation variable to nest REPEAT instructions. This allows you to use other instructions or
expressions to create more complex repeated dialogs.
For example, perhaps you want to use a computation to generate a list of different departments within a company. Then
you can list the names of employees within each department.
To nest REPEAT instructions in a Computation variable

1. Create a Computation variable and enter the script containing the nested repeats in the Script box. (See Customize
a Computation Variable.) An example of a possible script would be:
""
REPEAT Department Information
RESULT + Department Name + " " + "Department" + "
"
REPEAT Employee Information
RESULT + " " + FORMAT( COUNTER , "9" )
+ "." + " " + Employee Name + "
"
END REPEAT
END REPEAT

2. Open each dialog for editing and insert each repeated dialog (except for the first) into the dialog preceding it. (See
Insert Dialogs Into Dialogs.)

3. Select a repeated dialog style for each repeated dialog. (See Choose a Presentation Style for the Repeated Dialog
or Display a Child Dialog Directly on the Parent Dialog.)

Copyright 2010 HotDocs Ltd. All rights reserved

345

Help Topics for HotDocs Developer 10

Use a Particular Answer from a Sublist

Just as you can merge a particular answer from a regular list into the document, you can merge a particular answer from
a sublist. To do this, you must include in the brackets the numbers of the answers leading to the answer you want to use,
beginning with the first repeat level.
The following graphic shows the hierarchy HotDocs follows when determining which answer to merge into a specific field.
For example, if you need to merge the name of the fifth grandchild born to the fourth child of the second parent, you would
specify the following information in the variable name field: Grandchild Name [2,4,3] .
Then, during the interview, the user provides the answers and HotDocs retrieves the information from the correct levels
of the nested repeat. Specifically, the 2 in the first title bar directs HotDocs to the second answer entered for the variable
Parent Name. The 4 in the second title bar directs HotDocs to the fourth answer entered for the variable Child Name
for the second parent. The 3 in the third title bar directs HotDocs to the third answer entered for the variable Grandchild
Name for the fourth child of the second parent.

To merge a particular answer from a nested repeat

1. Determine the number path leading to the answer you want to merge.
2. At the template, position the cursor after the variable name, but inside the chevrons.
3. Type brackets ( [ ] ), and then, within the brackets, type the first number of the path, followed by a comma, then the
second number, followed by a comma, and so forth. Dont put spaces after the commas, and dont put a comma
after the last number.
As you select specific records from a nested repeat, enter all the necessary numbers in the path. HotDocs always uses
a 1 if a necessary number is missing, and it always places the 1 after the number(s) you entered. If you dont enter any
numbers, HotDocs uses [1,1,...] as the default number path.

Copyright 2010 HotDocs Ltd. All rights reserved

346

Help Topics for HotDocs Developer 10

Note:
When automating a form template, you must enter the number path in the Variable box at the Field Properties dialog
box. (See Retrieve a Specific Answer from a List.)

Copyright 2010 HotDocs Ltd. All rights reserved

347

Help Topics for HotDocs Developer 10

Chapter 25: Inserting Templates into Other Templates

Overview: Insert Templates into Templates
You can insert one template into another by using an INSERT instruction. For example, you might want to:
Include boilerplate text in multiple documents.
Include a set of related documents in one main template so users can choose the document they want.
During document assembly, when HotDocs finds an INSERT instruction, it stops assembling the main document so it can
assemble the inserted document. When it finishes, it continues assembling the main document.
In addition to inserting existing text templates, you can also convert part of your current template into an inserted template
so you can insert it into other templates.
Caution:
You cannot place INSERT instructions in template headers or footers. Additionally, you cannot place INSERT
instructions in a table.
Note:
Templates can be inserted from any location. Click here for details.
You can also use an ASSEMBLE instruction to assemble additional documents from within one template. For example,
say an answer a user provides while assembling a document means they must then assemble another document. Rather
than make them assemble it manually, you can have HotDocs assemble it automatically. You do this by inserting an
ASSEMBLE instruction in the template. Then, once the first assembly finishes, HotDocs will start an additional assembly.
(See Differences Between ASSEMBLE and INSERT Instructions.)

Copyright 2010 HotDocs Ltd. All rights reserved

348

Help Topics for HotDocs Developer 10

Make Part of a Template into an Inserted Template

You can select part of a template and turn it into a separate, inserted template. Once you do this, you can insert it in other
templates as well. For example, perhaps you have a section of a template that could be used in other templates. You
can select this section of text, create an inserted template from it, and then use this inserted template in other related
templates.
When you create inserted templates by selecting existing template text, the inserted template uses the same component
file as the parent template. This means you should save the newly created template to the same folder as the parent
template. If you save it to a different folder, a new, empty component file will be created for the template, which means
if the new template uses variables from the parent template, you must copy those variables into the new component file.
(See Inserted Templates and Shared Component Files and Copy Components From One File to Another.)
Note:
Templates can be inserted from any location. Click here for details.
To make part of a template into a separate, inserted template

1. At the template, select (highlight) the text you want to include in the inserted template and click the

INSERT Field

button. The INSERT Field dialog box appears.

2. Select INSERT Template.

3. Type a name for the new template in the Template to create box.
4. Click OK. HotDocs removes the selected text from the main template, creates the inserted template, and then
replaces the original text with the INSERT Template instruction.
Caution:
You cannot place INSERT instructions in template headers or footers. Additionally, you cannot place INSERT
instructions in a table.
Note:
You can let the user choose which templates they insert by surrounding INSERT instructions with IF instructions.
(See Include or Exclude a Single Version of Text Using a Simple IF Instruction or Expression and Include or
Exclude Multiple Versions of Text Using IF and ELSE IF Instructions or Expressions.) If you have multiple
instructions, you can place the True/False variables in a custom dialog and specify whether the dialog should use
a multiple-select or single-select grouping. (See Change a Dialog's Options.)
If youre going to allow the user to select several documents for assembly at the same time, make sure theres a
section break or page break at the bottom of each template so each assembled document starts on a new page.
In Microsoft Word, you can also add INSERT instructions either by clicking on the HotDocs drop-down menu in
the HotDocs toolbar and choosing INSERT Field, or by right-clicking in the template and choosing INSERT Field
from the shortcut menu.

Copyright 2010 HotDocs Ltd. All rights reserved

349

Help Topics for HotDocs Developer 10

Insert an Existing Template

You can create templates that contain the sections of documents you use over and over againlike signature blocks,
legal headers, and so forthand then insert them in your text templates wherever you need them.
Note:
Templates can be inserted from any location. Click here for details.
To insert an existing template

1. At the template, position the cursor where you want to insert the section of text.
2. Click the

INSERT Field button. The INSERT Field dialog box appears.

3. Select INSERT Template.

4. Click the

Open button and select the template.

5. Click OK. The new INSERT instruction is added to the template.

Once you have created an INSERT instruction, you can edit it by placing your cursor in the instruction and clicking the
INSERT Field button again. (See Edit an INSERT Template Instruction.)
Caution:
You cannot place INSERT instructions in template headers or footers. Additionally, you cannot place INSERT
instructions in a table.
Note:
If you do not know which template should be inserted during template development, you can use a variable
INSERT instruction so that the file path and name can be inserted during document assembly. For details, see
Specify File Names for Inserting Files During Assembly.
In some situations, you may want to assemble separate documents but keep all these separate documents
contained in single document file. When you insert a template for this purpose, headers and footers specific to
each inserted template must remain intact and should not be overwritten by the headers/footers defined for the
parent template. See Define Headers and Footers in Inserted Word Templates.
In Microsoft Word, you can also add INSERT instructions either by clicking on the HotDocs drop-down menu in
the HotDocs toolbar and choosing INSERT Field, or by right-clicking in the template and choosing INSERT Field
from the shortcut menu.

Copyright 2010 HotDocs Ltd. All rights reserved

350

Help Topics for HotDocs Developer 10

Edit an INSERT Template Instruction

Once you create an INSERT instruction in your template, you can edit it at any timeincluding making changes to the text
of the inserted template.
Note:
Templates can be inserted from any location. Click here for details.
To edit an INSERT Template instruction

1. At the template, place the cursor in the INSERT field and click the INSERT Field button. The

Insert FIELD dialog

box appears.

2. Perform either of the following tasks:

Click the

Open button to select a new template to insert.

Click Edit Template to edit the text of the inserted template. (Once the template is open, make any necessary
changes. Click the

Save and Close button to save and close the inserted template.)

Caution:
You cannot place INSERT instructions in template headers or footers. Additionally, you cannot place INSERT
instructions in a table.

Copyright 2010 HotDocs Ltd. All rights reserved

351

Help Topics for HotDocs Developer 10

Inserted Templates and Shared Component Files

Related templates often share many of the same variables. If you point an inserted templates component file to the main
templates component file, both templates can share the same variables and other components. On the other hand, if
there are not many shared variables between the templates, pointing may not be worthwhile. (See Use One Component
File for Multiple Templates and Make Templates Stop Sharing Component Files.)
When you insert an existing template, HotDocs does not automatically point its component file. When HotDocs processes
the INSERT instruction during assembly, it uses the inserted templates own component file. This makes sense since the
inserted template probably contains variables and other components not found in the component file of the main template.
If you want both templates to use the same component file, you must manually point the component file of the inserted
template. (Also, if the inserted template already contains variables, dialogs, and so forth, you must copy those existing
components into the shared component file).
When you select text and create a new template, HotDocs automatically points the component file of the new template to
the component file of the main templateas long as the template is saved to the same folder as its parent. This ensures
the main template and the inserted template will continue to share a common set of variables and other components. If
the inserted template is saved in a different folder, a new, empty component file is created. If the inserted template uses
variables, you must copy components from the parent template into the new component file. (See Copy Components
From One File to Another.)

Copyright 2010 HotDocs Ltd. All rights reserved

352

Help Topics for HotDocs Developer 10

Define Headers and Footers in Inserted Word Templates

Note:
In Microsoft Word, every template has a header and footer, even if no text is defined for it. This is especially important
to understand as you are working with headers/footers in inserted templates. The Microsoft Word help file contains a
lot of important information about inserting headers and footers in your templates and documents. You should read this
information before attempting to use headers and footers, particularly when using them in inserted templates.
When using headers, footers, and margins in your inserted RTF templates, you must first determine the purpose of the
inserted templatewill the inserted text be inline with that of the parent template, or will it be used to create a set of
documents contained within a single document file? Following is a discussion of both situations.
Inserting "Inline" Documents
An inserted template can merge a section of text so that it is "inline" with the text into which it is being inserted. This is
useful if you have an optional paragraph or clause that must be inserted at a specific place within the document.
By default, when you insert a template for this purpose, any headers/footers in the inserted template will be defined by the
parent template, and any headers/footers used in the inserted template will be deleted. This is correct.
For instructions on inserting inline text in a template, see Insert an Existing Template and Make Part of a Template into an
Inserted Template.
Inserting Separate Documents (with Separate Headers) in a Single Document File
An inserted template can also merge a section of text as though it were separate from the document into which it is
inserted. For example, you may want to assemble separate documents but keep all these separate documents contained
in a single document file. When you insert a template for this purpose, you may want the headers and footers specific to
each inserted template to remain intact and not be overwritten by the headers/footers defined for the parent template.
When working with headers and footers in inserted templates, you must think of each inserted template as a section of
the main template. This means that if you want inserted template text to have headers/footers that are different from the
parent template, you must define section breaks in your inserted template.
To use different headers or footers in your inserted templates

1. In the parent template, define the header/footer (or define no header/footer at all).
2. Place your cursor at the place in the parent template where you want the inserted template to be merged and place
a next-page section break.

3. Click the

INSERT Field button. The INSERT Field dialog box appears.

4. Click the

Open button next to the Template to insert box and locate the template file you are inserting.

5. At the INSERT Field dialog box, click Show Advanced. The view changes to show advanced options. Select either
Keep header of inserted template or Keep footer of inserted template. (Select both if you want the document to
maintain both the header and the footer.)

6. Click OK.
7. If inserting multiple templates, repeat this process for each inserted template.
Once you define headers/footers in the inserted template, any text that appears in the main template after the INSERT
instruction will use the headers/footers that were defined in the inserted template.
At times, you may want a cover page for the document that has its own unique header/footer (for example, a notice or
disclaimer). For the document to be assembled correctly, you must use a combination of section breaks both in the main
template as well as in the inserted templates.

Copyright 2010 HotDocs Ltd. All rights reserved

353

Help Topics for HotDocs Developer 10

Caution:
You cannot use the Keep header and Keep footer options with ASSEMBLE instructions.

Copyright 2010 HotDocs Ltd. All rights reserved

354

Help Topics for HotDocs Developer 10

Start a New Assembly From a Template

You can use the ASSEMBLE instruction to add templates to the Assembly Queue. Unlike the INSERT instruction, an
ASSEMBLE instruction adds the template to the assembly queue and then waits until the main document is finished
assembling before it starts assembling the new, added template. (See Differences Between ASSEMBLE and INSERT
Instructions.) ASSEMBLE instructions can be used in both text and form templates, and they can add both text and form
templates to the assembly queue, regardless of the type of template where the instruction is used.
To test an ASSEMBLE instruction, you must exit the template completely and test it from the library.
Note:
Templates can be inserted from any location. Click here for details.
To insert an ASSEMBLE instruction in a Word template

1. At the template, position the cursor in the template where you want the ASSEMBLE instruction.
2. Click the HotDocs drop-down menu in the HotDocs toolbar and choose Other Field from the list of options. The
Other Field dialog box appears.

3. Click the Field type drop-down button and choose ASSEMBLE.

4. Click the

Browse button next to the Template to assemble box and locate the template you want to assemble.

5. Click OK. The instruction is inserted in the template.

To insert an ASSEMBLE instruction in a WordPerfect template

1. At the template, position the cursor in the template where you want the ASSEMBLE instruction.
2. Click the

INSERT Field button. The INSERT Field dialog box appears.

3. Select INSERT Template.

4. Click the

Open button to select the template file you want to have assembled.

5. Click OK. HotDocs inserts the instruction for that specific template. For example: INSERT "subpoena.rtf".
6. Delete the text INSERT from the instruction and type the keyword ASSEMBLE. For example: ASSEMBLE
"subpoena.rtf".
Caution:
If the template you are inserting is a form template, HotDocs will not let you browse for the file from the INSERT Field
dialog box. Instead, at the template, you must manually enter the file path and name of the form template file.
To insert an ASSEMBLE instruction in a form template

1. At the template, create a field and attach a Computation variable to it. (See Create a Form Field and Attach a
Variable to a Field.)

2. At the Computation Editor, enter the ASSEMBLE instruction, including the path and file name (if necessary) of the
template you want to assemble. For example: ASSEMBLE "subpoena.hft".
Note:
You can add command-line options to an ASSEMBLE instruction (for example, ASSEMBLE "subpoena.rtf /pr").
If the command-line option includes a file path and name, enclose the path and name in double quotation marks (for
example, ASSEMBLE "subpoena.rtf /sa /af=""L Chang"""). (Four command-line options were designed
specifically for use with ASSEMBLE instructions. They are: Suggest Save, Suggest Save New, Save Answers, and
Save Answers Prompt. They control the saving of answers after each ASSEMBLE instruction is processed.)

Copyright 2010 HotDocs Ltd. All rights reserved

355

Help Topics for HotDocs Developer 10

Caution:
If your template uses a custom interview, you must place ASSEMBLE instructions in both the body of the template and
in the interview script. For more information, see ASSEMBLE "FILENAME".

Copyright 2010 HotDocs Ltd. All rights reserved

356

Help Topics for HotDocs Developer 10

Insert Image Files in a Template

Note:
Inserting graphics in a text template is supported in Microsoft Word only. If you insert a graphic in a WordPerfect
template, the instruction is ignored.
Using a HotDocs INSERT instruction, you can insert image files in your template. The actual files will not be stored in the
template, but instead may be inserted during assembly. This might be useful if you need to include diagrams, photos, or
other graphics in the final document, but specification of these files might not be known until the document is assembled.
For example, say you are a legal secretary drafting a letter for one of the attorneys in your firm. This letter can be signed
by any number of attorneys. Rather than use Word to add or remove signatures from the document after it has been
assembled, you can include a series of INSERT Image instructions, and then define the conditions for which signature is
inserted. For example:
IF Attorney Name = "Cathy Bailey"
INSERT "cbailey sig.png" IMAGE
ELSE IF Attorney Name = "Jim Johnson"
INSERT "jjohnson sig.png" IMAGE
END IF
When the document is assembled, the correct signature will be inserted based on how the user answers the Attorney
Name question.
You can insert JPG, PNG, and GIF files in a template. Also, when you insert a graphic in a template, the INSERT
instruction is appended with the IMAGE keyword. This keyword instructs HotDocs that the file that should be inserted is a
graphic. Finally, graphics can be inserted from any location, as long as the file path to the image file is specified correctly.
(Click here for details.)
If the graphic is already in the template, you can copy the graphic to an RTF document and specify the RTF document
in the INSERT instruction. You can do this by simply selecting the image in the template and clicking the INSERT Field
button.
Note:
One advantage to inserting RTF files that store the graphic (rather than inserting the graphic directly) is you can format
the graphic and have those settings transfer to the parent template. For example, if you want to specify placement,
text wrapping, borders, and other effects, you can assign them in the RTF template. Then, when the image is inserted,
those properties are carried over and applied to the parent template.
To insert an existing graphic file in a template

1. In the template, position the cursor where you want to insert the image file.
2. Click the

INSERT Field button. The INSERT Field dialog box appears.

3. Select INSERT Image.

4. Click the

Open button next to the Image file to insert box and select the graphic file.

5. Click OK. The new INSERT instruction is added to the template.

To create an INSERT instruction using an existing image in the template

1. In the template, click on the image you want to include in an RTF document. Field borders appear around the
graphic.

2. Click the

INSERT Field button. The INSERT Field dialog box appears.

3. Select Insert image.

Copyright 2010 HotDocs Ltd. All rights reserved

357

Help Topics for HotDocs Developer 10

4. Enter a name for the RTF document in the Image file to create box. (To specify a folder location different from the
template, click the

Open button and browse to the folder.)

5. Click OK. HotDocs removes the image from the template, copies it to an RTF document, and inserts the INSERT
Image instruction.
Note:
If you do not know which graphic should be inserted during template development, you can use a variable INSERT
instruction so that the file path and name can be inserted during document assembly. For details, see Specify File
Names for Inserting Files During Assembly.

Copyright 2010 HotDocs Ltd. All rights reserved

358

Help Topics for HotDocs Developer 10

Specify File Names for Inserting Files During Assembly

When inserting templates and images in a template, you may not always know, during template development, which files
you need to insert.
When this situation arises, you can instead use a variable INSERT in the template. A variable INSERT instruction allows
you to specify the templates file name during document assembly, rather than during template development. The type of
variable you insert must accept text as an answer, which means you must use a Text variable, a Multiple Choice variable,
or a Computation variable that produces a text result.
For example, say there are hundreds of sub-templates that could potentially be inserted in a document. It wouldnt make
sense to try to automate the template to account for each of these sub-templatesespecially when new sub-templates
are being created and added to the group on a regular basis. Using a variable INSERT instruction, however, you can
script your template such that it specifies the name of the inserted file when you assemble the document.
To specify a file for insertion during assembly

1. At the template, position the cursor where you want to insert the template or graphic.
2. Click the

INSERT Field button. The INSERT Field dialog box appears.

3. Select INSERT Template or INSERT image, depending on which type of file you want to include in the assembled
document.

4. Click Show Advanced. The dialog expands to show advanced options.

5. Select Variable INSERT.
6. Click the Type drop-down button and choose which type of variable you want to use in the INSERT instruction:
Computation Variable allows you to use a computation script to specify the file path and name of the template
that will be inserted. (Make sure the script produces a text result.)
Multiple Choice Variable allows you to specify the file path and name of the template that will be inserted
in the Option column. (If you want to provide a reader-friendly name for the template, enter the name in the
Prompt column.)
Text Variable allows you to specify the file path and name of the template using a simple text answer field.

7. Click the Variable drop-down button and choose the variable you want to use. (To create a new variable or edit the
existing variable, click the

Edit Component button.)

8. Click OK. The new INSERT instruction is added to the template.

Caution:
If you reference any specific templates in a variable INSERT instruction, make sure you include the template
in the library when you run Template Manager. If you do not, Template Manager may not accurately report
component usage information.
When publishing templates, you must manually add any files you reference in variable INSERT instructions to the
published file at the Additional Files page of the Publishing Wizard.

Copyright 2010 HotDocs Ltd. All rights reserved

359

Help Topics for HotDocs Developer 10

Chapter 26: Marking Editable Text in a Template

Overview: Use SPAN Instructions
Note:
SPAN fields are supported in Microsoft Word only.
Frequently, users need to edit document text once a document has been assembled. To allow this, you must mark
sections of template text using SPAN fields. Inserting SPAN fields in a template allows users to edit the text of the
assembled document while viewing the Document Preview tab of the assembly window. Changes made to the text can
be saved in an answer file, which allows users to later reassemble the document and still have access to the changes
they made.
SPAN instructions are inserted using Span components. Also, like IF and REPEAT instructions, SPAN instructions must
include an END instruction.

Copyright 2010 HotDocs Ltd. All rights reserved

360

Help Topics for HotDocs Developer 10

Allow Users to Edit the Text of an Assembled Document

Note:
SPAN fields are supported in Microsoft Word only.
Sometimes users need to edit the text of a document while viewing the Document Preview tab of the assembly window.
To allow this, you can mark sections of the template using a SPAN instruction. Text between the beginning and end
instruction can be highlighted and then selected and edited by the user. Any changes a user makes to the text can be
saved to an answer file so that if the user ever reassembles the document, he or she can reuse the answer file and have
the changes reapplied to the document.
Like IF and REPEAT instructions, SPAN instructions include an opening instruction (SPAN) and a closing instruction
(END SPAN).
To allow users to edit document text and save it in the answer file

1. At the template, select the text you want the user to be able to edit.
Caution:
When selecting template text, do not include IF instructions or REPEAT instructions between the SPAN
instructions, as these instructions will no longer be processed correctly once the user edits the document text.

2. Click the

SPAN Field button. The SPAN Field dialog box appears.

3. Enter a component name in the Span box.

4. Optionally, click the Notes tab to enter notes about the span component, such as an explanation about why the span
field was created or how it should function in the interview. (See Add Notes to Components for details.)

5. Optionally, click the

Edit Component button and enter a title in the Title box. The title will be used to identify the
editable text in the Document Text Editor.

Note:
When naming Span components, use unique component names. If two different (but related) templates use the
same Span component name, when users edit the document text in the first document, save the answer file,
and then use that answer file to assemble the second document, those changes from the first document may
overwrite text in the second.
To let users enter a new paragraph of text in the document, see Allow Users to Enter New Text in the Assembled
Document.
You cannot insert SPAN instructions in template headers and footers.
When working with SPAN instructions, you can use buttons on the HotDocs Navigation toolbar to label
instructions and match starting and ending instructions. (See Use Labels to Identify Instructions and Match
Opening Instructions with Closing Instructions.) You can also assign color to SPAN instructions. (See Assign
Colors to Fields and Instructions in Templates.)
You can also insert SPAN instructions either by clicking on the HotDocs drop-down menu in the HotDocs toolbar
and choosing SPAN Field, or by right-clicking in the template and choosing SPAN Field from the shortcut menu.

Copyright 2010 HotDocs Ltd. All rights reserved

361

Help Topics for HotDocs Developer 10

Allow Users to Enter New Text in the Assembled Document

Note:
SPAN fields are supported in Microsoft Word only.
Sometimes you may want to allow users to enter new text in an assembled document, rather than just modify existing
document text. For example, perhaps users need to insert a new paragraph, based on answers they entered during the
interview. You can insert a SPAN field in the template that allows users to do this.
When users view the assembled document, they can position their cursor either at the beginning of a paragraph or
between paragraphs and click the Edit Document Text button. HotDocs will then display a list of editable paragraphs
(if any) near the cursor position. If the cursor is in a paragraph and there are no additional Span fields near the cursor
position, HotDocs will simply display the Document Text Editor where users can enter their text. To help users better
identify which section of text they want to edit, you should enter a descriptive title for the Span component.
To insert an empty SPAN field in a template

1. At the template, place your cursor where you want the user to enter text.
2. Click the

SPAN Field button. The SPAN Field dialog box appears.

3. Enter a component name in the Span box.

4. Click the

Edit Component button and enter a title in the Title box. The title will be used to identify the editable
text in the Document Text Editor.

5. Optionally, click the Notes tab to enter notes about the span component, such as an explanation about why the span
field was created or how it should function in the interview. (See Add Notes to Components for details.)
Note:
When naming Span components, use unique component names. If two different (but related) templates use the
same Span component name, when users edit the document text in the first document, save the answer file,
and then use that answer file to assemble the second document, those changes from the first document may
overwrite text in the second.
To allow users to edit existing paragraph text, see Allow Users to Edit the Text of an Assembled Document.
You cannot insert SPAN instructions in template headers and footers.
When working with SPAN instructions, you can use buttons on the HotDocs Navigation toolbar to label
instructions and match starting and ending instructions. (See Use Labels to Identify Instructions and Match
Opening Instructions with Closing Instructions.) You can also assign color for SPAN instructions. (See Assign
Colors to Fields and Instructions in Templates.)
You can also insert SPAN instructions either by clicking on the HotDocs drop-down menu in the HotDocs toolbar
and choosing SPAN Field, or by right-clicking in the template and choosing SPAN Field from the shortcut menu.

Copyright 2010 HotDocs Ltd. All rights reserved

362

Help Topics for HotDocs Developer 10

Add a Comment to a Variable or Instruction Field

When you insert a variable or instruction in a template, you can add a comment to the insertion field. Comments are
useful when you want to document information about the variable or instruction you are inserting and you want those
comments to be viewable by anyone editing the text of the template.
Comments can also be useful when viewing a markup view of the templatethe comment can describe (in easy-tounderstand terms) the purpose of the field or provide a more reader-friendly name for the field.
Note:
If you want to add comments to a specific component, enter it at the Notes tab of the component editor. See Add
Notes to Components for details.
To add a comment to a variable or instruction field

1. Insert a new variable or edit an existing variable. (See Insert a Variable Field in a Text Template or Edit a Variable.)
The Variable Field dialog box appears. Or, insert a new instruction or edit an existing instruction. The instruction
field dialog box appears.

2. Click Show Advanced. The view expands to show advanced options.

3. Enter your comments in the Comment box.
When you click OK, HotDocs merges the field, with the comments merged after the variable name, like this: Employee
Salary //Calculates biweekly salary based on hourly rate.
Note:
To merge a comment in an END instruction (such as END IF, END REPEAT, OR END SPAN), place your cursor
before the closing chevron, enter two forward slashes (//), and type your comment, like this: END IF //Closing.
If the END instruction contains a Keep Return code ( | ), enter the comment before the return code, like this: END
IF //Closing |.

Copyright 2010 HotDocs Ltd. All rights reserved

363

Help Topics for HotDocs Developer 10

Understand How Smart Returns are Inserted After Instructions

By default, each time you insert any instruction (IF/END IF, REPEAT/END REPEAT, SPAN/END SPAN, INSERT, or
ASK) in a template, HotDocs adds a return following the instruction. Then, when HotDocs assembles the template
and processes the instruction, it removes the return it inserted. To some, this insertion of returns creates problems or
confusion in automating the template because it sometimes makes the template text difficult to read and understand,
especially when instructions (and their subsequent returns) within a paragraph sometimes break the paragraph into
separate lines of text.
To accommodate this, HotDocs allows you to choose whether to insert returns following these instructions. (See Control
When Returns Are Inserted After Instructions in Text Templates.). Specifically, you can:
Always insert a return after an instruction.
Never insert a return after an instruction.
Use "smart" return insertion.
The first two options behave exactly as expectedHotDocs will either always insert a return (and remove it during
assembly) or never insert a return, depending on which of the two options you choose.
The behavior of third option, using smart returns, depends on how and where you're inserting the instruction.
If text you select represents a complete paragraph (meaning there's a paragraph mark at the end of the selected text),
HotDocs will insert a return character after the instruction. In the following example, brackets ([]) indicate where text
selection begins and ends. Note that the closing bracket ends on the line after the paragraph mark ():
Here is a paragraph.
[Here is another paragraph.
]Here is a third paragraph.
Would produce a section of conditional text that looks like this:
Here is a paragraph.
IF Instruction
Here is another paragraph.
END IF
Here is a third paragraph.
However, if the text you select is within a paragraph, HotDocs will not insert a return character. So, in the following
example, when you insert the REPEAT instruction, HotDocs does not insert a return because the insertion is happening in
the middle of a paragraph. There is no paragraph break at the end of the insertion:
The client, Client Name, has the following children: REPEAT Children:a, b, and
cChild NameEND REPEAT. These children live with the client and are covered under
the provision.
At times, you may simply insert an instruction without first selecting text, or perhaps you may select some text but not
include the paragraph mark in the selection. If HotDocs detects an existing paragraph break immediately after the
instruction, it includes a Keep Return code (or vertical bar (|) ) at the end of the instruction. The code tells HotDocs to not
delete the return when it assembles the document. So, the following example, where brackets indicate text selection:
Here is a paragraph.
[Here is another paragraph.]
Here is a third paragraph.
would produce the following automation:
Here is a paragraph.
IF InstructionHere is another paragraph.END IF|
Here is a third paragraph.

Copyright 2010 HotDocs Ltd. All rights reserved

364

Help Topics for HotDocs Developer 10

Note that the Keep Return code (|) in the END IF instruction indicates to HotDocs to keep the return character when it
assembles the document.
Caution:
HotDocs' capacity to delete both an IF instruction and the return that follows it is very important in some situations. If
an optional paragraph includes numbering, it is difficult to condition out the entire paragraph and its numbering without
putting the IF on a separate line before the paragraph. It can be done, but the template looks odd, since the IF is inside
the numbering of the paragraph.

Copyright 2010 HotDocs Ltd. All rights reserved

365

Help Topics for HotDocs Developer 10

Use Labels to Identify Instructions

Note:
Click here if you are using WordPerfect and the HotDocs Navigation toolbar doesn't appear in your template.
You can assign labels to IF, REPEAT, and SPAN instructions to help you identify pairs or groups of instructions in a text
template. When you label fields, you can choose to merge just a numeric name in a field or you can choose to merge
a name as well as the level of nesting. This can help you match opening instructions with closing, as well as help you
determine the level of nesting within an instruction.
Field labels are merged as comments in the field.
The following example shows a series of nested REPEAT instructions that have been labeled. The first instruction,
REPEAT Editor Information, is labeled with the number 1, since it's the first REPEAT in the template. This same
instruction is also assigned the level number of L1, since it's the first level of the REPEAT instruction. The END REPEAT
is likewise labeled so that you can easily match them when examining the contents of the template.
For each subsequent instruction, HotDocs increments the field number. Additionally, if the next REPEAT instruction is
nested (which, in this example, it is), HotDocs increments the nesting level number. Each END REPEAT instruction is
likewise labeled.
REPEAT Editor Information // [1:L1]
Editor: Editor First Name Editor Last Name
REPEAT Author Information // [2:L2]
Author: Author First Name Author Last Name
REPEAT Book Information // [3:L3]
Title Edited / Date Completed: Book Title / Date Completed:03 JUN 90
END REPEAT // [3:L3]
END REPEAT // [2:L2]
END REPEAT // [1:L1]
When assigning labels to fields, you can choose whether to include both the field number and the nesting level. You can
also choose to merge just one or the other.
Finally, you can have HotDocs assign the hidden text property to these labels (as well as any other comments you've
assigned to fields in the template.) When this property is assigned, comments and labels will be hidden and shown,
depending on whether you are viewing hidden text in the template. (For information on viewing hidden text, see your word
processor's documentation.)
To label instructions

1. At the text template, click the

Label Fields button. The Label Fields dialog box appears.

2. Select an option, based on the following information:

To assign a numeric name to each instruction, select Label IF, REPEAT, and SPAN instructions.
To have HotDocs identify the level of nesting for each instruction, select Identify level of nested IF, REPEAT,
and SPAN instructions.
To apply the hidden text property to comments and labels, select Place comments (including field labels)
in hidden text. Once applied, you can quickly show and hide your comments and labels by choosing the
appropriate command at the word processor.

3. Click OK. HotDocs applies the labels you have selected to any instructions in the template.
Note:
SPAN fields are supported in Microsoft Word only.
To clear labels from fields or show comments once again, click the
options, and click OK.
Copyright 2010 HotDocs Ltd. All rights reserved

Label Fields button, clear all of the

366

Help Topics for HotDocs Developer 10

If you're using Microsoft Word, you can also label fields by clicking on the HotDocs drop-down menu in the
HotDocs toolbar and choosing Label Fields.

Copyright 2010 HotDocs Ltd. All rights reserved

367

Help Topics for HotDocs Developer 10

Match Opening Instructions with Closing Instructions

Note:
Click here if you are using WordPerfect and the HotDocs Navigation toolbar doesn't appear in your template.
Every IF, REPEAT, and SPAN instruction inserted in a template must include an END IF, END REPEAT, or END SPAN
instruction. Without both of these instructions, you will receive an error when you attempt to assemble a document. (The
one exception is a repeated row in a table. See Use a Word Processor Table to Display a List.) However, sometimes
during the course of editing a template, you may inadvertently delete or move part of the instruction. Doing so will cause
errors when you attempt to assemble the document. To troubleshoot errors like this, you can have HotDocs match the
different parts of the instruction. Likewise, if you have an intricate section of nested instructions, you can pair these
different parts of the instruction.
To match opening instructions with their closing instructions

1. Open the template for editing. (See Edit a Template.)

2. Place the cursor inside either the opening instruction or the closing instruction. For example, if you're trying to find
the opening instruction of a REPEAT, place your cursor in the END REPEAT instruction.

3. Click the

Match Fields button. HotDocs moves your cursor to the corresponding instruction.

Note:
When editing instructions in a computation script, you can place your cursor in either the opening or closing
instruction and press Ctrl+M. This will move your cursor to the corresponding instruction.
If you're using Microsoft Word, you can also match fields by clicking on the HotDocs drop-down menu in the
HotDocs toolbar and choosing Match Fields.

Copyright 2010 HotDocs Ltd. All rights reserved

368

Help Topics for HotDocs Developer 10

Chapter 27: Creating and Editing Clauses

Overview: Use Clauses and Clause Libraries
A clause is a HotDocs component that contains text. When you create clauses, you are, in essence, creating smaller
templates that can be added to one main document. Clauses can contain text as well as HotDocs components (such as
variables, instructions, and so forth).
You can insert a clause component directly into a template using an INSERT or an INSERT IF instruction, or you can add
clauses to a clause library so a user can select them for insertion into an assembled document.

Clauses
When you insert a clause into a template, you are actually working with three different parts of the clausethe clause
field, the clause component, and the clause text:
Clause field: This is the merge field that inserts the clause text into the assembled document. You can control
whether the clause is inserted automatically, or whether the clause is inserted based on certain conditions being
met. (When you create a clause at the clause library, there is no clause field associated with the clause.)
Clause component: This is the clause itself. It includes component properties, such as a prompt and resource
information.
Clause text: This is the text you want inserted into the assembled document. The clause text can also contain
HotDocs components, such as variables, dialogs, and instructions, which will all be processed during assembly.

Clause Libraries
Like a template library, a clause library is a collection of clauses. Grouping clauses in a library allows users to select,
organize, and insert any number of clauses into the document. HotDocs then proceeds to prompt users for any variables
contained in the clauses.
You can create clauses and clause libraries at two places: a HotDocs library and a template. Each location causes the
clause library to function a little differently:
A clause library assembled from a HotDocs library allows users to select clauses to insert into any text document.
They can select the clause library first at the template library and assemble a document using clauses from it, or
they can assemble a document and then after assembly, add clauses from the library to the document.
A clause library assembled in a template allows users to select which clauses they want to insert at that specific
point in the assembled document.
Note:
For additional information on the underlying functionality of clauses, see Understand How Clauses Work.

Copyright 2010 HotDocs Ltd. All rights reserved

369

Help Topics for HotDocs Developer 10

Understand How Clauses Work

When working with clauses and clause libraries, it is useful to understand the underlying functionality. This includes
understanding the files that control how clauses and clause libraries work.
When you create a clause library and add clauses to it, HotDocs creates and uses the following files:
Clause template file (.DOT, .RTF, .WPT): This is the file that contains the text of the clause component. When
you create a clause template file, HotDocs generates an eight-character file name based on the clause component
name, appends the appropriate file name extension, and adds the clause to an archive file (see below). (If the clause
name is less than eight characters, HotDocs adds underscores to make the template name the right length.)
Clause component file (.CMP): When you create a clause, HotDocs creates a clause component, which is added
to a component file. Where you create the clause determines which component file is used. For example, if you
create clauses at a template, the clause components are added to the template's component file. But if you create
clauses at a clause library, HotDocs creates a new component file that is associated with the clause library and
stores the clause components in it.
In addition to storing the clause components, the clause component file also stores other components used in the
clause text, such as variables, dialogs, and scripts.
Clause library file (.HDL): This is a library file that contains an organized set of shortcuts that correspond to a
set of clauses stored in the HotDocs clause archive file (see below). The clause library file gets its name based on
where it is createdeither at the template or at a template library. For example, if you create a clause library while
editing contract.rtf, the clause library file name becomes contract.hdl. However, when you create a clause library at a
regular template library, you specify the file name.
Clause Archive file (.HCL): This is a file that contains a set of related clauses in compressed (or zipped) format.
When you edit or assemble a document using clauses, this file is unzipped and the clause template files are
extracted on an as-needed basis to a temporary folder. When the clauses and clause library are no longer in use,
the clause template files are zipped and saved to the clause archive file, and all temporary files are deleted.
These files work simultaneously to organize and store clauses. The clause library file, the clause template file, and the
clause component file are all located in the word processor's template folder, along with the other HotDocs templates.
Note:
If you are uncertain about a clause's shortened name or file format, you can view the name in the Clause identifier
box at the Clause Editor. (See Edit an Existing Clause.)

Copyright 2010 HotDocs Ltd. All rights reserved

370

Help Topics for HotDocs Developer 10

Open and Close a Clause Library

You can open and close a clause library either at the template library or at the template.
To open a clause library from the template library
At the HotDocs library, select the clause library and click

Edit. The Clause Library window appears.

To open a clause library from the template

At the text template, click the

Clause Library button. The Clause Library window appears.

To close a clause library

Click the X in the upper-right corner of the clause library window.
Note:
To access the clause library toolbar using the keyboard, press F10.
Word users can also open a clause library by clicking on the HotDocs drop-down menu in the HotDocs toolbar
and choosing Clause Library.

Copyright 2010 HotDocs Ltd. All rights reserved

371

Help Topics for HotDocs Developer 10

Create a Clause Library at the HotDocs Library

At a template library, you can create a clause library that contains any number of clauses. These clauses can be
assembled and added to any word processor document. For example, users can select a clause library at the template
library, provide any required information, and then either send the assembled clauses to a new document or paste the
assembled document into an open document (perhaps another related document you have just finished assembling).
Storing sections of template text in clauses and then adding those clauses to a clause library makes it easy for the user to
choose which text will be used in assembling a document. A clause library also provides a way for users to organize their
clauses and view the properties of each individual clause.
Users can also preview clause text from the Preview tab of the clause library.
To create a clause library at a HotDocs template library

1. At the template library, select the folder in which you want the clause library to appear.
2. Click

New Template. The New Template dialog box appears.

3. Click the Type drop-down button and select a clause library option for the word processor you are using. Your
options include Word RTF Clause Library, Word DOT Clause Library, and WordPerfect Clause Library.

4. Type a name for the clause library in the File name box.
5. Type a title for the clause library in the Title box (or accept the suggestion HotDocs makes).
6. Optionally, type a description in the Description box. The description appears when the user views the clause
library's properties at the HotDocs template library.

7. Click OK. HotDocs creates and opens the clause library.

When the clause library opens, you will notice that it does not contain any clauses yet. You must create the clauses that
will appear in the clause list. See Create Clauses at the Clause Library for details.
When a clause library is created directly at a HotDocs template library, no template file is created. However, a component
file (using the same file name as the clause library) is created automatically to store information for components used in
the clause library.
Note:
A clause library can be used to assemble any number of documents and can even be inserted into any template if you
want to associate the clauses with a specific document. (See Insert a Clause Library into a Template.)

Copyright 2010 HotDocs Ltd. All rights reserved

372

Help Topics for HotDocs Developer 10

Add a Folder to a Clause Library

You can add folders to your clause library so you can organize your clauses into groups.
To add a folder to a clause library

1. At the template, or at the template library, open the clause library for editing. (See Open and Close a Clause
Library.)

2. With the clause library displayed, select the folder in which you want to create a new folder.
3. Click

Add. The Add Clause dialog box appears.

4. Click the Type drop-down button and select Folder. The dialog box changes to show folder properties.
5. Type a name for the folder in the Title box.
6. Optionally, type a description for the folder in the Description box. The description appears in the Properties tab of
the clause library window when the folder is selected.
Once you have created folders, you can arrange the folders (as well as the contents of the folders) by selecting the library
item and dragging it to a new location in the list. You can also arrange the contents of each folder by clicking
(See Customize a Clause Library.)

Copyright 2010 HotDocs Ltd. All rights reserved

Sort.

373

Help Topics for HotDocs Developer 10

Create Clauses at the Clause Library

Once you've created a clause library at a template library (see Create a Clause Library at the HotDocs Library), you can
add clause text from any word processor document to it. To do this, either copy text from an existing word processor
document or template and paste it into the clause component, or write the clause text as you go.
To create a clause at the clause library

1. Open for editing the clause library which will contain your clause components. (See Open and Close a Clause
Library.)

2. Click

New Clause. The Clause Editor appears.

3. Type a name for the clause in the Clause name box. (50-character limit.)
4. Optionally, enter a title for the clause in the Title box. The title will be used as the default title for the item once it is
added to the clause library.

5. Optionally, click the Resource tab to provide users with helpful information that can assist them in providing the
correct answer. (See Add Resource Information to a Variable or Dialog.)

6. Optionally, click the Notes tab to enter notes about the clause, such as an explanation about why the clause was
created or how it should function in the interview. (See Add Notes to Components for details.)

7. Click OK. HotDocs opens a new, empty text template.

8. Either copy sections of existing template text and paste it into the template (make sure you copy any existing
components into the associated component file), or type the text directly in the template. You can automate the
clause text by adding variables, instructions, and any other HotDocs functionality.

9. When you are finished, click the

Save and Close Template button at the HotDocs toolbar. The clause is added

to the clause library.

10. Repeat this process for all the clauses you need to create.
Caution:
In Word, the word processor may insert an extra hard return at the end of a new clause. To fix this, select the clause
at the clause library and click
Edit. The Clause Editor appears, where you can click Edit Clause Text. When
your text appears, delete the extra hard return. (Click the Show / Hide button in the Word toolbar to view paragraph
marks.)
Note:
As you create clauses, if you paste template text that already contains variables or other HotDocs components, you
must copy those components into the clause library's component file in order for the clauses to assemble correctly.
The easiest way to do this is to click the
Component Manager button in the clause library toolbar and copy those
components in. (See Copy Components From One File to Another.)

Copyright 2010 HotDocs Ltd. All rights reserved

374

Help Topics for HotDocs Developer 10

Add Existing Clauses to a Clause Library

When you create clauses at the template, you can either specify the clause text and have HotDocs immediately add the
clause to the clause library (see Create Clauses at the Template and Add Them to the Library), or you can manually add
the clauses at a later time.
If you are adding clauses to a library that resides in a template library, you can only add clauses that have already been
created for that specific clause library. (For example, maybe you have deleted a clause from the library list and you want
to re-add it.)
To add an existing clause to the clause library

1. Open the clause library for editing. (See Open and Close a Clause Library.) The Clause Library dialog box appears.
2. Click

Add. The Add Clause dialog box appears.

3. Click the Select clause drop-down button and select the clause you want to add.
4. Enter a new title for the clause in the Title box, or accept the suggestion HotDocs makes. (If you entered one,
HotDocs uses the title you suggested when you created the clause component. If you later decide you want to
change the title, select the clause in the clause library and click
Properties dialog box.)

Properties. Make your change at the Item

5. Optionally, enter a description in the Description box. The description, along with the title, appears in the
Properties pane of the clause library window.

6. Click OK. The clause is added to the clause list in the library.

Copyright 2010 HotDocs Ltd. All rights reserved

375

Help Topics for HotDocs Developer 10

Customize a Clause Library

It is often helpful to organize your clauses using a clause library. At the clause library, you can create, add, and delete
clauses from a clause library, as well as sort clauses in alphanumeric order. You can also create additional folders in the
library to group the clauses, and change the titles and descriptions of clauses and folders. Finally, you can view either the
properties of a specific clause, or you can view the text of the clause itself.
To customize a clause library

1. Open a clause library for editing. (See Open and Close a Clause Library.)
2. Perform any of the following tasks:
To

Do This

Move clauses within the

clause library

Select a clause and drag it to a different position. As you are dragging, HotDocs
displays a horizontal bar, indicating where the clause will be placed when you release
the mouse button.

Arrange the clause library

with other open windows

Resize the clause library window to the desired height and click the
Arrange
button. The clause library window appears below the window from which it was
openedeither the word processor or the template library.

Create a new clause

component

Click
New. HotDocs opens the Clause Editor where you can assign properties to
a clause component. Once you assign a name and click OK, a text template opens
where you can enter your clause text. (See Create Clauses at the Clause Library.)

Add an existing clause to

the clause library

Click
Add. HotDocs opens the Add Clause dialog box where you can select an
existing clause and add it. (See Add Existing Clauses to a Clause Library.)

Add a folder to the clause

library

Click
Add. When the Add Clause dialog box appears, select Folder from the
Type drop-down list. (See Add a Folder to a Clause Library.)

Remove a clause or a
folder from the clause
library

Select the clause or folder you want to remove and click

Make changes to a clause

in the clause list

Select the clause and click

Edit. HotDocs opens the Clause Editor where you can
change the clause component properties. (To edit the text of the clause, click Edit
Clause Text at this dialog box.) (See Edit an Existing Clause.)

Rearrange clauses in the

clause list in alphabetical
order

Select the folder whose contents you want to arrange and click the
Sort button.
HotDocs displays the Folder Sort Options dialog box where you can choose either
Ascending or Descending order.

Change the clause or

folder title, or add a
description

Select a clause or folder and click

Properties. The Item Properties dialog box
appears where you can type a new title in the Title box, or type a description in the
Description box. Both the title and the description appear in the clause library's
Properties tab.

Print a list of the clauses

Click the
Print button. HotDocs prints a list of all the clauses with their associated
clause identifiers.

Open the component file

for the clause library

Click the
Component Manager button. (See Use Component Manager to Work
with Components.)

Copyright 2010 HotDocs Ltd. All rights reserved

Remove Item.

376

Help Topics for HotDocs Developer 10

To

Do This

View the properties of

the clause or preview the
clause text

Click the Properties tab or the Preview tab, respectively.

Search the list of clause

names and clause
descriptions for a specific
string of text

Select Find and then type the text for which you are searching. HotDocs searches
the clause names as well as clause descriptions. When it finds the text string, it lists
only those clauses in the clause list until you clear Find.

Any time you make changes at the clause library file, those changes are automatically saved.
Note:
To access the clause library toolbar using the keyboard, press F10.

Copyright 2010 HotDocs Ltd. All rights reserved

377

Help Topics for HotDocs Developer 10

Create Clauses at the Template and Add Them to the Library

When the text for the clauses you want to create already exists in a single template, you can create individual clauses
right in the template. Once you've defined the clause text, you can add the clause to the clause library.
To create the clause and add it to the clause library

1. At the template containing your clause text, select the text you want to make into a clause and click the

Clause

Library button. The Clause Editor appears, as well as the Clause Library.

2. Type a name for the clause in the Clause name box.

3. Enter a title for the clause in the Title box. The title will be used as the default title for the item once it is added to the
clause library.

4. Optionally, click the Resource tab to provide users with information that can assist them in providing the correct
answer. (See Add Resource Information to a Variable or Dialog.)

5. Optionally, click the Notes tab to enter notes about the clause, such as an explanation about why the clause was
created or how it should function in the interview. (See Add Notes to Components for details.)

6. Click OK. The clause is added to the clause list in the library.
Caution:
In Word, the word processor may insert an extra hard return at the end of a new clause. To fix this, select the clause
at the clause library and click
Edit. The Clause Editor appears, where you can click Edit Clause Text. When
your text appears, delete the extra hard return. (Click the Show / Hide button in the Word toolbar to view paragraph
marks.)

Copyright 2010 HotDocs Ltd. All rights reserved

378

Help Topics for HotDocs Developer 10

Create and Insert Clauses Directly in Template

When the text for the clauses you want to create already exists in a single template, you can create individual clauses
right in the template instead of at the clause library.
To create a clause and insert it into the template

1. Edit the template that contains the text you want to convert to clauses. (See Edit a Template.)
2. At the template, select the text for the first clause and click the

INSERT Field button. The INSERT Field dialog

box appears.

3. Select INSERT Clause.

4. Type a name for the clause component in the Clause to create box. (50-character limit.)
5. Optionally, select INSERT clause only IF selected if you want the user to control whether the clause is inserted.
6. Click OK. The Clause Editor appears.
7. Perform any of the following optional tasks:
Enter a title for the clause in the Title box. The title will be used as the default title for the item once it is added
to the clause library.
Type the information about the clause you want the user to see in the Prompt box. (See Create a Prompt for a
Variable.)
If you selected INSERT clause only IF selected at the INSERT Field box, select Yes/No on same line to
have Yes/No options appear on the same line in the interview.
Click the Resource tab to provide users with information that can assist them in providing the correct answer.
(See Add Resource Information to a Variable or Dialog.)

8. Click OK when you are finished. The instruction is inserted into the template.
Caution:
In Word, the word processor may insert an extra hard return at the end of a new clause. To fix this, select the clause
at the clause library and click
Edit. The Clause Editor appears, where you can click Edit Clause Text. When
your text appears, delete the extra hard return. (Click the Show / Hide button in the Word toolbar to view paragraph
marks.)
Note:
To insert an existing clause in the template, position your cursor where you want the clause inserted and click the
INSERT Field button. Then select the clause by clicking the Clause to insert drop-down button. (The dropdown button is not available if you have selected text.)
You can add the clauses you have created to a clause library, which can be used to assemble any other
document. See Add Existing Clauses to a Clause Library for details.
Clauses not only have a text value, but they have a true/false value as well. That means if you insert a clause in a
template by using an INSERT IF instruction, the clause will automatically appear to the user as a yes/no question
during assembly. If the user answers Yes, the clause will be included in the document; if the user answers No,
the clause will not be included. You can also group clauses in a single selection or multiple selection group. See
Group Clause Components in One Custom Dialog for details.

Copyright 2010 HotDocs Ltd. All rights reserved

379

Help Topics for HotDocs Developer 10

Insert a Clause Library into a Template

Once you add clauses to a clause library (see Add Existing Clauses to a Clause Library), you can insert the library into the
template so it will appear during the interview. When the library appears, users can select and order the clauses they want
to appear in the document. You can insert any clause library into the template, as long as the library, its clauses (stored in
the clause archive (.HCL) file), the template, and the component file are all stored in a folder HotDocs can find.
To insert a clause library into the template

1. At the template, place the cursor where you want the library to be inserted. (If you've divided the whole document
into clauses in the library, the template may show no text at all.)

2. Click the

INSERT Field button. The INSERT Field dialog box appears.

3. Select INSERT Clause Library.

4. Click the

Open button next to the Clause library to insert box to browse for and select the file. Click OK when
you are finished.

Note:
To insert a clause library that is located in a folder separate from its host template, you must include the folder path,
or at least some portion of it. For example, a clause library can be inserted from a subfolder of the host template
(INSERT "Subfolder\ClauseLib.hdl"); or it can be inserted using a full file path (INSERT "C:\My Documents
\ClauseLib.hdl"); or it can be inserted using a reference path (INSERT "^referencePath\ClauseLib.hdl").

Copyright 2010 HotDocs Ltd. All rights reserved

380

Help Topics for HotDocs Developer 10

Edit an Existing Clause

Once you have created a clause component, you can edit it at any time. Clause components can be edited from the
template where the INSERT Clause instruction is, from the clause library that contains the clause, and from Component
Manager. Likewise, when you edit a clause, you can edit both the properties of the clause component (for example, the
prompt, the resource, and so forth) and the clause text itself.
To edit a clause

1. Open the Clause Editor using any of the following methods:

Select the clause at the clause library and click

Edit.

In Component Manager, select the clause in the Components list and click

Edit Component.

In the template, place your cursor in the INSERT Clause instruction and click the

Insert Field button.

2. Make any changes to the clause component by editing the Properties or the Resources.
3. Optionally, to edit the clause text, click Edit Clause Text at the Clause Editor. (Click

Save and Close Template

on the HotDocs toolbar to save your changes to the text.)

Caution:
In Word, the word processor may insert an extra hard return at the end of a new clause. To fix this, select the clause
at the clause library and click Edit. The Clause Editor appears, where you can click
Edit Clause Text. When
your text appears, delete the extra hard return. (Click the Show / Hide button in the Word toolbar to view paragraph
marks.)

Copyright 2010 HotDocs Ltd. All rights reserved

381

Help Topics for HotDocs Developer 10

Group Clause Components in One Custom Dialog

If your template contains several clauses from which the user must choose (meaning the clauses are inserted using
INSERT IF instructions), you can group the clauses in one dialog instead of displaying each clause option in its own
dialog. You can allow the user to select either one clause or multiple clauses.
To group clauses in a dialog

1. At the template, create the clauses you want the user to choose from, making sure you select INSERT clause only
IF selected at each clause's INSERT Field dialog box. (See Create and Insert Clauses Directly in Template.)

2. Create a dialog for the clauses. (See Gather Questions into a Custom Dialog.)
3. Once you have added the clauses to the Contents box at the Dialog Editor, click the Options tab. The window
changes to show several custom options.

4. Click the Selection grouping drop-down button and select either Select One or Select All That Apply, depending
on how many clauses you want your users to select.
Note:
Be careful not to create a custom dialog that contains variables from two or more different clauses. If the user selects
one clause and not the other, HotDocs might present a dialog that asks for unnecessary information. If youre going to
create custom dialogs, limit each dialog to include only those variables used in a single clause.

Copyright 2010 HotDocs Ltd. All rights reserved

382

Help Topics for HotDocs Developer 10

Chapter 28: Defining the Interview for the Document

Overview: HotDocs Interviews
Once a template is automated, users can assemble it to create a custom document. During this assembly process,
the variables you've included in the template are presented as questions so users can enter their information. These
questions make up the interview for the template. The interview is viewable by clicking the Interview tab of the assembly
window.
By default, HotDocs creates this interview by reading through the document by starting at the top left corner and finishing
at the bottom-right corner. (This is just as if you are reading through the document.) During this process, when HotDocs
finds a variable, it displays it in the interview. If the variable is linked to a dialog, HotDocs displays the dialog instead. As
it reads through the template, HotDocs also processes and executes any other instructions in the template, such as IF
instructions, REPEAT instructions, and INSERT instructions. All of these things together create a default interview. See
Have HotDocs Generate a Default Interview for details.
At times, you may want the order questions are asked in the interview to be a little different. If this is the case, you can
override the default interview with your own custom interview. You can do this by creating a Computation variable that
uses ASK DIALOG instructions to specify the new order. See Improve Interview Speed Using a Custom Interview for a
description of this process.
Sometimes, when templates are more complex, this complexity can make the interview sluggish. (This is especially
noticeable as users move between dialogs or change answers that update other questions in the dialog.) In situations
like this, you can use a custom interview to minimize the amount of script processing that has to happen to generate the
interview. See Improve Interview Speed Using a Custom Interview for a description of this process.

Copyright 2010 HotDocs Ltd. All rights reserved

383

Help Topics for HotDocs Developer 10

Have HotDocs Generate a Default Interview

When you assemble a template, HotDocs displays an interview, based on variables and instructions it finds in the
template. An outline of the interview is displayed in the left pane of the assembly window.
This interview is comprised of dialogs that contain one or more questions, which the user must answer to assemble a
complete document. As users answer questions, the outline updates to show which questions are still unanswered.
By default, HotDocs generates this interview by asking variables as it reads them in the template. When a variable is
linked to a dialog, the dialog is asked. For most templates, this default interview is sufficient. (However, if you need control
over the order questions are asked in the interview, you can create a custom interview component. See Define a Custom
Interview for details.)
To generate a default interview for a template

1. Open Component Manager. (See Open and Close Component Manager.)

2. Click the

Component File Properties button. The Component File Properties dialog box appears.

3. Click the Interview tab. The window changes to show interview options.
4. Select Generate default interview.
Now, whenever this template is assembled, the questions in the interview will be asked based on the order they are asked
in the template.
If you want to control the appearance of just one or two dialogs in the interview, you can insert ASK instructions at the
place in the template where you want your questions asked. See Control When Your Dialogs Appear for details. If you
want to use a custom interview script, see Define a Custom Interview.

Copyright 2010 HotDocs Ltd. All rights reserved

384

Help Topics for HotDocs Developer 10

Define a Custom Interview

When you assemble a template, HotDocs displays an interview, based on variables and instructions it finds in the
template. An outline of the interview is displayed in the left pane of the assembly window.
This interview is comprised of dialogs that contain one or more questions, which the user must answer to assemble a
complete document. As users answer questions, the outline updates to show which questions are still unanswered.
By default, HotDocs generates this interview by asking variables as it reads them in the template. When a variable is
linked to a dialog, the dialog is asked. For most templates, this default interview is sufficient.
However, if you need control over the order questions are asked in the interview, you can create a custom interview
component. A custom interview is defined by a computation script in which you use a series of ASK instructions to ask the
variables and dialogs in your template. A custom interview can also contain other scripting, such as IF instructions and
REPEAT instructions.
One reason why it may be beneficial to create a custom interview is to speed up the process with which HotDocs displays
and updates the interview. To explain, during assembly, the interview that is presented to the user is dynamic. This
means that each time a user enters an answer, the entire interview is updated to reflect any changes caused by that
answer. Depending on the complexity of the template and the frequency with which variables and instructions are used
in the template, this updating may take longer than expected because HotDocs must process each field. By creating a
custom interview, you can create a script that asks these components and processes these instructions just once, thereby
reducing the number of times HotDocs has to process each field. This can improve assembly speed considerably. (For a
detailed description of how a complex template can slow interview speed, see Improve Interview Speed Using a Custom
Interview.)
There are two parts to using a custom interview in your template:
Create the custom interview component that contains all of your scripting.
Specify a component file property that tells HotDocs to use the component when generating the interview.
To create a custom interview

1. At the template (which should be completely automated), open Component Manager. (See Open and Close
Component Manager.)

2. Select Computation Variables from the Components drop-down list and click the

New Component button.

HotDocs opens the Computation Editor.

3. Enter a name in the Variable name box. (The component can use any name, including INTERVIEW.)
4. Using a series of instructions, specify how you want variables in the template to be asked, based on the logic you
use in the template. For example, you can create a series of ASK instructions that ask the dialogs, as well as use IF
instructions to make variables in the template conditional upon users' answers.

5. Click OK when you are finished.

Once you have created the custom interview, you must specify a component file property that tells HotDocs to use
the computation when it generates the interview.

6. With Component Manager still open, click the

Component File Properties button. The Component File

Properties dialog box appears.

7. Click the Interview tab and select Use custom interview.

8. Specify the name of the Computation variable in the Interview component box.
Now, HotDocs will use this computation to generate the interview.

Copyright 2010 HotDocs Ltd. All rights reserved

385

Help Topics for HotDocs Developer 10

Note:
If you are pointing several templates to a shared component file, but you want each template to use its own
custom interview, at the Interview tab, clear Use Interview properties stored in the shared component
file, select Use custom interview, and then specify the name of the interview computation in the Interview
component box.
In a text template, if you select both Generate default interview and Use custom interview, HotDocs will
always use the custom interview. Any variables not asked in the custom interview will be left out of the interview
altogether. In a form template when both options are selected, HotDocs will present the custom interview first and
then include any variables not asked in the custom interview at the end of the interview outline.

Copyright 2010 HotDocs Ltd. All rights reserved

386

Help Topics for HotDocs Developer 10

Improve Interview Speed Using a Custom Interview

Once you automate a template, the template can be used to generate an interview, which displays the questions the user
must answer in order to produce a complete document.
How HotDocs generates this interview is important to understand. To start, HotDocs reads through the template text and
extracts all variables and instructions from it. This produces what is called an extracted script.
This example shows a short template, followed by its corresponding extracted script:
(Template text)
Last Will of Client Name
I, Client Name, being of sound mind, do make this my last will and testament. IF
Client Marital Status = "Married"My Client Spouse Gender: wife/husbands name is
Spouse Name. Client Spouse Gender: she/he is my personal representative. ELSE IF
Client Marital Status = "Never Married"I have never been married. END IF
(Extracted script)
Client Name
Client Name
IF Client Marital Status = "Married"
Client Spouse Gender: wife/husband
Spouse Name
Client Spouse Gender: She/He
ELSE IF Client Marital Status = "Never Married"
END IF
Once HotDocs creates this script, it then processes the script and asks any variables referenced in it, displaying those
questions in the interview. (When a variable is linked to a dialog, HotDocs displays the dialog instead.) Additionally,
HotDocs processes other instructions (such as ASK, REPEAT, or IF instructions) included in the extracted script.
While the extracted script may refer to a variable or instruction multiple times, once the variable or instruction has been
answered, it will not be asked again.
For most templates, allowing HotDocs to generate the interview this way is sufficient. In fact, all templates are set, by
default, to use this method.
For complicated templates that contain a lot of scripting, however, this default interview generation may produce an
interview that is sluggish for the user to navigate. This is because HotDocs must repeatedly process every variable and
instruction in the extracted scripteven if the user has already answered the question or the instruction has already been
executed. Depending on the complexity of the script, processing this script may cause a delay when moving between
answers in the dialog or between dialogs in the interview.
If this happens, you can create a custom interview that contains only the required scripting and variables. You create
this script using a Computation variable. Once you write the custom interview script, you must select a component file
property that tells HotDocs to use this script instead of the default extracted script. The following example shows a custom
interview script that might be created for the template shown above:
(Custom interview script)
ASK Client Information
IF Client Marital Status = "Married"
ASK Spouse Name
END IF
For instructions on creating a custom interview so you can improve the responsiveness of the interview, see Define a
Custom Interview.

Copyright 2010 HotDocs Ltd. All rights reserved

387

Help Topics for HotDocs Developer 10

Automatically Disable Irrelevant Variables in Interviews

When creating dialogs, you frequently need variables within a dialog to be dynamic. For example, you may want to
disable some questions in a dialog until a user answers a different question in the dialog a specific way. To accomplish
this, you can either write a script (see Use Scripts to Add Power to Your Dialogs) or you can have HotDocs automatically
hide or disable variables, based on whether they are used in the document.
For example, say you have a dialog that asks (using True/False variables) whether a client has any pre-existing health
conditions. If the client does, he or she must enter an explanation for each health condition. You can set variable
preferences that keep the explanations from being asked unless the corresponding True/False questions are answered
affirmatively. Then, if a dialog contains all inactive variables, you can keep the dialog from being asked in the interview.
Note:
When you start an assembly, HotDocs processes the template and determines which variables are referred to in
instructions, merged in the document, and so forth, based on the current answers. If a variable is unused, for example,
if you answer a conditional True/False variable such that it doesn't merge the associated Text variable, the Text
variable will be grayed or hidden in the dialog. (A third option lets you always show the variable, even if it's unused.)
Once this "usage pass" is done in the template, HotDocs does another pass through the template and generates the
interview.
There are three steps to automatically disabling unused variables:
Specifying at the variable level whether variables should be grayed or hidden if they're not needed in the document.
Specifying at the dialog level whether dialogs that contain only irrelevant variables should be left out of the interview
entirely.
Selecting a component file property that automatically disables irrelevant variables in the interview.
To mark how variables should be treated if they're not needed in the document

1. Edit the variable. (See Edit a Variable.)

2. At the Advanced tab of the Variable Editor, click the When irrelevant drop-down button and choose an option:
Default causes the variable to use the default setting, which you define at Component File Properties.
Gray causes the variable to appear grayed out if it is unused in the document. (This is the default option for all
variables.)
Hide causes the variable to be hidden if the variable is unused in the document. If the answer file changes and
the variable is needed, the variable will be shown in the dialog.
Show causes the variable to always appear in the dialog, regardless of whether it's used or not.
To automatically exclude dialogs that contain only irrelevant variables

1. Edit the dialog. (See Edit a Custom Dialog.)

2. Click the Options tab. The view changes to show the different options for displaying a dialog.
3. Select Hide this dialog when all variables are inactive.
To automatically disable unused variables in the interview

1. Open Component Manager for the template. (See Open and Close Component Manager.)
2. Click the

Component File Properties button. The Component File Properties dialog box appears.

3. Click the Interview tab. The view changes to show interview options.
4. Select Automatically disable irrelevant variables and dialogs.
5. Click the Default drop-down button and choose one of the options from the list:
Copyright 2010 HotDocs Ltd. All rights reserved

388

Help Topics for HotDocs Developer 10

Gray causes all variables with their irrelevant status set to Default to be grayed.
Hide causes all variables with their irrelevant status set to Default to be hidden.
Show causes all variables with their irrelevant status set to Default to always be asked, even if the variable is
irrelevant.
Note:
Model documents assembled from markup are set to automatically disable unused variables. For information on
marking up model documents, see Overview: Create a Model Document.
Caution:
Even when variables are automatically disabled, they will always be visible in pop-up dialogs users view when they
click a form field wizard button.

Copyright 2010 HotDocs Ltd. All rights reserved

389

Help Topics for HotDocs Developer 10

Chapter 29: Using Dot Codes to Format Text and Insert Special Characters
Overview: Dot Codes
Working with Plain Text
When working with plain texteither in variable prompts, dialog element text, plain-text resources, or in answers
generated by computation scriptsyou frequently want to assign font properties to the text, such as bolding, italicizing,
and underlining. Additionally, you may want to punctuate and capitalize characters in plain text as well as insert special
characters, such as hyphens and other punctuation marks.
To do this, you insert dot code fields in the your prompts, text, or scripts. During assembly, these dot codes will be
processed and will apply whatever formatting you specify to the text with which you are working.
Note:
Unfortunately, dot codes that format answer text in a form document cannot be processed. This is because the text
is in plain-text format and cannot support formatting, like bold and italics. To explain, think of when you've worked
on a plain-text document in Notepad. You can insert characters like line breaks, section symbols, and punctuation in
a Notepad document, but you cannot make character-level formatting changes. HotDocs uses this same plain text
in form document answers. Dot codes that insert characters (such as line breaks, section symbols, and so forth),
however, are processed without any problems in forms.

Punctuating Non-Repeated Lists

Dot codes can also be used to merge punctuation for non-repeated lists in the template. Using a series of dot codes, you
can define the punctuation mark that should be used to separate items in the list as well as define the conjunction used for
the list. This is useful when you have separate answers that are being merged conditionally in list format.

Full List of Dot Codes

The following table lists all of the dot codes that are available in HotDocs:
Dot Code

What It Does

Punctuation and
Capitalization Dot Codes
.

Inserts a period if no other punctuation precedes it

Inserts a comma if no other punctuation precedes it

Inserts a semicolon if no other punctuation precedes it

Inserts a colon if no other punctuation precedes it

Inserts an exclamation point if no other punctuation precedes it

Inserts a question mark if no other punctuation precedes it

.a/.ae

Capitalizes very letter in the selected text

.c

Capitalizes the word immediately following the code

.l/.le

Capitalizes the first letter of each word in the enclosed text

.s/.se

Capitalizes each letter in the enclosed text and displays the text at a smaller font size

Copyright 2010 HotDocs Ltd. All rights reserved

390

Help Topics for HotDocs Developer 10

Font Formatting Dot

Codes
.b/.be

Applies bold formatting to the enclosed word or group of words

.h/.he

Applies the hidden text property to a word or group of words

.i/.ie

Applies italic formatting to a word or group of words

.u/.ue

Applies underline formatting to a word or group of words

.x/.xe

Crosses out a word or group of words

.z/.ze

Increases or decreases the font size for a word or group of words by a specified
percentage.The dot code, .z +Size, is a percent increase in the current size. The dot
code, .z -Size is a percent decrease in the current size. (When you select this option,
HotDocs displays a dialog box asking you to specify these properties.)

Character Dot Codes

.an

Inserts a or an, depending on whether the word that follows begins with a consonant or a
vowel.

.la/.ra

Inserts a left or right apostrophe

.lq/.rq

Inserts a left or right quotation mark

.ps

Inserts a paragraph character

.ss

Inserts a section symbol character

.tc

Inserts a tab character

.lb

Inserts a line break

.pm

Inserts a paragraph mark

.pb

Inserts a page break

.ns

Inserts a non-breaking space character

.nh

Inserts a non-breaking hyphen character

.oh

Inserts an optional hyphen character

Non-Repeated List
Punctuation Dot Codes
.p "style"/.p/.pe

Identifies the beginning of a punctuated list and assigns the punctuation format to it. The
second dot code then identifies where the punctuation character should be inserted.
Finally, the closing dot code identifies where the punctuated list ends.

Web Link Dot Code

.w "URL"/.we

Inserts a Web link. Enter the link text between the two dot codes.

Copyright 2010 HotDocs Ltd. All rights reserved

391

Help Topics for HotDocs Developer 10

Change Font Properties of Text

Caution:
Dot codes that change the character format (bold, italic, font size, etc.) do not work in prompts for True/False and
Multiple Choice variables that are set to appear as buttons or check boxes.
Frequently, you use a computation script to generate an answer that must be merged in the document. Because answers
generated by a computation script are in plain text (which can't be formatted at the Script Editor), you can insert formatting
dot codes in the plain text. These dot codes will be processed and the formatting will be applied once the answer is
merged in the document.
Additionally, you can use dot codes to assign formatting to variable prompts and dialog element text. This allows
questions in the interview to be formatted according to your needs. Specifically, using dot codes, you can apply font
properties (such as bolding and italicizing) to answers. You can also specify font sizes and capitalization.
When formatting sections of text using dot codes, you must first highlight the text you are formatting before you assign
the dot code. This surrounds the text with beginning and ending codes that instruct HotDocs where the formatting
starts and stops. Additionally, when you insert multiple dot codes for a single block of text, the codes must be nested,
meaning the first opening dot code you assign must be the last closing dot code. For example, this is an example of
.b.inesting.ie.be.
To apply formatting to plain text

1. Either edit a Computation variable (See Customize a Computation Variable), or edit a prompt or dialog element text
(see Create a Prompt for a Variable and Add Text to Your Dialogs).

2. Highlight the text you want to format and right-click. A shortcut menu appears.
3. Choose Character Format > Format (where Format represents one of the dot codes described in the following
table). (WordPerfect users: To insert the dot codes, manually type the codes as you see them in the table below.)
Dot Code

What It Does

.b (Bold)

Applies bold formatting to a word or group of words.

.be (Bold End)

.h (Hidden)

Applies the hidden text property to a word or group of words.

.he (Hidden End)

Caution:
The hidden property
is not supported in
WordPerfect templates.
.i (Italics)

Applies italic formatting to a word or group of words.

.ie (Italics End)

.u (Underline)

Applies underline formatting to a word or group of words.

.ue (Underline End)

.x (Strike-through)

Crosses out a word or group of words.

.xe (Strike-through End)

.z (Font size)
.ze (Font size End)

Increases or decreases the font size for a word or group of words by a specified
percentage. The dot code, .z +Size, is a percent increase in the current size. The
dot code, .z -Size is a percent decrease in the current size. (When you select this
option, HotDocs displays a dialog box asking you to specify these properties.)

Copyright 2010 HotDocs Ltd. All rights reserved

392

Help Topics for HotDocs Developer 10

Dot Code
Caution:
The font size options
are not supported in
WordPerfect templates.

What It Does

The following is an example of a computation script that uses dot codes. The account status is bolded:
IF DAYS FROM( Purchase Date, TODAY ) > 60
"Your account is .bpast due.be."
ELSE
"Your account is .bcurrent.be. Thank you."
END IF
Likewise, this is an example of a variable's plain-text resource that uses dot codes. Here, the name of a required form is
italicized:
To get free service of the court's orders without paying a fee, you must fill out and
file the .iRequest and Order for Free Service of Restraining Order.ie.
Note:
When you type double angle brackets (<< >>), HotDocs converts them to chevrons ( ). You can manually enter the
dot code by typing the brackets with the format code between them.

Copyright 2010 HotDocs Ltd. All rights reserved

393

Help Topics for HotDocs Developer 10

Insert a Web Link in a Prompt or Dialog Text Element

You can use a Web link dot code (.w "URL"/.we) to add a Web address to a variable prompt or dialog element text.
The user will be able to click this link during the interview and a separate browser window (displaying the specified Web
page) will appear.
To include a Web address in a prompt or dialog text element

1. Edit a prompt or dialog text element. (see Create a Prompt for a Variable and Add Text to Your Dialogs.)
2. Place your cursor where you want the link to appear and right-click. A shortcut menu appears.
3. Choose Web Link. The Web Link dialog box appears.
4. In the URL box, enter the complete Web address for the page you want the hyperlink to open. (Make sure the URL
is entered correctly. Include http:// or https:// or ftp://, depending on what type of URL it is.)

5. Enter the text you want the user to see for the link in the Link text box.
Note:
Before creating the Web link, you can select existing text in the prompt or dialog element text and that text will be
used as the Link text.
If you don't know the exact URL for the Web page, click the
for the Web page.

Browse Web button next the URL box to search

You can include a link that opens an e-mail message rather than a Web address. To do this, enter
mailto:, followed by the email address you want included, in the URL box. (For example, enter
mailto:[email protected].)

Copyright 2010 HotDocs Ltd. All rights reserved

394

Help Topics for HotDocs Developer 10

Add Punctuation and Capitalization to Sentences

Sometimes you need answers in the assembled document to be capitalized and punctuated correctly, but you can't
anticipate how users will enter the answer. To ensure text in the document is correct, you can use dot codes to merge the
correct capitalization and punctuation.
For example, say the user enters a description but doesn't include the end punctuation in the answer. Using a dot code,
you can merge the punctuation in the document if the user doesn't. (If the user does include the punctuation, the dot code
won't merge anything.) The following script demonstrates this:
The property, which is located at Property Address, is described as Property
Description.
To add punctuation and capitalization dot codes

1. Either edit a Computation variable (See Customize a Computation Variable), or insert your cursor in the template
text where you want to insert the dot code.

2. To insert a punctuation mark, right-click to display the shortcut menu and choose Sentence Punctuation >
Punctuation Mark (where Punctuation Mark represents one of the dot codes described in the following table.
(WordPerfect users: To insert the dot codes, manually type the codes as you see them in the table below.)
Dot Code

What It Does

Inserts a period if no other punctuation precedes it.

Inserts a comma if no other punctuation precedes it.

Inserts a semicolon if no other punctuation precedes it.

Inserts a colon if no other punctuation precedes it.

Inserts an exclamation point if no other punctuation precedes it.

Inserts a question mark if no other punctuation precedes it.

3. To change the capitalization of text, right-click to display the shortcut menu and choose Character Format >
Capitalization (where Capitalization represents one of the dot codes described in the following table:
Dot Code

What It Does

.a (All Caps)

Capitalizes every letter in the selected text.

.ae (All Caps End)

.c (Capitalize Letter)

Capitalizes the first letter of the word immediately following the code.

.l (Leading Caps)

Capitalizes the first letter of each word in the selected text.

.le (Leading Caps End)

.s (Small Caps)

Capitalizes each letter in the selected text and displays the text at a smaller font size.

.se (Small Caps End)

Note:
When you type double angle brackets (<< >>), HotDocs converts them to chevrons ( ). You can manually enter the
dot code by typing the brackets with the format code between them.

Copyright 2010 HotDocs Ltd. All rights reserved

395

Help Topics for HotDocs Developer 10

Insert Characters in Text Strings

When working with plain text in both computation results and in variable prompts, dialog element text, and resources,
you frequently need to insert a character not typically supported by the plain-text character set. Using dot codes, you
can insert these characters so that when the answer is merged in the document, the dot codes are processed and the
sentence is punctuated correctly.
For example, if you are merging a literal text string in a computation script and the text needs smart quotation marks (and
not straight quotation marks), you can insert the dot codes that merge the correct marks.
To insert special characters in plain text

1. Either edit a Computation variable (See Customize a Computation Variable) or edit a prompt or dialog text element.
(see Create a Prompt for a Variable and Add Text to Your Dialogs.)

2. Place your cursor where you want the character and right-click. A shortcut menu appears.
3. Choose Character Insertion > Character (where Character represents one of the dot codes described in the
following table). (WordPerfect users: To insert the dot codes, manually type the codes as you see them in the table
below.)
Dot Code

What It Does

.an (An)

Inserts a or an, depending on whether the word that follows begins with a consonant
or a vowel. For example,
Employee Name, .anJob Title
becomes
Jack Carey, a paralegal
or
Bonnie Millet, an attorney

.la (Left Apostrophe)

Inserts a left or right apostrophe.

.ra (Right Apostrophe)

.lq (Left Quote)

Inserts a left or right quotation mark.

.rq (Right Quote)

.ps (Paragraph Symbol
)

Inserts a paragraph character.

.ss (Section Symbol )

Inserts a section symbol character.

.tc (Tab Character)

Inserts a tab character.

.lb (Line Break)

Inserts a line break.

.pm (Paragraph Mark)

Inserts a paragraph end.

.pb (Page Break)

Inserts a page break.

.ns (Non-breaking
Space)

Inserts a non-breaking space character.

.nh (Non-breaking
Hyphen)

Inserts a non-breaking hyphen character.

.oh (Optional Hyphen)

Inserts an optional hyphen character.

Copyright 2010 HotDocs Ltd. All rights reserved

396

Help Topics for HotDocs Developer 10

Note:
When you type double angle brackets (<< >>), HotDocs converts them to chevrons ( ). You can manually enter the
dot code by typing the brackets with the format code between them.

Copyright 2010 HotDocs Ltd. All rights reserved

397

Help Topics for HotDocs Developer 10

Punctuate Non-Repeated Lists of Answers

Sometimes you create lists of answers in a template without using a REPEAT instruction. Often, you need a way to
punctuate the list, depending on answers that are merged. For example, say you need to list the client name, the client's
spouse's name (if the client is married), and the children's names (if there are children). Such a list could look like this in
the assembled document:
The client's family consists of Tim Anderson, spouse Lori Anderson, and children
Jessica Anderson, Aubrey Anderson, and Lance Anderson.
However, not all clients will be married, nor will all clients have children. Because of this, you need some way to punctuate
the sentence, based on which answers are added to the list. You can accomplish this using a series of dot codes that
punctuate a sentence (including adding a conjunction between items in the list), depending on where answers are merged
in the document.
To punctuate a non-repeated list

1. Edit the template. (See Edit a Template.)

2. In the template text where you want to merge the list punctuation, right-click and choose List Punctuation >
Punctuation from the Word shortcut menu (where Punctuation represents the mark you want to insert, based on the
following table). (WordPerfect users: To insert the dot codes, manually type the codes as you see them in the table
below.)
Dot Code

What It Does

.p "style" (Punctuation
Format)

Identifies the beginning of a punctuated list and assigns the punctuation format.

.p (Punctuation)

Identifies the spot where punctuation character should be inserted.

.pe (Punctuation End)

Identifies the end of the punctuated list.

The following is an example of how punctuation dot codes are used in the text of a template. The first dot code (.p "a, b,
and c") indicates the start of the list (and specifies the punctuation and conjunction that should be used). Each item that
is added to the list is marked by a punctuation code (.p) which indicates where the punctuation mark should be merged.
The end punctuation mark (.pe) indicates the end of the list:
.p "a, b, and c"The client's family consists of Client Name.pIF Client is
Marriedspouse Spouse Name.pEND IFIF Client Has Childrenchildren REPEAT
Children:a, b, and cChild NameEND REPEAT.pEND IF.pe.
In this example, there are really two listsfirst, the list of family members (client, spouse, and children) and then
second, the list of individual children. While dot codes are used to punctuate this first list, the repeat format for the
REPEAT instruction punctuates the list of children. However, you can use dot codes to punctuate the items in a REPEAT
instruction, as well. The following script demonstrates how to nest these dot codes:
.p "a, b, and c"The client's family consists of Client Name.pIF Client is
Marriedspouse Spouse Name.pEND IFIF Client Has Children.p "a, b, and
c"children REPEAT ChildrenChild Name.pEND REPEAT.pe.pEND IF.pe.

Copyright 2010 HotDocs Ltd. All rights reserved

398

Help Topics for HotDocs Developer 10

Chapter 30: Using Instruction Models

Use Operators When Scripting
An operator is a symbol or word that causes an operation such as addition or a comparison to be performed in a
computation or expression. Operators are available at the Operators list wherever you can create a script or expression.
Most operators can be used when working with both number and text values.
There are three types of operators:
Comparison operators: These compare two values of the same type (text, number, date, multiple choice, or true/
false). They return values of true or false depending on whether the comparison is true or not.
Arithmetic operators: These calculate new values. Operands used in the script must be the same type.
Logical operators: These return a true/false value based on a logical comparison of their operands, both of which
must be true or false values.
The following tables explain how each operator works:
Comparison Operator

Description

The two items in the comparison are of equal value. For example:
Birth Date = 17 Dec 1989
Employee Name = "Louisa Gehrig"

!=

The two items in the comparison are not of equal value. For example:
IF Exhibit A != TRUE
IF Plaintiff Gender != "Male"

<

The first item in the comparison has a lesser value than the second item. For example:
Account Balance < 9000
COUNTER < 10

>

The first item in the comparison has a greater value than the second item. For example:
Dependent Age > 18

<=

The first item in the comparison is less than or equal to the second item. For example:
Client Age <= 65
COUNTER <= 2

>=

The first item in the comparison is greater than or equal to the second item. For example:
Taxed Income >= 75000

CONTAINS

The value of the first item is found in the value of the second item. For example:
"massachusetts virginia kentucky pennsylvania" CONTAINS State
Name

Arithmetic Operator

Description

Add the different components of the script together. For example:

Value 1 + Value 2
Street Address + ", " + City + ", " + State

Subtract the different components of the script from each other. For example:
Monthly Income - Amount of Owed Child Support

Copyright 2010 HotDocs Ltd. All rights reserved

399

Help Topics for HotDocs Developer 10

Multiply the different components of the script. For example:

Purchase Price * 0.625

Divide the different components of the script. For example:

Yearly Salary / 12

The unary minus operator results in the numeric negation of the operand (which must be
a Number value). For example:
SET Loss Amount TO - Aggregate Amount

The unary percent operator results in the operand (which must be a Number value)
divided by 100. It is a postfix operator. For example:
Purchase Price + (Purchase Price * 6.25%)

Logical Operator

Description

AND

The statement to the left and the statement to the right must both be true. For example:
IF Client is Married AND Client has Children

OR

The statement to the left or the statement to the right must be true. For example:
IF Single OR Widowed

NOT

The NOT operator results in the logical negation of the operand (which must be a True/
False value). For example:
IF NOT Client is Married

Note:
HotDocs also supports two other unary operatorsunary plus (+) and the dollar sign ($). While both produce
numeric results in a script, the results are exactly the same as the operands. Therefore, they should not be used
in a script.
The Add ( + ) operator can also be used to string together (concatenate) two text values.
The final operator, the parentheses ( ), instructs HotDocs to perform the operation inside the parentheses first.
HotDocs operators are processed in the following order of precedence, from highest to lowest. Operators listed on the
same line have the same precedence.
()
NOT - %
* /
+ = != < > <= >=
AND
OR
So in other words, when HotDocs is evaluating an expression, first parenthesis are used to determine order of operations,
then unary operators, then multiplication and division, then plus and minus, then comparisons, then logical AND, and last
logical OR.

Copyright 2010 HotDocs Ltd. All rights reserved

400

Help Topics for HotDocs Developer 10

Use Line Breaks, Paragraph Ends, and Tabs in Computation Scripts

Caution:
Inserting line breaks and paragraph ends are only relevant if you are merging text into an assembled Word document.
In WordPerfect, each of the commands listed below inserts a hard return. (See the WordPerfect helps for an
explanation.)
When including literal text strings in computation scripts, you can have HotDocs merge line breaks, paragraph ends,
and tabs in the answer. To do this, at the Script box, either manually enter the characters, or use a dot code. Use the
following information:
To insert

Do one of the following

A line break

Press Enter or Shift+Enter. When you do this, HotDocs creates a new line of text in the
same paragraph.
Note:
When you use a line break to span a literal text string across two lines in the script
editor, the color coding assigned to the text string changes to the default color. This
doesn't affect how the computation will be processed, but it may make it more difficult
to visually recognize the different portions of your script. To fix the color coding, click
the

Auto Format button.

Insert a Line Break dot code (.lb) at the place you want HotDocs to start a new line.
(See Insert Characters in Text Strings.)
A paragraph end

Press Ctrl+Enter. When you do this, HotDocs inserts a paragraph mark ( ) and starts a
new paragraph of text.
Insert a Paragraph Mark dot code (.pm) at the place you want HotDocs to start a new
paragraph. (See Insert Characters in Text Strings.)

A tab character

Press Ctrl+T.
If you want the Tab key to insert a tab character (instead of you pressing Ctrl+T), click
the
Options button and select Tab key inserts a tab in scripts. Now, whenever you
press Tab or Shift+Tab, HotDocs will insert a tab in the script instead of taking you to
another field in the dialog box.
Insert a Tab Character dot code (.tc) at the place you want the text to be tabbed. (See
Insert Characters in Text Strings.)

When creating multi-line Text variables, you can force HotDocs to merge a paragraph mark (rather than a line break)
when the user presses Enter. For details, see Customize a Text Variable.

Copyright 2010 HotDocs Ltd. All rights reserved

401

Help Topics for HotDocs Developer 10

Use the Script Editor

When writing a computation script, there are several tools you can use to make the process easier.
To use the script editor

1. Edit the script or expression.

2. At the Script or Expression box, complete any of the following tasks:
To

Do This

Have HotDocs
automatically complete
keywords, component
names, and Multiple
Choice options as you type

Place your cursor in the Script box and press Ctrl+Spacebar. HotDocs displays
a list of instruction and expression keywords, constant values (such as month
abbreviations), and components. Type a portion of the keyword, component name, or
Multiple Choice option for which you are searching. As you type, HotDocs filters the
list to show only those keywords that contain the text you have typed. Once selected,
press Enter to merge it into your script.
To keep seldom-used keywords out of the auto-complete list, click the
Options
button and clear Include seldom-used keywords in auto-complete list.

Access just a list of

components

Press the F5 key, select the component, and press Enter.

Access just a list of

keywords

Press Shift+F5, select the keyword, and press Enter.

Display a syntactical hint

Place your cursor inside the keyword and press the F7 key. HotDocs displays a small
of how an instruction or
ToolTip that shows the entire model as well as the type of value it produces, if it's an
expression should be used expression.
Indent matching pairs of IF
and REPEAT instructions
based on the level of their
insertion

Click the

Auto Format button.

Undo (or cancel) an action

you just performed

Click the

Undo button. HotDocs reverses the change you made.

Redo (or re-implement) an

action you just performed

Click the

Redo button. HotDocs reapplies the change you made.

Cut or copy and paste a

selected portion of the
script

Select the portion of the script you want to cut or copy, and then click the
button or the

Copy button. The script is copied to the Clipboard. To paste the

script in a new location, insert your cursor at that location and click the
button.
Find a specific string of
text in the script

Click the

Cut
Paste

Find button and enter your search text in the Find what box. To find the

next instance of the text, click the

Find Next button.

Note:
To find only those instances of text that are complete words, select Find whole
words only. To find only those instances that have the same capitalization as the
text for which you are searching, select Match case.
Find a specific string
of text in the script and

Click the
Find and Replace button. Enter the search text for which you are
searching in the Find what box, and then enter the replacement text in the Replace

Copyright 2010 HotDocs Ltd. All rights reserved

402

Help Topics for HotDocs Developer 10

To

Do This

replace it with another

string of text

with box. Once you have entered the required text, click Replace, Replace All, or
Find Next.
To find and replace script text in a specific block of script, select the block of script
first and then click the
Find and Replace button. At the Find and Replace dialog
box, select Replace only in selected text.

Move your cursor to a

specific location in the
script

Click the
Go To button. This displays the Go To dialog box, where you can enter
the line number or character position of where you want your cursor to move.

Indent or outdent a block

of the script

Select the portion of the script you want to indent or outdent and click the
button or the
indent.)

Indent

Outdent button. (Click repeatedly to increase or decrease the

Cause HotDocs to ignore a Highlight the block of the script you want to comment and click the
Comment
section of the script when
Block button. This puts two forward slashes in front of each line of the script, which
it processes it, or insert a
instructs HotDocs to ignore this section. To uncomment it, highlight the text and click
comment in the script
the
Uncomment Block button.
Match an IF or REPEAT
instruction with its END
IF or END REPEAT
instruction (or vice versa)

Place your cursor inside the instruction, right-click, and select Match IF/REPEAT
from the shortcut menu. (You can also press Ctrl+M.)

Highlight an entire IF
or REPEAT instruction
block (meaning everything
between a beginning
and ending IF/REPEAT
instruction)

Place your cursor inside the instruction, right-click, and select Select IF/REPEAT
from the shortcut menu. (You can also press Ctrl+Shift+M.)

View helpful information

while using the script
editor, including accessing
help topics for the
different instructions and
expressions you can use
in your script

Click the

Customize the way the

script editor works

Click the
Options.)

Insert line breaks and tab

characters in a script

See Use Line Breaks, Paragraph Ends, and Tabs in Computation Scripts.

Assign formatting
characteristics to literal
text strings in a script

Insert the corresponding dot code. See one of the following topics for details:

HotDocs Help button.

Options button and make your changes. (See Change Script Editing

Change Font Properties of Text

Insert Characters in Text Strings
Add Punctuation and Capitalization to Sentences

Note:
To access the script editor toolbar using the keyboard, press F10.
To access help for each instruction or expression, first select the model in one of the lists and then press Ctrl+F1.
Copyright 2010 HotDocs Ltd. All rights reserved

403

Help Topics for HotDocs Developer 10

For an explanation of the HotDocs scripting language, see Understand the HotDocs Scripting Language. For
details on creating a Computation variable, see Customize a Computation Variable. For a list of instruction and
expression models, see Overview: Instruction and Expression Models.

Copyright 2010 HotDocs Ltd. All rights reserved

404

Help Topics for HotDocs Developer 10

View an Outline of Scripting in the Template

Note:
The HotDocs Outliner is supported in Microsoft Word 2000 and later only.
Using the HotDocs Outliner, you can generate an outline of scripting in the template. This outline can include just a list of
instructions used in the template, or it can include variables as well. Items in the outline appear in the same order as they
are used in the template. Viewing this outline may help you better understand the logic used in the template.
You can expand the outline to view all nested instructions in the template. You can also click on entries in the outline and
view where that particular variable or instruction is merged in the template (and vice-versa). You can also view a single
variable or instruction and see just the conditions or instructions surrounding that particular instance.
To view a scripting outline

1. Edit a Word text template. (See Edit a Template.)

2. In the HotDocs Edit toolbar, click the

HotDocs Outliner button. The HotDocs Outliner window appears.

3. Perform any tasks, as described in the following table:

To

Do This

Arrange the Outliner with

Adjust the Outliner to the width you want and click the
the Microsoft Word window
View all instructions in the
templateincluding all
nested instructions

Click the

Arrange Windows button.

Expand All button. The outline expands to show all levels of instructions.

To collapse the interview outline, click the

Collapse All button.

Update the Outliner after

making changes in the
template

Click the
Refresh Outline button. The outline updates and displays any changes
you've made to the template text.

View the template's cursor

location in the outline

Click the
Synch Template button. Now, when you click in the template, entries in
the outline are highlighted to show where in the outline your cursor position is.

View variables used in the

template

Click the
Show Variables button. The outline expands to include all variables
merged in the template.
Viewing variables allows you to see relationships between variables and any
surrounding instructions.

Apply color coding to

instructions in the outline

Click the
Apply Colors button. The Apply Colors dialog box appears, where you
can choose the color scheme you want to use in the outline:
Choose None to make all variable and instruction entries black.
Choose Regular to mark all variable and instruction entries using a custom
color specific to that field type. For example, all variables will be marked with
one color, all IF instructions will be marked with a different color, all REPEAT
instructions will use a different color, and so forth.
Choose Nested to mark all instructions using a custom color. Where pairs of
REPEAT, IF, or SPAN instructions are nested, each level of nesting will be
marked with its own color.
Choose Sequential to mark all instructions using a custom color. Each pair
of REPEAT, IF, and SPAN instructions in the template will be marked by a
different color.

Copyright 2010 HotDocs Ltd. All rights reserved

405

Help Topics for HotDocs Developer 10

To

Do This

Copy the contents of

the script outline to the
Windows Clipboard so you
can paste it into another
application

Click the
Copy to Clipboard button. The entire outline is copied. Open another
application and then paste the script using that application's Paste command.

View all conditions or other Select Limit to and then click the drop-down button to select the variable you want
instructions surrounding
to view. The outline changes to show any REPEAT or IF instructions that affect that
the inclusion of a specific
particular variable.
variable in the outline
View the conditions
or other instructions
surrounding the cursor
position in the template

Select Limit to and then choose <cursor position> from the drop-down list. Click in
the template where you want to view these instructions or conditions.

Edit or test an instruction

or variable in the outline

Right-click on the instruction or variable in the outline and choose Edit or Test.

Have HotDocs show you

where in the template
a REPEAT, IF, or
SPAN instruction's END
instruction is inserted

Right-click on the instruction in the outline and choose Find Matching END. In the
template, the instruction is highlighted.

Copyright 2010 HotDocs Ltd. All rights reserved

406

Help Topics for HotDocs Developer 10

Full List of Instruction Models

Instruction

Description

ADD TEXT TO
MULT_CHOICE_VAR;
CLEAR
MULT_CHOICE_VAR

These instructions allow you to modify options of a Multiple Choice variable. The CLEAR
instruction removes all the current options, and the ADD instruction adds options to the
variable.

ASCEND VAR; DESCEND

VAR

The ASCEND instruction sorts lists of answers (gathered using a REPEAT instruction) in
alphanumeric order, from 1 to 9, and from A to Z. The DESCEND instruction sorts lists of
answers from 9 to 1, and from Z to A.

ASK DIALOG

The ASK DIALOG instruction allows you to control the order in which dialogs appear in
an interview. (See Control When Your Dialogs Appear.)

ASK VAR

Sometimes a variable needs to be asked by itself. You can use the ASK VAR instruction
so that during the interview, HotDocs displays the variable in its own default dialog.

ASSEMBLE "FILENAME"

You can use the ASSEMBLE instruction to add templates to the assembly queue. Unlike
the INSERT instruction, an ASSEMBLE instruction waits until the current document is
assembled before starting the next assembly session.

CONCEAL VAR

This instruction, which you use in a dialog script, keeps variables from appearing in the
Select From Answer Source dialog box of an answer source.

DEBUG

This instruction steps through the template or script field by field or line by line. It helps
you determine why the template you are automating (or the script you are writing) is
producing results you don't expect.

DEFAULT VAR TO VALUE

This instruction suggests a value for a variable if the variable is unanswered.

ERASE VAR; ERASE

DIALOG

The ERASE instructions let you clear answers in a dialog. Specifically, ERASE VAR
clears answers for a specified variable in a dialog, while ERASE DIALOG clears all
answers in the dialog. This may be useful when you are using a temporary dialog to store
lists of answers from two or more dialogs.

FILTER
COMPUTATION_VAR

The FILTER instruction filters out certain entries from a repeated list, based on conditions
you specify.

FORMAT "LIST_FORMAT"

The FORMAT "LIST_FORMAT" instruction allows you to create a sentence-style list

within a computation. (If you create the REPEAT instruction using a REPEAT field, you
can specify the list format by choosing a style from the Format drop-down list. See
Punctuate a Sentence-Style List.)

GRAY ALL; GRAY VAR;

UNGRAY ALL; UNGRAY
VAR

These instructions, which are used in a dialog script, control whether components in a
dialog appear grayed or ungrayed, depending on answers a user enters. GRAY ALL dims
all components in the dialog, while UNGRAY ALL makes all of the components active
again. Likewise, GRAY VAR dims a single component, and UNGRAY VAR enables the
component again.

HIDE ALL; HIDE VAR;

SHOW ALL; SHOW VAR

These instructions, which are used in a dialog script, control whether the user is able to
see variables in a dialog. The HIDE ALL instruction hides all variables in the dialog, while

Copyright 2010 HotDocs Ltd. All rights reserved

407

Help Topics for HotDocs Developer 10

SHOW ALL reveals the variables again. Likewise, HIDE VAR hides a single variable, and
SHOW VAR reveals the variable.
IF EXPRESSION; ELSE IF;
ELSE; END IF

You can make sections of templates or scripts conditional by using IF instructions. A

conditional section will be included only if a condition you specify is true. The ELSE IF
instruction allows two or more conditions to be included in an IF instruction. The ELSE
instruction establishes a final condition for an IF instruction, specifying that if all preceding
conditions are false, the following information should be included. It must be the last item
of the IF instruction.

INCREMENT NUM_VAR;
DECREMENT NUM_VAR

The INCREMENT and DECREMENT instructions cause HotDocs to increase or

decrease a number variable, usually a counter, by the value of 1.

INSERT "FILENAME"

This instruction inserts a clause, a clause library, or a template into the document
currently being assembled. When HotDocs encounters an INSERT instruction, it
immediately processes the instruction and inserts the template, clause, or clause library
into the current document. If there are variables to be answered, HotDocs presents them
before finishing the interview of the main document.

LANGUAGE CODE

This instruction tells HotDocs to format numbers and dates in a particular language.

LIMIT NUM

The LIMIT instruction limits the number of times a dialog can be repeated. It is placed in
the script of the dialog that must be limited to a specific number of repetitions.

OMIT VAR

The OMIT VAR instruction, which you use in a dialog script, keeps variables from
appearing in the Edit Answer Source dialog box of an answer source.

PLAY "MACRO"

The PLAY "MACRO" instruction plays a word processor macro after the document is
assembled and either sent to the word processor, printed, or saved.

QUIT

The QUIT instruction allows you to close the variable without losing the work you have
done. Normally, HotDocs will not save an invalid computation. The only way to exit an
invalid computation is to click Cancel, which erases the script. The instruction is usually
placed at the beginning of an unfinished or invalid computation.

REPEAT DIALOG; END

REPEAT

A REPEAT instruction gathers lists of answers and merges them into a document.

REQUIRE ALL; REQUIRE

VAR

The REQUIRE instruction requires users to answer questions in a dialog before they can
advance to the next dialog in the interview.

SET VAR TO VALUE

This instruction lets you specify a given value for a variables answer automatically, rather
than allow the user to specify an answer. With the SET instruction, you can transfer
names and other values from one variable to another.

WHILE EXPRESSION;
END WHILE

The WHILE EXPRESSION instruction allows you to repeatedly process (or loop through)
an answer or set of answers until a certain condition is met, such as a certain answer is
found or a limit is reached.

Copyright 2010 HotDocs Ltd. All rights reserved

408

Help Topics for HotDocs Developer 10

ADD TEXT TO MULT_CHOICE_VAR; CLEAR MULT_CHOICE_VAR

Placeholder

Replace With

TEXT

A text value, such as a Text variable or an actual word or name

MULT_CHOICE

Any Multiple Choice variable in the template

These instructions allow you to modify options of a Multiple Choice variable. The CLEAR instruction removes all the
current options, and the ADD instruction adds options to the variable.
Using these two models, you can create an entire Multiple Choice variable using answers the user provides.
For example, a template requires the user to first enter a list of all the committee member names. Later, the user can
identify which committee member is the chairperson. You can allow the user to identify the chairperson by presenting a
Multiple Choice variable that has the names of all committee members as options. The following script would create that
Multiple Choice variable:
CLEAR Committee Chairperson
REPEAT Committee Members List
ADD Member Name TO Committee Chairperson
END REPEAT
In this example, the CLEAR instruction first removes any existing options from the Multiple Choice variable Committee
Chairperson. Then, the script repeats the Committee Members List dialog, gathering the names of each committee
member. The ADD instruction then adds each members name to the Multiple Choice variable. After the committee
members have all been entered, you can present the Committee Chairperson variable for the user to identify the
chairperson.
Additionally, if the Multiple Choice variable you are clearing uses any option prompts, these prompts will also be cleared.
When adding new options to the Multiple Choice variable, you can also add new prompts. To do this, use a vertical bar to
separate the option from the prompt in the ADD instruction. For example:
CLEAR Marital Status
ADD "Single|Client is single" TO Marital Status
ADD "Married|Client is married" TO Marital Status
ADD "Divorced|Client is divorced" TO Marital Status
In this example, the Multiple Choice variable Marital Status is cleared. The script then adds a literal text value (denoted by
quotation marks) for the new option. The option is immediately followed by a vertical bar, which tells HotDocs to use the
text following the bar as a prompt for the option.
Both the CLEAR and ADD instructions must be used in a computation script, which must be processed before the Multiple
Choice variable is asked. To add options to a Multiple Choice variable, you should create the variable beforehand and
assign a temporary option. Then, as the user provides the answers you want to include as options, the CLEAR instruction
removes the temporary option, and the ADD instruction places the users answers as options in the variable.
Caution:
Unlike options and prompts, the merge text for a Multiple Choice variable comes from another componenta Merge
Text component. This means you cannot create and add merge text to a Multiple Choice variable "on the fly."

Copyright 2010 HotDocs Ltd. All rights reserved

409

Help Topics for HotDocs Developer 10

ASCEND VAR; DESCEND VAR

Placeholder

Replace With

VAR

A repeated variable

The ASCEND instruction sorts lists of answers (gathered using a REPEAT instruction) in alphanumeric order, from 1 to 9,
and from A to Z. The DESCEND instruction sorts lists of answers from 9 to 1, and from Z to A.
For example, the following script would insert a list of clients in alphabetical order, from A to Z. Even though it lists Client
First Name first, it sorts by Client Last Name:
""
REPEAT Client Information
ASCEND Client Last Name
RESULT + Client First Name + " " + Client Last Name + "
"
END REPEAT
The first empty set of quotation marks sets the computation value to nothing. Then, the repeated dialog, Client
Information, asks for each clients first and last name. Next, the ASCEND instruction sorts the list of names by last name.
Finally, the RESULT expression tells HotDocs to merge the names in the document.
Note:
The ASCEND and DESCEND instructions can only sort on a single variable; however, you can sort multiple variables
by including multiple ASCEND or DESCEND instructions.

Copyright 2010 HotDocs Ltd. All rights reserved

410

Help Topics for HotDocs Developer 10

ASK DIALOG
Placeholder

Replace With

DIALOG

Any dialog in the template

The ASK DIALOG instruction allows you to control the order in which dialogs appear in an interview. (See Control When
Your Dialogs Appear.)
ASK instructions are also useful when some interview questions should only be asked in certain situations. In the
following example, HotDocs only asks the Buyer Information dialog if the user is a first-time buyer:
IF First Time Buyer
ASK Buyer Information
END IF
In general, the ASK instruction tells HotDocs to display a dialog as soon as the instruction is processed. You can insert
an ASK instruction directly in the template, or use a Computation variable to ask several dialogs at once. In fact, you can
control the entire interview by using a series of ASK and other instructions in a single computation. (See Define a Custom
Interview for details.)

Copyright 2010 HotDocs Ltd. All rights reserved

411

Help Topics for HotDocs Developer 10

ASK VAR
Placeholder

Replace With

VAR

Any variable in the template

Sometimes a variable needs to be asked by itself. You can use the ASK VAR instruction so that during the interview,
HotDocs displays the variable in its own default dialog.
In the following example, an IF expression evaluates if more than a year has passed since the last time the client
assembled this document. If so, the Insurance Company Name variable is asked:
IF MONTHS FROM( Date Of Previous Filing , TODAY ) >= 13
ASK Insurance Company Name
END IF
You can insert the ASK VAR instruction directly in the template or you can use it in a Computation variable. Be aware,
however, that if you insert the instruction directly in the template, you can ask only one variable, and any answers the user
provides will not be merged into the document at that place.

Copyright 2010 HotDocs Ltd. All rights reserved

412

Help Topics for HotDocs Developer 10

ASSEMBLE "FILENAME"
Placeholder

Replace With

FILENAME

The name of another HotDocs template

Note:
Complete instructions on using the ASSEMBLE instruction can be found in the topic, Start a New Assembly From a
Template.
You can use the ASSEMBLE instruction to add templates to the assembly queue. Unlike the INSERT instruction, an
ASSEMBLE instruction waits until the current document is assembled before starting the next assembly session.
For example, you may or may not need to include a cover letter with the document you are assembling. If you do, the
following script adds the template, Cover Letter, to the assembly queue.
IF Cover Letter Required
ASSEMBLE "Cover Letter.rtf"
END IF
In this script, if the user opts to assemble a cover letter, then the ASSEMBLE instruction is processed and HotDocs
assembles the cover letter template after the main document is assembled.

Understand How Templates Are Added to the Assembly Queue

To achieve the best results when using the ASSEMBLE instruction, you should understand how HotDocs adds the
templates it finds in ASSEMBLE instructions to the assembly queueparticularly if your template uses a custom
interview. There are two different scripts that HotDocs processes during an assembly:
The template script is the body of the template where HotDocs merges the answers to produce the assembled
document.
The interview script is the set of instructions that determine what dialogs to include in the interview. If your template
uses a custom interview, this is your custom interview computation (e.g., INTERVIEW). Otherwise, the interview
script is the same as the template script for a default interview.
Each time HotDocs processes one of these scripts, it first removes from the Assembly Queue any templates that were
added by ASSEMBLE instructions in the current template. Then, as HotDocs encounters each ASSEMBLE instruction, it
adds that template to the assembly queue. Thus, if you have an ASSEMBLE instruction in your custom interview script,
the template in that instruction will be added to the assembly queue whenever HotDocs processes your interview script.
This behavior can cause a problem if the ASSEMBLE instructions in your interview script do not match the instructions in
the template script. For example, if HotDocs adds templates to the assembly queue while processing the interview script,
those templates could be removed when HotDocs subsequently processes the template script. Likewise, if your template
script adds templates to the assembly queue, they could be removed when the interview script is processed.
To ensure that templates are added to, and remain in, the assembly queue, you should include identical ASSEMBLE
instructions in both your interview and template scripts. This way, no matter which script HotDocs processes last, it will put
the desired templates in the assembly queue. (As noted above, both scripts are identical if you use a default interview, so
this information is only important when you use a custom interview in your template.)
Note:
You can add command-line options to an ASSEMBLE instruction (for example, ASSEMBLE "subpoena.rtf /pr").
If the command-line option includes a file path and name, enclose the path and name in double quotation marks (for
example, ASSEMBLE "subpoena.rtf /sa /af=""L Chang.anx"""). (Four command line options were designed
specifically for use with ASSEMBLE instructions. They are: Suggest Save, Suggest Save New, Save Answers, and
Save Answers Prompt. They control the saving of answers after each ASSEMBLE instruction is processed.)

Copyright 2010 HotDocs Ltd. All rights reserved

413

Help Topics for HotDocs Developer 10

CONCEAL VAR
Placeholder

Replace With

VAR

A variable used in an answer source

This instruction, which you use in a dialog script, keeps variables from appearing in the Select From Answer Source
dialog box of an answer source.
Answer sources are associated with specific dialogs in a template. When users view the dialog during the interview, they
can click a special button, which displays a list of answers that were entered during previous interview sessions. They can
either select an existing set of answers or add a new set to the list.
After creating an answer source for one dialog, you can use it with other dialogs, including dialogs in other templates.
However, when using an answer source with multiple dialogs, each variable must be represented in both the answer
source and in each dialog. If a variable that is referenced in the answer source isnt included in the dialog (or vice-versa),
answers in the answer source will get mixed together whenever you add, edit, or delete records.
In some situations though, it isnt always practical or relevant to show the user every variableeither in the dialog or in
the answer source. To accommodate this, you can use the HIDE, CONCEAL, and OMIT instructions to manipulate these
variables in both the dialog and the answer source. Specifically, HIDE keeps a variable from appearing on the dialog,
while CONCEAL keeps it from appearing in the answer source. OMIT keeps it from being associated with the answer
source at all. Often, you must use a combination of these instructions to achieve your desired result.
For example, in one template, the user must enter both a Creditor Name and a Creditor Address. However, in a second
template that uses the same dialog and answer source, Creditor Address isn't needed. You can keep it from appearing in
the Select From Answer Source dialog box for this template by using the following script:
CONCEAL Creditor Address
Answers for Creditor Address are still saved in the answer source, even though they do not appear when the user opens
the Select From Answer Source dialog box. (You would most likely include the instruction HIDE Creditor Address in this
script as well, which would keep Creditor Address from appearing on the actual interview dialog. To keep the variable
from appearing when the user edits a record in the answer source, see OMIT VAR.)
See Suggest an Answer Source for Dialogs for more information.

Copyright 2010 HotDocs Ltd. All rights reserved

414

Help Topics for HotDocs Developer 10

DEBUG
This instruction steps through the template or script field by field or line by line. It helps you determine why the template
you are automating (or the script you are writing) is producing results you don't expect.
For full information on how to use this instruction, please see the following topics:
Overview: Debugging Templates
Insert Debugging Instructions in Templates and Scripts
Step Through a Template or Script

Copyright 2010 HotDocs Ltd. All rights reserved

415

Help Topics for HotDocs Developer 10

DEFAULT VAR TO VALUE

Placeholder

Replace With

VAR

Any type of variable in the template

VALUE

A value that corresponds with the variable type

This instruction suggests a value for a variable if the variable is unanswered.

For example, in the following script, the variable Attorney Name is defaulted to the literal value of Sam Jones:
DEFAULT Attorney Name TO "Sam Jones"
In this example, when HotDocs processes this script, it first determines whether Attorney Name has been answered. If it
has, the DEFAULT instruction has no effect and HotDocs uses the answer already given. If Attorney Name has not been
answered, however, HotDocs suggests the answer Sam Jones. When this variable appears during the interview, users
can accept this answer by moving to the next dialog, or they can enter a different answer in the answer field.
You can also use a DEFAULT instruction to suggest an answer that has already been given in the interview. For example:
DEFAULT Trustee Name TO Client Name
In this example, when HotDocs processes this script, it first determines whether Trustee Name has been answered. If it
has, the DEFAULT instruction has no effect and HotDocs uses the answer already given. If Trustee Name has not been
answered, HotDocs then checks to see what answer has been given for Client Name and suggests that as the answer. It
is important to note, however, that if Client Name is unanswered, Trustee Name will likewise be unanswered.
Caution:
Do not use the DEFAULT instruction in the script of a repeating dialog unless the instruction is used in conjunction with
a conditional expression or a LIMIT instruction. If you use it by itself in a repeated dialog script, it will always add an
unanswered dialog to the interview, which will produce an incorrectly assembled document.
Note:
The DEFAULT and SET instructions both assign answers to variables. Click here for an explanation of the
differences between the two.
To default two or more options for a Multiple Choice variable, separate each option with a vertical bar (for
example, DEFAULT MC Variable TO "Option1|Option2|Option3").

Copyright 2010 HotDocs Ltd. All rights reserved

416

Help Topics for HotDocs Developer 10

ERASE VAR; ERASE DIALOG

Placeholder

Replace With

VAR

The name of a variable in a dialog you want to clear

DIALOG

The name of the dialog whose contents you want to clear

The ERASE instructions let you clear answers in a dialog. Specifically, ERASE VAR clears answers for a specified
variable in a dialog, while ERASE DIALOG clears all answers in the dialog. This may be useful when you are using a
temporary dialog to store lists of answers from two or more dialogs.
For example, say you have two repeated dialogsone containing plaintiff names and another containing defendant
names. If you need to generate a single list of all parties in the case, you can combine the two lists into a single repeated
dialog. To do this, you would want to erase any existing values from the combined list before populating it with the names
from the plaintiff and defendant dialogs.
Using the ERASE instruction in the script keeps the combined list up to date each time the computation script is
processed. For example, if the user adds or removes names in the plaintiff or defendant dialogs during the interview, the
ERASE instruction will make sure they are properly added or removed when the combined list is regenerated.
The following script demonstrates how to accomplish this:
ERASE Combined List
SET Counter TO 0
REPEAT Plaintiff Information
INCREMENT Counter
SET Combined Name[Counter] TO Plaintiff Name
END REPEAT
REPEAT Defendant Information
INCREMENT Counter
SET Combined Name[Counter] TO Defendant Name
END REPEAT

Copyright 2010 HotDocs Ltd. All rights reserved

417

Help Topics for HotDocs Developer 10

FILTER COMPUTATION_VAR
Placeholder

Replace With

COMPUTATION_VAR

Any Computation variable in the template that results in a true or false value

The FILTER instruction filters out certain entries from a repeated list, based on conditions you specify.
In the following example, the script filters out all corporate entities from a list of vendors:
""
REPEAT Vendor Information
FORMAT "A, B, and C"
FILTER No Corporate Vendors
RESULT + Vendor Name
END REPEAT
In the preceding script, No Corporate Vendors is a Computation variable with the following script:
Vendor Type != "Corporation"
First, the empty quotation marks set the value of the repeat to "nothing." HotDocs then repeats the Vendor Information DI
dialog. After the user enters all the information, HotDocs processes the responses, filters out all corporate entities, and
displays a modified list in the specified format.
Note:
You can use the AND operator in the computation to filter out entries based on two or more conditions.
A filter can be as complicated as it needs to be, but it must result in either true or false. For example, the
expression YEARS FROM( Child's Birth Date, TODAY ) produces a number (the age of a person), not a
true or false valueit is not a filter. But the expression YEARS FROM( Child's Birth Date, TODAY ) <=
17 can only result in true or false. It can correctly filter all children under the age of 18 from a list.

Copyright 2010 HotDocs Ltd. All rights reserved

418

Help Topics for HotDocs Developer 10

FORMAT "LIST_FORMAT"
Placeholder

Replace With

LIST_FORMAT

An example of the conjunction and punctuation desired, for example, a, b, and c or a; b;

or c.

The FORMAT "LIST_FORMAT" instruction allows you to create a sentence-style list within a computation. (If you create
the REPEAT instruction using a REPEAT field, you can specify the list format by choosing a style from the Format dropdown list. See Punctuate a Sentence-Style List.)
For example, perhaps you want the items in your list to appear with the final comma preceding the and. Your script would
look like this:
""
REPEAT Education Information
FORMAT "A, B, and C"
RESULT + Degree Designation
END REPEAT
RESULT
Once a user has provided the list of educational degrees in Education Information, the FORMAT instruction ensures
that the requisite commas are in place.
Note:
FORMAT instructions should be placed immediately after the REPEAT instructions for repeated dialogs.

Copyright 2010 HotDocs Ltd. All rights reserved

419

Help Topics for HotDocs Developer 10

GRAY ALL; GRAY VAR; UNGRAY ALL; UNGRAY VAR

Placeholder

Replace With

Var

Any variable used in a dialog

These instructions, which are used in a dialog script, control whether components in a dialog appear grayed or ungrayed,
depending on answers a user enters. GRAY ALL dims all components in the dialog, while UNGRAY ALL makes all of the
components active again. Likewise, GRAY VAR dims a single component, and UNGRAY VAR enables the component
again.
For example, say you want certain variables in a dialog to appear based on the user's family situation. How the user
answers the Multiple Choice variable, Family Status, controls which questions are asked:
GRAY ALL
UNGRAY Family Status
IF Family Status = "Married, with children"
UNGRAY ALL
ELSE IF Family Status = "Married, no children"
UNGRAY Spouse Name
ELSE IF Family Status = "Separated, with children"
UNGRAY Number Of Children
END IF
The initial GRAY ALL instruction dims all variables in the dialog, making them inactive. Then the Family Status Multiple
Choice variable is immediately ungrayed so the user can choose an option. Depending on the answer to this Multiple
Choice variable, some or all of the other variables are ungrayed.
Note:
In the script above, you could also gray each variable in the dialog (except the Multiple Choice variable); however,
graying all of the variables and then ungraying the Multiple Choice variable immediately after saves a lot of repetitive
typing.

Copyright 2010 HotDocs Ltd. All rights reserved

420

Help Topics for HotDocs Developer 10

HIDE ALL; HIDE VAR; SHOW ALL; SHOW VAR

Placeholder

Replace With

Var

A variable used in an answer source

These instructions, which are used in a dialog script, control whether the user is able to see variables in a dialog. The
HIDE ALL instruction hides all variables in the dialog, while SHOW ALL reveals the variables again. Likewise, HIDE VAR
hides a single variable, and SHOW VAR reveals the variable.
In the following example, a certain estate planning template may be used for both wills and trusts. The initial dialog uses
a Multiple Choice variable called Document Type to ask which type of document will be assembled. Then, depending on
how the user answers the variable, HotDocs asks either the executor/testator names or the trustee/grantor names:
HIDE ALL
SHOW Document Type
IF Document Type = "Will"
SHOW Executor Name
SHOW Testator Name
ELSE IF Document Type = "Trust"
SHOW Trustee Name
SHOW Grantor Name
END IF
Caution:
You should not HIDE or SHOW a variable in a repeated-as-spreadsheet dialog based on another variable in the same
dialog. When you use HIDE or SHOW in a spreadsheet dialog, the entire column is shown or hidden. Attempting to do
this may produce unexpected results.

Copyright 2010 HotDocs Ltd. All rights reserved

421

Help Topics for HotDocs Developer 10

IF EXPRESSION; ELSE IF; ELSE; END IF

Placeholder

Replace With

EXPRESSION

A statement that can be evaluated as true or false

You can make sections of templates or scripts conditional by using IF instructions. A conditional section will be included
only if a condition you specify is true. The ELSE IF instruction allows two or more conditions to be included in an IF
instruction. The ELSE instruction establishes a final condition for an IF instruction, specifying that if all preceding
conditions are false, the following information should be included. It must be the last item of the IF instruction.
Each IF instruction or expression must end with an END IF instruction. This instruction completes a section of conditional
logic. HotDocs automatically creates an END IF paired with each IF instruction. These pairs can be nested, allowing you
to test several conditions before applying a single effect.
For example, in the following script, HotDocs uses an IF instruction to insert a paragraph about vacation timebut only if
the new employee qualifies for paid vacation:
IF Vacation DaysIn addition, Employee Name shall be allowed Number of Vacation
Days:ten for vacation time. Employee Name shall also receive seven paid holidays,
including New Year's Day, Memorial Day, Fourth of July, Labor Day, Thanksgiving
(including the day after), and Christmas.END IF
More complex situations can also be handled using IF expressions. For example, in the following computation script, a
single paragraph in a template may change depending on how close a project is to completion. Using the IF, ELSE IF,
and ELSE instructions, the correct paragraph can be inserted:
IF Project Status = "Complete"
"Upon finishing the project"
ELSE IF Project Status = "In Process"
"While working on the project"
ELSE
"Before working on the project"
END IF
Note:
You can use IF expressions anywhere. Operators such as AND and OR can link multiple conditions, giving the
user greater control over the interview. However, creating complicated IF instructions directly in the template can
make the assembly process sluggish. Consider using Computation variables or INSERT instructions instead.
Please see Overview: Make Parts of Templates Conditional for further information on using IF instructions and
expressions.

Copyright 2010 HotDocs Ltd. All rights reserved

422

Help Topics for HotDocs Developer 10

INCREMENT NUM_VAR; DECREMENT NUM_VAR

Placeholder

Replace With

NUM_VAR

A Number variable

The INCREMENT and DECREMENT instructions cause HotDocs to increase or decrease a number variable, usually a
counter, by the value of 1.
In the following example, you want to create a list of potential employees. However, you want the list to include only those
applicants with four or more years of schooling. To do this, you would use the WHILE instruction to loop through a list
of applicants. You would then use the INCREMENT instruction to keep track of which repetition you are on so that the
correct information can be merged into a new list.
SET Applicant Count TO 1
SET Prospect Count TO 0
WHILE ANSWERED( Applicant Name[Applicant Count] )
IF Applicant Years of Schooling[Applicant Count] >= 4
INCREMENT Prospect Count
SET Prospect Name[Prospect Count] TO Applicant Name[Applicant Count]
END IF
INCREMENT Applicant Count
END WHILE

Copyright 2010 HotDocs Ltd. All rights reserved

423

Help Topics for HotDocs Developer 10

INSERT "FILENAME"
Placeholder

Replace With

FILENAME

The file name and folder path of another HotDocs template

Note:
Include the folder path if the inserted template resides in a folder that is different from
the main template.

This instruction inserts a clause, a clause library, or a template into the document currently being assembled. When
HotDocs encounters an INSERT instruction, it immediately processes the instruction and inserts the template, clause, or
clause library into the current document. If there are variables to be answered, HotDocs presents them before finishing
the interview of the main document.
To create a simple INSERT instruction, you can click the
INSERT Field button and insert the instruction directly in
the template. However, if you want to insert a more complex instruction using conditional logic, you may need to use a
Computation variable.
Often an organizations documents will include sections that are used frequently, such as company letterhead or attorney
information blocks. Rather than recreate these parts of a document each time you automate a template, you can save
just the letterhead or the information block as its own template and then use an INSERT instruction to include it in the
templates that require it. For example, let's say you have a specific attorney information block you use in pleadings. You
would create a template that contains only the attorney information and then use the INSERT instruction to insert it:
IF Attorney Information Required
INSERT "Attorney Information Block.rtf"
END IF
In text templates, if the inserted template contains unanswered variables, HotDocs asks these variables. After the inserted
template is assembled, HotDocs finishes assembling the main template. In contrast, with form templates, HotDocs
appends the inserted form template to the main form. Once it finishes assembling the main form, it then assembles the
inserted form template.
Note:
For detailed information on inserting templates, see Overview: Insert Templates into Templates.
Templates can be inserted from any location, as long as you specify the correct folder path information. (See
Inserted Template File Locations for examples.)
Inserted files may have formatting that differs from the original template. Headers, footers, and margins can often
be controlled more easily by using word processor section breaks. See Define Headers and Footers in Inserted
Word Templates.

Copyright 2010 HotDocs Ltd. All rights reserved

424

Help Topics for HotDocs Developer 10

LANGUAGE CODE
Placeholder

Replace With

CODE

Any of the following language codes:

ENG (English)
DEU (German)
DES (Swiss German)
DEA (Austrian German)
FRA (French)
NLD (Dutch)
ESN (Spanish)
ITA (Italian)

This instruction tells HotDocs to format numbers and dates in a particular language.
For example, the following script allows the template to use Spanish formats:
LANGUAGE ESN
Start Contract Date:3 Juno 1990
Optionally, if your date or number format requires non-U.S. thousands and decimal separators, you can specify which
separators you want to use in the LANGUAGE instruction. The first character must be the thousands separator and the
second character must be the decimal separator. For example:
LANGUAGE ".," FRA
Note:
For more detailed information on using foreign language templates, see Create a Foreign Language Template.
You must obtain the appropriate foreign language DLL file before the LANGUAGE instruction will work in your
templates. Contact your HotDocs sales representative for more information.

Copyright 2010 HotDocs Ltd. All rights reserved

425

Help Topics for HotDocs Developer 10

LIMIT NUM
Placeholder

Replace With

NUM

A whole number, Number variable, or numeric expression

The LIMIT instruction limits the number of times a dialog can be repeated. It is placed in the script of the dialog that must
be limited to a specific number of repetitions.
When setting repeat limits, assign a number value or numeric expression. For example, the dialog, Daily Schedule
Information, gathers information about the scheduled activities for each day of the work week, so it needs to be limited to
five repetitions. The following would be placed in the dialog's script:
LIMIT 5
Note:
You can let the user change the limit each time a document or form is assembled by replacing the NUM
placeholder with a Number variable. Make sure the Number variable gets answered before the REPEAT
instruction is processed.
To control the number of viewable rows in a spreadsheet (but still allow users to enter as many answers as they
need), enter the number in the Rows to display box. (Make sure Spreadsheet is selected as the Style.)

Copyright 2010 HotDocs Ltd. All rights reserved

426

Help Topics for HotDocs Developer 10

OMIT VAR
Placeholder

Replace With

VAR

A variable used in an answer source

The OMIT VAR instruction, which you use in a dialog script, keeps variables from appearing in the Edit Answer Source
dialog box of an answer source.
Answer sources are associated with specific dialogs in a template. When users view the dialog during the interview, they
can click a special button, which displays a list of answers that were entered during previous interview sessions. They can
either select an existing set of answers or add a new set to the list.
After creating an answer source for one dialog, you can use it with other dialogs, including dialogs in other templates.
When using an answer source with multiple dialogs, each variable must be represented in both the answer source file and
in each dialog. If a variable that is referenced in the answer source file isnt included in the dialog (or vice-versa), answers
in the answer source will get mixed together whenever you add, edit, or delete records.
In some situations though, it isnt always practical or relevant to show the user every variableeither in the dialog or
in the Select From Answer Source dialog box. To accommodate this, you can use the HIDE, CONCEAL, and OMIT
instructions to manipulate these variables in both the dialog and the answer source. Specifically, HIDE keeps a variable
from appearing in the dialog, while CONCEAL keeps it from appearing in the answer source spreadsheet. OMIT keeps
it from appearing in the answer source altogether, but still allows you to use it in the dialog. Often, you must use a
combination of these instructions to achieve your desired result.
For example, say you have a dialog that shows information about a client, including how much a client owes in payments
to the firm. Because information about amounts owed changes, it would not make sense to include it in the answer
source. To keep it from appearing in the answer sourceboth in the Select From Answer Source dialog and in the Edit
Answer Source dialogyou would use the OMIT instruction, like this:
OMIT Amount Owed
The variable would be asked on the dialog, however, so the user could answer it.
See Suggest an Answer Source for Dialogs for more information.

Copyright 2010 HotDocs Ltd. All rights reserved

427

Help Topics for HotDocs Developer 10

PLAY "MACRO"
Placeholder

Replace With

"MACRO"

A word processor macro that performs a certain function in your template

The PLAY "MACRO" instruction plays a word processor macro after the document is assembled and either sent to the
word processor, printed, or saved.
Where you store the macro depends on which word processor you are using:
For WordPerfect users, the macro can be stored anywhere. The PLAY instruction must include the file name of the
macro, and if the macro is stored anywhere other than the default macro folder, the instruction must include a full
path to the file as well.
For Word DOT users, the macro must be stored in the template itself, in Normal.dot, or in any global template that is
automatically loaded when you start Word.
For Word RTF users, the macro must be stored either in Normal.dot, in any global template that is automatically
loaded when you start Word, or in a Word template you associate with the template through Component Manager.
(See Specify a Word Template for Storing Post-Assembly Macros for details.)
Macros can be helpful in many situations, such as making sure the format of an inserted clause matches the rest of the
document. For example, the text in the Authority Clause document may be formatted differently than the text in the main
document. You could create a macro that can adjust the formatting so that its uniform:
INSERT "Authority Clause.rtf"
PLAY "Standard_Format"
To insert a PLAY instruction in a template

1. At the template, position the cursor in the template where you want the PLAY instruction.
2. If you are using Microsoft Word:
a. Click the HotDocs menu in the HotDocs toolbar and choose Other Field from the list of options. The Other
Field dialog box appears.
b. Click the Field type drop-down button and choose PLAY.
c. In the Macro name box, enter the name of the macro you want to run.
d. Click OK. The instruction is inserted in the template.

3. If you are using WordPerfect:

a. Copy an existing variable or instruction field in the template.
b. Replace text between the chevrons ( ) with the PLAY instruction.
See Specify a Word Template for Storing Post-Assembly Macros for more information.
Note:
PLAY instructions are executed when you create an actual document from the assembly. This includes sending
the document to the word processor, saving the document, or printing a copy of the document. If there are multiple
instructions, they are processed in the order they are encountered.

Copyright 2010 HotDocs Ltd. All rights reserved

428

Help Topics for HotDocs Developer 10

QUIT
The QUIT instruction allows you to close the variable without losing the work you have done. Normally, HotDocs will not
save an invalid computation. The only way to exit an invalid computation is to click Cancel, which erases the script. The
instruction is usually placed at the beginning of an unfinished or invalid computation.
For example, perhaps you aren't sure about the specific variable names that need to be included because the variables
have not yet been created. Normally, HotDocs wont allow an unfinished script to be saved. The QUIT instruction, though,
makes this possible:
QUIT
IF Client History = "____"
SET ____ TO "Returning"
ELSE
SET ____ TO "New"
END IF
Another useful place to include a QUIT instruction is at the end of a computation, which allows you to enter "developer
comments" about the computation script. You can also apply a comment block to the section of the script you don't want
processed. To do this, select that section of the script and click the
click the

Comment Block button. (To uncomment the script,

Uncomment Block button.)

Caution:
If you use a QUIT instruction in a script, it will cause all the scripting after the instruction to lose its syntax-aware
formatting. To restore this formatting once you remove the QUIT instruction, click the

Copyright 2010 HotDocs Ltd. All rights reserved

Auto Format button.

429

Help Topics for HotDocs Developer 10

REPEAT DIALOG; END REPEAT

Placeholder

Replace With

DIALOG

A dialog with a repeat style specified

A REPEAT instruction gathers lists of answers and merges them into a document.
For example, the following script gathers a list of editors and inserts them into the assembled document:
REPEAT Editor Information
Editor: Editor First Name Editor Last Name
END REPEAT
Each REPEAT instruction must also include an END REPEAT instruction, which tells HotDocs to stop repeating the
variables within the instruction.
This next computation script actually contains two repeated dialogsone nested in another. It produces a list of editors as
well as the titles and authors he or she is currently working with:
""
REPEAT Editor Information
RESULT + "Editor: " + Editor First Name + " " + Editor Last Name + "
"
REPEAT Book Information
RESULT + "Book Title: " + Book Title + "
" + "Author: " + Author First Name + " " + Author Last Name + "
"
END REPEAT
END REPEAT
You can create up to three levels of sublists by nesting REPEAT instructions. (See Overview: Create Lists Within a List.)
Note:
For more information about creating lists of answers, see Overview: Include Lists in Your Documents.
While editing complicated sequences, you can jump from the END REPEAT instruction to its associated REPEAT
instruction, or vice versa, by placing the cursor within the REPEAT or END REPEAT chevrons, then clicking the
Match Fields button.

Copyright 2010 HotDocs Ltd. All rights reserved

430

Help Topics for HotDocs Developer 10

REQUIRE ALL; REQUIRE VAR

Placeholder

Replace With

VAR

Any variable used in a dialog

The REQUIRE instruction requires users to answer questions in a dialog before they can advance to the next dialog in the
interview.
REQUIRE instructions ensure that important information is not left out of the assembled document. For example, a certain
document requires the user to enter the date when a legal filing was first made. Later in the template, this date is used to
calculate a deadline for subsequent filings. Many users, however, may not take the time to look up the initial filing date,
which creates problems for calculating the deadline. Using the REQUIRE instruction in a dialog script, as shown in this
example script, can help resolve this problem:
REQUIRE Initial Filing Date
When a dialog script contains a REQUIRE instruction, a red mark appears on the dialog icon in the interview outline. The
question in the dialog is also marked. This mark remains until the required variable is answered. If a user tries to move to
another dialog, HotDocs displays an error message, then moves the cursor to the first required answer field in the dialog.
Users cannot advance to the next dialog without first providing the required answers.
Note:
It may be helpful to include text in the dialog that provides users with information about which fields are
mandatory and why. See Add Text to Your Dialogs for details.
You can customize the marks used in the dialog by specifying your options at HotDocs Options. See Customize
the Look of the Dialog Pane.

Copyright 2010 HotDocs Ltd. All rights reserved

431

Help Topics for HotDocs Developer 10

SET VAR TO VALUE

Placeholder

Replace With

VAR

Any variable

VALUE

A value appropriate for the associated variable

Note:
For a more detailed explanation of setting variables to values, see Automatically Assign Answers to a Variable.
This instruction lets you specify a given value for a variables answer automatically, rather than allow the user to specify
an answer. With the SET instruction, you can transfer names and other values from one variable to another.
For example, if the plaintiff is the same as the client, you can use a SET instruction to automatically enter the plaintiffs
name as the clients, saving the user from typing the name a second time:
IF Is Plaintiff Also Client
SET Client Name TO Plaintiff Name
END IF
Caution:
Because HotDocs repeatedly processes SET instructions during the course of an interview, you must not let the
user specify a different answer for a variable whose value is being SET. When HotDocs updates the interview, the
users answer will be replaced with the value from the SET instruction. To suggest an answer for the user and allow
them to change it, use the DEFAULT instruction. (See Differences Between SET and DEFAULT Instructions for an
explanation.)
Note:
If you are grouping two or more child (inserted) dialogs in a parent dialog, you can SET the child dialog's status
to TRUE. This forces the contents of the child dialog to automatically appear in the interview outline. (See Group
Child Dialogs in a Parent Dialog for details.)
To set two or more options for a Multiple Choice variable, separate each option with a vertical bar (for example,
SET MC Variable TO "Option1|Option2|Option3")

Copyright 2010 HotDocs Ltd. All rights reserved

432

Help Topics for HotDocs Developer 10

WHILE EXPRESSION; END WHILE

Placeholder

Replace With

EXPRESSION

An expression that results in true or false

Note:
A True/False expression can be as complicated as it needs to be, but it must result
in either true or false. For example, the expression YEARS FROM( Childs Birth
Date, TODAY ) produces a number (the age of a person), not a true or false valueit
is not a True/False expression. But the expression YEARS FROM( Childs Birth
Date, TODAY )> 17 can only result in true or false. It is a True/False expression.

The WHILE EXPRESSION instruction allows you to repeatedly process (or loop through) an answer or set of answers
until a certain condition is met, such as a certain answer is found or a limit is reached.
Before using the WHILE instruction, you should understand the following:
The WHILE instruction must be used in a computation or dialog scriptit cannot be inserted directly into a template.
When using the WHILE instruction inside of a REPEAT instruction, the WHILE instruction will not affect the
underlying COUNTER variable associated with the REPEAT instruction. If you need to count something within a
WHILE loop, you must create your own temporary counter. Additionally, to access repeated variables in a WHILE
loop, you must use explicit indexing.
Unless the instructions inside the WHILE loop include an instruction that increments the temporary counter, the
WHILE instruction will repeat until the Maximum WHILE iterations limit is reached. You can specify this property at
the Component File Properties dialog box. (See Change Component File Properties.) To avoid problems like this,
make sure you increment the temporary counter.
In the following example, you want to create a list of signers in a will. Since the signers may include both beneficiaries and
fiduciaries, you want to merge both lists into one. Because some fiduciaries may also be beneficiaries, you will want to
remove any duplicate names. To loop through the list of fiduciaries, you will use the WHILE instruction:
SET Signer Count TO 0
REPEAT Beneficiary Information
INCREMENT Signer Count
SET Signer Name[Signer Count] TO Beneficiary Name
END REPEAT
REPEAT Fiduciary Information
SET Lookup TO 1
WHILE Lookup <= Signer Count AND Fiduciary Name != Signer Name[Lookup]
INCREMENT Lookup
END WHILE
IF Lookup > Signer Count
INCREMENT Signer Count
SET Signer Name[Signer Count] TO Fiduciary Name
END IF
END REPEAT
In the first part of this script, the Beneficiary Information dialog is repeated, and as answers are entered, their values are
set to be used for Signer Name (which is the variable that will be repeated to insert all the names of the signers). Then,
in the second part of the script, as the Fiduciary Information dialog is repeated, HotDocs uses the WHILE expression
to test whether the name of the fiduciary is the same as any of the beneficiary names. If it is not, it will likewise be
added to the Signer Information dialog. (When you insert the REPEAT instruction for the Signer Information dialog in
the template, clear the Ask Automatically option at the Dialog Editor (Options tab). See Control Whether Dialogs are
Asked Automatically for details.)

Copyright 2010 HotDocs Ltd. All rights reserved

433

Help Topics for HotDocs Developer 10

In the next example, you need to remove unwanted space characters from a user's account number. Here, the WHILE
instruction is used to repeat an answer, character by character, so that HotDocs can check to see if there are space
characters in the answer. If there are, HotDocs removes them and rewrites the answer.
SET Count Index TO 1
WHILE Count Index <= LENGTH( Account Number )
IF MID(Account Number, Count Index, 1 ) = " "
SET Account Number TO FIRST( Account Number, Count Index -1 ) + LAST( Account
Number, LENGTH(Account Number) - Count Index)
ELSE
INCREMENT Count Index
END IF
END WHILE
This script uses a temporary counter (Count Index) to keep track of which character in the answer HotDocs is looking
at. Any time the answer is repeated and HotDocs finds a space character, it removes it by concatenating the characters
before and after the space character. HotDocs then makes sure that the new character it is now examining isn't a space
character either. If it is not, HotDocs increments the temporary counter, moves to the next character, and repeats this
process.

Copyright 2010 HotDocs Ltd. All rights reserved

434

Help Topics for HotDocs Developer 10

Chapter 31: Using Expression Models

Overview: Instruction and Expression Models
As you use HotDocs, you may need to tell HotDocs to perform a particular task, such as insert one template into another,
hide variables in dialogs, or perform some action based on an answer the user provides. Similarly, you may need to add
up several dollar amounts, or find the number of years between two given dates. Or, you may need to search a users
answer for a certain block of text.
To accomplish this, you must use the HotDocs scripting language, which consists of instructions, expressions, operators,
and valuessuch as text, numbers, dates, or answers users enter. To help you learn this language, HotDocs provides
you with instruction and expression models.
Specifically, an instruction model tells HotDocs to perform some sort of function, while an expression model retrieves
a special value. Most instructions and expressions also include placeholders, which you must replace with a value.
Possible values include text strings, number amounts, other models, or HotDocs variables. A model will not work until all
its placeholders are replaced.
In addition to using instructions and expressions, you can use operators to control how the script is processed. Most
operators are common mathematical signs, but there are also Boolean operators such as AND and OR. The operator
AND means the statement to the left and the statement to the right must both be true. The operator OR means either the
statement to the left or the statement to the right must be true. The operator ( ) means to perform the operation between
the parentheses first. (See Use Operators When Scripting.)

Copyright 2010 HotDocs Ltd. All rights reserved

435

Help Topics for HotDocs Developer 10

Use Operators When Scripting

An operator is a symbol or word that causes an operation such as addition or a comparison to be performed in a
computation or expression. Operators are available at the Operators list wherever you can create a script or expression.
Most operators can be used when working with both number and text values.
There are three types of operators:
Comparison operators: These compare two values of the same type (text, number, date, multiple choice, or true/
false). They return values of true or false depending on whether the comparison is true or not.
Arithmetic operators: These calculate new values. Operands used in the script must be the same type.
Logical operators: These return a true/false value based on a logical comparison of their operands, both of which
must be true or false values.
The following tables explain how each operator works:
Comparison Operator

Description

The two items in the comparison are of equal value. For example:
Birth Date = 17 Dec 1989
Employee Name = "Louisa Gehrig"

!=

The two items in the comparison are not of equal value. For example:
IF Exhibit A != TRUE
IF Plaintiff Gender != "Male"

<

The first item in the comparison has a lesser value than the second item. For example:
Account Balance < 9000
COUNTER < 10

>

The first item in the comparison has a greater value than the second item. For example:
Dependent Age > 18

<=

The first item in the comparison is less than or equal to the second item. For example:
Client Age <= 65
COUNTER <= 2

>=

The first item in the comparison is greater than or equal to the second item. For example:
Taxed Income >= 75000

CONTAINS

The value of the first item is found in the value of the second item. For example:
"massachusetts virginia kentucky pennsylvania" CONTAINS State
Name

Arithmetic Operator

Description

Add the different components of the script together. For example:

Value 1 + Value 2
Street Address + ", " + City + ", " + State

Subtract the different components of the script from each other. For example:
Monthly Income - Amount of Owed Child Support

Multiply the different components of the script. For example:

Copyright 2010 HotDocs Ltd. All rights reserved

436

Help Topics for HotDocs Developer 10

Purchase Price * 0.625

/

Divide the different components of the script. For example:

Yearly Salary / 12

The unary minus operator results in the numeric negation of the operand (which must be
a Number value). For example:
SET Loss Amount TO - Aggregate Amount

The unary percent operator results in the operand (which must be a Number value)
divided by 100. It is a postfix operator. For example:
Purchase Price + (Purchase Price * 6.25%)

Logical Operator

Description

AND

The statement to the left and the statement to the right must both be true. For example:
IF Client is Married AND Client has Children

OR

The statement to the left or the statement to the right must be true. For example:
IF Single OR Widowed

NOT

The NOT operator results in the logical negation of the operand (which must be a True/
False value). For example:
IF NOT Client is Married

Note:
HotDocs also supports two other unary operatorsunary plus (+) and the dollar sign ($). While both produce
numeric results in a script, the results are exactly the same as the operands. Therefore, they should not be used
in a script.
The Add ( + ) operator can also be used to string together (concatenate) two text values.
The final operator, the parentheses ( ), instructs HotDocs to perform the operation inside the parentheses first.
HotDocs operators are processed in the following order of precedence, from highest to lowest. Operators listed on the
same line have the same precedence.
()
NOT - %
* /
+ = != < > <= >=
AND
OR
So in other words, when HotDocs is evaluating an expression, first parenthesis are used to determine order of operations,
then unary operators, then multiplication and division, then plus and minus, then comparisons, then logical AND, and last
logical OR.

Copyright 2010 HotDocs Ltd. All rights reserved

437

Help Topics for HotDocs Developer 10

Use Line Breaks, Paragraph Ends, and Tabs in Computation Scripts

Caution:
Inserting line breaks and paragraph ends are only relevant if you are merging text into an assembled Word document.
In WordPerfect, each of the commands listed below inserts a hard return. (See the WordPerfect helps for an
explanation.)
When including literal text strings in computation scripts, you can have HotDocs merge line breaks, paragraph ends,
and tabs in the answer. To do this, at the Script box, either manually enter the characters, or use a dot code. Use the
following information:
To insert

Do one of the following

A line break

Press Enter or Shift+Enter. When you do this, HotDocs creates a new line of text in the
same paragraph.
Note:
When you use a line break to span a literal text string across two lines in the script
editor, the color coding assigned to the text string changes to the default color. This
doesn't affect how the computation will be processed, but it may make it more difficult
to visually recognize the different portions of your script. To fix the color coding, click
the

Auto Format button.

Insert a Line Break dot code (.lb) at the place you want HotDocs to start a new line.
(See Insert Characters in Text Strings.)
A paragraph end

Press Ctrl+Enter. When you do this, HotDocs inserts a paragraph mark ( ) and starts a
new paragraph of text.
Insert a Paragraph Mark dot code (.pm) at the place you want HotDocs to start a new
paragraph. (See Insert Characters in Text Strings.)

A tab character

Press Ctrl+T.
If you want the Tab key to insert a tab character (instead of you pressing Ctrl+T), click
the
Options button and select Tab key inserts a tab in scripts. Now, whenever you
press Tab or Shift+Tab, HotDocs will insert a tab in the script instead of taking you to
another field in the dialog box.
Insert a Tab Character dot code (.tc) at the place you want the text to be tabbed. (See
Insert Characters in Text Strings.)

When creating multi-line Text variables, you can force HotDocs to merge a paragraph mark (rather than a line break)
when the user presses Enter. For details, see Customize a Text Variable.

Copyright 2010 HotDocs Ltd. All rights reserved

438

Help Topics for HotDocs Developer 10

Use the Script Editor

When writing a computation script, there are several tools you can use to make the process easier.
To use the script editor

1. Edit the script or expression.

2. At the Script or Expression box, complete any of the following tasks:
To

Do This

Have HotDocs
automatically complete
keywords, component
names, and Multiple
Choice options as you type

Place your cursor in the Script box and press Ctrl+Spacebar. HotDocs displays
a list of instruction and expression keywords, constant values (such as month
abbreviations), and components. Type a portion of the keyword, component name, or
Multiple Choice option for which you are searching. As you type, HotDocs filters the
list to show only those keywords that contain the text you have typed. Once selected,
press Enter to merge it into your script.
To keep seldom-used keywords out of the auto-complete list, click the
Options
button and clear Include seldom-used keywords in auto-complete list.

Access just a list of

components

Press the F5 key, select the component, and press Enter.

Access just a list of

keywords

Press Shift+F5, select the keyword, and press Enter.

Display a syntactical hint

Place your cursor inside the keyword and press the F7 key. HotDocs displays a small
of how an instruction or
ToolTip that shows the entire model as well as the type of value it produces, if it's an
expression should be used expression.
Indent matching pairs of IF
and REPEAT instructions
based on the level of their
insertion

Click the

Auto Format button.

Undo (or cancel) an action

you just performed

Click the

Undo button. HotDocs reverses the change you made.

Redo (or re-implement) an

action you just performed

Click the

Redo button. HotDocs reapplies the change you made.

Cut or copy and paste a

selected portion of the
script

Select the portion of the script you want to cut or copy, and then click the
button or the

Copy button. The script is copied to the Clipboard. To paste the

script in a new location, insert your cursor at that location and click the
button.
Find a specific string of
text in the script

Click the

Cut
Paste

Find button and enter your search text in the Find what box. To find the

next instance of the text, click the

Find Next button.

Note:
To find only those instances of text that are complete words, select Find whole
words only. To find only those instances that have the same capitalization as the
text for which you are searching, select Match case.
Find a specific string
of text in the script and

Click the
Find and Replace button. Enter the search text for which you are
searching in the Find what box, and then enter the replacement text in the Replace

Copyright 2010 HotDocs Ltd. All rights reserved

439

Help Topics for HotDocs Developer 10

To

Do This

replace it with another

string of text

with box. Once you have entered the required text, click Replace, Replace All, or
Find Next.
To find and replace script text in a specific block of script, select the block of script
first and then click the
Find and Replace button. At the Find and Replace dialog
box, select Replace only in selected text.

Move your cursor to a

specific location in the
script

Click the
Go To button. This displays the Go To dialog box, where you can enter
the line number or character position of where you want your cursor to move.

Indent or outdent a block

of the script

Select the portion of the script you want to indent or outdent and click the
button or the
indent.)

Indent

Outdent button. (Click repeatedly to increase or decrease the

Cause HotDocs to ignore a Highlight the block of the script you want to comment and click the
Comment
section of the script when
Block button. This puts two forward slashes in front of each line of the script, which
it processes it, or insert a
instructs HotDocs to ignore this section. To uncomment it, highlight the text and click
comment in the script
the
Uncomment Block button.
Match an IF or REPEAT
instruction with its END
IF or END REPEAT
instruction (or vice versa)

Place your cursor inside the instruction, right-click, and select Match IF/REPEAT
from the shortcut menu. (You can also press Ctrl+M.)

Highlight an entire IF
or REPEAT instruction
block (meaning everything
between a beginning
and ending IF/REPEAT
instruction)

Place your cursor inside the instruction, right-click, and select Select IF/REPEAT
from the shortcut menu. (You can also press Ctrl+Shift+M.)

View helpful information

while using the script
editor, including accessing
help topics for the
different instructions and
expressions you can use
in your script

Click the

Customize the way the

script editor works

Click the
Options.)

Insert line breaks and tab

characters in a script

See Use Line Breaks, Paragraph Ends, and Tabs in Computation Scripts.

Assign formatting
characteristics to literal
text strings in a script

Insert the corresponding dot code. See one of the following topics for details:

HotDocs Help button.

Options button and make your changes. (See Change Script Editing

Change Font Properties of Text

Insert Characters in Text Strings
Add Punctuation and Capitalization to Sentences

Note:
To access the script editor toolbar using the keyboard, press F10.
To access help for each instruction or expression, first select the model in one of the lists and then press Ctrl+F1.
Copyright 2010 HotDocs Ltd. All rights reserved

440

Help Topics for HotDocs Developer 10

For an explanation of the HotDocs scripting language, see Understand the HotDocs Scripting Language. For
details on creating a Computation variable, see Customize a Computation Variable. For a list of instruction and
expression models, see Overview: Instruction and Expression Models.

Copyright 2010 HotDocs Ltd. All rights reserved

441

Help Topics for HotDocs Developer 10

Full List of Expression Models

Expression

Description

Enter a Date

You can use this expression to format your dates correctly as you write computations.

Enter a Number

You can use the Enter a Number expression to format numbers correctly as you write
computations. Numbers in computations and expressions must be in numeric form and
cannot contain commas. If you enter a number that contains a comma, it will be removed
from the value. Decimals must have one digit to the left of the decimal point, even if it is
only a zero.

Enter some Text

You can use the Enter some Text expression to format a text string correctly as you
write computations. When used in computations and expressions, text strings must be
inside quotation marks. This expression adds those quotation marks to the text string.

Enter True or False

You can use this expression to enter a TRUE or FALSE value in a computation or
expression script. True/False values must use uppercase letters.

ABSOLUTE VALUE( NUM )

Using the ABSOLUTE VALUE expression, you can find the absolute value of a given
number. You can calculate a negative number, but have it appear as a positive number.

AGE( DATE )

The AGE( DATE ) expression produces an age, in years, by calculating the number of
years between the current date (as determined by your computers system clock) and a
date you provide in the computation script.

ANSWERED( DIALOG )

HotDocs can determine whether a dialog has been answered using the ANSWERED
expression. Even if only one variable in the dialog is answered, the expression returns a
value of true.

ANSWERED( VAR )

You can use the ANSWERED expression to determine whether a HotDocs variable has
been assigned a value. If so, the expression receives the value of true.

COUNT( DIALOG )

You can find out how many sets of answers a user provides for a repeated dialog. A
repeated dialog is any dialog used in a REPEAT instruction. This expression produces a
number, based on each answered dialog.

COUNT( MULT_CHOICE_VARThis
) expression counts how many options a user chooses when answering a Multiple
Choice variable. The result it produces is a number.
COUNTER

You can use the COUNTER expression to keep track of the current number of repetitions
of a repeated dialog. Each time a user clicks the Next button at a repeated dialog and
provides additional information, the value of COUNTER increases.

DATE - NUM DAYS

You can subtract any number of days from a Date variable. The result of this computation
is a new date value, which can be merged into the assembled document.

DATE - NUM MONTHS

You can subtract a certain number of months from a Date variable. The result of this
computation is a new date value, which can be merged into the assembled document.

DATE - NUM YEARS

You can subtract a certain number of years from a Date variable. The result of this
computation is a new date value, which can be merged into the assembled document.

Copyright 2010 HotDocs Ltd. All rights reserved

442

Help Topics for HotDocs Developer 10

DATE + NUM DAYS

You can add any number of days to a Date variable. The result of this computation is a
new date value, which can be merged into the assembled document.

DATE + NUM MONTHS

You can add any number of months to a Date variable. The result of this computation is a
new date value, which can be merged into the assembled document.

DATE + NUM YEARS

You can add a certain number of years to a Date variable. The result of this computation
is a new date value, which can be merged into the assembled document.

DATE OF( NUM, NUM,

NUM )

This expression finds a date value based on day, month, and year values.

DAY OF( DATE )

This expression returns the day portion (1 to 31) of a given date.

DAY OF WEEK( DATE )

This expression determines on which day of the week a specific date falls and converts
that value to an integer.

DAYS FROM( DATE,

DATE )

This expression allows you to find the number of days between two dates.

FIRST( TEXT, NUM )

Using this expression, you can return any number of characters starting with the first
character in an answer value.

FORMAT( VALUE,
"EXAMPLE" )

Sometimes you may need to add a date, number, or true/false value to a text value. You
can do this by formatting the date, number, or true/false value as text.

INTEGER( TEXT )

Sometimes you may have a text value that contains number characters, as in the case
of a time of day value. The INTEGER expression allows you to convert those number
characters into numeric values so you can perform calculations or compare them with
other values.

LAST( TEXT, NUM )

The LAST expression finds and returns a certain number of characters from the end of a
text string.

LENGTH( TEXT )

The LENGTH expression counts the number of charactersincluding spaces and

punctuationin a text value, such as a Text variable.

MAX( NUM, NUM )

The MAX expression compares two number values and returns the greater of the two.

MID( TEXT, NUM, NUM )

Like the FIRST and LAST expressions, this expression extracts a specified number of
characters from within a text string.

MIN( NUM, NUM )

The MIN expression compares two number values and returns the lesser of the two.

MONTH OF( DATE )

This expression returns the month portion of a given date.

MONTHS FROM( DATE,

DATE )

The MONTHS FROM expression calculates the number of months between two given
dates.

MULT_CHOICE=TEXT;
MULT_CHOICE!=TEXT

The MULT_CHOICE = TEXT expression returns true when the user chooses a
Multiple Choice option that is equal to ( = ) a given text value. If it is not equal ( != ),
the expression returns false. The MULT_CHOICE != TEXT expression functions in the
opposite waytesting instead to see if an answer is not equal to ( != ) a given text value.

NOT TRUE_FALSE

You can use the NOT TRUE_FALSE expression to find out if a True/False variable is
false.

Copyright 2010 HotDocs Ltd. All rights reserved

443

Help Topics for HotDocs Developer 10

OTHER( MULT_CHOICE_VARThis
) expression determines whether the user has chosen the Other option of a Multiple
Choice variable and, if so, returns the text entered in the Other field. It can also be used
to test whether the user has selected the None of the Above option.
POSITION( TEXT, TEXT )

The POSITION expression finds the position of a certain character or character string in a
given text value. It is useful if you need to find a character you know will be in an answer
but are not sure where it will appear. It returns a number value, which represents the first
character.

POWER( NUM, NUM )

The POWER expression generates a numeric value, based on a given exponent.

REMAINDER( NUM, NUM )

The REMAINDER expression returns the remainder of a division. If the denominator is a

zero, HotDocs generates a divide by zero error.

REPLACE( TEXT, TEXT,

TEXT, NUM )

This expression lets you search a string of text for a given character string and replace
the results with new text.

RESULT

As you write computations, you often need HotDocs to acknowledge what the result
would be at that point in the script. You can update this answer by using the RESULT
expression.

ROUND( NUM, NUM )

You can round a number value to a specified number of places.

SELECTION( MULT_CHOICE_VAR,
This expression lets you retrieve individual options (answers) selected in a Multiple
NUM )
Choice variable. It returns a text value that corresponds to the defined answer (as
designated by the NUM placeholder).
SPACE( TEXT, TEXT )

This expression tests whether the variable is answered. If it is, it merges the answer,
followed by a space character. If the variable is unanswered, it merges nothing ("").

STRIP( TEXT, TEXT,

TRUE_FALSE,
TRUE_FALSE )

This expression removes a specified character or characters from the beginning or end
of a text answer. By default, HotDocs removes the characters from both the beginning
and the end of the text. If you want to specify just one or the other, you must use the
TRUE_FALSE parameters.

SUM( COMPUTATION_VAR ) Using the SUM( COMPUTATION_VAR ) expression, you can add computation values
that have been repeated.
SUM( NUM_VAR )

Using the SUM expression, you can add repeated number values.

TEXT CONTAINS TEXT

The TEXT CONTAINS TEXT expression determines whether the first text value contains
the same text as the second value. If it does, it returns the value of true.

TODAY

This expression returns the current date, according to your computers system clock.

TRUNCATE( NUM, NUM )

You can truncate a decimal number a specified number of places after a decimal point.

UNANSWERED

This expression removes an assigned value from a variable. It is used most often with the
SET VAR TO VALUE instruction:

UNION( MULT_CHOICE,
MULT_CHOICE )

This expression creates a single list of all unique options (answers) that have been
selected across two or more Multiple Choice variables.

VALUE( VAR,
EXPRESSION )

This expression returns a default value for the variable type if the variable is unanswered.
If the variable is answered, the value is the answer the user specifies.

Copyright 2010 HotDocs Ltd. All rights reserved

444

Help Topics for HotDocs Developer 10

YEAR OF( DATE )

You can use this expression model to find the year portion of a given date.

YEARS FROM( DATE,

DATE )

This expression calculates the number of years between two given dates.

ZERO( NUM_VAR )

This expression returns the value of zero only if a Number variable is unanswered. If the
Number variable is answered, the value is the answer the user specifies.

Copyright 2010 HotDocs Ltd. All rights reserved

445

Help Topics for HotDocs Developer 10

Enter a Date
You can use this expression to format your dates correctly as you write computations.
To use the expression, drag the Enter a Date expression into the Script or Expression box. The Enter a Date dialog
appears where you can type a date into the field, or you can use the pop-up calendar to select a date. When you click OK,
HotDocs inserts the date at the cursor position in the correct format, for example, 3 JUN 1990.

Copyright 2010 HotDocs Ltd. All rights reserved

446

Help Topics for HotDocs Developer 10

Enter a Number
You can use the Enter a Number expression to format numbers correctly as you write computations. Numbers in
computations and expressions must be in numeric form and cannot contain commas. If you enter a number that contains
a comma, it will be removed from the value. Decimals must have one digit to the left of the decimal point, even if it is only
a zero.
To use the expression, drag the Enter a Number expression into the Script or Expression box. The Enter a Number
dialog box appears. Enter a number and click OK. The correctly formatted number is inserted at the cursor position.

Copyright 2010 HotDocs Ltd. All rights reserved

447

Help Topics for HotDocs Developer 10

Enter some Text

You can use the Enter some Text expression to format a text string correctly as you write computations. When used in
computations and expressions, text strings must be inside quotation marks. This expression adds those quotation marks
to the text string.
To use the expression, drag the Enter some Text expression into the Script or Expression box. The Enter some Text
dialog box appears. Enter some text and click OK. HotDocs inserts that textin quotation marksat the cursor position.

Copyright 2010 HotDocs Ltd. All rights reserved

448

Help Topics for HotDocs Developer 10

Enter True or False

You can use this expression to enter a TRUE or FALSE value in a computation or expression script. True/False values
must use uppercase letters.
To use the expression, drag the Enter True or False expression into the Script or Expression box. The Enter True
or False dialog box appears. Click either True or False. The keyword you choose is inserted in all capital letters at the
cursor position.

Copyright 2010 HotDocs Ltd. All rights reserved

449

Help Topics for HotDocs Developer 10

ABSOLUTE VALUE( NUM )

Placeholder

Replace With

NUM

A number value for which you want the absolute value returned. Can be a Number
variable or a fixed number value.

Using the ABSOLUTE VALUE expression, you can find the absolute value of a given number. You can calculate a
negative number, but have it appear as a positive number.
For example, you may need to send a notice to a client about an account balance. Not knowing whether it will be a
positive or negative balance, you would create the computation Absolute Value of Final Balance, which would return a
positive expression, regardless. The computation script is:
ABSOLUTE VALUE( Final Balance )
Once you have created the computation, you can use an IF/ELSE expression to merge the desired text with the correct
value in the document:
IF Final Balance < 0
Your account is $Absolute Value of Final Balance overdrawn.
ELSE
You have $Absolute Value of Final Balance in your account.
END IF

Copyright 2010 HotDocs Ltd. All rights reserved

450

Help Topics for HotDocs Developer 10

AGE( DATE )
Placeholder

Replace With

DATE

A date value, which you want to check against the current date. This can be a Date
variable or a fixed date value.

The AGE( DATE ) expression produces an age, in years, by calculating the number of years between the current date (as
determined by your computers system clock) and a date you provide in the computation script.
For example, the following script determines the age of the user based on his or her birth date:
AGE( Birth Date )
In the following conditional script, HotDocs determines whether the client is under the age of 18. If so, the ParentGuardian Information dialog is asked. If the client is over the age of 18, no dialogs are asked.
IF AGE( Birth Date ) < 18
ASK Parent-Guardian Information
END IF

Copyright 2010 HotDocs Ltd. All rights reserved

451

Help Topics for HotDocs Developer 10

ANSWERED( DIALOG )
Placeholder

Replace With

DIALOG

A dialog name

HotDocs can determine whether a dialog has been answered using the ANSWERED expression. Even if only one
variable in the dialog is answered, the expression returns a value of true.
Let's suppose you have a dialog that gathers information about a decedent (Decedent Information). From within this
dialog, a user could open an inserted dialog that asks questions about the decedent's assets (Decedent's Assets). Later in
the template, you could ask additional questions based on whether these dialogs have been answered:
IF ANSWERED( Decedent Information ) AND ANSWERED( Decedent's Assets )
ASK Asset Distribution Information
END IF

Copyright 2010 HotDocs Ltd. All rights reserved

452

Help Topics for HotDocs Developer 10

ANSWERED( VAR )
Placeholder

Replace With

VAR

A variable

You can use the ANSWERED expression to determine whether a HotDocs variable has been assigned a value. If so, the
expression receives the value of true.
Caution:
If you are testing whether a user has ANSWERED a variable, you must make sure the variable is presented to the user
using a custom dialog. Using the ANSWERED( VAR ) expression alone will not automatically force HotDocs to display
the variable for the user.
For example, you may place a variable for the second line of an address (Client Address 2) in a custom dialog; however,
not all users will provide information for that variable. In the template text, you can surround Client Address 2 with an IF
expression that merges that variable into the documentonly if the user answers it:
Client Name
Client Address 1
IF ANSWERED( Client Address 2 )
Client Address 2
END IF
Client City, Client State Client ZIP
In this script, the ANSWERED expression is used with an IF expression to insert or remove Client Address 2, based on
whether the user has provided that information. (Without it, the default unanswered text, ***Client Address 2***, would be
inserted in the assembled document.)
Note:
Even if a user chooses not to answer a variable that has been tested using the ANSWERED expression, HotDocs will
still warn that it is unanswered. If you don't want a warning to appear, clear Warn when unanswered at the Advanced
tab of the Variable Editor. (Control How HotDocs Processes a Variable.)

Copyright 2010 HotDocs Ltd. All rights reserved

453

Help Topics for HotDocs Developer 10

COUNT( DIALOG )
Placeholder

Replace With

DIALOG

A dialog name

You can find out how many sets of answers a user provides for a repeated dialog. A repeated dialog is any dialog used in
a REPEAT instruction. This expression produces a number, based on each answered dialog.
The following example determines if there is more than one fiduciary. If there is, certain prefixes and plural abbreviations
are added to the fiduciary title so the paragraph is structured correctly.
I appoint REPEAT Fiduciary Information:a, b, and cFiduciary Name:LIKE
THISEND REPEAT as IF COUNT( Fiduciary Information ) > 1Co-Fiduciary
TitlesELSEFiduciary TitleEND IF.
This expression uses the COUNT instruction to determine if Fiduciary Information is answered more than once. If it is,
the Co- prefix is inserted before Fiduciary Title, and the plural s is inserted at the end of the variable. For example, in the
assembled document, the answer may be inserted as Co-Executors or Co-Personal Representatives.
Note:
The difference between COUNT and COUNTER is that COUNT counts the number of repetitions in a list, while
COUNTER gives you the number of the current repetition.

Copyright 2010 HotDocs Ltd. All rights reserved

454

Help Topics for HotDocs Developer 10

COUNTER
You can use the COUNTER expression to keep track of the current number of repetitions of a repeated dialog. Each
time a user clicks the
increases.

Next button at a repeated dialog and provides additional information, the value of COUNTER

For example, a user may want to create a word processor table that contains a numbered list of clients:
REPEAT Client Information
COUNTER. Client Name
END REPEAT
In the example above, Client Information repeats the Client Name variable. Each time a user enters a different client,
COUNTER is incremented and merged into the assembled document. For example:
1.
2.
3.
4.

John TeNgaio
Erica Nees
Lisa Alvey
Jonathan Rainwater

HotDocs also uses COUNTER as a way to compare two incrementing number values. For example, perhaps you want to
list the last child named in a repeated dialog:
""
REPEAT Children Information
ASCEND Child Birth Date
IF COUNTER = COUNT( Children Information )
RESULT + "The youngest child is " + Child Name
END IF
END REPEAT
In this computation script, HotDocs first sets the value of the computation to nothing. It then processes the REPEAT
instruction, sorting the children based on their birth dates. It uses COUNTER to determine when the last answer in the
dialog is given (by comparing it to the COUNT of the dialog), and then merges the name of the youngest child in the list
into the document.
Note:
The difference between COUNT and COUNTER is that COUNT counts the number of repetitions in a list, while
COUNTER gives you the number of the current repetition.

Copyright 2010 HotDocs Ltd. All rights reserved

455

Help Topics for HotDocs Developer 10

COUNT( MULT_CHOICE_VAR )
Placeholder

Replace With

MULT_CHOICE_VAR

A Multiple Choice variable with the Select option set to All That Apply

This expression counts how many options a user chooses when answering a Multiple Choice variable. The result it
produces is a number.
For example, suppose the user wants to generate a list of cities in which an author plans to make appearances. There
might be oneor manydepending on the schedule. HotDocs can merge the correct termcity or citiesinto the
document once it knows how many cities were selected from the Multiple Choice variable:
IF COUNT( Publicity Tour City ) = 1
"city"
ELSE IF COUNT( Publicity Tour City ) > 1
"cities"
END IF

Copyright 2010 HotDocs Ltd. All rights reserved

456

Help Topics for HotDocs Developer 10

DATE - NUM DAYS

Placeholder

Replace With

DATE

A date value, such as a Date variable

NUM

A number value

You can subtract any number of days from a Date variable. The result of this computation is a new date value, which can
be merged into the assembled document.
For example, this computation calculates the date the books need to arrive at the warehouse before they can be shipped:
Shipping Date - 14 DAYS

Copyright 2010 HotDocs Ltd. All rights reserved

457

Help Topics for HotDocs Developer 10

DATE - NUM MONTHS

Placeholder

Replace With

DATE

A date value, such as a Date variable

NUM

A number value

You can subtract a certain number of months from a Date variable. The result of this computation is a new date value,
which can be merged into the assembled document.
In the following example, HotDocs subtracts four months from the Shipping Date and inserts the new date:
Shipping Date - 4 MONTHS

Copyright 2010 HotDocs Ltd. All rights reserved

458

Help Topics for HotDocs Developer 10

DATE - NUM YEARS

Placeholder

Replace With

DATE

A date value, such as a Date variable

NUM

A number value

You can subtract a certain number of years from a Date variable. The result of this computation is a new date value,
which can be merged into the assembled document.
For example, this computation subtracts two years from Marriage Date:
Marriage Date - 2 YEARS

Copyright 2010 HotDocs Ltd. All rights reserved

459

Help Topics for HotDocs Developer 10

DATE + NUM DAYS

Placeholder

Replace With

DATE

A date value, such as a Date variable

NUM

A number value

You can add any number of days to a Date variable. The result of this computation is a new date value, which can be
merged into the assembled document.
For example, this computation script adds 90 days to the Date variable, Purchase Date:
Purchase Date + 90 DAYS

Copyright 2010 HotDocs Ltd. All rights reserved

460

Help Topics for HotDocs Developer 10

DATE + NUM MONTHS

Placeholder

Replace With

DATE

A date value, such as a Date variable

NUM

A number value

You can add any number of months to a Date variable. The result of this computation is a new date value, which can be
merged into the assembled document.
For example, this computation determines what the date will be six months from the date the document is assembled:
TODAY + 6 MONTHS

Copyright 2010 HotDocs Ltd. All rights reserved

461

Help Topics for HotDocs Developer 10

DATE + NUM YEARS

Placeholder

Replace With

DATE

A date value, such as a Date variable

NUM

A number value

You can add a certain number of years to a Date variable. The result of this computation is a new date value, which can
be merged into the assembled document.
In this script, HotDocs adds 30 years to the date the loan originated:
Loan Origination Date + 30 YEARS

Copyright 2010 HotDocs Ltd. All rights reserved

462

Help Topics for HotDocs Developer 10

DATE OF( NUM, NUM, NUM )

Placeholder

Replace With

NUM

A number value representing the day of the month (from 1 to 31)

NUM

A number value representing the month (from 1 to 12)

NUM

A number value representing the year (should be four digits)

This expression finds a date value based on day, month, and year values.
You can use this expression to compare a date the user gives with another date, such as a cut-off date for when an
employee had to be hired to qualify for a yearly bonus:
IF Hire Date <= DATE OF ( 15, 8, YEAR OF( TODAY ) )
Employee Name + " qualifies for the annual bonus."
END IF
HotDocs uses an IF instruction to compare Hire Date with August 15 of the current year. If the comparison returns a true
value, the employee qualifies for the bonus.
Suppose, in this next example, a new employee qualifies for a benefits package on the first day of the second month of
employmentregardless of what day the employee was hired during the first month of employment. You can calculate
that date with the DATE OF expression:
DATE OF ( 1, MONTH OF( Hire Date + 1 MONTHS ), YEAR OF( Hire Date + 1 MONTHS ))
The first parameter in the expression, 1, tells HotDocs to specify the first day of the month. The second parameter
identifies the month of the hire date and adds one month. The third parameter determines the year of the hire date (plus
one month).

Copyright 2010 HotDocs Ltd. All rights reserved

463

Help Topics for HotDocs Developer 10

DAY OF( DATE )

Placeholder

Replace With

DATE

A date value

This expression returns the day portion (1 to 31) of a given date.

The following computation is used to determine when a new employee can begin accruing vacation days. If the employee
is hired on the first day of the month, he or she immediately begins accruing time off. Otherwise, he or she begins
accruing at the beginning of the next month:
IF DAY OF ( Hire Date ) =
SET Start Accruing Date
ELSE
SET Start Accruing Date
OF( Hire Date + 1 MONTHS
END IF

1
TO Hire Date
TO DATE OF( 1, MONTH OF( Hire Date + 1 MONTHS ), YEAR
) )

Copyright 2010 HotDocs Ltd. All rights reserved

464

Help Topics for HotDocs Developer 10

DAY OF WEEK( DATE )

Placeholder

Replace With

DATE

A Date variable

This expression determines on which day of the week a specific date falls and converts that value to an integer.
These integers are as follows:
Sunday = 1
Monday = 2
Tuesday = 3
Wednesday = 4
Thursday = 5
Friday = 6
Saturday = 7
For example, perhaps you want to determine whether a payment due date falls on a Saturday or Sunday. If it does,
HotDocs moves the payment due date to the following Monday. The following script shows how this works:
IF DAY OF WEEK( Payment Date ) = 7
Payment Date + 2 DAYS
ELSE IF DAY OF WEEK( Payment Date ) = 1
Payment Date + 1 DAYS
ELSE
Payment Date
END IF

Copyright 2010 HotDocs Ltd. All rights reserved

465

Help Topics for HotDocs Developer 10

DAYS FROM( DATE, DATE )

Placeholder

Replace With

DATE

A date value, such as a Date variable

DATE

A date value, such as a Date variable. (These can be in any order.)

This expression allows you to find the number of days between two dates.
In the following example, a buyer has 60 days to make a payment on an account balance. If the buyer has miss ed the
payment deadline, HotDocs merges a warning into the document:
IF DAYS FROM( Purchase Date, TODAY ) > 60
"Your account is past due."
ELSE
"Your account is current. Thank you."
END IF
This example uses an IF/ELSE IF expression to determine the text that must be inserted.

Copyright 2010 HotDocs Ltd. All rights reserved

466

Help Topics for HotDocs Developer 10

FIRST( TEXT, NUM )

Placeholder

Replace With

TEXT

A text value, such as a Text variable, from which the specified number of characters will
be returned. This can be a fixed text value, inside quotation marks.

NUM

A number value, such as a Number variable or a fixed number value. It specifies the
number of characters you want returned.

Using this expression, you can return any number of characters starting with the first character in an answer value.
The following computation looks at the clients first, middle, and last names and returns only the first character from each
of these variables. When merged together, these characters create the clients initials:
FIRST( Client First Name, 1 ) + FIRST( Client Middle Name, 1 ) + FIRST( Client Last
Name, 1 )
In the following example, the first four characters of a clients last name are merged with a case number to create a file
number.
FIRST( Client Last Name, 4 ) + Case Number

Copyright 2010 HotDocs Ltd. All rights reserved

467

Help Topics for HotDocs Developer 10

FORMAT( VALUE, "EXAMPLE" )

Placeholder

Replace With

VALUE

Any Number, Date, or True/False variable

"EXAMPLE"

A format example (in quotation marks) you want used with the value. Must be in a format
HotDocs can recognize.

Sometimes you may need to add a date, number, or true/false value to a text value. You can do this by formatting the
date, number, or true/false value as text.
For example, perhaps you want to create a list of items with their associated monetary values. Because these two values
are different in nature, they cannot be added together without first representing the number value as a text value:
""
REPEAT Purchase Information
RESULT + Item Name + ", " + FORMAT( Item Amount, "$9,999.00" ) + "
"
END REPEAT
In this script, HotDocs first sets the computation value to nothing. Then HotDocs repeats Purchase information and then
places the answers for both Item Name and Item Amount (which is formatted to appear as a text value) in the same text
string, separated by a comma. If Purchase Information is answered more than once, HotDocs manually inserts a hard
return (as shown before the END REPEAT) to create a column of amounts.

Copyright 2010 HotDocs Ltd. All rights reserved

468

Help Topics for HotDocs Developer 10

INTEGER( TEXT )
Placeholder

Replace With

TEXT

A text value, such as a Text variable

Sometimes you may have a text value that contains number characters, as in the case of a time of day value. The
INTEGER expression allows you to convert those number characters into numeric values so you can perform calculations
or compare them with other values.
INTEGER searches the beginning of a text string for number characters and converts those it finds to numeric values.
When it encounters a non-number character (such as a letter or punctuation mark) it stops processing the instruction.
For example, if you tried to find the integer of the word cat, the INTEGER expression would return 0 (zero) since there are
no number characters in cat. However, if you used INTEGER on the text value 12:30, it would return the number value 12
since those characters are numbers. (As explained earlier, it stops processing when it reaches a punctuation mark, which
in this case is a colon.)
One of the main uses for the INTEGER expression is to compare time values. In the following computation, HotDocs is
attempting to determine if a given time value falls after 5:30 P.M. Because time values are text values, the Text variable,
Call Time, must first be converted to an integer before it can be used in the comparison:
IF Call Time CONTAINS "p"
INTEGER( Call Time ) + ( INTEGER( MID( Call Time, 1 + POSITION( Call Time, ":" ),
2 ) ) /60 ) > 5.5
ELSE
INTEGER( Call Time ) + ( INTEGER( MID( Call Time, 1 + POSITION( Call Time, ":" ),
2 ) ) /60 ) > 17.5
END IF
In this script, Call Time is a Text variable with a 24-hour or 12-hour time pattern (99:99 or 99:99 A.M.). HotDocs first
determines if Call Time is in the afternoon (P.M.). If it is, the script uses the INTEGER expression to convert all the digit
characters up to the first non-digit character (the colon) into a numeric value. This number represents the hours portion of
the total time. Using the MID expression to locate the two digit characters after the colon, it also converts these characters
into an integer and divides the value by 60. This number represents the minutes portion of the total time. These two
numbers are added together, and if the result is greater than 5.5 (the equivalent of 5:30), the result is true. If the result is
not greater than 5.5, the result is false.
The second portion of the script (after the ELSE expression) performs the same functions on a non-afternoon time value
that is, one that is either in 24-hour format or in the morning (A.M.).

Copyright 2010 HotDocs Ltd. All rights reserved

469

Help Topics for HotDocs Developer 10

LAST( TEXT, NUM )

Placeholder

Replace With

TEXT

A text value, such as a Text variable, from which the specified number of characters will
be returned. This can be a fixed text value, inside quotation marks.

NUM

A number value, such as a Number variable or a fixed number value. It specifies the
number of characters you want returned.

The LAST expression finds and returns a certain number of characters from the end of a text string.
For example, the following text computation returns the last four digits of a Social Security number:
LAST( Social Security Number, 4 )
In the next example, the user wants to make the answer to Item Type plural. Using the LAST expression, HotDocs checks
to see if the last letter in the value is a specific letter. If so, HotDocs inserts the correct plural suffix.
IF LAST( Item Type, 1 ) = "s" OR LAST( Item Type, 1 ) = "z"
Item Type + "es"
ELSE
Item Type + "s"
END IF
Note:
This example script does not take into consideration words that end in y or x or any other letter that would cause yet
a different result. It is only shown here in its most basic form to demonstrate how the LAST expression functions.

Copyright 2010 HotDocs Ltd. All rights reserved

470

Help Topics for HotDocs Developer 10

LENGTH( TEXT )
Placeholder

Replace With

TEXT

A text value, such as a Text variable. HotDocs counts the characters in this value and
assigns a numeric value.

The LENGTH expression counts the number of charactersincluding spaces and punctuationin a text value, such as a
Text variable.
For example, lets say you want a user to add a descriptive paragraph about the novel he or she has just reviewed. If the
description is brief, youd like to keep it in the same paragraph as the lead-in sentence. However, if the user has much to
say about the novel, you would like to start a new paragraph:
IF LENGTH( Plot Description ) <= 150
The novel's plot description is as follows: Plot Description
ELSE
The novel's plot description is as follows:
Plot Description
END IF

Copyright 2010 HotDocs Ltd. All rights reserved

471

Help Topics for HotDocs Developer 10

MAX( NUM, NUM )

Placeholder

Replace With

NUM

A number value, such as a Number variable

NUM

A number value, such as a Number variable (These values can be in any order.)

The MAX expression compares two number values and returns the greater of the two.
In this example, HotDocs returns the value of either the Monthly Salary or the Monthly Expenses, depending on which is
the greater value:
MAX( Monthly Salary, Monthly Expenses )

Copyright 2010 HotDocs Ltd. All rights reserved

472

Help Topics for HotDocs Developer 10

MID( TEXT, NUM, NUM )

Placeholder

Replace With

TEXT

A text value, such as a Text variable, from which the specified number of characters will
be returned. This can be a fixed text value, inside quotation marks.

NUM

A number value, such as a Number variable or a number you type. This number specifies
where HotDocs starts "returning" characters.

NUM

A number value, such as a Number variable or a number you type. It specifies the
number of characters you want returned.

Like the FIRST and LAST expressions, this expression extracts a specified number of characters from within a text string.
For example, a form template may require that the text variable, Telephone Number (with the telephone number pattern),
be split into three pre-formatted fieldsthe area code, the prefix, and the number. In the following example, three different
computations would be scripted and inserted into the different fields as follows:
MID( Telephone Number, 2, 3 )
MID( Telephone Number, 7, 3 )
LAST( Telephone Number, 4 )
The first computation, which you would place in the area code field, tells HotDocs to include three characters, starting with
the second character (this takes into consideration the opening parenthesis.)
The second computation (the prefix field) starts at the seventh character (again, taking into account the parentheses and
space characters between the area code and the prefix), and inserts the next three characters.
The third expression, which uses the LAST expression, returns the last four digits of the phone number by counting
backwards from the last character.

Copyright 2010 HotDocs Ltd. All rights reserved

473

Help Topics for HotDocs Developer 10

MIN( NUM, NUM )

Placeholder

Replace With

NUM

A number value, such as a Number variable

NUM

A number value, such as a Number variable. (These values can be in any order.)

The MIN expression compares two number values and returns the lesser of the two.
In the following number computation, the expression compares the two values, Shipping Costs and Labor Costs, and
returns the lesser of the two values:
MIN( Shipping Costs, Labor Costs )

Copyright 2010 HotDocs Ltd. All rights reserved

474

Help Topics for HotDocs Developer 10

MONTH OF( DATE )

Placeholder

Replace With

DATE

A date value, such as a Date variable

This expression returns the month portion of a given date.

For example, in the following script, a new employee has temporary status until the end of his or her third month with the
company. HotDocs uses the MONTH OF expression to specify which month that is:
DATE OF( 1, MONTH OF ( Hire Date + 3 MONTHS ), YEAR OF ( Hire Date + 3 MONTHS ) ) - 1
DAYS
In this example, HotDocs finds the first day of the fourth month of employment. HotDocs then subtracts one day to reveal
the last day of the third montheither the 28th, 29th, 30th or 31stdepending on the month. It then inserts the new date
into the document.

Copyright 2010 HotDocs Ltd. All rights reserved

475

Help Topics for HotDocs Developer 10

MONTHS FROM( DATE, DATE )

Placeholder

Replace With

DATE

A date value, such as a Date variable

DATE

A date value, such as a Date variable. (These values can be in any order.)

The MONTHS FROM expression calculates the number of months between two given dates.
The following example finds the number of months between the judgment date and todayin months:
MONTHS FROM( Judgment Date, TODAY )

Copyright 2010 HotDocs Ltd. All rights reserved

476

Help Topics for HotDocs Developer 10

MULT_CHOICE=TEXT; MULT_CHOICE!=TEXT
Placeholder

Replace With

MULT_CHOICE

A Multiple Choice variable

TEXT

A text value that is either equal to ( = ) or not equal to ( != ) one of the options in the given
Multiple Choice variable, inside quotation marks.

The MULT_CHOICE = TEXT expression returns true when the user chooses a Multiple Choice option that is equal to ( = )
a given text value. If it is not equal ( != ), the expression returns false. The MULT_CHOICE != TEXT expression functions
in the opposite waytesting instead to see if an answer is not equal to ( != ) a given text value.
In the following True/False expression, if the user chooses Credit Card as the payment method, HotDocs asks the user for
the credit card information:
IF Method of Payment = "Credit Card"
ASK Credit Card Information
END IF
In the next expression, if Credit Card is not chosen as a method of payment, HotDocs inserts a template which can gather
alternate payment information about the user:
IF Method of Payment != "Credit Card"
INSERT "Alt payment method.RTF"
END IF
Note:
When writing this script, you can use the auto-complete functionality to access your list of Multiple Choice options.
Specifically, press Ctrl+Spacebar (after you enter the operator) to display a list of the different Multiple Choice options.
See Use the Script Editor for full details on using auto-complete as you write scripts.

Copyright 2010 HotDocs Ltd. All rights reserved

477

Help Topics for HotDocs Developer 10

NOT TRUE_FALSE
Placeholder

Replace With

TRUE_FALSE

A true/false value, such as a variable or expression that results in true or false.

You can use the NOT TRUE_FALSE expression to find out if a True/False variable is false.
In the following script, HotDocs asks whether the user is a United States citizen. If the user is not, HotDocs asks the user
for Visa information:
IF NOT US Citizen
ASK Visa Information
END IF

Copyright 2010 HotDocs Ltd. All rights reserved

478

Help Topics for HotDocs Developer 10

OTHER( MULT_CHOICE_VAR )
Placeholder

Replace With

MULT_CHOICE

A Multiple Choice variable that has either the Other option specified, or the None of the
Above option specified

This expression determines whether the user has chosen the Other option of a Multiple Choice variable and, if so, returns
the text entered in the Other field. It can also be used to test whether the user has selected the None of the Above option.
For example, a user is given a list of lending agents from which to choose. If the user doesnt see the correct name on the
list, he or she can select Other and specify the correct name. HotDocs then asks for the city in which the lending agent
operates, as shown in the following script:
IF Lending Agent = OTHER( Lending Agent )
ASK Lending Agent City
END IF
In this next example, you want to create a list of company representatives. However, if the user doesn't select a company
representative, you want the text No representative selected merged.
""
IF OTHER (Company Representative ) = "None of the Above"
"No representative selected"
ELSE
FORMAT (Company Representative, "a, b, and c")
END IF

Copyright 2010 HotDocs Ltd. All rights reserved

479

Help Topics for HotDocs Developer 10

POSITION( TEXT, TEXT )

Placeholder

Replace With

TEXT

A text value, such as a Text variable

TEXT

The character or character string for which you want to search

The POSITION expression finds the position of a certain character or character string in a given text value. It is useful if
you need to find a character you know will be in an answer but are not sure where it will appear. It returns a number value,
which represents the first character.
The following script finds the hyphen in the variable, Case Number, and returns a number value, representing its numeric
position in that given text string.
POSITION( Case Number, "-" )
In the next example, the POSITION expression is used as part of a larger computation to test whether a given time falls
after 5:30 P.M. POSITION locates the colon (:) in the time value so HotDocs can process the text before and after the
colon to find the correct result:
IF Call Time CONTAINS "p"
INTEGER( Call Time ) + ( INTEGER( MID( Call Time, 1 + POSITION( Call Time, ":" ),
2 ) ) /60 ) > 5.5
ELSE
INTEGER( Call Time ) + ( INTEGER( MID( Call Time, 1 + POSITION( Call Time, ":" ),
2 ) ) /60 ) > 17.5
END IF
This script first determines if the value of Call Time is in the afternoon (P.M.). If it is, the script uses the POSITION
expression to locate the first non-digit character (the colon) so the INTEGER expression can convert all of the digit
characters leading up to it into a numeric value.
Once identified, this number represents the hours portion of the total time. Using the MID expression to locate the two
digit characters after the colon, it also converts these characters into an integer and divides the value by 60. This number
represents the minutes portion of the total time. The hours and minutes are added together, and if the result is greater
than 5.5 (the equivalent of 5:30), the result is true. If the result is not greater than 5.5, the result is false.
The second portion of the script (after the ELSE expression) performs the same functions on a non-afternoon time value
that is, one that is either in 24-hour format or in the morning (A.M.).

Copyright 2010 HotDocs Ltd. All rights reserved

480

Help Topics for HotDocs Developer 10

POWER( NUM, NUM )

Placeholder

Replace With

NUM

A number value, such as a Number variable, to be raised to a power

NUM

The exponent (or number that indicates the operation of repeated multiplication)

The POWER expression generates a numeric value, based on a given exponent.

For example, say you want to calculate the future value of an investment:
POWER( ( 1 + Annual Rate of Return ), Number of Years ) * Amount Invested
HotDocs adds 1 to Annual Rate of Return and then raises it to the power of Number of Years. It then multiplies that
number by Amount Invested.

Copyright 2010 HotDocs Ltd. All rights reserved

481

Help Topics for HotDocs Developer 10

REMAINDER( NUM, NUM )

Placeholder

Replace With

NUM

A number value, such as a Number variable, to be divided (a numerator)

NUM

A number value, such as a Number variable, by which to divide (a denominator)

The REMAINDER expression returns the remainder of a division. If the denominator is a zero, HotDocs generates a
divide by zero error.
In this basic example, HotDocs divides 10 by 3. The remainder of that division is 1:
REMAINDER( 10, 3 )
In this next example, a user enters a time value in number format (such as 6 hours). However, using the REMAINDER
expression (as well as TRUNCATE and ROUND), HotDocs causes the value to appear in hours:minutes format:
FORMAT( TRUNCATE ( Number of Hours, 0 ), "9" ) + ":" +
FORMAT( ROUND ( 60 * REMAINDER( Number of Hours, 1 ), 0 ), "09" )
This script takes the value of Number of Hours, which may have a decimal value, and truncates it to a whole number.
Then, using the REMAINDER expression, Number of Hours is divided by 1 and the remainder of the division is multiplied
by 60 (as in 60 minutes). HotDocs then rounds that value and brings these two values together in a string, separated by a
colon. The value is then formatted correctly.

Copyright 2010 HotDocs Ltd. All rights reserved

482

Help Topics for HotDocs Developer 10

REPLACE( TEXT, TEXT, TEXT, NUM )

Placeholder

Replace With

TEXT

The name of a Text variable or the string of characters you need to search

TEXT

The text for which you are searching, which may include the following special characters:
\\ -- backslash character
\h -- non-breaking hyphen
\l -- line break
\p -- paragraph mark
\s -- non-breaking space
\t -- tab

TEXT

The text you want to use as a replacement, which may include the following special
characters:
\\ -- backslash character
\h -- non-breaking hyphen
\l -- line break
\p -- paragraph mark
\s -- non-breaking space
\t -- tab

NUM (optional)

Controls the number of times the character is replaced

For example, if no number is specified, all found instances will be replaced; however, if
you include a 1 as a parameter, only the first found instance will be replaced.

This expression lets you search a string of text for a given character string and replace the results with new text.
For example, perhaps you want to take the information in an address block (which will most likely appear as separate
lines) and display it as a single line, with each "part" separated by a comma. The following script removes all line breaks
( \l ) from the Text variable, Multi-Line Address, replaces them with a comma and space, and then SETs that result to the
Text variable Single-Line Address:
SET Single-Line Address TO REPLACE(Multi-Line Address, "\l", ", ")

Copyright 2010 HotDocs Ltd. All rights reserved

483

Help Topics for HotDocs Developer 10

RESULT
As you write computations, you often need HotDocs to acknowledge what the result would be at that point in the script.
You can update this answer by using the RESULT expression.
For example, lets suppose you are creating a list of editors. You want to combine Editor First Name TE and Editor Last
Name TE as well as the literal text Editor:. You must use RESULT to force HotDocs to acknowledge the result of the
computation before you add the next item to the text string:
""
REPEAT Editor Information
RESULT + Editor First Name +
"
END REPEAT

" " + Editor Last Name + ", Editor" + "

In this computation, the RESULT expression returns the value of Editor First Name and adds it to the value of Editor Last
Name. The RESULT expression updates the list each time a new editor is added to the list. (If no RESULT expression
were used, HotDocs would merge just the first name entered in the list.)

Copyright 2010 HotDocs Ltd. All rights reserved

484

Help Topics for HotDocs Developer 10

ROUND( NUM, NUM )

Placeholder

Replace With

NUM

A number value, such as a Number variable, to be rounded

NUM

A number value that indicates the number of places (0-7) to the right of the decimal point
after which the number will be rounded

You can round a number value to a specified number of places.

The following example looks at the first two digits after the decimal point and rounds the value based on the third digit.
(The resulting value is 5.93.)
ROUND( 5.9274, 2 )

Copyright 2010 HotDocs Ltd. All rights reserved

485

Help Topics for HotDocs Developer 10

SELECTION( MULT_CHOICE_VAR, NUM )

Placeholder

Replace With

MULT_CHOICE

A Multiple Choice variable

NUM

A number value that indicates which selected option to return

This expression lets you retrieve individual options (answers) selected in a Multiple Choice variable. It returns a text value
that corresponds to the defined answer (as designated by the NUM placeholder).
In the following example, you want to generate a list of employees that have various different work projects they need to
complete. Multiple employees may work on one individual project. Once you have this list, you want to generate a work
list report for each employee on the list.
To accomplish this, you first repeat a dialog (Employee List) that asks which employees are supposed to work on a given
assignment (using the Multiple Choice variable, Employee Names). As HotDocs repeats this list, the UNION expression
adds each selected, original name from each repetition to a new Multiple Choice variable, Unique List.
Once all of the unique answers have been added to Unique List, HotDocs then uses the SELECTION expression to
retrieve each individual answer from Unique List. The result of the script merges these names in a report.
ERASE Unique List
REPEAT Employee List
SET Unique List TO UNION(Unique List, Employee Names )
END REPEAT
ERASE Project Participant
SET Index TO 1
WHILE SELECTION(Unique List, Index ) != ""
SET Project Participant[Index] TO SELECTION(Unique List, Index )
INCREMENT Index
END WHILE

Copyright 2010 HotDocs Ltd. All rights reserved

486

Help Topics for HotDocs Developer 10

SPACE( TEXT, TEXT )

Placeholder

Replace With

TEXT

A Text variable or other expression that produces a text result

TEXT (optional)

A character or text string that can be used in place of the space character. You can
include the following special characters in your search:
\\ -- backslash character
\h -- non-breaking hyphen
\l -- line break
\p -- paragraph mark
\s -- non-breaking space
\t -- tab

This expression tests whether the variable is answered. If it is, it merges the answer, followed by a space character. If the
variable is unanswered, it merges nothing ("").
For example, perhaps you need to merge a client's full name. Some clients, however, do not have a middle name. You
can create a script that includes this middle name (if it's provided), followed by a space. If no middle name is given,
nothing will be merged.
Client First Name + " " + SPACE(Client Middle Name) + Client Last Name
Sometimes you may want to merge a character other than a space. The second optional parameter for this expression
allows you to specify what this character should be.
In the following example, the script uses the SPACE expression to determine if each of the variables in the address
block are answered. If so, it merges the answer to the variable, followed by a line break character (rather than a space
character). This merges each "part" of the address on its own line.
SPACE(Address Line 1, "\l") +
SPACE(Address Line 2, "\l") +
SPACE(City, ",") + SPACE(State) + SPACE(Zip Code)

Copyright 2010 HotDocs Ltd. All rights reserved

487

Help Topics for HotDocs Developer 10

STRIP( TEXT, TEXT, TRUE_FALSE, TRUE_FALSE )

Placeholder

Replace With

TEXT

The name of a Text variable, or the string of characters you need to search

TEXT

The character or string of characters for which you want to search. You can strip any
alphanumeric characters from a text string, including the following special characters:
(Make sure you include the backslash.)
\\ -- backslash character
\h -- non-breaking hyphen
\l -- line break
\p -- paragraph mark
\s -- non-breaking space
\t -- tab

TRUE_FALSE (optional)

The value of TRUE if characters should be stripped from just the beginning of the text

TRUE_FALSE (optional)

The value of TRUE if characters should be stripped from just the end of the text

This expression removes a specified character or characters from the beginning or end of a text answer. By default,
HotDocs removes the characters from both the beginning and the end of the text. If you want to specify just one or the
other, you must use the TRUE_FALSE parameters.
For example, perhaps you want to remove punctuation or space characters from the end of an answer (because the
punctuation is already included in the document text). The following script will help you accomplish this:
SET Product Description TO STRIP(Product Description, " !.,?", FALSE, TRUE)
Because the FALSE and TRUE parameters are used, HotDocs strips the characters from the end of the answer (TRUE)
and not the beginning (FALSE).

Copyright 2010 HotDocs Ltd. All rights reserved

488

Help Topics for HotDocs Developer 10

SUM( COMPUTATION_VAR )
Placeholder

Replace With

COMPUTATION_VAR

A repeated Computation variable

Using the SUM( COMPUTATION_VAR ) expression, you can add computation values that have been repeated.
For example, let's say you have a repeated dialog that contains three variablesItem Name, Item Amount, and Item
Quantity. For each line item, you create a fourth variable, a computation called Total Amount that multiplies Item Amount
by the number of items the user purchases (or Item Quantity). You can then add all of the Total Amount values and
receive one sum total:
SUM( Total Amount )
In order for SUM(COMPUTATION_VAR) to work properly in a template, the script that actually calculates the sum (for
example, the REPEAT instruction) must be processed before the variable containing the SUM expression is asked.
Also, when using RTF templates, headers or footers are always processed before the rest of the template text. This
means that if you are using SUM(COMPUTATION_VAR) in a header or footer, the script that calculates the sum must be
asked in the header or footer.

Copyright 2010 HotDocs Ltd. All rights reserved

489

Help Topics for HotDocs Developer 10

SUM( NUM_VAR )
Placeholder

Replace With

NUM_VAR

A repeated Number variable

Using the SUM expression, you can add repeated number values.
In this computation script, HotDocs totals the values of the repeated Number variable Monthly Payment:
SUM( Monthly Payment )
In the next example, HotDocs then takes the total monthly payments the user is making and compares it to the users
monthly income. If the monthly payments are greater than 36 percent of the monthly income, the loan application is
rejected:
SUM( Monthly Payment ) > ( Monthly Income * 0.36 )

Copyright 2010 HotDocs Ltd. All rights reserved

490

Help Topics for HotDocs Developer 10

TEXT CONTAINS TEXT

Placeholder

Replace With

TEXT

A text value, such as a Text variable

TEXT

A text value, such as a Text variable. Any text you type must be in quotation marks.

The TEXT CONTAINS TEXT expression determines whether the first text value contains the same text as the second
value. If it does, it returns the value of true.
In this example, some states in the United States are officially recognized as commonwealth states. In the following
script, HotDocs examines the answer the user provides for the variable State Name to see if the user has listed one of
these states. If so, HotDocs attaches the correct designation to the merged answer:
IF "massachusetts virginia kentucky pennsylvania" CONTAINS State Name
"The Commonwealth of State Name"
ELSE
"The State of State Name"
END IF
Note:
At first glance, this computation may seem backward. You may think you would test State Name to see if it contains
any of the commonwealths listed in the text string (for example, IF State Name CONTAINS "massachusetts
virginia kentucky pennsylvania"). However, if you used that method, the answer the user assigns to
State Name TE would have to contain everything between the quotation marks"massachusetts virginia kentucky
pennsylvania"and you would never produce a true statement. Of course, you could test State Name against each
individual commonwealth (for example, IF State Name CONTAINS "massachusetts" OR IF State Name
CONTAINS "virginia" and so forth), but by "switching" the values for the placeholders and placing all of the
commonwealths in one text string, you eliminate a lot of repetitive typing.

Copyright 2010 HotDocs Ltd. All rights reserved

491

Help Topics for HotDocs Developer 10

TODAY
This expression returns the current date, according to your computers system clock.
For example, this computation script figures out the number of days between the day the user purchased the item and
todays date (or the date the user assembles the document.)
DAYS FROM( Purchase Date, TODAY )
Note:
You also can create a Date variable called TODAY. See Create a Date Variable that Inserts the Current Date.

Copyright 2010 HotDocs Ltd. All rights reserved

492

Help Topics for HotDocs Developer 10

TRUNCATE( NUM, NUM )

Placeholder

Replace With

NUM

A number value, such as a Number variable

NUM

A number value specifying the number of places (0-7) to the right of the decimal point at
which to truncate the number

You can truncate a decimal number a specified number of places after a decimal point.
For example, the following script truncates the number 5.9375 to include only the first two digits after the decimal point.
The truncated value is 5.93:
TRUNCATE( 5.9375, 2 )
In the next example, however, a Computation variable tests if the value of Rent Amount includes cents. The variable is
then formatted to eliminate the text AND NO CENTS from being merged when the variable contains only a whole number:
IF Rent Amount = TRUNCATE( Rent Amount, 0 )
FORMAT( Rent Amount, "NINE DOLLARS" )
ELSE
FORMAT( Rent Amount, "NINE DOLLARS AND TWELVE CENTS" )
END IF
Specifically, this computation compares the actual value of Rent Amount against its truncated value. If the values are
equal, HotDocs formats the answer to exclude the text, AND TWELVE CENTS. Otherwise it includes the text in the
format.
Note:
The difference between the TRUNCATE and the ROUND expressions is that TRUNCATE simply "cuts off" a number
at a specified digit, while ROUND actually rounds a number up or down, based on where you want the number
rounded.

Copyright 2010 HotDocs Ltd. All rights reserved

493

Help Topics for HotDocs Developer 10

UNANSWERED
This expression removes an assigned value from a variable. It is used most often with the SET VAR TO VALUE
instruction:
SET Property Value TO UNANSWERED
If you use this instruction, do not allow the user to change the answer by asking the variable in the interview. Because
HotDocs can potentially reprocess the interview several times, the answer the user enters will always be replaced with the
UNANSWERED value. Only use this value if you want a variable to be unanswered in the assembled document.
Note:
Do not confuse the value of UNANSWERED with that of NOT ANSWERED. UNANSWERED is an actual value
assigned to a variable, while NOT ANSWERED (or !ANSWERED) is used to determine whether a value has been
assigned.

Copyright 2010 HotDocs Ltd. All rights reserved

494

Help Topics for HotDocs Developer 10

UNION( MULT_CHOICE, MULT_CHOICE )

Placeholder

Replace With

MULT_CHOICE

A Multiple Choice variable

MULT_CHOICE

A Multiple Choice variable

This expression creates a single list of all unique options (answers) that have been selected across two or more Multiple
Choice variables.
In the following example, you want to generate a list of employees that have various different work projects they need to
complete. Multiple employees may work on one individual project. Once you have this list, you want to generate a work
list report for each employee on the list.
To accomplish this, you first repeat a dialog (Employee List) that asks which employees are supposed to work on a given
assignment (using the Multiple Choice variable, Employee Names). As HotDocs repeats this list, the UNION expression
adds each selected, original name from each repetition to a new Multiple Choice variable, Unique List.
Once all of the unique answers have been added to Unique List, HotDocs then uses the SELECTION expression to
retrieve each individual answer from Unique List MC. The result of the script merges these names in a report.
ERASE Unique List
REPEAT Employee List
SET Unique List TO UNION( Unique List, Employee Names )
END REPEAT
ERASE Project Participant
SET Index TO 1
WHILE SELECTION( Unique List, Index ) != ""
SET Project Participant[Index] TO SELECTION( Unique List, Index)
INCREMENT Index
END WHILE

Copyright 2010 HotDocs Ltd. All rights reserved

495

Help Topics for HotDocs Developer 10

VALUE( VAR, EXPRESSION )

Placeholder

Replace With

VAR

The name of a variable

EXPRESSION (optional)

The specific value you want to assign to the variable if the user leaves it unanswered.
Otherwise, HotDocs will use one of the following default values:
"" for Text variables
0 for Number variables
1 JAN 1800 for Date variables
FALSE for True/False variables
"" for Multiple Choice variables

This expression returns a default value for the variable type if the variable is unanswered. If the variable is answered, the
value is the answer the user specifies.
For example, users will sometimes purposely not answer a question in the interview. However, all variables must be
answered or the script will fail. Using VALUE assigns an answer (albeit a default one) so that the script or expression can
be processed correctly and still return a value.
In the following example, suppose you need to calculate a sum. However, one of the variables in the calculation, Sales
Tax, may not be required in order to produce the result. Since the variable may be left unanswered, you can use the
VALUE expression to assign a default value of 0 to the variable so that the script can be processed correctly.
The optional EXPRESSION placeholder allows you specify the value that should be returned if the user leaves the
question unanswered. Otherwise, HotDocs will use the default value, shown in the table, above.
Services Cost + Product Cost + VALUE( Sales Tax )

Copyright 2010 HotDocs Ltd. All rights reserved

496

Help Topics for HotDocs Developer 10

YEAR OF( DATE )

Placeholder

Replace With

DATE

A date value, such as a Date variable

You can use this expression model to find the year portion of a given date.
For example, in the following script, a new employee has temporary status until the end of his or her third month with the
company. HotDocs uses the YEAR OF expression to specify the year:
DATE OF( 1, MONTH OF( Hire Date + 3 MONTHS ), YEAR OF( Hire Date + 3 MONTHS ) ) - 1
DAYS
In this example, HotDocs finds the first day of the fourth month of employment. HotDocs then subtracts one day to reveal
the last day of the third montheither the 28th, 29th, 30th or 31stdepending on the month. It then merges the new date
into the document.

Copyright 2010 HotDocs Ltd. All rights reserved

497

Help Topics for HotDocs Developer 10

YEARS FROM( DATE, DATE )

Placeholder

Replace With

DATE

A date value, such as a Date variable

DATE

A date value, such as a Date variable (These values can be in any order.)

This expression calculates the number of years between two given dates.
In the following example, the YEARS FROM expression finds the clients age at the time of the hearing:
YEARS FROM( Hearing Date, Birth Date )
In this next example, the expression determines whether an employee has worked at the company for 25 years or more. If
the employee has, HotDocs merges a paragraph into the document with details of a retirement party:
IF YEARS FROM( Hire Date, Retirement Date ) >= 25
We would like to honor you at a retirement party on Party Date at Party Time at
Party Location.
END IF

Copyright 2010 HotDocs Ltd. All rights reserved

498

Help Topics for HotDocs Developer 10

ZERO( NUM_VAR )
Placeholder

Replace With

NUM

A Number variable

This expression returns the value of zero only if a Number variable is unanswered. If the Number variable is answered,
the value is the answer the user specifies.
For example, users will sometimes leave a Number variable blank instead of entering 0. If the Number variable is then
used in a Computation variable, because it is unanswered, the computation will not be processed. The ZERO expression
ensures the variable is assigned a value so the computation can return a value.
In this example, the ZERO expression is used in the Computation variable Invoice Total to return 0 if the Number variable
Shipping Charge is unanswered.
Total Price + ZERO( Shipping Charge )
Note:
You can suggest default answers for unanswered variables of other types. See VALUE( VAR, EXPRESSION ) for
details.

Copyright 2010 HotDocs Ltd. All rights reserved

499

Help Topics for HotDocs Developer 10

Chapter 32: Linking Templates to a Database

Overview: Link Templates to a Database
Each time you use a text or form template to assemble a document, HotDocs prompts you for the information the template
requires. Once you have answered the questions, HotDocs merges your answers and carries out your instructions to
produce the finished, assembled document.
There are three ways to provide HotDocs with the information it needs during document assembly. You can use any (or a
combination) of these methods:

1. Enter the information manually.

2. Retrieve the information from an answer file (or answer source, such as an Outlook Contacts list).
3. Retrieve the information from a database using a database component.
The last option, which requires you to create a database component, allows you to use answers from a database during
document assembly. That way, information from a company data store or other database-driven program, such as some
case managers, can also be used to assemble a HotDocs document.
Before you can retrieve answers from a database, you must first set up a connection to your database from within a
HotDocs template. Then, once the connection is specified, you can link variables in your template to fields in a database
table. Finally, you can specify several options that control the scope of the records from which the user chooses and how
this data appears to them during the interview.
For a more technical explanation of how database components works, see Understand Database Connectivity.

Copyright 2010 HotDocs Ltd. All rights reserved

500

Help Topics for HotDocs Developer 10

Use Supported Databases

Supported Databases
The following is a list of database programs and servers (and their corresponding OLE DB providers) with which the
HotDocs has been tested and is certified to work. These databases include:
Microsoft Access (Microsoft.Jet.OLEDB)
Microsoft SQL Server (SQLOLEDB)
Oracle (It is strongly recommended that you use the Oracle Provider for OLE DB (OraOLEDB) instead of the
Microsoft OLE DB Provider for Oracle (MSDAORA).)
Any ODBC level 1-compliant database (using the Microsoft OLE DB provider for ODBC (MSDASQL))
HotDocs may also function with other OLE DB providers, as long as the following conditions are met: 1) The OLE DB
provider must accept plain-text command strings, 2) the OLE DB provider must return rowsets (ADO Recordsets) as the
result of commandsnot records and/or streams, and 3) the database must reside in a location accessible by HotDocs.
OLE DB providers that expose data in individual Rows and/or Fields (but not Rowsets) will not work. Please keep in mind
that these are recommended guidelines and meeting these guidelines does not necessarily mean your provider will work
with HotDocs.

Providers.ini
If you are able to establish a connection to a database using an OLE DB provider, but are having trouble accessing
certain data types (most noticeably dates), you can use a file called Providers.ini, which supplies HotDocs with information
specific to each OLE DB provider it accesses. This file augments information not provided by the database and
supersedes HotDocs' own defaults or information which may have been provided by the database.
The Providers.ini file was installed and saved to the HotDocs program folder at the time HotDocs was installed. You can
edit its contents using any text editor. It contains a header explaining the file's syntax and the possible options which
can be specified there. HotDocs queries each OLE DB provider it uses for as much of this information as possible, but
it is possible the information is not supplied. If this is the case, you must create an entry for the OLE DB provider in
Providers.ini. (Examples for doing this are included in the file itself.)
HotDocs needs to know certain details about how to build database commands for a given OLE DB provider. Among
these are:
How the database expects dates to be formatted.
How dates are delimited.
How database literals (table and column names) that contain spaces are delimited.
How schema and/or catalog names are separated from table names.

Copyright 2010 HotDocs Ltd. All rights reserved

501

Help Topics for HotDocs Developer 10

Understand Database Connectivity

HotDocs uses ActiveX Data Objects (or ADO) as the primary means of communicating with databases. (HotDocs 5 used
ODBC.) ADO allows greater flexibility in the types of databases you can access and gives you greater control over how
you extract information from a database.
In order to connect HotDocs to a database using an ADO connection, you must link your template to the database using
an OLE DB provider. An OLE DB provider acts as a "translator" between HotDocs and the database, telling the two how
to interpret the information that is being passed from the database to the template. Many database programs and/or
clients include their own native OLE DB providers, but if you are using a database for which no provider is available, you
can use an ODBC driver for your database and the OLE DB provider for ODBC. An ODBC-type connection allows you to
connect to the database using an ODBC DSN (data source name), which associates a database driver with the database
itself. This help file includes instructions for setting up both types of connectionssee Create a Database Component
Using ADO or Create a Database Component Using ODBC. (For additional information on ADO connections and data link
properties, please either refer to the Windows system help or refer to the help files installed with your particular database
program.)
Once the connection to the database is made, HotDocs must know what information to retrieve from the database. You do
this by linking variables in the template to fields in a database table or view. Optionally, you can set up filtering and sorting
options and designate other custom options that change how records are retrieved from the database.
To perform these various tasks, you can use the features available in the Database Editor, which is a component-editing
dialog box like those used to edit other components. However, if you have experience writing database commands, you
can specify an option that will allow you to define these filters, etc. using your own command text. Be aware, however,
that writing custom commands requires you to have experience using the query language (SQL or other database
query language) required by your specific database program. Because of the large number of databases (and potential
language variants) little effort is made in this help file to teach this. This help file does contain, however, some general
guidelines to help you write your custom commands. (See Use a Custom Command to Retrieve Data from a Database.)
Note:
If you are converting database components created in HotDocs 5 to the latest HotDocs format, you should consider
changing the type of connection you are using to use an OLE DB provider for the specific database program, rather
than the OLE DB provider for ODBC. For information, see Convert ODBC-based Connections to ADO.

Copyright 2010 HotDocs Ltd. All rights reserved

502

Help Topics for HotDocs Developer 10

Create a Database Component Using ADO

In order for programs such as HotDocs to communicate with certain database programs, the database must understand
the command HotDocs issues to retrieve data from it. Likewise, HotDocs must understand how to work with the data that
is retrieved from the database. One way this is accomplished is by using a data presentation layer known as ActiveX Data
Objects, or ADO. ADO allows HotDocs to communicate with a wide range of sources using OLE DB providers for each
specific database program. The OLE DB provider acts as a translator between the specific database and HotDocsit
reads information from the database and tells HotDocs how to interpret the data so HotDocs can use it.
That said, in order to connect with a database, you must tell HotDocs to which database you want it to connect. This
requires you to create at least one database component for your template, which is where information about the
connection is storedincluding information about the OLE DB provider you are using, the name of the database, and any
security information that is required to access data in the database. Once you have created the database component and
assigned a name to it, you must define a connection string, which is what HotDocs will use to connect to the database.
This string contains information about the OLE DB provider, the location of the actual database file or server, and any
other information needed to establish the connection.
To create a database component

1. At the template you want to connect to the database, click the

Component Manager button. The Component

Manager window appears.

2. Click the Components drop-down button and select Databases from the list. The list changes to show only
database components.

3. Click the

New Component button. HotDocs displays the Database Editor.

4. Type a name for the component in the Component name box.

5. Optionally, perform the following tasks:
In the Title box, enter a title for the database component. The title will be used in the interview outline and
dialog title bar.
In the Prompt box, type the information about the database table you want the user to see. This information
will appear above the database table in the assembly window. (See Create a Prompt for a Variable.)
Click the Resource tab and provide a resource option. A resource helps the user know what type of answer to
select. (See Add Resource Information to a Variable or Dialog.)

6. At the Properties tab of the Database Editor, click the Connection properties are defined by drop-down button
and choose an ADO connection string.

7. Click the

Edit button next to the Connection string box. The Data Link Properties dialog box appears.

Note:
The Data Link Properties dialog box is a standard Windows dialog box designed to set up a connection string. If
you have specific questions about items in this dialog box, click the Help button located in the lower-right corner
of the dialog box.

8. Select the OLE DB provider you need from the list of providers. For example:
a. If you are using a Microsoft Access database, select the Microsoft Jet 4.0 provider.
b. If you are using a SQL Server, select the Microsoft Provider for SQL Server.
c. If you are using an Oracle database, select the Oracle Provider for OLE DB.
d. For all other integrations, refer to the documentation for your specific database for help in identifying the correct
provider.

9. Click Next. HotDocs displays the Connection tab of the Data Link Properties dialog box.
Copyright 2010 HotDocs Ltd. All rights reserved

503

Help Topics for HotDocs Developer 10

10. Depending on which OLE DB provider you selected, enter the required information about the data source to which
you are linking, including selecting the actual database file.

11. When finished entering this information, click OK. The Database Editor appears again, showing the ADO
connection string that will link your template to the database. (This connection string is encrypted when it is saved in
the component file, but it will always appear in the Database Editor as plain text.)

12. Click the Field Map tab. The window changes to show how fields in the table will be linked to variables in the
template.

13. At the Table name drop-down list, select the table to which you want to connect. The information from that table
appears in the Field Name column.
Once you have created the database component and associated a table with it, you must link variables in the template to
fields in the database table. (See Link Variables to Database Fields). You also must designate a unique field in the table
as the key field, which will allow HotDocs to remember which record the user selects during assembly. (See Remember
Selected Records.)
Note:
Database connections in HotDocs 5 were maintained using a data presentation layer known as ODBC, or Open
Database Connectivity. The ADO-based connection in HotDocs 10 allows you to continue using ODBC by using
the OLE DB provider for ODBC, rather than a native OLE DB provider for the specific database. Maintaining this
type of connection may be useful when a native OLE DB provider may either be incompatible or unavailable
for you to use. (See Create a Database Component Using ODBC.) However, it is recommended that, where
possible, you update all existing ODBC-based connections to use a native OLE DB provider for the database
program you are using. (See Convert ODBC-based Connections to ADO.)
You can save ADO connection information in a Microsoft Data Link (.UDL) file. This may be useful if you plan
to distribute your templates and databases to users whose systems may not be configured the same as yours.
Because the connection information is saved in a file separate from the component file, it will make it easier for
users without component-editing capabilities to update their connections. See Save ADO Connection Information
in a Separate File for details.
If your connection to the database requires you to enter a user name, password, or other options, you can enter
them at the Options tab of the Database Editor instead of including them in the connection string. See Specify a
User Name and Password for a Database.

Copyright 2010 HotDocs Ltd. All rights reserved

504

Help Topics for HotDocs Developer 10

Create a Database Component Using ODBC

In order for programs such as HotDocs to communicate with certain database programs, the database must understand
the command HotDocs issues to retrieve data from it. Likewise, HotDocs must understand how to work with the data that
gets retrieved from the database. This is accomplished by using a data presentation layer known as ADO, or ActiveX Data
Objects. The functionality behind ADO allows HotDocs to communicate with a wide range of database programs using
OLE DB providers for each specific database program. In essence, an OLE DB provider acts as a translator between the
specific database and HotDocsit reads information from the database and tells HotDocs how to interpret the data so
HotDocs can use it.
Many database programs and/or clients include their own native OLE DB provider (see Create a Database Component
Using ADO), but in some situations, an OLE DB provider may either be incompatible or unavailable for you to use. (Click
here for a list of supported databases.) In such situations, you can use the OLE DB provider for ODBC (Open Database
Connectivity). This type of provider allows you to link your template to the database using an ODBC data source.
To connect to a database using the OLE DB provider for ODBC, you must first make sure you have a database driver
installed that is compliant with ODBC Level One or higher standards. Drivers are often installed when you install the
database program. If the driver you need is not installed, you should contact the database program provider.
Once you know the correct driver is installed, you must create a data source, which sets up a connection between
the database driver and the database so that you can retrieve information from it. You can create one data source to
associate a single driver with several database tables, as long as the tables are associated with one database.
Then, once you set up the data source, you must create a database component that uses your data source. HotDocs
will use the data source to link to the database table that contains your information. You can use Component Manager to
create a database component.
To create an ODBC data source and link it to a database component

1. Click Start > Settings > Control Panel and navigate to the Data Source Administrator dialog box. How you do
this depends on which operating system you are using:
a. Windows 2000: Click Settings > Control Panel. The Control Panel dialog box appears. Then double-click
the Administrative Tools icon. The Administrative Tools dialog box appears. Finally, double-click the Data
Sources (ODBC) icon. The Data Source Administrator dialog box appears.
b. Windows XP: Click Settings > Control Panel > Administrative Tools > Data Sources (ODBC). The ODBC
Data Source Administrator dialog box appears.
c. Windows Vista: Click Start > Programs > Administrative Tools > Data Sources (ODBC). The ODBC Data
Source Administrator dialog box appears.

2. With the Data Source Administrator dialog box displayed (and the User DSN or System DSN tab selected), click
Add. The Create New Data Source dialog box appears.

3. Select the driver you need and click Finish. The ODBC Setup dialog box appears.
4. Type a unique name for the data source in the Data Source Name box.
5. If the ODBC Setup dialog box includes database version options, select the version you are using.
6. Specify the database (or the folder containing the database tables) you want to use. The procedure varies
depending on the driver you selected.

7. At the ODBC Setup dialog box, click OK to return to the Data Source Administrator dialog box. The new data
source is added to the list of data sources.

8. Click OK at the Data Source Administrator dialog box and close the Control Panel window (if it's open).
9. Open the template you want to connect to the database. (See Edit a Template.)
10. Click the

Component Manager button in the HotDocs toolbar. The Component Manager window appears.

Copyright 2010 HotDocs Ltd. All rights reserved

505

Help Topics for HotDocs Developer 10

11. Click the Components drop-down button and select Databases from the list. The list changes to show only
database components.

12. Click the

New Component button. HotDocs displays the Database Editor.

13. Type a name for the component in the Component name box.
14. Optionally, perform the following tasks:
In the Title box, enter a title for the database component. The title will be used in the interview outline and
dialog title bar.
In the Prompt box, type the information about the database table you want the user to see. This information
will appear above the database table in the assembly window. (See Create a Prompt for a Variable.)
Click the Resource tab and provide a resource option. A resource helps the user know what type answer to
select. (See Add Resource Information to a Variable or Dialog.)

15. From the Connection properties are defined by drop-down list, select an ODBC data source.
16. From the ODBC Data Source Name (DSN) drop-down list, select the name of the data source you created earlier.
17. Click the Field Map tab. The window changes to show how fields in the table will be mapped to variables in the
template.

18. At the Table name drop-down list, select the name of the table you want to use. The information from that table
appears in the Field Name column.
Once you have created the database component and associated a table with it, you must link variables in the template to
fields in the database table. (See Link Variables to Database Fields). You also must designate a unique field in the table
as the key field, which will allow HotDocs to remember which record the user selects during assembly. (See Remember
Selected Records.)
Note:
If your connection to the database requires you to enter a user name, password, or other options you do not wish
to include in the ODBC data source, you can enter them at the Options tab of the Database Editor. See Specify
a User Name and Password for a Database.
In order for HotDocs to remember which records your users have selected during assembly, you must assign a
key field. For information on doing this, see Remember Selected Records.

Copyright 2010 HotDocs Ltd. All rights reserved

506

Help Topics for HotDocs Developer 10

Save ADO Connection Information in a Separate File

You can save ADO connection information in a Microsoft Data Link (.UDL) file. When you do this, HotDocs will look in this
file (rather than the component file) for the connection information when it tries to access the database. This is useful if
you plan to redistribute the template set to users who may need to edit the connection information, for example, because
their database is located in a different folder or on a different server than the one you used to develop the template.
Otherwise, storing this information in the component file would make it impossible for HotDocs Player users (who have no
component-editing capabilities) to make the required changes.
To save an ADO connection string

1. Using the Database Editor, define the ADO-based connection string. (See Create a Database Component Using
ADO.)

2. When finished, click the

Save button next to the Connection string box. The Save Microsoft Data Link File

dialog box appears.

3. Specify the location where you want to save the file, type a name for it, and click Save. The file is created.
4. At the Database Editor, click the Connection properties are defined by drop-down button and select a Microsoft
Data Link (.udl) file.

5. Click the

Open button next to the Microsoft Data Link file box and locate the data link file. The component now
looks in this separate file for connection information.

Note:
To edit a data link file, you or your user can double-click the file in Windows Explorer and make the changes in the
Data Link Properties dialog box.
Caution:
Microsoft Data Link (.UDL) files are plain text files. If you use a data link file to store your connection information, you
should be sure sensitive information, such as database user names and passwords, are not specified in the UDL file.
Specify this information in the database component instead, where it will be safely encrypted. See Specify a User
Name and Password for a Database for details.

Copyright 2010 HotDocs Ltd. All rights reserved

507

Help Topics for HotDocs Developer 10

Convert ODBC-based Connections to ADO

Database connections created in HotDocs 5 were driven by ODBC connectivity, which required you to specify an ODBC
data source name in your database component.
Now, when you connect to a database using HotDocs 10, the primary means of connection is ADO. (See Overview: Link
Templates to a Database.) This means that when you convert database components created in HotDocs 5 to HotDocs
2009, HotDocs updates the connection to use the OLE DB provider for ODBC. This allows you to continue to use an
ODBC data source, even though the primary mode of connection is ADO. While this type of connection is fully supported,
performance of the database component may improve if you change your connection to use a native OLE DB provider for
the database you are using.
Caution:
If your database does not have a native OLE DB provider or if the OLE DB provider does not work, you should
continue to use your existing data source, or the data source you created for HotDocs 5. During the conversion,
HotDocs automatically selects the OLE DB provider for ODBC drivers and maintains its connection to your data
source. You should not have to do anything to update your connection information.
You can change the type of connection by editing the database component, and, provided HotDocs can successfully
communicate with the new OLE DB provider, it will maintain all the other properties of the connectionincluding links
between the variables and fields and any filters you have created.
To change an ODBC connection to ADO

1. Convert the template to HotDocs 2009-10 format by editing it. (See Edit a Template.) (You can do this by clicking
Start > Programs > HotDocs 10 > HotDocs. Once the template library appears, you can either add your HotDocs
5 template to the library, or you can open an entire library of HotDocs 5 templates using HotDocs 10. See Add
Templates and Other Files to a Library or Open a Library for instructions.)

2. Once the template is converted to HotDocs 2009-10 format, open the existing database component for editing. (See
Edit a Database Component.) The Database Editor appears.

3. At the Properties tab of the Database Editor, click the Connection properties are defined by drop-down button
and select an ADO connection string.

4. Click the

Edit button next to the Connection string box. The Data Link Properties dialog box appears.

5. Select the provider that corresponds to your database program. (If you are using a Microsoft Access database,
select the Microsoft Jet 4.0 provider. If you are using a SQL Server, select the Microsoft Provider for SQL Server.
If you are using an Oracle database, select the Oracle Provider for OLE DB. For all other integrations, refer to the
documentation for your specific database for help in identifying the correct provider.)

6. Click Next. The Connection tab of the Data Link Properties dialog box appears.
7. Specify the correct database information, following the on-screen instructions provided for your specific provider and
click OK. The Database Editor appears again. Once the new connection information is specified, HotDocs should
maintain all existing properties of the component.

8. Check the different properties of the database component (such as field mappings and database options) and then
click OK to close the Database Editor.

Copyright 2010 HotDocs Ltd. All rights reserved

508

Help Topics for HotDocs Developer 10

Edit a Database Component

You can edit database components using Component Manager.
To edit a database component

1. At the template, click the

Component Manager button. The Component Manager window appears. (See Open
and Close Component Manager.)

2. Select the database component from the list of components and click the

Edit Component button. The Database

Editor appears. (To show only database components in the variable list, click the Components drop-down button
and select Databases.)

3. Make changes to the component as necessary. For example, you can:

Link variables in your template to fields in the database table. (See Link Variables to Database Fields.)
Create a filter to control the number of records that will be retrieved from the database table. (See Limit the
Number of Database Records from Which a User Chooses.)
Sort the data into logical lists for the end user. (See Sort Records in a Database Table.)
Cause HotDocs to remember which records you have selected for subsequent assemblies. (See Remember
Selected Records.)
Specify other database component properties. (See Change Database Component Properties.)
Note:
In order for HotDocs to remember which records your users have selected during assembly, you must assign a key
field. For information on doing this, see Remember Selected Records.

Copyright 2010 HotDocs Ltd. All rights reserved

509

Help Topics for HotDocs Developer 10

Link Variables to Database Fields

Once you connect your template to a database, you can select a table in the database and link its fields to variables in
your template. These links allow HotDocs to retrieve information from the database table each time the template is used
to assemble a document.
When linking variables to fields, data types must match. For example, if the field type is text, you must link to either a Text
variable or a Multiple Choice variable (since Multiple Choice variables are text values).
During assembly, HotDocs processes a template from top to bottom. When HotDocs encounters a variable that you have
linked to a field in a database table, HotDocs first checks to see whether the list of records for that database table has
been displayed yet. If it has not, HotDocs displays it so the user can select one or more records.
Caution:
Database components are designed to link to only one database table. That means that even though you may see
several tables listed in the Table name drop-down list, you can choose only one table for the component.
To create links between variables and database fields

1. Open the database component you want to link to the database table. (See Edit a Database Component.) The
Database Editor appears.

2. Click the Field Map tab. The window changes to show the fields in the table as well as the variables in the template.
3. In the Linked Variable column, click the drop-down button that corresponds to the database field to which you want
to link.

4. Select the variable.

5. Optionally, to show both linked and unlinked variables in the Linked Variable drop-down lists, clear Show unlinked
variables only. Be aware, however, that if you select a variable that is already linked, HotDocs will unlink it in
order to link it to the new field. Each variable in the template can be linked to only one field at a time. (In these lists,
HotDocs uses brackets to show the variable is linked, for example, [Employee Name].)

6. Repeat this process for every variable that can be answered using data from the database table.
Note:
In order for HotDocs to remember which records your users have selected during assembly, you must assign a
key field. For information on doing this, see Remember Selected Records.
In HotDocs, NULL values retrieved from a database are considered unanswered while empty string values ("")
are considered answered, but empty.
When HotDocs queries the database, it retrieves every record from the table, displays them for the user, and
then disconnects from the database. Because of this, you should use a filter on your database component to
minimize the number of records that are initially retrieved. (If filtering is not an option but you still want to avoid
retrieving all records at once, you can click the Options tab of the Database Editor and clear Use disconnected
(client) record set. Be aware, however, that clearing this option can impact the speed with which the user can
scroll through and filter large data sets. It also prohibits the user from sorting the data.) (See Choose a Database
Cursor for more details.)

Copyright 2010 HotDocs Ltd. All rights reserved

510

Help Topics for HotDocs Developer 10

Remember Selected Records

During assembly, when HotDocs connects to a database, it displays a table of records. Once a user selects a record and
moves to another dialog, HotDocs can remember from where in the database table the record was selected so that if the
user revisits the table during the interview, the user can see his or her selection.
For HotDocs to operate this way, you must make one of the fields in the database component the key field. A key field
contains information that is unique to a recordfor example, an invoice number or a customer identification number.
Without a key field, HotDocs has no way to remember from where in the table the record was retrieved and therefore,
cannot retain this information once the user moves to a new dialog. This may be confusing to a user who reviews a
database record selectioneven though answers may appear in the assembled document, the interview shows that no
record has been selected.
Selecting a key field also makes it easier to reuse an answer file that contains selected database records, for the reasons
explained above.
If you are connecting to a database table using a native OLE DB provider, HotDocs recognizes key fields and
automatically assigns them in the database component. (You can always choose a different key field, if necessary.)
However, HotDocs does not recognize existing key fields when you connect to the database using the OLE DB provider
for ODBC, or when your database component is connected to a database view. You must manually identify the key using
the Database Editor.
Caution:
The field you designate as the key field must always have a non-null value. This applies even in cases where you are
defining multiple key fieldsif you specify multiple key columns (because no single column uniquely identifies each
row), then none of the columns you select should be nullable.
To identify a field as a key field

1. Open the database component for editing. (See Edit a Database Component.) The Database Editor appears.
2. Click the Field Map tab. The window changes to show a list of database fields and their related template variables.
3. In the Key column, select the box next to the field you want to designate as the key.
Caution:
If you think you may need an exact replica of a document assembled from a template that includes a database
component, be sure to save a copy of the document. If you try to reassemble the document later, even if you use the
same answer file, the document may not come out exactly the same because the information stored in the connected
database may have changed.
Note:
If no single field in the table or view can uniquely identify a selected record, choose multiple keys, making sure the
combination of information in those fields will be unique for every record.

Copyright 2010 HotDocs Ltd. All rights reserved

511

Help Topics for HotDocs Developer 10

Save Changed Answers Back to the Database

When linking variables in your template to fields in a database, you can allow users to edit answers that are retrieved from
the database. At times, you may want to save changes the user makes back to the database. To allow this, you can select
an option for the database component that allows answers to be saved back to the database record. HotDocs can either
always save the answer back to the database, or it can allow the user to choose whether the answer should be saved
back. If changes should never be saved back to the database, you can disallow write-back for a specific variable.
Changed answers are saved back to the database when the user saves the answer file.
To save changes back to a database record

1. Open the database component for editing. (See Edit a Database Component.) The Database Editor appears.
2. Click the Properties tab. The window changes to show the main properties of the database component.
3. Select Allow database write-back.
4. Click the Field Map tab. The mapping spreadsheet appears. By default, all linked variables are set to never allow
write-back.

5. For each variable's answer you want to save back to the database, click the Write-back drop-down button and
choose the option you need:
Never keeps the answer from being written back to the database if it is changed.
Always always writes the answer back to the database if it is changed. The user will not be notified or
prompted of the change.
Prompt displays a dialog box that lets the user decide if the changed answer should be written back to the
database.
Note:
To allow users to change answers retrieved from the database, select Treat linked variables as asked: Never at the
Options tab of the Database Editor.

Copyright 2010 HotDocs Ltd. All rights reserved

512

Help Topics for HotDocs Developer 10

Change Database Component Properties

You can change certain properties of a database component. These properties control the way information is retrieved
from a database, as well as how the user is able to select which answers will be used in the document.
Database component properties allow you to:
Let users select multiple records.
Let users sort and filter records.
Automatically select records for the user.
Control which variables are asked in the interview, even if the database answers them.
Specify user names and passwords for accessing information in the database.
To change database component properties

1. Open a database component for editing. (See Edit a Database Component.) The Database Editor appears.
2. Click the Options tab. The window changes to show several component options.
3. Make changes as explained in the following table:
To

Do This

Allow the user to choose

Select Allow multiple selections. (Make sure the variables in the template are
two or more records during included in a REPEAT Database instruction so that all the answers can be merged
assembly
correctly.) (See Generate a List of Records in an Assembled Document.)
Force HotDocs to merge
a list of filtered answers
from a database into the
document without allowing
the user to make the
selection

Select Automatically select all filtered records. (See Merge Filtered Records into
the Document Automatically.)

Have HotDocs check

the database for new
or updated data each
time you assemble the
document

Select Automatically refresh linked answers. (See Cause HotDocs to Update

Selected Records Between Assemblies.)

Have HotDocs retrieve

data from a database and
then disconnect from it

Select Use disconnected (client) record set. (See Choose a Database Cursor.)

Give users the ability

to sort columns in
the database table in
ascending or descending
order

Select Allow sorting by end user. Users can then, during assembly, click column
headings in the table and have the records sort in alphanumeric order. They can also
control the order records will be merged into the assembled document.

Give users the ability to

limit the number of records
that appear in the table

Select Allow filtering by end user. This level of filtering does not affect any filters
you have used to retrieve the data from the databaseit only affects the records the
user is viewing at the assembly window.

Change the way HotDocs

treats variables that may
potentially be answered by
the database

Click the Treat linked variables as asked drop-down button and select one of the
following options: Always (HotDocs considers linked variables as always askedit
will not ask them, even if the database does not contain an answer), Never (HotDocs
considers linked variables as never askedit will ask them, even if the database
contains an answer), or Only if Answered from Database (HotDocs asks a linked

Copyright 2010 HotDocs Ltd. All rights reserved

513

Help Topics for HotDocs Developer 10

To

Do This
variable if no answer for the variable exists in the database). (See Ask Variables
Already Answered by the Database.)

Specify a user name

and password so that
information can be
retrieved from the
database

Type the user name and password in the User name and Password boxes,
respectively. This information is encrypted and saved in the component file. (See
Specify a User Name and Password for a Database.)

Note:
In order for HotDocs to remember which records your users have selected during assembly, you must assign a key
field. For information on doing this, see Remember Selected Records.

Copyright 2010 HotDocs Ltd. All rights reserved

514

Help Topics for HotDocs Developer 10

Use a Custom Command to Retrieve Data from a Database

Instead of linking variables to fields using HotDocs field mapping, advanced template developers or database
administrators can link variables to a database using a custom command. A custom command lets you extract exactly the
data you need from the database. It also may allow you to connect HotDocs to an OLE DB provider representing a nontraditional or non-relational data source.
In order to write a custom command, you must be familiar with the text command syntax of the particular OLE DB provider
you are using for the database component. For most relational databases, this is SQL, or at least some variation of SQL.
Some OLE DB providers also accept commands in a language or syntax other than SQL. In all cases, HotDocs should
work with any OLE DB provider that accepts text commands which return recordsets. HotDocs, however, does not work
with OLE DB providers that return records or streams. (Click here for a list of supported databases.)
You write a custom command at the Command tab of the Database Editor. (Instructions for getting this tab are included
below.) This tab lists all the variables in the template to which you can refer in your command. The only modification
HotDocs makes to the command string as it passes it through to the database is the substitution of answers for any
HotDocs fields it finds in the command.
As you add HotDocs components to a custom command string, keep the following in mind:
Custom commands should be written so that the returned recordset always has the same number of columns with
the same column names.
Only HotDocs fields that merge variable answers are permitted. Other fields (such as HotDocs scripting or
instructions) will not work in database commands.
When true/false values are merged into a command, an example format is required. When date values are merged
into a command, an example format is recommended.
For HotDocs variables to be mapped to database fields at design-time, HotDocs must execute the custom command
to determine what the column names and types are that it returns. Because no answers are available to merge at
design-time, HotDocs uses the following guidelines to prepare the command for execution at design-time:
o

If the merge field is a Text variable, Multiple Choice variable or text computation, the merge field is simply
replaced by an empty text string.

If the merge field is a Number variable or number computation, it is replaced by a zero (0) when the command
is issued. If the merge field is a True/False variable or a true/false computation, it is replaced by the false
portion of its example format.

If the merge field is a Date variable or date computation, it is replaced by its example format if one is specified;
if no format is specified, it is replaced by a generic date in the format expected by the OLE DB provider, as
specified in the file Providers.ini. (Click here for more information.)

Caution:
While it might be possible to merge a text computation that would vary the number of columns, or the column names or
types, that were returned by a command, doing so will prevent HotDocs from properly linking those fields to HotDocs
variables. Therefore, HotDocs answers merged into custom commands should only be used to limit or order the
results, not to change the scope of the command.
To create a database component using a custom command

1. Open the database component for editing. (See Edit a Database Component.) The Database Editor appears.
2. From the Command type drop-down list (found on the Properties tab), select User-defined (SQL or custom).
3. Click the Command tab and type the custom command, following the guidelines outlined earlier. Use the command
to retrieve the fields from the table. (Click here for an example of a custom command.)
Once the command script is correct and HotDocs has executed the command, the contents of the Field Map tab are
updated to show both the fields in the database and the variables in the template. You can then link your variables to
fields. See Link Variables to Database Fields.
Copyright 2010 HotDocs Ltd. All rights reserved

515

Help Topics for HotDocs Developer 10

Choose Which Database Fields Appear During Assembly

By default, when you connect your database component to a database table, HotDocs automatically selects every
displayable field in the table for display during assembly, even if some of the fields aren't directly linked to variables in the
template. (HotDocs automatically omits fields which cannot easily be displayed, such as binary fields.) However, you can
choose to display only certain fields.
Also, you can change the order of the database columns as well as the widths of the columns.
To display only selected fields

1. Open the database component for editing. (See Edit a Database Component.) The Database Editor appears.
2. Click the Field Map tab. The window changes to show the options for linking template variables to database fields.
3. In the Display column, clear the check boxes next to the fields you don't want to appear during assembly. Notice the
fields are removed from the list of fields in the Field display order list.

4. Complete any of the following tasks:

To

Do This

Change the order in which

the columns are presented

In the Field display order box, select a field name and drag it to a different location.

Make the column widths

larger than the space
taken by the field name

Enter the number of units in the Width column. This number must be larger than the
number of characters in the column name.

Test the database

component

Click Test. HotDocs displays the database table in the test assembly window.

Note:
If you are using a custom command, you control the order fields appear in the table using the command script
not by rearranging fields in the Field display order box. See Use a Custom Command to Retrieve Data from a
Database for details.
In order for HotDocs to remember which records your users have selected during assembly, you must assign a
key field. For information on doing this, see Remember Selected Records.
When specifying the column width, please note that one unit is about equal to the width of the character 5.

Copyright 2010 HotDocs Ltd. All rights reserved

516

Help Topics for HotDocs Developer 10

Cause HotDocs to Update Selected Records Between Assemblies

You can select an option that allows answers retrieved from a database to be current when it is merged into an
assembled document. This allows data in a table to be updated without the user having to manually re-select the record or
do something else that causes HotDocs to update the connection.
This update happens whenever a user starts a new assembly and then views the database selection dialog. However, if
answers in the underlying database change during the interview, those changes will not be reflected in the interview or the
document. When this option is cleared (which it is, by default), linked answers will only be updated when the user makes
some change to the database tablefor example adding, removing, or moving a selected row. Additionally, the data is
updated when the database returns nothing or only one record, or when the database component has the Automatically
select all filtered records option selected.
To update selected records between assemblies

1. Open the existing database component for editing. (See Edit a Database Component.) The Database Editor
appears.

2. Click the Options tab. The window changes to show several options for the component.
3. Select Automatically refresh linked answers.

Copyright 2010 HotDocs Ltd. All rights reserved

517

Help Topics for HotDocs Developer 10

Limit the Number of Database Records from Which a User Chooses

By default, when HotDocs presents a table of records for the user, every record in the table is displayed. Depending on
the size of the table, this may mean the table with which the user is working may be very large. You can limit the number
of records that appear, however, by filtering the list of records to include only those relevant to the user.
For example, if you are retrieving customer information from a database, you can create a filter that displays only those
customers located in a particular state.
A filter is created by setting up one or more comparisons between the value in a database field and a variable or other
value. Only the records that meet the comparison(s) will be displayed.
To filter certain records from the database table

1. Open the database component for editing. (See Edit a Database Component.) The Database Editor appears.
2. Click the Sort & Filter tab. The window changes to show sorting and filtering options.
3. Click the Filter by Field drop-down button and select the database field you want to use as a filter.
4. Click the Comparison drop-down button and select the type of comparison operator you want to use.
5. Click the Compared to drop-down button and select a value to which you want to compare the field. (This list of
values matches the data type of the field you are using as a filter. If you selected IS EMPTY or IS NOT EMPTY as a
comparison operator, you do not need to select a value here.)

6. Optionally, include another condition for the filter by selecting AND or OR from the first drop-down list of the second
row and completing the condition, just as you did earlier.
Note:
Each filter can have up to five comparison conditions, with each condition connected to the preceding condition
by the keyword AND or OR. When two conditions are connected by AND, they both must return true in order for
a record to be selected. If two conditions are connected by OR, only one of the conditions must be true in order
for a record to be selected. If the filter has multiple conditions, some connected by AND and others by OR, the
conditions connected by AND will be required first, followed by the conditions connected by OR.

7. Optionally, click Test to test the filter. You will see a list of records as it will be presented to the user during
assembly. (See Test Individual Variables.)
In addition to creating a filter yourself, you can allow the user to create his or her own filter during assembly. Filtering
options will appear in the interview for the user to select. To do this, select Allow filtering by end user at the Options
tab.
Note:
You can use a variable in a filter when you want to make the filter dependent on information the user enters
during assembly. For example, you could create a filter to display only those customers located in a particular
state, and users could specify different states each time they assemble a document.
If you have used multiple filters, you can remove all of them by clicking Clear All Filters. To remove a single
filter, click that specific filter's Field drop-down button and select the blank line at the top.
If you are filtering a repeated database component, you can also assign filtering instructions at the REPEAT
Field dialog box. For information about doing this, see Tips on Filtering and Sorting Repeated Database
Components.

Copyright 2010 HotDocs Ltd. All rights reserved

518

Help Topics for HotDocs Developer 10

Specify a User Name and Password for a Database

Some databases require users to provide a user name and password before connecting to the database. If this is the
case for your database, you can provide the information at the Options tab of the Database Editor. Connection strings,
user names, and passwords are saved and encrypted in the component file (for safety purposes).
To specify a user name and password at the Options tab of the Database Editor

1. Open the database component for editing. (See Edit a Database Component.) The Database Editor appears.
2. Click the Options tab. The window changes to show several database component options.
3. In the Connection Options group, type the user name in the User name box.
4. Type the password in the Password box.
Caution:
You can choose to store the username and password in the connection string (by entering them at the Data Link
Properties dialog box). However, ADO connection strings are always displayed in plain text in the Database
Editor, so anyone with component editing capabilities will be able to view the database password in plain text.
(Passwords entered at the Options tab of the Database Editor are masked, though.)
If you must supply a database password for an Access database, you specify it at the All tab of the Data Link
Properties dialog box. (You can access this dialog box by clicking the
Database Editor.)

Copyright 2010 HotDocs Ltd. All rights reserved

Edit button at the Properties tab of the

519

Help Topics for HotDocs Developer 10

Sort Records in a Database Table

To make it easier for users to find records in the database table, you can sort the records by any field in the table, either
in ascending (A to Z, 1 to 9) or descending (Z to A, 9 to 1) order. You can also sort a list at two levels. For example, you
could sort a client list first by state and then within the state by city.
You can also specify an option that allows users to sort the records during the interview. They can sort on any field in the
table and have the contents arranged in ascending or descending order (as described above).
To sort the records for the user

1. Open the database component for editing. (See Edit a Database Component.) The Database Editor appears.
2. Click the Sort & Filter tab. The window changes to show sorting and filtering options.
3. Click the first Sort by drop-down button and select the field on which you want to sort.
4. Click the second Sort by drop-down button and select Ascending or Descending.
5. Optionally, to sort on a second level, select a field at the Then by drop-down list and then choose Ascending or
Descending.
You can let users sort their own records. To allow this, select Allow sorting by end user at the Options tab of the
Database Editor.

Copyright 2010 HotDocs Ltd. All rights reserved

520

Help Topics for HotDocs Developer 10

Generate a List of Records in an Assembled Document

By default, users can merge answers from one selected database record during assembly. However, there may be times
when choosing multiple records would be necessary, for example, to produce a list of answers in a document.
To generate a list of answers that are retrieved from a database, you must repeat the database component that will
provide the answers. You must also specify a database component property that allows the user to select multiple records
from the table.
To assemble a single document that contains a list of records

1. Select the text (including variables, instructions, and so forth) you want repeated using information from different
records and click the

REPEAT Field button. The REPEAT Field dialog box appears.

2. Select REPEAT Database.

3. Click the Database drop-down button and select the database component you want to use.
4. Click the

Edit Component button to open the database component for editing. The Database Editor appears.

5. Click the Options tab and select Allow multiple selections.

6. Click OK at the Database Editor. The REPEAT Field dialog box appears again.
7. Optionally, click Show Advanced and choose sorting or filtering options. (See Tips on Filtering and Sorting
Repeated Database Components for information about doing this.)

8. Click OK. The REPEAT instruction is inserted into the template.

Copyright 2010 HotDocs Ltd. All rights reserved

521

Help Topics for HotDocs Developer 10

Tips on Filtering and Sorting Repeated Database Components

When you REPEAT a database component, you can specify filtering and sorting instructions at two placesat the
Database Editor and at the REPEAT Field dialog box. Generally speaking, instructions specified at the Database
Editor control how the database table appears during the interview, while instructions specified at the REPEAT Field
dialog box control how the data is merged into the assembled document. The following discusses in greater detail these
relationships.

Filtering Repeated Database Components

When you assign a filter at the Database Editor (at the Sort & Filter tab), you are limiting the records from which the
user may choose during the interview. When you assign a filter at the REPEAT Field dialog box, however, you are limiting
the answers that are actually merged into the assembled document.
In most situations, assigning a filter at the database component should be adequate. One situation where it might be
useful to create an additional filter at the REPEAT Field dialog box is if you want the user to select answers from one
table but you want the answers merged into different lists in the document.

Sorting Repeated Database Components

Similarly, when you assign sorting instructions at the Database Editor (at the Sort & Filter tab), HotDocs forces the
records in the table to appear in that order during the interview. If you also select Allow sorting by end user at the
Options tab of the Database Editor, the table initially is presented to users using your sorting order, but users can
then sort the records how they want. If users select multiple records, they can then rearrange the order the answers are
merged into the assembled document.
When you assign sorting instructions at the REPEAT Field dialog box, HotDocs will merge the answers into the
assembled document in the order you specify.
Where possible, you should always use the Database Editor to assign sorting instructions for a repeated database. One
situation where it might be useful to assign sorting instructions at the REPEAT Field dialog box would be if you need to
insert a list of answers at multiple places in the document but need the list to be arranged differently in each location. For
example, perhaps in one location, you would need the list to be sorted based on Invoice Number, but in another place the
list needs to be sorted by Company Name. You could use the sorting instructions at the REPEAT Field dialog box to help
you create these different lists. Make sure, however, that you clear Allow sorting by end user at the Options tab of the
Database Editor.

Copyright 2010 HotDocs Ltd. All rights reserved

522

Help Topics for HotDocs Developer 10

Merge Filtered Records into the Document Automatically

You can have HotDocs automatically select all filtered records and set the linked repeated variables accordingly. This can
be useful if you've designed a filter to automatically retrieve this information from the database and you don't need the
user to make any selections.
To merge all filtered records into the document during assembly

1. Repeat the variables you want answered by the database. (See Generate a List of Records in an Assembled
Document.)

2. Open the database component for editing. (See Edit a Database Component.) The Database Editor appears.
3. Click the Options tab. The window changes to show several database component options.
4. Select Allow multiple selections and then select Automatically select all filtered records.
Now, when your user assembles a document, any records that meet the filter condition are automatically selected and
used to set linked variablesthe table of records will not appear during assembly.

Copyright 2010 HotDocs Ltd. All rights reserved

523

Help Topics for HotDocs Developer 10

Ask Variables Already Answered by the Database

When variables in a template are answered using data from a database, HotDocs considers the variables to be answered
and, by default, won't ask them again. You can, however, have HotDocs ask the variables, even though answers
have already been provided. This may be useful if you want the user to review or change the answers supplied by the
database. Then, if you choose to allow it, users can save any changes they've made to the data back to the database.
(See Save Changed Answers Back to the Database for details.)
Similarly, if a variable requires an answer, but no answer for the variable exists in the database, HotDocs can ask the
variable and allow the user to provide the answer.
To control which linked variables are asked during the interview

1. Open the database component for editing. (See Edit a Database Component.) The Database Editor appears.
2. Click the Options tab. The window changes to show several database component options.
3. Click the Treat linked variables as asked drop-down button and select one of the following options:
Choose Never to have HotDocs never consider linked variables as askedit will ask them elsewhere in the
interview, even if the database contains an answer.
Choose Always to have HotDocs always consider linked variables as askedit will not ask them elsewhere in
the interview, even if the database does not contain an answer.
Choose Only if Answered from Database to have HotDocs ask a linked variable if no answer for the variable
exists in the database.

Copyright 2010 HotDocs Ltd. All rights reserved

524

Help Topics for HotDocs Developer 10

Select Related Database Records

Sometimes your template may link to more than one database table. If both tables have at least one field in common
(for example, both tables have a field named CLIENT_ID), you can create a filter based on this association that will
allow users, during assembly, to select a record from one table and have the corresponding records from the other table
automatically selected. (This common field is sometimes referred to as a foreign key.)
For example, perhaps you want to assemble an invoice letter for a specific client whose payment is past due. Specifically,
you want to select an unpaid invoice record from the INVOICE table and automatically have the associated information
about the client selected from the CLIENT table. This data should then be merged into the assembled document. To do
this, you must create both database components, link the fields in each table to variables in the template, and assign a
filter to the CLIENT table. The filter uses the value of CUSTOMER_ID (which has already been answered by the INVOICE
table) and returns the record from the CLIENT table that matches that value.
To select related records in another table

1. Create database components for two tables in your database. (See Create a Database Component Using ADO and
Link Variables to Database Fields.)

2. Open the database component for the database table from which you want the user to choose a record. (See Edit a
Database Component.)

3. Click the Field Map tab and link the related (or common) field to a variable in the template.
Note:
If no variable exists, create it by clicking the Linked Variable cell and then clicking the
New Component
button. HotDocs automatically creates a variable that matchesas closely as possiblethe properties of the
field. The variable is created, but not inserted into the template, and the field is linked to it.

4. Open the other database component for editing. (This is the database from which you want to select related
records.) The Database Editor appears.

5. Click the Sort & Filter tab. The window changes to show sorting and filtering options.
6. Click the Filter by Field drop-down button and select the related field.
7. Click the Comparison drop-down button and select EQUAL from the list of comparison operators.
8. Click the Compared to drop-down button and select the variable that corresponds to the related fields.
9. At each Database Editor, click OK to close both windows.
Note:
If you are retrieving answers from multiple records, you can have HotDocs automatically select all the records
that meet the filtered condition and merge them into the document. To do this, open the database component
that contains the filter (this is the database component you don't want displayed during assembly) and select
Automatically select all filtered records. (See Merge Filtered Records into the Document Automatically for
more details on using this option.)
See Custom Command Sample for an example of a custom command that actually joins two database tables.

Copyright 2010 HotDocs Ltd. All rights reserved

525

Help Topics for HotDocs Developer 10

Control When Your Database Tables Appear

When HotDocs creates an interview for the user, it reads through the template and displays dialogs based on the
variables it finds in the template text. If a variable is linked to a database table, HotDocs displays the database table
instead.
If you want your database table to appear at certain place in the template, you can insert an ASK Database instruction
into the text of the template where you want the database table to be displayed.
To insert an ASK Database instruction

1. Position the cursor at the point in the template where you want the table to be asked (for example, at the top of the
template).

2. Click the

ASK Field button. The ASK Field dialog box appears.

3. Select ASK Database.

4. Select a database table from the Database drop-down list, or click the

Edit Component button to create a new

database component. (See Create a Database Component Using ADO and Link Variables to Database Fields.)

5. Click OK. The ASK Database instruction is inserted in the template.

Note:
You can group several ASK instructions in one computation script and use that computation to control the order
questions are asked in the interview. (See Put ASK Instructions in a Computation Variable.)

Copyright 2010 HotDocs Ltd. All rights reserved

526

Help Topics for HotDocs Developer 10

Choose a Database Cursor

When HotDocs connects to the database and identifies the information it needs to retrieve, it uses what is called a cursor.
Just as a cursor in a word processor document allows you to move around and select text in a document, a database
cursor allows HotDocs to scroll through and select records from a database table.
A database component can use one of two types of cursors when retrieving data from a database table: client cursors
and server cursors. By default, HotDocs uses a client cursor; however, you can choose to have it use a server cursor. The
following is a discussion about the advantages of each.
Client Cursors
A client cursor retrieves all the data in the result set (possibly across the network) to the user's machine, and manipulates
the data there. The advantages of this are:
End users will have fast scrolling and full ability to change sort order.
The data is only pulled across the network one time.
Server resources (connections) are freed as soon as the data is retrieved. No server connection is maintained
while the user is interacting with the database component, selecting records. This has minimal impact on server
resources.
The primary disadvantage of client cursors is that for very large result sets, the initial loading of the data across a network
consumes bandwidth and can be time consuming. That is why, in HotDocs, it is recommended that you always use filters
to minimize the size of the result sets from which users will choose. (See Limit the Number of Database Records from
Which a User Chooses.)
Server Cursors
Unlike a client cursor, a server cursor opens the connection to the database and leaves it open until the user leaves the
database selection dialog. This may be desirable in a few circumstances, such as when a large result set is required and
the initial performance of a client cursor is prohibitive. However, the disadvantages of a server cursor are:
User scrolling can be slower, as only the displayed data is retrieved from the database at one time.
A connection to the database server must be maintained the whole time the user is selecting records from the
database. Also, network traffic may be impacted if the user scrolls through the data repetitively.
The user cannot change the sort order of the displayed results.
If the user applies filters to very large result sets, performance and network bandwidth usage can be negatively
impacted.
If you're accessing a database that is located on your local machine, there may not be a huge performance difference
between client and server cursors. The biggest difference in this case is that server cursors will not allow you to change
the sort order of the data you are viewing during the interview.
Caution:
Because of these limitations, it is recommended you use client cursorsunless you have a specific reason to choose
otherwise.
Once you decide which type of cursor best fits your needs, you can specify this option at the Options tab of the Database
Editor.
To specify which type of cursor you will use

1. Open the existing database component for editing. (See Edit a Database Component.) The Database Editor
appears.

2. Click the Options tab. The window changes to show several options for the component.
3. Choose one of the following options:
Copyright 2010 HotDocs Ltd. All rights reserved

527

Help Topics for HotDocs Developer 10

Select Use disconnected (client) record set to use a client cursor.

Clear Use disconnected (client) record set to use a server cursor.

Copyright 2010 HotDocs Ltd. All rights reserved

528

Help Topics for HotDocs Developer 10

Chapter 33: Testing HotDocs Automation

Overview: Test HotDocs Templates
Test Variables, Scripts, and Dialogs
As you create variables and computation scripts in your templates, you can test them to make sure they produce the
desired result. Likewise, you can test dialogs to see how the information will be presented to users during document
assembly.
As you test these different components, HotDocs displays the HotDocs test assembly window. If you find that you must
edit the variable, script, or dialog, you can leave the assembly window open, bring the component editor to the front, and
make the required changes. Then, to continue testing, you can click the Update button to review your changes. (Note,
however, that these changes aren't saved to the component file until you click OK or Save at the component editor.)

Test Assemble Documents

At any point during template development, you can test all or part of the template to make sure it is assembling correctly.
Test assembling a document can help you pinpoint trouble spots in the template without requiring you to close the
template and assemble it from the library.
When you test assemble a document, HotDocs displays the same HotDocs assembly window users will see. At any time
during test assembly, you can return to the template, make the desired changes, and test assemble the document again.
The test assembly window will adjust to show your changes.

Use the Test Panel

To help you test, you can use the HotDocs Test Panel. This feature lets you examine variable usage, including whether
variables referenced in the interview are actually used in the document (and vice versa). Features of the Test Panel also
let you check to make sure you've properly asked variables and set values for variables in the template. Finally, during a
test assembly, you can link from the Document Preview tab of the test assembly window back to a specific place in the
template.

Resolve Problems in a Template or Script

As you test, you may find problems with your automation. For example, HotDocs may display a syntax error or warning
you must fix before the template or script can be properly tested. To help you resolve syntax errors, HotDocs displays
error messages that contain information about the specific error as well as a command for going to the error in the
template.
Additionally, perhaps a test assembly produces a result you don't expect. To help you step through a template or script in
order to determine why you're receiving unexpected results, HotDocs provides the HotDocs Debugger.

Copyright 2010 HotDocs Ltd. All rights reserved

529

Help Topics for HotDocs Developer 10

Test Individual Variables

When youre creating a variable or an IF instruction, you can test it to see if its working the way you want. Even if the
variable is linked to a custom dialog, HotDocs still tests it individually. You can test variables by clicking the Test button at
the variable editor.
To test a variable or True/False expression

1. Edit a variable or IF instruction. (See Edit a Variable or Edit an IF Instruction or Expression.)

2. Click Test at the variable editor. HotDocs displays a test assembly window.
3. Enter an answer for the variable.
4. Optionally, if you assigned a resource to the variable, view the Resource pane. (The Resource pane appears below
the dialog pane. If it is not visible, select it at the View menu.)

5. Click the Result tab to see the answer that would be merged in the assembled document.
6. Optionally, place your cursor in the answer field and click the

Edit Component button in the assembly window

toolbar. The variable editor comes to the front so you can make changes. Click Update to update the window.
To permanently save the changes, click OK at the variable editor. (See Simultaneously Edit a Template and Test
Assemble a Document.)

7. Click Close (File menu) to close the test assembly window.

Note:
You can save your test answers in a test answer file. See Use a Test Answer File.
You can have HotDocs arrange the test assembly window with other open windows. Adjust the height of the test
assembly window and then click the

Copyright 2010 HotDocs Ltd. All rights reserved

Arrange button.

530

Help Topics for HotDocs Developer 10

Test a Computation Script

Often, as you write calculations or scripts, you want to make sure they produce the desired result. You can test
computations and scripts as you write them. When you do this, HotDocs displays a test dialog where you can enter the
information that is needed to produce a result.
To test a script

1. At the Computation Editor, enter your computation or script. (See Customize a Computation Variable and Use the
Script Editor.)

2. When finished, click Test. HotDocs displays a test assembly window.

3. Enter any required information and click the Result tab. HotDocs displays the computed answer.
4. Optionally, to further edit the variable, leave the test assembly window open and return to the Computation Editor to
make the changes. Click Update at the Computation Editor to update the test assembly window. To permanently
save the changes, click OK at the Computation Editor. (See Simultaneously Edit a Template and Test Assemble a
Document.)

5. Click Close (File menu) to close the test assembly window.

Note:
You can save your test answers in a test answer file. See Use a Test Answer File.
When you test a computation script, if HotDocs finds any syntax errors in the script, it displays a warning
message and then places your cursor as close to the error as possible in the Script box. You must fix the error
before HotDocs will allow you to save the script. (See Understand and Resolve Syntax Errors in a Template or
Script.)
You can have HotDocs arrange the test assembly window with other open windows. Adjust the height of the test
assembly window and then click the

Copyright 2010 HotDocs Ltd. All rights reserved

Arrange button.

531

Help Topics for HotDocs Developer 10

Test a Custom Dialog

You can test a custom dialog to see how the dialog contents will appear during an interview, including any scripting you
may have assigned. When you test assemble a dialog, HotDocs displays a test assembly window so you can see the
dialog exactly as the user will see it.
To test a custom dialog

1. Edit the dialog you want to test. (See Edit a Custom Dialog.)
2. At the dialog, click Test. HotDocs opens a test assembly window, which shows the different components of the
dialog you are editing.

3. Make sure variable prompts, dialog elements, and check boxes appear correctly.
4. Optionally, select the dialog icon in the interview outline and click the

Edit Component button in the assembly

window toolbar. The Dialog Editor comes to the front so you can make changes. Click Update to update the
window. To permanently save changes, click OK at the Dialog Editor. (See Simultaneously Edit a Template and
Test Assemble a Document.)

5. If you've created a dialog script, type information in the answer fields to make sure the script is updating the dialog
correctly.
Note:
You can save your test answers in a test answer file. See Use a Test Answer File.
You can have HotDocs arrange the test assembly window with other open windows. Adjust the height of the test
assembly window and then click the

Copyright 2010 HotDocs Ltd. All rights reserved

Arrange button.

532

Help Topics for HotDocs Developer 10

Test Assemble a Document

When youre automating a template, you can test assemble it at any time to see if the document assembles the way you
want. When testing a text document, you can test assemble all or just part of it. When testing a form template, you can
test using direct-fill mode as well as using an interview (if one has been specified).
To test assemble a text template

1. At the template, click the

Assemble button. HotDocs opens a test assembly window.

2. Answer questions as they are presented.

3. Click the Document Preview tab to see the assembled document, just as the user will.
4. Choose Close (File menu) to close the test assembly window, or switch windows to return to the template.
To test assemble a form template

1. At the form template, click the

Assemble button. HotDocs opens a test assembly window.

2. If you have created a custom interview, you can view the template's variables and dialogs in the left pane (or
interview outline) and the corresponding answer fields in the right pane (or dialog pane). Answer questions as they
are presented.

3. Click the Form Document tab to see the assembled document, just as the user will.
4. Optionally, click or tab through the fields in the Form Document tab to fill the form directly.
5. Choose Close (File menu) to close the test assembly window, or switch windows to return to the template.
Note:
You can save your test answers in a test answer file. See Use a Test Answer File.
As you complete the interview, you can move between dialogs by clicking dialog icons in the interview outline, by
clicking the Next or Previous buttons in the navigation bar, or by pressing Alt+N or Alt+P.
To test a template for online assembly, press the Shift key while clicking the
View an Interview in a Web Browser.)

Test Assemble button. (See

You can have HotDocs arrange the test assembly window with other open windows. Adjust the height of the test
assembly window and then click the

Arrange button.

When you test assemble a document from a template, if HotDocs finds any syntax errors in the template,
it displays a warning message, which allows you to go to the place in the template where the error occurs.
You must fix the error before HotDocs will let you continue. (See Understand and Resolve Syntax Errors in a
Template or Script.)
In Microsoft Word, you can also test assemble a document either by clicking on the HotDocs drop-down menu
in the HotDocs toolbar and choosing Test Assemble, or by right-clicking in the template and choosing Test
Assemble from the shortcut menu.
If you receive an error message that includes a field number, you can quickly go to that field in the template. To
do this, click the

Go To Field command. See Go to a Specific Field in the Template for details.

Copyright 2010 HotDocs Ltd. All rights reserved

533

Help Topics for HotDocs Developer 10

Use a Test Answer File

As you test variables, scripts, dialogs, and templates, you can save the answers you use in a special test answer file.
When you do this, these answers will be used each time you test, and you will not be prompted to save answers at the
end of each test.
To save your answers in a special test answer file

1. Test assemble a variable, dialog, or template by entering answers for each question.
2. When finished, close the assembly window. HotDocs asks if you want to save your answers.
3. Click Save or Save As. The Save Answer File dialog box appears.
4. In the File name box, type Test Answer File.
5. In the Title box, enter a title or accept the suggestion HotDocs makes.
6. Click OK.
Now, whenever you test assemble in HotDocs, this answer file will be used and you will not be prompted to save your
answers. To use a different answer file, click either the New Answers button or the
Open Answers button in the
test assembly window toolbar. If you use an existing answer file other than Test Answer File, HotDocs will use this answer
file for each test assembly, but you will be prompted to save any changes you have made to the file when you close the
assembly window.

Copyright 2010 HotDocs Ltd. All rights reserved

534

Help Topics for HotDocs Developer 10

Simultaneously Edit a Template and Test Assemble a Document

You can test a variable, dialog, or script to make sure the information is being processed correctly. When you don't get the
results you expect, you can leave the test assembly window open as you make the necessary changes at the component
editor for the component you are testing. You can then click the Update button and HotDocs refreshes the assembly
window to show your changes. Changes aren't saved to the component file until you click OK at the component editor.
To update the contents of a test assembly window with changes

1. At the template you are editing, test assemble a variable, dialog, computation script, or template.
2. Place your cursor in an answer field (or select a dialog in the interview outline) and click the

Edit Component

button. HotDocs displays the component editor for that specific component.

3. Make any desired changes to a component or the template text and click Update. HotDocs makes the changes in
the test assembly window.

4. Repeat this process until you see the desired result.

5. When you are finished, close the test assembly window and click OK at the component editor. The changes are
saved to the component file.
Note:
You can have HotDocs arrange the test assembly window with other open windows. Adjust the height of the test
assembly window and then click the

Arrange button.

Copyright 2010 HotDocs Ltd. All rights reserved

535

Help Topics for HotDocs Developer 10

Understand and Resolve Syntax Errors in a Template or Script

When HotDocs encounters a component or instruction in a template or script that it doesn't recognize or understand,
it generates and displays a syntax error message. This message lists the component or components HotDocs was
processing when it encountered the error and allows you to go directly to that point in the template or script so you can fix
the problem. (See Understand the HotDocs Scripting Language.)
Errors may be caused by:
Unrecognized variable names: Any references to variables or other components must have a corresponding
component in the component file. For example, you cannot refer to the Text variable Employee Name in the
template unless there is Text variable in the component file named Employee Name. This includes using
unrecognized variable names in prompts, dialog element text, scripts, and so forth.
Incomplete instructions: IF and REPEAT instructions used in the template or a script must have corresponding
END IF and END REPEAT instructions. If HotDocs cannot find these instructions, it generates a syntax error when
you assemble the document. (This includes test assembling from the template development window.) (You can
have HotDocs match opening instructions with closing instructions. See Match Opening Instructions with Closing
Instructions.)
Syntax errors in a script or expression: Writing scripts in HotDocs requires you to use a specific "language" that
HotDocs can recognize and then process. If you use the language incorrectly, or if you use words that are not part of
the language, you will receive an error when you try to save your work.
HotDocs reports syntax errors when you try to test assemble a document and when you try to save a script that contains
syntactical errors:
When a syntax error occurs in a template, HotDocs displays a warning message that describes the error and
displays the processing stack for the error. The stack shows, starting from the bottom, the components HotDocs was
processing when it found the error. The Field denotes the variable or instruction field in the template where the error
occurred, while Position denotes the character position within the field or script.
To resolve such a syntax error, select an entry in the processing stack and click Go To Error. (Usually, you should
select the topmost entry in the stack.) HotDocs takes you to the reference point so you can make the change. (When
you click Go To Error, HotDocs continues to display the error message in a pop-up window, which you can leave
open until you have corrected the error. When finished, click Close at the message box.)
Note:
You can click the
Go to Field button in the HotDocs toolbar to quickly move to a variable or instruction field
containing an error.
When a syntax error occurs in a script, HotDocs displays an error message and then moves the cursor as close to
the error in the script as it can.

Copyright 2010 HotDocs Ltd. All rights reserved

536

Help Topics for HotDocs Developer 10

Chapter 34: Using the HotDocs Debugger

Overview: Debugging Templates
When test assembling templates, you may find that some scripting or automation in your template isnt producing the
result you expect. Perhaps you have created a computation script that is producing an answer you think is wrong. To
help you troubleshoot situations like this, you can test your templates or scripts in Debug mode. You do this by inserting a
DEBUG instruction in the template or script you think may be causing the unexpected result. Then, you test the template
or script using an answer file. When HotDocs processes the DEBUG instruction, it brings up the HotDocs Debugger
so you can step through the script line by line, examining the components and any answers that may be causing the
problem. The Debugger allows you to observe how a script is being processed or how a document is being assembled.
While debugging your templates or scripts, there are several options you can use to help you diagnose the problem.
For example, you can add variables to a watch list, which allows you to track how answers to certain variables change
depending on how other questions are answered in the interview.
The Debugger also displays the processing stack which shows, starting from the bottom, the templates and components
HotDocs is processing at the field or line you are currently examining. For example, if you are debugging a computation
script in an inserted template, the processing stack would include the name of the parent template, the name of the
inserted template, and the name of the Computation variable. Viewing the stack can help you understand what part of the
interview youre viewing as well as provide the path for how you got to it.
You can use the information you gather from debugging to correct problems with automation.

Copyright 2010 HotDocs Ltd. All rights reserved

537

Help Topics for HotDocs Developer 10

Insert Debugging Instructions in Templates and Scripts

To debug your template or script, you must first insert a DEBUG instruction in the template or script. Then, you must test
assemble the template (or test the script). Finally, you must enable debugging in the test assembly window.
To debug your template or script using a certain set of answers, first test assemble the template using those answers and
then save your answers in a test answer file. (See Use a Test Answer File.) Once you have done this, then complete the
steps below.
You can insert a DEBUG instruction:
In a text template.
In a form template.
In a script.
To insert a DEBUG instruction

1. Open the text or form template for editing. (See Edit a Template.)
2. Complete the following steps, depending on where you need to insert the DEBUG instruction:
If you are inserting a DEBUG instruction in a text template, place your cursor where you want to begin
debugging. Click the HotDocs menu and choose Other Field from the list of options. Choose DEBUG from the
Field type drop-down menu. Click OK.
If you are inserting a DEBUG instruction in a form template, create a field on the form where you want to begin
debugging. Select the field and click the
Field Properties button. In the Variable box, type DEBUG. (Close
the Field Properties dialog box when you are finished.)
If you are inserting a DEBUG instruction in a script, edit the computation or dialog whose script you want to
debug. Insert the DEBUG instruction at the place in the script where you want to begin debugging.

3. Click the

Test Assemble button. (If debugging a script, click the Test button.) The test assembly window
appears, along with the HotDocs Debugger window, which stops at the field following the DEBUG instruction. (If the
Debugger window does not appear, make sure debugging is enabled by clicking the
in the assembly window toolbar.)

Enable Debugging button

4. Step through the template or script using the Debugger. (See Step Through a Template or Script.)

Copyright 2010 HotDocs Ltd. All rights reserved

538

Help Topics for HotDocs Developer 10

Step Through a Template or Script

Once you have inserted a DEBUG instruction in a script or in the template, you can begin stepping through the template
or script to determine where your automation is causing unexpected results. The HotDocs Debugger includes several
options for doing this.
Before debugging, however, you should understand how HotDocs processes the template or script:
When you first test assemble a template or script, HotDocs processes (or runs through) the entire template or script
to create the interview, which it displays in the test assembly window. As you answer questions in the interview, some
answers may cause HotDocs to reprocess the script so it can update the interview. (For example, answering a true/false
question may gray or ungray other variables in a dialog. In order for these changes to happen, HotDocs must reprocess
the template.) Depending on the complexity of your template, HotDocs may reprocess the template or script many times
during a test assembly.
During a test, if HotDocs encounters a DEBUG instruction, it displays the HotDocs Debugger, which simply shows you
how the template or script is being processed at that specific field or line using any answers that have been entered. This
allows you to see how variables and instructions are being used to manipulate text in the document or data in the script.
Such analysis will help you understand why you may be seeing unexpected results in your test.
At any time, you can close the Debugger and return to the test assembly window. However, as long as you are in
debugging mode, any time HotDocs processes a DEBUG instruction, the HotDocs Debugger will be redisplayed. This will
happen each time you make a change to answers in the interview that cause it to be reprocessed.
Note:
Debugging mode happens when you have a DEBUG instruction in your script or template and the
Debugging button is selected (pressed down) at the test assembly window.

Enable

To debug your template or script using a certain set of answers, first test assemble and then save your answers in a test
answer file. (See Use a Test Answer File.) Then debug your template. (See Insert Debugging Instructions in Templates
and Scripts.)
To step through a template or script

1. Insert a DEBUG instruction in the script or template and then test assemble the template. (See Insert Debugging
Instructions in Templates and Scripts.)

2. When the HotDocs Debugger window appears, complete any of the following tasks:
To

Do This

Understand why the

Debugger window is
showing

Read the explanation at the top of the tabbed pane.

Examine either each field

Click
Step Into. The Debugger steps into that field or line to show how HotDocs
in the template or each line
has
processed
it using the answers you have provided, specifically:
in the script
If you are in an INSERT instruction, the Debugger will step into the inserted
clause, clause library, or template and show you how that file is being
processed.
If you are in a Computation variable field, the Debugger will step into the
computation and show you how the script is being processed.
If you are in a regular (non-computed) variable field, the Debugger will move
you to the next field or line.

Copyright 2010 HotDocs Ltd. All rights reserved

539

Help Topics for HotDocs Developer 10

To

Do This
As you step into components and instructions, you will notice that you are adding
these levels of processing to the processing stack (which is a sequential list of
templates and components you are processing).

Ignore a field or line in a

script

Click
Step Over. The Debugger will not step through any computations or
subtemplates referenced in the field unless it encounters another explicit DEBUG
instruction.
For example, if you step over a computation field but the computation script includes
a DEBUG instruction, HotDocs will stop at the DEBUG instruction in the computation
script.

Move to the next item on

the processing stack

Click
Step Out. The Debugger will move you out of the current level of debugging
and move you to the next item down on the processing stack (which is a sequential
list of templates and components you are processing).
For example, if you are debugging a computation in an inserted template, clicking
Step Out will move you out of the computation and back to the inserted template.
If you click

Stop processing
any current DEBUG
instructions

Step Out again, the Debugger will return you to the parent template.

Click Continue. HotDocs continues processing the interview until it either finds
another explicit DEBUG instruction (which will cause the Debugger to appear again)
or it finishes processing the template.
Caution:
Changing answers in the interview may cause HotDocs to reprocess the interview,
thus triggering another debug session. To keep this from happening, close the
Debugger window and either remove the DEBUG instruction from the template
or script, or disable the Debugger. (To do this, click the
button in the test assembly window toolbar.)

Cancel the debugging

session

Enable Debugging

Click Stop. HotDocs closes the Debugger window and disables the Debugger. You
are returned to the test assembly window.
Note:
You can start the Debugger again by clicking the
the test assembly window toolbar.

Enable Debugging button in

View the current field

or line of script and
any answers used in
processing it

Click the Default Watch List tab, which shows a list of variables referenced in the
field or script as well as any answers for the variables.

Track the answers for

specific variables as the
Debugger steps through
the interview or script

Click the Custom Watch List tab. See Add Variables to the Debugger Watch List for
details.

As HotDocs processes REPEAT instructions, it displays the value for the current
iteration (or index) in the Answer column. As you step through the REPEAT
instruction, you can watch the Debugger increment this index. The Debugger also
displays the REPEAT COUNTER.

Copyright 2010 HotDocs Ltd. All rights reserved

540

Help Topics for HotDocs Developer 10

To

Do This

View the processing stack,

or path of execution

Click the Processing Stack tab.

The processing stack shows the sequential list of templates and components you are
processing as well as the reason why a certain template or component was added
to the stack. This can help you determine how HotDocs came to be processing the
current field or line. As you step into components, those components are added to
the top of the stack.

Keep HotDocs from

Click Stop at the Debugger window. This closes and disables the Debugger
debugging the template or
Enable Debugging
script without removing the window. (To start another debugging session, click the
button.
HotDocs
reprocesses
the
interview
or
script,
which
forces HotDocs to process
DEBUG instruction
the DEBUG instruction, thus causing the Debugger to open again.)

Copyright 2010 HotDocs Ltd. All rights reserved

541

Help Topics for HotDocs Developer 10

Add Variables to the Debugger Watch List

You can have the Debugger monitor how answers to specific variables change as you step through the interview or script.
You do this by adding variables to a custom watch list.
When you add variables to the watch list, they will be associated with the list until you manually remove them. Also, the
custom watch list contains variables for only the current component file. In other words, if you are debugging a template
that has an inserted template, you can actually have two watch listsone for variables in the parent template and one for
variables in the inserted template.
To add variables to a watch list

1. At the Debugger window, click the Custom Watch List tab. The tab changes to show the list of specific variables
you want to watch.

2. In the Watch pane, right-click and choose Add or Remove Variables from the shortcut menu. The Add or Remove
Variables dialog box appears, showing a list of all the variables in the current component file. (You can filter this list
by clicking the Variables drop-down button and choosing a variable type.)

3. Select a variable and click the

Add Variables button. The variable is added to the Variables to watch list.

4. Add as many variables as you want to monitor and click OK when you are finished. The variables are added to the
Custom Watch List tab.
Note:
To remove a variable from the custom watch list, select the variable and click the
Remove Variables button. You
can also select a variable at the Watch pane, right-click, and choose Remove Selected Variable from the shortcut
menu.

Copyright 2010 HotDocs Ltd. All rights reserved

542

Help Topics for HotDocs Developer 10

Chapter 35: Using the Test Panel

Overview: Use the Test Panel
You can display logistical information about the template you are testing in the Test Panel. This includes viewing a list
of variables that are asked in the interview but not used in the document (and vice versa), and identifying situations
where you've improperly asked or set variable values. Finally, it includes linking from the Document Preview tab of the
assembly window back to a specific place in a Microsoft Word template.
Once you open the Test Panel, you can leave it displayed as you work in the test assembly window. Changes you make
in the interview are automatically reflected in the Test Panel.

Copyright 2010 HotDocs Ltd. All rights reserved

543

Help Topics for HotDocs Developer 10

Validate Variable Usage in a Template

One key to good template automation is making sure the variables asked in the interview are both relevant to the
interview and to the document. Specifically, you must ensure you're not asking questions in the interview that aren't used
in the document, and vice versa. If such a situation exists, the interview and/or document may be incorrect.
You can use the Test Panel to examine which variables are asked in the interview (but not used in the document) as well
as see which variables are not asked in the interview but are used in the document.
Variables listed in these tables appear based on the current answer set. For example, if a variable is included in
conditional text and the condition has not yet been resolved, that variable will appear in the Variables asked in interview
but not referred to in document list. Additionally, if a variable is merged in the document but it is set to Don't ask
automatically and it's not specifically asked in a dialog, it will appear in the Variables referred to in document but not
asked in interview list.
You can use this tool with both text and form templates.
To view variable usage

1. Test assemble the document. (See Test Assemble a Document.)

2. At the test assembly window, click the

Test Panel button. The Test Panel window appears.

3. Click the Variable Usage tab. The view changes to show the validation options.
4. Select Enable variable usage tracking. This generates the variable lists.
5. Review the usage lists and make any necessary corrections to the template or interview script.
6. Optionally, to review the variable's properties, including seeing which dialog links to it, double-click the variable.

Copyright 2010 HotDocs Ltd. All rights reserved

544

Help Topics for HotDocs Developer 10

Check Interviews for Improper Scripting

When assembling documents in HotDocs, HotDocs displays an interview outline in the assembly window. This outline is
dynamic, in that as users enter answers, HotDocs processes the answers and updates the outline as necessary. Because
of this, some scripting may cause the interview to process incorrectly.
Potential problems include SET instructions that have been used incorrectly, and variables that have been asked or
referred to incorrectly. During testing, HotDocs identifies these problems and displays the relevant warnings in the
Warnings tab of the Test Panel. You can go directly from a warning to the problem in the template and make changes.
Many of these warnings pertain to variables being asked incorrectly in the interview. To understand the circumstances
under which a variable or dialog is asked, it is important to note that when the Ask automatically property is selected
for a variable, HotDocs will ask the variable 1) when the answer is used (for example, tested in an IF instruction or
merged into text) and 2) when the variable hasn't been asked before in the interview, either by itself or as part of a dialog.
Additionally, a dialog is asked automatically when 1) the dialog has not been asked before in the interview and 2) when a
variable to which the dialog is linked is asked automatically. Also, a dialog will be asked automatically when it is used in a
REPEAT instruction.
See Warnings Tab Descriptions for a description of each warning.
To test a template for correctly produced interviews

1. At the template you are editing, click the

Test Assemble button. HotDocs displays the test assembly window.

2. Answer questions in a way that causes the interview to update differently based on your answers.
3. Click the

Test Panel button. The Test Panel window appears.

4. Click the Warnings tab. HotDocs displays a window that contains items for which you can check, as well as a list of
actual problems that were found when HotDocs processed the interview.

5. Select a warning from the Warnings in interview list and click Go to Warning. HotDocs takes you to the place in
the template where the potential problem exists. If the problem is in a component, HotDocs opens the component
editor so you can make the changes.
Note:
If you receive an error that includes a field number, you can quickly go to that specific field in the template by clicking
the

Go To Field button in the HotDocs Edit toolbar. See Go to a Specific Field in the Template for details.

Copyright 2010 HotDocs Ltd. All rights reserved

545

Help Topics for HotDocs Developer 10

Move From the Document to the Template During Testing

Caution:
The Go to Template command is supported in Microsoft Word templates only.
When you are test assembling a document, you sometimes need to return to the template to see how automation in the
template affects the portion of the assembled document you are reviewing. Rather than manually search for that section
of text in the template, you can use the Go To Template command in the Test Panel to move from a specific place in the
assembled test document to the template.
Caution:
When using this command, you must test assemble the entire document. The command will not work properly if you
test assemble just a portion of the template.
To go to a specific location in the template from the test assembly window

1. Test assemble the document. (See Test Assemble a Document.)

2. At the test assembly window, click the

Test Panel button. The Test Panel window appears.

3. Click the Go to Template tab. The view changes to show the options available.
4. Select Enable Go to Template.
5. Click the Document Preview tab to view the assembled document.
6. Place your cursor in the document where you want to review the corresponding automation and click Go to
Template. The template window comes to the front and inserts your cursor at the specified location.
Caution:
Selecting Enable Go to Template inserts several hidden field markers in the assembled document that allow HotDocs
to find the correct location in the template when you click Go to Template. (To see these markers, you can right-click
in the assembled document and choose Show Codes.) If you send a test assembled document to Word with this
option enabled, the field markers will appear (albeit hidden) in the new Word document. If you don't want these hidden
markers in the document, clear this option before sending the document to Word. (Of course, these markers will not
appear in a document assembled regularly.)

Copyright 2010 HotDocs Ltd. All rights reserved

546

Help Topics for HotDocs Developer 10

Chapter 36: Managing Templates

Overview: Use Template Manager
You can use Template Manager to manage both templates and component files.
The following is an example of a template library that is being "managed" using Template Manager. A list of templates in
the library appears on the left, while a list of components used in the templates appears on the right.

Manage Templates
Template Manager allows you to view a list of items referenced in a library. This view includes templates and any files
referenced by the templates, including component files, inserted templates, clauses, clause libraries, and so forth.
Template Manager can also report any problems it finds with files you are managing.
You can use Template Manager to convert multiple documents either to HotDocs 2009-10 format or to RTF. Additionally,
you can use Template Manager to rename templates. Using Template Manager to do these tasks can ensure that any
changes you make in one file will be reflected in any other files referenced by it.

Manage Components
Template Manager provides a comprehensive overview of component usage in templates, inserted templates, clause
libraries, and component files, as well as the dependencies between all these files. You can also copy components to
multiple files at once to ensure consistency across templates and component files. Likewise, you can rename components
Copyright 2010 HotDocs Ltd. All rights reserved

547

Help Topics for HotDocs Developer 10

in multiple files. When you rename a component, the change is also reflected in the corresponding template files.
Additionally, you can single out unused components so you can delete them from the component files, which can reduce
the number of components with which you must work in a given file. Finally, you can modify the properties of several
component files at once.

Copyright 2010 HotDocs Ltd. All rights reserved

548

Help Topics for HotDocs Developer 10

Open and Close Template Manager

You can open Template Manager from the HotDocs template library. As Template Manager opens, it scans through the
entire template library and creates a database file that lists all of the files in the library as well as all the components used
in those files. (This happens even if you select only a single file to explore.) HotDocs uses this database to track changes
you make to templates and components so that your changes won't adversely affect other files in the library.
For example, perhaps you want to rename a single template file. When you select it at the template library and launch
Template Manager, HotDocs will create a database of all the files in the library, even though you have selected only one.
This allows HotDocs to make sure that when you rename the template, any other place where the file is referred to in the
library (either in the library itself or in another template), those references are updated with the new file name.
Caution:
This database file is saved to the same file location as the template library. Do not open this file directly with the intent
to modify its contents. Changes you make may have potentially serious consequences. For example, the change may
cause HotDocs to make incorrect assumptions about what files and components are being used. This may make you
think it's safe to delete something you shouldn't, thus "breaking" templates. Additionally, changes in the database may
cause HotDocs to crash if it receives data it is not expecting.
To start Template Manager

1. At the HotDocs template library, select the library items you want to work with and click the

Template Manager
button. A dialog appears telling you that HotDocs is building a component database. (Depending on the number of
files in the library, this process may take several minutes.)
If it encounters any errors when compiling the database, HotDocs displays an option to view the Error Report,
which appears in a temporary text file. The report lists the folder path and file names of the files that contained
the errors.
If it doesn't encounter any errors when compiling the database, it launches Template Manager.

2. Once Template Manager appears, you can perform any number of tasks, such as:
View the contents of a Template Manager window.
Work with Template Manager.
Convert multiple templates to work with HotDocs 10.
Convert templates and clauses to Microsoft RTF.
Rename templates.
Copy and paste components.
Rename components.
Delete components.
To close Template Manager, click the X in the upper-right corner of the Template Manager window.

Copyright 2010 HotDocs Ltd. All rights reserved

549

Help Topics for HotDocs Developer 10

Understand Parts of Template Manager Window

When you first start Template Manager, it creates a database of all of the templates and components found in the current
library. However, only the templates and components for those files you selected in the library appear in the Template
Manager window, which is divided into two panesthe file list and the component list.
Together, the file list and component list show relationships between files and components. For example, when you select
a file, Template Manager displays a

red marker next to the components used in the selected file. Likewise, when you

select a component, HotDocs displays a red marker next to the file or files that use that component either directly or
indirectly (for example, you may have an inserted template that uses that component).
As you examine templates and components in Template Manager, you can customize your view of the window. See
Template Manager Toolbar for details.

Viewing the File List

The file list shows all of the files you selected at the template library. You can expand each file to see all of the files
associated with it. (You can expand the file list to show corresponding component files and inserted templates by clicking
the
Expand button. (Click the Collapse button to once again minimize the list.) For example, if you expand a
template file, you will see the template's component file, as well as any other files that may be referenced in the template.
This can include a clause library (and all of its clauses) and any templates referenced in INSERT or ASSEMBLE
instructions (which are denoted by the

icon.)

In this example, the template, Introductory Instructions Series, is expanded to show the template's component file
(Introdur.cmp) and an inserted template (Table.rtf, which includes an ASSEMBLE instruction to assemble Table1.rtf). It
also shows that a clause library with several clauses has been inserted (Introdur.hdl).

Where there are problems with a specific file, such as the file is referenced either in the library or a template, but doesn't
actually exist on disk, Template Manager overlays a warning on the file icon. (Click here for an explanation of the different
template status icons used.)
You can choose to view either file titles or file names. Right-click anywhere in the file list and choose your preference.
Additionally, you can copy information about the files you're exploring to another program, such as Notepad or the word
processor by choosing Copy as Text from the shortcut menu.
While viewing the file list, you can:
Convert multiple earlier versions of HotDocs templates to HotDocs 10 format.
Convert multiple templates to Microsoft RTF.
Rename templates using Template Manager.
Modify component file properties across multiple files.

Copyright 2010 HotDocs Ltd. All rights reserved

550

Help Topics for HotDocs Developer 10

Viewing the Component List

The component list shows all the components associated with the files in the file list. This can include components
like variables and dialogs, but it can also include supplemental components, such as example formats, merge text,
and patterns. Template Manager shows information about the component, such as whether it's used in a template, or
whether it's referred to in a template but doesn't exist in the component file. (Click here for an explanation of the different
component status icons used.)
You can control what types of components and other information is displayed in the component list. See Set Template
Manager Options for details. Additionally, in the component list, you may see multiple listings of the same component.
This means that while each component shares the same component name, there is at least one property of the
component that is different, such as a prompt. You can right-click the component and select View from the shortcut menu
to view the properties of the component; however, to edit the component's properties, you must use Component Manager,
which you can access by right-clicking the corresponding file and selecting Component Manager from the shortcut menu.
While viewing the component list, you can:
Copy and paste components across multiple component files.
Rename components across multiple component files.
Delete components from multiple component files.
Modify component file properties across multiple files.
Note:
To access the Template Manager toolbar using the keyboard, press F10.

Copyright 2010 HotDocs Ltd. All rights reserved

551

Help Topics for HotDocs Developer 10

Template Manager Toolbar

The following buttons and commands appear on the Template Manager toolbar:
Button or Command

Open Window

Description
Opens a new Template Manager window that shows only the components for the files
you've selected in the file list. This makes it easier to copy components between files
and helps control the number of files and components you are viewing. You can have as
many windows open as necesary.

Expand All

Expands the list to show all top-level entries in the list with their related files.

Collapse All

Collapses the list to show only the top-level entries in the list.

Component Manager

Opens Component Manager.

Component File Properties

Opens the Component File Properties dialog box so you can modify properties across
multiple files at once.

Convert Files

Converts the selected files to either the latest version of HotDocs or to RTF format.

Copy Components

Copies the components so you can paste them in other files.

Paste Components

Pastes copied components into other template's component files.

Rename

Renames the selected file or component.

Delete

Deletes the selected component from the files you select.

Focus

Shows only the components for the selected template or group of templates. (Click
Focus again to show all components.)

Components drop-down
list

Shows only the specific type of component you select.

Refresh

Regenerates the component database and updates the contents of the Template
Manager window if you've made any changes.

Copyright 2010 HotDocs Ltd. All rights reserved

552

Help Topics for HotDocs Developer 10

Options

Changes specific settings for what information Template Manager displays in the
components list.

Copyright 2010 HotDocs Ltd. All rights reserved

553

Help Topics for HotDocs Developer 10

Export Contents of a Template Manager Window to a Spreadsheet

When working with Template Manager, you may want to copy either a list of variables or a list of files to a spreadsheet
so you can work with that data directly. You can do this by first opening the spreadsheet application (such as Microsoft
Excel) and dragging the data directly from Template Manager into the spreadsheet application.
To export lists of items from Template Manager to a spreadsheet

1. Start Template Manager. (See Open and Close Template Manager.)

2. Start the spreadsheet application. (See that program's help file for information on doing this.)
3. Complete either of the following steps:
To copy a list of components to the spreadsheet, select the components in the component list and drag them
to the rows in the spreadsheet you want to fill. When you release the mouse, the component names appear in
one column, while the corresponding component types appears in a second column.
To copy a list of templates to the spreadsheet, select the templates in the file list and drag them to the rows
in the spreadsheet you want to fill. When you release the mouse, the template titles (or file names, if you are
showing them) appear in one column, while the corresponding file path appears in a second column.

Copyright 2010 HotDocs Ltd. All rights reserved

554

Help Topics for HotDocs Developer 10

Convert Multiple Templates to Work with HotDocs 10

Caution:
Any time you make major changes to templates, component files, or other HotDocs files, it is a good idea to back the
files up before making the change. This is especially true when converting component files to work with HotDocs 10.
HotDocs 10 uses a file format for component files that is different from pre-2009 versions of HotDocs. This means that all
component files created in these earlier versions must be converted to HotDocs 2009-10 format in order for them to work.
Failure to convert the files may result in errors when you attempt to assemble documents using them.
You can either convert component files individually (see Convert a Single Template to a New File Format), or you can
convert several at once using Template Manager. When you convert using Template Manager, Template Manager
can convert all component files referred to in the template or templates you are converting. For example, if Template A
contains an INSERT instruction, when you convert Template A, any templates (and component files) referred to in the
instruction will also be converted.
To convert templates to HotDocs 2009-10 format

1. Back up the templates you want to convert by copying them to a different location.
2. Open the library containing the templates you want to convert. (See Create a Library and Add Templates and Other
Files to a Library.)

3. Click the top folder in the library and launch Template Manager. (See Open and Close Template Manager.) The
Template Manager window appears.

4. In the file list, select the templates you want convert. (To select all, press Ctrl+A.)
5. Click the

Convert Files button. The Convert Files dialog box appears.

6. The Convert component files to work with HotDocs 10 option is always selected by default. (This is correct.)
7. Optionally, select one of the options to convert the Word or WordPerfect templates to RTF. (See Convert Templates
and Clauses to Microsoft RTF for details about this kind of conversion.)

8. Click OK. HotDocs converts all the selected files (and any dependent files referenced by the templates) to HotDocs
2009-10 format.

Copyright 2010 HotDocs Ltd. All rights reserved

555

Help Topics for HotDocs Developer 10

Convert Templates and Clauses to Microsoft RTF

Caution:
Any time you make major changes to templates, component files, or other HotDocs files, it is a good idea to back the
files up before making the change. This is especially true when converting component files to work with HotDocs 10.
If you change your word processor brand from WordPerfect to Microsoft Word, you can convert your templates and clause
libraries to Microsoft Word RTF using Template Manager.
If you are already using Microsoft Word but your templates or clauses are in DOT format, you should consider converting
them to RTF. This is because HotDocs assembles all Word templates using an RTF-based assembly process. Therefore,
if your template or clause library is in DOT format, HotDocs must open it, convert it to RTF, and then assemble it. By
automating the templates (and clauses) in RTF, you can reduce the number of steps HotDocs must follow to assemble a
document. This improves assembly speed.
Template Manager allows you to convert multiple files to RTF at once. Doing so ensures that any files dependent on the
file you are converting are likewise converted and references to it are updated. Please note the following:
When you select a template or clause library in the file list to convert, Template Manager will convert that file to the
new format.
If the file you are converting contains INSERTed files, Template Manager will convert both the parent template and
any INSERTed templates or clauses.
Template Manager will not convert files used in ASSEMBLE instructions. However, you can convert these files at the
main list, and any ASSEMBLE instructions that refer to it in other files will be updated.
After a file is converted, Template Manager will search through the contents of the other files in the library to see if any
of those files contain INSERT or ASSEMBLE instructions that refer to the template or clauses it just converted. If so,
Template Manager updates the file name extension in those instructions so that the instruction correctly refers to the new
file.
Caution:
When converting templates to a new format, it's a good idea to convert all the files in the library so that you don't
create any file name extension inconsistencies. For example, TemplateA.wpt and TemplateB.wpt both INSERT
Subtemplate1.wpt. If you were to select only TemplateA for conversion, Template Manager would convert it and
Subtemplate1 to RTF. Template Manager would then update the reference to Subtemplate1 in TemplateB, but
TemplateB would still be in WordPerfect format because you haven't converted it yet. If you tried to assemble
Template B, you would get errors. (Remember, when inserting one template into another, the file types must match.)
To convert WordPerfect / Word templates or clauses to RTF

1. Back up the templates you want to convert by copying them to a different location.
2. Open the library containing the templates you want to convert. (See Create a New Library By Exporting Part of an
Existing Library and Add Templates and Other Files to a Library.)

3. Click the top folder in the library and launch Template Manager. (See Open and Close Template Manager.) The
Template Manager window appears.

4. In the file list, select the templates you want to convert and click the

Convert button. The Convert Files dialog

box appears, with the Convert component files to work with HotDocs 9 option selected by default. (See Convert
Multiple Templates to Work with HotDocs 10.)

5. Select Convert WordPerfect templates and clauses to MS Word RTF to convert your WPTs to RTF.
6. Select Convert MS Word DOT templates and clauses to RTF to convert your DOTs to RTF. HotDocs lists the files
that will be converted in the box below these options.

7. Click OK. Template Manager confirms that you want to convert the files.
8. Click Yes to continue.
Copyright 2010 HotDocs Ltd. All rights reserved

556

Help Topics for HotDocs Developer 10

Template Manager converts the templates (and clauses) to the new format. As it does this, it opens each template file in
Word and makes the necessary updates. Once it finishes converting the templates, it refreshes the Template Manager
database. When conversion is complete, you are returned to the Template Manager window.

Copyright 2010 HotDocs Ltd. All rights reserved

557

Help Topics for HotDocs Developer 10

Rename Templates Using Template Manager

Sometimes as you work with complex template sets, you may want to rename templates. However, renaming templates
in HotDocs isn't as easy as simply renaming the template and component file using Windows Explorer. References to the
template must be updated in the library. References to the file in other templates must also be updated. Additionally, any
other dependent files (such as clause libraries and clause archive files) must also be renamed.
Template Manager allows you to rename a template and have all the corresponding files and references to the template in
other templates updated as well. For example, if you rename a clause library, both its component file and clause archive
file will be renamed. If the clause library is inserted in any templates, the INSERT instruction will be updated with the new
file name.
To rename templates using Template Manager

1. Start Template Manager. (See Open and Close Template Manager.) Template Manager opens.
Note:
You should select all of the templates in the library before starting Template Manager. This makes it easier to
update file names throughout the template set.

2. Optionally, right-click anywhere in the file list and choose Show File Names from the shortcut menu. This lists
templates by file name rather than title, making it easier to identify which files you want to rename.

3. Select the file you want to rename from the file list and click

Rename. The Rename Files dialog box appears.

4. Type the new file name in the New file name box. Do not include a file name extension.
5. As you enter the new file name, Template Manager updates the file list below so you can see which files will be
updated.

6. Click Rename. Template Manager renames all the appropriate files and updates references in the template library. It
also searches through other files in the library and updates any INSERT or ASSEMBLE instructions with the new file
name information.
Note:
If you are renaming a template whose component file is pointed to a shared component file, Template Manager will
rename the pointed component file and repoint it to the shared file.

Copyright 2010 HotDocs Ltd. All rights reserved

558

Help Topics for HotDocs Developer 10

Chapter 37: Managing Components

Overview: Use Template Manager
You can use Template Manager to manage both templates and component files.
The following is an example of a template library that is being "managed" using Template Manager. A list of templates in
the library appears on the left, while a list of components used in the templates appears on the right.

Manage Templates
Template Manager allows you to view a list of items referenced in a library. This view includes templates and any files
referenced by the templates, including component files, inserted templates, clauses, clause libraries, and so forth.
Template Manager can also report any problems it finds with files you are managing.
You can use Template Manager to convert multiple documents either to HotDocs 2009-10 format or to RTF. Additionally,
you can use Template Manager to rename templates. Using Template Manager to do these tasks can ensure that any
changes you make in one file will be reflected in any other files referenced by it.

Manage Components
Template Manager provides a comprehensive overview of component usage in templates, inserted templates, clause
libraries, and component files, as well as the dependencies between all these files. You can also copy components to
multiple files at once to ensure consistency across templates and component files. Likewise, you can rename components
Copyright 2010 HotDocs Ltd. All rights reserved

559

Help Topics for HotDocs Developer 10

in multiple files. When you rename a component, the change is also reflected in the corresponding template files.
Additionally, you can single out unused components so you can delete them from the component files, which can reduce
the number of components with which you must work in a given file. Finally, you can modify the properties of several
component files at once.

Copyright 2010 HotDocs Ltd. All rights reserved

560

Help Topics for HotDocs Developer 10

Open and Close Template Manager

You can open Template Manager from the HotDocs template library. As Template Manager opens, it scans through the
entire template library and creates a database file that lists all of the files in the library as well as all the components used
in those files. (This happens even if you select only a single file to explore.) HotDocs uses this database to track changes
you make to templates and components so that your changes won't adversely affect other files in the library.
For example, perhaps you want to rename a single template file. When you select it at the template library and launch
Template Manager, HotDocs will create a database of all the files in the library, even though you have selected only one.
This allows HotDocs to make sure that when you rename the template, any other place where the file is referred to in the
library (either in the library itself or in another template), those references are updated with the new file name.
Caution:
This database file is saved to the same file location as the template library. Do not open this file directly with the intent
to modify its contents. Changes you make may have potentially serious consequences. For example, the change may
cause HotDocs to make incorrect assumptions about what files and components are being used. This may make you
think it's safe to delete something you shouldn't, thus "breaking" templates. Additionally, changes in the database may
cause HotDocs to crash if it receives data it is not expecting.
To start Template Manager

1. At the HotDocs template library, select the library items you want to work with and click the

Template Manager
button. A dialog appears telling you that HotDocs is building a component database. (Depending on the number of
files in the library, this process may take several minutes.)
If it encounters any errors when compiling the database, HotDocs displays an option to view the Error Report,
which appears in a temporary text file. The report lists the folder path and file names of the files that contained
the errors.
If it doesn't encounter any errors when compiling the database, it launches Template Manager.

2. Once Template Manager appears, you can perform any number of tasks, such as:
View the contents of a Template Manager window.
Work with Template Manager.
Convert multiple templates to work with HotDocs 10.
Convert templates and clauses to Microsoft RTF.
Rename templates.
Copy and paste components.
Rename components.
Delete components.
To close Template Manager, click the X in the upper-right corner of the Template Manager window.

Copyright 2010 HotDocs Ltd. All rights reserved

561

Help Topics for HotDocs Developer 10

Understand Parts of Template Manager Window

When you first start Template Manager, it creates a database of all of the templates and components found in the current
library. However, only the templates and components for those files you selected in the library appear in the Template
Manager window, which is divided into two panesthe file list and the component list.
Together, the file list and component list show relationships between files and components. For example, when you select
a file, Template Manager displays a

red marker next to the components used in the selected file. Likewise, when you

select a component, HotDocs displays a red marker next to the file or files that use that component either directly or
indirectly (for example, you may have an inserted template that uses that component).
As you examine templates and components in Template Manager, you can customize your view of the window. See
Template Manager Toolbar for details.

Viewing the File List

The file list shows all of the files you selected at the template library. You can expand each file to see all of the files
associated with it. (You can expand the file list to show corresponding component files and inserted templates by clicking
the
Expand button. (Click the Collapse button to once again minimize the list.) For example, if you expand a
template file, you will see the template's component file, as well as any other files that may be referenced in the template.
This can include a clause library (and all of its clauses) and any templates referenced in INSERT or ASSEMBLE
instructions (which are denoted by the

icon.)

In this example, the template, Introductory Instructions Series, is expanded to show the template's component file
(Introdur.cmp) and an inserted template (Table.rtf, which includes an ASSEMBLE instruction to assemble Table1.rtf). It
also shows that a clause library with several clauses has been inserted (Introdur.hdl).

Where there are problems with a specific file, such as the file is referenced either in the library or a template, but doesn't
actually exist on disk, Template Manager overlays a warning on the file icon. (Click here for an explanation of the different
template status icons used.)
You can choose to view either file titles or file names. Right-click anywhere in the file list and choose your preference.
Additionally, you can copy information about the files you're exploring to another program, such as Notepad or the word
processor by choosing Copy as Text from the shortcut menu.
While viewing the file list, you can:
Convert multiple earlier versions of HotDocs templates to HotDocs 10 format.
Convert multiple templates to Microsoft RTF.
Rename templates using Template Manager.
Modify component file properties across multiple files.

Copyright 2010 HotDocs Ltd. All rights reserved

562

Help Topics for HotDocs Developer 10

Viewing the Component List

The component list shows all the components associated with the files in the file list. This can include components
like variables and dialogs, but it can also include supplemental components, such as example formats, merge text,
and patterns. Template Manager shows information about the component, such as whether it's used in a template, or
whether it's referred to in a template but doesn't exist in the component file. (Click here for an explanation of the different
component status icons used.)
You can control what types of components and other information is displayed in the component list. See Set Template
Manager Options for details. Additionally, in the component list, you may see multiple listings of the same component.
This means that while each component shares the same component name, there is at least one property of the
component that is different, such as a prompt. You can right-click the component and select View from the shortcut menu
to view the properties of the component; however, to edit the component's properties, you must use Component Manager,
which you can access by right-clicking the corresponding file and selecting Component Manager from the shortcut menu.
While viewing the component list, you can:
Copy and paste components across multiple component files.
Rename components across multiple component files.
Delete components from multiple component files.
Modify component file properties across multiple files.
Note:
To access the Template Manager toolbar using the keyboard, press F10.

Copyright 2010 HotDocs Ltd. All rights reserved

563

Help Topics for HotDocs Developer 10

Template Manager Toolbar

The following buttons and commands appear on the Template Manager toolbar:
Button or Command

Open Window

Description
Opens a new Template Manager window that shows only the components for the files
you've selected in the file list. This makes it easier to copy components between files
and helps control the number of files and components you are viewing. You can have as
many windows open as necesary.

Expand All

Expands the list to show all top-level entries in the list with their related files.

Collapse All

Collapses the list to show only the top-level entries in the list.

Component Manager

Opens Component Manager.

Component File Properties

Opens the Component File Properties dialog box so you can modify properties across
multiple files at once.

Convert Files

Converts the selected files to either the latest version of HotDocs or to RTF format.

Copy Components

Copies the components so you can paste them in other files.

Paste Components

Pastes copied components into other template's component files.

Rename

Renames the selected file or component.

Delete

Deletes the selected component from the files you select.

Focus

Shows only the components for the selected template or group of templates. (Click
Focus again to show all components.)

Components drop-down
list

Shows only the specific type of component you select.

Refresh

Regenerates the component database and updates the contents of the Template
Manager window if you've made any changes.

Copyright 2010 HotDocs Ltd. All rights reserved

564

Help Topics for HotDocs Developer 10

Options

Changes specific settings for what information Template Manager displays in the
components list.

Copyright 2010 HotDocs Ltd. All rights reserved

565

Help Topics for HotDocs Developer 10

Copy and Paste Components Across Multiple Component Files

Sometimes you may create a variable or other component that you would like to copy into all the component files in your
template library. Rather than open each component file manually and copy the variable to it (see Copy Components From
One File to Another), you can use Template Manager to copy a component into several component files at once.
You can copy multiple components at a time. If the component you select is a clause that uses variables, a variable
reference (or variable used in another variable's prompt), a dialog, or Computation variable that refers to or requires other
variables to function, those variables will also be copied to the new component file.
To copy and paste components between component files

1. At Template Manager, select a component or components from the component list and click the

Copy

Components button. The components are saved to the Clipboard.

2. If the component is used in two or more component files, Template Manager displays the Copy Components dialog
box that lets you choose which component file you want to copy from. Select the correct file and click Copy. The
component is saved to the Clipboard.

3. From the file list, select the file or files you want to copy the component into.
4. Click the

Paste Components button. The Paste Components dialog box appears. The files you have already
selected appear in this list with a check mark next to them. The list also includes other component files you are
currently working with.

5. Select additional component files from the list, clear the selected files, or accept the current selection.
6. Optionally, select Warn when overwriting components that already exist if you want Template Manager to warn
you if the component you are copying already exists in the file.

7. Click Paste. Template Manager pastes the component into the file or files.
Note:
You can also drag components from the component list to selected files in the file list to copy and paste them.

Copyright 2010 HotDocs Ltd. All rights reserved

566

Help Topics for HotDocs Developer 10

Rename Components Across Multiple Component Files

Sometimes as you create complex template sets, you may wish to simultaneously change the name of a component
throughout the entire set. You can use Template Manager to select a component, assign a new name, and make the
change in multiple component files.
When you use Template Manager to rename components, components are renamed in both the component file and the
template file. Additionally, when renaming variables, any references to the variable in prompts or dialog element text will
also be renamed.
To rename components using Template Manager

1. At Template Manager, select a component from the component list and click

Rename. The Rename

Components dialog box appears.

2. Type the new component name in the New component name box.
3. From the Following files box, select the files you want to make the change in. (This box lists all of the files that
contain the component or a reference to the component.)
Caution:
If a component is used in a template and its associated component file, you must select both files in the list
before you rename the component. If you select one and not the other, you will create an unresolved reference
and you will not be able to assemble a document from the template. (Template Manager selects both files by
default.)

4. Click Rename. Template Manager renames all selected instances of the component.

Copyright 2010 HotDocs Ltd. All rights reserved

567

Help Topics for HotDocs Developer 10

Delete Components from Multiple Component Files

As you explore component files, you may discover you have several components that are unused. You can use Template
Manager to remove the unused components. If your component file contains a large number of components, removing
unused components can make the list much more manageable.
You can identify an unused component by its status, which is shown in the component list.
Caution:
If you delete a component that is either still referenced in the template or by another component, it deletes the
component from the component file, but does not remove the reference. The component still appears in the component
list in Template Manager; however, its status is Missing. You cannot assemble a document from a template that
contains an unresolved reference.
Components you remove using Template Manager are permanently deleted from the selected component files.
To remove unused components from one or more component files

1. At Template Manager, select the component you want to remove from the component list.
2. Click

Delete. Template Manager confirms that you want to delete the component.

3. Click Yes. Template Manager removes the component from the associated component files.

Copyright 2010 HotDocs Ltd. All rights reserved

568

Help Topics for HotDocs Developer 10

Modify Component File Properties Across Multiple Files

There may be certain component file properties that you want used across multiple templates in your set. You can use
Template Manager to specify these properties at once for all of these files.
For example, perhaps you want all the templates in your library to use the same product title. Rather than change this
property in each individual component file, you can specify a product title using Template Manager and have it applied to
all the selected component files at once.
To modify component file properties in multiple component files

1. At Template Manager, select the files you want to modify from the file list and click the

Component File

Properties button. The Component File Properties dialog box appears.

2. Enter or select which properties you want to change. (See Change Component File Properties for specific details of
each option.)

3. Click OK. HotDocs displays a list of component files that will be changed.
4. Click OK. The changes are made in the selected component files.

Copyright 2010 HotDocs Ltd. All rights reserved

569

Help Topics for HotDocs Developer 10

SECTION 6:
AUTOMATING FORM TEMPLATES

Copyright 2010 HotDocs Ltd. All rights reserved

570

Help Topics for HotDocs Developer 10

Chapter 38: Creating and Working with Forms

Overview: HotDocs Automator
Caution:
When creating a HotDocs form template (.HFT) file in previous versions of HotDocs, you had to use the HotDocs
HFT driver, which was only supported for use with Windows 98 and Windows Me. Starting with the release
of HotDocs 2006, these operating systems are no longer supported. Now, beginning with HotDocs 10, the
functionality for creating and saving form templates in PDF format is integrated with HotDocs.
HotDocs Automator helps you create templates based on graphical formsor forms that contain static text and graphics
that cannot be changed or modified by users. These kinds of forms include loan applications, tax forms, or pre-printed
court forms.
1

To create a PDF template, you first start with a PDF document . Some agencies or organizations with which you work
may provide you with these PDF documents, or you can create your own using PDF-creation software, such as Adobe
Acrobat Professional. You then use HotDocs to convert that file to HotDocs form template format.
When automating form templates, many tasks are identical to automating text templatesyou must 1) identify each place
on the form template where changeable information must be entered, 2) create fields, and then 3) attach variables to
these fields. (See Overview: Create and Customize Variables.)
You can create different types of fields, depending on what type of answer the field requires. For example, edit fields can
be used to merge Text, Date, and Number answers, while check-box fields can be used to merge True/False and Multiple
Choice answers. In contrast, control fields control the flow of information but are hidden from end users. Resource fields,
the final field type, allow you to create a resource for the entire form, which appears as a hyperlink on the form.
Edit and check-box fields, with variables attached, allow users to provide information to complete the form. Sometimes a
users answer is longer than the space available. By designating overflow options, you can manage the problem of limited
space on your form templates. When an answer overflows a field, HotDocs provides several ways to adjust the field or the
answer. One solution is to create an addendum after the last page of the document and save the answers there.
Users assemble form document files from the form templates you develop. They can print blank versions of the forms,
or provide answers for the questions and produce a finished document. After a form document is saved, users can
edit answers in it by using HotDocs Filler. However, once the document is saved and then viewed in Filler, much of
the template functionality is lost. For example, the form fields no longer process computations; they simply act as
placeholders for the users information.
Finally, you can test assemble your form templates to see how they will appear to users. (See Test Assemble a
Document.)

Copyright 2010 HotDocs Ltd. All rights reserved

571

Help Topics for HotDocs Developer 10

HotDocs Automator Toolbar

The following table gives a summary of the Automator toolbar buttons, many of which are also on the assembly window
toolbar:
Button Name

What It Does

HotDocs Library

Opens the HotDocs template library. If the library is already open, it brings it to the front.

New Template

Creates a new, untitled form template.

Open Form

Opens an existing form template.

Save Form

Saves any changes you've made to the current form template and component file.

Print Form

Prints the template currently displayed.

Field Properties

Displays the Field Properties dialog box, where you can change how the answer the
user enters is merged in the assembled document.

Answer Font

Displays the Font dialog box, where you can change the font face, size, or style for the
answer.

Detect Field

Scans the static content around the selected area for lines and text, and then moves the
selected field into position. If no field is selected, creates a new field.

Align Fields

Displays the Align dialog box, where you can arrange the size and layout of multiple
fields.

Undo

Removes the most recent changes you've made to the template.

Redo

Reapplies any changes you may have undone.

Variable Field

Displays the Variable Field dialog box, where you can attach a new variable to a field, or
edit the merge field properties of an existing variable.

Edit Component

Displays the Variable Editor, where you can edit the component properties of the
selected variable.

Component Manager

Opens Component Manager, where you can work with the components used in the
template.

Test Assemble

Starts a test assembly, showing how the current template will appear to users during
assembly.

Fill Tool

Allows you to click on a field and enter a test answer.

Select Tool

Creates new fields (on double-click); also selects and moves existing fields.

Select Text and Fields

Tool

(HotDocs form templates (.HFT) only) Creates new fields (on double-click); also allows
you to select underlying template text.

Scroll Tool

Scrolls the template vertically and horizontally.

Zoom Tool

Changes the view, increasing or decreasing the magnification.

Page Width

Changes the view to fit the left and right edges of the template in the window.

Copyright 2010 HotDocs Ltd. All rights reserved

572

Help Topics for HotDocs Developer 10

Full Page

Changes the view to fit the top and bottom edges of the template in the window.

Show Fields

Shows and hides the colored HotDocs variable fields.

Show Variables

Shows and hides the names of variables attached to each field. (Hiding variable names
lets you enter test answers in the fields so you can test the field properties you've
assigned. See Preview the Formatting of Answers in a Form Field.)

Show Thumbnails

Shows and hides the Thumbnails pane. You can click on a thumbnail (a small image of
each page in the template) to move through the template.

Previous Page

Changes the view to show the previous page.

Next Page

Changes the view to show the next page.

HotDocs Options

Opens the HotDocs Options dialog box where you can customize how HotDocs works.

What's This?

Changes the mouse cursor to a What's This? help cursor. When you click on a button
or property with this cursor, a help window appears, summarizing the purpose for that
option.

Note:
When you highlight a command on a menu or point to a toolbar button, a description of the command displays in
the status bar at the bottom of the window.
You can hide the toolbar and the status bar by choosing Toolbar or Status Bar (View menu). To redisplay the
toolbar or status bar, choose those commands again.

Copyright 2010 HotDocs Ltd. All rights reserved

573

Help Topics for HotDocs Developer 10

Create a Form Template

Caution:
When creating a HotDocs form template (.HFT) file in previous versions of HotDocs, you had to use the HotDocs
HFT driver, which was only supported for use with Windows 98 and Windows Me. Starting with the release
of HotDocs 2006, these operating systems are no longer supported. Now, beginning with HotDocs 10, the
functionality for creating and saving form templates in PDF format is integrated with HotDocs.
For instructions on creating a PDF form template from a fillable PDF document, see Create a Form Template
Using a Fillable PDF.
Using HotDocs Automator, you can create templates based on electronic forms. (Forms are documents that contain
underlying text and graphics that cannot be changed. Examples include loan applications, tax forms, and pre-printed court
forms.) An electronic form can be created in virtually any Windows program from which you can print, such as a word
processor, design, or form creation program.
Before you can automate a form template file, you must first convert an electronic form document into HotDocs template
format. You do this by first printing the document to PDF format using the HotDocs PDF driver. You then save the PDF
as a form template. If the document you want to automate is already in PDF format, you can simply save the PDF as a
HotDocs PDF template.
Note:
You can also use Adobe Acrobat to create PDF documents.
Once you have created a form template file, you can automate it using HotDocs Automator.
Creating a PDF template requires two parts:
Print the document as a PDF file.
Save the PDF file as PDF-based form template.
To create a PDF template

1. If you already have a PDF document, skip to Step 11.

2. Open the document in a Windows program with printing capability.
3. Select the Print command for that program.
4. At the printing dialog box, select HotDocs PDF Driver as the printer.
5. Assign any properties you need to the PDF (such as security settings, watermarks, and so forth.)
6. Click the Print or OK button. The Save As dialog box appears.
7. If necessary, browse and select the location for the file.
8. In the File name box, type a name for the new file.
9. At the Save as type drop-down list, select PDF as the file type.
10. Click the Save button. The PDF file is created and stored in the location you chose. (You can close the original
document.)
You will now create a PDF template from the document you just saved.

11. Start HotDocs. The template library appears. (See Start HotDocs.)
12. Click on a folder in the file list and click the

New Template button. The New Template dialog box appears.

13. Click the Type drop-down button and choose HotDocs PDF Template from the list.
14. Enter a name for the file in the File name box and a title for the template in the Title box.
Copyright 2010 HotDocs Ltd. All rights reserved

574

Help Topics for HotDocs Developer 10

15. In the Initial contents group, select Other file.

16. Click the the

Browse button and browse to (and open) the PDF you created in the first part of these steps.

17. Click OK at the New Template Initial Contents box.

18. Click OK at the New Template dialog box. The new template is opened in HotDocs Automator.
When you create a new form template, HotDocs automatically creates a companion file called the component file
that stores information about components you use in the template, such as variables and dialogs. The component file
works behind the scenes, but both filesthe form template and the component fileare necessary for the template to
work. (The component file works exactly the same for a form template as a text template. See Overview: Template and
Component Files.)
Note:
For information on converting existing form template (.HFT) files to PDF-based templates, see Save Existing HFT
Files as PDF-based Form Templates.
If you are comfortable working directly with file name extensions, you can also use Windows Explorer to change
the file name extension of a PDF file from .PDF to .HPT. Be aware, however, that when you do this (as opposed
to the steps outlined above), no component file will be created until you open the template and add components
to it (either by creating variable fields or by opening Component Manager and adding components that way.)

Copyright 2010 HotDocs Ltd. All rights reserved

575

Help Topics for HotDocs Developer 10

Save Existing HFT Files as PDF-based Form Templates

Caution:
When creating a HotDocs form template (.HFT) file in previous versions of HotDocs, you had to use the HotDocs
HFT driver, which was only supported for use with Windows 98 and Windows Me. Starting with the release
of HotDocs 2006, these operating systems are no longer supported. Now, beginning with HotDocs 10, the
functionality for creating and saving form templates in PDF format is integrated with HotDocs.
With HotDocs, you can convert existing Envoy-based form template (.HFT) files into PDF-based form template (.HPT)
files. The advantage of PDF-based form templates comes to end-users who want to use the templates to create PDF
documents.
Note:
If you want to convert an existing .HFT file to a PDF-based template file, first check to see if you have the original
source file (for example, the original Omniform file) and use that file instead to generate the PDF-based template. This
will maintain the quality of the template.
To convert an HFT file into an HPT file

1. At the HotDocs library window, select the form template you want to convert, and click Edit. HotDocs Automator
appears, showing the selected form template. (If the form template isn't included in the library currently showing,
open the necessary library. See Open a Library.)

2. Select Save As (File menu). The Save As dialog box appears.

Note:
If you change the name of the new template, or change the folder in which the template is saved, you must also
rename the .CMP file and move it to the new folder.

3. At the Save as type drop-down list, select HotDocs PDF Template (*.hpt).
4. Click Save. The Convert to PDF dialog box appears.
5. Optionally, provide information for the Title, Subject, Author, and Keywords boxes.
6. Click OK. The PDF-based form template is created.
7. You can now open the new template in HotDocs Automator to review and work with the template. (See Edit a Form
Template.)

Copyright 2010 HotDocs Ltd. All rights reserved

576

Help Topics for HotDocs Developer 10

Edit a Form Template

You can open existing form templates in three different ways:
To edit a template from the HotDocs library window

1. At the HotDocs library window, select the form template.

2. Click

Edit. The HotDocs Automator window appears, showing the form template.

To edit a template from the HotDocs Automator window

1. At the HotDocs Automator window, click the

Open Form button. The Open dialog box appears.

2. Locate and select the form template you want and click Open. The Automator window appears again, showing the
form template.
To edit a template from Windows Explorer

1. Using Windows Explorer, locate the form template you want.

2. Double-click the icon for that form template. The Automator window appears, showing the form template.
Note:
You can also drag a template icon from Windows Explorer and drop it into the HotDocs Automator window. The form
will then open for you to edit.

Copyright 2010 HotDocs Ltd. All rights reserved

577

Help Topics for HotDocs Developer 10

Add Pages to a Form Template

You can add pages to a form template. For example, say you need to add a page from one form template to the template
you are currently automating. When you insert a page, Automator copies the static content and fields, and then pastes
that information into the form template you're editing. The new page becomes part of the first template.
To insert pages from another template

1. Edit a form template. (See Edit a Form Template.)

2. Click

Insert Pages (Edit menu). The Insert Pages dialog box appears.

3. Click the Form containing pages to insert drop-down box and select the file from which you want to copy the
pages. You can also click the

Open button to locate another file and add it to the list.

Caution:
When inserting, file types must match, meaning you cannot insert pages from a PDF template into a HotDocs
form template.

4. In the Insert pages group, specify the pages you want to insert and where they should be inserted in the current
form.

5. Click OK. The template appears again, with the pages inserted.
Note:
If the pages you inserted contain variable fields, copy the components from the inserted template's component
file into the current file. (See Use Component Manager to Work with Components.)
To add pages to a form document during assembly, see Attach an INSERT Instruction to a Field.
To quickly navigate through inserted pages, click Thumbnails.

Copyright 2010 HotDocs Ltd. All rights reserved

578

Help Topics for HotDocs Developer 10

Remove Pages from a Form Template

At times you may want to delete a page from a form template.
To remove a page from a form

1. Edit the form template. (See Edit a Form Template.)

2. Choose Delete Pages (Edit menu). The Delete Pages dialog box appears.
3. Enter the range of page numbers you want to remove in the Delete and through boxes.
4. Click OK. The page(s) you specified are deleted.

Copyright 2010 HotDocs Ltd. All rights reserved

579

Help Topics for HotDocs Developer 10

Update the Underlying Text in a Form Template

Frequently, the courts or other agencies to whom you submit your form documents update the content of their forms,
which, in turn requires you to update the templates you are using. Rather than creating new templates and re-automating
them each time this happens, you can simply replace the text of the automated form with the updated content of the new
form. HotDocs Automator provides you the tools for doing this.
To replace the static content of a form template

1. Edit the form template. (See Edit a Form Template.)

2. Choose Replace Static Content (Edit menu). The Replace Static Content dialog box opens.
3. Either select the form with the correct static content from the Replace the static content... drop-down list, or click
the

Open button and locate the file you want.

4. Click OK at the Replace Static Content dialog box. You are returned to the template.
5. Reposition any fields, based on the updated static content. If the update significantly changed the form, check to
make sure the text still corresponds to the fields and variables. If any new questions are asked on the form, create
new fields and variables for them. (See Create a Form Field and Attach a Variable to a Field.)
Note:
If you are replacing static content in a fillable PDF template, it is recommended you check the fillable fields for
placement and formatting after replacing the content. See Detect Fillable Fields in a PDF Template for details.

Copyright 2010 HotDocs Ltd. All rights reserved

580

Help Topics for HotDocs Developer 10

View the Form in More than One Window

When you need to copy and paste fields, viewing the current form in multiple windows within Automatorcan be helpful.
Also, when you have several forms open at once, you can view all open windows simultaneously
To display the form in more than one window

1. Edit a form template. (See Edit a Form Template.)

2. Click the Window menu and make a selection, based on information in the following table:
To

Do This

Open an additional copy of Choose New Window.

the current form
Display all open forms
arranged from left to right

Choose Tile Vertical.

Display all open forms

arranged from top to
bottom

Choose Tile Horizontal.

Display all open forms so

they overlap from top-left
to bottom-right

Choose Cascade.

Copyright 2010 HotDocs Ltd. All rights reserved

581

Help Topics for HotDocs Developer 10

Globally Change Properties in a Template or Group of Templates

Caution:
Before making large-scale changes to templates or component files, you should back up these files. Additionally, if
you plan to use old versions of the templates, make copies before you use the Property Replicator feature. Unless you
have recovery options specified at the HotDocs Options dialog box (see Protect Forms By Backing Them Up), you
won't be able to retrieve the old copy. Another option is to have the template open when you apply a global change to
it; then you can save the new file, then click Undo (Edit menu) to restore the original version.
In major projects, you may want to quickly change the properties in several templates. Using the Property Replicator, you
can change the properties of regular fields, check-box fields, forms, or addenda propertiesor all fourfor the templates
you select. The changes will affect all the regular fields and check-box fields in all the selected templates.
There are two parts to making changes in multiple templates:
Create a source template that has the properties you want to apply to the other templates.
Apply the global changes using the Property Replicator feature.
To change properties in a set of templates

1. At the Automator window, click the

New Template button. A new, blank form template appears.

2. Create two fields and arrange them in this order:

A first field slightly larger than a regular edit field. (You also can copy a regular field and paste it into the new
template.)
A second field slightly larger than a check-box field. (You also can copy a check-box field and paste it into the
new template.)

3. Apply any changes to these fields that you want to be made globally. (You may want to make a note of exactly which
properties you changed. You will be asked in Step 9 to select these properties.)

4. Specify any template or addendum properties, again making note of any changes you make.
5. Click the

Save button, and name the source template.

Caution:
Make sure the check-box field you create is larger than the check boxes in the templates youre changing.
HotDocs applies check-box changes to only those fields that are equal in size to or smaller than the check box
you create. If the check boxes in the templates are larger than the one you create, HotDocs treats them as
regular fields.

6. In the source template, click Property Replicator (Tools menu). The Property Replicator dialog box appears.
7. In the Source template box, click the

Browse button to browse and select the source template. This file contains

the formatting you want to apply globally.

8. In the Destination templates box, click the

Browse button to browse and select the files.

Note:
You can also use wild cards to add templates. If you are changing all the files in a folder, you can use an asterisk
(*) when you type the file paths in the Files to change field. The asterisk replaces the individual file names, and
will add all files in a folder at once. For example, C:\Documents and Settings\UserName\My Documents\HotDocs
\Templates*.HFT would add all the form templates in the template folder, and C:\Documents and Settings
\UserName\My Documents\HotDocs\Templates*.* would add all the files in the template folder. To replace only
a single character in a file path, you can use a question mark (?). For example, C:\Documents and Settings
\UserName\My Documents\HotDocs\Templates*.HF? would add all the form templates and form documents.

9. Select the properties to be changed:

Copyright 2010 HotDocs Ltd. All rights reserved

582

Help Topics for HotDocs Developer 10

In the Regular fields list, select the properties of the edit field in the source template that you want to apply
globally to all fields in the destination templates.
In the Check boxes list, select the properties of the check-box field in the source template that you want to
apply globally to all fields in the destination templates.
In the Form list, select the properties of the form or addendum in the source template that you want to apply
globally to all destination templates.

10. After specifying the properties to be changed, click Replicate. The Replicate Properties dialog box appears,
showing which template files have been modified.

11. Click OK. The Property Replicator dialog box appears again. It notes the files that were processed and reports how
many files were changed.

12. Click Close.

Note:
You can use the Property Replicator to change the properties of linked fields in a fillable PDF template. Be aware,
however, that if you save the document assembled from this template as a fillable PDF, it will use the field properties
defined in the original fillable PDF. See Detect Fillable Fields in a PDF Template for details.

Copyright 2010 HotDocs Ltd. All rights reserved

583

Help Topics for HotDocs Developer 10

Save and Close a Form Template

As you automate a form template, you should periodically save your template. This protects your work from unexpected
program or system errors. Additionally, when you finish automating a template, you should save the template to disk and
close it.
To save and close a form template
Complete any of the steps in the following table:
To

Do This

Save changes to the

currently open template and
component file

Click the

Close the currently open

template

Click Close (File menu).

Close all open templates

Click Close All (File menu).

Save button.

Note:
You can have HotDocs automatically save back-up copies of form templates you are automating. See Protect Forms
By Backing Them Up for details.

Copyright 2010 HotDocs Ltd. All rights reserved

584

Help Topics for HotDocs Developer 10

Define the Interview for a Form Template

When users assemble form documents, they can provide the information in one of two ways: answering questions in an
interview or typing answers directly on the document (which is called direct-fill assembly).
All forms, when first automated, are set to allow only direct-fill assembly. However, you can allow interview-based
assembly by specifying an interview. The interview can be a default interview (one in which HotDocs determines the
order dialogs are asked in the template) or it can be a custom interview (one in which you specify the order dialogs and
variables are asked).
To allow only direct-fill assembly of a form

1. Edit the form template. (See Edit a Form Template.)

2. Open Component Manager for the template. Component Manager appears. (See Open and Close Component
Manager.)

3. Click the

Component File Properties button. The Component File Properties dialog box appears.

4. Click the Interview tab. The view changes to show interview options.
5. Clear both the Generate default interview and the Use custom interview options.
To define an interview for the form
See Define a Custom Interview or Have HotDocs Generate a Default Interview, depending on your preferences.
1

HotDocs supports the creation of templates using fillable PDFs. For details, see Overview: Use Fillable PDFs as Form
Templates.

Copyright 2010 HotDocs Ltd. All rights reserved

585

Help Topics for HotDocs Developer 10

Chapter 39: Creating Form Fields

Create a Form Field
Before You Begin:
These instructions can also be used to create a form field at both the Form Document tab of the assembly window
and in HotDocs Filler.
The first step in automating a form template is creating HotDocs fields at each place on the form where a user's
information must be merged.
When you create a field, HotDocs determines the type of field you are creating based on the size of the fieldif a field is
smaller than a certain dimension, HotDocs creates a check-box field. If a field is larger, then it creates an edit field. (You
can define these dimensions at HotDocs Options. See Set Properties for New Edit Fields.) Additionally, once you create
the field, you can make it a Resource hyperlink or a Control field.
Sometimes when you create a field, HotDocs can detect the borders of the underlying form and adjust its size to fit within
those borders. This helps ensure the field fits best in the space allotted. See Detect Borders to Create or Resize a Field.
Once a field is created, you can attach a variable to it.
Note:
Please see Detect Fillable Fields in a PDF Template for information on working with fields in a template created from a
fillable PDF.
To create a form field

1. Edit a form template. (See Edit a Form Template.)

2. Click the

Select Tool button.

3. Position the mouse pointer at one end of the intended field.

4. Press and hold down the left mouse button, then drag the pointer to the opposite corner of the field.
5. Release the mouse pointer. The field is created.
6. Optionally, click Detect to have HotDocs adjust the size of the field to more closely match the underlying static line
or lines.

7. Optionally, you can customize the appearance of your fields in the following ways:
Attach a variable to the field. (See Attach a Variable to a Field.)
Change the field type. (See Change the Field Type.)
Adjust the size. (See Resize Form Fields.)
Change the field's position on the form. (See Move a Field on a Form.)
Make a field conditional so the variable is asked only if a condition is true. (See Make a Field Conditional.)
Note:
To move multiple fields once they have been created, select the fields and press the arrow key that indicates
which direction you want to move them. To move fields more quickly, press the Shift key while pressing the
arrow keys.
You can also create a standard-size field by double-clicking on the form. Or, you can click to set the field crosshair and press F8.

Copyright 2010 HotDocs Ltd. All rights reserved

586

Help Topics for HotDocs Developer 10

Select a Field
Before You Begin:
These instructions can also be used to select fields both at the Form Document tab of the assembly window and in
HotDocs Filler.
In order to work with a field, you must first select it. When you select a field, handles appear on the field borders showing
that you can edit the borders or other properties. You can select a single field to work with, or you can select multiple
fields to group them or to make the same change to all of the fields.
To select fields

1. Edit a form template. (See Edit a Form Template.)

2. Click the

Select Tool button

3. Click on the field you want to work with.

4. Optionally, to select multiple fields, either press the Ctrl key while clicking each field, or press the Shift key, then
press the mouse button and drag the mouse pointer to create a bounding frame. All fields included in or touched by
this frame will be selected.

5. Use any of the following additional methods for selecting fields or canceling the selection, as described in the
following table:
To

Do This

Select all the fields on the

current page

Click Select All (Edit menu). (You can also press Ctrl+A.)

Cancel the selection of all

selected fields

Click outside the fields, or press the Esc key.

Cancel the selection of

only one of a group of
selected fields

Hold down the Ctrl key and click that field.

Add fields to your group

of selected fields without
canceling the selection of
those already selected

Hold down the Ctrl key and click the new fields.

Note:
If you have trouble selecting the field you want, the field may be in a group. If this is the case, you must first
ungroup the fields by clicking Ungroup (Field menu). (See Ungroup Form Fields.)
Click the

Show Fields button to show and hide field colors.

Copyright 2010 HotDocs Ltd. All rights reserved

587

Help Topics for HotDocs Developer 10

Create a Check-Box Field

Before You Begin:
These instructions can also be used to create check-box fields at the Form Document tab of the assembly window
and in HotDocs Filler.
Some forms include check boxes for users to mark. Check boxes can represent either true/false (or yes/no) options, but
they can also represent several predefined options for users. By default, HotDocs merges an X in a check box to indicate
that it has been selected, but you can define a different check-box character.
Note:
Please see Detect Fillable Fields in a PDF Template for information on working with fields in a template created from a
fillable PDF.
To create a check-box field

1. Edit a form template. (See Edit a Form Template.)

2. Where the check box appears on the form, double-click within the field borders, or click the

Detect Field button. A

check-box field is created.

3. Attach a variable to the field. Your options include True/False and Multiple Choice.
Note:
When assigning a True/False variable, if you want to merge a character other than an X, indicate the character
by specifying it as a variable format. See Customize a True/False Variable for details. To change the font for the
field, see Set Properties for New Check-Box Fields. When assigning a Multiple Choice variable, you should group
the fields before attaching the variable. See Group Form Fields So Answers Can Flow From One Field to Another
for details.

4. Optionally, specify a condition to make the field dependant on other answers in the form. (See Make a Field
Conditional.)
Note:
You can change the default measurements used to identify new fields as check boxes. You can also specify a
default character other than X to be used when selecting check-box fields. (See Set Properties for New CheckBox Fields.)
If HotDocs creates an Edit field, rather than a Check-box field, select the field, click the
button, and choose Check box as the Field type.

Copyright 2010 HotDocs Ltd. All rights reserved

Field Properties

588

Help Topics for HotDocs Developer 10

Attach a Variable to a Field

Once you create fields on the form template, you can assign variables to them. Variables help control the type of answer
the user enters (for example, a Text variable lets the user enter text, while a Date variable requires the user to enter a
valid date). See Overview: Create and Customize Variables.
To attach variables to fields

1. Edit a form template. (See Edit a Form Template.)

2. Create the field to which you want to attach the variable. (See Create a Form Field.)
3. Select the field and click the

Variable Field button in the Automator toolbar. The Variable Field dialog box

appears.

4. Create a new variable or select an existing variable. Your options include Text, Date, Number, True/False, Multiple
Choice, and Computation.
Note:
To attach variables to fields using a wizard-like approach, choose Create Variables (Tools menu). HotDocs
scans through the template, looking for fields that do not yet have an assigned variable. On a field-by-field basis,
it then displays the Variable Field dialog box, allowing you to create variables for each field. For instructions on
using this tool for linked fields in a fillable PDF template, see Attach Variables to Fillable Fields.
Other methods for attaching variables to fields include double-clicking on the field to display the Variable Field
dialog box, dragging variables from Component Manager to the fields in the template, and viewing the Field
Properties dialog box for the field and assigning the variable there.
To attach a single variable to multiple fields, for example, to create a run-on group, select and group all of the
fields before you click the
Field to Another.)

Variable Field button. (See Group Form Fields So Answers Can Flow From One

Copyright 2010 HotDocs Ltd. All rights reserved

589

Help Topics for HotDocs Developer 10

Attach an ASK Instruction to a Field

When HotDocs asks the questions in a form template interview, it asks the variables (in their associated dialogs) in the
order it encounters the variable fields on the formstarting from the top-left section of the template and processing to
bottom-right. At times, you may find that you want greater control over the order these dialogs are asked. To control this
order, you can insert an ASK field in the template. For example, if you want to gather attorney information first in the
interview, but the variables that ask the questions are located at the end of the template, you can insert an ASK instruction
for the Attorney Information near the beginning of the template.
To cause a dialog to be asked a certain place in the form interview

1. Edit a form template. (See Edit a Form Template.)

2. At the place in the form where you want the dialog to be asked, create a field. (See Create a Form Field.)
3. With the field selected, choose ASK (Field menu). The ASK Field dialog box appears.
4. Enter the name of the dialog you want to be asked in the Dialog box and click OK. (See Gather Questions into a
Custom Dialog.)

5. Optionally, change the field type to Control to keep users from typing in the field during direct-fill assembly. (See
Change the Field Type.)
Note:
To attach more than one ASK instruction to a field, group the ASK instructions in a Computation variable script, and
then attach the variable to the field. (See Put ASK Instructions in a Computation Variable.)

Copyright 2010 HotDocs Ltd. All rights reserved

590

Help Topics for HotDocs Developer 10

Make a Field Conditional

Some fields on a form should be answered only under certain conditions. For example, say you have a series of options
(designated by check box fields). Each check box field is followed by an edit field where users can enter explanations for
their selection. To keep users from entering an explanation without first selecting the corresponding option, you can attach
a condition (or IF instruction or expression) to the explanation field that disables it until the user first selects the check box.
For more information on using IF instructions and expressions, please see Include or Exclude a Single Version of Text
Using a Simple IF Instruction or Expression and Include or Exclude Multiple Versions of Text Using IF and ELSE IF
Instructions or Expressions.
To make a field conditional upon other answers

1. Edit a form template. (See Edit a Form Template.)

2. Select the field you want to make conditional. (See Select a Field.)
3. Click the

Field Properties button. The Field Properties dialog box appears.

4. At the Type tab, click

IF Field button. The IF Field dialog box appears.

5. Select IF True/False Variable or IF Expression depending on how complex the condition needs to be. The dialog
box changes to show the necessary options.
For a simple IF instruction, type a name for a new True/False variable, or select an existing one.
For expressions, drag expressions and variables into the Expression box.
When a user assembles a document using this template, the fields you are conditioning will be asked only if the True/
False variable or expression is true.

Copyright 2010 HotDocs Ltd. All rights reserved

591

Help Topics for HotDocs Developer 10

Attach an INSERT Instruction to a Field

When assembling form documents, you may need to attach another form to the current one. You can do this by using an
INSERT instruction.
When an INSERT instruction is used in a form template, the questions from the inserted template are asked in the same
interview as the parent template, but HotDocs appends the inserted document to the end of the parent document. (This
is different from text templates where an INSERT instruction merges the text of an inserted document at the point of
insertion in the parent document.) When inserting templates, file types must matchfor example, you cannot insert a PDF
template in a HotDocs form template, nor can you insert text templates in form templates.
To insert one form template into another

1. Edit a form template. (See Edit a Form Template.)

2. Create a new field. (See Create a Form Field.)
3. With the new field still selected, choose INSERT (Field menu). The INSERT Field dialog box appears.
4. Click the

Open button and select the form template file to insert.

5. Click OK. The INSERT Field dialog box appears again, showing the name of the inserted template in the Template
to insert box.

6. Click OK. The INSERT instruction is attached to the field.

7. Optionally, make the field a control field so the user won't see it during direct-fill assembly. (See Change the Field
Type.)

8. Optionally, make the field conditioned on other answers in the interview. (See Make a Field Conditional.)
Note:
If you need to add content from one template to another, use the Insert Pages command. See Add Pages to a Form
Template.

Copyright 2010 HotDocs Ltd. All rights reserved

592

Help Topics for HotDocs Developer 10

Detect Borders to Create or Resize a Field

Before You Begin:
These instructions can also be used to detect field borders both at the Form Document tab of the assembly window
and in HotDocs Filler.
When you create fields on a form, you often use the underlying static text as a guide as to where the field should be
placed. Often, you want the borders of the fields to match the borders of the static text. To help you align these borders,
you can use the
Detect feature. This feature is useful both when you create a new field and when you need to resize a
field to fit within its allotted space.
If HotDocs is unable to automatically create or resize a field to the size and position you want, you must create the field
manually. Several factors may contribute to these difficulties:
Insufficient surrounding features: To detect a field, HotDocs searches for surrounding features, such as lines,
text, or graphics. If there are insufficient surrounding features, HotDocs may have difficulty detecting a field. In such
cases, HotDocs creates a field of the default size.
Label text: When label text is inside the field area and there is enough space between the text and the bottom of
the field area, the
Detect command will extend the field up to the bottom of the label text. If you want the field to
occupy the area to the left or right of the label, or if you want to include the label inside the field, you must create the
field manually.
Field not completely visible: If part of the intended field is not visible (for example, it's scrolled out of the window),
HotDocs attempts to scroll to detect the field. It is recommended that you use a zoom level such as
Width so HotDocs can find the entire field on the screen.

Fit Page to

To detect the borders of the underlying static text

1. Edit a form template. (See Edit a Form Template.)

2. On the form, complete one of the following steps:
If the field is already created, select the field and click the

Detect button.

If you are creating a new field, place your cursor where the new field should be created and click the
button.

Detect

Caution:
If you are working with linked fields in a fillable PDF template and you plan to save the document assembled from the
template as a fillable PDF, any changes you make to the linked field will not be honored in the saved fillable PDF. See
Detect Fillable Fields in a PDF Template for details.

Copyright 2010 HotDocs Ltd. All rights reserved

593

Help Topics for HotDocs Developer 10

Move a Field on a Form

Before You Begin:
These instructions can also be used to move fields both at the Form Document tab of the assembly window and in
HotDocs Filler.
As you create fields on a form, you will frequently need to move the fields. You can do this using the mouse or keyboard.
You can also specify a precise location using the Field Properties dialog box.
To move a field using the mouse

1. Edit a form template. (See Edit a Form Template.)

2. Position the mouse pointer over the selected field. The cursor changes.
3. Hold down the mouse button and drag the field to the new position.
To move a field using the keyboard

1. Edit a form template. (See Edit a Form Template.)

2. Select a field. (See Select a Field.)
3. Press the arrow keys to move the field one unit of measurement in that direction. (To move the field more quickly,
hold down the Shift key as you press the arrow keys.)
To move a field using the Position/Size dialog box

1. Edit a form template. (See Edit a Form Template.) Edit a form document. (See Edit a Saved Form Document.)
2. Select a field. (See Select a Field.)
3. Click the

Field Properties button. The Field Properties dialog box appears.

4. Click the Additional tab. The view changes to show the positioning options.
5. In the Position group, enter the desired distance from the left and top margins of the page in the Left and Top
boxes. (You can also click the up or down arrows for each field to change the distance.)
Note:
If you are working with linked fields in a fillable PDF template and you plan to save the document assembled from
the template as a fillable PDF, any changes you make to the linked field will not be honored in the saved fillable
PDF. See Detect Fillable Fields in a PDF Template for details.
If a field you want to move is part of a group, you must first ungroup the fields. (See Ungroup Form Fields.)
The Field Properties dialog box includes the First, Previous, Next, and Last buttons to move you between
fields. When you have multiple fields selected, these buttons are not available.

Copyright 2010 HotDocs Ltd. All rights reserved

594

Help Topics for HotDocs Developer 10

Align Two or More Fields

When creating fields on a form template, you frequently need to align fields, either vertically or horizontally. Other times,
you may need to adjust the height or width of a group of fields so they match each other. Aligning fields can give forms
a more professional appearance, as well as minimize problems the user may experience when tabbing between fields
during direct-fill assembly.
To align fields in relation to each other

1. Edit a form template. (See Edit a Form Template.)

2. Select the fields you want to align. (See Select a Field.)
3. Click the

Align button. The Align Fields dialog box appears. (You can also right-click and choose Align from the
shortcut menu.)

4. Select an option in the Horizontal alignment group to align the fields horizontally, or the Vertical alignment group to
align the fields vertically. The Example box previews the selected alignment option.

5. Click OK. The template appears again, and the selected fields are repositioned.
To size fields in relation to each other

1. Edit a form template. (See Edit a Form Template.)

2. Select the fields you want to size. (See Select a Field.)
3. Click the

Align button. The Align Fields dialog box appears. (You can also right-click and choose Align from the
shortcut menu.)

4. Select the options you need from the Width group and/or the Height group. The Example box previews the
selected resizing options.

5. Click OK. The template appears again, and the selected fields are resized.
Caution:
If you are working with linked fields in a fillable PDF template and you plan to save the document assembled from the
template as a fillable PDF, any changes you make to the linked field will not be honored in the saved fillable PDF. See
Detect Fillable Fields in a PDF Template for details.

Copyright 2010 HotDocs Ltd. All rights reserved

595

Help Topics for HotDocs Developer 10

Change the Borders and Margins of a Field

Before You Begin:
These instructions can also be used to change the borders and margins of fields both at the Form Document tab of
the assembly window and in HotDocs Filler.
You can change the borders and margins of a form template field. Borders control the thickness of the field box, and
margins control the distance between the border of the field and the answer text.
To change field borders or margins

1. Edit a form template. (See Edit a Form Template.)

2. Select the field whose borders or margins you want to change.
3. Click the

Field Properties button. The Field Properties dialog box appears.

4. Click the Layout tab. The view changes to show layout options.
5. In the Borders and Margins groupings, make your selections. (Remember, borders affect the thickness of field
boxes, while margins affect the distance between the border of the field and the answer in the field.)
Caution:
If you are working with linked fields in a fillable PDF template and you plan to save the document assembled from the
template as a fillable PDF, any changes you make to the linked field will not be honored in the saved fillable PDF. See
Detect Fillable Fields in a PDF Template for details.

Copyright 2010 HotDocs Ltd. All rights reserved

596

Help Topics for HotDocs Developer 10

Copy One or More Form Fields

Before You Begin:
These instructions can also be used to copy and paste fields both at the Form Document tab of the assembly window
and in HotDocs Filler.
Frequently, you need to copy fields on a form. For example, say you need to create a group of fields that all have the
same properties. Rather than creating each field individually and modifying its properties, you can create a single field,
assign the properties, and then copy the field to create the others in the group.
When a field is copied to a new place in the same template, all the fields properties (size, font, line formatting, fill order,
etc.) are copied with it. Similarly, when variables, conditions, or REPEAT instructions are attached to fields, they are also
attached to the copied fields. However, if you copy fields from one template to another, the variables, dialogs, and other
components used in computations, conditions, or instructions are not copied to the new templates component file. You
must copy these items manually. (See Create and Edit Multiple Components Simultaneously or Use One Component File
for Multiple Templates.)
When you copy fields to a new location, the cursor position tells HotDocs where to paste the copied fields. If you copy a
single field, the lower-left corner of the field will be at the cursor position. Likewise, if you copy two or more fields at the
same time, the lower-left corner of an invisible boundary box drawn around all of the copied fields will be at the cursor
position. If there is no cursor, the field is pasted on top of the original.
You can copy fields on only one page at a time.
To copy and paste one or more fields

1. Edit a form template. (See Edit a Form Template.) Edit a form document. (See Edit a Saved Form Document.)
2. Select the field or fields you want to copy. (See Select a Field.)
3. Choose Copy (Edit menu). The field is copied to the Windows Clipboard. (You can also select the field and press
Ctrl+C, or you can right-click on the field and choose Copy from the shortcut menu.)

4. Place the mouse cursor where you want the lower-left corner of the copied field to be, and then click the mouse to
set the cross-hair.

5. Choose Paste (Edit menu). The copied field is pasted at that location. (You can also press Ctrl+V, or you can rightclick on the field and choose Paste from the shortcut menu.)
Note:
You can also copy a field by holding down the Ctrl key while dragging the field to its new location.
If you need to automate an updated version of the template, it may be easier to replace the static content, rather
than copy all of the fields. (See Update the Underlying Text in a Form Template.)
Note:
You can also copy a field by holding down the Ctrl key while dragging the field to its new location.
Caution:
If you are working in a fillable PDF template, remember that linked fields are associated with underlying fillable fields in
the PDF. If you plan to save the assembled document as a fillable PDF, answers associated with linked fields will only
be merged where there are fillable fields on the form. This means that you cannot copy a linked field to a new location
on the form and expect the answer to appear there in the resulting fillable PDF. If you want to use the same variable
somewhere else in the form, create a regular HotDocs field and assign it the same variable name as the fillable field.
Note, however, that in the fillable PDF, the answer will appear static.

Copyright 2010 HotDocs Ltd. All rights reserved

597

Help Topics for HotDocs Developer 10

Resize Form Fields

Before You Begin:
These instructions can also be used to resize fields both at the Form Document tab of the assembly window and in
HotDocs Filler.
You may need to adjust the size of a field to fit it into the available space on the form. You can change a field's size using
the mouse, the keyboard, or the Position/Size tab of the Field Properties dialog box.
To resize a field using a mouse

1. Edit a form template. (See Edit a Form Template.)

2. Select the field. (See Select a Field.)
3. Click a handle or field border. (When the mouse pointer is on a handle, the pointer changes to a double-arrow,
indicating the directions the border can be moved.)

4. Hold down the mouse button and drag the border to a new position.
To resize a field using the keyboard

1. Edit a form template. (See Edit a Form Template.)

2. Select the field. (See Select a Field.)
3. Press the Page Up or Page Down keys to move the top border of the field up or down, and the End or Home keys
to move the right border of the field right or left. (To resize the field more quickly, hold down the Shift key as you
press the keys.)
To resize a field using the Field Properties dialog box

1. Edit a form template. (See Edit a Form Template.)

2. Select the field. (See Select a Field.)
3. Click the

Field Properties button. The Field Properties dialog box appears.

4. Click the Additional tab and, in the Size group, enter the desired distance from the left and top borders of the field
in the Width or Height boxes. (You can also click the up or down arrows for each field to change the size.) The field
size is changed.
Caution:
If you are working with linked fields in a fillable PDF template and you plan to save the document assembled from the
template as a fillable PDF, any changes you make to the linked field will not be honored in the saved fillable PDF. See
Detect Fillable Fields in a PDF Template for details.

Copyright 2010 HotDocs Ltd. All rights reserved

598

Help Topics for HotDocs Developer 10

Change the Tab Order of Fields

Before You Begin:
These instructions can also be used to change the tab order of fields both at the Form Document tab of the assembly
window and in HotDocs Filler.
When determining the order to ask questions in the interview, HotDocs begins with the top-left field of the form and
processes all of the fields until it reaches the bottom-right field. This processing affects two thingsthe order questions
are asked in the default interview and the order in which the user is able to tab through fields on the form.
Because of this default field ordering, sometimes you may find your dialogs being asked out of order. You may also find
that the tab order during direct-fill assembly isn't working as you expect. Additionally, when automating a nontypical table,
you may need to change the order in which fields are asked.
Note:
Once you specify a fill order for one field, you must specify the order for every field you want processed after that
field. In effect, when you specify a fill order for just one field, you set that field to be answered last. This is because
all the other fields are still set to Row 0, Column 0they are lower than the Row 1 or Column 1 , so they will be filled
first. Therefore, to change the order of the fields in the middle of the form, you must also change the order for every
remaining field.
The following rules control field ordering:
Fill order is determined first by row, then by column.
All field values are initially set the sameRow 0, Column 0.
When fields have different row numbers, fields with lower row numbers are asked first, for example, Row 0, Column
0; Row 1, Column 0; etc.
When fields have the same row numbers, but different column numbers, fields with lower column numbers are asked
first, for example, Row 1, Column 0; Row 1, Column 1; etc.
Fill order is treated separately for each page of the templateyou cannot specify a fill order that runs from one page
to another.
To change the tab order for fields

1. Edit a form template. (See Edit a Form Template.)

2. Select the field. (See Select a Field.)
3. Click the

Field Properties button. The Field Properties dialog box appears.

4. Click the Additional tab. The view changes to show ordering options.
5. In the Row box, type the row number.
6. If you need to specify the order for fields in the same row, type a number in the Column box.
7. Optionally, at the Order dialog box, you can click the First, Previous, Next, or Last button to save the current field's
settings and display the next field's order.
By selecting and ordering different groups of fields, you can use fill order to handle various situations. For example:
Remove all fill order settings: Select all fields and set the Row and Column numbers to 0.
Organize large sections of fields: Select the desired fields and specify the order.
Flow answers across fields contrary to the default order (top to bottom, left to right): Set the desired order,
then group the fields. (See Group Form Fields So Answers Can Flow From One Field to Another.)
Fill table columns in an order different from the static text: Set the desired order, then group the fields as a
table.
Copyright 2010 HotDocs Ltd. All rights reserved

599

Help Topics for HotDocs Developer 10

Note:
To control when a variable is asked without changing fill order, you can use ASK instructions. For example, if you
simply want a particular field to be asked first even though it isn't the first field on the form, place an ASK instruction in
the top left corner of the page. (See Attach an ASK Instruction to a Field.)

Copyright 2010 HotDocs Ltd. All rights reserved

600

Help Topics for HotDocs Developer 10

Group Form Fields So Answers Can Flow From One Field to Another
Before You Begin:
These instructions can also be used to group fields for answer flow-through both at the Form Document tab of the
assembly window and in HotDocs Filler.
Sometimes an answer must begin in one field and continue in other fields. For example, you may have a Text variable
whose answer must span two or more pre-printed lines. You can create edit fields for each line, and then group the fields
so that answers flow from one field to another. Fields grouped this way are called run-on groups.
Once fields are grouped, HotDocs treats the group as a single field. This means that the Text variable and any conditions
for the variable will be assigned to the grouping, not the individual fields in the group.
Caution:
If you are automating a fillable PDF template and you plan to save the assembled document as a fillable PDF, you
cannot group fillable fields since necessarily, each fillable field is linked to a separate variable. Answersboth in
HotDocs and Adobemust be entered on individual lines. This means that when you reach the end of one field, you
must tab to the next field and continue typing your answer. (This inability to group fields is a limitation of Adobe. If you
have access to the form, you may consider replacing individual fields in the group with a single, multi-line field. Text
you enter may not match the lines perfectly, but you will not have to tab between fields to enter the answer.)
To flow an answer across multiple fields

1. Edit a form template. (See Edit a Form Template.)

2. Create all the text fields across which the answer should flow. (See Create a Form Field.)
3. Select all the fields that will be used for the answer. (See Select a Field.)
4. Click Group (Field menu). A bounding frame appears around the grouped fields. (You can also right-click and select
Group from the shortcut menu.)

5. Attach a variable to the grouped fields. (See Attach a Variable to a Field.)

Caution:
When fields are grouped, you cannot change properties for individual fields. You must first ungroup the fields. (See
Ungroup Form Fields.)
Note:
A form may require an answer to appear in a series of single-character fields or boxes (for example, a Social
Security number). To place one character or digit in each field requires additional formatting. See Attach a
Variable to Single-Character Boxes for details.
To group fields that appear on separate pages in the form, see Flow a Single Answer Across Two or More Pages
in a Form.
By default, HotDocs asks questions in the interview by reading fields in the form from left to right, top to bottom.
As it encounters a field, it asks the variable associated with it. If the variable is linked to a dialog, it asks the dialog
instead. When directly filling the form, HotDocs tabs through the form fields using this same method. However,
sometimes grouped run-on fields can create problems with the tab order. To ensure that text in a run-on group
flows in the correct order, you may need to specify a fill order for fields in the group. (See Change the Tab Order
of Fields.)

Copyright 2010 HotDocs Ltd. All rights reserved

601

Help Topics for HotDocs Developer 10

Attach a Variable to Single-Character Boxes

Sometimes an answer field is made up of several single-character boxes. Rather than create a single field that spans
these boxes, you can create individual fields in each box. Then, once you group the fields, you can assign a variable to
the grouped field and the answer the user enters will be split across the fieldsone character in each box.
For example, perhaps you have a field on your form that requires the user to enter the digits in a U.S. Social Security
number. If you just simply group the fields, HotDocs attempts to fit the entire answer in the first few boxes, like this:

When this happens, the answer will overflow and be sent to the addendum. However, if you group the fields and assign a
maximum character number of one to the group, only one character will be merged in each box, like this:

To split an answer across multiple single-character boxes

1. Edit a form template. (See Edit a Form Template.)

2. Create and select the appropriate fields. (See Create a Form Field and Select a Field.)
3. Choose Group (Field menu). A bounding box appears around the grouped fields. (See Group Form Fields So
Answers Can Flow From One Field to Another.)

4. Attach a variable to the group. (See Attach a Variable to a Field.)

5. Select the grouped field and click the

Field Properties button. The Field Properties dialog box appears.

6. Click the Layout tab. The view changes to show several alignment options.
7. In the Line Format group, enter 1 in both the Maximum lines and the Max chars/line boxes.
When a user answers the variable, each character of the answer will be merged in its own field.
Note:
Sometimes the preprinted boxes have space for only the variable characters, not for static characters (such as
the hyphens in a Social Security number, or the slash marks in date formats like MM/DD/YYYY). However, these
characters normally merge as part of the answer. This would make the answer too long, again causing it to overflow.
In such situations, you must specify an example format that prevents the static characters from being merged. If the
answer is for a Text variable, specify a pattern (see Use Pattern Codes to Create a Custom Pattern) and then use
an example format that uses an X for every character you want and an underscore for every character you want
suppressed (for example, XXX_XX_XXXX to remove hyphens from a Social Security number). For a Date variable,
create a format that eliminates the characters you don't want (for example, 061390).

Copyright 2010 HotDocs Ltd. All rights reserved

602

Help Topics for HotDocs Developer 10

Attach a Multiple Choice Variable to a Group of Check Boxes

Frequently, a form template includes several options from which a user can choose. These options are usually
represented by check boxes. In order to assign a Multiple Choice variable to these fields, you must first group the fields
and then attach the Multiple Choice variable to the grouped field. Additionally, the fields in the group must match the
order of the options in the variable. During the interview, when the user selects an option, the corresponding check box is
selected.
Caution:
If you are working with fields in a fillable PDF template, you can only group linked check box fields if each of the field's
corresponding fillable field has the same name. To view a linked field's name, select the field and click the
Field
Properties button, and then click the Additional tab. The Field name drop-down list shows the associated name.
To assign a Multiple Choice variable to check boxes

1. Edit a form template. (See Edit a Form Template.)

2. Create the check-box fields. (See Create a Check-Box Field.)
3. Select the fields you want grouped. (See Select a Field.)
4. Choose Group (Field menu). The fields are grouped (as indicated by a bounding outline).
5. Double-click on the group. The Variable Field dialog box appears.
6. Assign a Multiple Choice variable, making sure the options for the variable correspond with the fill order of the check
boxes. (If you need to assign a tab order to the fields, see Change the Tab Order of Fields.)
Note:
Sometimes the wrong box gets checked in the assembled form. If this happens, make sure the options are listed
in the Multiple Choice Variable Editor in the same order as the fields' tab order. By default, HotDocs fills fields
from top-left to bottom-right. If you want the fields processed in a different order, you can ungroup them and
change the field order.
The default fill character for check boxes is an X. To merge a different character, enter the character in the Merge
Text column for each multiple-choice option.

Copyright 2010 HotDocs Ltd. All rights reserved

603

Help Topics for HotDocs Developer 10

Ungroup Form Fields

Before You Begin:
These instructions can also be used to ungroup fields both at the Form Document tab of the assembly window and in
HotDocs Filler.
When fields are grouped, you cannot modify the individual fields. You must first ungroup the fields.
To ungroup the fields

1. Edit a form template. (See Edit a Form Template.)

2. Select one of the grouped fields. The whole group is selected. (See Select a Field.)
3. Click Ungroup (Field menu). (You can also right-click on the field and choose Ungroup from the shortcut menu.)
Some properties that were assigned to the group, such as text, margin, and line format properties remain applied to the
individual fields that made up the group. Other properties, such as a field order or a condition, are lost until you regroup
the fields. Regrouping the fields restores the properties that were previously applied to the group.
Caution:
Properties of a table, including the name of the repeated dialog, are attached to the first field in a table. Because of
this, you should not delete the first field in the group before you regroup the fields. Also, do not close the form before
you regroup the fields. If you do either of these things, these properties are lost.

Copyright 2010 HotDocs Ltd. All rights reserved

604

Help Topics for HotDocs Developer 10

Attach an Answer Wizard to a Field

When a user direct-fills a form document, he or she answers questions by clicking on the field and entering the answer
in the field. Sometimes, however, the user may not be able to enter an answer in the field, either because the field
requires other variables be answered to calculate its answer, or because it's conditioned on another field's answer in
the document. To help users answer the questions necessary to fill in the field, you can assign an answer wizard to the
field. An answer wizard attaches a button to the field that, when clicked, displays a pop-up interview asking the required
questions.
For example, say you create a field that merges a user's age. To merge this answer, you attach a Computation variable
that calculates the age based on the user's birth date and today's date. You can attach an answer wizard that asks the
dialog that contains the birth date variable. Once the user answers the date, the answer is calculated and merged in the
field.
Answer wizards are most often used with computation fields, conditional fields, or fields grouped as a table.
To create an answer wizard for a variable

1. Edit a form template. (See Edit a Form Template.)

2. Select the field to which you want to attach the answer wizard, then click the

Field Properties button. The Field

Properties dialog box appears. (You can also right-click and select Field Properties from the shortcut menu.)

3. At the Type tab, click the

Wizard button. The Answer Wizard Field dialog box appears.

4. Select the answer wizard option you want to use:

Computation Variable: Select an existing Computation variable from the Computation drop-down list, or
click the

Edit Component button to create a new one. During direct-fill assembly, when users click the

Answer Wizard button, the variables used in the Computation are displayed in the pop-up interview. (If the
variables are linked to a dialog, the dialog appears in the pop-up interview.)
ASK Instruction: Select an existing dialog from the drop-down list, or click the
create a new one. During direct-fill assembly, when users click the
dialog is displayed in the pop-up interview.
DEFAULT: When users click the
asked.

Edit Component button and

Answer Wizard button, the specified

Answer Wizard button, any dialogs containing the required variables are

NONE: Removes any answer wizards attached to the selected field (or group of fields).
Note:
You can also create a wizard for a table. A table wizard appears as a spreadsheet button (
wizard button (

) instead of as an answer

), and clicking it will display the repeated dialog in a pop-up interview. To create a table wizard,

select the table, click the

Field Properties button, and create the wizard. You can still create an answer wizard for
a field in a table by specifying the answer wizard before you group the fields in the table.

Copyright 2010 HotDocs Ltd. All rights reserved

605

Help Topics for HotDocs Developer 10

Chapter 40: Changing Field Properties

Preview the Formatting of Answers in a Form Field
As you create fields in a form template, you frequently want to see how an answer will appear in a field. For example, say
you create a multi-line field and you want to test whether a three-line address will fit. As you edit the field properties, you
can enter a test answer and see how the answer fits in the underlying form field.
Caution:
To test the assembly of the documentincluding how answers are merged in fields based on the underlying variables
click the

Test Assemble button.

To enter test answers in a field

1. Edit a form template. (See Edit a Form Template.)

2. Create a new field or select an existing field. (See Create a Form Field and Select a Field.)
3. Click the

Show Variables button to hide variable names. (See Show and Hide Fields.)

4. Click the

Field Properties button. The Field Properties dialog box appears.

5. Change the different properties for the field at the Type tab as necessary.
6. In the text box at bottom of the dialog, enter the text you want to view in the answer field, depending on the field
type.

7. Optionally, click the Layout tab of the Field Properties dialog box and make any changes to the field's alignment,
borders, margins, and multi-line format.

8. When you're finished entering the text, click outside of the text box. The field in the underlying form updates to show
the text you entered.

Copyright 2010 HotDocs Ltd. All rights reserved

606

Help Topics for HotDocs Developer 10

Show and Hide Fields

As you are viewing a form, field variables and backgrounds are shown by default. You can hide variable names and field
backgrounds, though, which may make it easier for you to scan through the form. When backgrounds are hidden, only the
variable name or answer appears. When variables are hidden, only the test answer text appears (if any is assigned to the
field).
To hide or show field backgrounds

1. Edit a form template. (See Edit a Form Template.)

2. Click the

Highlight Fields button.

To hide or show variable names

1. Edit a form template. (See Edit a Form Template.)

2. Click the

Show Variables button.

Note:
You can control whether field variables and field backgrounds are shown or hidden when you open form templates
documents. See Control How Forms Appear When Opened for details.

Copyright 2010 HotDocs Ltd. All rights reserved

607

Help Topics for HotDocs Developer 10

Change the Field Type

Before You Begin:
These instructions can also be used to change the field's type at the Form Document tab of the assembly window and
in HotDocs Filler.
When you first create a field, HotDocs creates it as either an edit or check-box field, depending on the fields height and
width. Check-box fields are usually used to mark a yes/no response, while edit fields are used for questions that require
text, date, or number answers. In addition, you can assign some fields as control fields, which means users can't access
or edit the field during direct-fill assembly. You can also create resource fields, which can display helpful information about
the form.
Once you choose a field type, you can determine the type of answer that is merged in the field. Your options include text,
graphics, and bar codes. You can also use fields to cross out or circle static text on a document.
The following are the different types of fields you can create:
Type of Field

Default Color

Description

Edit

Yellow

Allows users to enter any type of answer,

including text, dates, numbers, multiple
choice options, or computed values. It is
the most commonly used field type.

Check Box

Blue

Allows users to select from two or more

options. Usually check-box fields are
associated with True/False variables or
Multiple Choice variables. Answers in a
check-box field are usually indicated by an
X or other character. (See Create a CheckBox Field.)

Resource

Orange

Allows users to view helpful information

about the form while directly filling the
form. Resource fields appear as hyperlinks
on the form. When users click the link,
a pop-up window containing the useful
information opens. (See Create a Resource
Link on a Form.)
Note:
Resource fields provide help for the
form in general, instead of for a specific
variable or dialog.

Control

Green

Allows you to complete "behind-thescenes" tasks in the template, such as

inserting templates or setting the values
of variables. If the field contains answer or
example text, it will be visible to users, but
users won't be able to access the field.

Note:
If you are working with a fillable PDF template, linked fields appear using a light blue color. This distinguishes them
from regular HotDocs fields. See Detect Fillable Fields in a PDF Template.
To change the field type
Copyright 2010 HotDocs Ltd. All rights reserved

608

Help Topics for HotDocs Developer 10

1. Edit a form template. (See Edit a Form Template.)

2. Create a new field (See Create a Form Field) or select an existing field. (See Select a Field.)
3. Click the

Field Properties button. The Field Properties dialog box appears.

4. At the Type tab, make your selection, based on the information in the table above.
Note:
You can change the default colors used for form fields at the HotDocs Options dialog box. (See Change Colors in
HotDocs Forms.)

Copyright 2010 HotDocs Ltd. All rights reserved

609

Help Topics for HotDocs Developer 10

Change the Font Used for a Field

Before You Begin:
These instructions can also be used to change the field's font properties both at the Form Document tab of the
assembly window and in HotDocs Filler.
You can choose the font that is used for answers on a form. When choosing the font, you can also indicate the style (for
example, bold or italics), size, effects, and color that are used.
As is always the case when working with fonts, if the form requires a specific font be used, you must ensure the font is
installed on all computers where the form will be viewed.
To change the font for a field or group of fields

1. Edit a form template. (See Edit a Form Template.)

2. Select the field or fields whose font you want to change.
3. Click the

Field Properties button. The Field Properties dialog box appears.

4. At the Type tab, click Font. The Font dialog box appears.
5. Make your font selections.
Note:
You can specify default font properties for all new fields you create at HotDocs Options. See Set Properties for New
Edit Fields for more details.
Caution:
If you are working with linked fields in a fillable PDF template and you plan to save the document assembled from the
template as a fillable PDF, any changes you make to the linked field will not be honored in the saved fillable PDF. See
Detect Fillable Fields in a PDF Template for details.

Copyright 2010 HotDocs Ltd. All rights reserved

610

Help Topics for HotDocs Developer 10

Format Lines and Paragraphs of Text in a Form Field

Before You Begin:
These instructions can also be used to format how text appears in a field both at the Form Document tab of the
assembly window and in HotDocs Filler.
Sometimes you need to format the text within a multi-line text field. For example, perhaps you need to indent the first line
of a paragraph, or maybe you need to adjust the number of lines that fit in an inch of vertical space. To do this, you can
adjust the line format of a field.
To format lines and paragraphs

1. Edit a form template. (See Edit a Form Template.)

2. Create a multi-line field.
3. Attach a multi-line Text variable to the field. (See Customize a Text Variable.)
4. With the field selected, click the

Field Properties button. The Field Properties dialog box appears.

5. Click the Layout tab. The view changes to show the different options for formatting the field.
6. In the Line Format group, complete one of the following options:
To

Do This

Indent the first line of text

in the paragraph

Enter how much space to include between the margin of the field and the first
character of the answer in the First line indent box. (You can either type the number
or click the up or down arrows.)

Force a certain number of

lines to appear in an inch
of space in the field

Enter the number of lines in the Lines per inch box.

Indicate how many lines

can appear in the field

Enter the number of lines in the Maximum lines box. If the answer contains more
lines than is specified, the field will overflow.

Indicate the maximum

number of characters that
can appear in a given line
of text

Enter the number of characters in the Max chars/line box. When the number of
characters exceeds this limit, text will wrap to the next line.

Caution:
If you are working with linked fields in a fillable PDF template and you plan to save the document assembled from the
template as a fillable PDF, any changes you make to the linked field will not be honored in the saved fillable PDF. See
Detect Fillable Fields in a PDF Template for details.

Copyright 2010 HotDocs Ltd. All rights reserved

611

Help Topics for HotDocs Developer 10

Rotate Answers in a Field

Before You Begin:
These instructions can also be used to rotate answers in an answer field both at the Form Document tab of the
assembly window and in HotDocs Filler.
By default, answers in fields appear in horizontal rows and can be read from left to right. You can rotate text so answers
will read from bottom to top, top to bottom, or upside-down from right to left.
To rotate text in a field

1. Edit a form template. (See Edit a Form Template.)

2. Select the fields you want to rotate. (See Select a Field.)
3. Click the

Field Properties button. The Field Properties dialog box appears.

4. Click the Layout tab. The view changes to show field layout properties.
5. In the Rotation group, select a degree of rotation: 0, 90, 180, or 270, for example:

Note:
You can enter test text in the test answer box (of the Type tab) to preview the selected rotation. See Preview the
Formatting of Answers in a Form Field.
When you change the rotation, HotDocs views the bottom of the letters as the bottom of the field. This means that
aligning the text horizontally or vertically may have different effects.
Caution:
If you are working with linked fields in a fillable PDF template and you plan to save the document assembled from the
template as a fillable PDF, any changes you make to the linked field will not be honored in the saved fillable PDF. See
Detect Fillable Fields in a PDF Template for details.

Copyright 2010 HotDocs Ltd. All rights reserved

612

Help Topics for HotDocs Developer 10

Keep Contents of Form Fields from Printing

Before You Begin:
These instructions can also be used to keep field text from printing at the Form Document tab of the assembly window
and in HotDocs Filler.
Sometimes you want field text to appear on the form during direct-fill assembly, but you don't want the text to appear
when you print a copy of the form. For example, if you create a resource field, you may not want the resource field text to
appear on the form when you print it. You can select an option that keeps this text from printing.
To designate that a field's contents shouldn't be printed

1. Edit a form template. (See Edit a Form Template.)

2. Create or select the field whose text you want to appear only on the form.
3. Click the

Field Properties button. The Field Properties dialog box appears.

4. At the Type tab, select Non-printing field.

Caution:
If you are working with linked fields in a fillable PDF template and you plan to save the document assembled from the
template as a fillable PDF, any changes you make to the linked field will not be honored in the saved fillable PDF. See
Detect Fillable Fields in a PDF Template for details.

Copyright 2010 HotDocs Ltd. All rights reserved

613

Help Topics for HotDocs Developer 10

Create a Field for Behind-the-Scenes Tasks

Frequently, as you automate a form template, you need to perform a task or display text in a field that isn't accessible to
the user. You can do this by creating a control field.
For example, perhaps you want to automatically insert a form template (such as an attachment) if the user answers a
question a specific way. To do this, you must create a field on the form and attach a conditioned INSERT instruction to
the field. However, when you create the field, by default, the user can access the field by typing in it. To keep this from
happening, you can create the field (and attach the instruction) and then make the field a control field. This disables the
field for the user.
Additionally, perhaps you want to include text in a field but you don't want the user to access the text during direct-fill
assembly. If you make such a field a control field, the text will be visible to users, but users won't be able to access it.
To make a field a control field

1. Edit a form template. (See Edit a Form Template.)

2. Create the field you want to use for behind the scenes tasks. (See Create a Form Field.)
3. Assign whatever field properties, variables, or instructions you need to the field.
4. Select the field and click the

Field Properties button. The Field Properties dialog box appears.

5. At the Type tab, select Control in the Field type group.

6. Optionally, you can resize the field so only the field borders are visible. (See Resize Form Fields.) This keeps any
text in the field from appearing on the assembled document, which makes the field completely invisible.
Note:
If you are working with linked fields in a fillable PDF template, some fields are marked as read-only in the underlying
PDF. These become control fields in the template. However, even if you change the field's type in HotDocs, it will
remain a read-only field when you save the assembled document as a fillable PDF.

Copyright 2010 HotDocs Ltd. All rights reserved

614

Help Topics for HotDocs Developer 10

Create a Resource Link on a Form

When automating a template, you can assign resources to variables that help the user know how to answer a specific
question in the interview. At times, however, you may want to include a resource for an entire form. To do this, you create
a resource field. A resource field appears as a hyperlink on the form document. When clicked, the resource appears in a
pop-up window. Resource fields appear during direct-fill assembly only.
To create a resource field, you must create a Text variable and assign as its resource the text you want users to view
while directly filling the form document. You must then define the hyperlink text at the Field Properties dialog box.
To create a link field

1. Edit a form template. (See Edit a Form Template.)

2. Create a field, and attach a Text variable to the field. (See Create a Form Field and Attach a Variable to a Field.)
(This Text variable will not be asked during the interview.)

3. At the Variable Field dialog box, click the

Edit Component button. The Text Variable Editor appears.

4. Click the Resource tab and enter your resource text. (See Add Resource Information to a Variable or Dialog)
5. Click OK at the Text Variable Editor and the Variable Field dialog box. The Automator window appears again.
6. With the field still selected, click the

Field Properties button. The Field Properties dialog box appears. (You can
also right-click and choose Properties from the shortcut menu.)

7. At the Type tab, select Resource from the Field type group.
8. Choose one of the following options from the Display type group:
Hyperlink displays the resource as a link on which the user clicks. Enter the hyperlink text in the Hyperlink
text box.
Image displays the resource as graphic file on which the user clicks. Enter the file name of the graphic in the
Image file name box.
Bar code displays the resource in bar code format. Enter the text you want to encode in the Bar code text
box.

9. Select Non-printing field. (This keeps the hyperlink from printing on the document.)

Copyright 2010 HotDocs Ltd. All rights reserved

615

Help Topics for HotDocs Developer 10

Cross Out Static Text on the Form

Before You Begin:
These instructions can also be used to cross out static text on a form both at the Form Document tab of the assembly
window and in HotDocs Filler.
Sometimes a form includes static text that must be crossed out, depending on answers the user enters during the
interview. For example, say a form includes a list of medical conditions. Instructions on the form tell you to cross out any
conditions that do not apply to you. You could manually cross out these conditions once you've printed the form; however,
HotDocs allows you to create a strike-through field, which crosses out the text for you, depending on answers you enter
during the interview.
A strike-through field, which is transparent, overlays the static text. You can choose the character that will be used to
cross out the text.
To create a strike-through field in a form

1. Edit a form template. (See Edit a Form Template.)

2. Create a field that covers the static text on the form. (See Create a Form Field.)
3. Click the

Field Properties button. The Field Properties dialog box appears. (You can also right-click and select
Field Properties from the shortcut menu.)

4. Click the Type tab.

5. In the Field type group, select the type of field you want to associate with the strike-through field.
6. In the Display type group, select Strike-through.
7. In the Variable box, insert a True/False or Multiple Choice variable. This variable sets the conditions when static text
should be crossed out. (See Attach a Variable to a Field.)
True/False variable: Select an example format that merges the strike-through character when the variable is
true or false, as appropriate. (See Customize a True/False Variable.)
Multiple Choice variable: Type the strike-through character in the Merge Text field of the option that should
cause the strike through, and type NONE in the other choices. (See Customize a Multiple Choice Variable.)
Note:
You can use the alignment controls on the Field Properties dialog box to position the strike-through text more
accurately.
To change the font properties of the strike-through character, click the Font button at the Field Properties dialog
box and make your changes there.

Copyright 2010 HotDocs Ltd. All rights reserved

616

Help Topics for HotDocs Developer 10

Circle Static Text on a Form

Before You Begin:
These instructions can also be used to circle static text on a form both at the Form Document tab of the assembly
window and in HotDocs Filler.
Sometimes instructions on a form ask users to circle a preprinted option. Rather than make users print the form and
manually circle the option using a pen, you can create a form field that overlays a circle on the text. You can attach a
variable to the field so that the user can select which option should be circled during the interview. Creating circle fields
not only preserves the professional look of the form, but allows the answer associated with the selection to be saved in
the answer file.
To create a field that circles text

1. Edit a form template. (See Edit a Form Template.)

2. Create a field that covers the static option on the form you want to select. (See Create a Form Field.)
3. Click the

Field Properties button. The Field Properties dialog box appears. (You can also right-click and select
Field Properties from the shortcut menu.)

4. Click the Type tab.

5. In the Field type group, select the type of field you want to associate with the circled field.
6. In the Display type group, select Circled.
7. Assign a True/False or Multiple Choice variable to the field. (See Customize a True/False Variable, Attach a Multiple
Choice Variable to a Group of Check Boxes, and Customize a Multiple Choice Variable.)

8. Optionally, to control the width of the circle's border, click the Layout tab and change the Line thickness in the
Circle group.
Note:
To preview the circle (see Preview the Formatting of Answers in a Form Field), make sure you enter text in the
Answer text box of the Type tab.

Copyright 2010 HotDocs Ltd. All rights reserved

617

Help Topics for HotDocs Developer 10

Insert a Graphic File in a Form

Before You Begin:
These instructions can also be used to insert graphics in a form both at the Form Document tab of the assembly
window and in HotDocs Filler.
Sometimes you may need to include an image on your form, such as a signature or seal. You can create a field and
assign as one of its properties a graphic file. Supported file formats include .JPG, .BMP, and .PNG. Image files should be
saved to the same folder as the template.
You control the conditions under which the image appears on the form. For example, you can attach a Multiple Choice
variable or a True/False variable that merges an image file depending on which option a user chooses. Additionally, you
can make the field a control field so that users can't access the field directly.
To create a graphic field using a variable

1. Edit a form template. (See Edit a Form Template.)

2. Create a field (See Create a Form Field) and attach either a Multiple Choice or True/False variable to it. (See
Customize a Multiple Choice Variable or Customize a True/False Variable.)

3. If you're using a Multiple Choice variable, edit the variable and, in the Merge Text column, enter the file names of
the graphics, depending on which options the user chooses.

4. If you're using a True/False variable, edit the variable and, in the Format box, enter the file name of the graphic,
either preceded or followed by a forward slash (to indicate yes/no status).

5. Click OK at the variable editor and at the Variable Field dialog box.
6. With the field still selected, click the

Field Properties button. The Field Properties dialog box appears.

7. At the Type tab, select Image from the Display type group.
8. Optionally, change the Field type to Control to restrict the users ability to modify the field. (Change the Field Type.)
To create a graphic field without using a variable

1. Edit a form template. (See Edit a Form Template.)

2. Create a field. (See Create a Form Field.)
3. With the field still selected, click the

Field Properties button. The Field Properties dialog box appears.

4. At the Type tab, select Image from the Display type group.
5. Click the

Open button next to the Image file name box. The Open dialog box appears.

6. Locate and select the desired graphic file and click Open. The path and file name appear in the box.
7. Optionally, change the Field Type to Control to restrict the users ability to modify the field. (Change the Field
Type.)

8. Optionally, click the

Show Variables button in the Automator toolbar to view the image.

The image is visible at the Form Document tab.

Caution:
If you are automating a fillable PDF template and you plan to save the assembled document as a fillable PDF, you
cannot assign an image to a linked field. Instead, use a regular HotDocs field.

Copyright 2010 HotDocs Ltd. All rights reserved

618

Help Topics for HotDocs Developer 10

Convert Answers on the Form to Bar Code Format

Before You Begin:
These instructions can also be used to enter bar code text both at the Form Document tab of the assembly window
and in HotDocs Filler.
You can create a two-dimensional bar code field that displays a single answer or group of answers. This may be useful if
the organization to which you submit your documents requires certain data in the document be in bar code format. This
allows the organization to scan the information and save it in some data retrieval system, such as a database.
For example, say you must submit a form to the court. When the court files the form, rather than manually entering
case information (such as party names, case numbers, etc.), it can simply scan the bar code and have the information
automatically entered in the system.
Typically, bar codes display data in a pattern of lines and formats, which should be readable by most hand-held laser
scanners or charge-coupled device (CCD) scanners. The scanner should be able to read the size of the bars, which is
0.01 inch.
Use the following tips when working with bar codes:
The format HotDocs uses for bar codes is PDF417, or Portable Data File 417. It is one of several recognized 2-D bar
code formats.
Bar codes in HotDocs can store about 1,500 characters, including numbers and other standard text symbols.
Printing a form that has a bar code requires a high-density printer, such as a laser printer.
Bar code fields can overflow, but all overflow properties assigned to the field are ignored. When too much text is
entered for a bar code, no bar code appears. If you are having trouble getting the bar code to fit in the field, you
can enlarge the field or reduce the field margins. (See Resize Form Fields or Change the Borders and Margins of a
Field.)
There are two methods for creating a bar code:
Create a bar code using a variable: When the answers you want to convert to a bar code must be supplied by the
user, you can create a variable, such as a Computation variable, which will then merge the answers in the field and
convert them to bar code format.
Create a bar code using predefined text: If the bar code text is always the same, regardless of who is completing
the document, you can enter that text at the Field Properties dialog box.
To create a bar code using a variable

1. Edit a form template. (See Edit a Form Template.)

2. Create a field and attach a variable to it, such as a Computation variable. (See Attach a Variable to a Field.)
3. If using a Computation variable, create a script that will create a text string that includes all the answers you want
encoded. Separate each answer by using a delimiter character, such as a tilde (~) or a vertical bar ( | ). (See
Customize a Computation Variable and Overview: Instruction and Expression Models.)
For example, Court Branch or District + "|" + Court Mailing Address + "|" + Court City +
"|" + Court Zip Code.

4. Click OK at both the variable editor and the Variable Field dialog box. The template appears again.
5. With the field still selected, click the

Field Properties button. The Field Properties dialog box appears.

6. At the Type tab, select Bar code as the Display type.

7. Optionally, click the Bar Code tab and adjust any of the bar code settings. (See Understand Bar Code Settings.)
When the user assembles the document, the answer will be encoded as a two-dimensional bar code.
To create a bar code using predefined text
Copyright 2010 HotDocs Ltd. All rights reserved

619

Help Topics for HotDocs Developer 10

1. Edit a form template. (See Edit a Form Template.)

2. Create a field. (See Create a Form Field.)
3. Click the

Field Properties button. The Field Properties dialog box appears.

4. At the Type tab, select Bar code.

5. Type the data you want encoded in the Bar code text box. As you type the text, HotDocs displays the bar code
in the underlying form field. (You may need to click the
Show Variables button in the Automator toolbar to
hide variable names.) (If you are entering a group of answers that must be interpreted by the bar code scanner as
individual answers, you must separate each answer with some sort of delimiting character, such as a tilde (~) or
vertical bar (|).)
For example, Superior Court of Ada County|12 N. Elm Street|Boise|99999.
Note:
If you are automating a fillable PDF template and you plan to save the assembled document as a fillable PDF,
you cannot assign a bar code to a linked field. Instead, use a regular HotDocs field.
For information on changing the bar code specifications, see Understand Bar Code Settings.
To access the Field Properties dialog box, you can also right-click and select Field Properties from the shortcut
menu.

Copyright 2010 HotDocs Ltd. All rights reserved

620

Help Topics for HotDocs Developer 10

Move a Field on a Form

Before You Begin:
These instructions can also be used to move fields both at the Form Document tab of the assembly window and in
HotDocs Filler.
As you create fields on a form, you will frequently need to move the fields. You can do this using the mouse or keyboard.
You can also specify a precise location using the Field Properties dialog box.
To move a field using the mouse

1. Edit a form template. (See Edit a Form Template.)

2. Position the mouse pointer over the selected field. The cursor changes.
3. Hold down the mouse button and drag the field to the new position.
To move a field using the keyboard

1. Edit a form template. (See Edit a Form Template.)

2. Select a field. (See Select a Field.)
3. Press the arrow keys to move the field one unit of measurement in that direction. (To move the field more quickly,
hold down the Shift key as you press the arrow keys.)
To move a field using the Position/Size dialog box

1. Edit a form template. (See Edit a Form Template.) Edit a form document. (See Edit a Saved Form Document.)
2. Select a field. (See Select a Field.)
3. Click the

Field Properties button. The Field Properties dialog box appears.

4. Click the Additional tab. The view changes to show the positioning options.
5. In the Position group, enter the desired distance from the left and top margins of the page in the Left and Top
boxes. (You can also click the up or down arrows for each field to change the distance.)
Note:
If you are working with linked fields in a fillable PDF template and you plan to save the document assembled from
the template as a fillable PDF, any changes you make to the linked field will not be honored in the saved fillable
PDF. See Detect Fillable Fields in a PDF Template for details.
If a field you want to move is part of a group, you must first ungroup the fields. (See Ungroup Form Fields.)
The Field Properties dialog box includes the First, Previous, Next, and Last buttons to move you between
fields. When you have multiple fields selected, these buttons are not available.

Copyright 2010 HotDocs Ltd. All rights reserved

621

Help Topics for HotDocs Developer 10

Merge a List of Answers in a Standard Table

Sometimes you may need to merge a list of answers instead of a single answer in a form template. Often this list
can appear in a predefined table in which users enter answers in rows sequenced from top to bottom and in columns
sequenced from left to right.
You can also create what is called a nonstandard table, or one in which the rows are sequenced from left to right, instead
of top to bottom. For details, see Merge a List of Answers in a Nonstandard Table.
When you create a standard table, you create and group fields in every cell, but you only attach variables to fields in the
top row, like this:

To create a list

1. Edit a form template. (See Edit a Form Template.)

2. Create a field in each empty table cell that will contain an answer in the assembled form. (See Create a Form Field.)
3. Attach variables to only the first row of fieldsone variable for each column. (See Attach a Variable to a Field.)
4. Select all of the fields in the table, then select Group as Table (Field menu). A bounding frame appears around the
grouped fields. (You can also right-click and choose Group as Table from the shortcut menu.)

5. With the grouped fields still selected, choose REPEAT (Field menu). The REPEAT Field dialog box appears. (You
can also double-click the grouped fields.)

6. Create a repeated dialog that contains the variables used in the table, or select an existing repeated dialog. (See
Create a REPEAT Instruction to Gather a List of Answers.)
During assembly, if the user enters more answers than there are rows, those answers can be sent to the addendum,
which you can customize.
Note:
You can filter answers merged into the table. (See Filter a List of Answers and Filter a List Using a Computation
Variable.)
Information about the REPEAT instruction is associated with the field grouping. If you ungroup the table after you
have inserted a REPEAT Instruction, remember to regroup the fields before you close the template. Otherwise,
the information about the instruction is lost.
To create a list in a single variable field instead of a table, select the field and insert a Computation variable. In
the computation, use a REPEAT instruction. (See Create a REPEAT Instruction Using a Computation Variable.)

Copyright 2010 HotDocs Ltd. All rights reserved

622

Help Topics for HotDocs Developer 10

Merge a List of Answers in a Nonstandard Table

Sometimes you may need to merge a list of answers instead of a single answer in a form template. Often this list can
appear in a predefined table. Generally, these tables ask for information in a fairly standard orderin rows that read from
left to right. (See Merge a List of Answers in a Standard Table.)
However, some lists require information that flows in different patterns, such as rows going from top to bottom. These
kinds of tables are considered nonstandard. In nonstandard tables, you must specify a field order for every field in
the table, then insert the variables in the fields you have assigned to Row 1. The following examples show types of
nonstandard tables.
In this example, the rows are sequenced from left to right instead of top to bottom:

In this example, the table is divided into sections, but each section is actually a row in the table:

To put a list in a nonstandard table

1. Edit a form template. (See Edit a Form Template.)

2. Create a field in each empty table cell that will contain an answer in the assembled form. (See Create a Form Field.)
Copyright 2010 HotDocs Ltd. All rights reserved

623

Help Topics for HotDocs Developer 10

3. Select all of the fields for the first row (that is, the first series of fields) in the table, then click the
button. The
menu.)

Field Properties

Field Properties dialog box appears. (You can also right-click and select Order from the shortcut

4. Click the Additional tab, and in the Tab Order group, enter 1 in the Row box.
5. Click OK.
6. Select all of the fields for the next row in the table and set them to Row 2. Repeat this process for the remaining
rows in the table, incrementing the row number for each subsequent row.

7. Select all the fields for the first column in the table and set them to Column 1. Repeat this process for the remaining
columns in the table, incrementing the column number for each subsequent column.

8. Attach variables to the fields in Row 1. (See Attach a Variable to a Field.)

9. Select all of the fields in the table and choose Group as Table (Field menu). A bounding frame appears around the
grouped fields. (You can also right-click and select Group as Table from the shortcut menu.)

10. With the grouped fields still selected, choose REPEAT (Field menu). The REPEAT Field dialog box appears. (You
can also double-click the grouped fields.)

11. Create a repeated dialog that contains the variables used in the table, or select an existing repeated dialog. (See
Create a REPEAT Instruction to Gather a List of Answers.)

Copyright 2010 HotDocs Ltd. All rights reserved

624

Help Topics for HotDocs Developer 10

Flow a Single Answer Across Two or More Pages in a Form

Before You Begin:
These instructions can also be used to flow an answer across two pages both at the Form Document tab of the
assembly window and in HotDocs Filler.
At times, a single answer field will start at the bottom of one page and continue to the top of the next page. However,
HotDocs will not allow you to create a single field that spans across both pages. You can, however, create two fieldsone
on each pageand then link them using the Group Fields command.
To group fields on separate pages

1. Edit a form template. (See Edit a Form Template.)

2. Create the first field in the series of spanned fields. (See Create a Form Field.)
3. Assign a Text variable to the field. (See Customize a Text Variable.)
4. Select the field and click the

Field Properties button. The Field Properties dialog box appears.

5. Click the Overflow tab, and in the Group name box, enter a name. Usually, this is the name of the variable, but it
can be any text as long as it is the same for each field in the group.

6. On the following page(s), create the fields that will contain any overflow. Do not assign variables to these fields.
7. Repeat the preceding steps for each field in the group, using the same group name as you assigned to the first field.
Now, answers that do not fit in the first field will overflow to the next field named in the group.
Note:
To span text across multiple fields on the same page, see Group Form Fields So Answers Can Flow From One Field to
Another.

Copyright 2010 HotDocs Ltd. All rights reserved

625

Help Topics for HotDocs Developer 10

Chapter 41: Defining Form Overflow Properties

Define Overflow Properties for a Regular Field
Before You Begin:
These instructions can also be used to change the overflow properties for a field both at the Form Document tab of
the assembly window and in HotDocs Filler.
When an answer is too large to fit in its field, HotDocs, by default, warns you and asks how to handle the overflow. You
can customize the field overflow properties, controlling how HotDocs automatically handles answer overflows.
For example, you can have HotDocs automatically create an addendum, where each answer that overflows is sent. In the
field that overflows, HotDocs can insert cross-reference text that points you to a specific item in the addendum. You can
designate the text that is used both for the cross-reference and for the label in the addendum.
Another option is for you to have HotDocs automatically reduce the answers font size. You can set a minimum point size
and control if the answer is automatically reduced to this size before displaying an overflow warning message. (Be careful
reducing the font size since others may find the smaller size harder to read.) (See Change the Font Used for a Field.)
How you define overflow properties depends on the type of field you are creating. For example, in an addendum, grouped
fields and tables are handled a little differently from regular fields. See Define Overflow Properties for Run-on Fields and
Define Overflow Properties for a Table.
To set overflow properties for regular fields

1. Edit a form template. (See Edit a Form Template.)

2. Select the field whose overflow properties you want to define.
3. Click the

Field Properties button and click the Overflow tab.

4. Complete any of the following steps:

To

Do This

Automatically shrink an
answer that overflows to a
specific point size

Select Shrink answer as needed and enter a point size in the points box.

Automatically send an
answer that overflows to
the addendum

Select Send answer to addendum. (To send only part of a multi-line answer to the
addendum, select Split answer. (See Split a Multi-Line Answer Between the Form
and the Addendum.)

Define the text that

Enter the text in the Cross-reference text box. (See here for a list of reference
appears in the answer field numbering codes you can use.)
when an answer is sent to
the addendum
Define the text that
identifies the answer once
it has been sent to the
addendum

Enter the text in the Addendum label text box.

Make an answer the first

item on its addendum
page

Select Begin addendum entry on a new page.

Make an answer the last

item on its addendum
page

Select Begin new page following addendum entry.

Copyright 2010 HotDocs Ltd. All rights reserved

626

Help Topics for HotDocs Developer 10

Caution:
Fillable PDFs do not support the creation of an addendum when a field overflows. This means that if a field in an
assembled fillable PDF template overflows, the answer in the saved PDF document will simply appear cut off.
Template users should always review and modify any answers that may potentially overflow before saving the
assembled document as a fillable PDF.

Copyright 2010 HotDocs Ltd. All rights reserved

627

Help Topics for HotDocs Developer 10

Define Overflow Properties for Run-on Fields

When an answer is too large to fit in its field, HotDocs, by default, warns you and asks how to handle the overflow. You
can customize the field overflow properties, controlling how HotDocs automatically handles answer overflows.
For example, you can have HotDocs automatically create an addendum, where each answer that overflows is sent. In the
field that overflows, HotDocs can insert cross-reference text that points you to a specific item in the addendum. You can
designate the text that is used both for the cross-reference and for the label in the addendum.
Another option is for you to have HotDocs automatically reduce the answers font size. You can set a minimum point
size and control if the answer is automatically reduced to this size before displaying an overflow warning message. (In
reducing the font size, be cautious, because others may find the smaller size harder to read.) (See Change the Font Used
for a Field.)
How you define overflow properties depends on the type of field you are creating. Grouped fields and tables are handled a
little differently from regular fields. Grouped fields are shown in the addendum as just one answer.
To set the properties for a run-on group

1. Edit a form template. (See Edit a Form Template.)

2. Select the run-on group whose overflow properties you want to define.
3. Click the

Field Properties button and click the Overflow tab.

4. Complete any of the following steps:

To

Do This

Automatically shrink an
answer that overflows to a
specific point size

Select Shrink answer as needed and enter a point size in the points box.

Automatically send an
answer that overflows to
the addendum

Select Send answer to addendum.

Use a check box in the

grouped fields to indicate
the answer overflows

Select either Indicator check box is first in field group or Indicator check box
is last field in group, depending on where the check box that indicates overflow is
positioned.

Sometimes forms include

a check box that indicates
when an answer is
continued elsewhere,
such as in the addendum
or in an attachment.
Choosing one of these
options selects that check
box when the answer
overflows.

Select No addendum entry indicator check box if there is no check box to indicate
an answer has been sent to an attachment or addendum.

To send only part of a multi-line answer to the addendum, select Split answer.

Enter the text in the Cross-reference text box. (Click Use Answer Overflow and
Define the text that
appears in the answer field Addendum Text Codes for a list of reference numbering codes you can use.)
that an answer is sent to
the addendum

Copyright 2010 HotDocs Ltd. All rights reserved

628

Help Topics for HotDocs Developer 10

To

Do This

If you want the indicator

check box to be the only
designation that a field
overflows, enter NONE in
this box.
Define the text that
identifies the answer once
it has been sent to the
addendum

Enter the text in the Addendum label text box.

Make an answer the first

item on its addendum
page

Select Begin addendum entry on a new page.

Make an answer the last

item on its addendum
page

Select Begin new page following addendum entry.

Caution:
Fillable PDFs do not support the creation of an addendum when a field overflows. This means that if a field in an
assembled fillable PDF template overflows, the answer in the saved PDF document will simply appear cut off.
Template users should always review and modify any answers that may potentially overflow before saving the
assembled document as a fillable PDF.

Copyright 2010 HotDocs Ltd. All rights reserved

629

Help Topics for HotDocs Developer 10

Define Overflow Properties for a Table

When the contents of a table overflow, answers, by default, are sent to the addendum as one item. That is, if one answer
overflows, then all of the answers in the table are sent to the addendum. In the addendum, the table's answers are
organized in an outline using lowercase letters to identify each column. Thus, the first row of answers appear in the
addendum as a set marked "a, b, c". The second row of answers appear as a second set of "a, b, c", and so forth.
To define overflow properties for a table

1. Edit a form template. (See Edit a Form Template.)

2. Select the table whose overflow properties you want to define.
3. Click the

Field Properties button and click the Overflow tab.

4. Complete any of the following steps:

To

Do This

Automatically send an
answer (including extra
rows in the table) that
overflow to the addendum

Select Send answers to addendum.

Define how much of

the table is sent to the
addendum when there is
overflow

In the When sending answers to addendum group, select one of the following
options:
Select Send entire table to send the contents of the table to the addendum
any time any answer in the table overflows. The overflow cross-reference text
(for example, See 1 in Addendum) is merged in the top row of the table and no
other rows contain any answers.
Select Send complete rows to send only rows that overflow to the addendum.
For example, if an answer in a row overflows, the entire row is sent to
the addendum. The overflow cross-reference text (for example, See 1 in
Addendum) is merged in the affected row only.
Select Send individual cells to send only the contents of a single overflowing
field to the addendum. The overflow cross-reference text (for example, See 1 in
Addendum) is merged in the affected cell only.

Define the text that

Enter the text in the Cross-reference text box. (Click here for a list of reference
appears in the answer field numbering codes you can use.)
when an answer is sent to
the addendum
Define the text that
identifies the answer once
it has been sent to the
addendum

Enter the text in the Addendum label text box.

Make an answer the first

item on its addendum
page

Select Begin addendum entry on a new page.

Make an answer the last

item on its addendum
page

Select Begin new page following addendum entry.

Indent the answer a

specific amount of space

Enter a number in the Answer column indent box (or click the up and down arrows
to select a number).

Copyright 2010 HotDocs Ltd. All rights reserved

630

Help Topics for HotDocs Developer 10

Caution:
Fillable PDFs do not support the creation of an addendum when a field overflows. This means that if a field in an
assembled fillable PDF template overflows, the answer in the saved PDF document will simply appear cut off.
Template users should always review and modify any answers that may potentially overflow before saving the
assembled document as a fillable PDF.

Copyright 2010 HotDocs Ltd. All rights reserved

631

Help Topics for HotDocs Developer 10

Customize the Look of the Addendum

Before You Begin:
These instructions can also be used to customize the look of the addendum both at the Form Document tab of the
assembly window and in HotDocs Filler.
Sometimes when assembling a form document, an answer is too long for the form field. One way to resolve this overflow
is to send the overflowing text to an addendum, which is a section of the form designed to display such answers. You
can modify the appearance of the addendumfor example, you can choose what page margins to use, define what text
appears in the headers and footers, and choose the font properties for the text that is used in the addendum. You can
also define how pages are numbered in the addendum.
To change the addendum format

1. Edit a form template. (See Edit a Form Template.)

2. Click File > Template Properties > Addendum. The Addendum Properties dialog box appears.
3. Complete any of the following steps:
To

Do This

Define how much white

space there is between
the addendum page
edges and the text in the
addendum

Enter the dimensions in the Page margins group.

Define the text that

appears at the top of each
addendum page

Enter the text in the Header text box.

Define the text that

appears at the bottom of
each addendum page

Enter the text in the Footer text box.

Change the font properties

(including font face, size,
and style) of the header or
footer text

In the respective Header properties and Footer properties groups, click the Font
button and make the changes at the Font dialog box.

Define how much vertical

space the header or footer
text requires

In the respective Header properties and Footer properties groups, enter a number
in the Height box.

Change the alignment of

the header or footer text

In the respective Header properties and Footer properties groups, click the
Alignment button and choose your alignment option.

Insert a variable in the

header or footer text

In the respective Header properties and Footer properties groups, click the

Define the font properties

(including font face, size,
and style) for answers that
appear in the addendum

In the Addendum entries group, click the Font button and make your changes at the
Font dialog box.

Define how much space

there should be between

In the Addendum entries group, enter a number in the Indentation box.

To learn how to merge page numbers in the header, see Use Answer Overflow and
Addendum Text Codes.

To learn how to merge page numbers in the footer, see Use Answer Overflow and
Addendum Text Codes.

Variable Field button. The Variable Field dialog box appears, where you can
define the variable whose answer you want merged in the header or footer.

Copyright 2010 HotDocs Ltd. All rights reserved

632

Help Topics for HotDocs Developer 10

To

Do This

the addendum label and

the answer
Define how much space
there should be between
each answer in the
addendum

In the Addendum entries group, enter a number in the Space between box.

Make the addendum

appear as a pleading
paper

Select Number lines to format as pleading paper.

Once an answer has been sent to the addendum, you cannot edit the actual addendumyou must either modify your
answers at the Form Document tab or Interview tab, or you must send the addendum to the word processor (choose
File > Send Addendum To > Word Processor). You can also send the addendum to the Windows Clipboard (choose
File > Send Addendum To > Clipboard) to paste it into a different program for editing.
Caution:
Fillable PDFs do not support the creation of an addendum when a field overflows. This means that if a field in an
assembled fillable PDF template overflows, the answer in the saved PDF document will simply appear cut off.
Template users should always review and modify any answers that may potentially overflow before saving the
assembled document as a fillable PDF.

Copyright 2010 HotDocs Ltd. All rights reserved

633

Help Topics for HotDocs Developer 10

Split a Multi-Line Answer Between the Form and the Addendum

When creating multi-line fields, you can select an overflow option that sends either all of the answer to the addendum, or
only the part of the answer that doesn't fit in the field to the addendum.
If you allow the user to choose whether to split the answer between the form and the addendum, you can customize
the reference and label text, based on their selection. For example, if the user chooses to send the entire answer to the
addendum, you can specify See Addendum 1 as the cross-reference text. However, if the user chooses to send just part
of the answer, you can specify Continued in Addendum 1 as the reference text.
To choose overflow options for a multi-line answer

1. Create a multi-line field. (See Create a Form Field.)

2. Select the field and click the

Field Properties button. The Field Properties dialog box appears.

3. Click the Overflow tab. The view changes to show overflow options.
4. Complete any of the following steps:
To

Do This

Always send the answer

to the addendum without
prompting the user

Select Send answer to addendum.

Specify the text that will

be merged in the field as
well as the addendum if
the user chooses just to
send to addendum

Enter the text in the Cross-reference text and Addendum label text boxes,
respectively.

To send just the part of the answer that doesn't fit in the field to the addendum, select
Split answer.

To specify alternate text that will be merged in the field and addendum if the user
chooses to split the answer between the form and the addendum, type a vertical bar
(|) and then enter the alternate text after the bar. For example:
Cross-reference text: See Addendum 1|Continued in Addendum 1
Addendum label text: Addendum 1|(con't) Addendum 1

Caution:
Fillable PDFs do not support the creation of an addendum when a field overflows. This means that if a field in an
assembled fillable PDF template overflows, the answer in the saved PDF document will simply appear cut off.
Template users should always review and modify any answers that may potentially overflow before saving the
assembled document as a fillable PDF.

Copyright 2010 HotDocs Ltd. All rights reserved

634

Help Topics for HotDocs Developer 10

Create Independent Addendums for Forms

Before You Begin:
These instructions can also be used to customize the addendum both at the Form Document tab of the assembly
window and in HotDocs Filler.
Sometimes your form includes duplicate pages that must be given to or filed with a specific party. (For example, perhaps
you have a form where one copy must be given to the client, and another copy must be filed in your office.) You can
select an option that specifies that a new addendum page should begin following a specified field. This makes it possible
to create multiple, independent addendums.
To create independent addendums

1. Select the field(s) and click the

Field Properties button. The Field Properties dialog box appears.

2. Click the Overflow tab. The view changes to show overflow options.
3. Select Begin new addendum following this field.
Caution:
Fillable PDFs do not support the creation of an addendum when a field overflows. This means that if a field in an
assembled fillable PDF template overflows, the answer in the saved PDF document will simply appear cut off.
Template users should always review and modify any answers that may potentially overflow before saving the
assembled document as a fillable PDF.

Copyright 2010 HotDocs Ltd. All rights reserved

635

Help Topics for HotDocs Developer 10

Use Answer Overflow and Addendum Text Codes

These instructions can also be used to control numbering in overflow and addendum text both at the Form Document tab
of the assembly window and in HotDocs Filler.
As you customize the appearance of an addendum, you can insert any combination of codes to merge page numbering
into addendum headers and footers. Also, when defining overflow cross-references and labels, you can insert codes that
number entries in the addendum, particularly answers in tables that overflow. Finally, in both cases, you can control the
type of number that is usedArabic, Roman, or alphabetic.

Addendum Header and Footer Page Numbering Codes

You can use the following codes to merge page numbers in addendum headers and footers. For example, the header
text Financial Aid Application, page <PAGE> would insert at the top of each addendum page the form title followed by
the number of the current page in the form (that is, Financial Aid Application, page 1). The footer text Page <PAGE>
of <PAGES> would insert at the bottom of each addendum page the number of the current page followed by the total
number of pages in the form (that is, Page 1 of 7).
Page Numbering Code

What It Inserts in Assembled Document

<PAGE>

Current page in the document

<PAGES>

Total number of pages in the document, including addendum pages

<DOCPAGES>

Total number of pages in the document, without including the addendum

<PAGEINFO>

Current page in the document / Total pages in the document

<ADMPAGE>

Current page in the addendum

<ADMPAGES>

Total number of pages in the addendum

<ADMPAGEINFO>

Current page in addendum / Total pages in addendum.

Addendum Label and Cross-Reference Text Numbering Codes

As you define how HotDocs should handle fields that overflow, you can use the following codes to merge reference
numbers in cross-references and addendum labels. For example, in a table with two rows and two columns, the number
codes <ROW>, <COLUMN> would insert 2, 1 for the answer in the first column of the second row. For that same cell of
the table, <MEMBER> would insert 3, since the field is the third field in the table counting from the first cell of the table.
And again for that answer <MEMBER:A> would insert C, the item number as an uppercase alphabetic character (1=A,
2=B, C=3, etc.).
Numbering Code

What It Inserts in Assembled Document

<REFNR>

Addendum item number

<VARNAME>

The name of the variable

<ROW>

Table row number (merged in addendum only)

<COLUMN>

Table column number (merged in addendum only)

<MEMBER>

Table cell sequence number (merged in addendum only)

Copyright 2010 HotDocs Ltd. All rights reserved

636

Help Topics for HotDocs Developer 10

Numbering Format Codes

To change the format of the number, between the page or referencing number code and the closing angle bracket (>),
type a colon (:) immediately followed by one of the page format codes described in the following table. (A complete entry
would look like this: <DOCPAGES:A>.)
Page Format Code

What Number is Merged

Arabic numerals (default)

Uppercase letters

Lowercase letters

Uppercase Roman numerals

Lowercase Roman numerals

Copyright 2010 HotDocs Ltd. All rights reserved

637

Help Topics for HotDocs Developer 10

Chapter 42: Creating and Using Fillable PDF Form Templates

Overview: Use Fillable PDFs as Form Templates
You can use fillable PDF documents as the basis for creating form templates. A fillable PDF is an interactive PDF
document that allows users to enter answers on the form while viewing it in Adobe Acrobat or Reader. As you create
the template, you will be prompted for instructions on how to use the fillable PDF. You can either create a fillable PDF
template, or you can create a regular PDF-based form template.

Create a Fillable PDF Template

When you create a template from a fillable PDF, you can use the fillable fields from the Adobe document as a point of
reference for automating the template. In fact, during template creation, HotDocs will automatically create fields where
it detects fillable fields. These special fields are known as linked fields, since they link to and use the properties of the
fillable fields.
Users can then assemble a fillable PDF template and save the completed document as a fillable PDF document. This
allows them to edit answers directly in the PDF. Users can also save the assembled document as a regular (static) PDF
or as a HotDocs PDF document.
When using fillable PDF templates, please note the following:
First, when saving the assembled document as a fillable PDF, if you changed any of the default field properties for the
linked field, those properties will not be used in the saved document. Such properties include field position and size, font,
and borders, just to name a few. Adhering to the default properties defined in the original PDF document ensures the
saved document will meet any requirements specified by the agency that issued the form. Note, however, that if you save
the assembled document as a regular PDF or HotDocs PDF Document, any custom properties you specified will be used
for the fields instead.
Second, keeping fillable fields in the template makes it easier to match HotDocs fields to the original fillable fields,
especially when you accidentally move, change, or delete a HotDocs field while editing the template. This precision
may be important if you plan to submit the form to an agency that requires that answers be entered a very specific way,
regardless of whether you save the document as a fillable PDF or otherwise.
Finally, when you create variables and attach them to linked fields in a PDF-based template, HotDocs may suggest some
default properties for the variable, such as a name, format, pattern, and so forth. Where possible, you should accept these
default properties. If you save the assembled document as a fillable PDF, Adobe Acrobat or Adobe Reader will try to
format the answer coming from HotDocs so that it fits in the field as it is defined by Adobe Acrobat. If the answer contains
text or uses properties that are different than what it expects, the field text may appear incorrectly. This is especially true
with Number and Date formats.

Create a PDF Form Template

When creating a form template using a fillable PDF, you can choose not to keep fillable fields in the template. If you do,
the template will be created as a regular, static PDF template, and users of the form will not be able to save it as a fillable
PDF.
Caution:
HotDocs supports only fillable PDFs (or Acrobat Forms or AcroForms) created with Acrobat Professional. It does not
support any fillable PDF documents created or edited using Adobe LiveCycle Designer. (This includes XFA forms,
XML Forms, or Designer Forms.) A small subset of XFA forms might still work, as long as there are no dynamic form
features being used. Typically, if an AcroForm has been edited using LiveCycle Designer and only properties of fields
have been changed, it is likely to still work in HotDocs.

Copyright 2010 HotDocs Ltd. All rights reserved

638

Help Topics for HotDocs Developer 10

Create a Form Template Using a Fillable PDF

Caution:
HotDocs supports only fillable PDFs (or Acrobat Forms or AcroForms) created with Acrobat Professional. It does not
support any fillable PDF documents created or edited using Adobe LiveCycle Designer. This includes XFA forms,
XML Forms, or Designer Forms. Please note that a small subset of XFA forms might still work, as long as there are
no dynamic form features being used. Typically, if an AcroForm has been edited using LiveCycle Designer and only
properties of fields have been changed, it is likely to still work in HotDocs.
Some PDF documents you receive from an organization contain fillable fields, which allow you to enter the data required
by the document while you are viewing the PDF in Adobe Acrobat or Reader. You can create HotDocs form templates
based on these fillable PDFs.
For example, say you download a fillable PDF from the court. You can create a HotDocs PDF template using this fillable
PDF as the basis for the template. When you do, you can choose to keep the fillable fields in the template, or you can
choose to remove them from the template. If you choose to keep them, HotDocs will create special HotDocs fields that
mirror exactly the underlying fillable fields. (These are called linked fields.) This is useful if the resulting document must be
filed with an agency that requires answers be entered in very precise places on the form.
Keeping fillable fields in a form template also makes it easy to re-adjust fields back to their original position and format,
especially when you accidentally move, change, or delete a linked field while editing the template.
If you choose to remove the fillable fields, HotDocs will still create form fields where the fillable fields werethey just will
not be associated with the fillable fields. Additionally, users will not be able to save the document as a fillable PDF, and
the PDF will be static.
Once you create a template that contains fillable fields, you can attach variables to those fields. When you do, HotDocs
attempts to use information from the original fillable PDF to suggest what type of variable to create. It also suggests other
properties, such as variable names and answer formats.
Finally, when assembling a form document that contains fillable fields, you have three options for saving the document:
You can save the document as a regular HotDocs PDF document, or .HPD file. If you select this option, you can
view the file and edit the answers in it using HotDocs Filler only.
You can save the document as a static Adobe PDF document. If you select this option, you can only view the
document in Adobe Acrobat, Reader, or HotDocs Filler. You cannot edit the answers. Any fillable fields in the
template will be removed from the document when you save it.
You can save the document as a fillable PDF. If you select this option, you can edit the answers in the document in
Adobe Acrobat or Reader.
To create a PDF template from a fillable PDF

1. Start HotDocs. The template library appears. (See Start HotDocs.)

2. Click on a folder in the file list and click the

New Template button. The New Template dialog box appears.

3. Click the Type drop-down button and choose HotDocs PDF Template from the list.
4. Enter a name for the file in the File name box and a title for the template in the Title box.
5. In the Initial contents group, select Other file.
6. Click the

Browse button and browse to (and open) the fillable PDF document.

7. Click OK at the New Template Initial Contents box. A message box appears, asking if you want to leave fillable
fields in the form.

8. Make a decision, based on the following options:

Copyright 2010 HotDocs Ltd. All rights reserved

639

Help Topics for HotDocs Developer 10

Select Yes, leave fillable fields in the form if you want to use the fillable fields from the PDF as the basis
for fields in the new template. This allows you to create HotDocs fields that match exactly those fields in the
underlying PDF.
Select No, remove fillable fields from the form if you do not want the template to use the fillable fields from
the source PDF document.

9. If the fillable PDF document contains any annotations (such as notes, stamps, highlighting, etc.), a second message
box appears, asking if you want to leave annotations in the form. Select Yes, leave annotations in the form if you
want the assembled Adobe document to still show these annotations. Be aware, however, that annotations will not
appear on the form in HotDocs Automator. Select No, remove annotations from the form if you want to remove all
annotations so they will not appear in the assembled PDF.
HotDocs creates the template and adds fields to it. If you selected to keep fillable fields in the template, these HotDocs
fields are linked to the fillable fields. Otherwise, HotDocs creates regular HotDocs fields. See Detect Fillable Fields in a
PDF Template for more information on working with these fields.
Note:
When you create a new form template, HotDocs creates a component file, which stores information about components
you use in the template, such as variables and dialogs. The component file works behind the scenes, but both files
the form template and the component fileare necessary for the template to work. (The component file works exactly
the same for a form template as a text template. See Overview: Template and Component Files.)

Copyright 2010 HotDocs Ltd. All rights reserved

640

Help Topics for HotDocs Developer 10

Detect Fillable Fields in a PDF Template

When working with a fillable PDF, you can choose to create HotDocs fields that overlay and link to the PDFs fillable
fields. You can then attach variables to these linked fields and answers entered during the interview will be merged in the
assembled document.
One benefit of using fillable fields as the basis for HotDocs fields is the fillable fields often include properties that indicate
exactly where data must be entered in order for the completed PDF to be filed with a court or agency. For example, you
may download a court form that requires answers to appear using a certain font and size, and the answer must be placed
in an exact position in the field. When you save the assembled document as a fillable PDF, HotDocs honors the fillable
field properties over any HotDocs-specific properties you may assign to fields. This ensures the completed PDF will meet
the court's specifications.
Another benefit of using fillable fields is that saving an assembled document as a fillable PDF allows you to edit answers
while viewing the document in Adobe Acrobat or Reader.
Finally, you can use fillable fields as a "blueprint" for where HotDocs fields should be placed in the template, especially if
you delete or move fields, or if you accidentally edit field properties as you work in the template.
Note:
You can assign custom properties to fillable fields while editing the template in HotDocs Automator. However, these
properties will only be honored if the assembled document is saved as a regular (or static) PDF or HotDocs PDF
document (.HPD).
To help you make sure the linked fields match exactly the fillable fields, you can use the Check Fillable Fields tool, which
scans through the template and, on a field-by-field basis, allows you to compare the properties of a HotDocs field to its
corresponding fillable field. If there are discrepancies, you can adjust the HotDocs field to match the fillable field. Specific
properties this tool examines include size, position, field type, font properties, and text alignment within the field, just to
name a few.
If no HotDocs field is associated with a fillable field, HotDocs prompts you to create the HotDocs field and link it to the
fillable field.
There are two ways you can tell whether a HotDocs field is linked to a fillable field. First, linked fields appear using a light
blue color. Second, HotDocs displays the fillable field name at the Field Properties dialog box. (To view this name, click
the Additional tab of the Field Properties dialog box. The Field name drop-down list in the Linked Acrobat fillable
field group shows the name.)
Note:
You can view where the underlying PDF fillable fields are in the template by choosing Show Fillable Fields from the
View menu.
To detect fillable fields in the template

1. Edit a form template that uses fillable fields. (See Edit a Form Template.)
2. Choose Check Fillable Fields (Tools menu). The Check Fillable Fields Options dialog box appears.
3. Select the field properties you want to compare between the HotDocs fields and the fillable fields. (For example, if
you want to compare only the fonts assigned to the fields, select Font and clear all other options.)

4. Click OK. If there are discrepancies between the HotDocs fields and the fillable fields, the Check Fillable Fields
dialog box appears.
This dialog box shows a table that lists the differences between the two fields it is comparing. The Field Property
column of the table shows the property name, while the HotDocs Field column shows the values currently assigned
to the HotDocs field. The Fillable Field column shows the properties assigned to the fillable field.

5. In the Change column, select which HotDocs properties you want to change so they match the fillable field.
Copyright 2010 HotDocs Ltd. All rights reserved

641

Help Topics for HotDocs Developer 10

6. Proceed by choosing one of the following commands:

Click Change to change the selected properties for the current HotDocs field only. HotDocs makes the change
and then displays the next field comparison.
Click Change All to change the selected properties for all HotDocs fields that have different properties from the
fillable fields.
Click Ignore to ignore the suggested changes for the current field.
Click Ignore All to ignore all suggested changes for all HotDocs fields that have different properties from the
fillable fields.
Note:
As you are checking fillable fields in a template, if a fillable field exists, but does not have a HotDocs field linked
to it, HotDocs prompts you to create a linked field. To create the current field being suggested, click Yes. To
create all fields that are missing, click Yes to All. To ignore the suggestion to create fields, click either No or No
to All.
If you are showing fillable fields, you can double-click on a gray fillable field and HotDocs will create a linked field.
(To view fillable fields, choose Show Fillable Fields (View menu).)

Copyright 2010 HotDocs Ltd. All rights reserved

642

Help Topics for HotDocs Developer 10

Attach Variables to Fillable Fields

Using HotDocs, you can automate a fillable PDF document. As you attach variables to each linked field in the template,
HotDocs attempts to use field names and other properties from the underlying PDF field to create the variable. This
includes assigning any formats specified in Adobe to the HotDocs field. So, for example, if the Adobe document uses a
field named Signature Date and this field is formatted to appear in the mm/dd/yyyy format, HotDocs can attach a Date
variable with the same name to the linked field and assign as its format mm/dd/yyyy.
As you create these variable fields, you can accept the suggested Adobe defaults, or you can specify your own properties.
It is recommended, however, that where specific field formats are suggested, you honor them as closely as possible. If
you save the assembled document as a fillable PDF, Adobe Acrobat or Adobe Reader will try to format the answer to fit
in the field. If the answer contains text or uses properties that are different than what it expects, the field text may appear
incorrectly.
As you attach variables to linked fields in a fillable PDF template, you should be aware of the following rules:
To determine what type of variable to create, HotDocs looks at the different formats assigned to the underlying
fillable field. If the field doesn't have any formats, HotDocs suggests a Text variable. If the field does use formats,
HotDocs tries to map the assigned format to its equivalent in HotDocs. So, for example, if the Adobe field has a
Number format assigned to it, HotDocs will suggest Number as the variable type. If the Adobe field has a telephone
number format assigned to it, HotDocs will suggest a Text variable with a telephone number pattern, and so forth.
HotDocs requires users to follow a set of rules for naming variables. If a name assigned to an Adobe field breaks
one of these rules, HotDocs will change the name so that it becomes valid.
If an Adobe field is required or has a default answer assigned to it, HotDocs makes a note of this in the Notes tab of
the Variable Editor. (When HotDocs adds a note to the tab, it marks the tab using an asterisk (*) character.)
If an Adobe field has a Tooltip, HotDocs uses the Tooltip text as a variable prompt.
Adobe supports time fields that include seconds. It also supports date fields that include hours and minutes. Since
HotDocs does not support either of these types of formats, HotDocs will create a Text variable for the field and
include a prompt that instructs the user on how to enter the answer.
Calculated fields in a PDF file use a JavaScript expression to compute the actual value. When this field is
converted to a HotDocs field, HotDocs will place a commented-out copy of the expression in the Script box of the
Computation Editor. You can use this expression as a guide for writing a HotDocs script that calculates the same
value.
To attach variables to fillable fields using a wizard

1. Edit a form template that uses fillable fields. (See Edit a Form Template.)
2. Choose one of the following tasks for attaching a variable to a field:
Choose Create Variables (Tools menu). HotDocs opens the Variable Field dialog box for the first field in the
template that does not have a variable attached to it.
Select a field and click the

Variable Field button. The Variable Field dialog box appears.

3. Review the suggested variable type and name, and make any necessary changes.
4. Click the

Edit Component button. The Variable Editor appears.

5. Review the properties assigned to the variable, including its format, prompt, and any other patterns, limits, or other
options.

6. Optionally, if the Notes tab shows an asterisk in its label, click it to view any additional fillable field requirements.
7. Click OK to close the Variable Editor, and then click OK again to close the Variable Field dialog box. The variable
is created and attached to the field, and you are taken to the next empty field on the form.

8. Repeat this process for each field in the template.

Copyright 2010 HotDocs Ltd. All rights reserved

643

Help Topics for HotDocs Developer 10

Note:
To skip a field and not create a variable for it, click the Skip button on the Variable Field dialog box.

Copyright 2010 HotDocs Ltd. All rights reserved

644

Help Topics for HotDocs Developer 10

Tips for Working with Fillable Fields

As you work with fillable PDFs, please note the following information:

Creating Fillable PDF Form Templates

HotDocs supports only fillable PDFs (or Acrobat Forms or AcroForms) created with Acrobat Professional. It does not
support any fillable PDF documents created or edited using Adobe LiveCycle Designer. (This includes XFA forms, XML
Forms, or Designer Forms.)
Note:
A small subset of XFA forms might still work, as long as there are no dynamic form features being used. Typically, if an
AcroForm has been edited using LiveCycle Designer and only properties of fields have been changed, it is likely to still
work in HotDocs.

Using Fonts
If you have Type 1 (PostScript) fonts installed on your computer, you should not assign those fonts to fields in PDFbased template files. If you assign a Type 1 font to a form field, the field will appear correctly on screen during assembly
and when the form is saved as a fillable PDF. However, if you print the form or save it as a static PDF, HotDocs will
automatically substitute a TrueType font, which will keep the text in the field from appearing as expected. For best
results, use TrueType (.ttf) fonts (or OpenType (.otf) fonts containing TrueType outlines) with linked fields in a fillable PDF
template.
Fillable PDF authors may embed fonts they use in the fillable PDF. However, when you create a template using a fillable
PDF, HotDocs will not use the embedded font. Instead, it will check to see if the font is installed locally. If it is, HotDocs
will use it. If the font is not installed on the system, HotDocs will attempt to map the font to something similar. Once you
save the assembled document as a fillable PDF, however, the embedded font will once again be used.

Honoring Adobe Field Formats

When you create variables and attach them to linked fields in a PDF-based template, HotDocs may suggest some default
properties for the variable, such as a format, pattern, and so forth. Where possible, you should accept these default
properties. If you save the assembled document as a fillable PDF, Adobe Acrobat or Adobe Reader will try to format the
answer coming from HotDocs so that it fits in the field as its defined by Adobe Acrobat. If the answer contains text or uses
formats that are different than what it expects, the field text may appear incorrectly. This is especially true with Number
and Date formats.

Grouping Fields
If you are automating a fillable PDF template and you plan to save the assembled document as a fillable PDF, you cannot
group run-on fields since necessarily, each fillable field is linked to a separate variable. Answersboth in HotDocs and
Adobemust be entered on individual lines. This means that as you enter an answer in a field, when you reach the end of
one field, you must tab to the next field and continue typing your answer.
Note:
This inability to group fields is a limitation of Adobe. If you have write-access to the form using Adobe Acrobat, you
may consider replacing individual fields in the group with a single, multi-line field with a suitable font size. Text you
enter may not match the lines perfectly, but you will not have to tab between fields to enter the answer.

Copyright 2010 HotDocs Ltd. All rights reserved

645

Help Topics for HotDocs Developer 10

Check-Box Groups
Multiple check boxes or option buttons with the same field name in a PDF file are converted to a HotDocs check box
group. HotDocs relies on the sort order of the member fields when answers from HotDocs are saved back to the PDF
fields. This means that it is not a good idea to change the ordering of the member fields using row and column settings.
Additionally, in the fillable PDF, check boxes and option buttons should all have different Export values since HotDocs
doesn't allow duplicate options in a Multiple Choice variable.

Working with Rights-Enabled PDFs

When creating a fillable PDF document, form designers can enable usage rights within the document. These rights allow
Adobe Reader users to save copies of the document with changes they have made to the documentincluding entering
or changing answers they have entered in the fillable PDF. However, when you convert a rights-enabled fillable PDF to
template format, the document is changed in such a way that usage rights are no longer in effect. This means that users
will not be able to save changes they make when editing the assembled document in Adobe Reader.

Copyright 2010 HotDocs Ltd. All rights reserved

646

Help Topics for HotDocs Developer 10

SECTION 7:
PUBLISHING TEMPLATES

Copyright 2010 HotDocs Ltd. All rights reserved

647

Help Topics for HotDocs Developer 10

Chapter 43: Publishing HotDocs Templates

Overview: Publish HotDocs Templates
Publishing is a convenient way to distribute template files to others. When you publish a template, the related files
(component files, clause library files, and so forth) are automatically compressed with the template file into one file.
There are four types of files you can publish, including:
Standard template files. You can publish a regular template file and copy all the related files to the correct location.
You can also apply protection options to the files.
Auto-install files. You can publish a template or template set that, when accessed by the user, creates a new
library of templates or updates an existing library for the user.
Auto-assemble files. You can publish a template or template set that will automatically assemble when the user
accesses the file.
HotDocs Server files. You can publish the files needed to assemble documents using HotDocs Server.
All of these files can be uploaded to a Web server using your own custom uploading method. (See Overview: Upload
HotDocs Files to a Web Server.)
The HotDocs publishing process offers several ways for you to protect your published files. Also, at the end of the
process, you can save your publishing preferences in a HotDocs publish settings (.HDP) file. These files are saved to your
HotDocs Publish folder and can be used the next time you publish your templates.

Copyright 2010 HotDocs Ltd. All rights reserved

648

Help Topics for HotDocs Developer 10

Publish a Template as a Standard File

You can publish a template as a standard template file to distribute among other users, including other users who will
access it from the Internet or intranet. (See Upload Templates to a Web Server.) Publishing a template ensures that all
associated files are copied to the same folder. It also allows you to protect the files.
You can also publish multiple template files as standard files; however, when you publish multiple templates, they will not
be grouped as a set (as they are if you publish an auto-install or auto-assemble file.)
Additionally, you can publish your templates for use with HotDocs 2006-2008. This allows you to keep your templates
backwards compatible. If you select this option, HotDocs opens and saves the component file in that version.
To publish templates as standard template files

1. At the HotDocs library, select the template or templates you want to publish and click the

Publishing Wizard
button. The Publishing Wizard dialog box appears, displaying the Publishing Options information.

2. Select Standard template files from the Publish as group.

3. If your template contains any INSERT or ASSEMBLE instructions, select Include templates used in INSERT and
ASSEMBLE instructions.

4. If you want to make the published template(s) compatible with HotDocs 2006-2008, select Make published files
compatible with HotDocs 2006-2008.

5. Click the

Browse button next to the Local folder for published files box to specify the folder where you want
HotDocs to save the published files.

6. Optionally, if you plan to upload the published files, click the

Edit button next to the Web destination for

published files box and specify the URL of the server to which you want to upload. (When HotDocs finishes
publishing the templates, it will start the uploading process. See Overview: Upload HotDocs Files to a Web Server.)

7. Click Next. The File Security dialog box appears.

8. Optionally, specify any security options and click Next. (See Protect Published Files for details.) The Additional
Files dialog box appears.

9. If you want to include additional files (such as resource files), click Add Files, then select the desired files. (See Add
Additional Files to a Published Set for details.)

10. Click Finish. HotDocs publishes your files and returns you to the HotDocs library.
Note:
If you publish multiple template sets, you can save the settings you specify during the publishing process so that the
next time you publish, the options are already specified. (See Save Publishing Settings.)
Caution:
Once these files are published to this temporary folder, you should move them to a more permanent location. If you
publish additional templates or other files that use the same file names, HotDocs will overwrite the previously published
files.

Copyright 2010 HotDocs Ltd. All rights reserved

649

Help Topics for HotDocs Developer 10

Publish Templates as Auto-Assemble Files (HDA)

A HotDocs auto-assemble (.HDA) file is a compressed file containing a template and its related files (component files,
clause library files, and so forth.) When you assemble an auto-assemble file, HotDocs copies the template and related
files into a temporary folder, then begins assembling. After assembly finishes, HotDocs deletes the files in the temporary
folder. This is useful if you are distributing templates on the Internet, an intranet, or on a network and you dont want users
to have copies on their local drives. (See Overview: Upload HotDocs Files to a Web Server.)
If you select multiple library items to publish, you can either publish each item as its own auto-assemble file, or you can
group items together in a template set. When an auto-assemble file contains a group of templates, assembly proceeds as
if the user had selected multiple templates for assembly at the HotDocs library window.
Additionally, you can publish your templates for use with HotDocs 2006-2008. This allows you to keep your templates
backwards compatible. If you select this option, HotDocs opens and saves the component file in that version.
To assemble an auto-assemble file, you can either pass the file to HotDocs using a command-line option, or you can
add the auto-assemble file to a HotDocs library. If users access an auto-assemble file while browsing the Internet or an
intranet, the browser will start HotDocs and pass it the auto-assemble file. If you are using a Web browser other than
Internet Explorer, you may need to register HotDocs to work with the Web browser. (See Register HotDocs to Work with
Web Browsers.)
To publish templates as auto-assemble files

1. At the HotDocs library, select the template or templates you want to publish and click the

Publishing Wizard
button. The Publishing Wizard dialog box appears, showing the Publishing Options information.

2. Select one of the following from the Publish as group:

Individual auto-assemble files (HDA)
Template set in a single auto-assemble file (HDA)

3. If your template contains any INSERT or ASSEMBLE instructions, select Include templates used in INSERT and
ASSEMBLE instructions.

4. If you want to make the published template(s) compatible with HotDocs 2006s-2008, select Make published files
compatible with HotDocs 2006-2008.

5. Click the

Browse button next to the Local folder for published files box to specify the folder where you want
HotDocs to save the published files.

6. Optionally, if you plan to upload the published files, click the

Edit button next to the Web destination for

published files box and specify the URL of the server to which you want to upload. (When HotDocs finishes
publishing the templates, it will start the uploading process. See Overview: Upload HotDocs Files to a Web Server.)

7. Click Next. The File Security dialog box appears.

8. Optionally, specify any security options and click Next. (See Protect Published Files for details.)(If publishing
individual auto-assemble files, skip to step 9.)

9. Enter a name for the HDA file in the File name for published HDA file box, and then enter a title for the file in the
Template set title box.

10. Click Next. The Additional Files dialog box appears.

11. If you want to include additional files (such as resource files), click Add Files, then select the desired files. (See Add
Additional Files to a Published Set for details.)

12. Click Finish. HotDocs publishes your files and returns you to the HotDocs library.

Copyright 2010 HotDocs Ltd. All rights reserved

650

Help Topics for HotDocs Developer 10

Note:
If you publish multiple template sets, you can save the settings you specify during the publishing process so that the
next time you publish, the options are already specified. (See Save Publishing Settings.)
Caution:
Once these files are published to this temporary folder, you should move them to a more permanent location. If you
publish additional templates or other files that use the same file names, HotDocs will overwrite the previously published
files.

Copyright 2010 HotDocs Ltd. All rights reserved

651

Help Topics for HotDocs Developer 10

Publish Templates as Auto-Install Files (HDI)

A HotDocs auto-install (.HDI) file is a compressed file containing a library and one or more templates and their related
files (component file, clause library file, and so forth). Auto-install files are a convenient way to distribute template sets to
users, especially sets that must be updated periodically.
When you create an auto-install file, you specify a library file name. The first three characters of the file name are
automatically assigned the characters, PUB, which sets a reference path keyword for the library. The first time a user
installs a template set with that library file name, HotDocs suggests to the user that the library for the templates be
installed in the Template Sets folder or the user's Libraries folder. HotDocs then asks where the templates should be
installed. Any subsequent template sets with that same library file name will automatically get installed to the same
folders. The paths for the templates in the library will appear as ^library file name\library file name\template file name.
If you select multiple library items to publish, you can either publish each item as its own HDI file, or you can group items
together in a template set.
Additionally, you can publish your templates for use with HotDocs 2006-2008. This allows you to keep your templates
backwards compatible. If you select this option, HotDocs opens and saves the component file in that version.
To assemble an auto-install file, you can either pass the file to HotDocs using a command-line option, or you can add the
auto-install file to a HotDocs library using the Install Templates command (File menu at the HotDocs library). If users
open an auto-install file from the Internet or an intranet, the browser will start HotDocs and pass it the file.
When HotDocs is passed an auto-install file, it installs a library, which contains the templates you published. If the library
already exists, HotDocs updates it, overwriting existing library items and adding new items. If the library doesn't already
exist, HotDocs creates it.
To publish templates as HotDocs auto-install files

1. At the HotDocs library, select the template or templates you want to publish and click the

Publishing Wizard
button. The Publishing Wizard dialog box appears, displaying the Publishing Options information.

2. Select one of the following from the Publish as group:

Individual auto-install files (HDI)
Template set in a single auto-install file (HDI)

3. If your template contains any INSERT or ASSEMBLE instructions, select Include templates used in INSERT and
ASSEMBLE instructions.

4. If you want to make the published template(s) compatible with HotDocs 2006-2008, select Make published files
compatible with HotDocs 2006-2008.

5. Click the

Browse button next to the Local folder for published files box to specify the folder where you want
HotDocs to save the published files.

6. Optionally, if you plan to upload the published files, click the

Edit button next to the Web destination for

published files box and specify the URL of the server to which you want to upload. (When HotDocs finishes
publishing the templates, it will start the uploading process. See Overview: Upload HotDocs Files to a Web Server.)

7. Click Next. The File Security dialog box appears.

8. Optionally, specify any security options and click Next. (See Protect Published Files.) (If publishing individual autoinstall files, skip to step 9.)

9. At the Published Template Set dialog box, enter a name for the HDI file in the File name for published HDI file
box, and then enter a title for the file in the Template set title box.

10. Click Next. The Auto-Install Target Library dialog box appears.

Copyright 2010 HotDocs Ltd. All rights reserved

652

Help Topics for HotDocs Developer 10

11. Enter a library file name, title, and optional description for the library that will be created and select any of the
following options:
Update library title and description even if library already exists updates the current library title and
description to match the information in the library that is being installed.
Update library items without installing templates points the items in the library to templates on a CD. (The
templates on the CD must be saved in a first-level folder with the same name as the library base file name
(including PUB).)
Install templates for read-only access installs the templates as read-only, which prohibits users from editing
them.

12. Click Next. If youre publishing a template set in a single auto-install file, the Target Library Shortcut dialog box
appears. (If youre publishing individual auto-install files, skip to step 13.)

13. Optionally, select Install a shortcut in the user's Start menu and specify any shortcut options. (See Create a
Shortcut for an Auto-Install Library.)

14. Click Next. The Additional Files dialog box appears.

15. If you want to include additional files (such as resource files), click Add Files, then select the desired files. (See Add
Additional Files to a Published Set for details.)

16. Click Finish. HotDocs publishes your files and returns you to the HotDocs library.
Caution:
Once these files are published to this temporary folder, you should move them to a more permanent location. If you
publish additional templates or other files that use the same file names, HotDocs will overwrite the previously published
files.
Note:
When installing templates for read-only access, you should understand that this option simply marks the files as
read-only, so feasibly, users could change the file properties and then edit the templates, as long as they have
HotDocs Developer. To keep users from editing the template, specify the Lock Component Files option at the
File Security dialog box.
When updating an existing published template set that is in binary format, if you use any foreign characters in any
of the properties of the template set, HotDocs will convert the existing library to XML format so that it can display
the characters.
When updating the library, HotDocs looks to see if each item in the auto-install files library exists in the users
library. If folder and template titles don't match, HotDocs adds new items instead of updating existing items.
If you give your libraries file names that are unique to your company or product, you will reduce the chance of
another publisher creating a template set with the same name.
If you publish multiple template sets, you can save the settings you specify during the publishing process so that
the next time you publish, the options are already specified. (See Save Publishing Settings.)
You can have a custom splash screen appear when the user launches the library created by the auto-install file.
(See Use a Custom Library Splash Screen.)

Copyright 2010 HotDocs Ltd. All rights reserved

653

Help Topics for HotDocs Developer 10

Protect Published Files

During the publishing process, you can specify options that control users' access to the files, set expiration dates for the
files, and assign passwords to them.
To protect published files

1. At the File Security dialog box of the Publishing Wizard, select the desired protection options:
Lock component files to prevent editing assigns an encrypted password to the component file, which keeps
the user from editing it.
Set expiration date for component files makes the published templates usable only until a certain date.
Selecting this option causes the Component File Expiration dialog box to appear when you click Next. (See
Step 2 for details.)
Register component files allows you to register templates for commercial use with HotDocs Player. (To do
this, you must obtain a special publisher key (.HDK) file from your HotDocs sales representative. Once this file
is obtained (including a password to use it), the publisher key must be copied to the HotDocs program folder.
Then, when you publish your template set, these options will be available. The resulting published set can be
used with Player. See Publish and Register Templates for Use With HotDocs Player.)
Caution:
If your users upgrade to HotDocs Developer and then attempt to edit any published templates you have
registered, those templates will no longer work with HotDocs Player. To prevent users from modifying
component files, and thus unregistering them, you should lock the component files. (See above.)
Password protect published files requires users to enter a password before assembling the auto-assemble
file or installing the auto-install file. You specify this password in the Password box.
Password protect documents sent to Microsoft Word requires users to unprotect the document before
modifying assembled documents that have been sent to Microsoft Word. (They do this by entering the
password you used to publish the file.) (This can include documents that were assembled from WordPerfect
templates.) You specify this password in the Password box.

2. If you selected Set expiration date for component files, the Component File Expiration dialog box appears.
Select the desired expiration options:
Expiration date lets you specify the date on which you want the files to expire. Type the date in the box, or
click the calendar icon next to the box to select the date.
Warning period lets you warn users that their files are about to expire. Click the up or down arrows to specify
the number of days this warning will appear before the template actually expires and can no longer be used.
Extension period lets users continue to use the files for a specified amount of time after the template or
template set has expired. Click the up or down arrows to specify the number of days.
Expiration message lets you include a custom message about the files that are set to expire. Enter your
message in the text box. (HotDocs automatically includes information about the expiration date.)

Copyright 2010 HotDocs Ltd. All rights reserved

654

Help Topics for HotDocs Developer 10

Publish and Register Templates for Use With HotDocs Player

You can register your templates so they can be used with HotDocs Player. To do this, you must first obtain a publishing
license from HotDocs Corporation. You will then receive a publishing key file (register.hdk), which allows you to register
your templates for use with HotDocs Player. Registration happens during the publishing process. A publishing license also
allows you to redistribute HotDocs Player at no cost to your users.
To publish your templates for use with HotDocs Player

1. Copy Register.hdk to the HotDocs program folder (for example, C:\Program Files\HotDocs).
2. At the template library, select the templates you want to publish and click the

Publishing Wizard button.

3. At the Publishing Options page of the wizard, enter all the required information for the template set you are
publishing and click Next. The File Security page appears.

4. Select Register component files and enter the password for the publisher key file in the Password box. (You
should have received this password from the HotDocs Corporation publisher key administrator who gave you the
publisher key file.)

5. Continue with the publishing process.

Your templates are now registered and can be used with HotDocs Player.
Note:
To distribute HotDocs Player, either your users can download a version from the HotDocs Web site, or you can include
it in the installation package with your template sets.

Copyright 2010 HotDocs Ltd. All rights reserved

655

Help Topics for HotDocs Developer 10

Create a Shortcut for an Auto-Install Library

When you publish a template set in a single auto-install file, you can have HotDocs create a shortcut in the user's Start
menu. The shortcut is created when the user installs the file, and, depending on the options you specify, the user can
specify the exact location for the shortcut. You can also include your own custom icon that will be used when the shortcut
is created.
To add a shortcut (including a custom icon) to the Start menu

1. At the Target Library Shortcut dialog box (which appears during the publishing of a template set in a single autoinstall file), select Install a shortcut in the user's Start menu.

2. Optionally, select any of the following options:

Select Prompt for which folder should contain the shortcut to have HotDocs prompt users to specify where
the shortcut will be placed.
Click the
Browse button next to the Icon to use box and locate the icon (.ICO) file you want to assign to the
library. (If you leave this box empty, HotDocs will use a default icon.)
Type a name in the Folder to contain shortcut box. HotDocs will create a folder in the Start > Program Files
menu using this name, and will save the shortcut there. (If you don't specify a name, HotDocs creates the
shortcut in the HotDocs program folder.)
Type a shortcut name in the Label for shortcut box. The label is what identifies the shortcut in the Start menu.

3. Click Next and finish the publishing process.

Copyright 2010 HotDocs Ltd. All rights reserved

656

Help Topics for HotDocs Developer 10

Create an HDI File for a CD-based Template Set

If you are distributing a template set on CD and you want the templates to stay on the CD instead of being installed, you
can create an auto-install file that will create the template set library on the users computer and point the library entries to
the templates on the CD.
Users can install the library by clicking Install Templates (File menu at the HotDocs library window) and selecting
the .HDI file.
To create an auto-install file for a CD-based template set

1. Publish the template set in a single .HDI file. (See Publish Templates as Auto-Install Files (HDI).)
2. At the Auto-Install Target Library dialog box, note the library file name (you will need this name in Step 4), and
select Update library items without installing templates.

3. Finish publishing the template as you normally would.

4. When you put the templates and their associated files on the CD, put them in a first-level folder with the same name
as the library base file name (including PUB) you specified in Step 2. Make sure all associated files and all inserted
files are included on the CD.

Copyright 2010 HotDocs Ltd. All rights reserved

657

Help Topics for HotDocs Developer 10

Add Files to a Published Set

As you are publishing templates and template sets, you may want to include additional files, such as answer files,
resource files, or bitmap files used for custom library splash screens. You can include any of these files by adding them at
the Additional Files dialog box.
To add files to a published template set

1. Publish your templates or your template set. (See Publish a Template as a Standard File, Publish Templates as
Auto-Assemble Files (HDA), or Publish Templates as Auto-Install Files (HDI).)

2. At the Additional Files dialog box, click Add Files. The Select Additional File(s) dialog box appears.
3. Browse to the folder that contains your additional files, select the files, and click Select. HotDocs lists the files in the
box.

4. Optionally, select a file and click Remove Files to remove a file from the list.
5. Click Finish to finish the publishing process.

Copyright 2010 HotDocs Ltd. All rights reserved

658

Help Topics for HotDocs Developer 10

Save Publishing Settings

Any options you select during the publishing process can be saved to a published settings (.HDP) file and used again the
next time you publish a template or set of templates.
To save the settings you used during publishing

1. Publish your templates or your template set. (See Publish a Template as a Standard File, Publish Templates as
Auto-Assemble Files (HDA), or Publish Templates as Auto-Install Files (HDI).)

2. Before clicking Finish at the Additional Files dialog box, click Save Settings. HotDocs displays the Save Publish
Settings As dialog box.

3. Type a name for the file in the File name box. HotDocs adds the extension .HDP to the file.
4. Click Save. The file is saved to the HotDocs Publish folder.
To use the publish settings file, at the first dialog box of the Publishing Wizard, Publishing Options, click Load Settings.
The Load Publish Settings dialog box appears. Select the publish settings (.HDP) file and click Load.

Copyright 2010 HotDocs Ltd. All rights reserved

659

Help Topics for HotDocs Developer 10

Use a Custom Library Splash Screen

You can attach a custom splash screen to any HotDocs library. The splash screen is displayed each time the library is
opened. Template set publishers use library splash screens to identify ownership of or contributors to the templates in a
library.
To attach a splash screen to a library

1. Create a bitmap file (.BMP) of your splash screen, then save it with the same base name as your published library
name. For example, the splash screen for the published library with the file name PUBBusiness.hdl would be
PUBBusiness.bmp.

2. Save the splash screen file to the same folder as the library file to which you want it associated. (If you are
publishing an auto-install file, add the file at the Additional Files dialog box of the Publishing Wizard.)
Caution:
When a user opens a library by clicking the
displayed.

Copyright 2010 HotDocs Ltd. All rights reserved

HotDocs button in the word processor toolbar, no splash screens are

660

Help Topics for HotDocs Developer 10

Automatically Update Published Template Sets

Caution:
For complete information on automatically updating your published template sets through HotDocs, see the HotDocs
API section of the HotDocs Knowledge Base.
When you publish a template set, you can distribute a HotDocs update catalog (.HCAT) file along with your templates.
HotDocs uses this file to automatically check for updates and notify users when updates are available for your template
set. Catalog files contain a link to an RSS document ("feed") on your organization's Web server, which lists all of the
available updates. When you need to update the template set, you add an item to the RSS document and users see the
update the next time HotDocs checks the RSS feed.
To use this feature, you must create an update catalog (.HCAT) file that you distribute to each user and an update
document (RSS feed) that you host on your Web server.

HotDocs Update Catalog Files

A HotDocs update catalog file is an XML file that contains information about the template set to be updated. The following
table lists the main elements of a catalog file:
Element

Description

formatversion

A number that indicates the catalog file format. Currently, the only recognized value is 1,
but future versions of HotDocs may support additional values.

feedurl

A URL for the update document (RSS feed). For example, http://
www.yourcompany.com/update.rss.

checkinterval

The number of days between each update check. If the interval is 0, HotDocs will check
for updates every time it starts.

publishdate

The date on which the template set was published. When HotDocs reads the RSS feed,
it ignores any updates published prior to this date. The date must be in the following
format: Sun, 03 Jun 1990 00:00:00 GMT.

title

The title of the template set. For example, Hobble Creek Real Estate Forms.

password

The password required to install HotDocs Auto-Install (.HDI) files for your template set.
When HotDocs installs an update that requires a password, it uses the password found in
this property. (If you set this property, you should use the same password each time you
create an .HDI file to update your template set.)

enabled

Indicates whether HotDocs should check for updates for this template set (true) or not
(false). Users can change this value at HotDocs Options (Tools > Options > Template
Set Updates).

In addition to these elements, catalog files contain three lists of update items: notinstalleditems, discardeditems, and
installeditems. HotDocs populates these lists and keeps them up to date automatically as it reads the RSS feed specified
in the feedurl element. When you create an update catalog file for distribution with a template set, these lists are normally
empty.
The following example shows the contents of a typical update catalog file without any updates.
Example HotDocs Update Catalog File
You can distribute the update catalog file in two ways. If you publish your template set as a HotDocs Auto-Install (.HDI)
file, you can include the .HCAT file in the list of additional files. When HotDocs installs the template set, it automatically
copies the .HCAT file to the Catalog Files folder specified in the user's HotDocs Options (Tools > Options > File
Locations > Catalog Files). You can also manually copy the .HCAT file to the user's Catalog Files folder.
Copyright 2010 HotDocs Ltd. All rights reserved

661

Help Topics for HotDocs Developer 10

Caution:
HotDocs must have read/write access to the .HCAT file. If HotDocs cannot access the folder or catalog file, the catalog
file will be ignored.

HotDocs Update RSS Document

A HotDocs update RSS document is an XML file that conforms (with a few exceptions) to the RSS 2.0 specifications. It
contains one channel with the following required elements:
Element

Description

title

The title of the template set. For example, Hobble Creek Real Estate Forms.

link

A URL for the template set. It may be a Web site that contains information about your
company or template set. (HotDocs does not currently use this element, but it is included
to conform to the RSS specifications.)

description

A description of the template set. (HotDocs does not currently use this element, but it is
included to conform to the RSS specifications.)

The RSS channel also includes a list of individual update items, which contain the following elements:
Element

Description

title

The title of the update item. For example, if you update your template set monthly, the
title may include the month in which the update is released. If the update fixes a problem
with a particular template, the title may include the name of the template.

link

The URL for the update item. For file updates, this is the URL for a HotDocs Auto-Install
(.HDI) file. For message updates, this is either the URL for a Web site you want users to
visit, or it can be empty if you just want to display a simple message (see the description
element below).

description

A description of the update item. If a message update does not include a link, HotDocs
displays this description when the user applies the update.

guid

A string that uniquely identifies this update item. This must be different for each update
item within your template set.

category

The type of item update. It can be one of the following two values:
File Update: Installs an .HDI file.
Message: Displays a message or links to a Web page.

pubDate

The date on which the update item was published. When HotDocs reads the RSS
document, it ignores any items with a publication date earlier than the publication date
in the .HCAT file. The date must be in the following format: Sun, 03 Jun 1990 00:00:00
GMT.

You can also indicate if an item is required, which means that end users cannot discard (hide) the update. HotDocs
does not force users to install the update, but it will appear in the list of updates every time HotDocs checks for
updates until it has been installed. To make an update item required, add required="true" to the item tag (e.g., <item
required="true">).
The following example shows an RSS document with three update items.
Example RSS Document

Copyright 2010 HotDocs Ltd. All rights reserved

662

Help Topics for HotDocs Developer 10

Example HotDocs Update Catalog File

<?xml version="1.0"?>
<updatecatalog>
<formatversion>1</formatversion>
<feedurl>http://www.HobbleCreek.com/update.rss</feedurl>
<checkinterval>7</checkinterval>
<publishdate>Sun, 03 Jun 1990 00:00:00 GMT</publishdate>
<title>Hobble Creek Real Estate Forms</title>
<enabled>true</enabled>
<password></password>
<notinstalleditems/>
<discardeditems/>
<installeditems/>
</updatecatalog>

Example RSS Document

<?xml version="1.0"?>
<rss version="2.0">
<channel>
<title>Hobble Creek Real Estate Forms</title>
<link>http://www.HobbleCreek.com/update.rss</link>
<description>Serving you since 1994</description>
<item required="true">
<title>Real Estate Purchase Contract (REPC)</title>
<link>http://www.HobbleCreek.com/repc.hdi</link>
<description>This is the new form adopted by the State Real Estate Commission.</
description>
<guid>00001</guid>
<category>File Update</category>
<pubDate>Tue, 21 Mar 2006 15:27:18 GMT</pubDate>
</item>
<item>
<title>Visit the new Hobble Creek Real Estate Web Site</title>
<link>http://www.HobbleCreek.com</link>
<description>New features are added daily</description>
<guid>00002</guid>
<category>Message</category>
<pubDate>Tue, 21 Mar 2006 15:27:18 GMT</pubDate>
</item>
<item>
<title>Happy Holidays</title>
<link></link>
<description>Wishing you a happy holiday season from your friends at Hobble Creek
Real Estate.</description>
<guid>00003</guid>
<category>Message</category>
<pubDate>Tue, 21 Mar 2006 15:27:18 GMT</pubDate>
</item>
</channel>
</rss>

Copyright 2010 HotDocs Ltd. All rights reserved

663

Help Topics for HotDocs Developer 10

Chapter 44: Publishing HotDocs Server Templates

What is HotDocs Server?
HotDocs Server is the server-based version of HotDocs that uses a standard Web browser to display HotDocs interviews,
or answer-gathering sessions. Generally speaking, when a user goes to your Web site and selects a document for
assembly, a request is made from the user's browser to the HotDocs Server engine, which is running on the server.
HotDocs Server then sends an interview file back to the user's browser, where it appears as a Web page. Once the
required information has been entered, the user clicks a button that posts the answers (in XML format) back to HotDocs
Server, where they are merged into assembled documents.
The following diagram shows the assembly process:

The benefit of creating a Web application using HotDocs Server is that users do not need HotDocs installed on their
computers, since the interview is presented in a Web browser and document assembly happens on the server. For
example, your human resources department may integrate its forms into its intranet site using HotDocs Server.
Employees would then go to the intranet site, select which form to fill out, provide the required information, and then
submit the form to the appropriate human resources representativeall from within a Web browser. Depending on project
requirements, employees may also print copies of assembled documents, save copies of assembled documents to their
hard drives, or simply store assembled documents on the server. Additionally, users can save their answer files on the
server, as well as upload answer files from their desktops to the server.
HotDocs Server may also be used for non-interactive assembly. For example, a call can be made to a database and
a document can be generated from information within the database. In this case, users do not have to answer any
interview questions. Likewise, HotDocs Server interviews may be used to gather information to store in a database
without assembling any documents at all.

HotDocs Server vs. Desktop HotDocs

HotDocs Server differs from "desktop" HotDocs (including Developer, User, and Player) in several ways. First of all,
HotDocs Server does not require that users install any special software on their computers; interviews are presented in a
Web browser and document assembly occurs on the server.
Another difference between HotDocs Server and desktop HotDocs is the user interface. The desktop editions include user
interfaces for creating and managing templates, assembling documents, managing answer files, and more. The HotDocs
Copyright 2010 HotDocs Ltd. All rights reserved

664

Help Topics for HotDocs Developer 10

Server user interface, at least from the end user's perspective, is limited to displaying interviews in the Web browser. All
other interaction with the user is accomplished by a custom host application, which you must build and maintain.
Desktop HotDocs does play an important role in a complete HotDocs Server implementation, however. Specifically,
HotDocs Developer is the software used to create templates for use with HotDocs Server, and each authorized instance
of HotDocs Server includes a limited number of licenses for HotDocs Developer.

Copyright 2010 HotDocs Ltd. All rights reserved

665

Help Topics for HotDocs Developer 10

Features Not Allowed in HotDocs Server Templates

The following features are not compatible with HotDocs Server. Using any one of these features will prevent a template
from being assembled using HotDocs Server. (An error message is displayed when you try to test the template in a
browser or publish it for use with HotDocs Server.) In some cases, there are simple ways of accomplishing the same task
without using the feature, however.
Feature

Description

Clauses and clause libraries Although clauses and clause libraries are not supported in HotDocs Server, you can use
inserted templates to achieve similar results. For example, you can use the answer for a
True/False variable to determine when to insert a template into the assembled document.
INSERT instructions used in HotDocs Server cannot process INSERT instructions in computation scripts. However,
computation scripts
INSERT instructions can be processed when they are inserted directly in the template.
LANGUAGE instructions
used in expressions

LANGUAGE instructions are not allowed when used as part of an expression. However,
you can merge the instruction directly in the template.

Personal Information
variables

Personal Information variables require access to the Current User key of the Windows
registry. Since HotDocs Server cannot access the user's registry, this feature is not
allowed.

ANSWER FILE NAME

variables

The ANSWER FILE NAME variable is used to merge the name of the answer file used in
the assembled document. Because of the differences in the way HotDocs Server works
with answer files, this is not allowed.

Database components

Database components created using the HotDocs Database Connection cannot be used
in HotDocs Server templates. However, you can achieve much of the same functionality
using server answer sources. (See the HotDocs Server Help for instructions on creating
an answer source.)

PLAY "MACRO"
instructions

This instruction plays a word processor macro after the document is assembled and
either sent to the word processor, printed, or saved. Playing a macro requires access to
a word processor, and since HotDocs Server assembles documents outside of the word
processor, it cannot play macros.

Application link dialog

elements and EXECUTE
instructions

These instructions are used to start other applications on the user's computer. However,
they are not allowed in HotDocs Server templates.

Scripting in plain text

resources or prompts

In JavaScript interviews, you cannot use scripting (such as IF, REPEAT, SPACE, and
VALUE instructions or expressions) in a resource or prompt. In Silverlight interviews, you
can use scripting in resources and prompts.

Automatic Paragraph
Numbering

In JavaScript and Silverlight interviews, you cannot use PN Numbering (e.g., PN1.
What is your name?) to automatically number the prompts.

Copyright 2010 HotDocs Ltd. All rights reserved

666

Help Topics for HotDocs Developer 10

Features That Work Differently in HotDocs Server Interviews

The following features are allowed in HotDocs Server templates, but they work differently in desktop and server
interviews. For example, the end result may be the same, but the different user interfaces require changes to the
implementation of some features. There are also some features that are ignored when they are used in HotDocs Server
templates. Unlike the features not supported in HotDocs Server templates (click here), these features do not cause any
errors.
Feature

Description

Answer sources

In desktop HotDocs, you can specify an answer source (a list of answers from which a
user can select one) for a dialog. Users open the list when answering a question in a
dialog and pick an existing answer, instead of entering one manually. However, when
assembling documents using HotDocs Server, these answer sources are ignored (the
Select button does not appear on the dialog), although you can use a server answer
source to achieve similar results. (See the HotDocs Server documentation for instructions
on doing this.)

Automatically selecting a
At the Multiple Choice Variable Editor, you can click the Options tab and specify which
Multiple Choice option when option should be automatically selected if the variable is unanswered when displayed.
the variable is unanswered
Although these "default" options are ignored in HotDocs Server interviews, you can still
achieve the same results by using the DEFAULT instruction in your template.
Text patterns

Text patterns are supported in both desktop and server interviews, but the way answers
are formatted as they are entered during the interview is slightly different in each version.

Example formats

You can include variable fields in variable prompts and dialog element text by inserting
the name of the variable within chevrons ( ). You can also specify an example format
for variables within the chevrons. For example, to display a text answer in ALL CAPS,
insert the variable name as follows: Text Var:LIKE THIS (where Text Var is the name
of your variable).
Also, in JavaScript interviews, the FORMAT instruction is not supported in dialog element
text or variable prompts. For example, FORMAT( Text Var, "LIKE THIS" ) or FORMAT
"a, b, and c" does not work in a JavaScript interview. This instruction can be used to
format text in Silverlight interviews and in the assembled document, however.

Script link dialog elements

You can use a script link dialog element to add a button to a dialog that processes a
Computation variable. However, in a HotDocs Server template, the Computation variable
cannot include an ASK instruction or otherwise cause a dialog to be asked. (HotDocs
Server ignores ASK instructions in script link computation scripts.)

Web link dialog elements

You can use Web link dialog element to add a button to a dialog that links to a database.
However, this works only in browser-based (HotDocs Server) interviews. Web links that
launch such databases do not appear in desktop interviews. (See Add a Hyperlink to a
Dialog.)

Image dialog elements

The following restrictions apply to images displayed in dialogs:

Image files must be saved to the same folder as the template.
.JPG and .PNG images are supported in both Silverlight and JavaScript interviews.
In addition, JavaScript interviews allow .GIF images, but neither interview type can
display .BMP images.
Silverlight does not support all possible color depths that are included in the PNG
specification. Specifically, gray scale and 64-bit true color are not supported in
Silverlight.

Copyright 2010 HotDocs Ltd. All rights reserved

667

Help Topics for HotDocs Developer 10

Variable field ( ) and dot

codes in Multiple Choice
option prompts and merge
text

In JavaScript interviews, HotDocs Server processes variable fields ( ) and dot codes in
Multiple Choice option prompts when the Multiple Choice variable is first displayed in an
interview. If the variable used in the prompt is asked before the Multiple Choice variable
is displayed, the variable field will be resolved to display the answer. However, if the
variable did not already have an answer, the prompt will show an unanswered variable
reference instead. In both cases, if the answer for the variable used in the prompt is
subsequently changed, the prompt will not be updated because it is only processed one
time per interview. Finally, variable fields in merge text are never processed in JavaScript
interviews, but they are processed when the answer is merged in the assembled
document.
In Silverlight interviews, variable fields in Multiple Choice option prompts and merge text
are always kept up to date as they are in desktop interviews.

Resources for variables and

dialogs

HotDocs Server only supports Plain Text and URL resources. All other resource
types (HTML Help, Windows Help, Folio Infobase, Custom Program) are ignored
in HotDocs Server interviews. (No resource is displayed for the dialog or variable.) In
addition, HotDocs Server displays all URL resources as hyperlinks that open up separate
windows; the actual Web page does not appear in the resource pane.

End of Interview dialog

HotDocs Server interviews do not include an End of Interview dialog. Selecting Hide End
of Interview dialog at the Component File Properties dialog box (Assembly tab) has
no effect on the server interview.

Question and Answer

summaries

Selecting Use variable names in summaries at the Component File Properties dialog
box (Assembly tab) has no effect on the server interview. (HotDocs Server does not
have an option for creating Question summaries, and Answer summaries always use
variable prompts.)

"TypeHere" bookmarks

Since HotDocs Server does not send assembled documents to the word processor,
selecting Move to the "TypeHere" bookmark at the Component File Properties dialog
box (Assembly tab) is not applicable to HotDocs Server templates.

Prevent users from using an Since answer file selection and processing is handled by your HotDocs Server Web
answer file to assemble a
(host) application, the Do not use answer files option at the Component File
document
Properties dialog box (Assembly tab) does not affect server interviews.
Max WHILE iterations

HotDocs Server does not honor the Maximum WHILE iterations value specified at the
Component File Properties dialog box (Assembly tab). (You should be careful not to
create an infinite WHILE loop in your templates.)

Max processing stack depth

HotDocs Server does not honor the Maximum processing stack depth value specified
at the Component File Properties dialog box (Assembly tab). (You should be careful to
avoid infinitely recursing (processing) a computation.)

Accelerator keys in variable

prompts

In desktop interviews, you can make a character in a variable prompt an accelerator

key by typing an ampersand (&) character immediately before the letter you want as
an accelerator. HotDocs Server correctly removes the ampersand when the prompt is
displayed in the interview, but does not make the following character an accelerator key.

ASCEND, DESCEND, and

FILTER instructions

The ASCEND, DESCEND, and FILTER instructions, which are used for sorting and
filtering repeated dialogs, are ignored in HotDocs Server interviews. They can be used
to sort answers in the assembled document, but not to display a sorted or filtered list of
answers in the interview.

SUM( COMPUTATION_VAR ) Using the SUM( COMPUTATION_VAR) expression to display information during
expression
the interview is not supported. You can use this expression as part of the text in the
assembled document, but not in a dialog script or dialog element.
Copyright 2010 HotDocs Ltd. All rights reserved

668

Help Topics for HotDocs Developer 10

Dot Codes

The following dot codes are not supported in Silverlight interviews:

.tc: Tab character dot codes are ignored.
.oh: An optional hyphen is treated like a normal hyphen.
.pb and .pm: Page break and paragraph mark dot codes are both treated like
line breaks.
.w "URL"/.we: New line characters, strike-through, and underline formatting is
ignored within the text of a Web link.

Automatic Prompt
Alignment

In Silverlight interviews, automatic prompt alignment works differently than it does in

JavaScript or desktop interviews.

SPAN Instructions

When HotDocs assembles a template which contains a SPAN instruction, it checks

the answer file to see if it contains an answer for that SPAN component. If there is an
answer, the text within the SPAN instruction is replaced by the text in the answer file.
This works whether you are assembling a document on the desktop or server. The
difference, however, is that desktop interviews provide an interface at the Document
Preview tab where you can edit the text within a SPAN instruction. On the server, there
is no such user interface for editing SPAN text, which puts the usefulness of SPAN
instructions in server-only templates into question.

Copyright 2010 HotDocs Ltd. All rights reserved

669

Help Topics for HotDocs Developer 10

Enable Templates for Use With HotDocs Server

To enable templates for use with HotDocs Server

1. Open the template's component file for editing and click the

Component File Properties button. The

Component File Properties dialog box appears.

2. Click the HotDocs Server tab and select Enable template for use with HotDocs Server.
3. Select any of the following options:
Option

Description

Interview outline initially

showing

This option causes the interview outline (list of dialogs in the interview) to appear
when the interview is first displayed.

Allow user to hide/show

interview outline

This option lets users show and hide the interview outline as needed.

Resource pane initially

showing

This option causes the resource pane, which shows helpful information about
questions in the interview, to appear when the interview is first displayed.

Allow user to hide/show

resource pane

This option lets users show and hide the resource pane as needed.

Instant Update initially ON

This option causes HotDocs Server to automatically update the entire interview as
users enter or change answers. If this option is turned off, HotDocs will only update
the interview as needed. (Some complex interviews may require Instant Update to be
turned off or response time may be slow.)
Note:
The Instant Update option applies only to JavaScript interviews. In Silverlight,
interviews are always instantly updated.

Allow user to turn Instant

Update on/off

This option lets users control how frequently HotDocs updates the interview.

Single-page interview
initially ON

This option causes the interview to appear as a single page when the interview is first
displayed.

Allow user to turn singlepage interview on/off

This option lets users switch between normal and single-page interviews.

When a template is enabled for use with HotDocs Server, HotDocs warns you if you try to use a feature that is not allowed
in a HotDocs Server template. In addition, HotDocs Server-enabled templates can be tested in a Web browser to ensure
that the interview appears as intended.
Tip:
To view a JavaScript or Silverlight browser interview, use the Template > Test in Browser command at the library
window. You can also view a JavaScript-based interview by pressing the Shift key as you click the
button. To view the interview using Silverlight, press the Ctrl key as you click the

Assemble button. (This also

works while editing a template; you can press either the Shift key or the Ctrl key as you click the
button in your word processor or HotDocs Automator.)

Copyright 2010 HotDocs Ltd. All rights reserved

Assemble
Test Assemble

670

Help Topics for HotDocs Developer 10

View an Interview in a Web Browser

When you test assemble a template you plan to use with HotDocs Server, you can display the interview in a Web
browser. This allows you to test its functionality and view its overall appearance.
To view an interview in a Web browser

1. At the HotDocs library window, select a template and ensure it is enabled for use with HotDocs Server. (See Enable
Templates for Use with HotDocs Server.)

2. Select one of the following options from the Template > Test in Browser menu:
JavaScript: Displays a traditional JavaScript-based interview in a browser window.
Silverlight: Displays a Silverlight-based interview in a browser window. Unlike the traditional JavaScriptbased interviews where the interview logic is written in an interpretive language (JavaScript), Silverlight-based
interviews are compiled into machine code, which makes them much quicker. This is especially noticeable in
long, complex interviews.
Note:
The Silverlight option is only enabled if you have the Microsoft Silverlight 3 Runtime, SDK, and
Microsoft .NET Framework 3.5 installed on your computer. See System Requirements for details.
HotDocs displays the Answer File dialog box.

3. Select an answer file and click OK. A browser window appears and displays the interview.
4. Type any answers and click

Finish. HotDocs closes the browser window and displays the assembled document
in your default word processor or HotDocs Filler (for form documents).

Tip:
You can also view a JavaScript-based interview by pressing the Shift key as you click the
view the interview using Silverlight, press the Ctrl key as you click the

Assemble button. (This also works while

editing a template; you can press either the Shift key or the Ctrl key as you click the
word processor or HotDocs Automator.)

Copyright 2010 HotDocs Ltd. All rights reserved

Assemble button. To

Test Assemble button in your

671

Help Topics for HotDocs Developer 10

Publish Templates For Use With HotDocs Server

To publish and upload templates for use with HotDocs Server

1. At the HotDocs library, select the template or templates you want to publish and click the

Publishing Wizard
button. The Publishing Wizard dialog box appears, displaying the Publishing Options information.

2. Select Template files for use with HotDocs Server from the Publish as group
3. Click the Browse button next to the Local folder for published files box to specify the folder where you want
HotDocs to save the published files. (Once these files are published to this temporary folder, you should move
them to a more permanent location. If you publish additional templates or other files that use the same file names,
HotDocs will overwrite the previously published files.)

4. Choose how you want to upload the templates to the server:

Automatically: Click the Edit button next to the Web destination for published files box to display the Web
Destination dialog box where you can specify the URL and description ("friendly name") of the Publishing
Form Page on the server to which you want to upload the files.
Manually: Leave the Web destination for published files box empty.

5. Click Next. The Additional Files dialog box appears.

6. Select any additional files you want to include with your published templates, and then click Finish. HotDocs finishes
publishing your templates.
If you chose to automatically upload the templates, the Publishing Form Page appears where you can enter
additional information about the templates you are uploading, and then upload that information and the templates to
the server using the Publishing Destination Page.
If you chose to manually upload the templates, move the files from the Local folder for published files to the server.
You can use an FTP client or other application, such as Microsoft FrontPage.
When a template is published for use with HotDocs Server, HotDocs creates two other files required by HotDocs Server:
HotDocs Variable Collection (.HVC) file: stores all of the variables used in a given template
Interview definition (.JS) file: defines (in JavaScript) how the browser should display the interview
If you upload the template automatically using the Publishing Wizard, these files are also uploaded to the server
automatically. If you manually upload your template, you must remember to copy these files to the server.

Copyright 2010 HotDocs Ltd. All rights reserved

672

Help Topics for HotDocs Developer 10

Upload Templates to a Web Server

Once you finish publishing templates and template sets, you can upload the published files to a Web server. This might
be useful if you are publishing templates to be used with HotDocs Server, or if you want your users to access files from an
Internet or intranet site.
To upload template files to a Web server

1. Publish your templates or your template set. (See Publish a Template as a Standard File, Publish Templates as
Auto-Assemble Files (HDA), or Publish Templates as Auto-Install Files (HDI).)

2. At the Publishing Options dialog box, click the

3. Type an absolute URL in the URL box, or click the

Edit button. The Web Destination dialog box appears.

Browse button to locate the URL.

4. Type a description of the Web site in the Friendly name box, and click OK.
5. HotDocs displays the Publishing Options dialog box again, where you can complete the publishing process.
When HotDocs finishes publishing your templates, it displays your customized Web page where you can enter additional
information about the templates you are uploading. Provide the information required by your organization and submit it.
That information, along with your templates, are uploaded to the server.
Note:
In order for template uploading to work, you must create two HTML pages to handle the data you are uploading. (See
Create Custom HTML Documents For Template Uploading.)

Copyright 2010 HotDocs Ltd. All rights reserved

673

Help Topics for HotDocs Developer 10

Chapter 45: Uploading Published Files

Overview: Upload HotDocs Files to a Web Server
You can upload HotDocs template files to a Web server. These include standard template files, auto-assemble files, autoinstall files, and HotDocs Server files. You can do this by creating a custom Web publishing method, which allows you to
use an HTML form to upload your template files. This method also allows you to specify and gather metadata about the
files, such as titles and descriptions, before uploading the files to the server. This information can be integrated with a
database or used with other custom programs or Web designs.

Copyright 2010 HotDocs Ltd. All rights reserved

674

Help Topics for HotDocs Developer 10

Create Custom HTML Documents for Template Uploading

Once you publish your templates or template sets, you can upload the files to a Web server. This may be useful if you are
developing templates for HotDocs Server, or if you want to make your templates available on an Internet or intranet site.
Since Web servers are configured to handle data exchange differently, you must customize the uploading process
to meet your own needs. This requires you (or your Web server administrator) to create a custom HTML form, called
the Publishing Form Page. This form can gather information about the user, the template set, or any other information
required by your project.
Once this form has been created, the template developer can specify its URL as a destination for the upload. (This is
done at the Publishing Options dialog box of the Publishing Wizard.) When the publishing process finishes, the form
appears and template developers can provide the information required to complete the uploading process. Then, once
they have provided the information and submitted the form, HotDocs posts that information, along with the template or
template set, to the server.
As the information and the files are uploaded to the server, the server must know how to manipulate the data being sent
from HotDocs. This requires you to create a second HTML document, called the Publishing Destination Page. This page
contains scripting that can accept the HTTP POST from the Publishing Form Page. It should then process the data and
files contained in the upload by entering metadata about the templates in a database, and then by copying the published
files to the correct server locations, or by performing any other number of services your project requires.
Caution:
During the publishing process, HotDocs logs a report about the uploading process. This report may be useful
if you experience problems uploading your templates. To view this report, open 0hdUploadDebug.htm, located
in the Local Settings\Temp folder (for example, C:\Documents and Settings\<username>\Local Settings\Temp
\0hdUploadDebug.htm).

Publishing Form Page

The Publishing Form Page contains an HTML form. With this form, you can provide fields or other options for the template
developer to add more information about the files being uploaded, such as template titles and descriptions.
You must follow certain criteria when creating the HTML form. First, you must name the form HotDocsPubForm. Second,
the form ACTION must include an absolute URL path to the location on the server where you want to send the files. Last,
any Select/Option fields (or drop-down/list/combo boxes) must have a VALUE attribute assigned, for example:
<option value="Option Text">Select the option</option>
Once the template developer provides the necessary information in this form, he or she submits the form and HotDocs
adds the information to the published files. All the information is then uploaded (using HTTP POST) to the server.
Click here for an example of a Publishing Form Page.

Publishing Destination Page

After the uploading process is complete, the Publishing Destination page appears. This page accepts the HTTP POST
from the Publishing Form page and then processes it by completing the actions specified by your project.
Once the information has been received on the server, the files from the upload must be decoded and handled. Several
components are available to help with this process, including the Dundas Upload control, distributed by Dundas Software.
Click here for an example of Publishing Destination Page. (This page uses the Dundas Upload control.)

Copyright 2010 HotDocs Ltd. All rights reserved

675

Help Topics for HotDocs Developer 10

Upload Templates to a Web Server

Once you finish publishing templates and template sets, you can upload the published files to a Web server. This might
be useful if you are publishing templates to be used with HotDocs Server, or if you want your users to access files from an
Internet or intranet site.
To upload template files to a Web server

1. Publish your templates or your template set. (See Publish a Template as a Standard File, Publish Templates as
Auto-Assemble Files (HDA), or Publish Templates as Auto-Install Files (HDI).)

2. At the Publishing Options dialog box, click the

3. Type an absolute URL in the URL box, or click the

Edit button. The Web Destination dialog box appears.

Browse button to locate the URL.

4. Type a description of the Web site in the Friendly name box, and click OK.
5. HotDocs displays the Publishing Options dialog box again, where you can complete the publishing process.
When HotDocs finishes publishing your templates, it displays your customized Web page where you can enter additional
information about the templates you are uploading. Provide the information required by your organization and submit it.
That information, along with your templates, are uploaded to the server.
Note:
In order for template uploading to work, you must create two HTML pages to handle the data you are uploading. (See
Create Custom HTML Documents For Template Uploading.)

Copyright 2010 HotDocs Ltd. All rights reserved

676

Help Topics for HotDocs Developer 10

Chapter 46: Uploading Answer Files to a Server

Overview: Upload HotDocs Answer Files
You can specify options that let users upload the answers they use to assemble documents. You must designate a
destination URL and provide a resource at that URL, such as a CGI script or HotDocs Server server, to process the
answers.
HotDocs answers are not uploaded in a HotDocs answer file, they are uploaded as a single block of data using the HTTP
POST method. The server receiving the data sees it as a POST submission from an HTML form.
A CGI script receiving the data should do three things:
Get the size of the incoming data block from the CONTENT_LENGTH environment variable.
Read that number of characters from standard input.
Parse the data to extract the HotDocs answers.
This section does not provide the details of writing a CGI script or other program to process the answers. It does,
however, tell you how to enable answer uploading for a template. It also provides the information you need to parse the
uploaded data and extract the HotDocs answers.

Copyright 2010 HotDocs Ltd. All rights reserved

677

Help Topics for HotDocs Developer 10

Specify Options to Upload Answers

You can allow users to upload answers they use with certain templates to a Web server. To do this, you must specify
uploading options at each template's component file.
Caution:
If you plan on uploading answers, make sure your templates dont contain variables with names longer than 30
characters. HotDocs uploads the variable name along with the answer, and it can only upload 30 characters for the
variable name.
To enable users to upload answers for a template

1. Edit the template's component file using Component Manager. (See Open and Close Component Manager.) The
Component Manager window appears.

2. Click the

Properties button. The Component File Properties dialog box appears.

3. Click the Answer Upload tab.

4. Type the URL of the Web page to which you want the answers uploaded in the Upload URL box.
5. Type a description of the page to which the URL points in the Friendly name box.
6. Optionally, select Upload answers without asking to force the answers to always be uploaded, according to the
instructions you have specified.
When users assemble documents that have answer uploading enabled, at the end of document assembly, HotDocs will
either prompt them to upload their answers, or it will upload the answers automatically (depending on whether you select
Upload answers without asking). If users choose to upload their answers later, they can select Upload Answers from
the Tools menu of the HotDocs library.

Copyright 2010 HotDocs Ltd. All rights reserved

678

Help Topics for HotDocs Developer 10

Handle Data in Uploaded Answers

This topic covers information on writing the CGI script or other program to process the answers. It contains the information
needed to parse the data to extract the HotDocs answers, which are uploaded as a single block of data using the HTTP
POST method. The server receiving the data sees it as a POST submission from an HTML form.

Format of Answers
The answers are uploaded in a single string of data, with each answer separated from the next by an ampersand, like this:
Answer1&Answer2&Answer3
The answers are not necessarily in the order in which they were input during document assembly.
Each answer is in the format Name=Value. This results in a data block, like this:
Name1=Value1&Name2=Value2&Name3=Value3
The format for answer names and values is URL-encoded text, with numbers being represented by text. For example,
the number 25 would be represented by the characters 2 and 5. (For more information on URL-encoded text, see URLencoded Text.)
The ampersand character that separates HotDocs answers and the equal sign that separates names and values are not
URL-encoded. The script needs to use these characters to delimit the answers, names, and values before it decodes the
names and values.

Answer Names
All answer names are 31 characters long. (Names for repeated answers are longer, however. See Names of Repeated
Answers.) The first character of the name is a capital letter code indicating the value type of the answer value (which is
always URL-encoded text). This value type corresponds to the variable type of the HotDocs variable that gathered the
answer.
Code

Value

Text

Number

Date

True/False (Boolean)

Multiple Choice

The other 30 characters of the answer name are the variable name of the variable that gathered the answer. If the
variables name is shorter than 30 characters, space characters are appended to the name to bring the total to 30.
The template developer needs to give you the complete answer names (value type code plus variable name).

Answer Values
The format of an answer value depends on the value type of the answer, as specified by the value type code in the
answer name.
Type

Format

Text

Any text

Copyright 2010 HotDocs Ltd. All rights reserved

679

Help Topics for HotDocs Developer 10

Number

Number characters with an optional decimal point

Date

dd mm yyyy (fixed length of 10 characters)

True/False

Either TRUE or FALSE

Multiple Choice

Sections of text separated by vertical bars (for example, No Pets|Covered Parking|AC)

Answer File History

Every collection of HotDocs answers uploaded to an Internet resource has an Answer File History answer. This answer
contains the name of the template used to gather the answers and the date and time it was used. The answer name is:
T(ANSWER FILE HISTORY)
The answer value is a text string in the following format:
template_name : month_name, day, four_digit_year, hh:mm
The time is the local time of the machine on which the template was used and is expressed in 24-hour format. The
following is an example of an Answer File History answer (after URL-decoding):
T(ANSWER FILE HISTORY) =MyTemplate : April 9, 2002, 18:15
Note:
You can use HotDocs Server to process uploaded answers. Click here for an example of an ASP page that
processes uploaded answers using HotDocs Server. (Contact your HotDocs sales representative for information
on obtaining a HotDocs Server license.)
When the upload answers script executes and the server encounters an error, it sends an error report back to
HotDocs. This error report is saved in a file called uploadOutput.htm. It is usually stored in your default temporary
folder.

Copyright 2010 HotDocs Ltd. All rights reserved

680

Help Topics for HotDocs Developer 10

SECTION 8:
ASSEMBLING DOCUMENTS

Copyright 2010 HotDocs Ltd. All rights reserved

681

Help Topics for HotDocs Developer 10

Chapter 47: Completing an Interview

Overview: Assemble a Text or Form Document
There are two types of documents you can assembletext documents and form documents:
Text documents are documents you view in your word processor. Once the document is assembled, you can edit
any of the text.
Form documents are those in which the underlying text is static, meaning it cannot be modified. Only the answers
that are merged into the document can be modified. (An IRS form is a good example of a form document.)
The process of assembling both of these types of documents is very similar. However, there are specific things you
should know about assembling form documents. Please see Overview: Assemble a Form Document for a description of
these differences.
When you assemble a document, HotDocs displays the assembly window, which is divided into three panesthe
interview outline, the dialog pane, and the resource pane. The interview outline shows a list of dialogs (or groups of
questions). You can click on any dialog in the outline and view (and answer) the questions in the dialog pane. Finally,
where provided, the resource pane shows information to help you answer questions in the dialog.
As you answer questions, HotDocs merges your answers into the assembled document, which you can view by clicking
the Document tab at the assembly window. As you are reviewing the assembled document, if you see an answer that
needs to be edited or changed, you can make the change right in the Document Preview tab. (Some template providers
may prohibit you from changing answers at the Document Preview tab. If this is the case, the buttons and commands
that control this feature will be disabled.) Additionally, if the template provider has allowed it, you can edit the actual text of
the document while viewing the Document Preview tab. (These features are available to Microsoft Word users only.) You
can also use the document navigation bar to move between answers in the document.
If you need to generate quick views of the documentfor example a list of just the questions or a list of questions and
answers (without all of the other document text)you can view the Question Summary tab or the Answer Summary
tab. Both provide you with a short list of information required in the document. You can also view a spreadsheet of the
template's variables and any answers that have been given.
Once all of the answers are provided and the document is correct, you can send a copy of the document to a word
processor (if you are assembling a text document) or you can view the assembled document at the Form Document tab
(if you're assembling a form document). If no further editing is needed, you can print the document or save it to disk. You
also can save the answers you've provided in an answer file, which can then be used to assemble other documents.
The following diagram shows the assembly process:

Copyright 2010 HotDocs Ltd. All rights reserved

682

Help Topics for HotDocs Developer 10

Adjust HotDocs Windows and Panes

You can arrange the HotDocs windows and panes to match your work preference.
To work with HotDocs windows

1. At the HotDocs window, complete any of the following steps:

To move a window, click on the title bar and drag the window to another location.
To maximize or minimize the window, click either the Maximize or Minimize buttons in the window title bar. The
Maximize button causes the window to fill the entire screen, while Minimize closes the window and places it on the
Windows taskbar.
To resize the window to a specific size, move the mouse pointer to a border or corner of the window. When the icon
becomes a resize arrow, click and drag the border to the desired position.
To resize a pane within a window, move the mouse pointer to a border between two panes. The icon becomes a
resize arrow. Click and drag the border to the desired proportions.
To rearrange toolbars, move the mouse pointer to the anchor bar of one of the toolbars. Drag the toolbar to the
desired location in the window.
Note:
When moving toolbars, you can separate toolbars from the assembly window. To reattach the toolbar, move it to a
position over the menu bar. You can also remove toolbars by clearing the toolbar at the View menu.

Copyright 2010 HotDocs Ltd. All rights reserved

683

Help Topics for HotDocs Developer 10

Update Your Interview Outline and Document

Some answers you enter during an interview may cause HotDocs to update the appearance of the interview outline.
Additionally, each time you change an answer while viewing the Document tab, HotDocs updates the entire document.
Depending on the complexity of the interview or the document, this updating may take longer than desired. You can
minimize the amount of time HotDocs takes to update the interview or document with your changes by forcing it to update
only when it needs to. You do this by turning
When

Instant Update off.

Instant Update is turned off, information in the interview and document may become outdated. When this

happens, the
Instant Update button changes appearance. You can click the button and HotDocs will update the
interview or document so that all information will be current. (HotDocs also updates the document and interview when you
move between tabs in the assembly window, as well as when you print, save, or send the assembled document to the
word processor.)
To control when HotDocs updates the interview outline or document

1. While viewing either the Interview tab or the Document tab at the assembly window, click the

Instant Update

button.
When the button is selected (or pressed in), HotDocs updates the interview outline as you move between answer
fields. If you're viewing the Document tab, it updates the entire document.
When the button is not selected (or not pressed in), HotDocs updates the outline only when you move between
dialogs. If you're viewing the Document tab, it updates just the answer field you are currently viewing (and any other
answer fields that merge the same answer).

Copyright 2010 HotDocs Ltd. All rights reserved

684

Help Topics for HotDocs Developer 10

Preview a Template Before Assembling It

To help you identify the correct template, you can preview the template before you select it for assembly. The Preview tab
shows the text of the document, as well as where HotDocs variable fields are merged.
To preview a template

1. At the HotDocs library window, select a template.

2. Click the Preview tab. The library window changes to show the template text.
Note:
To remove the Preview tab from the library window, choose Preview Tab (View menu).
To move the Properties and Preview tabs to the top of the pane, select Tabs at Top (View menu.)
The Preview tab shows the information in the template correctly; however, it may not be formatted correctly
particularly when previewing WordPerfect templates. Additionally, previewing form templates will not show you
variable fields.
You can preview a simpler version of the template by choosing Markup View at the template library window. This
changes the preview so it shows simple mark-up fields, rather than complicated automation. (Markup View is
supported for Word templates only.)

Copyright 2010 HotDocs Ltd. All rights reserved

685

Help Topics for HotDocs Developer 10

Search for a Specific Template in a Library

Some libraries may contain a long list of templates. Instead of browsing through the template list, you can search for a
specific template or clause library based on the template's title, file name, or description.
To search for a template or clause library

1. At the HotDocs library window, select the Find check box, located below the template list. The template list changes,
showing each template in the library in alphabetical order.

2. In the Find box, type the text that is in the title, description, or file name of the desired template. The template list
changes to show only the items that contain the text you type. (The Find text box is not case-sensitive.)

3. To view the entire library again, clear the Find check box.
Note:
To show file names instead of template titles in the file list, choose File Names from the View menu. To view template
titles again, choose Template Titles.

Copyright 2010 HotDocs Ltd. All rights reserved

686

Help Topics for HotDocs Developer 10

Assemble a Text or Form Document

You assemble a document by selecting a template and then answering the questions in the interview. Answers to your
questions are then merged in the correct places in the document. Once all of the questions are answered, you can view,
print, or save the document.
To assemble a document

1. At the HotDocs library window, select a template. (If you're assembling a form document, see Overview: Assemble a
Form Document for additional instructions.)

2. Click

Assemble. The Answer File dialog box appears. (You can also start an interview by double-clicking the
template.)

3. Select an answer file (see Select an Answer File for Assembly), then click OK. The assembly window appears,
showing the interview outline and the first information-gathering dialog.

4. Answer the questions in each dialog, clicking

Next to advance to each new dialog. (See Navigate Through

Answer-Gathering Dialogs.) (You can also advance to the next dialog by pressing Alt+N, Enter, or Page Down.)

After the final dialog, the End of Interview dialog identifies how many questions are unanswered. This dialog also
provides options for working with the assembled document. See Use the End of Interview Dialog for specific details.
Note:
HotDocs updates the interview as you enter answers in a dialog. If you experience a significant delay when moving
from one answer to the next, you can have HotDocs update the interview less frequently. (See Update Your Interview
Outline and Document.)

Copyright 2010 HotDocs Ltd. All rights reserved

687

Help Topics for HotDocs Developer 10

Select an Answer File for Assembly

When you assemble a document, you must choose whether to use a new answer file or an existing file. After you
complete each interview, HotDocs can save your answers for use with other assemblies.
To select an answer file

1. At the HotDocs library window, select a template, then click

Assemble. The Answer File dialog box appears.

2. Accept the suggested answer file or change the answer file by choosing one of the following options:
Click the

Open Answer File button to open the Open Answer File dialog box where you can choose an

existing answer file. After making your selection, click

Click the

Open.

New Answer File button to create an empty, untitled answer file.

Select Automatically select this answer file for use with the next assembly to have HotDocs suggest this
answer file for all subsequent documents you assemble.

3. At the Answer File dialog box, click OK. The assembly window appears.
Note:
You can also use Windows Explorer to access your answer files. See Overview: Use Answer Management.
Some templates may have an answer file assigned by the template provider. For templates like this, the Answer
File dialog box does not appear.

Copyright 2010 HotDocs Ltd. All rights reserved

688

Help Topics for HotDocs Developer 10

Assemble an Interview Template

An interview template is distinguished from other templates in the library by its icon: . An interview template does not
produce an assembled document. Instead, it gathers and (and sometimes automatically saves) information (such as
court, attorney, or client information) that can be used in assembling other documents.
For example, a template library might include an interview template named Client Information. This template could gather
personal information about each clientsuch as name, address, gender, birth date, and so forth. This information may be
needed in other templates in the library. Before you ever assemble any of these other documents, you could assemble the
interview template and create a set of answers. Then, whenever a dialog requires client information, you can access the
answers you've already entered. (See Answer Questions in a Dialog Using an Answer Source.)
To assemble an interview template

1. At the HotDocs library window, select the

interview template and click

Assemble. The Answer File dialog box
appears. (If the template is already associated with an external answer source, you will not be prompted to select an
answer file. Skip to step 3.)

2. Select an answer file, then click OK. (See Select an Answer File for Assembly.) HotDocs displays the assembly
window.

3. Answer the questions in each dialog, clicking

Next or

Previous to move between dialogs.

4. At the end of the assembly, HotDocs may prompt you to save your answers in an answer file.
If this prompt appears, click Save or Save As to view the Save Answer File dialog box, where you can save
the answers you've provided. Or, click Don't Save to discard the answers.
If this prompt doesn't appear, the template is probably associated with an external answer source, so HotDocs
automatically saves the answers to that answer source. (See Answer Questions in a Dialog Using an Answer
Source for information on using an answer source.)

5. Close the assembly window.

Copyright 2010 HotDocs Ltd. All rights reserved

689

Help Topics for HotDocs Developer 10

Assemble a Document Without Showing an Interview

You can assemble a document without answering any questions in the interview. When you do this, HotDocs uses the
answer file you specify and assembles the document. Depending on which Finish Interview Action options you have
selected, you can choose where you will view the assembled documenteither in the word processor (text templates),
HotDocs Filler (form documents), or at the Document tab of the assembly window. (See Control What Happens When
You Finish an Interview.)
To assemble a document without viewing the interview

1. At the HotDocs library window, select one or more templates.

2.

Click

Assemble. The Answer File dialog box appears.

3. Select an answer file. (See Select an Answer File for Assembly.)

4. Select Send / Go directly to ... without displaying an interview and click OK. HotDocs assembles the document
using the answers in the answer file you selected. It then displays the assembled document in the application
specified at HotDocs Options.

Copyright 2010 HotDocs Ltd. All rights reserved

690

Help Topics for HotDocs Developer 10

Overlay Answers in the Current Answer File

When you assemble a document, you can use answers from an existing answer file and overlay them in the current
answer file. When an overlay answer file is loaded, it overwrites any existing answers in the current answer file.
For example, perhaps you have an answer file that contains only client-specific answers (such as names and addresses).
These answers could be used in assembling several related documents. However, to use this answer file in the traditional
way (selecting it at the Answer File dialog box), you would most likely add answers to the file, making it less useful in
assembling other documents. To avoid this, you can select a new or existing answer file at the Answer File dialog box,
and then use the answer file that contains your client-specific answers as an overlay answer file. Answers you enter or
change during the interview are saved to the current answer filenot the overlay answer file.
To use an overlay answer file during assembly

1. At the HotDocs library window, select a template and click

Assemble. The Answer File dialog box appears.

2. Select an answer file, and click OK. The assembly window appears. (See Select an Answer File for Assembly.)
3. Click Overlay Answers (File menu). The Open Answer File dialog box appears.
4. Select an answer file to overlay, and click the

Open button. The assembly window appears again, showing

information from the overlay answer file; however, the answer file you selected in step two is still assigned (as seen
in the Current Answer File drop-down list).

Caution:
HotDocs 5 users: You can no longer save or load pattern answer files. Instead, to merge specific answers from one
file into the current answer file, use the Overlay Answers command at the File menu of the assembly window. To
distinguish overlay answer files from regular answer files (as you could with pattern answer files), create a separate
folder in Answer File Manager and store your overlay answer files there. (See Add, Modify, and Delete Folders in
Answer File Manager.)
Note:
You can also specify an overlay answer file at the command line. (See Overview: Command-Line Options and Overlay
Answer File.)

Copyright 2010 HotDocs Ltd. All rights reserved

691

Help Topics for HotDocs Developer 10

Assemble Multiple Documents

You can select multiple templates or clause libraries, and then start one assembly process that will address each
template. Each template or clause library will create a separate document, using the same answer file, unless you select a
different answer file during the interview. (See Switch Answer Files During Assembly.)
To assemble multiple documents

1. At the HotDocs library window, press Ctrl or Shift, then select all the templates and clause libraries you want to
assemble.

2. Click

Assemble. The assembly queue status box (located in the status bar of the assembly window) displays
how many assemblies are waiting, and the Answer File dialog box appears.

3. Select an answer file and click OK. (Select an Answer File for Assembly.) The assembly window appears.
If the item is a template, the first answer-gathering dialog is shown. (See Assemble a Text or Form Document.)
If the item is a clause library, the clause library is shown. (See Select Clauses During an Interview.)

4. Provide answers or select clauses for the interview.

5. After completing the interview, the End of Interview dialog notifies you that other assemblies are ready to begin.
6. Close the assembly window, and begin assembling the next document.
Note:
The assembly queue and assembly queue status box (located in both the library and the assembly window status
bars) can help you track the assembly of each document. See Use the Assembly Queue for details.

Copyright 2010 HotDocs Ltd. All rights reserved

692

Help Topics for HotDocs Developer 10

Use the Assembly Queue

The assembly queue shows a list of templatessome that may be waiting to be assembled and some that may have
recently been assembled. Using the assembly queue, you can start and stop assemblies, change the assembly order, and
change how assemblies are started. In addition, the assembly queue status box (which is located in the status bar of the
template library window and assembly window) also shows when templates are queued for assembly.
The assembly queue provides two methods for starting assemblies: auto mode and manual mode. These methods are
controlled by the
Auto Start button in the assembly queue toolbar. When assembling multiple templates and
Auto
Start is selected, HotDocs automatically starts each assembly, following the order in which the templates are added to
the queue. When assembling multiple templates and

Auto Start is not selected, HotDocs starts the first assembly, but

then waits for you to start each subsequent assembly by clicking the

Assemble button on the assembly queue toolbar.

As templates are added to the assembly queue, they are assigned a status, which helps you identify each template's
stage in the assembly process. (For a description of template statuses, click here.)
To work with templates in the assembly queue

1. At the HotDocs library window, click the

Assembly Queue button. The Assembly Queue dialog box appears.

(You can also select Assembly Queue (Tools menu) or double-click the assembly queue status box in the status
bar of the template library window.)

2. At the library window, select multiple templates and click

Assemble. Entries for each template appear in the

assembly queue. Then the Answer File dialog box appears. (See Assemble Multiple Documents.)

3. At the Answer File dialog box, select an answer file and click OK. (See Select an Answer File for Assembly.) The
first dialog appears in the assembly window.

4. Throughout the interview process, perform any of the following tasks using the following commands in the Assembly
Queue:
To

Do This

Change the order in which

pending or confirmed
templates are assembled

Select the item in the assembly list and click either the
Up button or the
Down
button. (Templates that are currently assembling cannot be moved in the queue.)

Remove a confirmed
assembly

Select the item in the assembly list and click the

Delete button. (Templates that
are currently assembling cannot be removed from the queue.)

Change whether
assemblies start
automatically or manually

Click the

Auto Start button. When Auto Start is turned off, clicking the

Assemble button at the HotDocs library only starts the first assembly. To begin
subsequent assemblies, you must also select an entry in the assembly queue and
click the

Assemble button there.

Manually start an
assembly

Click the

Assemble button.

Remove the entries for

all completed assemblies
from the Assembly Queue

Click the

Clean Up button.

Note:
When HotDocs closes, it remembers the assembly queue display setting. If you close HotDocs while the queue is
showing, the queue will automatically be displayed the next time you open HotDocs.

Copyright 2010 HotDocs Ltd. All rights reserved

693

Help Topics for HotDocs Developer 10

You can have completed assemblies automatically removed from the assembly queue. See Include List of
Completed Assemblies in Assembly Queue for details.

Copyright 2010 HotDocs Ltd. All rights reserved

694

Help Topics for HotDocs Developer 10

Assemble a Clause Library from the Template Library

A clause is a section of text, usually a commonly used paragraph, and a clause library is a collection of clauses. You can
select clauses from a clause library and use them to assemble text documents. (See Overview: Use Clauses and Clause
Libraries.)
In HotDocs, there are two places where you may view a clause library and select clauses for inclusion in a documentat
the template library or during the interview for a text template:
When a clause library is referenced in a template library, you assemble the clause library and then choose where
the assembled clause text is merged. You can choose to send the assembled clauses to a new, empty document;
copy the assembled text to the Windows Clipboard (so you can paste it into an existing document); or paste the
assembled text directly into an open word processor document. (Instructions for this method are included below.)
When a clause library is asked during the interview of a text template, the clause text is automatically inserted into
that assembled document. (See Select Clauses During an Interview for instructions on using this method.)
To assemble a clause library from the template library

1. At the HotDocs library window, select a clause library and click

Assemble. The Answer File dialog box appears.

2. Select an answer file and click OK. The clause library appears in the dialog pane. (See Select an Answer File for
Assembly.)

3. Optionally, perform either of the following tasks:

Select the Find check box to find all of the clauses with specific text in their title or description. In the text box,
type the text for which you are searching.
Click
Preview to view the clause text in a pop-up dialog box. To return to the clause library, click the X in
the upper-right corner of the pop-up dialog box.

4. From the Available list, select each clause you want to use and click
remove a clause, select it, then click

Select to add it to the Selected list. To

Remove. (Press Ctrl or Shift to select multiple items.)

5. Optionally, reorder the clauses in the Selected list by selecting and dragging a clause to the desired position. The
clauses will be inserted into the document in this order.

6. When all the necessary clauses are in the Selected list, click

Next on the navigation bar.

7. Answer any questions in the interview. Once all questions are answered, complete any of the following steps:
Click the
Send the assembled document to the word processor button (or press F11) to open the
assembled document in your word processor.
Click
Paste the assembled document into the open word processor document (or press Shift+F11) at
the End of Interview dialog. This will insert the assembled document into an open word processor document.
Microsoft Word users: Choose File > Send Document To > Clipboard (or press Ctrl+F11) to place a copy
of the document on the Windows Clipboard. You can then open an existing document and paste the text in the
desired location.

Copyright 2010 HotDocs Ltd. All rights reserved

695

Help Topics for HotDocs Developer 10

Navigate Through Answer-Gathering Dialogs

To assemble a document, you must answer interview questions. To help you, you can use the navigation bar, located at
the bottom of the dialog pane.
As you answer questions, the icons in the interview outline change color. This can help you identify how much of the
interview is left to complete:
None of the questions in the dialog are answered.
At least one of the questions in the dialog is answered.
All of the questions in the dialog are answered.
Repeats the dialog, allowing you to enter more than one set of answers.
Allows you to enter a new set of answers in a list.
The final dialog in every interview is usually the End of Interview dialog, which reports how many questions are
unanswered. This dialog also provides options for working with the assembled document. For information on these
options, or to learn about hiding or customizing the End of Interview dialog, see Use the End of Interview Dialog.
To navigate through HotDocs dialogs

1. At the HotDocs library window, select a template and begin assembling the document. (See Assemble a Text or
Form Document.)

2. The HotDocs assembly window appears. Complete any of the tasks using commands listed in the following table:
To

Do This

Enter an answer for the

question

Depending on the type of answer required, type a text or number answer, enter a
date, select a check box, or choose an option from a list of options.
When entering a multi-line text answer, you can control whether the Enter key inserts
a line break or a paragraph mark in the assembled Word document. To enter a line
break, simply press Enter. To enter a paragraph break, press Ctrl+Enter. (In some
situations, the template developer may have specified which break to use.)
When entering a patterned time of day, enter the hour first, then press the right arrow
key to move past the colon to enter the minutes. You can also click the up and down
arrows next to the answer field to select the hours and minutes.

Move to another dialg in

the interview outline
Go to the next or previous
dialog

Click a dialog icon in the interview outline.

Click either the

Next Dialog button or the Previous Dialog button. (You can
also press Page Down/Page Up, or Alt+N/Alt+P.)

Go to the next dialog or

the previous dialog that
contains an unanswered
variable

Click either the

Next Unanswered button or the Previous Unanswered button.
You can also press Ctrl+Page Up/Ctrl+Page Down.

Go to the first or the last

dialog in the interview

Click either the

Copyright 2010 HotDocs Ltd. All rights reserved

First Dialog button or the

Last Dialog button.

696

Help Topics for HotDocs Developer 10

To

Do This

Finish the interview and

view the assembled
document

Click the
Finish Interview button. (Where you view the assembled document
depends on the Finish Interview action you've specified. See Control What Happens
When You Finish an Interview.)

View additional information Click the

about a specific answer or
the contents of a dialog

View Resource button. (See View Resources During Assembly.)

View where the answer is

merged into the document
(This option is available to
Word users only.)

Click the
Go to Answer in Document button. HotDocs displays the Document
tab and moves the cursor to the first place in the document where the answer is
merged.

Hide the interview outline

Clear Interview outline (View menu).

Preview an assembled text Click the Document Preview tab. (See Preview the Assembled Text Document.)
document before sending
it to the word processor
View an assembled form
document

Click the Form Document tab. (See View the Assembled Form Document .)

View a list of all questions

in the template

Click the Question Summary tab. (See View a Question Summary.)

View a list of all the

questions and their
answers in the interview

Click the Answer Summary tab. (See View an Answer Summary.)

View a spreadsheet of the

variables and their current
answers

Click the Variable Sheet tab. (See View the Variable Sheet.)

Note:
HotDocs updates the interview as you enter answers in a dialog. If you experience a significant delay when
moving from one answer to the next, you can have HotDocs update the interview less frequently. (See Update
Your Interview Outline and Document.)
Sometimes the format of your answer may be changed. To verify these changes, you can specify an option
that forces HotDocs to warn you of answer format changes before moving to the next dialog. (See Warn When
HotDocs Reformats Date and Number Answers.)
To display the different tabs along the bottom of the window (instead of the top), clear Tabs at Top (View menu).

Copyright 2010 HotDocs Ltd. All rights reserved

697

Help Topics for HotDocs Developer 10

View Resources During Assembly

Template providers can include helpful information with dialogs and questions in the interview. When such information is
available, it appears in the resource pane. (To view the resource pane, either choose Resource Pane (View menu) or
click the

Resource button in the assembly window toolbar.)

To view resource information

1. At the HotDocs library window, select a template and begin assembling the document. (See Assemble a Text or
Form Document.)

2. Navigate to a dialog that shows a resource.

If the resource pane is already displayed, the information automatically appears there. (You can change the
size of the resource pane by selecting the top border of the pane and dragging it up or down.)
If the resource pane isn't displayed, you can either click the

Resource button in the toolbar or click the

Resource button that appears next to the answer field.

Note:
Resources help you answer questions in the interview. For help using HotDocs, see Get Help Using HotDocs.

Copyright 2010 HotDocs Ltd. All rights reserved

698

Help Topics for HotDocs Developer 10

Save an Answer File During Assembly

While assembling a document, you can save the answers you have entered. This allows you to save your work and
perhaps start a different assembly without closing the assembly window. Saving answers also allows you to use the
information you enter with other templates, thus saving you time.
To save answers during assembly

1. At the HotDocs library window, select a template and begin assembling the document. (See Assemble a Text or
Form Document.)

2. At the assembly window, click the

Save Answers button. If you are using an existing answer file, the new
answers are saved. If you are using a new answer file, the Save Answer File dialog box appears where you can
perform any of the following tasks:
To

Do This

Enter the file name

At the File name box, enter a name. When you click OK, the answer file will be
saved to the default Answers folder and a reference to it will be added to Answer File
Manager.
To save the answers to a location other than the default Answers folder, click the
Browse button and navigate to the location.

Enter the title that

identifies the answer file in
Answer File Manager

At the Title box, enter a name or accept the suggestion HotDocs makes.

Add information to help

identify the file

At the Description box, type notes about the answer file's purpose or contents. (The
description will appear at the Properties tab of the Answer File Manager. When
searching for specific answer files, you can search for text in the description.)

Save the answer file so it

Select HotDocs 2005-2008 answer file. (See Compatibility of HotDocs 10 Files with
is compatible with versions Earlier Versions of HotDocs.)
of HotDocs earlier than
HotDocs 2009
Note:
See Overview: Use Answer Management for information on using Windows Explorer instead of Answer File
Manager.
The
Save Answers button may be disabled because the template provider wants to prevent the answer
file from being altered. You can assemble a document using new answers, but when you close the assembly
window, the new answers are automatically discarded.

Copyright 2010 HotDocs Ltd. All rights reserved

699

Help Topics for HotDocs Developer 10

Switch Answer Files During Assembly

While assembling a document, you may want to use another answer file. At any point during the interview, you can select
a different answer file, then continue the interview using the new answers.
To switch answer files

1. At the HotDocs library window, select a template and begin assembling a document. (See Assemble a Text or Form
Document.)

2. During the interview, click

Open Answers. The Open Answer File dialog box appears. (Depending on the
file management settings you have selected, a Windows Explorer dialog box or a window from your document
management program may appear instead. See Manage Answer Files.)

3. Select an answer file and click

Open.

4. If prompted to save the old answers, click Save, Save As, or Don't Save, depending on your needs. (See Save an
Answer File During Assembly.)

5. The assembly window appears again, using the newly selected answer file.
Note:
When viewing the answer library, you can sort the answer files. To do this, select a folder and click
Sort. To search
for a specific answer file, select the Find check box, then type the text for which you are searching in the text box.

Copyright 2010 HotDocs Ltd. All rights reserved

700

Help Topics for HotDocs Developer 10

Use Repeated Dialogs During Assembly

Dialogs can be repeatedly asked to gather several sets of answers for the same questions. A repeated dialog can appear
as a series of dialogs or as a spreadsheet.
Once you have created a list of answers, you can use commands in the toolbar to move records within the list.
Note:
You can change the way repeated dialogs are represented in the interview outline. (See Display Repeated
Dialogs Using a Special Icon.)
HotDocs updates the interview as you enter answers in a dialog. If you experience a significant delay when
moving from one answer to the next, you can have HotDocs update the interview less frequently. (See Update
Your Interview Outline and Document.)
To enter answers in a series of dialogs

1. At the repeated dialog, enter answers for the questions.

2. Click the

Add Another button to add another repetition of the dialog to the series. The repetition number next
to the dialog icon increases each time you enter a new set of answers. (You can also press Alt+A to add new
repetitions to a list.)

3.

To move to the next dialog after entering all the answers in the list, click
Next in the navigation bar. (You can also
click on the next dialog icon in the interview outline, or press Page Down or Alt+N.)

Note:
When entering a list of answers within another list of answers, you can press Alt+Left Arrow to return to the parent
dialog. (You can also choose Parent Dialog from the Navigate menu.)
To enter answers in a repeated spreadsheet

1. At an answer-gathering dialog that includes a repeated dialog formatted as a spreadsheet, click in the first
spreadsheet cell and enter your answer.

2. Press Tab to move to the next cell in the row (or use the mouse to click in the next cell) and enter your answer.
3. Repeat this process for each answer.
To work with repeated answers

1. Answer questions in the repeated dialog.

2. Select the record with which you want to work. (If you are editing records in a dialog series, select the dialog icon in
the interview outline. If you are editing records in a spreadsheet, click on the row you want to edit.)

3. Use the options described in the following table to complete additional tasks:
To

Do This

Remove a specific dialog

from the list of answers

Select the dialog you want to delete and either click the
or choose Delete Repetition from the Edit menu.

Insert a new dialog

between existing dialogs

Either click the

Edit menu.

Move an existing dialog up

in the list of answers

Select the dialog you want to move and click the

(located on the Edit toolbar).

Move Repetition Up button

Move an existing dialog

down in the list of answers

Select the dialog you want to move and click the

(located on the Edit toolbar).

Move Repetition Down button

Copyright 2010 HotDocs Ltd. All rights reserved

Delete Repetition button,

Insert Repetition button, or choose Insert Repetition from the

701

Help Topics for HotDocs Developer 10

To

Do This

Sort the contents of a

spreadsheet dialog in
alphanumeric order

Click in the column on which you want to sort and click the
Sort button (located on
the Edit toolbar). The Sort Spreadsheet dialog box appears where you can specify
your sorting preferences. If the template developer has specified any sorting options,
answers will be merged in the document using those sort options. Otherwise the sort
order you specify here will be used in the assembled document.

Edit the contents of the

row in a regular dialog

Click in the row you want to edit and either click the
and choose Edit Row from the shortcut menu.

Copyright 2010 HotDocs Ltd. All rights reserved

Edit Row button, or right-click

702

Help Topics for HotDocs Developer 10

Use Inserted Dialogs During Assembly

In some templates, one dialog may contain other dialogs. For example, a dialog may ask for information about a client;
then, if the client is married, an inserted dialog may ask for information about the spouse.
To use an inserted dialog

1. At the HotDocs library window, select a template and begin assembling the document. (See Assemble a Text or
Form Document.)

2. Navigate to a dialog that contains an inserted dialog.

3. Select the inserted dialog and provide information for the answer fields, based on the following information:
If the dialogs are not grouped: For each inserted dialog, HotDocs displays an icon in the dialog pane
and in the interview outline. If you don't answer questions in the inserted dialogs, HotDocs counts them as
unanswered questions and warns you about them.
If the dialogs are grouped for single selection: HotDocs adds an option button next to each inserted dialog
icon. Until you select one of the option buttons or click the child dialog icon or title, no icon for the inserted
dialog appears in the interview outline. If you don't select an option button and don't answer any questions in
the inserted dialogs, HotDocs doesn't count them as unanswered questions.
If the dialogs are grouped for multiple selection: HotDocs adds a check box next to each inserted dialog
icon. Until you select the check boxes or click the child dialog icon or title, no inserted dialogs appear in the
interview outline. If you don't select any check boxes and don't answer any questions in the inserted dialogs,
HotDocs doesn't count them as unanswered questions.
Note:
You can hide all inserted dialogs in the interview outline by selecting Collapse All (View menu) or by pressing
Alt+-.
HotDocs updates the interview as you enter answers in a dialog. If you experience a significant delay when
moving from one answer to the next, you can have HotDocs update the interview less frequently. (See Update
Your Interview Outline and Document.)

Copyright 2010 HotDocs Ltd. All rights reserved

703

Help Topics for HotDocs Developer 10

View Individual Rows in a Spreadsheet

Some documents may require a list of information. To generate a list, template providers create a repeated dialog, which
may be formatted as a spreadsheet. This format may be awkward to work with when there are large numbers of questions
(or columns)the spreadsheet may extend beyond the viewable area. However, to see all the questions at once, you can
view one row of the spreadsheet in dialog format.
To answer a single set of answers in a spreadsheet

1. At the HotDocs library window, select a template and begin assembling the document. (See Assemble a Text or
Form Document.)

2. At the assembly window, navigate to a repeated dialog that is formatted as a spreadsheet.

3. At the spreadsheet, click

Edit Row. A pop-up interview appears. (You can also right-click and choose Edit Row

from the shortcut menu.)

4. Type answers in the answer fields, then click

Next. The answers are saved and a new set of answer fields

appears.

5. After providing all the necessary answers, close the pop-up interview by clicking

Copyright 2010 HotDocs Ltd. All rights reserved

Finish.

704

Help Topics for HotDocs Developer 10

Select Clauses During an Interview

A clause is a section of text, usually a commonly used paragraph, and a clause library is a collection of clauses. You can
select clauses from a clause library and use them to assemble text documents. (See Overview: Use Clauses and Clause
Libraries.)
In HotDocs, there are two places where you may view a clause library and select clauses for inclusion in a documentat
the template library or during the interview for a text template:
When a clause library is referenced in a template library, you assemble the clause library and then choose where
the assembled clause text is merged. You can choose to send the assembled clauses to a new, empty document;
copy the assembled text to the Windows Clipboard (so you can paste it into an existing document); or paste the
assembled text directly into an open word processor document. (See Assemble a Clause Library from the Template
Library for instructions on using this method.)
When a clause library is asked during the interview of a text template, the clause text is automatically inserted into
that assembled document. (Instructions for this method are included below.)
To select clauses from an inserted clause library

1. At the HotDocs library window, select a template that contains an inserted clause library and begin assembling the
document. (See Assemble a Text or Form Document.)

2. Navigate to the dialog where the clause library is located. The clause library appears in the dialog pane.
3. Optionally, perform either of the following tasks:
Select the Find check box to find all of the clauses with specific text in their title or description. In the text box,
type the text for which you are searching.
Click
Preview to view the clause text in a pop-up dialog box. To return to the clause library, click the X in
the upper-right corner of the pop-up dialog box.

4. From the Available list, select each clause you want to use and click
remove a clause, select it, then click

Select to add it to the Selected list. To

Remove. (Press Ctrl or Shift to select multiple items.)

5. Optionally, reorder the clauses in the Selected list by selecting and dragging a clause to the desired position. The
clauses will be inserted into the document in this order.

6. When all the necessary clauses are in the Selected list, click

Next on the navigation bar.

7. Answer any questions in the interview.

Copyright 2010 HotDocs Ltd. All rights reserved

705

Help Topics for HotDocs Developer 10

View an Assembled Document in Markup View

Caution:
If you are not a template developer, please click here for a brief explanation of template development terms.
Understanding these terms will help you understand how the assembled document is marked up.
As you assemble Microsoft Word documents, there may be times when you want to assemble only a partial document
and then submit it to an attorney or peer for revisions or corrections. To make the document easier for a non-HotDocs
user to review, you can change the formatting of the document to Markup View and then provide the reviewer a copy of it.
When displaying markup, HotDocs replaces unanswered fields and instructions in the document with markup, which
includes markers (such as brackets) and variable names. How the resulting markup fields look depend on the type of
fields they are:
Answer fields: By default, answer fields are marked using brackets. If the template developer has assigned a
comment to the variable, the comment text may be used as the field name. If no comment is used, HotDocs will use
either the title or the name the template developer assigned to the variable.
Conditional and repeated text blocks: By default, conditional and repeated text blocks are marked using brackets.
If a comment is assigned to these text blocks, the comment can be merged in the field label. If no comment is
assigned, HotDocs will simply merge the field markers around the text block. The text block can be marked using an
annotated footnote or endnote (depending on your preferences).
Insertion fields: HotDocs will merge the file name of the template being inserted.
Once you assemble the document using as many answers as needed, you can switch to Markup View and save a copy of
the document. You can then provide a copy of it to the reviewer.
To view a document in Markup View

1. Define the Markup View options you want to use in the document. (See Specify How Documents Should Be Marked
Up.)

2. Assemble the Word document for which you want to generate markup.
3. Answer only the questions whose answers you want to appear in the assembled document. Leave all other
questions unanswered. (These unanswered questions are the fields that will be marked using the scheme you define
in step 1.)

4. Choose Markup View (View menu). The document changes to show the marked up document.
Note:
By default, merge fields in the document appear in colorred for unanswered questions and blue for answered
questions. Sometimes, however, if an answer field is within a text block that is conditional or repeated, it appears
(and remains) blue until the condition is met or the REPEAT instruction is answered. Editable text likewise
appears using the colors you've defined at HotDocs Options.
Additionally, merge fields in the document are italicized by default. If you've used international characters in your
answers, the italicized version of the font used in the document may not display the foreign characters correctly. If
this is the case, clear the Italic attribute for Markup View. See Specify How Documents Should Be Marked Up for
details.
If the template developer has used merge fields in question prompts, those merge fields can be displayed as
markup fields. (Choose Markup View (View menu) while at the Interview tab.) Additionally, you can switch to
Markup View while assembling form documents.
To view a non-marked up version of the assembled document again, clear Markup View (View menu).

Copyright 2010 HotDocs Ltd. All rights reserved

706

Help Topics for HotDocs Developer 10

Answer Date Questions

To make it easier to answer Date variables, HotDocs provides three different ways to enter a date:
Type the letter t, then move to the next answer field. HotDocs converts the letter to the current date.
Type a date using a common format, such as MM/DD/YYYY. HotDocs converts the format to match the format
specified for the template.
Click the
Calendar button to access the Calendar dialog box. Then use the Next or Previous arrows to find the
desired month and year. Select a day, and click OK.
Note:
HotDocs requires a four-digit year for Date variables. However, you can enter a two-digit year, and then let
HotDocs convert it to a four-digit year. You can control which years are converted to 1900-century dates, and
which are converted to 2000-century dates. See Control How HotDocs Handles Two-Digit and Four-Digit Years.
The
Calendar button is not available when a Date variable is in a dialog repeated as a spreadsheet. However,
if you click Edit Row, the pop-up interview will show the calendar button.
HotDocs may format dates in the interview different from the way they will appear in the assembled document.
The appearance in the interview is controlled by a setting in the HotDocs Options dialog box. (See Change the
Way Dates Appear in Answer Fields.) When a date appears in the document, however, it is formatted according
to the format assigned to that variable.
HotDocs updates the interview as you enter answers in a dialog. If you experience a significant delay when
moving from one answer to the next, you can have HotDocs update the interview less frequently. (See Update
Your Interview Outline and Document.)

Copyright 2010 HotDocs Ltd. All rights reserved

707

Help Topics for HotDocs Developer 10

View an Answer's Variable Name

Sometimes as you complete an interview, you may need to ask the template provider about a specific question asked in
the interview. Being able to identify the question by variable name may help the template provider better understand the
kind of information you need. You can have HotDocs show you the name of the variable.
To view the variable name for a question in the interview

1. At the HotDocs library window, select a template and begin assembling the document. (See Assemble a Text or
Form Document.)

2. Navigate to the dialog that contains the question.

3. Place your cursor in the answer field, right-click, and choose Variable Name from the shortcut menu. A message
box appears, showing you the variable name.

Copyright 2010 HotDocs Ltd. All rights reserved

708

Help Topics for HotDocs Developer 10

Use the End of Interview Dialog

The End of Interview dialog appears after the last dialog in each interview. At this dialog, you can view a report of
unanswered questions, as well as access commands for working with the assembled document.
To work with assembled documents at the End of Interview dialog

1. At the HotDocs library window, select a template and begin assembling the document. (See Assemble a Text or
Form Document.)

2. After completing the interview, the End of Interview dialog appears. The following table describes the commands
available here:
To

Do This

Return to the first

unanswered question in
the interview

Click

Go to the first unanswered question in the interview.

Click

Send the assembled document to the word processor.

Send the assembled text

document to the word
processor so you can view
it in its final format

You can choose the default word processor to which assembled documents are
always sent, or you can let HotDocs choose the word processor each time based on
the file type. See Change Your Default Word Processor.

View the assembled form

document

Click the
View the assembled form document at the Form Document tab
button. (See View the Assembled Form Document.)

Insert the assembled

document into an open
word processor document

Click
Paste the assembled document into the open word processor
document.
This command will paste the document text into a document already open in your
word processor. If there is not a document already open, HotDocs will create a new
document.

Copy the document

text to the Clipboard
(only available when
assembling Microsoft
Word documents)

Click

Copy the assembled document to the Clipboard.

Save a copy of the

assembled document

Click

Save the assembled document in a file.

Save an assembled text or

form document as a PDF
file

Click

Save the assembled document as a PDF.

Close the assembly

window without saving a
copy of the assembled
document

Click

Close this window without saving the assembled document.

Choose which buttons are

displayed in the End of
Interview dialog

Click

Choose which buttons are displayed on this dialog.

Caution:
For complete instructions on saving assembled documents as PDF files, see Save
Assembled Text Document as PDF.

Copyright 2010 HotDocs Ltd. All rights reserved

709

Help Topics for HotDocs Developer 10

Note:
When you assemble multiple documents, the End of Interview dialog also notifies you that other assemblies are
ready to begin.
To keep the End of Interview dialog from appearing, clear End of Interview Dialog at the View menu of the
assembly window. Then, when you click Next at the last dialog in the interview, HotDocs will either send the
assembled document to the word processor or HotDocs Filler, or it will display the Document tab of the assembly
window. To specify which action HotDocs performs, see Control What Happens When You Finish an Interview.
You can choose which options appear in the End of Interview dialog. See Customize the End of Interview Dialog.

Copyright 2010 HotDocs Ltd. All rights reserved

710

Help Topics for HotDocs Developer 10

Edit Answers at the Document Preview Tab

Note:
The ability to edit answers at the Document Preview tab is available to Microsoft Word users only. Additionally, this
option is available only if the template provider has allowed it.
If you are viewing the Document Preview tab, you can edit answers you've entered. Additionally, you can move from an
answer in the document to its question in the interview and vice versa. Seeing answers in the context of the document
helps you pinpoint errors and makes it easy for you to correct them without having to go back to the interview.
To help you review answers in the document, you can use the Document Navigation Bar. Just like the Interview
Navigation Bar, this toolbar can help you move between answers, unanswered fields, and matching answers.
Caution:
Some template providers may prohibit you from changing answers at the Document Preview tab. If so, the buttons
and commands that control this feature will be disabled.
To change answers while previewing the document

1. At the HotDocs library window, select a template and begin assembling the document. (See Assemble a Text or
Form Document.)

2. After providing the required answers, click the Document Preview tab. The assembly window changes to show a
preview of the document.

3. Click the

Highlight Fields button. This assigns colors to both answered questions and unanswered questions in
the document. (You can change the default colors assigned to answered fields as well as unanswered fields. See
Set Properties for Viewing Answers and Editable Text in the Assembled Document.)

4. Double-click on an answer field. A pop-up interview appears, showing the dialog in which the question is used.
5. Change your answer and click

Next or

Finish. The pop-up interview closes and the answer is updated in the

document.

6. Use any of the following commands to help you edit answers in the document:
To
Jump to the place in
the interview where the
question is asked

Do This
Caution:
Because of scripting in the template, sometimes you will not be able to move
between the Interview and Document tabs. HotDocs will warn you when this is
the case.
Place your cursor in the answer field and click the
button.

Go to Answer in Interview

While viewing the Interview tab, you can go to the place in the document where
the answer is merged. To do this, place your cursor in the answer field and click the
Go to Answer in Document button.
Move between answers in
the document

Click

Next or

Previous to move to the next or previous answer in the document.

Click the
Next Unanswered or Previous Unanswered button to move to the
next unanswered or previous unanswered question in the document.
Press Ctrl+M or Ctrl+Shift+M to move between matching answers in the document
(for example, those answers in the document that are exact matches). (You can also
press Shift as you click the

Copyright 2010 HotDocs Ltd. All rights reserved

Next or

Previous button.)

711

Help Topics for HotDocs Developer 10

To

Do This
Click
End or
document.

Beginning to go to end of the document or the beginning of the

Note:
If you experience a delay when changing answers in your document, click the
Document Instant Update
button (so it isn't pressed in). Then, when you change an answer, HotDocs will just update the field you are
editing (and any other fields that merge the exact same answer). Be aware, however, that turning
Instant
Update off may cause some of the information in the document to be out of date if you change answers. (You
can tell when the document is out of date by the appearance of the
Instant Update button. To update the
document, click the button again. (The document will automatically update if you attempt to save it, print it, or
send it to the word processor.)
Once your cursor is in an answer field, you can press Enter and the pop-up interview will appear.
If the template provider has allowed it, you can also edit the text of the document. See Edit Document Text at the
Document Preview Tab for details.

Copyright 2010 HotDocs Ltd. All rights reserved

712

Help Topics for HotDocs Developer 10

Spell Check Answers

You can spell check text answers you have entered at any time during an interview.
To spell check your answers

1. At the HotDocs library window, select a template and begin assembling the document. (See Assemble a Text or
Form Document.)

2. After providing the required answers, click the

Check Spelling button. If HotDocs finds any unrecognized words,

the Check Spelling dialog box appears. In the Answer being checked box, HotDocs shows a section of the text
that contains the misspelled word, which is highlighted. Options for working with the misspelled word appear below
it.

3. Make your selection, based on the options described in the following table:
To

Do This

Ignore the current instance Click Ignore.

of the word and continue
spell checking
Ignore all instances of the
word and continue spell
checking

Click Ignore All.

Correct only the current

instance of the word and
continue spell checking

Select an existing replacement from the Change to list (or type the replacement in
the Change to box) and click Change.

Correct all instances of

the misspelled word and
continue spell checking

Select an existing replacement from the Change to list (or type the replacement in
the Change to box) and click Change All.

Add the word to your

personal dictionary so
that the spelling checker
will not question the word
again

Click Add.

Display additional spelling

alternatives for the
unrecognized word

Click Suggest.

Change your spell

checking options, such as
which words the spelling
checker looks at and how
it determines whether
a word is a possible
replacement

Click Options. (You can also change your options at the HotDocs Options dialog
box. See Change Your Spell Checking Options.)

A deeper search takes longer but produces better possible replacements. If the
button is unavailable, HotDocs is searching at the deepest level.

Copyright 2010 HotDocs Ltd. All rights reserved

713

Help Topics for HotDocs Developer 10

Chapter 48: Working with Assembled Text Documents

Preview the Assembled Text Document
After assembling a text document, you can print the document, send it as an e-mail attachment, or save it as a word
processor file. However, once you perform any of these actions, the document is no longer associated with HotDocs. That
means any changes you make to the text of the document will not be updated in the answer file or template. Because
of this, it is helpful to preview the assembled document in the assembly window and make sure the information in the
document is accurate before you perform any of the aforementioned tasks.
Caution:
While the information in the Document Preview tab is shown accurately, the document may not be formatted
correctly, particularly in WordPerfect documents. To view the actual formatting, send the document to the word
processor. (See Send the Assembled Text Document to the Word Processor.)
Some template providers may not allow you to edit answers or text at the Document Preview tab. If not, these
commands will be disabled.
To preview an assembled text document

1. At the HotDocs library window, select a template and begin the assembly. (See Assemble a Text or Form
Document.)

2. After providing the required answers, click the Document Preview tab. The assembly window changes to show a
preview of the document. By default, answers that have not been entered are marked with asterisks (for example,
***Employee Name***). You can choose a different unanswered format, however. See Format Unanswered
Variables in a Document for details.

3. (Word users) Optionally, to edit an answer or document text, click the

Highlight Fields button, then double-click

on an answer field or section of editable text. (See Edit Answers at the Document Preview Tab and Edit Document
Text at the Document Preview Tab for details.)

4. Once you have verified that the document is correct, use any of the following commands to work with the assembled
document:
To

Do This

Save the assembled text

document to disk

Click the
Save Document button. (See Save an Assembled Text or Form
Document.)

Send the assembled text

document to the word
processor so you can see
it in its final format

Click the
Send Document button. (See Send the Assembled Text Document to
the Word Processor.)

Print the assembled text

document

Click the
Print Document button. (See Print an Assembled Text Document or
Print an Assembled Form Document.)

Close the assembly

window

Choose Close (File menu)

Note:
If an assembled text document contains any cross references, including a table of contents or index, you may need to
update the references once you send the document to the word processor. To do this, select all of the document text
(press Ctrl+A) and then press the F9 key.

Copyright 2010 HotDocs Ltd. All rights reserved

714

Help Topics for HotDocs Developer 10

Edit Answers at the Document Preview Tab

Note:
The ability to edit answers at the Document Preview tab is available to Microsoft Word users only. Additionally, this
option is available only if the template provider has allowed it.
If you are viewing the Document Preview tab, you can edit answers you've entered. Additionally, you can move from an
answer in the document to its question in the interview and vice versa. Seeing answers in the context of the document
helps you pinpoint errors and makes it easy for you to correct them without having to go back to the interview.
To help you review answers in the document, you can use the Document Navigation Bar. Just like the Interview
Navigation Bar, this toolbar can help you move between answers, unanswered fields, and matching answers.
Caution:
Some template providers may prohibit you from changing answers at the Document Preview tab. If so, the buttons
and commands that control this feature will be disabled.
To change answers while previewing the document

1. At the HotDocs library window, select a template and begin assembling the document. (See Assemble a Text or
Form Document.)

2. After providing the required answers, click the Document Preview tab. The assembly window changes to show a
preview of the document.

3. Click the

Highlight Fields button. This assigns colors to both answered questions and unanswered questions in
the document. (You can change the default colors assigned to answered fields as well as unanswered fields. See
Set Properties for Viewing Answers and Editable Text in the Assembled Document.)

4. Double-click on an answer field. A pop-up interview appears, showing the dialog in which the question is used.
5. Change your answer and click

Next or

Finish. The pop-up interview closes and the answer is updated in the

document.

6. Use any of the following commands to help you edit answers in the document:
To
Jump to the place in
the interview where the
question is asked

Do This
Caution:
Because of scripting in the template, sometimes you will not be able to move
between the Interview and Document tabs. HotDocs will warn you when this is
the case.
Place your cursor in the answer field and click the
button.

Go to Answer in Interview

While viewing the Interview tab, you can go to the place in the document where
the answer is merged. To do this, place your cursor in the answer field and click the
Go to Answer in Document button.
Move between answers in
the document

Click

Next or

Previous to move to the next or previous answer in the document.

Click the
Next Unanswered or Previous Unanswered button to move to the
next unanswered or previous unanswered question in the document.
Press Ctrl+M or Ctrl+Shift+M to move between matching answers in the document
(for example, those answers in the document that are exact matches). (You can also
press Shift as you click the

Copyright 2010 HotDocs Ltd. All rights reserved

Next or

Previous button.)

715

Help Topics for HotDocs Developer 10

To

Do This
Click
End or
document.

Beginning to go to end of the document or the beginning of the

Note:
If you experience a delay when changing answers in your document, click the
Document Instant Update
button (so it isn't pressed in). Then, when you change an answer, HotDocs will just update the field you are
editing (and any other fields that merge the exact same answer). Be aware, however, that turning
Instant
Update off may cause some of the information in the document to be out of date if you change answers. (You
can tell when the document is out of date by the appearance of the
Instant Update button. To update the
document, click the button again. (The document will automatically update if you attempt to save it, print it, or
send it to the word processor.)
Once your cursor is in an answer field, you can press Enter and the pop-up interview will appear.
If the template provider has allowed it, you can also edit the text of the document. See Edit Document Text at the
Document Preview Tab for details.

Copyright 2010 HotDocs Ltd. All rights reserved

716

Help Topics for HotDocs Developer 10

Edit Document Text at the Document Preview Tab

Note:
The ability to edit the text of an assembled document is available to Microsoft Word users only. Additionally, this option
is available only if the template provider has allowed it. (You can tell if the developer has made text editable by the
color of the document text. By default, editable text is green.)
After you finish answering questions in an interview and before you send the document to the word processor or save
it, you should review it. As you do, you may see that you need to change the language of a particular paragraph, or you
may need to change a word or phrase to fit your particular needs. If the template developer has allowed it, you can edit
the document text while viewing the Document Preview tab. Changes you make can be saved in an answer file so
that if you reassemble the document, those changes will be reapplied. (You can always send the document to the word
processor and make the changes there. However, those changes are specific to the word processor and will not be saved
to HotDocs.)
When you edit the text of the assembled document, the text appears in a pop-up window called the Document Text
Editor. This editor provides many of the text-editing tools you need, including font options, spell checking, printing, and
copying and pasting. As you edit, you can add new text or remove existing text. You can also change the formatting of
text.
Caution:
You cannot edit variable (or answer) fields at the Document Text Editor. To edit answers, return to the assembly
window and make the change at the Interview tab.
To edit the text of the document

1. At the HotDocs library window, select a Microsoft Word template and begin assembling the document. (See
Assemble a Text or Form Document.)

2. After providing the required answers, click the Document Preview tab. The assembly window changes to show a
preview of the document.

3. Click the

Highlight Fields button. Text in the document that can be edited changes color.

4. Place your cursor in an editable section of text and click the

Edit Document Text button (or double-click on the

text). The Document Text Editor appears. (If there are multiple sections of text you can edit, HotDocs may ask you
which section you want to edit.)

5. Edit the text using the commands in the Document Text Editor toolbar. (See Document Text Editor Toolbar for a
description of each command.)

6. When you are finished making your changes, click

Save and Close. The editor closes and your changes are

merged in the assembled document.

When you are finished reviewing the document, you can save your answers and the changes you made to the document
are saved to the answer file. Then, if you reassemble the document using that answer file, the document will update with
the changes you made.
Note:
To move between sections of editable text, click the
buttons in the navigation bar.

Next Editable Text or the

Previous Editable Text

You can choose specific colors for marking editable and edited text in the document. See Set Properties for
Viewing Answers and Editable Text in the Assembled Document.
When viewing the document in the Document Text Editor, if you click the Show Codes button, you will see
an extra paragraph mark at the end of the document. This paragraph mark is merged by the text editor and will

Copyright 2010 HotDocs Ltd. All rights reserved

717

Help Topics for HotDocs Developer 10

be deleted when you save your changes and the text is inserted back into the document. Because of this, do not
modify the paragraph mark.

Copyright 2010 HotDocs Ltd. All rights reserved

718

Help Topics for HotDocs Developer 10

View an Assembled Document in Markup View

Caution:
If you are not a template developer, please click here for a brief explanation of template development terms.
Understanding these terms will help you understand how the assembled document is marked up.
As you assemble Microsoft Word documents, there may be times when you want to assemble only a partial document
and then submit it to an attorney or peer for revisions or corrections. To make the document easier for a non-HotDocs
user to review, you can change the formatting of the document to Markup View and then provide the reviewer a copy of it.
When displaying markup, HotDocs replaces unanswered fields and instructions in the document with markup, which
includes markers (such as brackets) and variable names. How the resulting markup fields look depend on the type of
fields they are:
Answer fields: By default, answer fields are marked using brackets. If the template developer has assigned a
comment to the variable, the comment text may be used as the field name. If no comment is used, HotDocs will use
either the title or the name the template developer assigned to the variable.
Conditional and repeated text blocks: By default, conditional and repeated text blocks are marked using brackets.
If a comment is assigned to these text blocks, the comment can be merged in the field label. If no comment is
assigned, HotDocs will simply merge the field markers around the text block. The text block can be marked using an
annotated footnote or endnote (depending on your preferences).
Insertion fields: HotDocs will merge the file name of the template being inserted.
Once you assemble the document using as many answers as needed, you can switch to Markup View and save a copy of
the document. You can then provide a copy of it to the reviewer.
To view a document in Markup View

1. Define the Markup View options you want to use in the document. (See Specify How Documents Should Be Marked
Up.)

2. Assemble the Word document for which you want to generate markup.
3. Answer only the questions whose answers you want to appear in the assembled document. Leave all other
questions unanswered. (These unanswered questions are the fields that will be marked using the scheme you define
in step 1.)

4. Choose Markup View (View menu). The document changes to show the marked up document.
Note:
By default, merge fields in the document appear in colorred for unanswered questions and blue for answered
questions. Sometimes, however, if an answer field is within a text block that is conditional or repeated, it appears
(and remains) blue until the condition is met or the REPEAT instruction is answered. Editable text likewise
appears using the colors you've defined at HotDocs Options.
Additionally, merge fields in the document are italicized by default. If you've used international characters in your
answers, the italicized version of the font used in the document may not display the foreign characters correctly. If
this is the case, clear the Italic attribute for Markup View. See Specify How Documents Should Be Marked Up for
details.
If the template developer has used merge fields in question prompts, those merge fields can be displayed as
markup fields. (Choose Markup View (View menu) while at the Interview tab.) Additionally, you can switch to
Markup View while assembling form documents.
To view a non-marked up version of the assembled document again, clear Markup View (View menu).

Copyright 2010 HotDocs Ltd. All rights reserved

719

Help Topics for HotDocs Developer 10

Send the Assembled Text Document to the Word Processor

Once you complete an interview, you often want to view the document in its final format. For text documents, this must be
done in the word processor.
To send the assembled text document to the word processor

1. At the HotDocs library window, select a template and begin assembling the document. (See Assemble a Text or
Form Document.)

2. After providing the required answers, click the

Send Document to the Word Processor button. The word

processor appears, showing the assembled document.

3. Using the word processor's tools, modify the document. Be aware, however, that any changes you make to answers
in the document will not be reflected in the answer file.
Note:
If you have more than one word processor installed, you can choose which word processor will be used for
viewing assembled documents. See Change Your Default Word Processor for details.
You can preview a text document at the Document Preview tab. While this preview shows the information in the
document correctly, it may not be formatted correctlyparticularly in WordPerfect documents.
If the template provider has allowed it, you may be able to edit the text of the document while still viewing it in the
assembly window. For details, see Edit Document Text at the Document Preview Tab (Word users only).

Copyright 2010 HotDocs Ltd. All rights reserved

720

Help Topics for HotDocs Developer 10

Open a Saved Text Document for Editing

After assembling and saving a document, you can later edit the document using the appropriate program:
Text documents are saved as word processor files (.DOC, .WPD, or .RTF). To edit these files, you must use a word
processor.
Form documents are saved as HotDocs form files (.HFD or .HPD). To edit these files, you must use HotDocs Filler.
See Edit a Saved Form Document for instructions on completing these actions.
To open a saved text document using Windows Explorer
Using Windows Explorer, locate the document file and double-click it. Your word processor appears, showing the
saved document.
To open a saved text document using the word processor
Using your word processor program's commands, locate and open the desired document file.
Caution:
When an assembled document is saved, the file is separated from the template file, component file, and answer file
that created it. This means that changes you make to a saved document are not reflected in the answer file used
to assemble that document. Finally, if you do make changes to the document, you must identify and change each
instance of the answer manually, including re-evaluating any computations or conditions affected by changed answers.

Copyright 2010 HotDocs Ltd. All rights reserved

721

Help Topics for HotDocs Developer 10

Print an Assembled Text Document

Many projects require you to print copies of assembled documents.
To print an assembled text document

1. At the HotDocs library window, select a template and begin assembling the document. (See Assemble a Text or
Form Document.)

2. After providing the required answers, click the Document Preview tab. The assembly window changes to show a
preview of the document.

3. Click the

Print Document button. The document is printed at the printer you specify.

Copyright 2010 HotDocs Ltd. All rights reserved

722

Help Topics for HotDocs Developer 10

Save an Assembled Text or Form Document

Some projects may require you to save an electronic copy of every document. Also, you may need to move the document
to a disk or laptop, so you can take an editable, printable version of the document to another location.
Caution:
When you save a text or form document, the file is separated from the answer file, so any changes made to a saved
document are not saved to the answer file.
To save an assembled text or form document

1. At the HotDocs library window, select a template and begin assembling the document. (See Assemble a Text or
Form Document.)

2. After providing the required answers, click the

Save Document button in the toolbar or at the End of Interview

dialog. The Save As dialog box appears.

3. Navigate to the folder where you want the document to be saved.

4. In the File name box, enter a name for the document and click Save.

Copyright 2010 HotDocs Ltd. All rights reserved

723

Help Topics for HotDocs Developer 10

Save Assembled Text Document as PDF

With HotDocs Developer, you can use the PDF printer driver to save assembled text and form documents as PDF
documents. Creating PDF files allows you to take advantage of features available in Adobe Acrobat.
To save a document as PDF

1. At the HotDocs library window, select a text template and click

Assemble. (See Assemble a Text or Form

Document.)

2. Answer questions in each dialog.

3. After answering all of the questions, choose Save Document As (File menu). The Save As dialog box appears.
4. Specify the file name and folder path for the file.
5. At the Save as drop-down list, make sure PDF File (*.pdf) is selected.
6. Optionally, click Security to assign any security options you need to the document. (See Assign Security Options to
a PDF Document.)

7. Click Save. The Convert to PDF dialog box appears.

8. Optionally, you can add information about the document's title, subject, author, or search keywords. Otherwise, click
OK. The assembled document is saved in PDF format.
Note:
Information you type in the Convert to PDF dialog box is saved as metadata embedded in the PDF-based file.
HotDocs does not use this information, but other programs that work with PDF files may access this metadata. (For
instance, if you open a PDF or PDF-based form template in Adobe Acrobat, you can select Document Properties
(File menu) to see the values in these fields.) For form templates, the values input here will also be set in any PDF
documents assembled with that template.

Copyright 2010 HotDocs Ltd. All rights reserved

724

Help Topics for HotDocs Developer 10

Save Assembled Form Document as PDF

With HotDocs, you can use the PDF printer driver to save assembled PDF form documents as PDF documents. Creating
PDF files allows you to take advantage of features available in Adobe Acrobat.
To save assembled PDF forms as PDF

1. At the HotDocs library window, select a PDF template and click

Assemble. (See Assemble a Text or Form

Document.)

2. At the End of Interview dialog, click Save the assembled document as a PDF. The Save As dialog box appears.
3. Specify the file path and name for the PDF file, and select PDF File (*.pdf) from the Save as type drop-down list.
4. Optionally, click Security to assign any security options you need to the document. (See Assign Security Options to
a PDF Document.)

5. Click Save. The Convert to PDF dialog box appears.

6. Optionally, you can add information about the document's title, subject, author, or search keywords. Otherwise, click
OK. The assembled document is saved in PDF format.
Caution:
If the file you're using to create a PDF document is a form document, the answer fields and other HotDocs features
are removed. Only the current answers are shown as static text on the PDF document. If you may need to edit the
answers later, you should first save the file as a PDF-based form document (.HPD), then save another copy of the file
as a PDF.
Note:
Information you type in the Convert to PDF dialog box is saved as metadata embedded in the PDF-based file.
HotDocs does not use this information, but other programs that work with PDF files may access this metadata. (For
instance, if you open a PDF or PDF-based form template in Adobe Acrobat, you can select Document Properties
(File menu) to see the values in these fields.) For form templates, the values input here will also be set in any PDF
documents assembled with that template.

Copyright 2010 HotDocs Ltd. All rights reserved

725

Help Topics for HotDocs Developer 10

Assign Security Options to a PDF Document

When creating PDF documents, you may want to protect the content of the document. You can do this by assigning
security options to the document.
To assign security options at the HotDocs Save As dialog box

1. Assemble a document. (See Assemble a Text or Form Document.)

2. Choose Save Document As (HotDocs File menu). The Save As dialog box appears.
3. Click the Save as type drop-down button and choose PDF File (*.pdf).
4. Click the Security button. The PDF Security Settings dialog box appears.
5. Make your selection, based on the following information (for additional information about each of these options, see
the Adobe Help file):
Select None to leave the document unprotected. No security options will be applied and the user can edit the
document (using Adobe Acrobat Professional).
Select 40-bit RC4 encryption to apply less-stringent security options to the document (and make the
document compatible with all versions of Adobe starting Adobe 3.x). (Selecting this option affects which options
are available in the rest of the dialog box.)
Select 128-bit RC4 encryption to apply more stringent security options to the document (and restrict use of
the document to Acrobat 5.x and later users). (Selecting this option affects which options are available in the
rest of the dialog box.)
Select Master password and enter (and confirm) the required password to require the user to enter a
password when changing security options for the document.
Select User password and enter (and confirm) the required password, require the user to enter a password
when attempting to open the document.
Select one of the printing options: Fully allowed, Low resolution only, and Not allowed to allow varying
levels of printing.
Clear Allow content copying and extraction to keep users from copying the text in the document and pasting
it into other applications.
Select Allow access for visually impaired to allow the document to be read out loud by Acrobat.
Select Allow content editing to let users can modify the pages of the document, including adding or removing
pages, or rotating pages to let users make changes to the document.
Select Allow page-level editing (insert, delete, rotate) to let users make changes to page properties of the
document (such as inserting pages).
Select Allow annotations to let users make comments or other notes in the document.
Select Allow form filling to let users enter information in Adobe fields on the form.

Copyright 2010 HotDocs Ltd. All rights reserved

726

Help Topics for HotDocs Developer 10

Chapter 49: Working with Assembled Form Documents

Overview: Assemble a Form Document
In most cases, you assemble a form document exactly as you assemble a text document. (See Assemble a Text or
Form Document.) However, HotDocs form documents provide some additional capabilities. For example, you can enter
answers directly in the form document, moving from field to field. You can also print a blank copy of the form that can be
completed by hand. Finally, you can create and modify an addendum to save answers that require more space than the
form provides.

Copyright 2010 HotDocs Ltd. All rights reserved

727

Help Topics for HotDocs Developer 10

Enter Answers Directly at the Form Document Tab

When assembling text documents, you answer questions in the interview and those answers are merged into the
document. When assembling form documents, however, you can either enter your answers in the interview or you can
enter your answers directly on the form document. This latter method of assembly is called direct-fill assembly. In some
cases, the template provider designs templates so that the only method for assembly is by direct-fill.
To enter your answers directly into the fields

1. At the HotDocs library window, select a form template and begin assembling the document. (See Assemble a Text
or Form Document.)

2. If you're not viewing it, click the Form Document tab. The assembly window changes to show the form document.
3. Click on a field and enter an answer.
4. Press Tab to move to the next field, or use the mouse to click on another field.
As you tab between fields, HotDocs will skip any conditioned fields that have been resolved in such a way that it isn't
necessary to answer the field.

5. Optionally, you can perform any of the following tasks:

To

Do This

Create a new field on the

document

Click the

Add additional answers to

a table

If the template developer has included it, click the

field.

Table Wizard button next to the

Answer questions that

compute the answer
for a field or control the
inclusion of other answers

If the template developer has included it, click the

the field.

Answer Wizard button next to

Show or hide the colored

fields

Click the

Quickly browse through

the pages of a form
document

Click the
Show Thumbnails button. This displays small images of each page in
the document in the left margin of the form view. You can click one of these images
and go to that page immediately.

Jump to a specific page of

the assembled document

Choose Go To (Edit menu) and enter the page number of the page you want to view.

Move through the answers

in a document

Place your cursor in a field and click one of the following navigation buttons: (If the
Form Navigation Bar isn't showing, choose it at the View menu.)

Select Tool button and draw the field. (See Create a Form Field.) To

enter text in the field click on the

Fill Tool and then click in the field.

Show Fields button.

Clicking Next or
document.

Previous moves you to the next or previous answer in the

Clicking the
Next Unanswered or Previous Unanswered button moves
you to the next unanswered question in the document
Pressing Ctrl+M or Shift+Ctrl+M moves between matching answers in
the document (for example, those answers in the document that are exact
matches). (You can also press Shift as you click the
button.)

Copyright 2010 HotDocs Ltd. All rights reserved

Next or

Previous

728

Help Topics for HotDocs Developer 10

To

Do This
Clicking
End or Beginning to go to the end of the document or the
beginning of the document.

Note:
To access answer wizards, table wizards, and calendars during direct-fill assembly, right-click on the field and
choose the option from the shortcut menu. For example, to view the calendar for a date field, right-click on the
field and choose Calendar from the shortcut menu.
Some answers may be too large to fit in the field. If this happens, HotDocs warns you by displaying the Overflow
Options dialog box. See Check Form Fields for Answer Overflow. Similarly, you can specify when this warning
should appear. See Set Rules for Handling Answer Overflow.

Copyright 2010 HotDocs Ltd. All rights reserved

729

Help Topics for HotDocs Developer 10

View the Assembled Form Document

Before saving the assembled form document, it is a good idea to review the document. You can do this at the Form
Document tab of the assembly window. Doing this allows you to make changes to answers in the document and have
those changes automatically updated in the answer file.
To view assembled form documents

1. At the HotDocs library window, select a template and begin assembling the document. (See Assemble a Text or
Form Document.)

2. After answering the questions in the interview, click the Form Document tab. The assembly window changes to
show the assembled document.

3. Optionally, select a field and enter a different answer. (See Enter Answers Directly at the Form Document Tab.)
4. Once you have finished entering answers, complete any of the following options:
Click the
Save Document button to save the assembled form document to disk. (See Save an Assembled
Text or Form Document.)
Click the
Print Document button to print the assembled form document. (See Print an Assembled Form
Document.)
Click Send Document To > Mail Recipient (File menu)to attach the assembled form document to an e-mail
message. (See Attach a Text or Form Document to an E-mail Message.)
Click Close (File menu) to close the assembly window. HotDocs prompts you to save any changed answers.
Note:
See Overview: Assemble a Form Document for a list of changes you can make to an assembled form document.

Copyright 2010 HotDocs Ltd. All rights reserved

730

Help Topics for HotDocs Developer 10

Assemble a Fillable PDF Document

Some form templates you assemble can be saved as fillable PDF documents. Fillable PDF documents allow users to
enter answers on the form while editing the form in Adobe Acrobat or Reader.
The process of assembling a fillable PDF is nearly the same as the process for assembling a regular form documentyou
can enter answers in the interview or type your answers directly on the form at the Form Document tab. You can also
choose to save the assembled document as a HotDocs form document, a regular PDF, or a fillable PDF. If you plan to
save the assembled document as a fillable PDF, however, there are a few things you should understand:
Adobe Acrobat/Reader does not support the creation of an addendum when an answer overflows its field. If a field
overflows in HotDocs, Adobe may attempt to force the answer to fit in the field when you save it as a fillable PDF. If
the answer doesn't fit, it will simply appear cut off. If possible, you should review the assembled document for any
field overflow before sending it to Adobe so that you can minimize the chance answers won't appear correctly in the
field. See Check Form Fields for Answer Overflow for details.
When viewing the document in HotDocs, some answers may appear differently than when viewing the assembled
document in Adobe Acrobat/Reader. This is because the underlying Adobe fields may have formats or patterns
assigned to them that are different than what was assigned in HotDocs.
If you create additional fields on the assembled document, any text you enter in the fields will appear as static text
when you save the document as a fillable PDF.
If you change the properties of an existing fillable field, those changes will not be honored when you save the
document as a fillable PDF.
To assemble a fillable PDF document

1. Follow the instructions for assembling a form document in Assemble a Text or Form Document.
2. Complete the interview. (See Navigate Through Answer-Gathering Dialogs.)
3. At the Form Document tab, review your answers.
4. Choose Check for Overflow (Tools menu) and resolve any fields that overflow.
5. Click the

Save Document button. The Save As dialog box appears

6. Click the Save as type drop-down button and select Fillable PDF Form from the list of options.
7. Enter a name in the File name box and click Save. The document is saved.
Once you save the document, you should review it to make sure the answers appear correctly.
Caution:
When creating a fillable PDF document, form designers can enable usage rights within the document. These rights
allow Adobe Reader users to save copies of the document with changes they have made to the documentincluding
entering or changing answers they have entered in the fillable PDF. However, when a rights-enabled fillable PDF is
converted to template format, the document is changed in such a way that usage rights are no longer in effect. This
means that you will not be able to save changes you make when editing the assembled document in Adobe Reader.

Copyright 2010 HotDocs Ltd. All rights reserved

731

Help Topics for HotDocs Developer 10

Override an Answer in a Form

In a HotDocs form document, fields are designed to hold certain types or formats of information. However, there may be
times when you need to enter a type of answer that HotDocs won't allow. You can override the field type and enter any
answer you need.
For example, a field with a Number variable attached to it is designed to hold only digits. However, if the number you enter
(say, $325,000,000) is too large for the field, but you don't want to send the answer to the addendum, you can override
the field and enter $325 m.
Answers entered in overridden fields are not saved in the answer file. The original answer is saved in the answer file and
used in any computations or other fields that require it.
To override an answer

1. At the HotDocs library window, select a form template and begin assembling the document. (See Assemble a Text
or Form Document.)

2. After entering answers, click the Form Document tab. The assembly window changes to show the document.
3. Select the field you want to override.
4. Click the

Override Field button and, at the Override Field warning message, click OK. The assembly window
appears again.

5. In the field, enter the answer you want, then move to a different field. The overridden field changes to gray.
To remove the overridden answer, select the field and click the
Override Field button again. The current answer is
removed and the saved answer reappears. Removing the override, however, may create answer overflow situations. See
Check Form Fields for Answer Overflow for details.

Copyright 2010 HotDocs Ltd. All rights reserved

732

Help Topics for HotDocs Developer 10

Print an Assembled Form Document

Many projects require you to print copies of assembled form documents. The options available for printing a form depend
on which type of form you are printing. Specifically, you can print:
HotDocs form documents (or .HFDs).
HotDocs PDF documents (or .HPDs).
To print a form document

1. At the HotDocs library window, select a template and begin assembling the document. (See Assemble a Text or
Form Document.)

2. After providing the required answers, click the Form Document tab. The assembly window changes to show the
assembled document.

3. Click the

Print Document button.

4. If you are printing a HotDocs form document (or .HFD file), select any of the following printing options. (If you're
printing a PDF form document, skip to step #5.)
To print the form and answers, select Form with Answers in the Output group.
To print only the static text of the form, select Form Only (Blank Form) in the Output group.
To print the answers onto a pre-printed copy of the form, select Answers Only (Use Preprinted Form) in the
Output group.
To change the double-sided printing options, select the desired option. Single-sided prints the document using
one side of each sheet of paper. Double-Sided, Side-to-Side prints the document with the tops of both pages
at the same end of the paper, like a traditional book. Double-Sided, Top-to-Bottom, prints the document with
the bottom of the second page at the same end as the top of the first page, like a flip-chart.

5. If you are printing a PDF form document (or .HPD file), you must choose whether to print using the functionality
of HotDocs or Adobe Acrobat. (See Print PDF-Based Documents Dialog Box for tips on which printing option you
should choose.)
Choose HotDocs, which prints at a slower speed but provides a wider range of printing options.
Choose Adobe Acrobat, which prints at a faster speed but provides few printing options.
Some types of printers have been known to cause problems when printing a form template or document, and should be
tested before use with finished products. These printers include:
Ink jet printers
Brother printers
16-bit postscript printer drivers
DeskJet printers
Xerox printers
"All-in-one" printers (printers that include copying, scanning, printing, and faxing capabilities)
For best results, it is recommended that you use an HP LaserJet with at least two megabytes of memory.

Copyright 2010 HotDocs Ltd. All rights reserved

733

Help Topics for HotDocs Developer 10

Choose Default Form Printing Options for a Form

Different forms may require different printing settings. You can specify that a form should be printed single-sided, doublesided side-to-side, or double-sided top-to-bottom. You can also control what size of paper to use as well as which paper
tray should feed the paper to the printer.
The option you specify is set as the default in the Print dialog box, but users can select a different option.
To specify form printing options

1. Edit a form template. (See Edit a Form Template.)

2. Click File > Template > Printing. The Printing Properties dialog box appears.
3. Select the printing settings from the following options:
Single-sided prints the document using one side of each sheet of paper (default setting).
Double-sided, side-to-side prints the document double-sided, with the tops of both pages at the same end of
the paper. (This option allows you to turn through the pages like a traditional book.)
Double-sided, top-to-bottom prints the document double-sided with the bottom of the second page at the
same end as the top of the first page. (This option allows you to turn through the pages like a flip chart.)
Paper size specifies the dimensions of the paper used to print the document.
Paper source specifies what tray of paper is used to print the document.
Note:
You can specify the print setting for all forms you create at the HotDocs Options dialog box. (See Overview:
HotDocs Options.)
You can use command-line options to control the paper size and paper source. (See Paper Size and Paper
Tray.)

Copyright 2010 HotDocs Ltd. All rights reserved

734

Help Topics for HotDocs Developer 10

Edit a Saved Form Document

After assembling a form document, you often need to save the document to disk. Once saved, you can re-open the
document using HotDocs Filler.
Once a form document is saved to disk, it is no longer associated with the answer file. This means that changes you make
to answers in the document do not affect the answer file. If you want to save changes you're making to the answers, reassemble the form document and change your answers in the interview. Then save your answer file again.
To work with a saved form document in Filler

1. Using Windows Explorer, locate and double-click the appropriate form document. HotDocs Filler appears, showing
the form document.

2. Optionally, you can perform any of the following tasks:

To

Do This

Change an answer in a
field

Click on a field. The field becomes active, allowing you to enter an answer.

Create new fields

Caution:
You can edit answers in a saved form document, but you must re-evaluate any
computations or conditions affected by changed answers. Similarly, changes you
make are not reflected in the answer file used to assemble the document.
With the

Select Tool button selected, press the left mouse button and move the

mouse pointer to draw a rectangle. To type in this field, select the

Fill Tool button.

The fields you create in Filler have no variable associated with them. They are simply
text boxes where you can type information.
Print the document

Click the

Print button.

Open a different HotDocs

form file

Click the
+O.)

Open button, and then locate the desired file. (You can also press Ctrl

3. Once you have the assembled form document open for editing, there are several other things you can do. For
example, you can:
Change the field type. (See Change the Field Type.)
Change the size of a field. (See Resize Form Fields.)
Change the position or margins of a field. (See Move a Field on a Form and Change the Borders and Margins
of a Field.)
Create a new answer field. (See Create a Form Field.)
Rotate text in a field. (See Rotate Answers in a Field.)
Convert answers on the form to bar code format. (See Convert Answers on the Form to Bar Code Format.)
Insert a graphic into a field. (See Insert a Graphic File in a Form.)
Cross out static text on the form. (See Cross Out Static Text on the Form.)
Circle static text on a form. (See Circle Static Text on a Form.)

Copyright 2010 HotDocs Ltd. All rights reserved

735

Help Topics for HotDocs Developer 10

Create a Form Field

Before You Begin:
These instructions can also be used to create a form field at both the Form Document tab of the assembly window
and in HotDocs Filler.
The first step in automating a form template is creating HotDocs fields at each place on the form where a user's
information must be merged.
When you create a field, HotDocs determines the type of field you are creating based on the size of the fieldif a field is
smaller than a certain dimension, HotDocs creates a check-box field. If a field is larger, then it creates an edit field. (You
can define these dimensions at HotDocs Options. See Set Properties for New Edit Fields.) Additionally, once you create
the field, you can make it a Resource hyperlink or a Control field.
Sometimes when you create a field, HotDocs can detect the borders of the underlying form and adjust its size to fit within
those borders. This helps ensure the field fits best in the space allotted. See Detect Borders to Create or Resize a Field.
Once a field is created, you can attach a variable to it.
Note:
Please see Detect Fillable Fields in a PDF Template for information on working with fields in a template created from a
fillable PDF.
To create a form field

1. Edit a form template. (See Edit a Form Template.)

2. Click the

Select Tool button.

3. Position the mouse pointer at one end of the intended field.

4. Press and hold down the left mouse button, then drag the pointer to the opposite corner of the field.
5. Release the mouse pointer. The field is created.
6. Optionally, click Detect to have HotDocs adjust the size of the field to more closely match the underlying static line
or lines.

7. Optionally, you can customize the appearance of your fields in the following ways:
Attach a variable to the field. (See Attach a Variable to a Field.)
Change the field type. (See Change the Field Type.)
Adjust the size. (See Resize Form Fields.)
Change the field's position on the form. (See Move a Field on a Form.)
Make a field conditional so the variable is asked only if a condition is true. (See Make a Field Conditional.)
Note:
To move multiple fields once they have been created, select the fields and press the arrow key that indicates
which direction you want to move them. To move fields more quickly, press the Shift key while pressing the
arrow keys.
You can also create a standard-size field by double-clicking on the form. Or, you can click to set the field crosshair and press F8.

Copyright 2010 HotDocs Ltd. All rights reserved

736

Help Topics for HotDocs Developer 10

Select a Field
Before You Begin:
These instructions can also be used to select fields both at the Form Document tab of the assembly window and in
HotDocs Filler.
In order to work with a field, you must first select it. When you select a field, handles appear on the field borders showing
that you can edit the borders or other properties. You can select a single field to work with, or you can select multiple
fields to group them or to make the same change to all of the fields.
To select fields

1. Edit a form template. (See Edit a Form Template.)

2. Click the

Select Tool button

3. Click on the field you want to work with.

4. Optionally, to select multiple fields, either press the Ctrl key while clicking each field, or press the Shift key, then
press the mouse button and drag the mouse pointer to create a bounding frame. All fields included in or touched by
this frame will be selected.

5. Use any of the following additional methods for selecting fields or canceling the selection, as described in the
following table:
To

Do This

Select all the fields on the

current page

Click Select All (Edit menu). (You can also press Ctrl+A.)

Cancel the selection of all

selected fields

Click outside the fields, or press the Esc key.

Cancel the selection of

only one of a group of
selected fields

Hold down the Ctrl key and click that field.

Add fields to your group

of selected fields without
canceling the selection of
those already selected

Hold down the Ctrl key and click the new fields.

Note:
If you have trouble selecting the field you want, the field may be in a group. If this is the case, you must first
ungroup the fields by clicking Ungroup (Field menu). (See Ungroup Form Fields.)
Click the

Show Fields button to show and hide field colors.

Copyright 2010 HotDocs Ltd. All rights reserved

737

Help Topics for HotDocs Developer 10

Create a Check-Box Field

Before You Begin:
These instructions can also be used to create check-box fields at the Form Document tab of the assembly window
and in HotDocs Filler.
Some forms include check boxes for users to mark. Check boxes can represent either true/false (or yes/no) options, but
they can also represent several predefined options for users. By default, HotDocs merges an X in a check box to indicate
that it has been selected, but you can define a different check-box character.
Note:
Please see Detect Fillable Fields in a PDF Template for information on working with fields in a template created from a
fillable PDF.
To create a check-box field

1. Edit a form template. (See Edit a Form Template.)

2. Where the check box appears on the form, double-click within the field borders, or click the

Detect Field button. A

check-box field is created.

3. Attach a variable to the field. Your options include True/False and Multiple Choice.
Note:
When assigning a True/False variable, if you want to merge a character other than an X, indicate the character
by specifying it as a variable format. See Customize a True/False Variable for details. To change the font for the
field, see Set Properties for New Check-Box Fields. When assigning a Multiple Choice variable, you should group
the fields before attaching the variable. See Group Form Fields So Answers Can Flow From One Field to Another
for details.

4. Optionally, specify a condition to make the field dependant on other answers in the form. (See Make a Field
Conditional.)
Note:
You can change the default measurements used to identify new fields as check boxes. You can also specify a
default character other than X to be used when selecting check-box fields. (See Set Properties for New CheckBox Fields.)
If HotDocs creates an Edit field, rather than a Check-box field, select the field, click the
button, and choose Check box as the Field type.

Copyright 2010 HotDocs Ltd. All rights reserved

Field Properties

738

Help Topics for HotDocs Developer 10

Detect Borders to Create or Resize a Field

Before You Begin:
These instructions can also be used to detect field borders both at the Form Document tab of the assembly window
and in HotDocs Filler.
When you create fields on a form, you often use the underlying static text as a guide as to where the field should be
placed. Often, you want the borders of the fields to match the borders of the static text. To help you align these borders,
you can use the
Detect feature. This feature is useful both when you create a new field and when you need to resize a
field to fit within its allotted space.
If HotDocs is unable to automatically create or resize a field to the size and position you want, you must create the field
manually. Several factors may contribute to these difficulties:
Insufficient surrounding features: To detect a field, HotDocs searches for surrounding features, such as lines,
text, or graphics. If there are insufficient surrounding features, HotDocs may have difficulty detecting a field. In such
cases, HotDocs creates a field of the default size.
Label text: When label text is inside the field area and there is enough space between the text and the bottom of
the field area, the
Detect command will extend the field up to the bottom of the label text. If you want the field to
occupy the area to the left or right of the label, or if you want to include the label inside the field, you must create the
field manually.
Field not completely visible: If part of the intended field is not visible (for example, it's scrolled out of the window),
HotDocs attempts to scroll to detect the field. It is recommended that you use a zoom level such as
Width so HotDocs can find the entire field on the screen.

Fit Page to

To detect the borders of the underlying static text

1. Edit a form template. (See Edit a Form Template.)

2. On the form, complete one of the following steps:
If the field is already created, select the field and click the

Detect button.

If you are creating a new field, place your cursor where the new field should be created and click the
button.

Detect

Caution:
If you are working with linked fields in a fillable PDF template and you plan to save the document assembled from the
template as a fillable PDF, any changes you make to the linked field will not be honored in the saved fillable PDF. See
Detect Fillable Fields in a PDF Template for details.

Copyright 2010 HotDocs Ltd. All rights reserved

739

Help Topics for HotDocs Developer 10

Move a Field on a Form

Before You Begin:
These instructions can also be used to move fields both at the Form Document tab of the assembly window and in
HotDocs Filler.
As you create fields on a form, you will frequently need to move the fields. You can do this using the mouse or keyboard.
You can also specify a precise location using the Field Properties dialog box.
To move a field using the mouse

1. Edit a form template. (See Edit a Form Template.)

2. Position the mouse pointer over the selected field. The cursor changes.
3. Hold down the mouse button and drag the field to the new position.
To move a field using the keyboard

1. Edit a form template. (See Edit a Form Template.)

2. Select a field. (See Select a Field.)
3. Press the arrow keys to move the field one unit of measurement in that direction. (To move the field more quickly,
hold down the Shift key as you press the arrow keys.)
To move a field using the Position/Size dialog box

1. Edit a form template. (See Edit a Form Template.) Edit a form document. (See Edit a Saved Form Document.)
2. Select a field. (See Select a Field.)
3. Click the

Field Properties button. The Field Properties dialog box appears.

4. Click the Additional tab. The view changes to show the positioning options.
5. In the Position group, enter the desired distance from the left and top margins of the page in the Left and Top
boxes. (You can also click the up or down arrows for each field to change the distance.)
Note:
If you are working with linked fields in a fillable PDF template and you plan to save the document assembled from
the template as a fillable PDF, any changes you make to the linked field will not be honored in the saved fillable
PDF. See Detect Fillable Fields in a PDF Template for details.
If a field you want to move is part of a group, you must first ungroup the fields. (See Ungroup Form Fields.)
The Field Properties dialog box includes the First, Previous, Next, and Last buttons to move you between
fields. When you have multiple fields selected, these buttons are not available.

Copyright 2010 HotDocs Ltd. All rights reserved

740

Help Topics for HotDocs Developer 10

Align Two or More Fields

When creating fields on a form template, you frequently need to align fields, either vertically or horizontally. Other times,
you may need to adjust the height or width of a group of fields so they match each other. Aligning fields can give forms
a more professional appearance, as well as minimize problems the user may experience when tabbing between fields
during direct-fill assembly.
To align fields in relation to each other

1. Edit a form template. (See Edit a Form Template.)

2. Select the fields you want to align. (See Select a Field.)
3. Click the

Align button. The Align Fields dialog box appears. (You can also right-click and choose Align from the
shortcut menu.)

4. Select an option in the Horizontal alignment group to align the fields horizontally, or the Vertical alignment group to
align the fields vertically. The Example box previews the selected alignment option.

5. Click OK. The template appears again, and the selected fields are repositioned.
To size fields in relation to each other

1. Edit a form template. (See Edit a Form Template.)

2. Select the fields you want to size. (See Select a Field.)
3. Click the

Align button. The Align Fields dialog box appears. (You can also right-click and choose Align from the
shortcut menu.)

4. Select the options you need from the Width group and/or the Height group. The Example box previews the
selected resizing options.

5. Click OK. The template appears again, and the selected fields are resized.
Caution:
If you are working with linked fields in a fillable PDF template and you plan to save the document assembled from the
template as a fillable PDF, any changes you make to the linked field will not be honored in the saved fillable PDF. See
Detect Fillable Fields in a PDF Template for details.

Copyright 2010 HotDocs Ltd. All rights reserved

741

Help Topics for HotDocs Developer 10

Change the Borders and Margins of a Field

Before You Begin:
These instructions can also be used to change the borders and margins of fields both at the Form Document tab of
the assembly window and in HotDocs Filler.
You can change the borders and margins of a form template field. Borders control the thickness of the field box, and
margins control the distance between the border of the field and the answer text.
To change field borders or margins

1. Edit a form template. (See Edit a Form Template.)

2. Select the field whose borders or margins you want to change.
3. Click the

Field Properties button. The Field Properties dialog box appears.

4. Click the Layout tab. The view changes to show layout options.
5. In the Borders and Margins groupings, make your selections. (Remember, borders affect the thickness of field
boxes, while margins affect the distance between the border of the field and the answer in the field.)
Caution:
If you are working with linked fields in a fillable PDF template and you plan to save the document assembled from the
template as a fillable PDF, any changes you make to the linked field will not be honored in the saved fillable PDF. See
Detect Fillable Fields in a PDF Template for details.

Copyright 2010 HotDocs Ltd. All rights reserved

742

Help Topics for HotDocs Developer 10

Copy One or More Form Fields

Before You Begin:
These instructions can also be used to copy and paste fields both at the Form Document tab of the assembly window
and in HotDocs Filler.
Frequently, you need to copy fields on a form. For example, say you need to create a group of fields that all have the
same properties. Rather than creating each field individually and modifying its properties, you can create a single field,
assign the properties, and then copy the field to create the others in the group.
When a field is copied to a new place in the same template, all the fields properties (size, font, line formatting, fill order,
etc.) are copied with it. Similarly, when variables, conditions, or REPEAT instructions are attached to fields, they are also
attached to the copied fields. However, if you copy fields from one template to another, the variables, dialogs, and other
components used in computations, conditions, or instructions are not copied to the new templates component file. You
must copy these items manually. (See Create and Edit Multiple Components Simultaneously or Use One Component File
for Multiple Templates.)
When you copy fields to a new location, the cursor position tells HotDocs where to paste the copied fields. If you copy a
single field, the lower-left corner of the field will be at the cursor position. Likewise, if you copy two or more fields at the
same time, the lower-left corner of an invisible boundary box drawn around all of the copied fields will be at the cursor
position. If there is no cursor, the field is pasted on top of the original.
You can copy fields on only one page at a time.
To copy and paste one or more fields

1. Edit a form template. (See Edit a Form Template.) Edit a form document. (See Edit a Saved Form Document.)
2. Select the field or fields you want to copy. (See Select a Field.)
3. Choose Copy (Edit menu). The field is copied to the Windows Clipboard. (You can also select the field and press
Ctrl+C, or you can right-click on the field and choose Copy from the shortcut menu.)

4. Place the mouse cursor where you want the lower-left corner of the copied field to be, and then click the mouse to
set the cross-hair.

5. Choose Paste (Edit menu). The copied field is pasted at that location. (You can also press Ctrl+V, or you can rightclick on the field and choose Paste from the shortcut menu.)
Note:
You can also copy a field by holding down the Ctrl key while dragging the field to its new location.
If you need to automate an updated version of the template, it may be easier to replace the static content, rather
than copy all of the fields. (See Update the Underlying Text in a Form Template.)
Note:
You can also copy a field by holding down the Ctrl key while dragging the field to its new location.
Caution:
If you are working in a fillable PDF template, remember that linked fields are associated with underlying fillable fields in
the PDF. If you plan to save the assembled document as a fillable PDF, answers associated with linked fields will only
be merged where there are fillable fields on the form. This means that you cannot copy a linked field to a new location
on the form and expect the answer to appear there in the resulting fillable PDF. If you want to use the same variable
somewhere else in the form, create a regular HotDocs field and assign it the same variable name as the fillable field.
Note, however, that in the fillable PDF, the answer will appear static.

Copyright 2010 HotDocs Ltd. All rights reserved

743

Help Topics for HotDocs Developer 10

Resize Form Fields

Before You Begin:
These instructions can also be used to resize fields both at the Form Document tab of the assembly window and in
HotDocs Filler.
You may need to adjust the size of a field to fit it into the available space on the form. You can change a field's size using
the mouse, the keyboard, or the Position/Size tab of the Field Properties dialog box.
To resize a field using a mouse

1. Edit a form template. (See Edit a Form Template.)

2. Select the field. (See Select a Field.)
3. Click a handle or field border. (When the mouse pointer is on a handle, the pointer changes to a double-arrow,
indicating the directions the border can be moved.)

4. Hold down the mouse button and drag the border to a new position.
To resize a field using the keyboard

1. Edit a form template. (See Edit a Form Template.)

2. Select the field. (See Select a Field.)
3. Press the Page Up or Page Down keys to move the top border of the field up or down, and the End or Home keys
to move the right border of the field right or left. (To resize the field more quickly, hold down the Shift key as you
press the keys.)
To resize a field using the Field Properties dialog box

1. Edit a form template. (See Edit a Form Template.)

2. Select the field. (See Select a Field.)
3. Click the

Field Properties button. The Field Properties dialog box appears.

4. Click the Additional tab and, in the Size group, enter the desired distance from the left and top borders of the field
in the Width or Height boxes. (You can also click the up or down arrows for each field to change the size.) The field
size is changed.
Caution:
If you are working with linked fields in a fillable PDF template and you plan to save the document assembled from the
template as a fillable PDF, any changes you make to the linked field will not be honored in the saved fillable PDF. See
Detect Fillable Fields in a PDF Template for details.

Copyright 2010 HotDocs Ltd. All rights reserved

744

Help Topics for HotDocs Developer 10

Change the Tab Order of Fields

Before You Begin:
These instructions can also be used to change the tab order of fields both at the Form Document tab of the assembly
window and in HotDocs Filler.
When determining the order to ask questions in the interview, HotDocs begins with the top-left field of the form and
processes all of the fields until it reaches the bottom-right field. This processing affects two thingsthe order questions
are asked in the default interview and the order in which the user is able to tab through fields on the form.
Because of this default field ordering, sometimes you may find your dialogs being asked out of order. You may also find
that the tab order during direct-fill assembly isn't working as you expect. Additionally, when automating a nontypical table,
you may need to change the order in which fields are asked.
Note:
Once you specify a fill order for one field, you must specify the order for every field you want processed after that
field. In effect, when you specify a fill order for just one field, you set that field to be answered last. This is because
all the other fields are still set to Row 0, Column 0they are lower than the Row 1 or Column 1 , so they will be filled
first. Therefore, to change the order of the fields in the middle of the form, you must also change the order for every
remaining field.
The following rules control field ordering:
Fill order is determined first by row, then by column.
All field values are initially set the sameRow 0, Column 0.
When fields have different row numbers, fields with lower row numbers are asked first, for example, Row 0, Column
0; Row 1, Column 0; etc.
When fields have the same row numbers, but different column numbers, fields with lower column numbers are asked
first, for example, Row 1, Column 0; Row 1, Column 1; etc.
Fill order is treated separately for each page of the templateyou cannot specify a fill order that runs from one page
to another.
To change the tab order for fields

1. Edit a form template. (See Edit a Form Template.)

2. Select the field. (See Select a Field.)
3. Click the

Field Properties button. The Field Properties dialog box appears.

4. Click the Additional tab. The view changes to show ordering options.
5. In the Row box, type the row number.
6. If you need to specify the order for fields in the same row, type a number in the Column box.
7. Optionally, at the Order dialog box, you can click the First, Previous, Next, or Last button to save the current field's
settings and display the next field's order.
By selecting and ordering different groups of fields, you can use fill order to handle various situations. For example:
Remove all fill order settings: Select all fields and set the Row and Column numbers to 0.
Organize large sections of fields: Select the desired fields and specify the order.
Flow answers across fields contrary to the default order (top to bottom, left to right): Set the desired order,
then group the fields. (See Group Form Fields So Answers Can Flow From One Field to Another.)
Fill table columns in an order different from the static text: Set the desired order, then group the fields as a
table.
Copyright 2010 HotDocs Ltd. All rights reserved

745

Help Topics for HotDocs Developer 10

Note:
To control when a variable is asked without changing fill order, you can use ASK instructions. For example, if you
simply want a particular field to be asked first even though it isn't the first field on the form, place an ASK instruction in
the top left corner of the page. (See Attach an ASK Instruction to a Field.)

Copyright 2010 HotDocs Ltd. All rights reserved

746

Help Topics for HotDocs Developer 10

Group Form Fields So Answers Can Flow From One Field to Another
Before You Begin:
These instructions can also be used to group fields for answer flow-through both at the Form Document tab of the
assembly window and in HotDocs Filler.
Sometimes an answer must begin in one field and continue in other fields. For example, you may have a Text variable
whose answer must span two or more pre-printed lines. You can create edit fields for each line, and then group the fields
so that answers flow from one field to another. Fields grouped this way are called run-on groups.
Once fields are grouped, HotDocs treats the group as a single field. This means that the Text variable and any conditions
for the variable will be assigned to the grouping, not the individual fields in the group.
Caution:
If you are automating a fillable PDF template and you plan to save the assembled document as a fillable PDF, you
cannot group fillable fields since necessarily, each fillable field is linked to a separate variable. Answersboth in
HotDocs and Adobemust be entered on individual lines. This means that when you reach the end of one field, you
must tab to the next field and continue typing your answer. (This inability to group fields is a limitation of Adobe. If you
have access to the form, you may consider replacing individual fields in the group with a single, multi-line field. Text
you enter may not match the lines perfectly, but you will not have to tab between fields to enter the answer.)
To flow an answer across multiple fields

1. Edit a form template. (See Edit a Form Template.)

2. Create all the text fields across which the answer should flow. (See Create a Form Field.)
3. Select all the fields that will be used for the answer. (See Select a Field.)
4. Click Group (Field menu). A bounding frame appears around the grouped fields. (You can also right-click and select
Group from the shortcut menu.)

5. Attach a variable to the grouped fields. (See Attach a Variable to a Field.)

Caution:
When fields are grouped, you cannot change properties for individual fields. You must first ungroup the fields. (See
Ungroup Form Fields.)
Note:
A form may require an answer to appear in a series of single-character fields or boxes (for example, a Social
Security number). To place one character or digit in each field requires additional formatting. See Attach a
Variable to Single-Character Boxes for details.
To group fields that appear on separate pages in the form, see Flow a Single Answer Across Two or More Pages
in a Form.
By default, HotDocs asks questions in the interview by reading fields in the form from left to right, top to bottom.
As it encounters a field, it asks the variable associated with it. If the variable is linked to a dialog, it asks the dialog
instead. When directly filling the form, HotDocs tabs through the form fields using this same method. However,
sometimes grouped run-on fields can create problems with the tab order. To ensure that text in a run-on group
flows in the correct order, you may need to specify a fill order for fields in the group. (See Change the Tab Order
of Fields.)

Copyright 2010 HotDocs Ltd. All rights reserved

747

Help Topics for HotDocs Developer 10

Ungroup Form Fields

Before You Begin:
These instructions can also be used to ungroup fields both at the Form Document tab of the assembly window and in
HotDocs Filler.
When fields are grouped, you cannot modify the individual fields. You must first ungroup the fields.
To ungroup the fields

1. Edit a form template. (See Edit a Form Template.)

2. Select one of the grouped fields. The whole group is selected. (See Select a Field.)
3. Click Ungroup (Field menu). (You can also right-click on the field and choose Ungroup from the shortcut menu.)
Some properties that were assigned to the group, such as text, margin, and line format properties remain applied to the
individual fields that made up the group. Other properties, such as a field order or a condition, are lost until you regroup
the fields. Regrouping the fields restores the properties that were previously applied to the group.
Caution:
Properties of a table, including the name of the repeated dialog, are attached to the first field in a table. Because of
this, you should not delete the first field in the group before you regroup the fields. Also, do not close the form before
you regroup the fields. If you do either of these things, these properties are lost.

Copyright 2010 HotDocs Ltd. All rights reserved

748

Help Topics for HotDocs Developer 10

Change the Field Type

Before You Begin:
These instructions can also be used to change the field's type at the Form Document tab of the assembly window and
in HotDocs Filler.
When you first create a field, HotDocs creates it as either an edit or check-box field, depending on the fields height and
width. Check-box fields are usually used to mark a yes/no response, while edit fields are used for questions that require
text, date, or number answers. In addition, you can assign some fields as control fields, which means users can't access
or edit the field during direct-fill assembly. You can also create resource fields, which can display helpful information about
the form.
Once you choose a field type, you can determine the type of answer that is merged in the field. Your options include text,
graphics, and bar codes. You can also use fields to cross out or circle static text on a document.
The following are the different types of fields you can create:
Type of Field

Default Color

Description

Edit

Yellow

Allows users to enter any type of answer,

including text, dates, numbers, multiple
choice options, or computed values. It is
the most commonly used field type.

Check Box

Blue

Allows users to select from two or more

options. Usually check-box fields are
associated with True/False variables or
Multiple Choice variables. Answers in a
check-box field are usually indicated by an
X or other character. (See Create a CheckBox Field.)

Resource

Orange

Allows users to view helpful information

about the form while directly filling the
form. Resource fields appear as hyperlinks
on the form. When users click the link,
a pop-up window containing the useful
information opens. (See Create a Resource
Link on a Form.)
Note:
Resource fields provide help for the
form in general, instead of for a specific
variable or dialog.

Control

Green

Allows you to complete "behind-thescenes" tasks in the template, such as

inserting templates or setting the values
of variables. If the field contains answer or
example text, it will be visible to users, but
users won't be able to access the field.

Note:
If you are working with a fillable PDF template, linked fields appear using a light blue color. This distinguishes them
from regular HotDocs fields. See Detect Fillable Fields in a PDF Template.
To change the field type
Copyright 2010 HotDocs Ltd. All rights reserved

749

Help Topics for HotDocs Developer 10

1. Edit a form template. (See Edit a Form Template.)

2. Create a new field (See Create a Form Field) or select an existing field. (See Select a Field.)
3. Click the

Field Properties button. The Field Properties dialog box appears.

4. At the Type tab, make your selection, based on the information in the table above.
Note:
You can change the default colors used for form fields at the HotDocs Options dialog box. (See Change Colors in
HotDocs Forms.)

Copyright 2010 HotDocs Ltd. All rights reserved

750

Help Topics for HotDocs Developer 10

Change the Font Used for a Field

Before You Begin:
These instructions can also be used to change the field's font properties both at the Form Document tab of the
assembly window and in HotDocs Filler.
You can choose the font that is used for answers on a form. When choosing the font, you can also indicate the style (for
example, bold or italics), size, effects, and color that are used.
As is always the case when working with fonts, if the form requires a specific font be used, you must ensure the font is
installed on all computers where the form will be viewed.
To change the font for a field or group of fields

1. Edit a form template. (See Edit a Form Template.)

2. Select the field or fields whose font you want to change.
3. Click the

Field Properties button. The Field Properties dialog box appears.

4. At the Type tab, click Font. The Font dialog box appears.
5. Make your font selections.
Note:
You can specify default font properties for all new fields you create at HotDocs Options. See Set Properties for New
Edit Fields for more details.
Caution:
If you are working with linked fields in a fillable PDF template and you plan to save the document assembled from the
template as a fillable PDF, any changes you make to the linked field will not be honored in the saved fillable PDF. See
Detect Fillable Fields in a PDF Template for details.

Copyright 2010 HotDocs Ltd. All rights reserved

751

Help Topics for HotDocs Developer 10

Format Lines and Paragraphs of Text in a Form Field

Before You Begin:
These instructions can also be used to format how text appears in a field both at the Form Document tab of the
assembly window and in HotDocs Filler.
Sometimes you need to format the text within a multi-line text field. For example, perhaps you need to indent the first line
of a paragraph, or maybe you need to adjust the number of lines that fit in an inch of vertical space. To do this, you can
adjust the line format of a field.
To format lines and paragraphs

1. Edit a form template. (See Edit a Form Template.)

2. Create a multi-line field.
3. Attach a multi-line Text variable to the field. (See Customize a Text Variable.)
4. With the field selected, click the

Field Properties button. The Field Properties dialog box appears.

5. Click the Layout tab. The view changes to show the different options for formatting the field.
6. In the Line Format group, complete one of the following options:
To

Do This

Indent the first line of text

in the paragraph

Enter how much space to include between the margin of the field and the first
character of the answer in the First line indent box. (You can either type the number
or click the up or down arrows.)

Force a certain number of

lines to appear in an inch
of space in the field

Enter the number of lines in the Lines per inch box.

Indicate how many lines

can appear in the field

Enter the number of lines in the Maximum lines box. If the answer contains more
lines than is specified, the field will overflow.

Indicate the maximum

number of characters that
can appear in a given line
of text

Enter the number of characters in the Max chars/line box. When the number of
characters exceeds this limit, text will wrap to the next line.

Caution:
If you are working with linked fields in a fillable PDF template and you plan to save the document assembled from the
template as a fillable PDF, any changes you make to the linked field will not be honored in the saved fillable PDF. See
Detect Fillable Fields in a PDF Template for details.

Copyright 2010 HotDocs Ltd. All rights reserved

752

Help Topics for HotDocs Developer 10

Rotate Answers in a Field

Before You Begin:
These instructions can also be used to rotate answers in an answer field both at the Form Document tab of the
assembly window and in HotDocs Filler.
By default, answers in fields appear in horizontal rows and can be read from left to right. You can rotate text so answers
will read from bottom to top, top to bottom, or upside-down from right to left.
To rotate text in a field

1. Edit a form template. (See Edit a Form Template.)

2. Select the fields you want to rotate. (See Select a Field.)
3. Click the

Field Properties button. The Field Properties dialog box appears.

4. Click the Layout tab. The view changes to show field layout properties.
5. In the Rotation group, select a degree of rotation: 0, 90, 180, or 270, for example:

Note:
You can enter test text in the test answer box (of the Type tab) to preview the selected rotation. See Preview the
Formatting of Answers in a Form Field.
When you change the rotation, HotDocs views the bottom of the letters as the bottom of the field. This means that
aligning the text horizontally or vertically may have different effects.
Caution:
If you are working with linked fields in a fillable PDF template and you plan to save the document assembled from the
template as a fillable PDF, any changes you make to the linked field will not be honored in the saved fillable PDF. See
Detect Fillable Fields in a PDF Template for details.

Copyright 2010 HotDocs Ltd. All rights reserved

753

Help Topics for HotDocs Developer 10

Keep Contents of Form Fields from Printing

Before You Begin:
These instructions can also be used to keep field text from printing at the Form Document tab of the assembly window
and in HotDocs Filler.
Sometimes you want field text to appear on the form during direct-fill assembly, but you don't want the text to appear
when you print a copy of the form. For example, if you create a resource field, you may not want the resource field text to
appear on the form when you print it. You can select an option that keeps this text from printing.
To designate that a field's contents shouldn't be printed

1. Edit a form template. (See Edit a Form Template.)

2. Create or select the field whose text you want to appear only on the form.
3. Click the

Field Properties button. The Field Properties dialog box appears.

4. At the Type tab, select Non-printing field.

Caution:
If you are working with linked fields in a fillable PDF template and you plan to save the document assembled from the
template as a fillable PDF, any changes you make to the linked field will not be honored in the saved fillable PDF. See
Detect Fillable Fields in a PDF Template for details.

Copyright 2010 HotDocs Ltd. All rights reserved

754

Help Topics for HotDocs Developer 10

Cross Out Static Text on the Form

Before You Begin:
These instructions can also be used to cross out static text on a form both at the Form Document tab of the assembly
window and in HotDocs Filler.
Sometimes a form includes static text that must be crossed out, depending on answers the user enters during the
interview. For example, say a form includes a list of medical conditions. Instructions on the form tell you to cross out any
conditions that do not apply to you. You could manually cross out these conditions once you've printed the form; however,
HotDocs allows you to create a strike-through field, which crosses out the text for you, depending on answers you enter
during the interview.
A strike-through field, which is transparent, overlays the static text. You can choose the character that will be used to
cross out the text.
To create a strike-through field in a form

1. Edit a form template. (See Edit a Form Template.)

2. Create a field that covers the static text on the form. (See Create a Form Field.)
3. Click the

Field Properties button. The Field Properties dialog box appears. (You can also right-click and select
Field Properties from the shortcut menu.)

4. Click the Type tab.

5. In the Field type group, select the type of field you want to associate with the strike-through field.
6. In the Display type group, select Strike-through.
7. In the Variable box, insert a True/False or Multiple Choice variable. This variable sets the conditions when static text
should be crossed out. (See Attach a Variable to a Field.)
True/False variable: Select an example format that merges the strike-through character when the variable is
true or false, as appropriate. (See Customize a True/False Variable.)
Multiple Choice variable: Type the strike-through character in the Merge Text field of the option that should
cause the strike through, and type NONE in the other choices. (See Customize a Multiple Choice Variable.)
Note:
You can use the alignment controls on the Field Properties dialog box to position the strike-through text more
accurately.
To change the font properties of the strike-through character, click the Font button at the Field Properties dialog
box and make your changes there.

Copyright 2010 HotDocs Ltd. All rights reserved

755

Help Topics for HotDocs Developer 10

Circle Static Text on a Form

Before You Begin:
These instructions can also be used to circle static text on a form both at the Form Document tab of the assembly
window and in HotDocs Filler.
Sometimes instructions on a form ask users to circle a preprinted option. Rather than make users print the form and
manually circle the option using a pen, you can create a form field that overlays a circle on the text. You can attach a
variable to the field so that the user can select which option should be circled during the interview. Creating circle fields
not only preserves the professional look of the form, but allows the answer associated with the selection to be saved in
the answer file.
To create a field that circles text

1. Edit a form template. (See Edit a Form Template.)

2. Create a field that covers the static option on the form you want to select. (See Create a Form Field.)
3. Click the

Field Properties button. The Field Properties dialog box appears. (You can also right-click and select
Field Properties from the shortcut menu.)

4. Click the Type tab.

5. In the Field type group, select the type of field you want to associate with the circled field.
6. In the Display type group, select Circled.
7. Assign a True/False or Multiple Choice variable to the field. (See Customize a True/False Variable, Attach a Multiple
Choice Variable to a Group of Check Boxes, and Customize a Multiple Choice Variable.)

8. Optionally, to control the width of the circle's border, click the Layout tab and change the Line thickness in the
Circle group.
Note:
To preview the circle (see Preview the Formatting of Answers in a Form Field), make sure you enter text in the
Answer text box of the Type tab.

Copyright 2010 HotDocs Ltd. All rights reserved

756

Help Topics for HotDocs Developer 10

Insert a Graphic File in a Form

Before You Begin:
These instructions can also be used to insert graphics in a form both at the Form Document tab of the assembly
window and in HotDocs Filler.
Sometimes you may need to include an image on your form, such as a signature or seal. You can create a field and
assign as one of its properties a graphic file. Supported file formats include .JPG, .BMP, and .PNG. Image files should be
saved to the same folder as the template.
You control the conditions under which the image appears on the form. For example, you can attach a Multiple Choice
variable or a True/False variable that merges an image file depending on which option a user chooses. Additionally, you
can make the field a control field so that users can't access the field directly.
To create a graphic field using a variable

1. Edit a form template. (See Edit a Form Template.)

2. Create a field (See Create a Form Field) and attach either a Multiple Choice or True/False variable to it. (See
Customize a Multiple Choice Variable or Customize a True/False Variable.)

3. If you're using a Multiple Choice variable, edit the variable and, in the Merge Text column, enter the file names of
the graphics, depending on which options the user chooses.

4. If you're using a True/False variable, edit the variable and, in the Format box, enter the file name of the graphic,
either preceded or followed by a forward slash (to indicate yes/no status).

5. Click OK at the variable editor and at the Variable Field dialog box.
6. With the field still selected, click the

Field Properties button. The Field Properties dialog box appears.

7. At the Type tab, select Image from the Display type group.
8. Optionally, change the Field type to Control to restrict the users ability to modify the field. (Change the Field Type.)
To create a graphic field without using a variable

1. Edit a form template. (See Edit a Form Template.)

2. Create a field. (See Create a Form Field.)
3. With the field still selected, click the

Field Properties button. The Field Properties dialog box appears.

4. At the Type tab, select Image from the Display type group.
5. Click the

Open button next to the Image file name box. The Open dialog box appears.

6. Locate and select the desired graphic file and click Open. The path and file name appear in the box.
7. Optionally, change the Field Type to Control to restrict the users ability to modify the field. (Change the Field
Type.)

8. Optionally, click the

Show Variables button in the Automator toolbar to view the image.

The image is visible at the Form Document tab.

Caution:
If you are automating a fillable PDF template and you plan to save the assembled document as a fillable PDF, you
cannot assign an image to a linked field. Instead, use a regular HotDocs field.

Copyright 2010 HotDocs Ltd. All rights reserved

757

Help Topics for HotDocs Developer 10

Convert Answers on the Form to Bar Code Format

Before You Begin:
These instructions can also be used to enter bar code text both at the Form Document tab of the assembly window
and in HotDocs Filler.
You can create a two-dimensional bar code field that displays a single answer or group of answers. This may be useful if
the organization to which you submit your documents requires certain data in the document be in bar code format. This
allows the organization to scan the information and save it in some data retrieval system, such as a database.
For example, say you must submit a form to the court. When the court files the form, rather than manually entering
case information (such as party names, case numbers, etc.), it can simply scan the bar code and have the information
automatically entered in the system.
Typically, bar codes display data in a pattern of lines and formats, which should be readable by most hand-held laser
scanners or charge-coupled device (CCD) scanners. The scanner should be able to read the size of the bars, which is
0.01 inch.
Use the following tips when working with bar codes:
The format HotDocs uses for bar codes is PDF417, or Portable Data File 417. It is one of several recognized 2-D bar
code formats.
Bar codes in HotDocs can store about 1,500 characters, including numbers and other standard text symbols.
Printing a form that has a bar code requires a high-density printer, such as a laser printer.
Bar code fields can overflow, but all overflow properties assigned to the field are ignored. When too much text is
entered for a bar code, no bar code appears. If you are having trouble getting the bar code to fit in the field, you
can enlarge the field or reduce the field margins. (See Resize Form Fields or Change the Borders and Margins of a
Field.)
There are two methods for creating a bar code:
Create a bar code using a variable: When the answers you want to convert to a bar code must be supplied by the
user, you can create a variable, such as a Computation variable, which will then merge the answers in the field and
convert them to bar code format.
Create a bar code using predefined text: If the bar code text is always the same, regardless of who is completing
the document, you can enter that text at the Field Properties dialog box.
To create a bar code using a variable

1. Edit a form template. (See Edit a Form Template.)

2. Create a field and attach a variable to it, such as a Computation variable. (See Attach a Variable to a Field.)
3. If using a Computation variable, create a script that will create a text string that includes all the answers you want
encoded. Separate each answer by using a delimiter character, such as a tilde (~) or a vertical bar ( | ). (See
Customize a Computation Variable and Overview: Instruction and Expression Models.)
For example, Court Branch or District + "|" + Court Mailing Address + "|" + Court City +
"|" + Court Zip Code.

4. Click OK at both the variable editor and the Variable Field dialog box. The template appears again.
5. With the field still selected, click the

Field Properties button. The Field Properties dialog box appears.

6. At the Type tab, select Bar code as the Display type.

7. Optionally, click the Bar Code tab and adjust any of the bar code settings. (See Understand Bar Code Settings.)
When the user assembles the document, the answer will be encoded as a two-dimensional bar code.
To create a bar code using predefined text
Copyright 2010 HotDocs Ltd. All rights reserved

758

Help Topics for HotDocs Developer 10

1. Edit a form template. (See Edit a Form Template.)

2. Create a field. (See Create a Form Field.)
3. Click the

Field Properties button. The Field Properties dialog box appears.

4. At the Type tab, select Bar code.

5. Type the data you want encoded in the Bar code text box. As you type the text, HotDocs displays the bar code
in the underlying form field. (You may need to click the
Show Variables button in the Automator toolbar to
hide variable names.) (If you are entering a group of answers that must be interpreted by the bar code scanner as
individual answers, you must separate each answer with some sort of delimiting character, such as a tilde (~) or
vertical bar (|).)
For example, Superior Court of Ada County|12 N. Elm Street|Boise|99999.
Note:
If you are automating a fillable PDF template and you plan to save the assembled document as a fillable PDF,
you cannot assign a bar code to a linked field. Instead, use a regular HotDocs field.
For information on changing the bar code specifications, see Understand Bar Code Settings.
To access the Field Properties dialog box, you can also right-click and select Field Properties from the shortcut
menu.

Copyright 2010 HotDocs Ltd. All rights reserved

759

Help Topics for HotDocs Developer 10

Flow a Single Answer Across Two or More Pages in a Form

Before You Begin:
These instructions can also be used to flow an answer across two pages both at the Form Document tab of the
assembly window and in HotDocs Filler.
At times, a single answer field will start at the bottom of one page and continue to the top of the next page. However,
HotDocs will not allow you to create a single field that spans across both pages. You can, however, create two fieldsone
on each pageand then link them using the Group Fields command.
To group fields on separate pages

1. Edit a form template. (See Edit a Form Template.)

2. Create the first field in the series of spanned fields. (See Create a Form Field.)
3. Assign a Text variable to the field. (See Customize a Text Variable.)
4. Select the field and click the

Field Properties button. The Field Properties dialog box appears.

5. Click the Overflow tab, and in the Group name box, enter a name. Usually, this is the name of the variable, but it
can be any text as long as it is the same for each field in the group.

6. On the following page(s), create the fields that will contain any overflow. Do not assign variables to these fields.
7. Repeat the preceding steps for each field in the group, using the same group name as you assigned to the first field.
Now, answers that do not fit in the first field will overflow to the next field named in the group.
Note:
To span text across multiple fields on the same page, see Group Form Fields So Answers Can Flow From One Field to
Another.

Copyright 2010 HotDocs Ltd. All rights reserved

760

Help Topics for HotDocs Developer 10

Check Form Fields for Answer Overflow

HotDocs can compare the size of a field and the length of the answer. If an answer uses more space than is available in
that field, HotDocs warns you and lets you resolve the overflow. Your options for resolving the overflow include reducing
the answer's font size, sending answers to the addendum, editing the answer, resizing the field in which the answer is
merged, and overriding the field to enter a differently formatted answer.
After you complete an interview, you can manually check for answer overflow. Also, when you direct-fill assemble a form
document, HotDocs automatically checks each field when you move to another field. Finally, when you print a document,
HotDocs checks for any unresolved answer overflows.
To manually check for field overflow

1. At the HotDocs library window, select a form template and begin assembling the document. (See Assemble a Text
or Form Document.)

2. After answering the questions in each dialog, click the Form Document tab to view the assembled document.
3. Click Check for Overflow (Tools menu). HotDocs begins comparing the size of each field and answer.
4. If an answer is too long, HotDocs selects the field and displays the Overflow Status dialog box. Information about
the status of any answers that overflow is displayed at the top of the dialog box.

5. Make adjustments as explained in the following table:

To

Do This

Reduce the answer's font

size to the minimum size
allowed for the field

Select Shrink the answer to fit in the field. The answer's font size is reduced to a
smaller point size. If the answer still doesn't fit in the answer field, you must choose
another option for resolving the overflow.

Send the answer to the

addendum and insert
cross-reference text in the
answer field

Select Send the answer to the addendum. The answer is moved to the addendum.
HotDocs then merges text in the field that indicates the answer can be found in the
addendum.
Select Split answer if you want only the part of the answer that doesn't fit in the field
to be sent to the addendum.

Change the text of the

answer, such as reduce
the number of words in the
answer

Click Edit. HotDocs highlights the field that contains the answer so you can edit the
text.

Make the answer field

larger

Click Resize. HotDocs selects the field so you can click one of its handles to resize it.

Override any settings or

formats of the field and
enter any text in the field

Click Override and enter the text you choose in the field.

Once you edit your answer, click back on the Overflow Status dialog box to have
HotDocs the overflow.

Once you resize the answer field, click back on the Overflow Status dialog box to
have HotDocs recheck the overflow.

Note:
Overriding a field does not change the original answer. In fact, HotDocs continues
to use the original answer in any calculations or scripts that require it. It also saves
the original answer to the answer file. Choosing to override a field simply allows
you to define only the text that needs to appear on the form.
Once you override the answer field, click back on the Overflow Status dialog box to
have HotDocs recheck the overflow.

Copyright 2010 HotDocs Ltd. All rights reserved

761

Help Topics for HotDocs Developer 10

To

Do This

Resolve the overflow at a

later time

Click Ignore. The Overflow Status dialog box is closed and you are able to work
with other answer fields in the document. If you click on the overflowing answer field
again, or if you check for answer overflow, you will be asked to resolve the overflow
again.

Resolve the overflow on

your own

Choose Close. HotDocs highlights the overflowing field so you can change the
answer in whatever way you choose.

Once you resolve the overflow, you can click Close to close the dialog box. Any other fields that overflow will display a
similar dialog box.
Note:
You can prevent HotDocs from checking for field overflow during assembly. See Set Rules for Handling Answer
Overflow for details.
Caution:
Fillable PDFs do not support the creation of an addendum when a field overflows. This means that if a field in an
assembled fillable PDF template overflows, the answer in the saved PDF document will simply appear cut off.
Template users should always review and modify any answers that may potentially overflow before saving the
assembled document as a fillable PDF.

Copyright 2010 HotDocs Ltd. All rights reserved

762

Help Topics for HotDocs Developer 10

Customize the Look of the Addendum

Before You Begin:
These instructions can also be used to customize the look of the addendum both at the Form Document tab of the
assembly window and in HotDocs Filler.
Sometimes when assembling a form document, an answer is too long for the form field. One way to resolve this overflow
is to send the overflowing text to an addendum, which is a section of the form designed to display such answers. You
can modify the appearance of the addendumfor example, you can choose what page margins to use, define what text
appears in the headers and footers, and choose the font properties for the text that is used in the addendum. You can
also define how pages are numbered in the addendum.
To change the addendum format

1. Edit a form template. (See Edit a Form Template.)

2. Click File > Template Properties > Addendum. The Addendum Properties dialog box appears.
3. Complete any of the following steps:
To

Do This

Define how much white

space there is between
the addendum page
edges and the text in the
addendum

Enter the dimensions in the Page margins group.

Define the text that

appears at the top of each
addendum page

Enter the text in the Header text box.

Define the text that

appears at the bottom of
each addendum page

Enter the text in the Footer text box.

Change the font properties

(including font face, size,
and style) of the header or
footer text

In the respective Header properties and Footer properties groups, click the Font
button and make the changes at the Font dialog box.

Define how much vertical

space the header or footer
text requires

In the respective Header properties and Footer properties groups, enter a number
in the Height box.

Change the alignment of

the header or footer text

In the respective Header properties and Footer properties groups, click the
Alignment button and choose your alignment option.

Insert a variable in the

header or footer text

In the respective Header properties and Footer properties groups, click the

Define the font properties

(including font face, size,
and style) for answers that
appear in the addendum

In the Addendum entries group, click the Font button and make your changes at the
Font dialog box.

Define how much space

there should be between

In the Addendum entries group, enter a number in the Indentation box.

To learn how to merge page numbers in the header, see Use Answer Overflow and
Addendum Text Codes.

To learn how to merge page numbers in the footer, see Use Answer Overflow and
Addendum Text Codes.

Variable Field button. The Variable Field dialog box appears, where you can
define the variable whose answer you want merged in the header or footer.

Copyright 2010 HotDocs Ltd. All rights reserved

763

Help Topics for HotDocs Developer 10

To

Do This

the addendum label and

the answer
Define how much space
there should be between
each answer in the
addendum

In the Addendum entries group, enter a number in the Space between box.

Make the addendum

appear as a pleading
paper

Select Number lines to format as pleading paper.

Once an answer has been sent to the addendum, you cannot edit the actual addendumyou must either modify your
answers at the Form Document tab or Interview tab, or you must send the addendum to the word processor (choose
File > Send Addendum To > Word Processor). You can also send the addendum to the Windows Clipboard (choose
File > Send Addendum To > Clipboard) to paste it into a different program for editing.
Caution:
Fillable PDFs do not support the creation of an addendum when a field overflows. This means that if a field in an
assembled fillable PDF template overflows, the answer in the saved PDF document will simply appear cut off.
Template users should always review and modify any answers that may potentially overflow before saving the
assembled document as a fillable PDF.

Copyright 2010 HotDocs Ltd. All rights reserved

764

Help Topics for HotDocs Developer 10

Define Overflow Properties for a Regular Field

Before You Begin:
These instructions can also be used to change the overflow properties for a field both at the Form Document tab of
the assembly window and in HotDocs Filler.
When an answer is too large to fit in its field, HotDocs, by default, warns you and asks how to handle the overflow. You
can customize the field overflow properties, controlling how HotDocs automatically handles answer overflows.
For example, you can have HotDocs automatically create an addendum, where each answer that overflows is sent. In the
field that overflows, HotDocs can insert cross-reference text that points you to a specific item in the addendum. You can
designate the text that is used both for the cross-reference and for the label in the addendum.
Another option is for you to have HotDocs automatically reduce the answers font size. You can set a minimum point size
and control if the answer is automatically reduced to this size before displaying an overflow warning message. (Be careful
reducing the font size since others may find the smaller size harder to read.) (See Change the Font Used for a Field.)
How you define overflow properties depends on the type of field you are creating. For example, in an addendum, grouped
fields and tables are handled a little differently from regular fields. See Define Overflow Properties for Run-on Fields and
Define Overflow Properties for a Table.
To set overflow properties for regular fields

1. Edit a form template. (See Edit a Form Template.)

2. Select the field whose overflow properties you want to define.
3. Click the

Field Properties button and click the Overflow tab.

4. Complete any of the following steps:

To

Do This

Automatically shrink an
answer that overflows to a
specific point size

Select Shrink answer as needed and enter a point size in the points box.

Automatically send an
answer that overflows to
the addendum

Select Send answer to addendum. (To send only part of a multi-line answer to the
addendum, select Split answer. (See Split a Multi-Line Answer Between the Form
and the Addendum.)

Define the text that

Enter the text in the Cross-reference text box. (See here for a list of reference
appears in the answer field numbering codes you can use.)
when an answer is sent to
the addendum
Define the text that
identifies the answer once
it has been sent to the
addendum

Enter the text in the Addendum label text box.

Make an answer the first

item on its addendum
page

Select Begin addendum entry on a new page.

Make an answer the last

item on its addendum
page

Select Begin new page following addendum entry.

Caution:
Fillable PDFs do not support the creation of an addendum when a field overflows. This means that if a field in an
assembled fillable PDF template overflows, the answer in the saved PDF document will simply appear cut off.
Copyright 2010 HotDocs Ltd. All rights reserved

765

Help Topics for HotDocs Developer 10

Template users should always review and modify any answers that may potentially overflow before saving the
assembled document as a fillable PDF.

Copyright 2010 HotDocs Ltd. All rights reserved

766

Help Topics for HotDocs Developer 10

Split a Multi-Line Answer Between the Form and the Addendum

When creating multi-line fields, you can select an overflow option that sends either all of the answer to the addendum, or
only the part of the answer that doesn't fit in the field to the addendum.
If you allow the user to choose whether to split the answer between the form and the addendum, you can customize
the reference and label text, based on their selection. For example, if the user chooses to send the entire answer to the
addendum, you can specify See Addendum 1 as the cross-reference text. However, if the user chooses to send just part
of the answer, you can specify Continued in Addendum 1 as the reference text.
To choose overflow options for a multi-line answer

1. Create a multi-line field. (See Create a Form Field.)

2. Select the field and click the

Field Properties button. The Field Properties dialog box appears.

3. Click the Overflow tab. The view changes to show overflow options.
4. Complete any of the following steps:
To

Do This

Always send the answer

to the addendum without
prompting the user

Select Send answer to addendum.

Specify the text that will

be merged in the field as
well as the addendum if
the user chooses just to
send to addendum

Enter the text in the Cross-reference text and Addendum label text boxes,
respectively.

To send just the part of the answer that doesn't fit in the field to the addendum, select
Split answer.

To specify alternate text that will be merged in the field and addendum if the user
chooses to split the answer between the form and the addendum, type a vertical bar
(|) and then enter the alternate text after the bar. For example:
Cross-reference text: See Addendum 1|Continued in Addendum 1
Addendum label text: Addendum 1|(con't) Addendum 1

Caution:
Fillable PDFs do not support the creation of an addendum when a field overflows. This means that if a field in an
assembled fillable PDF template overflows, the answer in the saved PDF document will simply appear cut off.
Template users should always review and modify any answers that may potentially overflow before saving the
assembled document as a fillable PDF.

Copyright 2010 HotDocs Ltd. All rights reserved

767

Help Topics for HotDocs Developer 10

Chapter 50: Creating Template and Document Summaries

Overview: Question and Answer Summaries
Some projects may require a printout of the information in the template. A Question Summary lists each question followed
by a blank space so an answer can be written in, as if being filled out like a questionnaire. An Answer Summary lists each
question and the associated answer. These printouts can be concise records of exactly what information was used when
the document was assembled.
The following is an example of an Answer Summary:

Note:
You can specify a one-column or two-column format for your summaries. In one-column format, dialogs,
questions, and answers are displayed as an indented outline. In two-column format, the information is presented
as a table, with each answer appearing on the same row as its question. (See Change the Way Question and
Answer Summaries Appear.)
If you're assembling a form document, you can create a questionnaire by printing a blank copy of the form itself.

Copyright 2010 HotDocs Ltd. All rights reserved

768

Help Topics for HotDocs Developer 10

View a Question Summary

You can create a concise list of the questions that appear in an interview. This can be useful when you want to create a
questionnaire, gathering information from one person so that a second person can enter the information using HotDocs. A
question summary can also give a quick overview of what questions will be asked during an interview.
You can format a question summary to appear as an indented bullet list, or as a table with one column for questions
and a second column for answers. (See Change the Way Question and Answer Summaries Appear.) Also, in a question
summary, you can control which conditional sections are included. (See Control Which Variables are Asked in a Question
Summary.)
To assemble a question summary

1. Assemble a text or form document. (See Assemble a Text or Form Document.)

2. At the assembly window, click the Question Summary tab. The assembly window shows the HotDocs variables and
other information about the template. (To hide or show the tab, choose Question Summary Tab at the View menu.)

3. Optionally, complete any of the following tasks:

To

Do This

Print a copy of the

summary

Click the

Attaches the summary

(in HTML format) to an email message to send to
another person

Choose Send Summary to Mail Recipient (File menu).

Print button.

Send the summary to the

Click the
word processor so you can
edit it or format it

Send Summary to Word Processor button.

Save a copy of the

summary as an HTML
document

Save Summary button.

Click the

Copyright 2010 HotDocs Ltd. All rights reserved

769

Help Topics for HotDocs Developer 10

View an Answer Summary

An answer summary is a list of the questions and the answers in an assembled document. It provides a way to quickly
scan and review information, rather than reading through a document or paging through dialogs in the assembly window.
You can format an answer summary to appear as an indented bullet list, or as a table with one column for questions and a
second column for answers. (See Change the Way Question and Answer Summaries Appear.)
To view an answer summary

1. At the HotDocs library window, select a template and begin assembling a document. (See Assemble a Text or Form
Document.)

2. After answering the questions, click the Answer Summary tab. The assembly window shows the HotDocs variables
and the answers you have entered in the interview.

3. Optionally, perform any of the following tasks:

To

Do This

Print a copy of the

summary

Click the

Attaches the summary

(in HTML format) to an email message to send to
another person

Choose Send Summary to Mail Recipient (File menu).

Print button.

Send the summary to the

Click the
word processor so you can
edit it or format it

Send Summary to Word Processor button.

Save a copy of the

summary as an HTML
document

Save Summary button.

Click the

Copyright 2010 HotDocs Ltd. All rights reserved

770

Help Topics for HotDocs Developer 10

View the Variable Sheet

The Variable Sheet helps you see the relationship between variables and answers. It shows the variables in the interview
as well as the answers, variable types, and prompts. While viewing the Variable Sheet, you can sort the different columns.
To view the Variable Sheet

1. At the HotDocs library window, select a template and begin assembling the document. (See Assemble a Text or
Form Document.)

2. After providing the required answers, choose Variable Sheet Tab (View menu).
3. Click the Variable Sheet tab. The assembly window changes to show the Variable Sheet.
4. Optionally, complete any of the following tasks using toolbar buttons and menus:
To sort the different lists in alphanumeric order, click one of the column headings.
To save the variable sheet as an HTML document, click the
To view the variable sheet in the word processor, click the
button.

Save Variable Sheet button.

Send Variable Sheet to Word Processor

To attach the variable to an e-mail message, click File > Send Variable Sheet To > Mail Recipient.
To copy the contents of the Variable Sheet into a spreadsheet program, such as Microsoft Excel, click File >
Send Variable Sheet To > Spreadsheet.
Caution:
When sending Variable Sheet data to a spreadsheet, HotDocs automatically looks for Microsoft Excel. If
you do not have Excel installed, you will be prompted to copy the contents from the Clipboard to another
spreadsheet program.

Copyright 2010 HotDocs Ltd. All rights reserved

771

Help Topics for HotDocs Developer 10

Chapter 51: Answer Files: Saving Answer Files

Overview: Save Answers
When you assemble a document, you can save the answers you enter in an answer file, which can then be used later to
recreate the same document or assemble other documents that require the same information.
For example, perhaps you are creating several estate planning documents that require much of the same information, like
names, addresses, and important dates. You can save your answers in an answer file and then use that answer file when
assembling other estate planning documents. This eliminates the need to re-enter information you've already provided.
Answer files are saved in XML format.
You can organize your answer files with the Answer File Manager, or you can use Windows Explorer to manage your
answer files. (See Manage Answer Files.)
Note:
See Compatibility of HotDocs 10 Files with Earlier Versions of HotDocs for details on making answer files compatible
with versions of HotDocs prior to HotDocs 2009 and HotDocs 10.

Copyright 2010 HotDocs Ltd. All rights reserved

772

Help Topics for HotDocs Developer 10

Create a Default Answer File

When certain answers are used frequently in a specific document, you can have those answers automatically inserted
each time you assemble the document. To do this, create a default answer file for that document.
A default answer file must be saved to the same folder as the template's component file. It must also have the exact same
file name as the component file, but the file name extension must be either .ANX or .ANS. In most cases, the file name
and path for the component file are identical to the file name and path for the template file. (The exception would be if the
template is pointing to a shared component file, in which case you would use the shared component file name.) You can
find this information by selecting the template at the HotDocs library window and viewing the Properties tab.
To create a default answer file for a document

1. At the HotDocs library window, select a template and begin assembling the document, using a new answer file. (See
Assemble a Text or Form Document.)

2. Type information for only the answers you want to be default answers.
3. Click the

Save Answers button. The Save Answer File dialog box appears.

4. At the File name box, click the

Browse button and locate the folder that contains the component file. Then enter
a name that matches the component file's name, followed by an answer file name extension. For example, if the
component file is named Invoice.cmp, the answer file name would be Invoice.anx.

5. In the Title box, type a name for the default answer file.
6. Optionally, in the Description box, type a description for the answer file.
7. If the answer file will be used with HotDocs 2005-2008, select HotDocs 2005-2008 answer file. (See Compatibility
of HotDocs 10 Files with Earlier Versions of HotDocs.)
The next time you assemble the document, HotDocs automatically inserts the answers from the default answer file into
the template's answer fields. You can then modify the answers as necessary and save a new answer file. (See Create a
New Answer File.)

Copyright 2010 HotDocs Ltd. All rights reserved

773

Help Topics for HotDocs Developer 10

Suggest an Answer File for Every Assembly

You may use a certain answer file more frequently than any others. You can select an option that will automatically
suggest that answer file every time you assemble a document.
To suggest an answer file for every assembly

1. At the HotDocs library window, select a template and click

2. Click the

Assemble. The Answer File dialog box appears.

Open Answer File button. The Open Answer File dialog box appears.

3. Choose an answer file and click

Select. The Answer File dialog box appears again.

4. Select Automatically select this answer file for use with the next assembly, then click OK.
The next time you assemble any document, the same answer file will automatically be selected at the Answer File dialog
box. To change the answer file, click the

Copyright 2010 HotDocs Ltd. All rights reserved

Open Answer File button and choose a different file.

774

Help Topics for HotDocs Developer 10

Save an Answer File During Assembly

While assembling a document, you can save the answers you have entered. This allows you to save your work and
perhaps start a different assembly without closing the assembly window. Saving answers also allows you to use the
information you enter with other templates, thus saving you time.
To save answers during assembly

1. At the HotDocs library window, select a template and begin assembling the document. (See Assemble a Text or
Form Document.)

2. At the assembly window, click the

Save Answers button. If you are using an existing answer file, the new
answers are saved. If you are using a new answer file, the Save Answer File dialog box appears where you can
perform any of the following tasks:
To

Do This

Enter the file name

At the File name box, enter a name. When you click OK, the answer file will be
saved to the default Answers folder and a reference to it will be added to Answer File
Manager.
To save the answers to a location other than the default Answers folder, click the
Browse button and navigate to the location.

Enter the title that

identifies the answer file in
Answer File Manager

At the Title box, enter a name or accept the suggestion HotDocs makes.

Add information to help

identify the file

At the Description box, type notes about the answer file's purpose or contents. (The
description will appear at the Properties tab of the Answer File Manager. When
searching for specific answer files, you can search for text in the description.)

Save the answer file so it

Select HotDocs 2005-2008 answer file. (See Compatibility of HotDocs 10 Files with
is compatible with versions Earlier Versions of HotDocs.)
of HotDocs earlier than
HotDocs 2009
Note:
See Overview: Use Answer Management for information on using Windows Explorer instead of Answer File
Manager.
The
Save Answers button may be disabled because the template provider wants to prevent the answer
file from being altered. You can assemble a document using new answers, but when you close the assembly
window, the new answers are automatically discarded.

Copyright 2010 HotDocs Ltd. All rights reserved

775

Help Topics for HotDocs Developer 10

Switch Answer Files During Assembly

While assembling a document, you may want to use another answer file. At any point during the interview, you can select
a different answer file, then continue the interview using the new answers.
To switch answer files

1. At the HotDocs library window, select a template and begin assembling a document. (See Assemble a Text or Form
Document.)

2. During the interview, click

Open Answers. The Open Answer File dialog box appears. (Depending on the
file management settings you have selected, a Windows Explorer dialog box or a window from your document
management program may appear instead. See Manage Answer Files.)

3. Select an answer file and click

Open.

4. If prompted to save the old answers, click Save, Save As, or Don't Save, depending on your needs. (See Save an
Answer File During Assembly.)

5. The assembly window appears again, using the newly selected answer file.
Note:
When viewing the answer library, you can sort the answer files. To do this, select a folder and click
Sort. To search
for a specific answer file, select the Find check box, then type the text for which you are searching in the text box.

Copyright 2010 HotDocs Ltd. All rights reserved

776

Help Topics for HotDocs Developer 10

Attach an Answer File to an E-mail Message

After gathering information in an interview, you may need to send those answers to another user. You can do this by
attaching the answer file to an e-mail message.
Caution:
Internet-based e-mail services are not compatible with this feature. You must have an e-mail program, such as
Microsoft Outlook, installed on your computer.
To attach an answer file to an e-mail message

1. At the HotDocs library window, select a template and begin assembly. (See Assemble a Text or Form Document.)
2. After completing the interview, click Send Answers To (File menu). The Send Answers to Mail Recipient dialog
box appears.

3. In the Attachment name box, enter a name for the answer file attachment. Make sure to leave the file name
extension on the attachment name.

4. Optionally, if you want the answer file to be compatible with versions of HotDocs prior to HotDocs 2009, select
HotDocs 2005-2008 answer file.

5. Click OK. HotDocs opens an e-mail message and attaches the answer file.

Copyright 2010 HotDocs Ltd. All rights reserved

777

Help Topics for HotDocs Developer 10

Spell Check Answers

You can spell check text answers you have entered at any time during an interview.
To spell check your answers

1. At the HotDocs library window, select a template and begin assembling the document. (See Assemble a Text or
Form Document.)

2. After providing the required answers, click the

Check Spelling button. If HotDocs finds any unrecognized words,

the Check Spelling dialog box appears. In the Answer being checked box, HotDocs shows a section of the text
that contains the misspelled word, which is highlighted. Options for working with the misspelled word appear below
it.

3. Make your selection, based on the options described in the following table:
To

Do This

Ignore the current instance Click Ignore.

of the word and continue
spell checking
Ignore all instances of the
word and continue spell
checking

Click Ignore All.

Correct only the current

instance of the word and
continue spell checking

Select an existing replacement from the Change to list (or type the replacement in
the Change to box) and click Change.

Correct all instances of

the misspelled word and
continue spell checking

Select an existing replacement from the Change to list (or type the replacement in
the Change to box) and click Change All.

Add the word to your

personal dictionary so
that the spelling checker
will not question the word
again

Click Add.

Display additional spelling

alternatives for the
unrecognized word

Click Suggest.

Change your spell

checking options, such as
which words the spelling
checker looks at and how
it determines whether
a word is a possible
replacement

Click Options. (You can also change your options at the HotDocs Options dialog
box. See Change Your Spell Checking Options.)

A deeper search takes longer but produces better possible replacements. If the
button is unavailable, HotDocs is searching at the deepest level.

Copyright 2010 HotDocs Ltd. All rights reserved

778

Help Topics for HotDocs Developer 10

Chapter 52: Answer Files: Using Answer File Manager

Overview: Use Answer Management
By default, each answer file you create or use is managed through the Answer File Manager. The Answer File Manager
is similar to the HotDocs template library in that it allows you to organize your answer files according to project
specifications. It also lets you sort and search for answer files. (See Overview: Use HotDocs Libraries.)
At times you may prefer to not use the Answer File Manager. For example, you can manage answer files using a
document manager instead of Answer File Manager. Or, if you have multiple users accessing the same set of answer
files, you can use Windows Explorer, since only one person can have write access to Answer File Manager. (All other
users have read-only access, which keeps them from saving or adding answer files to the answer library.)
Note:
HotDocs 6 through HotDocs 2008 supported binary answer libraries (or answer libraries with the .HAL file name
extension). Starting with the release of HotDocs 2009, however, HotDocs now supports both binary answer libraries
and XML-based answer libraries (which use the .HDL file name extension). By default, HotDocs will continue to use
binary answer libraries as long as the file properties of items in the library use characters that are compatible with your
system's default language. If you define answer file properties that contain foreign characters, HotDocs will create an
XML-based answer library (so that it can properly display these characters in the Properties tab of the library window.)

Copyright 2010 HotDocs Ltd. All rights reserved

779

Help Topics for HotDocs Developer 10

Open and Close Answer File Manager

When you use Answer File Manager to manage your answer files, you have greater control over the organization of your
files (see Work with Answer File Manager). To use Answer File Manager, however, you must first open it.
To open Answer File Manager
At the HotDocs library, click the

Answer File Manager button. Answer File Manager appears.

To close Answer File Manager

At Answer File Manager, click the X in the upper-right corner of the dialog box.
Note:
You can also open Answer File Manager by choosing Answer File Manager at the Tools menu. To close Answer File
Manager using the keyboard, press Alt+F4.

Copyright 2010 HotDocs Ltd. All rights reserved

780

Help Topics for HotDocs Developer 10

Add an Answer File to Answer File Manager

Answer File Manager allows you to organize your answer files. When you save your answers after an interview, a
reference to the file is automatically added to Answer File Manager. When you need to use answer files that someone
else has created (or if you have created them while using Windows Explorer to manage your files), you must add the files
to Answer File Manager.
There are two ways to add an answer file to an answer library. You can import the answer file or you can add it using the
Add button.
To import an answer file

1. At the HotDocs library window, click the

2. Click

Answer File Manager button. Answer File Manager appears.

Import. The Import Answer File dialog box appears.

3. Browse to and select the file you want to import. HotDocs confirms you want to import the file.
4. Click Yes. The answer file is added to Answer File Manager. The file is also automatically included in any answer file
drop-down lists.
To add an answer file to Answer File Manager using Add

1. At the HotDocs library window, click the

2. Click the

Answer File Manager button. Answer File Manager appears.

Add button. The Add Item dialog box appears.

3. In the File name box, enter the path and file name of the answer file you want to use (or click

Browse to locate

and open the file).

4. In the Title box, enter a name for the answer file. This title will identify the answer file in Answer File Manager.
5. Optionally, in the Description box, enter a description to help you identify the answer file. (This description appears
at the Properties tab, and can be used when searching for specific answer files.)
Note:
By default, answer libraries are saved in binary format, which does not support the use of international
characters. If you attempt to add an answer file that contains international characters in its properties to Answer
File Manager, HotDocs will prompt you to choose whether to create a new, XML-based answer library (which
will support these characters) or convert the foreign characters to an approximate character that can be read in
binary format. If you choose to create a new XML-based library, HotDocs 2005-2008 will continue to use the older
binary-format library, while HotDocs 10 and HotDocs 2009 will use the XML-based library.
If the answer file is located in a folder other than the default Answers folder, you can import the file, which copies
the file to the default Answers folder and adds it to Answer File Manager. To do this, click Import and then
locate the answer file.
When adding files to the library, press Ctrl or Shift to select multiple files at once.

Copyright 2010 HotDocs Ltd. All rights reserved

781

Help Topics for HotDocs Developer 10

Work with Answer File Manager

Answer File Manager helps you organize answer files, much like a HotDocs library helps you organize templates and
clause libraries.
When you save answer files, they are added to Answer File Manager. Once added, you can organize the files and modify
the properties of the files. In addition, you can view an answer file's historya list of dates and times the answer file
was used, including the template with which it was used. Finally, the Answer File Manager lets you preview the answers
currently saved in an answer file.
Note:
By default, answer libraries are saved in binary format, which does not support the use of international characters.
If you are using a binary answer library and you either add an answer file that contains foreign characters in its
properties to the library, or you change the properties or an existing file to include foreign characters, HotDocs will
prompt you to either convert the answer library to XML format or manually remove the characters from the file's
properties. If you choose to convert the answer library to XML format, you will have two answer librariesone that
works with HotDocs 2008 and earlier and one that works with HotDocs 2009 and later. (A third option allows you to
keep the library in its current, non-XML format, but HotDocs will replace characters that are not compatible with your
system's default language with the closest approximation available. Usually this means HotDocs will use question
marks or square box characters.)
To display Answer File Manager

1. At the template library, click the Answer File Manager button. The Answer File Manager dialog box appears.
2. Complete any of the tasks described in the following table:
To

Do This

Create a new, empty

answer file

Click the

New button. (See Create a New Answer File.)

Add an existing answer file Click the Add button. (See Add an Answer File to Answer File Manager.)
to the library
To add multiple files one at a time, press Ctrl or Shift to select several files.
Remove a reference to an
answer file and optionally
delete the actual file from
disk

Select the answer file, then click

Simultaneously copy an
answer file you receive to
the Answers folder and
add it to the answer library

Click Import. The Import Answer File Name dialog box appears, where you can
browse to the answer file and select it. When you click OK, the file is copied to the
Answers folder and added to the library.

Sort answer files in

Select a folder, then click the
alphanumeric order, based reorganized.
on answer file titles
Search for a specific
answer file

Remove.

Sort button. The contents of the folder are

Select Find, then type the text from the answer file's title or description for which
you are searching in the text box. Only files that have matching text in their title or
description are shown.

View the answers currently Select the answer file, then click the Contents tab.
saved in an answer file
In the Contents tab, you can sort the columns by clicking the column headings.
View the history of when
the selected answer file

Select the answer file, then click the Properties tab.

Copyright 2010 HotDocs Ltd. All rights reserved

782

Help Topics for HotDocs Developer 10

To

Do This

was used to assemble

various templates
Change the title, path,
file name, description, or
format of an answer file

Select the answer file, then click the

changes.

Properties button and make the necessary

Caution:
Changing the file path does not change the location of the actual answer file. If
you change the file path without moving the actual file to the new location on disk,
that answer file will not be accessible.
Add a folder so that you
Click the Add button, then select Folder at the Type drop-down box. (See Add,
can better organize groups Modify, and Delete Folders in Answer File Manager.)
of answer files
Modify a folder's title or
description

Select the folder, then click

Answer File Manager.)

Delete a folder

Select the folder, then click Remove. HotDocs asks what you want to do with any
answer files within the folder. (See Add, Modify, and Delete Folders in Answer File
Manager.)

Move an answer file into a

folder

Double-click the folder to open it, then select the answer file and drag it to the folder.

Change the format of

an answer file so it is
compatible with a specific
version of HotDocs

Select the answer file, and then click

Properties. The Item Properties dialog box
appears where you can select HotDocs 2005-2008 answer file. (See Compatibility
of HotDocs 10 Files with Earlier Versions of HotDocs for details.)

Use Windows Explorer

to access answer files
instead of Answer File
Manager

Change the setting at the HotDocs Options dialog box. (See Manage Answer Files.)

Copyright 2010 HotDocs Ltd. All rights reserved

Properties. (See Add, Modify, and Delete Folders in

783

Help Topics for HotDocs Developer 10

Add, Modify, and Delete Folders in Answer File Manager

To help organize your answer files, you can place them in folders and subfolders within Answer File Manager.
To add a new folder

1. At the HotDocs library window, click the

2. Click the

Answer File Manager button. The Answer File Manager appears.

Add button. The Add Item dialog box appears.

3. In the Type drop-down list, select Folder. The dialog box changes to show the options needed for new folders.
4. In the Title field, enter a folder name.
5. Optionally, in the Description field, enter notes to explain why the folder was created, or what kinds of answer files
it contains. (This description appears at the Properties tab, and can be used when searching for specific answer
files.)

6. Click OK. The folder is added to the answer library. You can work with the folder using the following commands:
To

Do This

Move an answer file to a

specific folder

Double-click the folder to open it, then select an answer file and drag it to the folder.

Modify the title or

description

Select the folder and click the

Properties button. The Item Properties dialog box
appears, where you can change the title or description.

Sort the contents of a

folder in alphanumeric
order

Select the folder and click

Remove a folder

Select a folder and click Remove. If you want to remove the items in the folder
as well, select Remove the unselected items contained in the selected folders.
Otherwise, any files referenced in the folder will be moved to the next folder level.

Copyright 2010 HotDocs Ltd. All rights reserved

Sort. The answer files are rearranged based on title.

784

Help Topics for HotDocs Developer 10

Chapter 53: Using Published and Web-Based Files

Overview: Use Published Files on the Internet
When you install HotDocs, the installation program sets up HotDocs as a helper program for Microsoft Internet Explorer.
This makes it possible for the browser to communicate with HotDocs. When you click on a hyperlink to an auto-install or
auto-assemble file, the browser starts HotDocs and sends it the file. Then HotDocs begins installing or assembling the file.
In HotDocs, you can also add auto-assemble files from the Internet or from a corporate intranet to your HotDocs library.
This allows you to access the files without starting your browser. If you will be unable to connect to the Internet at the time
of assembly, you can download and cache copies of the auto-assemble files for use offline. If you add the URL for a Web
page to a HotDocs library, you can start your browser from within HotDocs and display that Web page.
In HotDocs, if you are using a template that has been enabled for answer uploading, you can upload the answers you
used to assemble a document to a Web server. (Note, however, that the URL of the Web server must be specified by the
template developer.)
Finally, if you use a browser other than Internet Explorer, you may need to manually register HotDocs to work with your
browser.

Copyright 2010 HotDocs Ltd. All rights reserved

785

Help Topics for HotDocs Developer 10

Register HotDocs to Work with Web Browsers

If HotDocs is registered as a helper program with your Web browser, you can click on a HotDocs auto-install (.HDI) or
auto-assemble (.HDA) file listed on a Web page and have your browser start HotDocs and pass the file to it.
The HotDocs installation program automatically registers HotDocs with Microsoft Internet Explorer. If you use a different
Web browser, you will need to register HotDocs as a helper program yourself. Specific instructions for your browser
should be available in your browsers online help system. (Search for the keywords MIME types, file types, helper
programs, or associations.)
To register HotDocs with a Web browser (other than Internet Explorer)

1. Find your browsers list of MIME types. A MIME type is an association that tells the browser what to do when
you download a particular type of file. Each entry in the list of MIME types consists of a MIME type, one or more
associated file name extensions, and an action to take on files of this typeusually either by displaying the file in the
browser, by using a plug-in to view it, or by starting a helper program. Depending on the browser, each entry may
also have a descriptive name.

2. For HotDocs auto-assemble files, make an entry in the MIME types list using the following settings:
Option

Value

Name (optional)

HotDocs Auto-Assemble File

MIME type

application/x-hotdocs-auto

Extension

hda

Launch Application

hd_dispatch.exe /ha=
Note:
By default, the launch application executable is found in C:\Program Files
\HotDocs 6.

3. For HotDocs auto-install files, make an entry in the MIME types list using the following settings:
Option

Value

Name (optional)

HotDocs Auto-Install File

MIME type

application/x-hotdocs

Extension

hdi

Launch Application

hd_dispatch.exe /hi=
Note:
By default, the launch application executable is found in C:\Program Files
\HotDocs 6.

4. Save these settings and restart your browser.

Note:
If you upgrade or change browsers after installing HotDocs, you may need to reinstall HotDocs so it will be registered
correctly with the new browser.

Copyright 2010 HotDocs Ltd. All rights reserved

786

Help Topics for HotDocs Developer 10

Add an Auto-Assemble File on the Internet to a HotDocs Library

You can add an auto-assemble file located on the Internet to the HotDocs library. You must know the URL for the files
location on the Internet or intranet. When you select the auto-assemble file at the library window, and click the Assemble
button, HotDocs downloads the file and begins assembling.
To make sure you always have the most current version of the auto-assemble file, you must be connected to the Internet
at the time you assemble it. Otherwise, HotDocs uses the version of the file that has been cached.
To add an Internet-based auto-assemble file to a library

1. At the HotDocs library window, select the folder in which you want the auto-assemble file and click the

Add

button. The Add Item dialog box appears.

2. In the Type drop-down list, select Auto-Assemble File.

3. At the File name box, type the URL for the file's location on the Internet or intranet, or click the

Browse button to

locate the file on your local disk or network and click OK.
Note:
Make sure the URL is entered correctly. If you dont include http:// or https:// or ftp:// (or if you are missing a
slash or a colon), HotDocs will treat the URL as a regular file path.

4. In the Title box, type a title for the auto-assemble file. The title identifies the file in the template library.
5. Optionally, type a description in the Description box. The description appears at the Properties tab.
Note:
The first time you use an auto-assemble file that is stored on a Web server to assemble a document, HotDocs caches
the HDA on your hard disk. Then, each time you use the file, it checks to see if a newer version of the file is available
and, if so, automatically downloads it. You can also force HotDocs to check for newer versions by choosing Refresh
Cache from the Tools menu. (See Download Auto-Assemble Files for Use Offline.)

Copyright 2010 HotDocs Ltd. All rights reserved

787

Help Topics for HotDocs Developer 10

Download Auto-Assemble Files for Use Offline

In HotDocs, you can download the latest version of an auto-assemble (.HDA) file and store it on your local drive. When
you are assembling, if HotDocs can't connect to the Internet or intranet, it uses the local copy.
To download auto-assemble files for use offline

1. At the HotDocs library window, select the auto-assemble file you want to download. You can download all the autoassemble files in a folder by selecting the folder.

2. Click Refresh Cache (Tools menu).

Copyright 2010 HotDocs Ltd. All rights reserved

788

Help Topics for HotDocs Developer 10

Install a Template Set

Some template sets are published as an auto-install file. Because these templates are published, you can't simply add
the templates to an existing library. Instead, you must first install them. When you do, HotDocs installs the library and
templates to the locations you specify. You can then access the templates.
To install a template set

1. At the HotDocs library window, click Install Templates (File menu). The Install Templates dialog box appears.
2. Locate and select the auto-install (.HDI) file you want to install, then click Install. The Install Template Set dialog
box appears.

3. At the Specify where the templates should be installed box, accept the suggested Template Sets folder location,
or click the

Browse button to choose a different location.

4. Click the Choose where the library file should be installed drop-down button and choose whether to save the
library to the shared Templates folder, the user-specific Libraries folder, or, if you installed the templates to a custom
folder in step 3, to the same folder as specified for the templates.

5. Click OK. HotDocs installs the template set (including the library) to the locations you specified.

Copyright 2010 HotDocs Ltd. All rights reserved

789

Help Topics for HotDocs Developer 10

Check for Template Set Updates

If you are using a published template set, HotDocs can check for updates to the set at regular intervals and notify
you when updates are available. Updates can include new or revised template files, or they may include an important
message from the template provider. Although the frequency of automatic update checks is set by the template provider,
you can manually check for template set updates at any time.
To check for template set updates

1. At the HotDocs library window, click Update Template Sets (Tools menu). The Update Template Sets dialog box
appears.

2. Select the template sets for which you want to check for updates, then click OK. The Template Set Update
Progress dialog box appears, showing the progress as HotDocs checks for updates.

3. When HotDocs has finished checking for updates, the Install Template Set Updates dialog box appears, displaying
a list of updates. You can work with this list as described in the following table:
To

Do This

Install specific update

items

Select Install for each item you want to install.

Discard an update item

Select Discard for the item. If this box is disabled, the template provider has marked
to prevent HotDocs from
it as a required update and it cannot be discarded. (You can choose to not install the
prompting you to install the update, but it will be displayed every time you check for updates.)
update
View a list of discarded
updates

Select Discarded updates. The list changes to include discarded items.

View a list of all installed

updates

Select Installed updates. The list changes to include installed updates.

Reinstall an update

Select Installed updates, then select the update you want to reinstall from the list.

4. Click Continue. HotDocs installs the selected updates.

Note:
You can hide the Template Set Update Progress dialog box or choose which template sets are checked for updates
in the HotDocs Options dialog box. (See Determine How Frequently HotDocs Checks for Template Set Updates.)

Copyright 2010 HotDocs Ltd. All rights reserved

790

Help Topics for HotDocs Developer 10

Upload Answers
If a template has been enabled for answer uploading, the answers you provide to assemble a document can be uploaded
to a Web server. The template developer specifies where and when answers will be uploaded. The developer may also
specify that HotDocs automatically uploads the answers.
To upload answers

1. If a template is enabled for uploading answers, HotDocs automatically displays the Upload Answers dialog box
after you assemble a document and close the assembly window. (If the Upload Answers dialog box doesn't appear,
it means either that the template isn't enabled for answer uploading, or that the template developer specified that
HotDocs must always upload the answers.)

2. Click one of the upload buttons to finish the upload process: Upload Now (uploads the answers immediately),
Upload Later (lets you upload either when you start or exit HotDocs), or Don't Upload (doesn't upload the answers
at all).
Note:
If errors occur when HotDocs tries to upload the answers (or if you click the Upload Later button), HotDocs
creates a data file that contains the information needed about the files you need to upload. Then, every time
HotDocs starts or closes, it checks to see if files are waiting to be uploaded and prompts you to upload them.
If you choose to Upload Later, you can then upload the files from the library window at any time by clicking
Upload Answers (Tools menu).

Copyright 2010 HotDocs Ltd. All rights reserved

791

Help Topics for HotDocs Developer 10

Add a Web Page to a HotDocs Library

You can include a URL in a HotDocs template library, making it possible to open a Web page and download published
files. You can also use a URL to link to a support site where information about the template set is available.
When you click a URL in the template library, HotDocs launches a Web browser and displays the specified Web page.
To add a Web page to a template library

1. At the HotDocs library, open the folder to which you want to add the URL.
2. Click the

Add button. The Add Item dialog box appears.

3. At the Type drop-down list, select Web Address.

4. In the URL box, enter the URL. Or, click the

Browse button to locate the address. Then close the browser

window to save the URL to the Add Item dialog box.
Note:
Make sure the URL is entered correctly. If you dont include http:// or https:// or ftp:// (or if you are missing a
slash or a colon), HotDocs will treat the URL as a regular file path.

5. In the Title box, enter a title for the URL. The title identifies the item in the template library.
6. Optionally, type a description in the Description box. The description appears at the Properties tab.

Copyright 2010 HotDocs Ltd. All rights reserved

792

Help Topics for HotDocs Developer 10

Chapter 54: Assembling Documents Linked to a Database

Overview: Assemble Documents Linked to a Database
For the most part, templates linked to database tables are assembled just like regular unlinked templates. However,
instead of entering answers to questions, you select a record or records from a database table and HotDocs uses the
information in those records and merges them into the assembled document. You can save your record selections in a
HotDocs answer file.
Depending on how the template was designed, you may also have the ability to sort and filter records you view in the
database table.

Copyright 2010 HotDocs Ltd. All rights reserved

793

Help Topics for HotDocs Developer 10

Select Records During Document Assembly

Instead of displaying questions during the interview for which you must enter individual answers, HotDocs presents a
list of records from which you can choose. The information in the record or records you select will be merged into the
assembled document.
In some situations, the template developer may allow you to select multiple records from the table, for example, to create
a list of answers.
To select records from a database table

1. Assemble a document. (See Assemble a Text or Form Document.)

2. When a database table appears, click a single row in the table, or press and hold either Shift or Ctrl to click multiple
rows.

3. If selecting a single row, complete the following steps:

a. Click Select. HotDocs places the record in the Selected Item pane of the assembly window. (You can also
double-click a record and have it automatically placed in the Selected Item pane.)
b. Click Next. HotDocs merges the answers from the database record into the assembled document.

4. If selecting multiple rows, complete the following steps:

a. Click Select. HotDocs adds the records you just selected to the Selected Items pane of the assembly window.
(Additionally, to select multiple records, double-click the cell that uses a thicker border in the last record you
selected.)
b. Optionally, select a record and click the

Up button (moves the record up to the next row in the list of records)

or the
Down button (moves the record down to the next row in the list of records). You can also click the
column headings of the Selected Items list to automatically sort selected rows by any field. (These options
are available if the template developer has given you permission to sort your records. If these buttons do not
appear, you cannot change the order of selected rows.)
c. Click

Next. HotDocs merges the answers from the database into the assembled document.

Note:
If the template developer has assigned a filter to the table, you may see different results. For example, if only one
record meets the filter criteria, that record will automatically be merged into the document without appearing in
the interview. Similarly, if no records meet the filter criteria, HotDocs will ask the questions and allow you to enter
your own answers. Finally, in some situations, the template developer may have opted to have any selections
returned by the filter automatically merged into the assembled document without first prompting you.
To remove a selected record, you can either select a different record, or you can click

Clear.

To remove a single selected record from the Selected Items list, select the record and click Clear. To remove all
selected records from the list, click Clear All.

Copyright 2010 HotDocs Ltd. All rights reserved

794

Help Topics for HotDocs Developer 10

Sort Database Records During Assembly

If the template developer has allowed it, you can sort the list of records in the database table to show the records in
ascending (A to Z,1 to 9) or descending (Z to A, 9 to 1) order. You can sort on any column in the table. Additionally, if the
template developer has allowed you to select multiple records (in order to create a list of answers), you can choose which
order the answers will be merged into the document.
To sort database records in alphanumeric order

1. Assemble a document. (See Assemble a Text or Form Document.)

2. When the database table appears, click the heading for the column on which you want to sort. HotDocs sorts the list
in alphanumeric order (A to Z, 1 to 9.)

3. Optionally, to sort the list in reverse alphanumeric order, click the column heading again. HotDocs lists the entries
from Z to A, 9 to 1.

4. Optionally, if you have selected multiple records and want to control the order the answers are merged into the
assembled document, click a record in the Selected Items list and then click the Up button (moves the record up to
the next row in the list of records) or the Down button (moves the record down to the next row in the list of records).
You can also click the column headings in the Selected Items list to automatically sort the selected items by any
field.
Note:
You may also be able to filter the list of records to show only those you think will be relevant to your selection. See
Filter Database Records During Assembly for details.

Copyright 2010 HotDocs Ltd. All rights reserved

795

Help Topics for HotDocs Developer 10

Filter Database Records During Assembly

If the template developer has allowed it, you can filter the list of records in the database table to show only those records
you think are relevant. To do this, you specify conditions that must be met for the records to appear. You can filter based
on any field in the table.
To filter a list of records in a database table during assembly

1. Assemble a document. (See Assemble a Text or Form Document.)

2. When the database table appears, select Find records where all conditions are met. This causes filtering options
to appear at the top of each database column.

3. In the database table, select the drop-down button at the top of the column on which you want to filter and select a
comparison operator. A comparison operator allows you to compare two values. If the comparison results in a true
statement, the record will be included. If it's false, it will not be included.

4. In the field directly below the comparison operator, type the value against which you want to filter. For example,
to view only those companies whose names start with the letter A, you would click the drop-down button in the
Company column, select begins with, and type the letter A in the next cell.

5. Click Apply Filter. HotDocs filters the list of records to show only those that meet the criteria you specified.
Once the list is filtered, you can select a record or records (see Select Records During Document Assembly) and continue
with the interview.
Note:
When you apply the filter, only those records that meet every condition you specified will be returned. This is
because <all> is selected at the Find records where all conditions are met prompt. You can click the dropdown button and select <any> , which will return a record, even if only one of the conditions is true.
You can sort a list of records in alphanumeric order. For details, see Sort Database Records During Assembly.

Copyright 2010 HotDocs Ltd. All rights reserved

796

Help Topics for HotDocs Developer 10

Save Selected Records in an Answer File

If you are using a database to provide your answers during document assembly, you can save your answers using the
same steps you follow when saving regular answer files. (See Create a New Answer File.)
However, if you think you may need an exact replica of a document assembled from a template that includes a database
component, be sure to save a copy of the document. If you try to reassemble the document later, even if you use the
same answer file, the document may not come out exactly the same because the information stored in the connected
database may have changed.

Copyright 2010 HotDocs Ltd. All rights reserved

797

Help Topics for HotDocs Developer 10

SECTION 9:
USING COMMAND-LINE OPTIONS

Copyright 2010 HotDocs Ltd. All rights reserved

798

Help Topics for HotDocs Developer 10

Chapter 55: Using Command-Line Options

Overview: Command-Line Options
You can use command-line options to control the way HotDocs assembles text and form documents. Most options can be
placed on any command line that causes HotDocs to run. They are case-sensitive and must be typed in lowercase letters.
If the option requires you to include a full file path, you must enclose the file path with quotation marks.
You can use command-line options in different ways, including specifying the options at the command line, at the
Properties dialog box of a given template, and for the program file's shortcut.
Most command-line options control certain aspects of document assembly. For example, you can specify an option that
always prints an assembled document once it has been sent to the word processor.
Caution:
When HotDocs is started from the command line, it will continue to run, even after the processing of the
command-line request is completed. To tell HotDocs to close after processing the command-line request, use the
Exit HotDocs option.
If you are using multiple options on a single command line, you must separate each option with a space
character. If the command line includes space characters, you must enclose the path in quotation marks.
To use command-line options when starting HotDocs

1. Choose Run from the Start menu. The Run dialog box appears.
2. Type "C:\Program Files\hotdocs.exe" (including the quotation marks) followed by a space and the options you
want in the Open box. For example:
"C:\Program Files\HotDocs\Hotdocs.exe" /tf=demoempl.rtf

3. Click OK. If HotDocs is not already running, it loads and then performs the command-line instructions. If HotDocs is
already running, it performs the command-line instructions.
To use command-line options when using a shortcut to start HotDocs

1. Locate the HotDocs program file shortcut. (A shortcut is an icon on the desktop or Start menu that a user can click
to quickly access a program.)

2. Right-click the icon and select Properties from the shortcut menu. The program item's Properties dialog box
appears.

3. Select the Shortcut tab.

4. In the Target box, enter a space after the executable (.EXE) file and type the options you want.
To add command-line options to a library item

1. Open a library at the HotDocs library window.

2. Select the library item and click the

Properties button to open the Item Properties dialog box.

3. In the File name box, following the file name, type a space and the command-line options you want to use. For
example:
/af="C:\Documents and Settings\Username\My Documents\HotDocs\Answers\jalvey.anx"

Copyright 2010 HotDocs Ltd. All rights reserved

799

Help Topics for HotDocs Developer 10

Full List of Command-Line Options

Option Name

Option

Description

Answer File

/af

The Answer File option is useful if you

want to use a specific answer file when you
assemble a document. The option does
two things: 1) when a template is selected
for assembly, it immediately opens the
specified answer file without displaying
the Answer File dialog box, and 2) it sets
the value for path and file name as the
current answer file name to be used when
answers are saved. If the specified answer
file doesn't exist, it will be created when the
user saves the answers.

Answer Summary

/as

The Answer Summary option is used

with the Output File option to specify the
path and file name for saving an answer
summary. It is useful if you want a certain
template to always generate an answer
summary document.

Clause Name

/cl

The Clause Name option is used

by HotDocs to identify which clause
component is associated with an item in a
clause library. It is also used by HotDocs
to process INSERT instructions during the
assembly process. Generally speaking,
developers should never have to modify
this option unless they are converting
clauses from one file format to another.
Likewise, end users may see the Clause
Name option while working with clauses
at a clause library or during assembly, but
should not modify it.

Default Answer File

/df

The Default Answer File option specifies

a default answer file that is used to "seed"
any answer file created during assembly.
When a new answer file is created, it is
automatically loaded with answers from the
default answer file.

Discard Answers

/da

The Discard Answers option prevents

the user from saving answers after the
document has been assembled. This option
is useful when you know you will never
want to save the answers you use with
a particular template (for example, a fax

Copyright 2010 HotDocs Ltd. All rights reserved

800

Help Topics for HotDocs Developer 10

cover sheet), and you don't want HotDocs

to ask about saving the answers when you
close the assembly window. However, the
user can save the answer file during the
interview.
Edit Template

/ed

The Edit Template option causes HotDocs

to edit a template using the specified
template or clause library file.

Exit HotDocs

/ex

The Exit HotDocs option closes HotDocs

when both of the following conditions are
met: 1) there are no documents waiting to
be assembled, and 2) all other programs
are finished using HotDocs.

Finish Interview Action

/fia

When a user starts assembling a template

that has the Finish Interview Action
command-line option applied, HotDocs will
complete the action defined in HotDocs
Optionseither display the assembled
document at the Document tab of the
assembly window or send the document to
the word processor or HotDocs Filler. (See
Control What Happens When You Finish
an Interview.)

Hide Library

/hl

The Hide Library option causes HotDocs

to assemble a document without first
displaying the HotDocs template library.
The user will not see the template library
window at all during assembly. It is most
commonly used by integrators who are
using HotDocs with a third-party program
and want to start an assembly without first
displaying the template library window.
(See also Show Library.)

HotDocs Auto-Assemble
File

/ha

The HotDocs Auto-Assemble File option

causes a document to be assembled using
the specified auto-assemble (.HDA) file.

HotDocs Auto-Install File

/hi

The HotDocs Auto-Install File option

causes the template set in the specified
auto-install (.HDI) file to be installed. During
this process, HotDocs prompts the user for
any required information it needs to install
the template library to the correct location.

Interview Scope

/is=u

The Interview Scope option allows you

to ask only those dialogs that contain
questions not answered by an existing

Copyright 2010 HotDocs Ltd. All rights reserved

801

Help Topics for HotDocs Developer 10

answer file. This may be useful, for

example, if you have some answers you
are retrieving from a database that you
don't want the user to change. Using this
option will ask only those questions that
don't have answers.
Keep Interview Group

/kig

The Keep Interview Group option is used

to control which questions are asked when
assembling a group of related documents,
specifically, it keeps questions that are
already answered in one interview from
being asked in subsequent interviews.
It must be used with the Start Interview
Group option, which must be assigned to
each subsequent template within the group.

Library File

/lf

The Library File option allows you to start

HotDocs and open a specific library. If
HotDocs is already running, it opens the
library specified by the path and file name.

Lock Answer File

/la

The Lock Answer File option prevents

users from opening, closing, and saving
answer files during document assembly. If
it is the only option used, however, users
can choose an answer file before assembly
and save any answers they have entered
after assembly.

Lock Library

/ll

The Lock Library option locks the current

library and prevents the user from editing
the library or its contents. Specifically,
when HotDocs is launched and the library
appears, users can select templates and
assemble documents from them. They
can also view the answer library and
change user preferences at the HotDocs
Options dialog box. All other options are
unavailable.

Model Document

/mo

The Model Document command-line

option indicates that the file referenced
in the library is a model document. When
you select the document in the library and
click Assemble, HotDocs will create an
interview for the model document.

New Answer File

/na

The New Answer File option specifies

a new, untitled answer file to be used
when assembling a given document. This
option causes HotDocs to suppress the

Copyright 2010 HotDocs Ltd. All rights reserved

802

Help Topics for HotDocs Developer 10

Answer File dialog box, which normally

appears before assembly. Specifying a
path and file name is optional. If a file name
is specified, it will be used for the new
answer file. If an answer file with that same
name already exists, HotDocs overwrites
the existing file with the new one. If no
file name is specified, HotDocs displays a
Save Answer File dialog box at the end of
assembly.
No Assembly Window

/nw

The No Assembly Window option causes

HotDocs to assemble a document without
displaying the assembly window.

No Interview

/ni

The No Interview option removes the

Interview tab from the assembly window,
and, by default, displays the assembled
document in the Document Preview
or Form Document tab (depending on
whether you are assembling a text or
form document). To present a correctly
assembled document, you should specify
an answer file using the Answer File
option. Otherwise, the document will be
assembled without any answers.

Output File

/of

The Output File option causes HotDocs to

assemble the document and save it using
the file name specified. If you are using the
Answer Summary or Question Summary
options, the Output File option specifies
the name for either of those generated
documents. This is useful if you know you
want to save an assembled document
every time assembly of that document
finishes.

Overlay Answer File

/ov

The Overlay Answer File option causes

HotDocs to take answers from a specific
answer file and overlay them in the current
answer file. For example, if you have
specific information about a client that can
be used in assembling multiple documents,
you can save just that information in an
overlay answer file and then use the
Overlay Answer File option to force
HotDocs to use those answers when
assembling a document. All answers
entered during assembly (including overlaid
answers) are saved to the current answer

Copyright 2010 HotDocs Ltd. All rights reserved

803

Help Topics for HotDocs Developer 10

filenot the overlay answer filethus

maintaining the integrity of the overlay
answer file. An overlay answer file is
loaded after the regular answer file so that
the answers contained therein can overlay
existing answers.
Paper Size

/ps

The Paper Size option selects the specified

paper size when the user prints a copy of
the form template or document. The effect
is the same as manually setting the page
size from the Print dialog box. This option
works with form templates and documents
only.

Paper Tray

/pt

The Paper Tray option causes a specified

printer paper tray or manual feed option
to be used when printing a form document
from HotDocs Filler. Paper tray values
that can be used include manual, upper,
lower, and so forth. For a complete list of
acceptable values, either at the assembly
window or at the HotDocs Filler window,
click Document Properties > Printing
(File menu) and click the Paper Source
drop-down button.

Print

/pr

The Print option causes HotDocs to

print a copy of the assembled text or
form document once the user closes the
assembly window. This is useful if you
know you will always need to print a copy
of a specific assembled document.

Print Answers Only

/pa

The Print Answers Only option selects

the Answers Only (Use Preprinted
Form) option at the Print dialog box. Then,
when the user prints the assembled form
document, it prints only the form's answers
and not the underlying static text. This
allows you to use preprinted forms.

Print Both

/pb

The Print Both option selects the Form

with Answers option at the Print dialog
box. Then, when the user prints the form
document, the current form and its answers
are printed.

Print Copies

/pc

The Print Copies option specifies the

number of copies that should be printed
when the user prints the form document.

Copyright 2010 HotDocs Ltd. All rights reserved

804

Help Topics for HotDocs Developer 10

This number should appear in the Number

of Copies box at the Print dialog box.
Print Duplex

/pd

The Print Duplex option sets the duplex

printing option for a given form document. It
prints the document Double-Sided, Sideto-Side, as if that option were selected at
the Printing Properties dialog box (which
you can access by clicking Document
Properties > Printing (File menu).) When
the user prints the form document, it is
printed using this option.

Print Form Only

/po

The Print Form Only option selects the

Form Only (Blank Form) option at the
Print dialog box. Then, when the user
prints the form document, it prints a blank
copy of the form without answers.

Print Without Dialogs

/pw

The Print Without Dialog option causes

HotDocs to bypass the Print dialog box
and print the form using the current printer.
The form is printed when the user clicks the
Print Document button at the assembly
window.

Question Summary

/qs

The Question Summary option is used

with the Output File option to specify the
path and file name for saving a question
summary. It is useful if you want a certain
template to always generate a question
summary document.

Save Answers

/sa

The Save Answers option forces an

answer file to be saved at the end of an
assembly. If using an existing answer file,
any answers entered during the interview
will be saved automatically. If using a new,
untitled answer file, HotDocs will force the
user to specify an answer file name.

Save Answers Prompt

/sap

The Save Answers Prompt option, which

is used in connection with an ASSEMBLE
instruction, prompts the user to save an
answer file after completing an interview.
Regardless of whether the user uses an
existing answer file during assembly, when
the user finishes that assembly, HotDocs
prompts to save the answers in a different
file.

Copyright 2010 HotDocs Ltd. All rights reserved

805

Help Topics for HotDocs Developer 10

Send to Word Processor

/stw

The Send to Word Processor option

sends the assembled document to the
word processor once the user closes
the assembly window. This is useful if
you know you always want to view the
assembled document using the word
processing program.

Show Library

/sl

The Show Library option forces HotDocs

to display the template library if it is
currently not showing. This is useful if
you are integrating HotDocs with another
program and you have hidden the library
using the Hide Library option.

Start Interview Group

/sig

The Start Interview Group option is used

to control which questions are asked when
assembling a group of related documents,
specifically, it keeps questions that are
already answered in one interview from
being asked in subsequent interviews. It
must be used with the Keep Interview
Group option, which must be assigned to
each subsequent template within the group.

Suggest Save

/ss

The Suggest Save option, which is

used in connection with an ASSEMBLE
instruction, causes HotDocs to ask users
after assembly of a document has finished
if they want to save answers entered during
the interview in an answer file. Specifically,
if the user has assembled a document
and made changes to an existing answer
file, HotDocs prompts to save the answers
to that file. If saving a new, untitled file,
HotDocs allows the user to specify the new
answer file name.

Suggest Save New

/ssn

The Suggest Save New option, which is

used in connection with an ASSEMBLE
instruction, causes HotDocs to ask if
answers should be saved in a new answer
file after assembly of a document has
finished. Regardless of whether the user
is using an existing answer file during
assembly, when the user finishes that
assembly, HotDocs gives the user the
option of saving the answers in a new
answer file.

Copyright 2010 HotDocs Ltd. All rights reserved

806

Help Topics for HotDocs Developer 10

Suppress Unanswered
Warning

/sw

The Suppress Unanswered Warning

option keeps HotDocs from displaying the
warning dialog box that appears when
the user attempts to either print, save, or
send the assembled document to the word
processor and the assembled document
still contains unanswered questions.

Template File

/tf

The Template File option causes HotDocs

to assemble a document using the
specified template or clause library.

Copyright 2010 HotDocs Ltd. All rights reserved

807

Help Topics for HotDocs Developer 10

Answer File
/af="path and file name"
The Answer File option is useful if you want to use a specific answer file when you assemble a document. The option
does two things: 1) when a template is selected for assembly, it immediately opens the specified answer file without
displaying the Answer File dialog box, and 2) it sets the value for path and file name as the current answer file name
to be used when answers are saved. If the specified answer file doesn't exist, it will be created when the user saves the
answers.
When using an existing answer file, you can retrieve an answer file from a location on a Web server by specifying a
URL for the path and file name (for example, /af=http://www.yoursite.com/answers.anx). (You cannot, however, save an
answer file back to the server.)
Note:
You cannot assign the Answer File option to a HotDocs Auto-Assemble file.
If using this option at the command line, include the Template File option.

Copyright 2010 HotDocs Ltd. All rights reserved

808

Help Topics for HotDocs Developer 10

Answer Summary
/as
The Answer Summary option is used with the Output File option to specify the path and file name for saving an answer
summary. It is useful if you want a certain template to always generate an answer summary document.
The Answer Summary option is normally used with the No Assembly Window and Answer File options, which cause
HotDocs to automatically create and save the answer summary document without displaying the assembly window.
Answer summaries are saved in HTML format.
Note:
If using this option at the command line, include the Template File and Output File options. If using this option at the
library properties, include the Output File option.

Copyright 2010 HotDocs Ltd. All rights reserved

809

Help Topics for HotDocs Developer 10

Clause Name
/cl=clausename
The Clause Name option is used by HotDocs to identify which clause component is associated with an item in a clause
library. It is also used by HotDocs to process INSERT instructions during the assembly process. Generally speaking,
developers should never have to modify this option unless they are converting clauses from one file format to another.
Likewise, end users may see the Clause Name option while working with clauses at a clause library or during assembly,
but should not modify it.

Copyright 2010 HotDocs Ltd. All rights reserved

810

Help Topics for HotDocs Developer 10

Default Answer File

/df="path and file name"
The Default Answer File option specifies a default answer file that is used to "seed" any answer file created during
assembly. When a new answer file is created, it is automatically loaded with answers from the default answer file.
When specified, it does not need to have the same file name as the template's component file, nor does it need to be
saved in the same folder as the component file. However, the default answer file name should be different from the
current answer file name. Also, when using an existing default answer file, you can retrieve it from a location on a Web
server by specifying a URL for the path and file name (for example, /df=http://www.yoursite.com/defaultanswers.anx).
Note:
If using this option at the command line, include the Template File option.

Copyright 2010 HotDocs Ltd. All rights reserved

811

Help Topics for HotDocs Developer 10

Discard Answers
/da
The Discard Answers option prevents the user from saving answers after the document has been assembled. This
option is useful when you know you will never want to save the answers you use with a particular template (for example,
a fax cover sheet), and you don't want HotDocs to ask about saving the answers when you close the assembly window.
However, the user can save the answer file during the interview.
Note:
To disable all answer file usage (saving, selecting new, and so forth) during a given assembly, use the Lock
Answer File option.
If using this option at the command line, include the Template File option.

Copyright 2010 HotDocs Ltd. All rights reserved

812

Help Topics for HotDocs Developer 10

Edit Template
/ed="path and file name"
The Edit Template option causes HotDocs to edit a template using the specified template or clause library file.

Copyright 2010 HotDocs Ltd. All rights reserved

813

Help Topics for HotDocs Developer 10

Exit HotDocs
/ex
The Exit HotDocs option closes HotDocs when both of the following conditions are met: 1) there are no documents
waiting to be assembled, and 2) all other programs are finished using HotDocs.

Copyright 2010 HotDocs Ltd. All rights reserved

814

Help Topics for HotDocs Developer 10

Finish Interview Action

/fia
When a user starts assembling a template that has the Finish Interview Action command-line option applied, HotDocs
will complete the action defined in HotDocs Optionseither display the assembled document at the Document tab of the
assembly window or send the document to the word processor or HotDocs Filler. (See Control What Happens When You
Finish an Interview.)

Copyright 2010 HotDocs Ltd. All rights reserved

815

Help Topics for HotDocs Developer 10

Hide Library
/hl
The Hide Library option causes HotDocs to assemble a document without first displaying the HotDocs template library.
The user will not see the template library window at all during assembly. It is most commonly used by integrators who
are using HotDocs with a third-party program and want to start an assembly without first displaying the template library
window. (See also Show Library.)
Note:
If using this option at the command line, include the Template File option.

Copyright 2010 HotDocs Ltd. All rights reserved

816

Help Topics for HotDocs Developer 10

HotDocs Auto-Assemble File

/ha="path and file name"
The HotDocs Auto-Assemble File option causes a document to be assembled using the specified auto-assemble
(.HDA) file.
You can also specify a URL for the path and file name (for example, /ha=http://www.yoursite.com/hdafile.hda).

Copyright 2010 HotDocs Ltd. All rights reserved

817

Help Topics for HotDocs Developer 10

HotDocs Auto-Install File

/hi="path and file name"
The HotDocs Auto-Install File option causes the template set in the specified auto-install (.HDI) file to be installed.
During this process, HotDocs prompts the user for any required information it needs to install the template library to the
correct location.
You can also specify a URL for the path and file name (for example, /hi=http://www.yoursite.com/hdifile.hdi). When this
command is passed, HotDocs downloads the file and prompts the user for the information needed to install the template
library.

Copyright 2010 HotDocs Ltd. All rights reserved

818

Help Topics for HotDocs Developer 10

Interview Scope
/is=u
The Interview Scope option allows you to ask only those dialogs that contain questions not answered by an existing
answer file. This may be useful, for example, if you have some answers you are retrieving from a database that you don't
want the user to change. Using this option will ask only those questions that don't have answers.
Caution:
If you do not want certain variables to appear in an interview, do not include them in an explicit ASK instruction.
Otherwise, HotDocs will present the variables to the user.

Copyright 2010 HotDocs Ltd. All rights reserved

819

Help Topics for HotDocs Developer 10

Keep Interview Group

/kig
The Keep Interview Group option is used to control which questions are asked when assembling a group of related
documents, specifically, it keeps questions that are already answered in one interview from being asked in subsequent
interviews. It must be used with the Start Interview Group option, which must be assigned to each subsequent template
within the group.
For example, you have three related templates that will be added to the assembly queue (Template A, Template B, and
Template C). Each of these templates uses Variable A. To keep Variable A from being asked in all three interviews, you
would assign the Start Interview Group option to Template A. Then you would assign the Keep Interview Group option
to Templates B and C. Once the user answers Variable A, it will not be asked in any subsequent interviews.
If a template is added to the assembly queue that doesn't use either of these options, it and any subsequent templates will
not be included in the interview group.

Copyright 2010 HotDocs Ltd. All rights reserved

820

Help Topics for HotDocs Developer 10

Library File
/lf="path and file name"
The Library File option allows you to start HotDocs and open a specific library. If HotDocs is already running, it opens the
library specified by the path and file name.

Copyright 2010 HotDocs Ltd. All rights reserved

821

Help Topics for HotDocs Developer 10

Lock Answer File

/la
The Lock Answer File option prevents users from opening, closing, and saving answer files during document assembly.
If it is the only option used, however, users can choose an answer file before assembly and save any answers they have
entered after assembly.
To keep users from choosing an answer file before assembly, specify an answer file using the Answer File option. To
keep them from manually saving their answers, use either the Discard Answers option or the Save Answers option.
Note:
If using this option at the command line, include the Template File option.

Copyright 2010 HotDocs Ltd. All rights reserved

822

Help Topics for HotDocs Developer 10

Lock Library
/ll
The Lock Library option locks the current library and prevents the user from editing the library or its contents.
Specifically, when HotDocs is launched and the library appears, users can select templates and assemble documents
from them. They can also view the answer library and change user preferences at the HotDocs Options dialog box. All
other options are unavailable.

Copyright 2010 HotDocs Ltd. All rights reserved

823

Help Topics for HotDocs Developer 10

Model Document
/mo
The Model Document command-line option indicates that the file referenced in the library is a model document. When
you select the document in the library and click Assemble, HotDocs will create an interview for the model document.
Note:
See Overview: Create a Model Document for more information.

Copyright 2010 HotDocs Ltd. All rights reserved

824

Help Topics for HotDocs Developer 10

New Answer File

/na[="path and file name"]
The New Answer File option specifies a new, untitled answer file to be used when assembling a given document. This
option causes HotDocs to suppress the Answer File dialog box, which normally appears before assembly. Specifying a
path and file name is optional. If a file name is specified, it will be used for the new answer file. If an answer file with that
same name already exists, HotDocs overwrites the existing file with the new one. If no file name is specified, HotDocs
displays a Save Answer File dialog box at the end of assembly.
When specifying an answer file name, you must include the file name extension .ANX.
Note:
If using this option at the command line, include the Template File option.

Copyright 2010 HotDocs Ltd. All rights reserved

825

Help Topics for HotDocs Developer 10

No Assembly Window
/nw
The No Assembly Window option causes HotDocs to assemble a document without displaying the assembly window.
Note:
If using this option at the command line, include the Template File and Answer File options. If using this option
at the library properties, include the Answer File option.
You should also use the Output File or Send to Word Processor option if you want HotDocs to produce a
document at the end of the assembly.

Copyright 2010 HotDocs Ltd. All rights reserved

826

Help Topics for HotDocs Developer 10

No Interview
/ni
The No Interview option removes the Interview tab from the assembly window, and, by default, displays the assembled
document in the Document Preview or Form Document tab (depending on whether you are assembling a text or form
document). To present a correctly assembled document, you should specify an answer file using the Answer File option.
Otherwise, the document will be assembled without any answers.
Note:
While viewing an assembled document that was generated using this command-line option, you cannot edit
answers while viewing the Document tab.
If using this option at the command line, include the Template File and Answer File options. If using this option
at the library properties, include the Answer File option.

Copyright 2010 HotDocs Ltd. All rights reserved

827

Help Topics for HotDocs Developer 10

Output File
/of="path and file name"
The Output File option causes HotDocs to assemble the document and save it using the file name specified. If you are
using the Answer Summary or Question Summary options, the Output File option specifies the name for either of
those generated documents. This is useful if you know you want to save an assembled document every time assembly of
that document finishes.
Note:
If using this option at the command line, include the Template File option.

Copyright 2010 HotDocs Ltd. All rights reserved

828

Help Topics for HotDocs Developer 10

Overlay Answer File

/ov="path and file name"
The Overlay Answer File option causes HotDocs to take answers from a specific answer file and overlay them in the
current answer file. For example, if you have specific information about a client that can be used in assembling multiple
documents, you can save just that information in an overlay answer file and then use the Overlay Answer File option
to force HotDocs to use those answers when assembling a document. All answers entered during assembly (including
overlaid answers) are saved to the current answer filenot the overlay answer filethus maintaining the integrity of the
overlay answer file. An overlay answer file is loaded after the regular answer file so that the answers contained therein
can overlay existing answers.
If you do not include a full path on the command-line, HotDocs will first look for the answer file in the same folder as the
template. If it's not located there, HotDocs will look in the Answers folder.
You can retrieve an overlay answer file from a location on a Web server by specifying a URL for the path and file name
(for example, /ov=http://www.yoursite.com/overlayanswers.anx).
Note:
If you are saving the overlay answer file to the same folder as the template, do not use the same name as the
template. Otherwise, HotDocs will think the answer file is a default answer file. (See Create a Default Answer
File.)
If using this option at the command line, include the Template File option.

Copyright 2010 HotDocs Ltd. All rights reserved

829

Help Topics for HotDocs Developer 10

Paper Size
/ps=paper size
The Paper Size option selects the specified paper size when the user prints a copy of the form template or document.
The effect is the same as manually setting the page size from the Print dialog box. This option works with form templates
and documents only.
Paper size values that can be used include letter, legal, and so forth. For a complete list of acceptable values, either at
the assembly window or at the HotDocs Filler window, click Document Properties > Printing (File menu) and click the
Paper Size drop-down button. Values that include a space character must be placed inside quotation marks. You can
shorten the values as long as the shortened form matches only one paper size. Paper size values are not case-sensitive.
Note:
If a paper size is specified at the Printing Properties dialog box and the Paper Size command-line option is also
used, the command-line option takes precedence.
If using this option at the command line, include the Template File option.

Copyright 2010 HotDocs Ltd. All rights reserved

830

Help Topics for HotDocs Developer 10

Paper Tray
/pt=paper tray
Caution:
This option is used with form documents only.
The Paper Tray option causes a specified printer paper tray or manual feed option to be used when printing a form
document from HotDocs Filler. Paper tray values that can be used include manual, upper, lower, and so forth. For
a complete list of acceptable values, either at the assembly window or at the HotDocs Filler window, click Document
Properties > Printing (File menu) and click the Paper Source drop-down button.
Note:
If a paper source is specified at the Printing Properties dialog box and the Paper Tray command-line option is
also used, the command-line option takes precedence.
If using this option at the command line, include the Template File option.

Copyright 2010 HotDocs Ltd. All rights reserved

831

Help Topics for HotDocs Developer 10

Print
/pr
Caution:
This option is used with form documents only.
The Print option causes HotDocs to print a copy of the assembled text or form document once the user closes the
assembly window. This is useful if you know you will always need to print a copy of a specific assembled document.
Note:
If using this option at the command line, include the Template File option.

Copyright 2010 HotDocs Ltd. All rights reserved

832

Help Topics for HotDocs Developer 10

Print Answers Only

/pa
Caution:
This option is used with form documents only.
The Print Answers Only option selects the Answers Only (Use Preprinted Form) option at the Print dialog box. Then,
when the user prints the assembled form document, it prints only the form's answers and not the underlying static text.
This allows you to use preprinted forms.
Note:
If using this option at the command line, include the Template File option.

Copyright 2010 HotDocs Ltd. All rights reserved

833

Help Topics for HotDocs Developer 10

Print Both
/pb
Caution:
This option is used with form documents only.
The Print Both option selects the Form with Answers option at the Print dialog box. Then, when the user prints the form
document, the current form and its answers are printed.
Note:
If using this option at the command line, include the Template File option.

Copyright 2010 HotDocs Ltd. All rights reserved

834

Help Topics for HotDocs Developer 10

Print Copies
/pc=numberofcopies
Caution:
This option is used with form documents only.
The Print Copies option specifies the number of copies that should be printed when the user prints the form document.
This number should appear in the Number of Copies box at the Print dialog box.
Note:
If using this option at the command line, include the Template File option.

Copyright 2010 HotDocs Ltd. All rights reserved

835

Help Topics for HotDocs Developer 10

Print Duplex
/pd
Caution:
This option is used with form documents only.
The Print Duplex option sets the duplex printing option for a given form document. It prints the document Double-Sided,
Side-to-Side, as if that option were selected at the Printing Properties dialog box (which you can access by clicking
Document Properties > Printing (File menu).) When the user prints the form document, it is printed using this option.
Note:
If using this option at the command line, include the Template File option.

Copyright 2010 HotDocs Ltd. All rights reserved

836

Help Topics for HotDocs Developer 10

Print Form Only

/po
Caution:
This option is used with form documents only.
The Print Form Only option selects the Form Only (Blank Form) option at the Print dialog box. Then, when the user
prints the form document, it prints a blank copy of the form without answers.
Note:
If using this option at the command line, include the Template File option.

Copyright 2010 HotDocs Ltd. All rights reserved

837

Help Topics for HotDocs Developer 10

Print Without Dialogs

/pw
Caution:
This option is used with form documents only.
The Print Without Dialog option causes HotDocs to bypass the Print dialog box and print the form using the current
printer. The form is printed when the user clicks the Print Document button at the assembly window.
Note:
If using this option at the command line, include the Template File option.

Copyright 2010 HotDocs Ltd. All rights reserved

838

Help Topics for HotDocs Developer 10

Question Summary
/qs
The Question Summary option is used with the Output File option to specify the path and file name for saving a
question summary. It is useful if you want a certain template to always generate a question summary document.
The Question Summary option is normally used with the No Assembly Window option, which causes HotDocs to
automatically create and save the question summary document without displaying the assembly window.
Question summaries are saved in HTML format.
Note:
If using this option at the command line, include the Template File option.

Copyright 2010 HotDocs Ltd. All rights reserved

839

Help Topics for HotDocs Developer 10

Save Answers
/sa
The Save Answers option forces an answer file to be saved at the end of an assembly. If using an existing answer file,
any answers entered during the interview will be saved automatically. If using a new, untitled answer file, HotDocs will
force the user to specify an answer file name.
Note:
To always force the user to save a new answer file after entering answers in an intervieweven if using an
existing answer fileuse the Save Answers Prompt option.
To give users the option of saving an answer file, rather than forcing them to save, use either the Suggest Save
or the Suggest Save New option.

Copyright 2010 HotDocs Ltd. All rights reserved

840

Help Topics for HotDocs Developer 10

Save Answers Prompt

/sap
The Save Answers Prompt option, which is used in connection with an ASSEMBLE instruction, prompts the user to save
an answer file after completing an interview. Regardless of whether the user uses an existing answer file during assembly,
when the user finishes that assembly, HotDocs prompts to save the answers in a different file.
Note:
To always save an answer file without prompting the user for an answer file name (unless the user is using a new
answer file) use the Save Answers option.
To give users the option of saving an answer file, rather than forcing them to save, use either the Suggest Save
or the Suggest Save New option.

Copyright 2010 HotDocs Ltd. All rights reserved

841

Help Topics for HotDocs Developer 10

Send to Word Processor

/stw
The Send to Word Processor option sends the assembled document to the word processor once the user closes the
assembly window. This is useful if you know you always want to view the assembled document using the word processing
program.
Note:
If using this option at the command line, include the Template File option.

Copyright 2010 HotDocs Ltd. All rights reserved

842

Help Topics for HotDocs Developer 10

Show Library
/sl
The Show Library option forces HotDocs to display the template library if it is currently not showing. This is useful if you
are integrating HotDocs with another program and you have hidden the library using the Hide Library option.

Copyright 2010 HotDocs Ltd. All rights reserved

843

Help Topics for HotDocs Developer 10

Start Interview Group

/sig
The Start Interview Group option is used to control which questions are asked when assembling a group of related
documents, specifically, it keeps questions that are already answered in one interview from being asked in subsequent
interviews. It must be used with the Keep Interview Group option, which must be assigned to each subsequent template
within the group.
For example, you have three related templates that will be added to the assembly queue (Template A, Template B, and
Template C). Each of these templates uses Variable A. To keep Variable A from being asked in all three interviews, you
would assign the Start Interview Group option to Template A. Then you would assign the Keep Interview Group option
to Templates B and C. Once the user answers Variable A, it will not be asked in any subsequent interviews.
If a template is added to the assembly queue that doesn't use either of these options, it and any subsequent templates will
not be included in the interview group.

Copyright 2010 HotDocs Ltd. All rights reserved

844

Help Topics for HotDocs Developer 10

Suggest Save
/ss
The Suggest Save option, which is used in connection with an ASSEMBLE instruction, causes HotDocs to ask users
after assembly of a document has finished if they want to save answers entered during the interview in an answer file.
Specifically, if the user has assembled a document and made changes to an existing answer file, HotDocs prompts to
save the answers to that file. If saving a new, untitled file, HotDocs allows the user to specify the new answer file name.
Note:
If your user is using an existing answer file but you want to give the user the option of saving the answers in a
new, different answer file, use the Suggest Save New option.
If you want to force users to save their answers after an assembly is finished, rather than give them the option,
use either the Save Answers or the Save Answers Prompt options.

Copyright 2010 HotDocs Ltd. All rights reserved

845

Help Topics for HotDocs Developer 10

Suggest Save New

/ssn
The Suggest Save New option, which is used in connection with an ASSEMBLE instruction, causes HotDocs to ask if
answers should be saved in a new answer file after assembly of a document has finished. Regardless of whether the user
is using an existing answer file during assembly, when the user finishes that assembly, HotDocs gives the user the option
of saving the answers in a new answer file.
Note:
If your users are using an existing answer file and you want them to save answers they have entered in that file
instead of a new one, use the Suggest Save option.
If you want to force users to save their answers after an assembly is finished, rather than give them the option,
use either the Save Answers or the Save Answers Prompt options.

Copyright 2010 HotDocs Ltd. All rights reserved

846

Help Topics for HotDocs Developer 10

Suppress Unanswered Warning

/sw
The Suppress Unanswered Warning option keeps HotDocs from displaying the warning dialog box that appears when
the user attempts to either print, save, or send the assembled document to the word processor and the assembled
document still contains unanswered questions.

Copyright 2010 HotDocs Ltd. All rights reserved

847

Help Topics for HotDocs Developer 10

Template File
/tf="path and file name"
The Template File option causes HotDocs to assemble a document using the specified template or clause library.
Caution:
If you want an interview template (component file) started from the Template File command line, the component file
must have an INTERVIEW or STARTUP computation in it or assembly will fail.

Copyright 2010 HotDocs Ltd. All rights reserved

848

Help Topics for HotDocs Developer 10

Use Command-Line Options at File Properties

To add command-line options to a library item

1. Open a library at the HotDocs library window.

2. Select the library item and click the

Properties button to open the Item Properties dialog box.

3. In the File name box, following the file name, type a space and the command-line options you want to use. For
example:
/af="C:\Documents and Settings\Username\My Documents\HotDocs\Answers\jalvey.anx"

Copyright 2010 HotDocs Ltd. All rights reserved

849

Help Topics for HotDocs Developer 10

Use Command-Line Options When Starting HotDocs

To use command-line options when starting HotDocs

1. Choose Run from the Start menu. The Run dialog box appears.
2. Type "C:\Program Files\hotdocs.exe" (including the quotation marks) followed by a space and the options you
want in the Open box. For example:
"C:\Program Files\HotDocs\Hotdocs.exe" /tf=demoempl.rtf

3. Click OK. If HotDocs is not already running, it loads and then performs the command-line instructions. If HotDocs is
already running, it performs the command-line instructions.

Copyright 2010 HotDocs Ltd. All rights reserved

850

Help Topics for HotDocs Developer 10

Use Command-Line Options when Using a Shortcut to Start HotDocs

To use command-line options when using a shortcut to start HotDocs

1. Locate the HotDocs program file shortcut. (A shortcut is an icon on the desktop or Start menu that a user can click
to quickly access a program.)

2. Right-click the icon and select Properties from the shortcut menu. The program item's Properties dialog box
appears.

3. Select the Shortcut tab.

4. In the Target box, enter a space after the executable (.EXE) file and type the options you want.

Copyright 2010 HotDocs Ltd. All rights reserved

851

Help Topics for HotDocs Developer 10

SECTION 10:
MODEL DOCUMENTS

Copyright 2010 HotDocs Ltd. All rights reserved

852

Help Topics for HotDocs Developer 10

Chapter 56: Creating and Using Model Documents

Overview: Create a Model Document
As you draft documents for your clients, you frequently modify existing documents by replacing the changeable text in the
document (such as names, dates, and figures) with the current clients information. This process can be time-consuming
and error-prone, especially because you must go through this process for each new client or matter.
One way you can solve this problem is to create a HotDocs template from the document. This process requires someone
with HotDocs knowledge to replace changeable text with variables, conditions, and scripts. Depending on how complex
the template is, sometimes the automated template can be difficult for non-HotDocs developers to read and understand.
Another option is to instead create a model document. Model documents are ideal for subject matter experts who want to
learn a simpler language for marking text that varies from one client to another in the document. This language, the Model
Document Markup Langauge (or MDML), provides an unambiguous description of how a model document should be used
to draft client-specific documents. Resulting documents are easier to read and understand.
Once you have a model document, you can use it with HotDocs to generate documents for your clients. If you are using
HotDocs Developer, you can also convert your model documents to HotDocs template format so they can be added to
your collection of templates.
For example, say you have a will that could include different provisions for different inheritance scenarios. Some
provisions should be included if you're drafting a will for one type of client, but those same provisions should be left out
for other types of clients. With a model document, you keep all of the different text variations in a single document, rather
than storing the text in separate documents. Then, using MDML, you can mark up the document so that only the correct
versions are used, depending on answers the user gives.
You mark up model documents directly in Microsoft Word. Your documents must be in DOC or RTF format.
For full instructions on using model documents, please visit http://help.hotdocs.com/modeldocuments.
For instructions on using model documents with HotDocs, click the following links:
Convert HotDocs Templates to Model Documents
Convert Model Documents to HotDocs Template Format

Copyright 2010 HotDocs Ltd. All rights reserved

853

Help Topics for HotDocs Developer 10

Convert HotDocs Templates to Model Documents

Note:
See http://help.hotdocs.com/modeldocuments for full instructions on creating model documents.
You can convert existing HotDocs templates to model documents. Saving templates as model documents allows you to
share your templates with subject matter experts unfamiliar with HotDocs. As long as those experts understand (and use)
the markup language specified in this help file, they can further automate the template and use it with HotDocs Player to
assemble documents from it.
When you convert a template to a model, HotDocs converts variable and instruction fields to markup fields. Variable
and instruction properties are stored in tables at the end of the document. Component file properties are saved in an
embedded component file.
Note:
Some template development features are not supported in model documents. This includes pointed component files
and clause libraries.
To convert a template to a model document

1. At the template library, select the template you want to convert.

2. Click Convert Template to Model (Template menu). The Convert HotDocs Template to Model Document dialog
box appears.

3. Optionally, change the name of the model document in the Model document file name box. (By default, HotDocs
appends the text .model to the file name. This helps distinguish between it and the original template file.)

4. Optionally, select Add converted model document to library to add a reference to the model to the library. This
allows you to more easily assemble the model document using the Assemble command.

5. Click OK. HotDocs converts the template. You can further edit the model or distribute copies of it to others for review
or additional markup.

Copyright 2010 HotDocs Ltd. All rights reserved

854

Help Topics for HotDocs Developer 10

Convert Model Documents to HotDocs Template Format

Note:
See http://help.hotdocs.com/modeldocuments for full instructions on creating model documents.
Once you have marked up a document, you can convert the model document to template format. Markup fields in the
model are converted to variable and instruction fields. Once converted, you can edit the template or assemble it.
To convert the document to template format

1. At the HotDocs library, choose Convert Model to Template (Template menu). The Convert Model Document to
HotDocs Template dialog box appears.

2. Click the

Browse button next to the Model document file name box and locate the model document.

3. Enter a file path and name for the newly created template in the HotDocs template file name box. (HotDocs
automatically suggests the same name as the model, with the text .template appended to it.)

4. Optionally, select Add converted HotDocs template to library. This places a reference to the template in the
HotDocs library.

5. Click OK. The template is created from the marked up model document.

Copyright 2010 HotDocs Ltd. All rights reserved

855

Help Topics for HotDocs Developer 10

Model Document Naming Standards

When marking up model documents, you must adhere to the Model Document Markup Language, which requires you
to follow certain rules and suggestions when naming variables and other fields in the model. Failure to follow these
standards, particularly #1, may result in errors or other problems when users attempt to assemble the model document.
Specifically:

1. You must use only letters, digits, and underscores. You cannot use spaces or other special characters.
2. You should use names that are at least two words.
3. You should make one of the words in the name the "subject" word (Client, Child, etc.).
4. You should capitalize the first letter of each word, regardless of part of speech.
5. You must never use names that are all capitals.
Note:
If you must include spaces or special characters in your variable and other field names, you can select a HotDocs
option that allows this. See Allow Non-Standard Names in Model Documents.

Copyright 2010 HotDocs Ltd. All rights reserved

856

Help Topics for HotDocs Developer 10

SECTION 11:
TROUBLESHOOTING

Copyright 2010 HotDocs Ltd. All rights reserved

857

Help Topics for HotDocs Developer 10

Chapter 57: Template Development

Can't Dynamically Add Merge Text to a Multiple Choice Variable
Problem
I'm creating my Multiple Choice variables "on the fly," using the CLEAR and ADD instructions. I know I can ADD options
and prompts, but can I ADD Merge Text to the variable?

Solution
Unlike options and prompts, the merge text for a Multiple Choice variable comes from another componenta Merge Text
component. This means you cannot create and add merge text to a Multiple Choice variable "on the fly."

Copyright 2010 HotDocs Ltd. All rights reserved

858

Help Topics for HotDocs Developer 10

Changing the Order Questions are Asked in an Interview

Problem
I have completed automation on my template but when I test assemble it, I find that I want the questions asked in a
different order than how HotDocs is asking them. Is there some way to override the order dialogs are asked?

Solution
By default, HotDocs generates this interview by asking variables as it reads them in the template. When a variable is
linked to a dialog, the dialog is asked. For most templates, this default interview is sufficient. However, there may be times
when you want to control the order questions are asked.
There are two ways to accomplish this: 1) Use an ASK instruction to ask a single dialog at a specific place in the
interview, and 2) use an INTERVIEW computation to define the order of all dialogs in template.
For details, see Control When Your Dialogs Appear and Define a Custom Interview.

Copyright 2010 HotDocs Ltd. All rights reserved

859

Help Topics for HotDocs Developer 10

Checking the Spelling of Library Entries

Problem
How can I spell check the items in my template library?

Solution
There is no spell-checking capabilities at the template library. You can, however, copy the text of a library to a word
processor and spell check it there. You must manually update entries in the library with any corrections.
To spell check your library

1. At the template library, choose File > Export Library to > Plain Text File. The Save As dialog box appears.
2. Specify a file name and location for the text file and click Save. The file is created.
3. Open the plain-text file using Notepad.
4. Select all of the text and copy it. (Press Ctrl+A to select the text, and then press Ctrl+C to copy it.)
5. Open a new word processor document and paste the text. (Press Ctrl+V.)
6. Use the word processor's spell checking tool. If there are spelling corrections that need to be made, return to the
library and make the change. (To edit template titles, select the file and click the

Copyright 2010 HotDocs Ltd. All rights reserved

Properties button.)

860

Help Topics for HotDocs Developer 10

Child Dialog Always Appearing in Interview Outline Even When it Shouldn't

Problem
I have a child dialog that is always appearing in the interview, even when there are times it shouldn't. How can I make the
child dialog optional?

Solution
When you add a child dialog to a parent dialog, you can group the child dialog so users can more easily specify if they
want to answer it. When you group child dialogs, HotDocs places a check box or option button in front of the child dialog
icon. When this check box or option button is selected, HotDocs places the child dialog in the interview outline so that its
contents can be answered. Otherwise, HotDocs will treat the child dialog as if it doesn't existeven if there are required
variables in it.
If child dialogs are not grouped, each child dialog will appear in the interview outline, regardless of whether the dialog is
optional to answer. If the user does not answer every question in every dialog, HotDocs will report in the End of Interview
dialog that there are unanswered questions.
For instructions on grouping child dialogs, see Group Child Dialogs in a Parent Dialog.

Copyright 2010 HotDocs Ltd. All rights reserved

861

Help Topics for HotDocs Developer 10

Choosing Which Word Processor Will Be Used By Default

Problem
I have multiple word processors installed on my computer. I want to use a specific word processor for creating templates
but HotDocs keeps defaulting to the other word processor. I also want to send assembled documents to one word
processor, but again, HotDocs defaults to the other. How can I fix this?

Solution
You can specify which word processor you want to use when creating templates. This same word processor will be used
for viewing assembled text documents. For details, see Change Your Default Word Processor.

Copyright 2010 HotDocs Ltd. All rights reserved

862

Help Topics for HotDocs Developer 10

Comparing the Contents of Two or More Component Files

Problem
I need to compare the contents of two or more component files, but I can't seem to open two different copies of
Component Manager to do so. Is there some way to do this?

Solution
You can use Template Manager to simultaneously compare the contents of two or more component files. For complete
instructions, see Understand Parts of Template Manager Window.

Copyright 2010 HotDocs Ltd. All rights reserved

863

Help Topics for HotDocs Developer 10

Converting WordPerfect Templates to Word

Problem
I recently switched from using WordPerfect to Microsoft Word. Can I convert my templates to Word format, and, if so,
how?

Solution
You can convert your templates to Word format on a template-by-template basis, or you can convert multiple templates
at once using Template Manager. (See Convert Multiple Templates to Work with HotDocs 10 and Convert Templates and
Clauses to Microsoft RTF for details.)
Once converted, you should review each template carefully to make sure it still looks and works correctly.

Copyright 2010 HotDocs Ltd. All rights reserved

864

Help Topics for HotDocs Developer 10

'The Component File Cannot Be Used With This Version of HotDocs' Message
Appearing
Problem
When attempting to edit a template, I get the error message, The component file cannot be used with this version of
HotDocs. What does this message mean?

Solution
This message appears because you are trying to edit a newer version of a template with an older version of HotDocs. For
example, you may be trying to edit a HotDocs 2009-version template with HotDocs 2005. Generally speaking, templates
edited in the latest version of HotDocs are not backwards compatible with older versions.
If you must retain backwards compatibility with your templates, you can select a component file property that makes the
template compatible with a specific version of HotDocs. If doing this, you must be careful not to use any features available
in newer versions of the software, or else the template will not work with the older version. For example, dot codes are a
new feature of HotDocs 2006. If you make a template containing dot codes available to HotDocs 2005 users, the template
will generate errors because HotDocs 2005 has no support for dot codes.
See Compatibility of HotDocs 10 Files with Earlier Versions of HotDocs for details.

Copyright 2010 HotDocs Ltd. All rights reserved

865

Help Topics for HotDocs Developer 10

Dot Code Formatting Doesn't Seem to Work in True/False and Multiple Choice
Options
Problem
Formatting dot codes (such bold, italics, and underline) assigned to Multiple Choice and True/False variable prompts don't
work.

Solution
If a Multiple Choice or True/False variable prompt contains a formatting dot code and the variable is set to appear either
as option buttons or check boxes, the prompt text will not be formatted. This is a known limitation of dot codes.

Copyright 2010 HotDocs Ltd. All rights reserved

866

Help Topics for HotDocs Developer 10

Editing Answer Source Records Causes Problems

Problem
I have an answer source whose records become jumbled anytime I edit records in it. Specifically, if I add a new record,
some answers from other records appear in the new record. Those answers then disappear from their actual records.
How can I keep this from happening?

Solution
Answer sources are associated with specific dialogs in a template. When users view the dialog during the interview, they
can click a special button, which displays a list of answers that were entered during previous interview sessions. They can
either select an existing set of answers or add a new set to the list.
After creating an answer source for one dialog, you can use it with other dialogs, including dialogs in other templates.
However, when using an answer source with multiple dialogs, each variable must be represented in both the answer
source and in each dialog. If a variable that is referenced in the answer source isnt included in all of the dialogs that link
to it (or vice-versa), answers in the answer source will get "mixed together" whenever you add, edit, or delete records.
In some situations, though, it isnt always practical or relevant to show the user every variableeither in the dialog or
in the answer source. To accommodate this, you should use the HIDE, CONCEAL, and OMIT instructions in a dialog
script to manipulate these variables both in the dialogs and the answer source. Specifically, HIDE keeps a variable from
appearing on the dialog, while CONCEAL keeps it from appearing in the answer source. OMIT keeps the variable from
being associated with the answer source at all. Often, you must use a combination of these instructions to achieve your
desired result.

Copyright 2010 HotDocs Ltd. All rights reserved

867

Help Topics for HotDocs Developer 10

Enabling Multiple Templates for Use with HotDocs Server At Once

Problem
I am automating a set of templates that I plan to use with HotDocs Server. All of these templates need to be enabled for
use with Server. How do I specify this setting for all templates at once?

Solution
If you need to enable this setting for existing templates, you can use Template Manager.
To enable multiple templates for use with HotDocs Server at once

1. At your template library, select the templates you want to enable.

2. Click the

Template Manager button. The Template Manager window appears.

3. Select the templates in the list and click the

Component File Properties button. The Component File

Properties dialog box appears.

4. Click the HotDocs Server tab and select Enable template for use with HotDocs Server.
5. Select any other Server options and click OK. The selected templates are now enabled for use with Server.
You can also set this option for all new templates you create. To do this, see Enable All New Templates for Use with
HotDocs Server.

Copyright 2010 HotDocs Ltd. All rights reserved

868

Help Topics for HotDocs Developer 10

Entered Answers Getting Overwritten

Problem
In HotDocs 5, I could ask a question in the interview, allow the user to answer the question, and then use a SET
instruction to assign a different answer to the question later in the interview. In current HotDocs, however, the answer
used in the SET instruction is always overwriting any answers entered by the user. What can I do to fix this?

Solution
Simply stated, don't automate your templates this way. Because scripting in dialogs is processed each time you answer a
question in the interview, you cannot ask a variable in an interview and then later SET that variable's value to something
else. In all cases, each time the interview is updated, the SET instruction value will overwrite any answers the user enters.
See Overview: HotDocs Interviews, Automatically Assign Answers to a Variable, and Check Interviews for Improper
Scripting for details.

Copyright 2010 HotDocs Ltd. All rights reserved

869

Help Topics for HotDocs Developer 10

Entering Multiple Choice Option Prompts and Merge Text

Problem
I want to enter a long prompt and merge text for a Multiple Choice variable, but there isn't much room to enter it at the
Properties tab of the Multiple Choice Variable Editor. Is there some way to enter the text and be able to see it all at
once?

Solution
If you need to enter lengthy prompt text or merge text, you can do so at the Options tab of the Multiple Choice Variable
Editor.
To add prompt text

1. Edit the Multiple Choice variable. (See Customize a Multiple Choice Variable.)
2. Click the Options tab. The view changes to show different ways you can customize the multiple choice options.
3. Click the Option drop-down button and choose the option you want to customize.
4. Enter the prompt text in the Prompt box.
5. Repeat steps 3 and 4 for any additional options you want to customize further.
6. Optionally, enter longer merge text in the Default merge text box.

Copyright 2010 HotDocs Ltd. All rights reserved

870

Help Topics for HotDocs Developer 10

Fixing Warnings Listed at Warnings Tab

Problem
The HotDocs Warnings tab shows several warnings listed in it. How do I fix them?

Solution
Many of these warnings pertain to variables being asked incorrectly in the interview.
To correct the problem, select the warning in the list and click the Go to Warning button. HotDocs takes you to the script
or location in the template where the error occurs so you can correct it.
The following table lists each warning, followed by a description of what it means:
Warning

Description

Variables that are set to a

When HotDocs generates an interview outline, it processes any SET instructions and
value and are marked "Save assigns answers to the variables that are set. This causes HotDocs to ask to save the
in answer file"
answer file, even if the user doesn't enter any answers during the interview.
Variables that are set to
a value and asked in the
same interview

You should not use a SET instruction to assign an answer to a variable and then ask the
variable later in the interview. As HotDocs processes answers and rebuilds the interview,
the value assigned by the SET instruction will always overwrite any answers the user
provides. An example of this would be the following script:
SET TF Variable TO TRUE
... (later in the template)
ASK Dialog
(where Dialog uses the variable, TF Variable.)
In this situation, even if the user marks TF Variable as false, HotDocs will always change
it back to true because of the SET instruction.
If you want to suggest an answer for a user, use the DEFAULT instruction instead of the
SET instruction. If you want a variable to always have a specific answer, then SET the
answer and do not ask that variable anywhere in the template.

Variables that are asked

more than once in the same
interview

You should not ask the same variable more than once in an interview. If you do, HotDocs
will always assign the last answer you gave to the variable, no matter where it is used in
the interview.

Variables that are referred

to in a dialog script and are
set to a value later

You should not refer to a variable in a dialog script and then set that variable to a value
later in the template. When HotDocs reprocesses the interview, the set value may
change the appearance of the dialogincluding how it presents variables to the user and
how it processes the answers.
An example of this would be the following script:
SET
ASK
SET
ASK

Client TO "Husband"
Husband Information
Client TO "Wife"
Wife Information

In and of itself, this script is OK. However, Husband Information and Wife Information are
dialogs that contain the following dialog element text:
Copyright 2010 HotDocs Ltd. All rights reserved

871

Help Topics for HotDocs Developer 10

The following information applies to the Husband or Wife.

Husband or Wife is a computation that merges the literal text "husband" or "wife" into
dialog element text, depending on the answer to Client.
Because HotDocs continually updates the interview, it will always use the last value
resulted for this computation, which means that the dialog element text will always merge
the word "wife," even if the user is viewing the Husband Information dialog. This could be
confusing to the user.
Variables that are not asked
when referred to but are
asked later

You can refer to a variable in a template without asking the variable (by referring to the
variable in an ASK NONE block or by clearing the Ask automatically option for the
variable). However, if you do this, you should not ask the variable or set it to a value later
in the template. Doing this will replace the answer that was used for the variable earlier in
the template, thus causing an inconsistency.

Copyright 2010 HotDocs Ltd. All rights reserved

872

Help Topics for HotDocs Developer 10

Foreign Characters Are Appearing as Boxes or Question Marks in HotDocs

Problem
I am using foreign (or Unicode) characters in my template, but they are appearing as boxes or question marks.

Solution
Even though HotDocs supports Unicode characters, these characters may not appear correctly if you do not have fonts
installed that can display them.
For example, say you automate your template using the Tahoma font on Windows Vista. If the template is used on an
earlier operating system, some of the characters you have used may not appear correctly because those characters may
not be supported in the version of Tahoma available on that operating system.
Or, perhaps you use a very specialized font for displaying symbolic characters. If your users do not have the same font
installed on their computers, your text will appear as unrecognized charactersusually boxes or question marks.
Additionally, you must also be careful when assigning font styles (such as bold or italic) to international characters, as
characters may not display correctly when these styles are applied.

Copyright 2010 HotDocs Ltd. All rights reserved

873

Help Topics for HotDocs Developer 10

Getting Missing END IF or Missing END REPEAT Errors

Problem
When I test assemble my template, I get a Missing END IF (or a Missing END REPEAT) error. I have a lot of different
instructions in my templatehow can I determine where the END instruction is missing?

Solution
The HotDocs Outliner can help you quickly locate the opening IF instruction that isn't paired with a closing instruction.
To use the HotDocs Outliner

1. At the template, click the

HotDocs Outliner button. HotDocs displays an error message saying an END

instruction is missing. (This is correct.)

2. Click on this warning and click Go to Error in Template. HotDocs highlights the opening instruction.
3. Determine where the closing instruction should appear and merge it in the template. (You can manually create the
END field, or you can copy an existing field and replace the text between the chevrons with the appropriate END
instruction.)
Note:
Two other tools can help you match opening instructions with their closing instructions. These are the

Match

Fields tool and the

Label Fields tool. See Match Opening Instructions with Closing Instructions and Use
Labels to Identify Instructions for details.
The only time an END instruction should not be used is when inserting a REPEAT instruction in a table. See Use
a Word Processor Table to Display a List for details. In all other cases, every IF and REPEAT instruction must
have a corresponding END instruction.

Copyright 2010 HotDocs Ltd. All rights reserved

874

Help Topics for HotDocs Developer 10

Hiding the End of Interview Dialog During the Interview

Problem
When assembling the document, I want the users to go from the last dialog in the interview directly to the assembled
document. I don't want the End of Interview dialog to be shown. How can I keep this from appearing?

Solution
You can specify a component file property that keeps the End of Interview dialog from appearing during the interview.
To specify this property

1. Open Component Manager.

2. Click the

Component File Properties button. The Component File Properties dialog box appears.

3. Click the Interview tab. The view changes to show interview properties.
4. Select Hide End of Interview dialog.
5. Click OK.
Now, whenever users assemble this template, clicking
document.

Copyright 2010 HotDocs Ltd. All rights reserved

Next at the last dialog will take them to the assembled

875

Help Topics for HotDocs Developer 10

'HotDocs Cannot Play the Macro HD6EditTemplate.Main' Message Appearing

Problem
When attempting to edit a template, I get the error message, HotDocs cannot play the macro HDEditTemplate.Main
because the macro does not exist in the original template or in a template currently loaded into Word. What does this
message mean?
Note:
Several file names and locations were changed for HotDocs 10. For a list of these changes, please see New and
Enhanced Features for HotDocs 10

Solution
The first thing to check is to make sure that HotDocs is putting its global macro templates in the right location, and also to
make sure that Word is finding them. To do this, complete the following steps:

1. In Windows Explorer, browse to C:\Program Files\HotDocs\Source\Word\Macros, and make a note of the file
dates on the files in that folder.

2. In HotDocs, go to Tools > Options > Word Processors > Word 2000. Make a note of the Startup Folder location
and browse to that folder in Windows Explorer. (You can click the
and it will open that folder in Windows Explorer.)

Browse button next to the Startup folder box

3. Compare the files in the folder opened through HotDocs with the files you found in step #1 above and make sure
that hd6edit.dot and hd6icon.dot match exactly. (If they don't, you need to copy the files from the "source" folder to
the "startup" folder.)

4. In Word, go to Tools > Templates and Add-ins and make sure that hd6edit.dot and hd6icon.dot are both listed
and checked, which indicates that they are loaded.
Assuming these steps check out OK, another place to look is in Word's macro security settings. Although the HotDocs
macros are digitally signed and should not be blocked even if you have your security set to the highest level, you could try
temporarily lowering the security level to see if it makes a difference:
In Word, go to Tools > Macro > Security. At the Security Level tab, lower the security level to Medium or Low and
then see if the macros work under one of those settings. If it doesn't make a difference, be sure to switch it back to
the previous setting.
Finally, you should check to make sure that the version of hd_api.dll in your Windows system folder is the correct
version:

1. In HotDocs, go to Help > About HotDocs > Version Info. Make a note of the file version for hotdocs.exe.
2. In Windows Explorer, browse to C:\Windows\System32 and find the file named hd_api.dll.
3. Right-click on hd_api.dll and choose Properties from the shortcut menu.
4. At the Version tab, check to see if the file version is the same as that of hotdocs.exe.
5. If the versions do not match, delete the DLL file from the Windows folder and repair the HotDocs installation.

Copyright 2010 HotDocs Ltd. All rights reserved

876

Help Topics for HotDocs Developer 10

HotDocs is Creating Database File with Library File

Problem
I've noticed that there's a Microsoft Access database file saved in the same folder as my template library. This file also
has the same name as my library. What is this file, and can I edit it?

Solution
When you run Template Manager, it creates a database file in the same folder as the library. This database is necessary
in managing the different templates and components you are viewing in Template Manager.
You should not edit this file. If you were to inadvertently change or delete information in the database, it may corrupt your
templates or make them unusable.

Copyright 2010 HotDocs Ltd. All rights reserved

877

Help Topics for HotDocs Developer 10

Keeping Users from Editing Templates

Problem
I need to make templates I've automated available for assembly to several users within our office, but I don't want them to
edit the templates. How can I restrict my users like this?

Solution
There are some options available for limiting use of your templates. Nearly all of the following options involve storing
copies of the files to a different location (such as a network drive), separate from the folder that contains your working
files:
Publish the template files as auto-assemble files and make the auto-assemble files available to your users. See
Publish Templates as Auto-Assemble Files (HDA).
Export the library to a different location and specify that the exported files be used for assembly only. See Create a
New Library By Exporting Part of an Existing Library.
Obtain a publisher's license from HotDocs Corporation and publish the files for use with HotDocs Player. See
Publish and Register Templates for Use With HotDocs Player. (Contact your HotDocs sales representative for
information on acquiring a publishing license.)
Mark the folder where the files are stored as read-only. Mark the template files within the folder as read-only as well.
(See the Windows Help file for instructions on marking folders and files as read-only.)
Publish the templates (as standard template files) but lock the component files. (Make sure you don't inadvertently
replace your working component files with the locked component files. There is no way to recover a locked
component file.) See Protect Published Files.

Copyright 2010 HotDocs Ltd. All rights reserved

878

Help Topics for HotDocs Developer 10

Limiting Visible Rows but Not Limiting Number of Answers

Problem
I want to show only a few rows of a spreadsheet dialog in my interview, but I don't want to limit the number of answers a
user can enter. How can I do this?

Solution
You can control the number of rows that appear in a spreadsheet dialog. This setting has no effect on the number of rows
a user can enter.
To limit the number of visible rows

1. Edit the spreadsheet dialog. (See Edit a Custom Dialog.)

2. In the Rows to display box, enter the number of the rows you want to be visible.
3. Click OK.
Note:
To limit the number of answers a user can enter, use the LIMIT NUM instruction in a dialog script.

Copyright 2010 HotDocs Ltd. All rights reserved

879

Help Topics for HotDocs Developer 10

Matching Pairs of Instructions in a Computation Script

Problem
I have a complicated script that incorporates several IF and REPEAT instructions. I need to be able to see these pairings
better. I know there are several tools for doing this when editing instructions in the text of the template, but I'm unsure of
what's available to me when I'm in a computation script.

Solution
There are a few things you can do to match pairs of instructions while working in a computation script:
Click the
Auto Format button in the script editor toolbar. This indents scripting between instructions. Nested
instructions are likewise indented, like in the following example:

Place your cursor in the opening or closing instruction and press Ctrl+M. HotDocs moves your cursor to the
matching instruction. (You can also choose Match IF/REPEAT from the shortcut menu.)
Copyright 2010 HotDocs Ltd. All rights reserved

880

Help Topics for HotDocs Developer 10

Place your cursor in the opening or closing instruction and press Ctrl+Shift+M. HotDocs highlights the entire section
of the instruction with which you are working. (You can also choose Select IF/REPEAT from the shortcut menu.)
For details, see Use the Script Editor.
For details on working with instructions in a text template, see Match Opening Instructions with Closing Instructions.

Copyright 2010 HotDocs Ltd. All rights reserved

881

Help Topics for HotDocs Developer 10

Merging Check Boxes in a Text Template

Problem
I know how to automate check boxes in my form templates, but I'm unsure of how to create check boxes in a text
template.

Solution
Some fonts on your system include empty box characters, as well as box characters with an X. You simply need to
conditionally insert these characters in your template. For example, if you have the Wingdings 2 font installed on your
computer, you can complete the following steps to merge these characters.
To create check boxes in a text template

1. Automate your template, including specifying the conditional instructions that will merge the correct check box. (Use
placeholder characters to represent the check boxes.)

2. Open the Windows Character Map tool. (For instructions on finding and opening this tool, refer to your Windows
Help.)

3. Click the Font drop-down button and choose Wingdings 2. The character list changes to show the different
characters available to you.

4. Locate a box with an X in it and click Select. This adds the character to the Characters to copy box.
5. Locate a box without an X in it and click Select. This adds this character to the box as well.
6. Click Copy.
7. In the template, place your cursor where the check boxes should go and choose the Paste command (for example,
press Ctrl+V). The characters are inserted in your template. (You may need to highlight the character and choose
Wingdings 2 from the application's font menu to reapply the correct font.)
A simpler way to merge check boxes may be to place either an X character or empty space character between opening
and closing brackets. For example, [X] vs. [ ].

Copyright 2010 HotDocs Ltd. All rights reserved

882

Help Topics for HotDocs Developer 10

Merging Just a Portion of a Date Instead of the Whole Date

Problem
I need to merge just the year part of a date in an answer fieldnot the whole date. How can I limit the answer in this way?

Solution
You can use an example format to merge just a portion of the date. The user will still enter a full date, but only a portion of
it will be merged in the document.
To merge the year only

1. Create a Date variable. (See Customize a Date Variable.)

2. At the Format box (either at the Variable Field dialog box or at the Date Variable Editor), enter 1990.
Using example formats, you can merge a single Date variable in three separate answer fields. For example, say you are
automating a form template and the date needs to appear on three separate blank lines. You can merge the same Date
variable in all three blank spaces, but use different portions of a date format to control what gets merged in each blank
space.
For example, in the following, you'd break the dates into three separate parts:

In the first blank space, you'd merge the Date variable with the format third. In the second blank, you would use June as
the format. In the last blank, you'd use 1990 as the format.

Copyright 2010 HotDocs Ltd. All rights reserved

883

Help Topics for HotDocs Developer 10

Optional Variables Showing Up as Unanswered in Interview and Document

Problem
My template provides an option for users to enter a second address line. However, when users don't have a second
address, HotDocs is merging an unanswered variable marker in the document. It's also reporting in the End of Interview
dialog that some questions are unanswered. How can I keep these markers and warnings from appearing?

Solution
To keep HotDocs from merging an unanswered variable placeholder, you must insert the variable conditionally.
Specifically, you must insert it only if the variable is answered. For example, the following expression in the template will
merge the second address only if the user provides it:
Client Name
Client Address 1
IF ANSWERED(Client Address 2)Client Address 2END IF
Client City, Client State Client ZIP Code

To keep HotDocs from warning the user that the question in the dialog is unanswered, you specify a variable property. At
the Variable Editor, click the Advanced tab and clear Warn when unanswered. (See Control How HotDocs Processes
a Variable.)

Copyright 2010 HotDocs Ltd. All rights reserved

884

Help Topics for HotDocs Developer 10

Punctuating a Repeated List of Answers

Problem
I have created a REPEAT instruction in my template, but when I test it, the answers all run together, for example, like
Answer OneAnswer TwoAnswer Three. How can I separate these answers with the correct punctuation and conjunction?

Solution
You can assign a format to a repeated list of answers. This format separates answers with either commas or semi-colons,
and it also inserts the conjunction AND or OR, depending on your needs. To assign the format, at the REPEAT Field
dialog box, click the Format drop-down button and choose the punctuation style you need.
For instructions on assigning a format in a computation script, see Punctuate a List Using a Computation Variable.

Copyright 2010 HotDocs Ltd. All rights reserved

885

Help Topics for HotDocs Developer 10

Receiving 'Invalid Variable Name' Errors When Creating Components

Problem
When I create a new variable and try to save it, HotDocs displays an Invalid Variable Name error message. What am I
doing wrong that causes this error to appear?

Solution
When naming variables, there are a few rules you must follow:
A variable name can have up to 50 characters, including letters, numbers, and some symbols.
The first character in a variable name must be a letter.
Each variable name must be unique. Even if the variables are different types, their names cannot be identical.
Do not use all uppercase letters in your variable names. Because HotDocs instruction and expression keywords
use uppercase letters, you may inadvertently use a word that may someday be used as a keyword, which will cause
HotDocs to read your variable name incorrectly. (See Overview: Instruction and Expression Models.)
Do not use any of the following characters when naming your components:
. (period)
$ (dollar sign)
" (quotation mark)
: (colon)
[ ] (brackets)
, (comma)
( ) (parenthesis)
% (percent)
These characters can be used only if there is a character other than a space immediately before or after it:
+ (plus)
- (hyphen)
* (asterisk)
/ (forward slash)
> < (greater than and less than signs)
>= <= (greater than or equal to and less than or equal to signs)
= (equals)
!= (does not equal)

Copyright 2010 HotDocs Ltd. All rights reserved

886

Help Topics for HotDocs Developer 10

Reducing Template File Size

Problem
I completed automation on my template and now the template's file size is several megabytes. What can I do to reduce
the file size?

Solution
Most likely the increased file size is because you've used graphics in your template. When you insert a graphic in an RTF
template, Word creates an extra copy of the graphic and merges it in the file. Other causes may be invisible merge ID
marks and unused property codes.
You can keep Word from storing all of this information in the template. See Hidden Data Remover Dialog Box for details.
You can also remove existing hidden data from your templates. For details, see Remove Hidden Data from Word RTF
Templates.

Copyright 2010 HotDocs Ltd. All rights reserved

887

Help Topics for HotDocs Developer 10

Renaming Components Correctly

Problem
I renamed a component in my component file, but now my template won't assemble. I keep getting 'unrecognized variable'
errors.

Solution
When you rename a component, it is changed everywhere it is used in the component file. For example, renaming a
variable will update all references to it in dialogs, scripts, and prompts. However, you must update references to the
component in the template text itself for the template to continue to work. To do this, you may need to remove the old
variable field and insert the new variable. See Rename Components in a Single Template for details.
You can use Template Manager to rename components. If you do, all references to the componentboth in the
component file and in the templatewill be updated. See Rename Components Across Multiple Component Files for
details.

Copyright 2010 HotDocs Ltd. All rights reserved

888

Help Topics for HotDocs Developer 10

Repeating the Contents of a Single Cell in a Table

Problem
I have a table. I need to repeat the contents of a single cell. I've added a REPEAT instruction to that cell, but when I
assemble the document, it creates new rows for each repetition. How can I create the list in a single cell and not repeat
the entire table?

Solution
When you place a REPEAT instruction directly in a table, it will repeat each row of the table. To repeat the contents of a
single cell, you must create a REPEAT instruction in a computation script and then insert that Computation variable in the
cell. See Create a REPEAT Instruction Using a Computation Variable.

Copyright 2010 HotDocs Ltd. All rights reserved

889

Help Topics for HotDocs Developer 10

Repeating a Single Variable in a Dialog

Problem
I have a dialog that contains several related variables. I want to repeat one of the variables in the dialog but not all of
them. How do I do this?

Solution
To repeat a single variable in a dialog that contains other variables, you must effectively create two dialogs and then nest
the repeated variable's dialog in the non-repeated dialog. Specifically:

1. Create a dialog for all of the non-repeated variables. (See Gather Questions into a Custom Dialog.)
2. Create a dialog for the repeated variable and assign Spreadsheet on Parent as its repeat Style. (See Choose a
Presentation Style for the Repeated Dialog.)

3. Edit the non-repeated dialog and drag the repeated dialog to its Contents list.
See Insert Dialogs Into Dialogs and Create a List Within a List for more details.

Copyright 2010 HotDocs Ltd. All rights reserved

890

Help Topics for HotDocs Developer 10

Test Assembling Template with ASSEMBLE Instructions

Problem
When I try to test assemble my template, the ASSEMBLE instruction in the template doesn't work.

Solution
You cannot test an ASSEMBLE instruction from within the templateyou must first close the template and then assemble
it from the library. See ASSEMBLE "FILENAME" for details.

Copyright 2010 HotDocs Ltd. All rights reserved

891

Help Topics for HotDocs Developer 10

Trying to Save an Invalid Computation Script

Problem
When I try to save my Computation variable, I instead get an error message and HotDocs won't let me exit the script. I
need to work on other projects, but I don't want to cancel and lose all of my work on this script.

Solution
HotDocs will not let you save an invalid computation script. However, you can 'disable' the script and save the variable.
Disabling the script keeps HotDocs from trying to validate it when you save it.
There are two ways to disable a script:
Highlight all of the text in the script and click the
Comment Block button. This turns all of the text in the script
into a comment, which HotDocs won't process. When you are ready to work on the script again, highlight the text
and click the

Uncomment Block button. This enables the script once more.

Note:
Comments are descriptions or remarks about the computation script. Many developers enter comments to
explain how they are using instructions and expressions in the script to achieve the result they are seeking.
At the beginning of the script, enter the instruction QUIT. This instructs HotDocs to not process any of the script after
the instruction.

Copyright 2010 HotDocs Ltd. All rights reserved

892

Help Topics for HotDocs Developer 10

Understanding the Difference Between Multiple Choice Options and Merge Text
Problem
What is the difference between a Multiple Choice option and merge text?

Solution
There are actually three parts to a Multiple Choice variable:
Options: Multiple Choice options are the actual possible answers to the variable. When an option is selected, it is
the value that is saved in the answer file.
Prompts: Prompts are the text used to describe the options. For example, if your option text isn't descriptive
enough, you can enter a prompt for the option and the prompt will be used in the interview. (If you don't enter a
prompt, HotDocs will use the Option text.)
Merge Text: Merge text is the text that gets merged in the document, based on the options the user selects. (If you
don't enter Merge Text, HotDocs will merge the Option text in the document.)
See Customize a Multiple Choice Variable for details.

Copyright 2010 HotDocs Ltd. All rights reserved

893

Help Topics for HotDocs Developer 10

Using DEFAULT Instruction Causes Extra Repetition

Problem
I have a DEFAULT instruction in my repeated dialog script, but it's causing an unanswered repetition to appear in my
interview outline. This causes unanswered questions to appear in the document, as well. What do I do?

Solution
Do not use the DEFAULT instruction in the script of a repeated dialog unless the instruction is used in conjunction with
a conditional expression or a LIMIT instruction. If you use it by itself in a repeated dialog script, it will always add an
unanswered dialog to the interview, which will produce an incorrectly assembled document.
See DEFAULT VAR TO VALUE for details.

Copyright 2010 HotDocs Ltd. All rights reserved

894

Help Topics for HotDocs Developer 10

Using Headers and Footers of Inserted Templates

Problem
I have several inserted templates, each with their own defined headers and footers. However, when they are inserted in
the parent template, the headers and footers are lost. How can I keep the headers and footers from being overwritten?

Solution
When working with inserted templates, you can select an option that uses the headers and footers of the inserted
template when the template is merged in the main document. If the text is merged "inline" with the rest of the main
document, the inserted template's headers will overwrite the main document's headers. If the inserted template is merged
as a separate section of the main document, each section will use the headers defined for it. See Define Headers and
Footers in Inserted Word Templates for details.

Copyright 2010 HotDocs Ltd. All rights reserved

895

Help Topics for HotDocs Developer 10

Using INSERT Instructions in a Table

Problem
I've placed an INSERT instruction in a word processor table, but when I assemble the document, the inserted text appears
outside the table.

Solution
You cannot place INSERT instructions in the cell of a word processor table.

Copyright 2010 HotDocs Ltd. All rights reserved

896

Help Topics for HotDocs Developer 10

Using One Variable in Two Different Dialogs

Problem
I have a template where I need to ask one of two dialogs, based on how users answer other questions in the interview.
I have one variable that needs to appear in both dialogs. How can I link the variable to both dialogs without breaking my
template?

Solution
As long as only one dialog gets asked during the interview, you can associate the variable with both dialogs. To do this,
however, you will need to select some dialog options. You will also need to explicitly (but conditionally) ask both dialogs.
To associate the variable with both dialogs

1. Create the first dialog and add the required variables to it, including the variable you need to share between the two
dialogs.

2. At the Dialog Editor, click the Options tab.

3. Clear Link variables to this dialog and click OK.
4. Create the second dialog and add the required variables to it, including the variable you've already added to the first
dialog.

5. Either in a Computation variable or directly in the template, insert two ASK instructionsone for each dialog.
6. Condition the ASK instructions accordingly.
See Use the Same Variable or Clause in Two or More Dialogs for more information.

Copyright 2010 HotDocs Ltd. All rights reserved

897

Help Topics for HotDocs Developer 10

Variables Not Working in Word Text Boxes

Problem
I have a text box with a variable inside of it in my Word template. However, when I assemble the document, the variable
isn't processed.

Solution
You cannot insert variables inside Word text boxes. Alternatives to using text boxes may include creating a single table
cell to place your variable, or implementing a frame (Word XP). Refer to Microsoft Word's help file for specifics on creating
these types of boxes.

Copyright 2010 HotDocs Ltd. All rights reserved

898

Help Topics for HotDocs Developer 10

Chapter 58: Document Assembly

Can't Attach Answer File or Document to Outlook 2007 E-mail Message
Problem
When I try to attach an answer file or an assembled document file to an e-mail message, HotDocs displays the following
error message: "Error Sending Message. One or more unspecified errors occurred." I am using Outlook 2007.

Solution
This is an Outlook 2007 problem. It sometimes occurs when the Outlook 2007 forms cache becomes corrupt. To correct it
(at least temporarily), follow these steps:

1. In Outlook, choose Tools > Forms > Choose Form. The Choose Form dialog box appears.
2. Click the Look In drop-down button and choose Standard Forms Library.
3. Select one of the forms and open it.
4. Close the form. (You don't need to make any changes.)
Note:
You may need to restart HotDocs for this to work.

Copyright 2010 HotDocs Ltd. All rights reserved

899

Help Topics for HotDocs Developer 10

Changing Unanswered Text Markers

Problem
When I leave questions in the interview unanswered, HotDocs merges asterisks in the assembled document where the
answer is supposed to go. I'd rather have it insert blank lines or something else less obtrusive. Can I change this?

Solution
You can choose the unanswered marker HotDocs uses when you leave questions unanswered in the interview. For
details, see Format Unanswered Variables in a Document.
Note:
The template provider may have selected a specific unanswered marker for some questions in the interview. If this is
the case, these markers will override your selection.

Copyright 2010 HotDocs Ltd. All rights reserved

900

Help Topics for HotDocs Developer 10

Discerning Between Template Preview and Actual Template

Problem
When I preview the template at the Preview tab of the library or at the Document Preview tab of the assembly window,
the preview looks different from the actual template or assembled document when I view it in the word processor. Why
this difference in appearance?

Solution
Because of technical restrictions, HotDocs cannot display the actual word processor document in the library or at the
assembly window. Instead, it uses a third-party application to render the text of the template or document.
This application depicts a Microsoft Word template or document fairly accurately because it is able to convert the text
to RTF (if it's not already in RTF format). Some of the formatting may be different, but, for the most part, it is a good
representation. However, because WordPerfect text can't be converted to RTF at the time the document is displayed, the
application is only able to display the text in plain formatthere is no formatting.
In either case, however, the actual text in the template or document is correct. And, once you edit the template in the
correct word processor or send the assembled document to the word processor, the document will appear exactly as it's
supposed to.

Copyright 2010 HotDocs Ltd. All rights reserved

901

Help Topics for HotDocs Developer 10

Downloading HDIs and HDAs as ZIP Files

Problem
When downloading HotDocs auto-install (.HDI) or auto-assemble files (.HDA) from a server, files are saved to disk in ZIP
format. Additionally, attempting to open or run the file results in HotDocs prompting the user for a ZIP file password.

Solution
The first possible (and less likely) problem is that HDI file associations are not set up properly on the workstation. To test
whether this is true, create an HDI file, close HotDocs, and then double-click the .HDI file in Windows Explorer. If HotDocs
starts and then launches the installation, HDI files are properly associated. If HotDocs does not launch, the following are
two solutions that should correct the problem.
Solution 1: See Receiving Error Messages When Launching HDAs, HDIs.
Solution 2: Repair your installation of HotDocs. To do this, go to Start > Settings > Control Panel > Add or
Remove Programs. Select your version of HotDocs in the list of programs and click Change/Remove. When
prompted to either repair or uninstall HotDocs, choose Repair and complete the installation.
The second possible (and more likely) problem occurs because Windows XP examines files being downloaded. If they
appear to be in the ZIP format (which both HDI and HDA files are), then regardless of the download extension, Windows
concludes they are ZIP files and applies a .ZIP file name extension. Even though you have a proper MIME type set up on
your computer, Windows XP makes the change during the download.
To set the correct MIME types on the server

1. Bring up the IIS management tool (i.e. go to Start > Programs > Administrative Tools > Internet Services
Manager).

2. Choose the Web site whose MIME types you need to change.
3. Right-click and choose Properties from the shortcut menu.
4. Click the HTTP Headers tab.
5. Click the File Types button.
6. Click the New Type button. (You will do this for both HDIs and HDAs.)
7. Enter the following information for each file type:
Type of File

MIME Type

Auto-install (HDI)

application/x-hotdocs

Auto-assemble (HDA)

application/x-hotdocs-auto

Copyright 2010 HotDocs Ltd. All rights reserved

902

Help Topics for HotDocs Developer 10

Editing Answers in Assembled Document

Problem
When viewing the assembled document, I can't edit the answers that are merged in the document. The help file says I
should be able to.

Solution
You may not be able to edit answers at the Document Preview tab for one of three reasons:
You are viewing a WordPerfect document. (Answer editing is not supported in WordPerfect templates and
documents.)
The template developer has not allowed it.
The Highlight Fields option is turned off. To highlight fields again, click the
assembly window toolbar.

Copyright 2010 HotDocs Ltd. All rights reserved

Highlight Fields button in the

903

Help Topics for HotDocs Developer 10

Entering a Two-Digit Year

Problem
I want to enter a two-digit year whenever I answer a date question, but HotDocs always displays the following error
message: "You must enter a four-digit year".

Solution
As a safety precaution, HotDocs requires you to enter four digits when entering the year portion of a date. If you enter a
two-digit date, such as 7/9/99, HotDocs responds with this message: "You must enter a four-digit year."
You can override this default option by specifying a century rollover year at the HotDocs Options dialog box. The number
you enter controls how HotDocs interprets two-digit years. Two-digit years less than or equal to the number you enter are
understood as 2000-century years. Two-digit years greater than the number you enter are understood as 1900-century
years.
For example, if you specify a rollover value of 34, dates entered as 5/14/34 will appear as 14 May 2034. A date entered as
5/14/35 will appear as 14 May 1935.
Note:
See Control How HotDocs Handles Two-Digit and Four-Digit Years for information on setting this option.

Copyright 2010 HotDocs Ltd. All rights reserved

904

Help Topics for HotDocs Developer 10

HotDocs Skips Questions When Navigating from Child Dialog

Problem
After I answer questions in a child (or nested) dialog, I click Next and HotDocs takes me to the next dialog in the
interviewnot back to the main-level dialog I was in originally. How can I keep this from happening?

Solution
HotDocs moves to the next dialog in the interview outline because of a default setting. Its behavior is most useful when
child dialogs appear as the last item in a dialog, and, after answering questions in the child dialog, you want to move
to the next dialog in the interview. However, there are times when you need to return to the parent dialog and continue
answering questions in the current dialog.
If, instead, you want to return to the main-level dialog that uses the child, you can clear this default setting. At the
assembly window, clear Next Dialog Follows Outline (Navigate menu).

Copyright 2010 HotDocs Ltd. All rights reserved

905

Help Topics for HotDocs Developer 10

Increasing Font Size

Problem
When answering questions in the interview, the text used in the dialogs is too small or too hard to read. Can I change it?

Solution
You can change the font, size, and color of the text used in a dialog. You can also change the properties of text used in
the interview outline. For details, see Customize the Look of the Dialog Pane.

Copyright 2010 HotDocs Ltd. All rights reserved

906

Help Topics for HotDocs Developer 10

Installing Support for New Word Processor

Problem
I've installed a new word processor, but when I try to use HotDocs with it, HotDocs won't recognize it.

Solution
After you have installed the new word processor, you must run the word processor at least once. This creates entries in
the Windows System Registry, which HotDocs must be able to access before it can integrate with it.
Once the registry is updated with the required information, you must select the new word processor at HotDocs Options
and choose to install support for it. For details, see Install Support for New Word Processors.
It is possible your new word processor isn't compatible with HotDocs. If you are unsure, please see the list of HotDocs
System Requirements (see System Requirements.)

Copyright 2010 HotDocs Ltd. All rights reserved

907

Help Topics for HotDocs Developer 10

Moving Between Questions in Interview Slow

Problem
Whenever I answer a question in an interview and try to move to the next question, it seems like it takes HotDocs a long
time to respond. Moving between dialogs in the interview also seems slow. What can I do to make this process faster?

Solution
In an effort to keep the assembly process up to date, HotDocs updates the dialog and the interview outline each time you
enter or edit an answer in the interview. Depending on the complexity of the interview or the document, this updating may
take longer than desired.
You can minimize the amount of time HotDocs takes to update the interview or document with your changes by forcing
it to update only when it needs to. You do this by turning
Instant Update off. When instant update is off, HotDocs
updates dialogs and interviews only when it needs to. For details, see Update Your Interview Outline and Document.
Note:
Template Developers: You can create a custom interview component that can greatly reduce the amount of
processing required to keep the interview up to date. This can improve response time for your users. For details, see
Define a Custom Interview.

Copyright 2010 HotDocs Ltd. All rights reserved

908

Help Topics for HotDocs Developer 10

Moving to the Next Dialog After Entering a Date or Number

Problem
When I answer a date or number question in an interview and then click
me to the next dialog. I have to click

Next or

Next or

Previous, HotDocs doesn't move

Previous again to move to that dialog.

Solution
When you type an answer in an answer field, HotDocs sometimes reads the answer and reformats it to appear a certain
way. For example, if you type February 6, 2006 in a date field, HotDocs will reformat the answer to appear as 6 Feb
2006. Sometimes this reformatting can reveal an incorrectly interpreted answer, especially if the answer you typed is
ambiguous. For example, the date 05/06/2006 may either be interpreted as June 5, 2006 or as May 6, 2006.
Depending on where the reformatted answer appears in the dialog, you may not even be aware that it has been
reformatted. For example, when you enter an answer in one of the first answer fields in a dialog and then move to the next
field, you will most likely see that your answer has been reformatted. However, if you enter an answer in the last answer
field and click

Next to advance to the next dialog, you may not see that the answer was reformatted.

In this situation, HotDocs keeps you in the dialog so you can review the change it has made to the format. For information
on changing this default behavior, see Warn When HotDocs Reformats Date and Number Answers.

Copyright 2010 HotDocs Ltd. All rights reserved

909

Help Topics for HotDocs Developer 10

Organizing Files in the Library vs. on the Disk

Problem
I don't understand the difference between how files are organized in my library and how they are organized on disk.

Solution
A HotDocs library is simply a tool for viewing and working with the files on the disk. Specifically:
Files in the library are shortcuts that link to the actual files on disk (much like a desktop shortcut to an application you
use frequently links to a program in your Program Files folder).
Files in the library can be organized into "virtual" folders. These folders do not need to match the organization of
folders on the desktop.
Files in the library can be viewed using either the template title or the template file name. Files on disk are viewed
only by file name.
If you manually move a file on disk, you must update the reference to the file in the library or HotDocs will not know
how to find the file. To move files while keeping the reference to the file updated in the library, use the Move or
Copy commands in the library.

Copyright 2010 HotDocs Ltd. All rights reserved

910

Help Topics for HotDocs Developer 10

Overriding an Answer in a Form

Problem
What happens when I override an answer in a form document?

Solution
Sometimes you need to enter an answer in a form document, but you are unable to enter that answer because of
formatting restrictions on that field. (Remember, dates and numbers must be formatted a certain way for HotDocs to
consider them valid.) For example, say you enter 3,000,000 as an answer to a number variable. The field, however, may
not be large enough to show the whole answer without sending it to the addendum. You can override the field's format
and enter 3 mill. as the answer.
Or perhaps you have a date that is appearing in one format (19 May 2006), but you want it to appear in a different format
(06/19/06). You can override the field and enter the answer you need.
Overriding the format of the field allows you to enter whatever text you need in the answer field.
See Override an Answer in a Form for details on overriding form fields.
Note:
Overriding a field is like placing a sticky note over the field and writing on ityou can see what is written on the note,
but HotDocs continues to use the original answer. Any other fields that use the answer, either in a calculation or a
condition, will continue to do so. The original answer will likewise be saved in the answer file.

Copyright 2010 HotDocs Ltd. All rights reserved

911

Help Topics for HotDocs Developer 10

Printing Form Document Takes Incredibly Long Time

Problem
When printing a PDF-based form document, it takes an incredibly long time for the document to actually print. What can I
do to speed up this process?

Solution
This slowness happens when you print the document through HotDocs. To print more quickly, use Adobe Acrobat or
Reader to print the document. See Print an Assembled Form Document for details on selecting this preference.

Copyright 2010 HotDocs Ltd. All rights reserved

912

Help Topics for HotDocs Developer 10

Printing Form Document is Off-Center

Problem
When I print my PDF-based form, the document appears off-center on the printed page.

Solution
This problem appears when you use Adobe Acrobat to print the document and you're using a non-PostScript printer
driver.
To correct the problem, always use a PostScript printer driver.
See Print an Assembled Form Document for more details.

Copyright 2010 HotDocs Ltd. All rights reserved

913

Help Topics for HotDocs Developer 10

Receiving Error Messages When Launching HDAs, HDIs

Problem
When attempting to run either a HotDocs Auto-Install file (HDI) or HotDocs Auto-Assemble file (HDA), HotDocs displays
an error message and is unable to launch the file. The error message frequently says it cannot find hd_dispatch.exe, the
application used to launch these files.

Solution
During installation, HotDocs creates certain entries in the Windows System Registry. One of these entries designates
where the file hd_dispatch.exe should be found so that HDAs and HDIs can be properly run. By default, this file is usually
created and registered in C:\Program Files\HotDocs. However, if you performed a custom installation and changed the
program folder for HotDocs to some location other than C:\Program Files\HotDocs, this registry key was not updated with
the new program files path. Because of this, HotDocs cannot run the HDA or HDI because it doesn't know where to look
for hd_dispatch.exe.
To update the registry with the correct information
Caution:
This workaround requires you to work in the Windows System Registry. Failure to follow these instructions carefully
and entirely may result in you changing a setting that may adversely affect several other programs you use. If you are
unsure of how to work with the registry, please ask your system administrator for assistance.

1. Click Start > Run. The Run dialog box appears.

2. In the Open box, type regedit. The Registry Editor appears.
3. Open HKEY_CLASSES_ROOT > HotDocsHdaFile. (To update the information for an HDI file, navigate to
HKEY_CLASSES_ROOT > HotDocsHdiFile.)

4. Expand the folder so you can see its subfolders.

5. Click the DefaultIcon folder.
6. In the right pane, double-click (Default). The Edit String dialog box appears.
7. Change the folder path in the Value data box so that it matches the folder where HotDocs is installed. Do not
remove the ,1.

8. Click OK.
9. In the same subfolder (in the right pane), expand Shell > open > command.
10. Repeat steps 6 through 8, updating the folder path so that it matches the folder where HotDocs is installed. Again,
do not change the information after the file path.

11. Remember to update the file locations for both HDAs and HDIs. See step 3 in the list above.

Copyright 2010 HotDocs Ltd. All rights reserved

914

Help Topics for HotDocs Developer 10

Restoring System Defaults to HotDocs

Problem
I've altered several default settings for HotDocs, but now I want to restore the default settings I had when I installed
HotDocs. How can I do this?

Solution
HotDocs uses the Windows System Registry to store your personal preferences for working with HotDocs. If you need to
restore the installation defaults, you must clear the Current User section of the HotDocs portion of the System Registry.
Caution:
You must be extremely careful when working in the System Registry. Failure to follow the instructions below exactly
could result in your making changes that negatively affect all of the programs on your computer. You may want to ask
your system administrator for help if you are unsure of what you are doing.
Note:
To understand HotDocs installation and the changes that are made to the registry, please see Understand HotDocs
Installation.

1. At the Start menu, select Run. The Run dialog box appears.
2. In the Open box, type regedit and click OK. The Registry Editor appears.
3. Navigate to HKEY_CURRENT_USER > Software > HotDocs > HotDocs.
4. Select the HotDocs subfolder and press Delete. Click Yes to confirm the deletion.
5. Check for the registry key HKEY_CURRENT_USER > Software > LexisNexis > HotDocs 6. If it exists, proceed to
Step 6. Otherwise, proceed to Step 7.

6. Select the HotDocs 6 subfolder and press Delete. Click Yes to confirm the deletion.
7. Close the Registry Editor.

Copyright 2010 HotDocs Ltd. All rights reserved

915

Help Topics for HotDocs Developer 10

Saving Answers During Interview

Problem
HotDocs won't let me save answers during an interview. The buttons and menu options for doing so are disabled.

Solution
If the buttons and menu options for saving an answer file are disabled, it is because the template provider has either
prohibited you from saving the answer file, or because the answer file is being saved automatically. If you have specific
questions, please contact the template provider.

Copyright 2010 HotDocs Ltd. All rights reserved

916

Help Topics for HotDocs Developer 10

Specifying Printing Options When Printing Text Documents

Problem
When I print my assembled text document from the assembly window, HotDocs just automatically prints the document
without prompting me for any of my preferences. (I don't get a Print or Print Options dialog box.) How do I first set my
preferences before printing?

Solution
To set your preferences before you print the document, you must first send the document to the word processor. Once in
the word processor, choose the Print command and then specify your settings.

Copyright 2010 HotDocs Ltd. All rights reserved

917

Help Topics for HotDocs Developer 10

Understanding What Happens When Deleting Templates from the Library

Problem
What happens when you delete templates from a library?

Solution
When you select a template or folder in a HotDocs library and click the
Remove Items button, HotDocs asks if you
want to remove just the reference to the file from the library or if you want to delete the actual files from disk, too.
If you remove just the reference from the library, that specific reference to the file is removed from the library but the
actual file still exists on disk. Additionally, if the item is referenced any other place in the library or in a different library,
those references still exist.
If you choose to delete the item from disk, the reference is removed from the library and the file is sent to the Recycle Bin
(if working with files on your local drive) or permanently deleted (if you're working with files on a network drive).
When you remove a folder from the library, you can choose to delete just the folder (in which case, items in the folder
are moved to the next highest folder), or you can choose to delete the folder along with all of the items referenced in the
folder.
For details, see Remove Items from a Library.

Copyright 2010 HotDocs Ltd. All rights reserved

918

Help Topics for HotDocs Developer 10

Updating Changes Made in Word Processor Document in the Answer File,

Template
Problem
I've edited text in my assembled document but neither the template nor the answer file shows these changes. How do I
update these files with my changes?

Solution
Once you send an assembled document to the word processor, it becomes "disconnected" from HotDocs. If you make
changes to the document, those changes will not be represented in either the template or the answer file.
To update the template with your changes, you must edit the template and make the changes there. If you do not have
editing privileges, you should notify the template publisher of your recommended changes.
If you need to update answers, you must reassemble the document using the saved answer file and make your changes
during the interview. Make sure you save the answer file when you are finished.

Copyright 2010 HotDocs Ltd. All rights reserved

919

Help Topics for HotDocs Developer 10

Updating Cross-References in an Assembled Document

Problem
I've assembled a document and sent it to Microsoft Word, but now the Table of Contents is outdated. How do I update
these cross-references?

Solution
To update cross-references in an assembled Word document

1. Highlight all of the text in the document (press Ctrl+A or choose Select All (Edit menu)).
2. Press the F9 key.
3. Select your update options and click OK. Cross-references in the document are updated.
Note:
Template Developers: You can select a component file property that automatically updates references in the
document once the document is sent to the word processor. See Change Component File Properties for details.

Copyright 2010 HotDocs Ltd. All rights reserved

920

Help Topics for HotDocs Developer 10

Viewing File Names Instead of Template Titles at Library

Problem
I'm looking for a specific template in my library. I know what its file name is, but am not sure how to find it based on its
title. Is there some way to display templates by their file names in the item list?

Solution
To view items in the library by file name, choose File Names (View menu). To show template titles again, choose
Template Titles.
You can search a list of library items for a specific template by using the Find command. Simply select Find and then
enter the text for which you are searching in the box. HotDocs will search both template titles and file names for the text
you enter. Any files that contain that specific text will be displayed in the list.

Copyright 2010 HotDocs Ltd. All rights reserved

921

Help Topics for HotDocs Developer 10

Chapter 59: HotDocs Automator

Double-Clicking Doesn't Create Field as Expected
Problem
I double-clicked to create a form field, but HotDocs didn't create the field as I expected it would.

Solution
Several factors may contribute to these difficulties:
Insufficient surrounding features: To detect a field, HotDocs searches for surrounding features, such as lines,
text, or graphics. If there are insufficient surrounding features, HotDocs may have difficulty detecting a field. In such
cases, HotDocs creates a field of the default size.
Label text: When label text is inside the field area and there is enough space between the text and the bottom of the
field area, the Detect command will extend the field up to the bottom of the label text. If you want the field to occupy
the area to the left or right of the label, or if you want to include the label inside the field, you must create the field
manually.
Field not completely visible: If part of the intended field is not visible (for example, it's scrolled out of the window),
HotDocs attempts to scroll to detect the field. It is recommended that you use a zoom level such as Fit Page to
Width so HotDocs can find the entire field on the screen.
If HotDocs is unable to automatically create or resize a field to the size and position you want, you must create the field
manually. See Create a Form Field for details.

Copyright 2010 HotDocs Ltd. All rights reserved

922

Help Topics for HotDocs Developer 10

Fixing Page Rotation Problems in PDF Templates

Problem
Pages that are rotated in a PDF document aren't rotated when I convert the PDF to template format.

Solution
Starting with the release of HotDocs 2006, page rotation is honored when creating a new template. However, you may
need to update existing forms where page rotation is not honored.
To fix page rotation problems in existing PDF templates

1. Make a back-up copy of the form.

2. Edit the original form.
3. Delete all of the fields on the original form.
4. Save and close the form.
5. Reopen the original form. The rotated pages should appear correctly.
6. Open the back-up copy of the form and copy the fields for the non-rotated pages.
7. Create new fields for the rotated page.
8. Optionally, copy any printing or addendum properties from the back-up form.

Copyright 2010 HotDocs Ltd. All rights reserved

923

Help Topics for HotDocs Developer 10

Getting Errors When Automating Table in Form

Problem
When I try to group my fields in a table, I get errors that say things like Row 2 has 1 columns when it should have 3
columns. What am I doing wrong?

Solution
HotDocs expects fields in a table to appear in standard rows and columns that read from top to bottom and from left to
right. When fields in a table are laid out differently, you must first define the rows and columns by specifying the field order
before you try to group the fields as a table. For complete instructions on doing this, please see Merge a List of Answers
in a Standard Table and Merge a List of Answers in a Nonstandard Table.

Copyright 2010 HotDocs Ltd. All rights reserved

924

Help Topics for HotDocs Developer 10

Keeping Control Field Text From Appearing on Form

Problem
I have a control field on my form template which runs a computation. When I assemble the document, the text that
results from the computation script appears in the fieldand I don't want it to. (For example, I want the result to go to the
addendum.) How can I keep this text from appearing directly on the form?

Solution
You can keep text from being merged in a control field. To do this, you will increase the field border so that text that
doesn't fit in the field will be sent to the addendum.
To keep text from appearing

1. Select the field and click the

Field Properties button. The Field Properties dialog box appears.

2. Click the Layout tab. The view changes to show options for field placement and appearance.
3. In the Borders group, enter 1 in the Left border box.
4. The underlying form field should turn a dark shade of green. If it does not, increase the field border until it does.
Note:
See Change the Borders and Margins of a Field for complete instructions.

Copyright 2010 HotDocs Ltd. All rights reserved

925

Help Topics for HotDocs Developer 10

Modifying a Single Field in a Group

Problem
I want to change the properties of a single field in a group, but I can't seem to select the field. How do I get to the field so I
can edit it?

Solution
You must first ungroup the fields and then make the changes to the field. When you are finished, regroup the fields. See
Group Form Fields So Answers Can Flow From One Field to Another and Ungroup Form Fields.
Caution:
Properties for field and table groupings are stored with the first field in the group. If you delete the first field in the
group, you will lose these grouping properties.

Copyright 2010 HotDocs Ltd. All rights reserved

926

Help Topics for HotDocs Developer 10

Moving Form Fields Using Keyboard Takes Too Long

Problem
When working with fields in a form, I use keys on the keyboard to move them because I like the precision it affords me.
However, this process, at times, takes too long. Is there some faster way to move fields using the keyboard?

Solution
To use the keyboard to move fields on the form, you can use the arrow keys. This moves the field pixel by pixel, which is
useful when you want precise placement. To move the fields more quickly, press Shift as you press the arrow keys. See
Move a Field on a Form for details.

Copyright 2010 HotDocs Ltd. All rights reserved

927

Help Topics for HotDocs Developer 10

Needing Characters in Answer to Appear in Individual Boxes

Problem
I have a form that requires a date be split into separate boxeseach number appearing in its own box. However, when
I try to do this, all of the characters end up in the first few boxes of the form or the field overflows. How can I accomplish
this?

Solution
To do this, you must group the fields and then assign a maximum number of lines and characters to the fields in the
group. You may also need to assign an example format to the field. For complete instructions, see Attach a Variable to
Single-Character Boxes.

Copyright 2010 HotDocs Ltd. All rights reserved

928

Help Topics for HotDocs Developer 10

No Interview When Assembling Form Document

Problem
I finished automating my form template and when I test assemble it, there isn't an interview. Instead, HotDocs just shows
the Form Document tab and I have to type my answers directly in the fields. How do I get an interview for the template?

Solution
When users assemble form documents, they can provide the information in one of two ways: answering questions in an
interview or typing answers directly on the document (which is called direct-fill assembly).
All forms, when first automated, are set to allow only direct-fill assembly. However, you can allow interview-based
assembly by specifying an interview. The interview can be a default interview (one in which HotDocs determines the
order dialogs are asked in the template) or it can be a custom interview (one in which you specify the order dialogs and
variables are asked). Either way, you can designate which type of interview you want to use. For details, see Define the
Interview for a Form Template.
Note:
If you want all new templates you create to use a default interview, you can specify a HotDocs option. See
Automatically Generate Default Interviews for Form Templates for details.

Copyright 2010 HotDocs Ltd. All rights reserved

929

Help Topics for HotDocs Developer 10

Setting Form Properties Not Taking Effect in Existing Templates

Problem
At HotDocs Options, I've assigned several properties for how I want my form templates to look and work, but none of
these settings are working in the templates I've created. How come?

Solution
Many of the properties you specify in the Form Documents section of HotDocs Options only affect new templates or
fields you create. To update existing templates and fields you've already created with the settings, you must manually
specify the properties while working in the template or working with the fields.

Copyright 2010 HotDocs Ltd. All rights reserved

930

Help Topics for HotDocs Developer 10

Tabbing Through Fields Sequentially in Form

Problem
When I tab through questions at the Form Document tab during a test assembly, I can't tab through the fields
sequentially. Instead, HotDocs moves somewhat randomly between the fields. Is there some way I can correct this tab
order?

Solution
When determining the order to ask questions in the interview, HotDocs begins with the top-left field of the form and
processes all of the fields until it reaches the bottom-right field. This processing affects two thingsthe order questions
are asked in the default interview and the order in which the user is able to tab through fields on the form.
Because of this default field ordering, sometimes you may find that the tab order during direct-fill assembly isn't working
as you expect. To correct the problem, you must manually assign a tab order to the fields on the form. You do this at the
Additional tab of the Field Properties dialog box. Specifically, you assign rows and/or column numbers to fields on the
form. For complete details on assigning a tab order, see Change the Tab Order of Fields.

Copyright 2010 HotDocs Ltd. All rights reserved

931

Help Topics for HotDocs Developer 10

Want Check Box to Use Actual Check Mark

Problem
I want to use an actual check mark in a form check boxnot the default X character. How do I do this?

Solution
If you have symbolic fonts installed on your computer, you can 1) assign the font to the field, and 2) assign the special
character to the True/False variable format.
The following steps provide an example using the Symbol font.
To merge a check mark in a check box

1. On the form template, create a check box field. (See Create a Check-Box Field.)
2. Attach a True/False variable to the field. (See Customize a True/False Variable.)
3. Enter the following text in the Default format box: / . (The capital O with an umlaut can be entered by pressing Alt
+0214. This character represents the check mark character in the Symbol font. You may need to enter the character
in a separate text editor and then copy and paste it into the Format box.)

4. Select the field and click the

Field Properties button. The Field Properties dialog box appears.

5. Change the font to Symbol. (See Change the Font Used for a Field.)
When the template is assembled, HotDocs uses the check mark (#) instead of the X.

Copyright 2010 HotDocs Ltd. All rights reserved

932

Help Topics for HotDocs Developer 10

SECTION 12:
LEGAL NOTICES

Copyright 2010 HotDocs Ltd. All rights reserved

933

Help Topics for HotDocs Developer 10

Chapter 60: Legal Notices

Copyright Information
Copyright
Copyright 2010 HotDocs Limited.
All rights reserved. No part of this product may be reproduced, transmitted, transcribed, stored in a retrieval system,
or translated into any language in any form by any means without the express written permission of HotDocs Limited.
("HotDocs").

Warranty Information
HotDocs makes no representations or warranties with respect to the contents or use of this product and specifically
disclaims any express or implied warranties of merchantability or fitness for any particular purpose. Information in this
document is subject to change without notice and does not represent a commitment on the part of HotDocs.

Government Use
Use, duplication, or disclosure by the Federal Government is subject to restrictions as set forth in FAR clauses
52.227--14, Rights in Data--General; 52.227--19, Commercial Computer Software--Restricted Rights; and subdivision
(c)(1)(ii) of the Rights in Technical Data and Computer Software clause DFAR 252.227--7013; and the limitations set forth
in the standard commercial license agreement for this software. Unpublished rights are reserved under the copyright laws
of the United States.

Trademark Information
HotDocs is a registered trademark of HotDocs Limited. Other product names may be trademarks or registered trademarks
of their respective companies.

Sample Templates and Forms

This product includes sample templates and documents. Using them may have significant legal implications in some
situations, and these implications vary by state and depending on the subject matter. Before using these templates and
documents or adapting them for your business, you should consult with a lawyer and financial advisor.

Copyright 2010 HotDocs Ltd. All rights reserved

934

Help Topics for HotDocs Developer 10

Software Licence Agreement

IMPORTANT NOTICE: PLEASE READ CAREFULLY BEFORE INSTALLING THE SOFTWARE. This licence agreement
(Licence) is a legal agreement between you (an individual or a single entity) and the licensor (Licensor) of this
HotDocs software product, which includes computer software, the associated media, printed materials and electronic
documentation (Software). Written approval is not a prerequisite to the validity and enforceability of this License and no
solicitation of any such written approval by or on behalf of Licensor shall be construed as an inference to the contrary.
If you reside in the European Union: the Licensor is HotDocs Limited, a limited company registered in Scotland, UK, with
company number SC166375 and with its registered office at Edinburgh Quay, 133 Fountainbridge, Edinburgh, EH3 9AG.
This Licence, its subject matter or its formation (including non-contractual disputes or claims) shall be governed by and
construed in accordance with English law and submitted to the exclusive jurisdiction of the English courts.
If you reside outside the European Union: the Licensor is HotDocs Corporation, a corporation incorporated in Delaware,
USA, with its principal place of business at 387 South 520 West, Suite 210, Lindon, Utah 84042, USA. This Licence shall
be governed by and construed under the laws of the State of Utah and the United States without regard to conflicts of
laws provisions thereof. Unless otherwise elected by the Licensor in writing for the particular instance (which Licensor
may do at its option), the sole jurisdiction and venue for actions related to the subject matter hereof shall be the Utah
state and U.S. federal courts having within their jurisdiction the location of the Licensors principal place of business. Both
parties consent to the jurisdiction of such courts and agree that process may be served in the manner provided herein for
giving of notices or otherwise as allowed by Utah or federal law.
If you have a written agreement signed by the Licensor which relates to the supply of the Software and which expressly
states that its terms prevail over the terms of any 'click-wrap' or 'shrink-wrap' agreement packaged with the Software,
then the former agreement shall prevail over any inconsistent terms of this Licence. Otherwise, this Licence represents
the entire agreement between us in relation to the licensing of the Software and supersedes any prior agreement,
understanding or arrangement between us, whether oral or in writing.
THIS SOFTWARE REQUIRES A COMPUTER WITH SUFFICIENT MEMORY AND DISK SPACE, AND A COMPATIBLE
OPERATING SYSTEM. SOME FUNCTIONALITY MAY REQUIRE A SPECIFIC INTERNET BROWSER OR OTHER
SOFTWARE NOT INCLUDED WITH THIS SOFTWARE. BY CHOSING BELOW TO ACCEPT THE TERMS OF THIS
LICENCE AGREEMENT YOU AGREE TO THE TERMS OF THIS LICENCE WHICH WILL BIND YOU. IF YOU DO NOT
AGREE TO THE TERMS OF THIS LICENCE, WE ARE UNWILLING TO LICENSE THE SOFTWARE TO YOU AND
YOU MUST DISCONTINUE INSTALLATION OF THE SOFTWARE NOW BY CLICKING ON THE "I DO NOT ACCEPT"
BUTTON BELOW. IN THIS CASE YOU MUST RETURN THE MEDIA ON WHICH THE SOFTWARE IS STORED AND
ALL ACCOMPANYING DOCUMENTATION TO THE SUPPLIER, TOGETHER WITH PROOF OF PAYMENT WITHIN
14 DAYS OF PURCHASE FOR A REFUND. IF YOU PURCHASED THIS SOFTWARE FROM AN AUTHORISED
RESELLER, PLEASE NOTE THAT THE RESELLER HAS THE RIGHT TO ENTER INTO THIS LICENCE ON OUR
BEHALF.

1. In consideration of you agreeing to abide by the terms of this Licence and the payment of the licence fee (which is
part of the price for this package), the Licensor hereby grants to you a non-exclusive, non-transferable licence to use
the Software on a single computer or workstation. The Software may not be shared or used concurrently on other
computers. If any updates, maintenance releases or other modified versions of the Software are made available to
you they shall be deemed to be Software supplied under the terms of this Licence unless otherwise stated at the
time of supply.

2. You may make one copy of the Software for back-up purposes only. You may not transfer your rights to the back-up
copy unless you also transfer your rights to the Software.

3. Except as expressly set out in this Licence or as permitted by any local law, you shall not (and shall not allow a third
party to):
(a) copy the Software except where such copying is incidental to normal use of the Software or where it is necessary
for the purpose of back-up or operational security;
(b) rent, lease, sub-license, loan, translate, merge, adapt, vary or modify the Software;
Copyright 2010 HotDocs Ltd. All rights reserved

935

Help Topics for HotDocs Developer 10

(c) make alterations to, or modifications of, the whole or any part of the Software;
(d) disassemble, de-compile, reverse engineer or create derivative works based on the whole or any part of the
Software.

4. You acknowledge that all intellectual property rights in the Software throughout the world belong to HotDocs Limited,
that rights in the Software are licensed (not sold) to you, and that you have no rights in, or to, the Software other
than the right to use it in accordance with the terms of this Licence.

5. The Licensor warrants that the media on which the Software is stored and distributed are (at the time of supply),
and will be for the period of 90 days after that time (Warranty Period), free from defects in design, material and
workmanship under normal use. If a defect in the media occurs during the Warranty Period, the Licensor will replace
it free of charge if you return it to the Licensor with proof of purchase and (so far as you are able) a documented
example of such defect or error.

6. You acknowledge that the Software has not been developed to meet your individual requirements and that it is
therefore your responsibility to ensure that the facilities and functions of the Software meet your requirements.

7. You acknowledge that the Software may not be free of bugs or errors and you agree that the existence of any minor
errors shall not constitute a breach of this Licence.

8. If, within the Warranty Period, you notify the Licensor in writing of any defect in the Software in consequence of
which it fails to perform substantially in accordance with the electronic documentation, and such defect does not
result from you having amended the Software or used it in contravention of the terms of this Licence, the Licensor
will, at its sole option, (i) repair or replace the Software or (ii) accept a return of the Software (with proof of purchase)
and provide a refund of the purchase price, provided that you make available all information that may be necessary
to assist the Licensor in resolving the defect or fault, including sufficient information to enable the Licensor to
recreate the defect or fault.

9. Nothing in this Licence shall limit or exclude the liability of either party for death or personal injury resulting from
negligence, fraud, fraudulent misrepresentation, or for liability which cannot lawfully be excluded or limited.

10. SUBJECT TO CONDITION 9:

(a) THE LICENSOR SHALL NOT BE LIABLE FOR ANY LOSS OF PROFIT, LOSS OF BUSINESS, LOSS OF
GOODWILL, LOSS OF SAVINGS, LOSS OF DATA, LOSS OF ANTICIPATED SAVINGS, WHETHER DIRECT
OR INDIRECT IN EACH CASE, OR FOR ANY INDIRECT LOSS OR CONSEQUENTIAL LOSS WHATSOEVER
AND HOWSOEVER CAUSED (EVEN IF CAUSED BY THE LICENSORS NEGLIGENCE AND/OR BREACH OF
CONTRACT AND EVEN IF THE LICENSOR WAS ADVISED THAT SUCH LOSS WOULD PROBABLY RESULT);
(b) THE LICENSOR'S MAXIMUM AGGREGATE LIABILITY UNDER OR IN CONNECTION WITH THIS LICENCE,
OR ANY COLLATERAL CONTRACT, WHETHER IN CONTRACT, TORT (INCLUDING NEGLIGENCE)
OR OTHERWISE, SHALL BE LIMITED TO A SUM EQUAL TO THE ACTUAL PRICE YOU PAID FOR THE
SOFTWARE.

11. This Licence does not provide for maintenance or support for the Software, which must be purchased separately
if required. Licensor has no obligation to provide maintenance, support or updates, modifications or new releases
under this Licence.

12. This Licence sets out the full extent of the Licensor's obligations and liabilities in respect of the supply of the
Software. There are no conditions, warranties, representations or other terms, express or implied, that are binding
on the Licensor except as specifically stated in this Licence. Any condition, warranty, representation or other term
concerning the supply of the Software which might otherwise be implied into, or incorporated in, this Licence, or any
collateral contract, whether by statute, common law or otherwise, is hereby excluded to the fullest extent permitted
by law.

13. You may not transfer, assign, charge or otherwise dispose of this Licence, or any of your rights or obligations arising
under it, without our prior written consent.

14. Upon request from time to time, you agree to certify to the Licensor the number of copies of the Software installed on
your computers.

Copyright 2010 HotDocs Ltd. All rights reserved

936

Help Topics for HotDocs Developer 10

Third-Party Software Acknowledgements

Colosseum Builders, Inc.
This product uses the image library software created by Colosseum Builders, Inc., to load, decode, draw, and
print .BMP, .JPG, and .PNG files in form templates and documents.

Copyright 2010 HotDocs Ltd. All rights reserved

937