CDSA Developers Guide.pdf

7/22/2019 CDSA Developers Guide.pdf

1/74

Clinical Documentation Solution Accelerator

Developer's Guide

Thursday, 15 April 2010Version 1.0.0.0

Prepared by

Microsoft


2/74

Microsoft

The information contained in this document represents the current view of Microsoft Corporation on the issues discussed as of the date of publication.

Because Microsoft must respond to changing market conditions, it should not be interpreted to be a commitment on the part of Microsoft, and Microsoft

cannot guarantee the accuracy of any information presented after the date of publication.

MICROSOFT MAKES NO WARRANTIES, EXPRESS, IMPLIED OR STATUTORY, AS TO THE INFORMATION IN THIS DOCUMENT.

Complying with all applicable copyright laws is the responsibility of the user. Without limiting the rights under copyright, no part of this document may be

reproduced, stored in or introduced into a retrieval system, or transmitted in any form or by any means (electronic, mechanical, photocopying, recording, orotherwise), or for any purpose, without the express written permission of Microsoft Corporation.

Microsoft may have patents, patent applications, trademarks, copyrights, or other intellectual property rights covering subject matter in this document.

Except as expressly provided in any written license agreement from Microsoft, the furnishing of this document does not give you any license to these

patents, trademarks, copyrights, or other intellectual property.

The descriptions of other companies products in this document, if any, are provided only as a convenience to you. Any such references should not be

considered an endorsement or support by Microsoft. Microsoft cannot guarantee their accuracy, and the products may change over time. Also, the

descriptions are intended as brief highlights to aid understanding, rather than as thorough coverage. For authoritative descriptions of these products, please

consult their respective manufacturers.

2010 Microsoft Corporation. All rights reserved.

Microsoft and Windows are either registered trademarks or trademarks of Microsoft Corporation in the United States and/or other countries.

SNOMED CT is a registered trademark of the International Health Terminology Standards Development Organization.

The names of actual companies and products mentioned herein may be the trademarks of their respective owners.

Page ii

Clinical Documentation Solution Accelerator Developer's Guide

Prepared by Microsoft, Version 1.0.0.0

Last modified on 15 April 2010


3/74

Microsoft

Page iii




TABLE OF CONTENTS

1 Introduct ion .............................................................................................................................. 12 Overview of the CDSA Development Environment ................................................................. 3

2.1 System Prerequisites ........................................................................................................... 32.2 Assumed Skills and Knowledge ........................................................................................... 32.3 Building the CDSA Solution in Visual Studio......................................................................... 4

2.3.1 Visual Studio 2008.......................................................................................................... 42.3.2 Visual Studio 2010.......................................................................................................... 4

2.4 Debugging the CDSA Add-in using Visual Studio ................................................................. 42.4.1 Office Word 2007 ........................................................................................................... 42.4.2 Office Word 2010 ........................................................................................................... 5

2.5 Installing the CDSA Office Word Add-in ............................................................................... 52.6 The CDSA Source Folders ................................................................................................... 62.7 Accessing the CDSA Development Environment .................................................................. 6

3 Constructing a Template Using the Included Controls........................................................... 93.1 Introduction.......................................................................................................................... 93.2 Inserting and Formatting Office Word Tables ....................................................................... 93.3 Adding and Modifying the CDSA Controls .......................................................................... 103.4 Deleting Controls ............................................................................................................... 16

4 Creating a Simple Contro l ...................................................................................................... 174.1 Introduction........................................................................................................................ 174.2 Creating the Name Input Control ........................................................................................ 18

5 Customising the Layout of an Existi ng Control .................................................................... 215.1 Introduction........................................................................................................................ 215.2 Creating the Customised Single Concept List Control ........................................................ 21

6 Creating a WPF-Based Control .............................................................................................. 266.1 Introduction........................................................................................................................ 266.2 Creating the WPF-Based Control ....................................................................................... 28

7 Creating a WPF-Based List Control ....................................................................................... 397.1 Introduction........................................................................................................................ 397.2 Creating the WPF-Based List Control ................................................................................. 40

8 Creating an XML Mapp ing Class ............................................................................................ 558.1 Introduction........................................................................................................................ 558.2 Creating the New XML File ................................................................................................ 55


4/74

Microsoft

Page iv




8.3 Creating a Storage Class ................................................................................................... 588.4 Creating a Storage Template ............................................................................................. 588.5 Changing the Storage Class Reference ............................................................................. 618.6 Mapping Across All Items................................................................................................... 638.7 Running Custom Code ....................................................................................................... 658.8 Creating a Model ............................................................................................................... 66

9 Document Information............................................................................................................ 699.1 Terms and Abbreviations ................................................................................................... 699.2 Definitions .............................................................................Error! Bookmark not defined.9.3 Nomenclature .................................................................................................................... 69

9.3.1 Body Text ..................................................................................................................... 699.3.2 Cross References ......................................................................................................... 70

9.4 References ........................................................................................................................ 70


5/74

Microsoft

Page 1




1 INTRODUCTION

The Clinical Documentation Solution Accelerator (CDSA) for the MicrosoftOffice system enables

you to provide solutions for users whose task is to create clinically encoded documents. Users write

those documents based on the CDSA templates you have designed (for example, for a Discharge

Summary or a Referral) and edit them using MicrosoftOffice Word.

CDSA promotes the safety and consistency of clinical documentation by utilising Microsoft Health

Common User Interface (CUI) software toolkit controls. Those controls support the embedding of

structured, machine-readable clinical information in a human-readable Office Word document that

is shareable across care boundaries. The encoding of clinical information is to industry standard

formats (such as the Health Level 7 (HL7) Clinical Document Architecture (CDA)).

CDSA allows for the direct utilisation of external clinical data in a document (perhaps from a cloud

computing or WindowsAzure source). Example external data sources include Systematized

Nomenclature of Medicine Clinical Terms (SNOMED CT) encoding services or drug reference

data.

That combination of features provides the means of creating clinical documents that incorporatecomplex encoding but which are written using the familiar Office Word interface.

Figure 1 provides an example of what the user might see when editing a CDSA document (on the

left is the main document and on the right the summary of clinically-encoded terms from it):

Figure 1: Users View When Editing a CDSA-Enabled document

Such documents can act as significant building blocks within an overall healthcare environment.

For example, you can incorporate them as the foundation for clinical document workflows (perhaps

in combination with MicrosoftOffice SharePoint

Server 2010). To facilitate this, CDSA allows you

to:

Tailor documents to the specific Electronic Medical Record (EMR) or Electronic Health

Record (EHR) systems in your healthcare environment

Create clinical documents suitable for upload to a Personal Health Record (PHR) system

(such as MicrosoftHealthVault) or to other external storage

Easily share clinical documents, passing them across care boundaries whilst retaining the

clinically encoded data


6/74

Microsoft

Page 2




More specifically, the CDSA toolkit extends Office Word to provide the functionality indicated for the

following groups:

For Clinical Template Designers With the CDSA add-in enabled, a template designer

can create Office Word templates. In addition to providing a human-readable document,

such templates can allow the data entered in the document to be mapped to a

machine-readable representation using clinical encoding taxonomies (such asSNOMED CT)

For Clinical Document Creators With the CDSA add-in enabled, a user can complete a

clinical form created from a CDSA-enabled Office Word template. The one Office Word

(.docx) file contains both human-readable and machine-readable clinical information (such

as a HL7 CDA representation).

For Clinical Document recipients Without the need for the CDSA add-in, a recipient can

read (but not edit) the Office Word document. The document .docx file still contains the

machine-readable clinical information and this can be extracted and uploaded to an

external clinical system.

The remainder of this document provides background information and worked examples to

illustrate how you can customise CDSA for your own purposes. The topics covered are:

Overview of the CDSA development environment (see section2)

