Skip to content

Latest commit

 

History

History
61 lines (41 loc) · 2.74 KB

suite_generation.rst

File metadata and controls

61 lines (41 loc) · 2.74 KB
Raw

The Suite

An application's suite.xml file controls its structure.

The full XML spec for the suite is availabe on the commcare-core wiki.

Overview

Suite generation starts with Application.create_suite, which delegates to SuiteGenerator.

Suite generation is organized based on its major XML elements: resources, entries, details, etc. The suite is generated in two passes:

  1. corehq.apps.app_manager.suite_xml.sections generates independendent parts. A "section" is one of the major elements that goes into the suite: resources, entries, details, etc. This logic relies on the app document itself.
  2. corehq.apps.app_manager.suite_xml.post_process handles logic that depends on the first pass being complete. Some of this logic adds new elements, some manipulates existing elements. This logic relies on the app document and also on the XML models generated by the first pass. Anything that deals with stacks must be a post processor, to guarantee that all menus have already been generated.

Challenges for developers in suite generation code:

  • Language mixes CommCare concepts, such as "datum" and "menu", with HQ concepts, such as "modules"
  • Lots of branching
  • Has evolved one feature at a time, sometimes without attention to how different features interact
  • CommCare's suite spec supports plenty of behavior that HQ doesn't allow the app builder to configure. In some areas, 20% of the HQ logic handles 80% of what's actually supported, so the code is more complex than the developer might expect. As an example of this, the suite code generally supports an arbitrary number of datums per form, even though the vast majority of forms only require one or two cases.

A bright spot: test coverage for suite generation is good, and adding new tests is typically straightforward.

Sections

.. automodule:: corehq.apps.app_manager.suite_xml.sections.details


.. automodule:: corehq.apps.app_manager.suite_xml.sections.entries


.. automodule:: corehq.apps.app_manager.suite_xml.sections.fixtures


.. automodule:: corehq.apps.app_manager.suite_xml.sections.menus


.. automodule:: corehq.apps.app_manager.suite_xml.sections.resources

Post Processors

.. automodule:: corehq.apps.app_manager.suite_xml.post_process.endpoints


.. automodule:: corehq.apps.app_manager.suite_xml.post_process.instances


.. automodule:: corehq.apps.app_manager.suite_xml.post_process.menu


.. automodule:: corehq.apps.app_manager.suite_xml.post_process.remote_requests


.. automodule:: corehq.apps.app_manager.suite_xml.post_process.resources


.. automodule:: corehq.apps.app_manager.suite_xml.post_process.workflow