XForms Module Use Cases

I'm adding new patients using XForms. How do I set predefined data such as addresses (city, county, etc)?

One way is to use the "external source" property in any text widget. Let's say you've created a table in your OpenMRS database called "address" containing the following fields:

state	county	city
MyProvince	MyRegion	MyTown
MyProvince	OtherRegion	OtherTown
MyOtherProvince	RegionBA	Exampleville

...and filled it with real data. State, County and City are Patient attributes that come by default in OpenMRS, so there is no need to create them. Now in each widget add the following:

	State/Province	County/District	City/Village
External source	address	address	address
Display field	state	county	city
Value field	state	county	city
Filter field		state	county

Having done this, you would obtain something like this:

As you can probably guess, Provincia, Partido and Ciudad are Spanish for Province, County and City. Gaiman only exists in the Chubut province and Bryn Gwyn only exists in Gaiman county.

I want to associate a variable amount of concepts to a field, say add findings to an EEG. How do I do that?

One possible way is to use a repeat section associated to a ConvSet (Convenience set) of concepts. In this example, we'll create a ConvSet with two fields: a coded concept and a text concept for use as a comment. The steps are:

Create a text concept.
Create a coded concept and either
1. set the possible answers by hand (let's say TUMOR and NONE)
2. leave it without answers. This way, we can set the possible answers using a similar method to the above Province/State/County address example. This is the one we'll use for this example.
Create a ConvSet class concept, type N/A, make it a set (by checking the "Is Set" ckeckbox) and add the concepts you created in 1 and 2 as set members. Make sure the ConvSet is of type N/A.
Go to your form's schema and add the ConvSet you've just created to the OBS section. In the Max value write -1, so the XForm Designer will automatically create a repeat box for you with the members of your set. Make sure you add the concept in the OBS section, otherwise the repeat box will not be created.

In this example, "HALLAZGOS EEG SET" is the ConvSet concept, with HALLAZGO EEG and COMENTARIO HALLAZGO EEG as members of the set. Once in the XForm Designer, you'll see something like this:

The first field looks kind of useless for now. It stores concepts ids as answers yet is has no answers loaded.Let's have it choose from all the concepts listed in OpenMRS with the class "findings".
Set it's External Source field to:

select distinct cn.name, concat(cn.concept_id,concat(concat('^',name),'^99DCT'))
as concept_id from concept_name cn inner join concept c on c.concept_id=cn.concept_id
where class_id=5

Why all that huge select instead of just writing "concept"?

Concept names are stored in another separate table, called concept_names, hence the inner join.
The concept_id field (present in both tables), is just a number (E.g: for "HALLAZGO EEG" it's 6252), yet it is not what it is stored in the coded concept. What needs being stored is the HL7 version of the concept, that is "6252^HALLAZGO EEG^99DCT", hence all the concats.
The "where class_id=5" clause selects only the concepts that are findings. Just change the number to display other classes (1=Test, 2=Procedure, 3=Drug, 4=Diagnosis, 6=Finding, 7=Anatomy, and so on, following the same order in which they are listed while creating a concept from the Dictionary)

Also set the Value Field to: "concept_id" and Display Field to: "name".

Also, to make that text concept better suited for multi-lined comments, let's replace that text box with a text area. Just remember to re-bind the text area to the comment concept. Text area widgets are also resizable in real time.

Note: if you're experiencing layout problems (in the design view the text area is placed right of the coded concept but in the preview it appears to the left), change the tab indexes of both widgets to a non-zero value. (E.g, 1 and 2)

And there you go!

Alternative method

Since version 4.0.8.1 of the XForms module, there is an easier and faster method for concept suggestions in text widgets. Just set
External Source = "concept"
leaving Display and Value parameters empty.

This method, in spite of it's (current) lack of flexibility, is much faster than the previous. Users with large concept databases are encouraged to use it, and shall certainly note the difference.

. |
|