Constructing a template using the included controls (see section3)

Creating a simple control (see section4)

Customising the layout of an existing control (see section5)

Creating a WindowsPresentation Foundation (WPF) based control (see section6)

Creating a WPF-based list control (see section7)

Creating a mapping class (see section8)


7/74

Microsoft

Page 3




2 OVERVIEW OF THE CDSADEVELOPMENT

ENVIRONMENT

2.1 System PrerequisitesTo run and use the CDSA development environment requires a system matching at least the

following requirements.

Your computer must be running one of the following operating systems:

Windows7

Windows Vista

Service Pack 1

With Windows Vista, you also need Microsoft.NET Framework 3.5 Service Pack 1

1

WindowsXP Service Pack 3

With Windows XP, you also need Microsoft.NET Framework 3.5 Service Pack 1

1

Your computer must have these applications installed:

Microsoft Office Word 2010 or Microsoft Office Word 2007

With Microsoft Office Word 2007, you also need:

2007 Microsoft Office System Update: Redistributable Primary Interop Assemblies2

MicrosoftVisual Studio

Tools for the Microsoft Office System (version 3.0 Runtime)

(x86)

3

Microsoft Visual Studio Tools for the Microsoft Office System (version 3.0 Runtime)

Service Pack 1 (x86)

4

MicrosoftVisual Studio2008 Service Pack 1 or Microsoft Visual Studio 2010

2.2 Assumed Skills and Knowledge

This guide assumes that you have at least the following technical knowledge and skills:

Expertise with Office Word, in particular an in-depth knowledge of table formatting and the

creation of templates

General understanding of Microsoft Visual Studio and its underlying platform technology

Guidelines on the skill sets required in order to make best use of CDSA, as well as reference

material and training resources, are detailed on the Microsoft TechNet Web site5

1Downloadable from

. However, the use

of Microsoft courses and resources are optional and training on a number of relevant areas can be

provided by a variety of certified training partners.

Microsoft .NET Framework 3.5 Service Pack 1

2Downloadable fromRedistributable Primary Interop Assemblies

3Downloadable fromVisual Studio Tools for the Microsoft Office System

4

Downloadable fromVisual Studio Tools for the Microsoft Office System Service Pack 15Microsoft TechNet {R1}:http://technet.microsoft.com/
http://www.microsoft.com/downloads/details.aspx?FamilyID=AB99342F-5D1A-413D-8319-81DA479AB0D7&displaylang=enhttp://www.microsoft.com/downloads/details.aspx?FamilyID=AB99342F-5D1A-413D-8319-81DA479AB0D7&displaylang=enhttp://www.microsoft.com/downloads/details.aspx?FamilyID=AB99342F-5D1A-413D-8319-81DA479AB0D7&displaylang=enhttp://www.microsoft.com/downloads/details.aspx?FamilyID=59daebaa-bed4-4282-a28c-b864d8bfa513&DisplayLang=enhttp://www.microsoft.com/downloads/details.aspx?FamilyID=59daebaa-bed4-4282-a28c-b864d8bfa513&DisplayLang=enhttp://www.microsoft.com/downloads/details.aspx?FamilyID=59daebaa-bed4-4282-a28c-b864d8bfa513&DisplayLang=enhttp://www.microsoft.com/downloads/details.aspx?displaylang=en&FamilyID=54eb3a5a-0e52-40f9-a2d1-eecd7a092dcbhttp://www.microsoft.com/downloads/details.aspx?displaylang=en&FamilyID=54eb3a5a-0e52-40f9-a2d1-eecd7a092dcbhttp://www.microsoft.com/downloads/details.aspx?displaylang=en&FamilyID=54eb3a5a-0e52-40f9-a2d1-eecd7a092dcbhttp://www.microsoft.com/downloads/details.aspx?familyid=D8EB4921-891A-4B5E-973F-0B96E6CCF376&displaylang=enhttp://www.microsoft.com/downloads/details.aspx?familyid=D8EB4921-891A-4B5E-973F-0B96E6CCF376&displaylang=enhttp://www.microsoft.com/downloads/details.aspx?familyid=D8EB4921-891A-4B5E-973F-0B96E6CCF376&displaylang=enhttp://technet.microsoft.com/http://technet.microsoft.com/http://technet.microsoft.com/http://technet.microsoft.com/http://www.microsoft.com/downloads/details.aspx?familyid=D8EB4921-891A-4B5E-973F-0B96E6CCF376&displaylang=enhttp://www.microsoft.com/downloads/details.aspx?displaylang=en&FamilyID=54eb3a5a-0e52-40f9-a2d1-eecd7a092dcbhttp://www.microsoft.com/downloads/details.aspx?FamilyID=59daebaa-bed4-4282-a28c-b864d8bfa513&DisplayLang=enhttp://www.microsoft.com/downloads/details.aspx?FamilyID=AB99342F-5D1A-413D-8319-81DA479AB0D7&displaylang=en


8/74

Microsoft

Page 4




2.3 Building the CDSA Solution in Visual Studio

You can build the CDSA solution in either Visual Studio 2008 or Visual Studio 2010. Obtain the

CDSA solution files by downloading the Microsoft.Cdsa.zip file6

2.3.1 Visual Studio 2008

.

To build the CDSA solution in Visual Studio 2008, follow these steps:

1. Extract all the files from the Microsoft.Cdsa.zip file into their default file structure

2. Navigate to the \Microsoft.Cdsa\Solutions\Main folder and open the Main.sln file

3. Press F6 to build the solution

2.3.2 Visual Studio 2010

The CDSA solution has been created by Visual Studio 2008. The solution needs to be upgraded for

use with Visual Studio 2010. To do so, follow these steps:

1. Extract all the files from the Microsoft.Cdsa.zip file into their default file structure.

2. Navigate to the \Microsoft.Cdsa\Solutions\Main folder and open the Main.sln file

3. Follow the steps in the Visual Studio Conversion Wizard to upgrade the solution to Visual

Studio 2010

4. A dialog box will appear asking Do you want to upgrade the Web site to use .NET

Framework 4.0? Select the Do the same for all Webscheck box and click No

5. When the solution has opened, right-click on the Microsoft.Consulting.OfficeTools.Controls

project and select the Properties> Code Analysistab

6. Disable the code analysis rule CA1903 - Microsoft.Portability: Use only API from

targetted frameworklisted under Portability Rules by clearing the check box

7. Disable the same rule for the Microsoft.Consulting.Servicesproject

8. Press F6 to build the solution

2.4 Debugging the CDSA Add-In Using Visual Studio

You can run the Office Word add-in project in debug mode using Visual Studio for either Office

Word 2007 or Office Word 2010.

2.4.1 Office Word 2007

To run in debug mode for Office Word 2007, follow these steps:

1. In Solution Explorer, check that the Microsoft.Consulting.OfficeTools.WordAddinproject is

set as the start-up project by default (the project name should be displayed in bold). If it is

not, right-click the project and select Set as StartUp Project

2. Press F5 to launch Office Word with the CDSA add-in enabled

6Downloadable fromhttp://www.codeplex.com/cdsa
http://www.codeplex.com/cdsahttp://www.codeplex.com/cdsahttp://www.codeplex.com/cdsahttp://www.codeplex.com/cdsa


9/74

Microsoft

Page 5




2.4.2 Office Word 2010

To run in debug mode for Office Word 2010, follow these steps:

1. In Solution Explorer, check that the Microsoft.Consulting.OfficeTools.WordAddinproject is

set as the start-up project by default (the project name should be displayed in bold). If it is

not, right-click the project and select Set as StartUp Project

2. Right-click on the Microsoft.Consulting.OfficeTools.WordAddin project and select the

Properties > Debug tab

3. Set the Start Actionby selecting the Start external programradio button.

