Accessing Locations from within a CommCare Supply form

For users already familiar with CommCare's conditional select functionality, referencing locations within a form is very similar.  To access the list of locations from within a CommCare Supply form, you can use the syntax described HERE.

Much like lookup tables in order to reference location data in a form, you must first include a reference to this instance in the forms xml.  To access this xml, enter your form, and in the top righthand corner, under "Tools", select "Edit Source XML"

You'll need to add the following line to the instances in order to reference location data:

<instance id="locations" src="jr://fixture/commtrack:locations"></instance>

Place this just above the first "<instance>" here:

Next you'll need to add a select question to the XML.

It should look something like: 

You can drill down to any level of location within this hierarchy by following this model.  For example, if your hierarchy starts at the regional level, then proceeds to state, then district, then outlet.  You can reference facilities like this:

If you'd like to select a location based on a previously selected location higher up in the location hierarchy, in this example select a facility only from a list of facilities that are in a district that you've already chosen, you can filter use the following XML:

Note that whenever referencing the location hierarchy, only locations with which a mobile user is associated will sync to that users phone.  So, if the mobile user account is linked to outlet 'a', then the only district that will appear on that users phone is the district to which outlet 'a' belongs, and the only state will be the state to which that district belongs.

UPDATE !

In order to set up a single of multiple answer questions on locations, follow these steps:

1. Add a Single/Multiple Answer Lookup Table:
   
2. Click on the "Lookup Table Data" question
   
   
3. Edit the following fields:
   1. Lookup Table: ignore that for now
   2. Value Field: what you want to save as an answer (usually an id or a code). For locations you can use site_code or @id.
   3. Label Field: what you want to display to the user. For locations you can use name
   4. (Optional) Filter: can be used to filter the locations displayed.
      
      
4. The tricky part is now to modify the xml to point the question to the location table. To do so:
   1. Click on Tools / Edit Source XML on the top right corner of the form builder:
      
   2. In the XML search for a select1 node holding your lookup question. It should look like this:
      
      
      In this example my lookup question is /data/location_loookup
   3. Then in the expression <itemset nodeset="instance('products')/products/product">, replace the instance with the instance of your location. For example
      1. if you want to display the list of states: instance('locations')/states/state
      2. if you want to display the list of districts of a previously selected state: instance('locations')/states/state[site_code=/data/state_selected]/districts/district
         where /data/state_selected is the state previously selected.