Building CommCare Apps from Handwritten XForms

Dear CommCare Users,

While most common use cases can be addressed using the form designer and
other tools in the ‘Applications’ section of www.commcarehq.org, some
advanced users might prefer to circumvent these tools and work directly in
the raw XML. If you are one of these people, and are comfortable writing
CommCare XForms by hands, there are now two ways to go about this. Both
features are in ‘alpha’ release, so please let us know if you encounter any
bugs or have any suggestions.

Remote App: If you want full control over the xforms and are also
comfortable writing your own CaseXML (i.e. suite and profile
files)https://bitbucket.org/commcare/commcare/wiki/Hometo specify
the flow of menus and lists, then you can use the RemoteApp
feature. To do so:

  1. Go to the ‘Applications’ section of www.commcarehq.org
  2. Select the ‘Change Apps’ pull down
  3. Click ‘New Application’ and then ‘Remote App (Advanced Users Only)’
  4. Under the ‘Remote Setup’ section of your App, you’ll need to specify
    the raw download URL for your profile.xml. For example:
    <goog_2007135387>
    http://bitbucket.org/commcare/commcare-apps/raw/0f5b7c2e218b/commcare-pf/profile.xml(Note
    the
    raw in the URL).
  5. Now from the ‘Release Manager’ section, you can ‘make new builds’,
    download them onto a phone, and run them just like any other CommCare App.

Careful! Every time you update your bitbucket repo, for now, you’ll need to
*update the raw download URL, *since currently this URL is only available
for specific commits.

Upload XForm: If you want to write the XForm by hand, but continue to use
www.commcarehq.org to handle the application management (settings, menus,
select screens, etc.) you can do this by uploading your xforms instead of
using the form designer.

  1. Under ‘Applications’ -> ‘Structure and Configuration’, when you add a
    new form, instead of clicking ‘Create’ after ‘Edit XForm’, click ‘Upload
    Xform’. You will be able to upload the xform xml file directly.

Careful! Any case information in this XForm will be ignored. CommCareHQ
itself will handle the configuration of cases, referrals, menus, profiles,
suites, etc. (under ‘structure and configuration’). Of course, there are
dependencies between the questions and answers the xform and the case
information which www.commcarehq.org handles. Be careful not to remove
references in your XForm which CommCareHQ relies on to generate or
manipulate cases.

As always, please let us know of any suggestions you have about these
features, or any bugs that might come up.

Cheers,

Rowena

To elaborate, a custom uploaded XForm can have a case block, and HQ will
not touch it unless you use the online interface to configure cases. If you
do, it will delete the case block in the form and write its own.

Danny

··· 2011/5/25 Rowena Luk

Dear CommCare Users,

While most common use cases can be addressed using the form designer and
other tools in the ‘Applications’ section of www.commcarehq.org, some
advanced users might prefer to circumvent these tools and work directly in
the raw XML. If you are one of these people, and are comfortable writing
CommCare XForms by hands, there are now two ways to go about this. Both
features are in ‘alpha’ release, so please let us know if you encounter any
bugs or have any suggestions.

Remote App: If you want full control over the xforms and are also
comfortable writing your own CaseXML (i.e. suite and profile files)https://bitbucket.org/commcare/commcare/wiki/Hometo specify the flow of menus and lists, then you can use the RemoteApp
feature. To do so:

  1. Go to the ‘Applications’ section of www.commcarehq.org
  2. Select the ‘Change Apps’ pull down
  3. Click ‘New Application’ and then ‘Remote App (Advanced Users Only)’
  4. Under the ‘Remote Setup’ section of your App, you’ll need to specify
    the raw download URL for your profile.xml. For example:
    http://goog_2007135387
    http://bitbucket.org/commcare/commcare-apps/raw/0f5b7c2e218b/commcare-pf/profile.xml(Note the
    raw in the URL).
  5. Now from the ‘Release Manager’ section, you can ‘make new builds’,
    download them onto a phone, and run them just like any other CommCare App.

Careful! Every time you update your bitbucket repo, for now, you’ll need to
*update the raw download URL, *since currently this URL is only available
for specific commits.