4. Navigate to the location of the Office 2010 WINWORD.EXE file (usually C:\Program

Files\Microsoft Office\Office14\WINWORD.EXE)

5. Press F5 to launch Office Word with the CDSA add-in enabled

2.5 Installing the CDSA Office Word Add-In

The CDSA solution includes a set-up project (Microsoft.Consulting.OfficeTools.WordAddin.Setup)that creates a sample MSI. You can use this to install the CDSA Office Word add-in on a per-user

basis (that is, for the current user only).

The sample installer performs the following actions:

Installs the CDSA Office Word add-in for the current user

Adds a new registry key:

HKEY_CURRENT_USER\Software\Microsoft\Office\Word\Addins\Microsoft.Consulting.OfficeTools.WordAddin

Copies the following files to the installation folder:

All assemblies used by the CDSA Office Word add-in

Schemas for native CDSA XML

The CDSABuildingBlocks Word template

Unlocked versions of the sample CDSA Office Word templates (for developer

demonstration purposes)

By default, the installation folder is:

C:\Users\\AppData\Roaming\Microsoft\Clinical Documentation Solution Accelerator

Copies the sample CDSA Office Word templates to the Clinical Documents folder in the

users Templates directory. Those versions of the templates are locked and end users can

only update the content of the form fields. On Windows 7 and Windows Vista, the

Templates directory is:

C:\Users\\AppData\Roaming\Microsoft\Templates\Clinical Documents

Note

The sample installer does not check for prerequisites before installing CDSA. When creating a version of

the installer for a production environment, you may need to create different versions of the installer for

Office 2007 and Office 2010 (Office 2007 has a number of prerequisites that are not required for Office

2010). See the ReadMe.txt for a full list of the end-user prerequisites.


10/74

Microsoft

Page 6




2.6 The CDSA Source Folders

Table 1 describes the directory structure of the CDSA source and the content of each folder:

Directory Content

Sample Forms Two sample Office Word templates (.dotx files) built using CDSA controls:

Cardiology Referral form

Cardiology Referral form (Unlocked)

Discharge Summary form

Discharge Summary form (Unlocked)

Microsoft.Cdsa.Services.Common Service contracts for the Terminology Service and the Drug Service and

data contracts for the Terminology service

Microsoft.Consulting.Data Data contracts for the Drug Service

Microsoft.Consulting.OfficeTools.Controls All controls-related classes including:

CDSA section controls WPF controls used by the section controls

Layout for the WPF controls on the Document Summary task pane

Helper classes for the controls

Base storage class and sample classes for the Referral and Discharge

Summary forms

Referral and Discharge Summary mappings and schema files

Model class used by the storage class

Microsoft.Consulting.OfficeTools.WordAddin The CDSA Office Word add-in project including:

Ribbon class

Developer Properties window implementation Document Summary task pane implementation

Microsoft.Consulting.OfficeTools.WordAddin.Setup Setup project that builds a sample Microsoft Installer (MSI) to install the

CDSA Office Word add-in and the two sample templates on a per-user basis

Microsoft.Consulting.Services WindowsCommunication Foundation (WCF) service interfaces for:

The sample SNOMED CT Terminology Service

(TerminologyService.svc)

The sample medications Data Service (DrugService.svc)

Table 1: CDSA Directories and Folder Content

2.7 Accessing the CDSA Development Environment

To access the CDSA development environment after installing the CDSA Office Word add-in, follow

these steps:

1. Start Office Word

2. Click the CDSA Developertab. If it is not visible, take these steps first:

a. Click the CDSA Usertab

b. From the CDSA Userribbon, click the Developer Tabbutton


11/74

Microsoft

Page 7




Figure 2 shows what the CDSA developer ribbon looks like when you first access it:

Figure 2: CDSA Developer Ribbon

Table 2 describes the function of each button on the CDSA developer ribbon:

Button Description

Converts an Office Word document into a CDSA document by creating the correct XML

configuration.

You use this tool as the first step in developing a CDSA-compliant document. Until this is done,

CDSA disables all of the other developer ribbon buttons.

Accesses the configuration and data details of the controls in the document.

Opens the library of built-in controls that you can use in your CDSA document. You can also add

controls to the Section Gallery that you have implemented.

A control placed in a document is referred to as a section.

Table 3details the controls available in the Section Gallery.

Removes a section from your CDSA document.

You have to select the section before you can delete it.

Ensures all sections are updated according to the latest configuration and are bound to the native

XML.

You use this after making amendments to controls or changing other CDSA document definitions.

Accesses the array of built-in section building-blocks that you can use to create your own controls.

A section building block is referred to as apart.

Table 4details the parts available in the Custom Parts Gallery.

Table 2: CDSA Developer Buttons

If you are implementing a new CDSA template, you can make use of the built-in sections already

available in the Section Gallery.Table 3 lists and describes the sections in the Section Gallery:

Section Name Descript ion

Address Field Multi-line address entry fields with labels

Allergies Concept List Allergy search and list control with date and status settings (provides encoding)

Check Box Simple check box with label

Date Field Automatic and free-text date entry

Drop Down List Selection menu with prompt watermark text

Free Text Parser Clinical terms search and list control based on user entered free-text (provides encoding)

Medication List Medications search and list control (provides encoding)


12/74

Microsoft

Page 8




Section Name Descript ion

Mini Patient Banner Simplified patient details banner with labels

Patient Banner Full patient details banner with labels

Radio Button Simple radio button with label

Single Concept List (no date) Single concept search and list control either without date support (provides encoding)

Single Concept List (with date) Single concept search and list control either with date support (provides encoding)

Text Field Simple text entry field with prompt watermark text

Table 3: Section Gallery

If you are implementing a new CDSA control, you can make use of the built-in parts available in the

Custom Parts Gallery, each of which provides a rich text content control placeholder.Table 4 lists

and describes the parts in the Custom Parts Gallery:

Part Name Descript ion

Action Control Insertion Part Placeholder for a .NET Framework control

Section Edit Button Insertion Part Placeholder for a Section Edit button

Section Line Delete Button Insertion Part Placeholder for a lines Delete button

Section Line Edit Button Insertion Part Placeholder for a lines Edit button

Section Line Part Placeholder for a line layout

Section Lines Insertion Part Placeholder for a sections line insertion table

Section Part Constructs a section layout. Adds a new section to the document and to the Developer

Propertieswindow

Word Control Insertion Part Placeholder for an Office Word Visual Basic for Applications (VBA) control

Table 4: Custom Parts Gallery

The worked examples in the remainder of this guide describe how you can use the CDSA

development environment to create and customise your own CDSA-compliant documents.


13/74

Microsoft

Page 9




3 CONSTRUCTING A TEMPLATE USING THE INCLUDED

CONTROLS

3.1 IntroductionThe CDSA software includes a number of ready-made controls for you to use when constructing

your Office Word templates. You can also use controls of your own making, as described in section

7.However, the built-in controls provide a wide range of functionality and you may find that they are

sufficient to implement all of the features you need.

You construct a template by using the tools and facilities provided by the CDSA development

environment (as described in section2.3). After starting Office Word, you must open the CDSA

Developertab and click the Convert To Clinical Documentbutton to begin the development

process.

In outline, the steps involved in constructing a template are:

1. Insert and format Office Word tables to structure your document (for ease of layout andusability purposes, most controls are located in tables) (see section3.2)

2. Add and modify the required controls (see section3.3)

3. Delete controls to fine-tune the template layout (see section3.4)

To guide you in implementing your template, the remainder of this section provides more details

and examples to illustrate each of those steps.

3.2 Inserting and Formatting Office Word Tables

You use the standard table insertion and layout features of Office Word to create the outline

structure of your document. An example set of steps you might follow would be:

1. Insert a table with enough columns and rows to match your input requirements

2. Turn on gridlines to help track the layout of the cells

3. Adjust the size and other features of the cells to match the layout you require

4. Add narrow rows as spacers to separate distinct blocks of the table

5. Use the first row as a header for the material in the table (for example, by adding special

formats such as a different background shade with an external border and the text in a

coloured font)

6. Prepare the cells that will hold the controls (for example, to emphasise that these are inputareas, configure borders around the cells and add an appropriate label to each)

When you have completed the outline structure, you can move on to include the CDSA controls

that will help your users add their information to the document.


14/74

Microsoft

Page 10




3.3 Adding and Modifying the CDSA Contro ls

Although the provided controls offer a wide range of functionality, when adding each one to your

template you follow the same top-level procedure:

1. Place the cursor where you want to locate the control

2. Insert the control you require by selecting from the Section Galleryin the CDSA

Developerribbon

3. Click the Developer Propertiesbutton and open the controls Configurationscreen. Enter

a unique Section Idfor it

4. If required for your implementation, modify other Configurationscreen parameters (for

example, to modify label or watermark text)

At its simplest, you can use a control in your template just by taking steps 1 to 3. However, the

controls also allow you to customise them according to your needs. The remainder of this section

provides examples of how you do this by detailing how to add and customise the most useful

controls for clinical documents.

The examples include controls for entering relatively basic text:

Text Field Where a user enters plain text

Address Field Where a user enters an address

There are also more sophisticated search and match controls to help your users find and enter

specific medical terms:

Medication List Helps the user build a list of drug prescriptions

Single Concept L ist Helps the user build a list of descriptive terms and concepts (such

as symptoms)

Free Text Parser Identifies medical terms and concepts from a free-text descriptionentered by the user

Additional controls assist the users in selecting from pre-defined options:

Drop Down List Where a user selects from a menu of items

Radio Button Where a user selects or deselects an item


15/74

Microsoft

Page 11




Table 5 describes how you add and modify each of those controls:

Step Descript ion Screenshot

Adding a Text Field

1. Select the control you want to

insert. In this case, create a simpletext entry control by selecting Text

Field.

Note

Some controls include

paragraph spaces before and

after them. Delete if not

required.

2. TheText Fieldcontrol displays

default watermark text.

To edit this:

1. In the Office Word Developer

ribbon, click Design Mode

2. Edit the text as required

3. Click Design Modeto exit

3. As templates can contain a lot of

controls, it is good practice to alter

the Section Id of each control as

you add it. This ensures the Section

Id has a more meaningful name for

future reference.

Alter the Section Id by:

1. In the CDSA Developer ribbon,

click Developer Properties

2. Select the control from the left

pane

3. Click the Configurationtab

4. Edit the text in the Section Id

field so it is specific to this

section of the document or is

otherwise meaningful to you

5. Click elsewhere in the pane to

save the new Section Id

6.

Exit the ClinicalDocumentation Developer

Windowto return to your

document

Remember to repeat these steps

for every control you add


16/74

Microsoft

Page 12





Adding an Address Field

1. Another commonly required

component of a document is a

section to hold an address.To include this, selectAddr ess

Fieldfrom theSection Gallery.

2. To edit the labels:





Adding a Medicat ion List

1. To include a Medication List, select

it from the Section Gallery.

This control supports the formal

encoding of terms. Therefore,

including it in your document also

creates an entry in the Document

Summarypanel

2. Besides altering the Section Id, you

can also modify the display and

label text.

To do so, click Developer

Propertiesand edit these

Configurationfields for the control:

Display Name Modifies the

section header displayed in the

Document Summarypane

Word Control Label Modifies

the label on the Add button

Section Line Edit ButtonLabel Modifies the label on

the Edit button (only visible

after the user has added a

medication to the list)

Section Line Delete Button

Label Modifies the label on

the Delete button (only visible

after the user has added a

medication to the list)


17/74

Microsoft

Page 13





Adding Single Concept Match ing L ist

1. To include Single Concept

Matching, select it from the Section

Gallery.This control supports the formal

encoding of terms. Therefore,



Summarypanel

2. Besides altering the Section Id,

display and label text, you can also

specify the terminology to search

through and modify the controls

watermarks.


Propertiesand edit theseConfigurationfields for the control:

SearchSubset Specifies the

clinical terminology subset that

CDSA will search against

ConceptSearchWatermark

Modifies the watermark in the

Concept Search box

Add it ionalTextWatermark

Modifies the watermark in the

Additional Text box

3. You can also alter the headings

used in the display of the concepts.

To do so, in the Office Word

Developerribbon, click Design

Modeand follow these steps:

1. In the document, select the

heading to change

2. Click Properties

3. Uncheck theContents cannot

be editedbox and click OK

4. Modify the heading

5. Click Properties and recheck

the Contents cannot be edited

box

6. Click OKand click Design

Modeto exit


18/74

Microsoft

Page 14





Adding a Free Text Parser

1. To include a Free-Text parser, add

it from the Section Gallery.

This control supports the formalencoding of terms. Therefore,



Summarypanel

2. Change the Section Id as described

previously.

As also described previously, you

can alter other aspects of the free-

text parser operation and display by

modifying the appropriate fields in

the Configurationtab.


19/74

Microsoft

Page 15





Adding a Drop Down List

1. To include a drop-down list, add it

from the Section Gallery.

2. Change the Section ID as

described previously.

To add items to the drop-down list:

1. Select the list


ribbon,click Properties

3. In the Content Control

Propertiesscreen, clickAdd 4. On theAdd Choicescreen,

enter the details for the menu

item

5. Click OK

6. Repeat steps 3, 4 and 5 for

each item you want to add to

the menu

7. When complete, click OK


20/74

Microsoft

Page 16





Adding a Radio But ton

1. To include a radio button, add it

from the Section Gallery.

Add as many radio buttons asneeded to match the number of

options you wish to offer your

users.

2. Besides altering the Section Id, you

will also need to specify a label for

each button and a group name that

they share.


Propertiesand edit these

Configurationfields for the control:

Word Control Label

Specifies the label that appearsbeside the button

GroupName Specifies an

identifier for this group of

buttons (use the same identifier

for all the buttons in this group)

Table 5: Adding Controls to the Template

3.4 Deleting Controls

As you progress with the development of your template, you may decide that controls entered

earlier are no longer needed. However, because CDSA documents are structured, you cannot

simply delete controls as you would normally delete items from an ordinary Office Word document.

Instead, you have to use the CDSA DeleteSectiontool.

To delete a control using the Delete Sectiontool:

1. Select all of the control that you wish to delete

2. Open the CDSA Developerribbon

3. Click Delete Section

4. To ensure the document is cleanly updated, click Refresh All Sections


21/74

Microsoft

Page 17




4 CREATING A SIMPLE CONTROL

4.1 Introduction

CDSA controls are made up of parts. Each part is an Office Word content control that has a specific

title and/or tag. For more advanced controls, you can insert buttons and .NET controls to handle

user input.

Note

Not all types of Office Word content control can be bound to the CDSA XML. For example, plain text and

drop down lists can be bound but a rich text content control cannot. Therefore, when designing a new

control, it is important that you identify which of its areas need to display bound content and which are

placeholders for buttons or .NET controls.

This section describes the steps to take when building a simple control. The control used as an

example is a name input control that provides fields for the user to enter a family name, a given

name and a title.

The example shows how the control is constructed from:

An outer section content control (a CDSA Section Part)

Inner plain text content controls for each field (Office Word content controls)

When the control is complete, the example goes on to show:

How to bind the control to the CDSA XML

How to add the control to the CDSA Section Gallery for use in other documents

When adding a new control, you always begin by following the same steps:


2. Open the CDSA Developertab and click the Convert To Clinical Documentbutton to

begin the development process

Having done that, you can continue to develop your new control. Follow the steps in the next

section to see how this is done for the example name input control.


22/74

Microsoft

Page 18