Upload XForm: If you want to write the XForm by hand, but continue to
use www.commcarehq.org to handle the application management (settings,
menus, select screens, etc.) you can do this by uploading your xforms
instead of using the form designer.

  1. Under ‘Applications’ -> ‘Structure and Configuration’, when you add
    a new form, instead of clicking ‘Create’ after ‘Edit XForm’, click ‘Upload
    Xform’. You will be able to upload the xform xml file directly.

Careful! Any case information in this XForm will be ignored. CommCareHQ
itself will handle the configuration of cases, referrals, menus, profiles,
suites, etc. (under ‘structure and configuration’). Of course, there are
dependencies between the questions and answers the xform and the case
information which www.commcarehq.org handles. Be careful not to remove
references in your XForm which CommCareHQ relies on to generate or
manipulate cases.

As always, please let us know of any suggestions you have about these
features, or any bugs that might come up.

Cheers,

Rowena

Fyi, the information in this email has also been updated on the wiki,
available at:
https://wiki.commcarehq.org/display/commcarepublic/Handwritten+XForms

··· On Wed, May 25, 2011 at 9:12 PM, Rowena Luk wrote:

Dear CommCare Users,

While most common use cases can be addressed using the form designer and
other tools in the ‘Applications’ section of www.commcarehq.org, some
advanced users might prefer to circumvent these tools and work directly in
the raw XML. If you are one of these people, and are comfortable writing
CommCare XForms by hands, there are now two ways to go about this. Both
features are in ‘alpha’ release, so please let us know if you encounter any
bugs or have any suggestions.

Remote App: If you want full control over the xforms and are also
comfortable writing your own CaseXML (i.e. suite and profile files)https://bitbucket.org/commcare/commcare/wiki/Hometo specify the flow of menus and lists, then you can use the RemoteApp
feature. To do so:

  1. Go to the ‘Applications’ section of www.commcarehq.org
  2. Select the ‘Change Apps’ pull down
  3. Click ‘New Application’ and then ‘Remote App (Advanced Users Only)’
  4. Under the ‘Remote Setup’ section of your App, you’ll need to specify
    the raw download URL for your profile.xml. For example:
    http://goog_2007135387
    http://bitbucket.org/commcare/commcare-apps/raw/0f5b7c2e218b/commcare-pf/profile.xml(Note the
    raw in the URL).
  5. Now from the ‘Release Manager’ section, you can ‘make new builds’,
    download them onto a phone, and run them just like any other CommCare App.

Careful! Every time you update your bitbucket repo, for now, you’ll need to
*update the raw download URL, *since currently this URL is only available
for specific commits.

Upload XForm: If you want to write the XForm by hand, but continue to
use www.commcarehq.org to handle the application management (settings,
menus, select screens, etc.) you can do this by uploading your xforms
instead of using the form designer.

  1. Under ‘Applications’ -> ‘Structure and Configuration’, when you add
    a new form, instead of clicking ‘Create’ after ‘Edit XForm’, click ‘Upload
    Xform’. You will be able to upload the xform xml file directly.

Careful! Any case information in this XForm will be ignored. CommCareHQ
itself will handle the configuration of cases, referrals, menus, profiles,
suites, etc. (under ‘structure and configuration’). Of course, there are
dependencies between the questions and answers the xform and the case
information which www.commcarehq.org handles. Be careful not to remove
references in your XForm which CommCareHQ relies on to generate or
manipulate cases.

As always, please let us know of any suggestions you have about these
features, or any bugs that might come up.

Cheers,

Rowena

Danny, can you explain how to use HQ while not using the online interface to configure cases?

Thanks

··· Sent from my iPhone

On May 26, 2011, at 9:25 AM, Daniel Roberts droberts@dimagi.com wrote:

To elaborate, a custom uploaded XForm can have a case block, and HQ will not touch it unless you use the online interface to configure cases. If you do, it will delete the case block in the form and write its own.

Danny

2011/5/25 Rowena Luk rluk@dimagi.com
Dear CommCare Users,

While most common use cases can be addressed using the form designer and other tools in the ‘Applications’ section of www.commcarehq.org, some advanced users might prefer to circumvent these tools and work directly in the raw XML. If you are one of these people, and are comfortable writing CommCare XForms by hands, there are now two ways to go about this. Both features are in ‘alpha’ release, so please let us know if you encounter any bugs or have any suggestions.