4.2 Creating the Name Input Control

Table 5 shows the steps required to create a simple name input control:


1. In the Custom Parts Gallery

menu, select Section Partto

insert it in your document

2. In the Insertribbon, click Table.

Format the table to match the

layout requirements for your

control.

For the example name input

control, the layout is:

Two columns (resized to fit the

content) and three rows No borders

Add labels in the first column

(Family name, Given name

and Title), right-aligned and

italic

3. Insert plain text content controls in

each cell of the second column.

In the Controlsgroup of the

Office Word Developerribbon,

click the button to insert each

one.

4. Select each plain text content

control in turn and follow these

steps:

1. In the Controlsgroup, click

Properties

2. Enter a name for the control in

the Titlefield (respectively

Family name, Given name

and Title)

3. Click OK


23/74

Microsoft

Page 19





5. You may want to change the

watermark text displayed (Click

here to enter text).

To edit this:





Note

Design Mode shows the

beginning and end section

tags and all the fields inside.

This lets you see the range

your control uses.

6. Office Word includes paragraph

spaces before and after the table

to prevent it interfering with the

section controls.

To better align the table:

1. Place your cursor in the

paragraph space

2. In the Homeribbon, open the

Paragraphdialog

3. InSpacing, set Beforeand

Afterto a suitable value

4.

From theLine Spacingmenu,selectExactlyand use theAt

field to set a suitable height

7. In the CDSA Developer ribbon,

click Refresh All Sections.

This updates the new control and

creates bindings for it in the CDSA

XML using the Content Control

Properties title as the name for the

binding.


24/74

Microsoft

Page 20





8. You can see that your new control

(now identified as a CDSA

section) is in place by:

1. In the CDSA Developer

ribbon, click DeveloperProperties

2. Select the section in the left

pane

3. Click the Datatab

Three new UniqueIdentifiers

match the plain text content

controls you defined.

TheDeveloper Properties

screen will also reflect content

entered in the fields in the

document.

Table 6: Creating a Simple Control


25/74

Microsoft

Page 21




5 CUSTOMISING THE LAYOUT OF AN EXISTING CONTROL

5.1 Introduction

The example in this section describes the steps you take to create a customised version of one of

the built-in CDSA controls. The example chosen is that of a single concept list control.

To create a custom layout for a single concept list control, you need to include the following parts in

your control layout:

An outer section content control (a CDSA Section Part)

A section line insertion point content control (a CDSA Section Lines Part)

An action control insertion point content control (a CDSAAct ion Control Part)

A word control insertion point content control (a CDSA Word Control Part)

Each of those parts is available from the CDSA Custom Parts Gallery.

As before, when adding a new control, you always begin by following the same steps:


2. Open the CDSA Developertab and click the Convert To Clinical Documentbutton to

begin the development process

Having done that, you can continue to create your customised control. Follow the steps in the next

section to see how this is done for the example single concept list control.

5.2 Creating the Customised Single Concept List Control

Table 5 shows the steps required to create the customised single concept list control:


Inserting Parts and Formatting the Layout


menu, select Section Partto

insert it in your document

Add some extra paragraphs inside

the Section Part to make it easier

to insert the other components of

the layout.

2. For this custom layout, the part

that will provide the search controlgoes in first:

1. Position the cursor on the first

paragraph


menu, selectAct ion Contr ol

Partto add it

This provides a rich text content

control as a placeholder for the

WPF control that will support

searching later.


26/74

Microsoft

Page 22





3. Add an insertion point for the Add

button at the second paragraph:

1. Right-align the second

paragraph


menu, select Word Control

Partto add it

4. Add a part to position the other

lines that will make up the layout:

1. Position the cursor at the

paragraph below the Word

Control Part


menu, selectSection Lines

Partto add it

This provides a rich text contentcontrol as a placeholder for the

lines that will display the list of

search results.

5. Format the lines in the layout

using a table:

1. Position the cursor in the

Section Lines Part

2. In the Insertribbon, click

Table

Create the layout in this fixed

order:

1. Two rows

2. Each row distinctly shaded

with a rule below the first and

the last

3. No other borders

4.All cell margins = 0

6. To format the headings, insert

another table in the top row with

these features:

First column width = 35%

Second column width = 65%

All cell margins = 0

No borders

Enter Diagnosis in the first

column and Additional Text in the

second. Make both bold italic.


27/74

Microsoft

Page 23





7. Remove any unwanted space:

Set the bottom row height to

hide it from view leaving just

the table headings visible

Delete unneeded paragraphs

and modify the size of those

remaining to achieve the

desired layout (for example,

Office Word allows a minimum

Multiple line spacing of 0.06)

Adding Control Assembly and Class Informat ion

1. Configure the control properties:


ribbon, click Developer

Properties

2. Select the section in the left

pane


Complete theCommon

Propertiesfields as follows:

Section Id DiagnosisList

Display Name Diagnosis

List

This appears in the Document

Summarypane

Word Control Label Add

DiagnosisThis is the label for what will

be the Add button

Section Line Edit Button

Edit

This is the label for what will

be the Edit button

Section Line Delete Button

Delete

This is the label for what will

be the Delete button


28/74

Microsoft

Page 24





2. This control is a customised

version of the built-in Single

Concept List control. Therefore,

configure the Section Class

Propertiesfields to match thoseof the Single Concept List control.

The simplest way to do this is to:

1. Position the cursor on an

empty line

2. Select Single Concept Li st

from the Section Galleryto

insert it

3. OpenDeveloper Properties

and use it to move between

the configurations

4. Copy the individual Single

Concept Li stsettings andpaste them into the

Configurationtab for your

control

5. Use theDelete Secti ontool to

remove the Single Concept

List section when you have

finished

The settings are as shown in the

screenshot.

Initialising, Customising and Testing the Control

1. In the CDSA Developer ribbon,click Refresh All Sections.

This initialises the control using

the assembly information you

entered in the previous step.


29/74

Microsoft

Page 25





2. Examine and if necessary modify

the custom properties inherited

from Single Concept List Control:


ribbon, click DeveloperProperties

2. Select DiagnosisListfrom the

left pane


For example, to modify the

watermark prompt displayed in the

additional text field, edit the

Add it ionalTextWatermark field.

When done, exit the Clinical

Documentation Developer

Window.

3. To test that the control works:

1. Click theAdd Diagnos is

button

The WPF search control

displays above the button

2. In the Search for a conceptbox, enter Chest pain and

click

3. Select the term you want from

the list and click Save

4. Repeat steps 1, 2 and 3 but

search for hypertension.

4. As defined in your format:

The lines display with rows

shaded every second row

EditandDeletebuttons

enable you to modify the

content

Table 7: Customising the Layout of an Existing Control


30/74

Microsoft

Page 26




6 CREATING A WPF-BASED CONTROL

6.1 Introduction

CDSA provides support for two types of control for use in your clinical document templates:

Simple controls (constructed using the built-in Office Word content controls)

Complex, rich-editing controls (constructed using custom-built WPF controls)

Section4 described how to construct a simple control using the Office Word content controls. This

section provides a worked example of how to build a complex CDSA control based upon an

existing CDSA WPF control.

Important

The example shows how to include an existing WPF control into the CDSA control gallery. It does notcover how to create a WPF-based control from first principles. To learn more about creating

WPF-based controls, consult the relevant articles on the Microsoft Developer Network (MSDN) Web

site. In addition, you can find WPF controls in the MSCUI Controls Toolkit7

For further guidance, look at the code for some of the CDSA controls. For example, after inserting aWPF control into a document, CDSA controls also listen for a number of events raised by Office Word

(such as BeforeSave, BeforePrint and SelectionChanged)in order to remove the WPF control from

the document if necessary. It is good practice to follow a similar pattern for all controls based on WPF

or on other .NET Framework controls.

.

In the example, you will see how to construct a new CDSA control starting from a WPF-based

person-lookup control. That control allows the user to enter some characters and use them to

initiate a search against a list of people (such as the names of clinical staff within a hospital stored

in a local database).

7Available fromwww.mscui.net
http://www.mscui.net/http://www.mscui.net/http://www.mscui.net/http://www.mscui.net/


31/74

Microsoft

Page 27




Figure 3 shows how such a control might work:

Figure 3: How the WPF-Based Control Might Work

Figure 3 shows the controls sequence of operation:

1. The section in the document shows that no one has yet been selected. It contains a

Changebutton

2. Clicking the Changebutton causes the WPF control to appear above the section

3. Entering a name and clicking the Searchbutton presents a list of search results, where a

result can be selected

4. Clicking the Savebutton removes the WPF control and displays the selected persons

details in the document

To create this control, you need to take these steps:

Add a new section control to the CDSA Visual Studio solution

Create an Office Word building block for the Control

Test the new control in a CDSA document

To guide you in creating your control, the remainder of this section provides more details and

examples to illustrate each of those steps.


32/74

Microsoft

Page 28




6.2 Creating the WPF-Based Control

Table 5 shows the steps required to create a WPF-based control:


Adding a New Section Control to the Visual Stud io Solut ion1. In Visual Studio, open the CDSA

Solution:

1. Expand the

Microsoft.Consulting.OfficeT

ools.Controlsproject

2. In this example, a custom

WPF control has already been

added to the project, called

PersonEntry and the default

style and templates are

already present in the

Generic.xaml file

2. Create a new section control to

place the Person Entrycontrol in

the document and handle the

SaveandCancelevents.

To do this, first create a new class

calledPersonField

3. ThePersonFieldclass inherits

basic behaviour definitions from

the providedSectionBase

control.

Note

For security reasons, all

sections must derive from

SectionBase to prevent

execution of code not related

to the CDSA solution

namespace Mi crosof t . Consul t i ng. Of f i ceTool s. Cont r ol s{

publ i c cl ass Per sonFi el d : Sect i onBase{}

}


33/74

Microsoft

Page 29





4. Specify the private fields within

the class. These fields are:

Wrapper of type

Microsoft.Office.Tools.Word.

OLEControl

PersonEntry of type

PersonEntry

Host of type ElementHost

/ / / / / / St or es t he cont r ol wr apper ./ / / pr i vat e Mi crosof t . Of f i ce. Tool s. Wor d. OLEContr ol wr apper;

/ / / / / / The person ent r y cont r ol ./ / / pri vat e Per sonEntr y per sonEnt r y;

/ / / / / / The WPF el ement host ./ / /

pr i vat e El ementHost host ;

5. Override the initialisation method

to allow addition of a custom

configuration value for the

watermark in the search field.

publ i c over r i de voi d I ni t i al i ze(Mi crosof t . Of f i ce. I nt er op. Wor d. Cont ent Cont r ol

cont ent Cont r ol ){

base. I ni t i al i ze( contentContr ol ) ;i f ( st r i ng. I sNul l Or Empt y(

thi s. Get Conf i gur at i onVal ue( "Wat er mar k" ) ) ){

thi s. AddConf i gur at i onI t em("Wat er mar k" ,"Ent er a search f or a person") ;

}

}

6. Override theEditSection method.

CDSA calls EditSection when the

user clicks a sections Editbutton.

The button is inserted from theSectionBaseclass

pr ot ect ed over r i de voi d Edi t Secti on( ){

base. Edi tSect i on() ;t hi s. I nsert Act i onContr ol () ;

}


34/74

Microsoft

Page 30





7. Before inserting the WPF control,

check if the WPF control is not

already in the document and also

check that an action control

insertion point was found withinthe section.

If both checks are OK, go ahead

and insert the WPF control into

the ActionControlInsertionPoint:

1. If necessary, create an

instance of thepersonEntry

control. Add handlers to the

Saveand Canceledevents

2. Update theWatermark

property to use the value

specified in the custom

configuration3. Host the WPF control in a

WinForms control (Office Word

does not support WPF content

directly in a document)

4. Create an instance of an

ElementHost and set the

background colour to white

5. Set the LockContents

property to falseto enable

insertion of the control.

6. Insert the ElementHost into the

document. ThepersonEntrycontrol methods set the size at

insertion. The method returns

the wrapper that Office Word

uses to host the control. Store

this locally to allow deletion of

the wrapper when the control

is removed from the

document.

7.Add the person entry control

as a child

8. Lock the action control

insertion point.

The control is now in the

document.

pr i vat e voi d I nser t Acti onCont r ol ( ){

i f ( t hi s. wr apper == nul l &&thi s. Acti onCont r ol I nsert i onPoi nt ! = nul l )

{i f ( t hi s. per sonEnt r y == nul l ){

thi s. per sonEnt r y = new Per sonEnt r y( ) ;thi s. per sonEnt r y. Saved +=

new EventHandl er ( per sonEnt r y_Saved) ;thi s. per sonEnt r y. Cancel ed +=

newEventHandl er ( per sonEnt r y_Cancel ed) ;

}

thi s. per sonEnt r y. Wat ermark =thi s. Get Conf i gur at i onVal ue("Wat ermar k" ) ;

t hi s. host = new El ementHost ( ) ;t hi s. host . BackCol or =

Syst em. Dr awi ng. Col or . Whi t e;thi s. Act i onCont r ol I nser t i onPoi nt . LockCont ent s

= fal se;thi s. wr apper =

Mi crosof t . Of f i ce. Tool s. Wor d. Extensi ons. Document Ext ensi ons. Get Vst oObj ect (

thi s. Act i onCont r ol I nsert i onPoi nt . Range. Document ) . Contr ol s. AddCont r ol (

thi s. host ,thi s. Acti onCont r ol I nser t i onPoi nt . Range,

thi s. per sonEnt r y. Desi r edWi dt h,thi s. per sonEnt r y. Desi r edHei ght ,st r i ng. For mat(

System. Gl obal i zat i on. Cul t ureI nf o. Cur r ent Cul t ur e,"{0}_Per sonEnt r y_{1}",

t hi s. Sect i onI d,

Sect i onLi st Xml Hel per . Get Uni queI denti f i er () )) ;t hi s. host. Chi l d = thi s. per sonEnt r y;thi s. Act i onCont r ol I nser t i onPoi nt . LockCont ent s

= true;}

}


35/74

Microsoft

Page 31





8. Add a method called

RemoveActionControlthat:

1. Deletes the wrapper control

from the document

2. Unlocks the action control

insertion point

3. Sets the range text to empty to

clear out the content control

4. Locks the action control

insertion point again and sets

focus back to the Editbutton

pr i vat e voi d RemoveAct i onCont r ol ( ){

i f ( t hi s. wr apper ! = nul l ){

thi s. wr apper . Del et e( ) ;

t hi s. wr apper = nul l ;}

i f ( t hi s. host ! = nul l ){

thi s. host. Chi l d = nul l ;}

thi s. Act i onCont r ol I nser t i onPoi nt . LockCont ent s =f al se;

thi s. Act i onCont r ol I nser t i onPoi nt . Range. Text =st r i ng. Empty;

thi s. Act i onCont r ol I nser t i onPoi nt . LockCont ent s =true;

}

9. Create an event handler

personEntry_Canceled (if it does

not already exist) and call

RemoveActionControlto remove

the WPF control from the

document without updating the

values

voi d per sonEnt r y_Cancel ed( obj ect sender, EventAr gs e){

thi s. RemoveAct i onCont r ol ( ) ;

}


36/74

Microsoft

Page 32






personEntry_Saved (if it does

not already exist). Add a call to


the WPF control from thedocument, first saving the

information in the control back to

the native data XML:

1. Create a field for the custom