Remote App: If you want full control over the xforms and are also comfortable writing your own CaseXML (i.e. suite and profile files) to specify the flow of menus and lists, then you can use the RemoteApp feature. To do so:
Go to the ‘Applications’ section of www.commcarehq.org
Select the ‘Change Apps’ pull down
Click ‘New Application’ and then 'Remote App (Advanced Users Only)'
Under the ‘Remote Setup’ section of your App, you’ll need to specify the raw download URL for your profile.xml. For example: http://bitbucket.org/commcare/commcare-apps/raw/0f5b7c2e218b/commcare-pf/profile.xml (Note the raw in the URL).
Now from the ‘Release Manager’ section, you can ‘make new builds’, download them onto a phone, and run them just like any other CommCare App.
Careful! Every time you update your bitbucket repo, for now, you’ll need to update the raw download URL, since currently this URL is only available for specific commits.

Upload XForm: If you want to write the XForm by hand, but continue to use www.commcarehq.org to handle the application management (settings, menus, select screens, etc.) you can do this by uploading your xforms instead of using the form designer.

Under ‘Applications’ -> ‘Structure and Configuration’, when you add a new form, instead of clicking ‘Create’ after ‘Edit XForm’, click ‘Upload Xform’. You will be able to upload the xform xml file directly.
Careful! Any case information in this XForm will be ignored. CommCareHQ itself will handle the configuration of cases, referrals, menus, profiles, suites, etc. (under ‘structure and configuration’). Of course, there are dependencies between the questions and answers the xform and the case information which www.commcarehq.org handles. Be careful not to remove references in your XForm which CommCareHQ relies on to generate or manipulate cases.

As always, please let us know of any suggestions you have about these features, or any bugs that might come up.

Cheers,

Rowena

Hi All,

I just wanted to add a litte bit more about bitbucket. Rowena/Danny,
can you confirm that this will work? (Not sure exactly what your code
is doing)

If you’re very careful when you set it up, you don’t have to update
the raw URL every time you update your repository. The key is to use
the name of a tag or branch in the url instead of the hash. For
example, instead of

http://bitbucket.org/commcare/commcare-apps/raw/0f5b7c2e218b/commcare-pf/profile.xml

you can use:

http://bitbucket.org/commcare/commcare-apps/raw/tip/commcare-pf/profile.xml

Or you can use the name of a branch. For example:

https://bitbucket.org/javarosa/javarosa/raw/mediasupport/.hgignore