XML part storing the document

data

2. Call AddElementNode for each

part of the name, passing in

the:

Custom XML part

Element name

Section Id

Empty section line ID (as

this is not a list item)

Value ( if no person was

selected, pass in an empty

string)

3. Repeat for GivenName and

Title

The values in the document

update automatically because the

plain text content controls in the

document are already bound to

those elements in the native dataXML.

voi d per sonEnt r y_Saved(obj ect sender , EventAr gs e){

Of f i ce. Cor e. Cust omXMLPar t xml =

El ement Li st Xml Hel per . Get El ement Li st Par t ( t hi s. Secti onC

ont ent Cont r ol . Range. Document ) ;El ement Li st Xml Hel per . AddEl ement Node(

xml ,"Fami l yName",thi s. Sect i onI d,st r i ng. Empty,thi s. per sonEnt r y. Sel ect edPer son ! = nul l ?

thi s. per sonEnt r y. Sel ect edPer son. Fami l yName :s t r i ng. Empt y) ;

El ement Li st Xml Hel per . AddEl ement Node(xml ,"Gi venName" ,

thi s. Sect i onI d,st r i ng. Empty,thi s. per sonEnt r y. Sel ect edPer son ! = nul l ?

thi s. per sonEnt r y. Sel ectedPer son. Gi venName: st r i ng. Empt y);

El ement Li st Xml Hel per . AddEl ement Node(xml ," Ti t l e",t hi s. Sect i onI d,st r i ng. Empty,thi s. per sonEnt r y. Sel ect edPer son ! = nul l ?thi s. per sonEnt r y. Sel ectedPer son. Ti t l e :

s t r i ng. Empt y) ;

t hi s. RemoveAct i onCont r ol ( ) ;}

Creating an Office Word Building B lock for the Control

1. To create a reusable Office Word

building block, open the

CDSABuildingBlocks.dotx

template file found in the

WordAddinproject


37/74

Microsoft

Page 33





2. CDSABuildingBlocks.dotx

contains all of the building blocks

for each of the controls.

Each control layout is on a

separate page in the document.To change a layout, edit it in these

pages and then update the

building blocks collection held

within the template.

3. At the end of the document:

1.Add a new page for the new

control

2.Add the control title: Person

Field3. Click the CDSA Developertab

(if it is not on view, access it

through the CDSA Usertab as

described in section2.7).

The next steps in creating the

building block use options on the

CDSA Developerribbon and the

Office Word Developerribbon.

Sections3and4describe the use

of both sets of options.

4. Insert a Section Partfrom the

Custom Parts Gallery.

5. Add some paragraphs to create

some space and insert anAct ion

Control Insertion Partfrom the

Custom Parts Gallery

6. Add a table with these features:

Three rows and two columns

Table width = AutoFit Contents

Labels in the left column


38/74

Microsoft

Page 34





7. Open the Office WordDeveloper

ribbon and in each cell of the

second column:

1. Insert a Plain Text Content

Control

2. Select Properties from the

Developerribbon

3. Enter the title for the content

control and check the

Contents cannot be edited

box

8. Click Design Modeand enter

watermark prompt text in each

content control.

When done, click Design Mode

to exit and open the CDSA

Developerribbon again

9. Add an edit button insertion point

by following these steps:

1. Position the cursor below the

table

2. Right-align the paragraph

3. Select Section Edit Button

Insertion Partfrom the

Custom Parts Gallery


39/74

Microsoft

Page 35





10. Click the Developer Properties

button to see your new control

listed.

Next you need to:

Set some default properties on

the control

Point the control at the

PersonField class created at

the beginning

11. Select the control name on the

Developer Propertiesscreen and

set the following values:

Section Id= Person Field

Section Edit Button Label =

Change

Section Control Assembly=

Microsoft.Consulting.OfficeToo

ls.Controls

Section Control Class=Microsoft.Consulting.OfficeToo

ls.Controls.PersonField.

Close the Developer Properties

screen.


40/74

Microsoft

Page 36





12. Ensure that the section

configuration gets used with this

building block by following these

steps:

1. Click on the section to select it


ribbon, click Properties

3. Enter a name in the Titlefield

that is the same as the Section

Id set in step11(Person

Field)

4. Click OK

13. Save the building block by

following these steps:

1. Open the Insertribbon

2. Click Quick Parts

3. Select Save selection to

Quick Part Gallery


41/74

Microsoft

Page 37





14. Complete the Create New

Building Blockfields as follows:

Name A unique and

meaningful name (in this case,

Person Field)

Gallery For consistency, add

CDSA building blocks to the

Custom 1gallery

Category As this is a new

section control, select Section

Save in Select


Note

Often, Save inlists two


items. Select the top onehere. The second is

overwritten every time the

project is built.

15. Save the CDSA building blocks

template and your new control is

ready to use. If you run the

project, you can test the control in

a document.

Testing the New Control in a CDSA Document

1. To test your new control, follow

these steps:

1. Open a new document in

Office Word

2. Open the CDSA Developer

ribbon

3. Click Convert to Clinical

Document

4. Click Section Gallery. You

can see that Person Fieldis

now an option

5. Select Person Fieldto insert it

into the document.


42/74

Microsoft

Page 38





2. The display shows the Person

Field layout, including the Change

button

3. Clicking Changecauses the WPF

control to appear and you can

search for a person

4. Having found a match, click Save

to select the person

5. CDSA inserts the persons details

into the document

Clicking Changedisplays the

WPF control again to allow

another search and clicking Save

again updates the selection

Table 8: Creating a WPF-Based Control


43/74

Microsoft

Page 39




7 CREATING A WPF-BASED LIST CONTROL

7.1 Introduction

Section6 covered how to create a simple WPF-based section control. This section covers the

creation of a basic list control to input values using the same WPF control (a person-lookup

control).

Important

As in Section6,the example shows how to include an existing WPF control into the CDSA controlgallery. It does not cover how to create a WPF-based control from first principles. To learn more about

creating WPF-based controls, consult the relevant articles on the Microsoft Developer Network

(MSDN) Web site. In addition, you can find WPF controls in the MSCUI Controls Toolkit8

For further guidance, look at the code for some of the CDSA controls. For example, after inserting aWPF control into a document, CDSA controls also listen for a number of events raised by Office Word

(such as BeforeSave, BeforePrint and SelectionChanged)in order to remove the WPF control from

the document if necessary. It is good practice to follow a similar pattern for all controls based on WPF

or on other .NET Framework controls.

.

Figure 4 shows how such a control might work:

Figure 4: How the WPF-Based List Control Might Work

8Available fromwww.mscui.net
http://www.mscui.net/http://www.mscui.net/http://www.mscui.net/http://www.mscui.net/


44/74

Microsoft

Page 40




Figure 4 shows the controls sequence of operation:

1. The section in the document shows that no one has yet been selected. It contains anAdd

Personbutton

2. Clicking theAdd Person button causes the WPF control to appear in the section

3. Entering a name and clicking the Searchbutton presents a list of search results, where aresult can be selected

4. Clicking the Savebutton removes the WPF control and adds the selected persons details

to a new table row in the document. CDSA appends a Deletebutton to allow the row to be

removed later

To create this control, you need to take these steps:

Add a new section control in the CDSA Visual Studio solution

Create an Office Word building block for the control

Create another building block to represent a row within the table

Test the new control in a CDSA document

7.2 Creating the WPF-Based List Control

Table 5 shows the steps required to create a WPF-based list control:


Adding a New Section Control to the Visual Stud io Solut ion

1. In Visual Studio, open the CDSA

Solution, and expand the

Microsoft.Consulting.OfficeTool

s.Controlsproject.In the example, the custom WPF

control namedPersonEntryhas

already been added to the

solution and is present in the WPF

folder.

The default style and templates

are already present in the

Generic.xaml file located in the

Themes folder


45/74

Microsoft

Page 41





2. Create a new class called

PersonList for the new section

control in theSectionControls

folder

3. Make thePersonListclass inherit

the providedSectionListBase

class.

TheSectionListBaseclass

inherits SectionBaseand adds

virtual methods that are useful

when working with list controls.

These include methods for

populating the lines collection as

the control loads and for adding,

editing or deleting a line in thetable.

Note

For security reasons, all

sections must derive from

SectionBase to prevent

execution of code not related

to the CDSA solution

namespace Mi crosof t . Consul t i ng. Of f i ceTool s. Cont rol s{

cl ass Per sonLi st : Sect i onLi st Base{}

}

4. Add the following private fields to

the class:

Wrapper of type

Microsoft.Office.Tools.Word.OLEControl

PersonEntry of type

PersonEntry

Host of typeElementHost

/ / / / / / St ores t he cont r ol wr apper./ / / pri vate Mi crosof t . Of f i ce. Tool s. Word. OLECont r ol wr apper ;

/ / / / / / The person ent r y cont r ol ./ / / pri vate Per sonEnt r y personEnt r y;

/ / / / / / The WPF el ement host ./ / /

pri vate El ement Host host ;


46/74

Microsoft

Page 42





5. Create an override for the

Initializemethod by adding the

code shown opposite. This adds a

custom configuration value for the

watermark in the search field

publ i c overr i de voi d I ni t i al i ze(Mi crosof t . Of f i ce. I nt er op. Word. Cont ent Cont r ol cont ent Cont r ol ){

base. I ni t i al i ze(contentCont r ol ) ;i f ( s t r i ng. I sNul l Or Empt y(

t hi s. GetConf i gur ati onVal ue("Wat er mar k" ) ) ){

t hi s. AddConf i gur ati onI t em("Wat er mar k" ,"Ent er a search f or a per son" ) ;

}

}

6. Before inserting the WPF control,

check if the WPF control is not

already in the document and also

check that an action control

insertion point was found within

the section.

If both checks are OK, go ahead

and insert the WPF control into

the ActionControlInsertionPoint:

1. If necessary, create an

instance of thepersonEntry

control. Add handlers to the

Saveand Canceledevents

2. Update the Watermark

property to use the value

specified in the custom

configuration

3. Host the WPF control in a

WinForms control (Office Word

does not support WPF contentdirectly in a document)

4. Create an instance of an

ElementHost and set the

background colour to white

5. Set the LockContents

property to falseto enable

insertion of the control.

6. Insert the ElementHost into the

document. The personEntry

control methods set the size at

insertion. The method returns

the wrapper that Office Worduses to host the control. Store

this locally to allow deletion of

the wrapper when the control

is removed from the

document.

7.Add the personEntry control as

a child

8. Lock the action control

insertion point

pr i vate voi d I nsert Acti onCont r ol ( ){

i f ( t hi s. wr apper == nul l &&t hi s. Acti onCont r ol I nsert i onPoi nt ! = nul l )

{i f ( t hi s. per sonEnt r y == nul l ){

t hi s. per sonEnt r y = new Per sonEnt r y( ) ;t hi s. per sonEnt r y. Saved +=

new Event Handl er ( personEntr y_Saved) ;t hi s. per sonEnt r y. Cancel ed +=

new Event Handl er ( personEntr y_Cancel ed) ;}

t hi s. per sonEnt r y. Wat ermark =t hi s. GetConf i gurat i onVal ue("Wat er mar k" ) ;

t hi s. host = new El ement Host ( ) ;t hi s. host . BackCol or = Syst em. Dr awi ng. Col or . Whi t e;

t hi s. Act i onCont r ol I nsert i onPoi nt . LockCont ent s =f a l s e;t hi s. wr apper =

Mi crosof t . Of f i ce. Tool s. Word. Extensi ons. DocumentExtensi ons. Get Vst oObj ect (

t hi s. Act i onCont r ol I nsert i onPoi nt . Range. Document ) . Cont r ol s. AddCont r ol (

t hi s. host ,t hi s. Acti onCont rol I nsert i onPoi nt . Range,t hi s. personEntr y. Desi r edWi dth,t hi s. personEnt r y. Desi r edHei ght ,s t r i ng. For mat(

Syst em. Gl obal i zati on. Cul t ureI nf o. Cur rent Cul t ure,"{0}_PersonEnt r y_{1}" , t hi s. Sect i onI d,

Secti onLi st Xml Hel per. Get Uni queI dent i f i er( ) ) ) ;t hi s. host . Chi l d = t hi s. personEnt r y;t hi s. Act i onCont r ol I nsert i onPoi nt . LockCont ent s =

true;}

}


47/74

Microsoft

Page 43





7. Create a new method called

RemoveActionControl.

This method:

1. Deletes the wrapper control

from the document

2. Unlocks the action control

insertion point

3. Sets the range text to empty to

clear out the content control

4. Locks the action control

insertion point again

pr i vate voi d RemoveAct i onCont r ol ( ){

i f ( t hi s. wr apper ! = nul l ){

t hi s. wrapper. Del et e( ) ;

t hi s. wr apper = nul l ;}

i f ( t hi s. host ! = nul l ){

t hi s. host . Chi l d = nul l ;}

t hi s. Act i onCont r ol I nsert i onPoi nt . LockCont ent s = f al s e;t hi s. Act i onCont r ol I nsert i onPoi nt . Range. Text =

st r i ng. Empty;t hi s. Act i onCont r ol I nsert i onPoi nt . LockCont ent s = true;

}

8. Create an override for the

HandleAddButtonClickmethod

that gets called when theAdd button is clicked. Add a call to

InsertActionControlto add the

WPF control into the document

pr ot ect ed overr i de voi d Handl eAddButt onCl i ck( ){

base. Handl eAddBut t onCl i ck() ;t hi s. I nsert Act i onCont rol ( ) ;

}


personEntry_Canceled (if it does

not already exist) and call


the WPF control from the

document without creating a line

voi d per sonEnt r y_Cancel ed( obj ect sender, Event Ar gs e){

t hi s. RemoveAct i onCont r ol ( ) ;

}


personEntry_Saved (if it does

not already exist) and add a call tothe CreateSectionLinemethod to

create a new SectionLine in the

table:

Specify sectionLineId as null

so that CDSA will create a

randomly generated line id

Specify

SectionLineBuildingBlockNa

me as this is the name of the

building block that represents

a line for the table

Thedefault implementation ofCreateSectionLinemethod found

in the SectionListBaseclass

checks that the table for insertion

exists, adds a row at the bottom of

the table and inserts the line

building block into the row

voi d per sonEnt r y_Saved(obj ect sender, Event Ar gs e){

Sect i onLi neBase sect i onLi ne =t hi s. Cr eat eSect i onLi ne(nul l ,t hi s. Secti onLi neBui l di ngBl ockName);

}


48/74

Microsoft

Page 44





11. Include these additions in the

personEntry_Saved event

handler:

1.Add code to add the line data

to the native data XML

2.Add a call toCreateBindings

for the sectionLineinstance

This finds all plain text content

controls in the line and binds

them to the native data XML

using the section ID, the

section line ID and the content

control title.

3.Add a call toInsertControls

for the sectionLineinstance

to add an edit and delete

button for the line, if required4.Add the sectionLineinstance

to the controls SectionLines

collection

5. CallRemoveActionControlto

remove the WPF control from

the document

voi d per sonEnt r y_Saved(obj ect sender, Event Ar gs e){

Sect i onLi neBase sect i onLi ne =t hi s. Cr eat eSect i onLi ne(nul l ,t hi s. Secti onLi neBui l di ngBl ockName);

i f ( sect i onLi ne != nul l ){

Of f i ce. Core. Cust omXMLPar t xml =El ement Li