However, you need to be extra careful when do things this way. Make
sure you know what “tip” means
(http://mercurial.selenic.com/wiki/Tip). Specifically, that it is
independent of the branch or head.

Hope that helps simplify bitbucket integration!

Brian

··· On Thu, May 26, 2011 at 8:03 AM, Rowena Luk wrote: > Fyi, the information in this email has also been updated on the wiki, > available at: > https://wiki.commcarehq.org/display/commcarepublic/Handwritten+XForms > > On Wed, May 25, 2011 at 9:12 PM, Rowena Luk wrote: >> >> Dear CommCare Users, >> >> While most common use cases can be addressed using the form designer and >> other tools in the 'Applications' section of www.commcarehq.org, some >> advanced users might prefer to circumvent these tools and work directly in >> the raw XML. If you are one of these people, and are comfortable writing >> CommCare XForms by hands, there are now two ways to go about this. Both >> features are in 'alpha' release, so please let us know if you encounter any >> bugs or have any suggestions. >> >> Remote App: If you want full control over the xforms and are also >> comfortable writing your own CaseXML (i.e. suite and profile files) to >> specify the flow of menus and lists, then you can use the RemoteApp feature. >> To do so: >> >> Go to the 'Applications' section of www.commcarehq.org >> Select the 'Change Apps' pull down >> Click 'New Application' and then 'Remote App (Advanced Users Only)' >> Under the 'Remote Setup' section of your App, you'll need to specify the >> raw download URL for your profile.xml. For example: >> http://bitbucket.org/commcare/commcare-apps/raw/0f5b7c2e218b/commcare-pf/profile.xml >> (Note the raw in the URL). >> Now from the 'Release Manager' section, you can 'make new builds', >> download them onto a phone, and run them just like any other CommCare App. >> >> Careful! Every time you update your bitbucket repo, for now, you'll need >> to update the raw download URL, since currently this URL is only available >> for specific commits. >> >> Upload XForm: If you want to write the XForm by hand, but continue to use >> www.commcarehq.org to handle the application management (settings, menus, >> select screens, etc.) you can do this by uploading your xforms instead of >> using the form designer. >> >> Under 'Applications' -> 'Structure and Configuration', when you add a new >> form, instead of clicking 'Create' after 'Edit XForm', click 'Upload Xform'. >> You will be able to upload the xform xml file directly. >> >> Careful! Any case information in this XForm will be ignored. CommCareHQ >> itself will handle the configuration of cases, referrals, menus, profiles, >> suites, etc. (under 'structure and configuration'). Of course, there are >> dependencies between the questions and answers the xform and the case >> information which www.commcarehq.org handles. Be careful not to remove >> references in your XForm which CommCareHQ relies on to generate or >> manipulate cases. >> >> As always, please let us know of any suggestions you have about these >> features, or any bugs that might come up. >> >> Cheers, >> >> Rowena > >

Hmm, that’s interesting, Brian. Right now it won’t work because commcare hq
expects you to change something before allowing you to save another build.
If this is a workflow that people want, though, I could change the way that
works.

Cheers,
Danny

Hi All,

I just wanted to add a litte bit more about bitbucket. Rowena/Danny,
can you confirm that this will work? (Not sure exactly what your code
is doing)

If you’re very careful when you set it up, you don’t have to update
the raw URL every time you update your repository. The key is to use
the name of a tag or branch in the url instead of the hash. For
example, instead of

http://bitbucket.org/commcare/commcare-apps/raw/0f5b7c2e218b/commcare-pf/profile.xml
you can use:

http://bitbucket.org/commcare/commcare-apps/raw/tip/commcare-pf/profile.xml

Or you can use the name of a branch. For example:

https://bitbucket.org/javarosa/javarosa/raw/mediasupport/.hgignore

However, you need to be extra careful when do things this way. Make
sure you know what “tip” means
(http://mercurial.selenic.com/wiki/Tip). Specifically, that it is
independent of the branch or head.

Hope that helps simplify bitbucket integration!

Brian

··· On May 26, 2011 9:53 PM, "Brian DeRenzi" wrote:

On Thu, May 26, 2011 at 8:03 AM, Rowena Luk rluk@dimagi.com wrote:

Fyi, the information in th…

Ok, good to clear that up. Thanks Danny.

··· On Thu, May 26, 2011 at 8:36 PM, Daniel Roberts wrote: > Hmm, that's interesting, Brian. Right now it won't work because commcare hq > expects you to change something before allowing you to save another build. > If this is a workflow that people want, though, I could change the way that > works. > > Cheers, > Danny > > On May 26, 2011 9:53 PM, "Brian DeRenzi" wrote: > > Hi All, > > I just wanted to add a litte bit more about bitbucket. Rowena/Danny, > can you confirm that this will work? (Not sure exactly what your code > is doing) > > If you're very careful when you set it up, you don't have to update > the raw URL every time you update your repository. The key is to use > the name of a tag or branch in the url instead of the hash. For > example, instead of > > http://bitbucket.org/commcare/commcare-apps/raw/0f5b7c2e218b/commcare-pf/profile.xml > > you can use: > > http://bitbucket.org/commcare/commcare-apps/raw/tip/commcare-pf/profile.xml > > Or you can use the name of a branch. For example: > > https://bitbucket.org/javarosa/javarosa/raw/mediasupport/.hgignore > > However, you need to be extra careful when do things this way. Make > sure you know what "tip" means > (http://mercurial.selenic.com/wiki/Tip). Specifically, that it is > independent of the branch or head. > > Hope that helps simplify bitbucket integration! > > Brian > > > > On Thu, May 26, 2011 at 8:03 AM, Rowena Luk wrote: >> Fyi, the information in th...

I do not see a structure and configuration option under applications. Is this information still relevant to the current version. I have handwritten xforms that I want to import, how do I do this?

Hi Shawn,

If you create a “stub” form, you can then upload your XForm in to replace that one.

-Clayton