### Bad Example: Redundant setUpClass Execution

Source: https://commcarehq.readthedocs.io/en/latest/testing.html

Avoid running `setUpClass` multiple times for classes inheriting from the same base class if the setup operations are expensive. This can significantly slow down test execution.

```python
# BAD EXAMPLE

class MyBaseTestClass(TestCase):

    @classmethod
    def setUpClass(cls):
        ...


class MyTestClass(MyBaseTestClass):

    def test1(self):
        ...

class MyTestClassTwo(MyBaseTestClass):

    def test2(self):
        ...

```

--------------------------------

### Install coverage.py

Source: https://commcarehq.readthedocs.io/en/latest/test_coverage.html

Install the coverage.py library using pip. This is the first step to enable code coverage analysis.

```bash
$ pip install coverage

```

--------------------------------

### Install Grunt globally

Source: https://commcarehq.readthedocs.io/en/latest/js-guide/testing.html

Install grunt and grunt-cli globally for command-line access.

```bash
$ npm install -g grunt
$ npm install -g grunt-cli
```

--------------------------------

### Install dependencies

Source: https://commcarehq.readthedocs.io/en/latest/js-guide/testing.html

Install required npm packages using yarn.

```bash
$ yarn install --frozen-lockfile
```

--------------------------------

### Install and Run ESLint Locally

Source: https://commcarehq.readthedocs.io/en/latest/js-guide/linting.html

Install ESLint globally using npm and then run it on a specific file to check for errors and style issues.

```bash
# Install it through npm:
$ npm install -g eslint

# Try it out locally if you like
$ eslint path/to/file.js
```

--------------------------------

### Bulk User Resource Example Query

Source: https://commcarehq.readthedocs.io/en/latest/api.html

An example query string for the bulk user resource. It demonstrates how to use parameters like 'q', 'fields', 'limit', and 'offset' to filter and paginate results.

```http
?q=foo&fields=username&fields=first_name&fields=last_name&limit=100&offset=200

```

--------------------------------

### Example Static File Path with CDN

Source: https://commcarehq.readthedocs.io/en/latest/js-guide/static-files.html

This example shows how a static JavaScript file path is prefixed with a CDN URL during compilation for efficient delivery.

```html
<script src="/static/js/awesome.js"/>
```

--------------------------------

### Enable Production-like Setup for Static Files

Source: https://commcarehq.readthedocs.io/en/latest/js-guide/static-files.html

Configure `localsettings.py` to enable compression and offline processing. This setup closely mirrors production by compressing files offline, but requires re-running management commands and restarting the server after frontend changes.

```python
COMPRESS_ENABLED = True
COMPRESS_OFFLINE = True

```

--------------------------------

### General Install Declaration Format

Source: https://commcarehq.readthedocs.io/en/latest/js-guide/external-packages.html

The general format for specifying a Yarn package installation, including name, package, and version.

```text
<name>:<package>#<version>
```

--------------------------------

### Example: DemoReport extending SqlData

Source: https://commcarehq.readthedocs.io/en/latest/reporting.html

An example demonstrating how to extend the SqlData class to create a custom report, including defining columns, filters, and data formatting.

```APIDOC
## Example: DemoReport

### Description
This example shows a `DemoReport` class that extends `SqlTabularReport` and `CustomProjectReport`, utilizing `SqlData` properties to define a report querying user data.

### Class Definition
```python
class DemoReport(SqlTabularReport, CustomProjectReport):
    name = "SQL Demo"
    slug = "sql_demo"
    fields = ('corehq.apps.reports.filters.dates.DatespanFilter',)

    # The columns to include the the 'group by' clause
    group_by = ["user"]

    # The table to run the query against
    table_name = "user_report_data"

    @property
    def filters(self):
        return [
            BETWEEN('date', 'startdate', 'enddate'),
        ]

    @property
    def filter_values(self):
        return {
            "startdate": self.datespan.startdate_param_utc,
            "enddate": self.datespan.enddate_param_utc,
            "male": 'M',
            "female": 'F',
        }

    @property
    def keys(self):
        # would normally be loaded from couch
        return [["user1"], ["user2"], ['user3']]

    @property
    def columns(self):
        return [
            DatabaseColumn("Location", SimpleColumn("user_id"), format_fn=self.username),
            DatabaseColumn("Males", CountColumn("gender"), filters=self.filters+[EQ('gender', 'male')],
            DatabaseColumn("Females", CountColumn("gender"), filters=self.filters+[EQ('gender', 'female')],
            AggregateColumn(
                "C as percent of D",
                self.calc_percentage,
                [SumColumn("indicator_c"), SumColumn("indicator_d")],
                format_fn=self.format_percent)
        ]

    _usernames = {"user1": "Location1", "user2": "Location2", 'user3": "Location3"}  # normally loaded from couch
    def username(self, key):
        return self._usernames[key]

    def calc_percentage(num, denom):
        if isinstance(num, Number) and isinstance(denom, Number):
            if denom != 0:
                return num * 100 / denom
            else:
                return 0
        else:
            return None

    def format_percent(self, value):
        return format_datatables_data("%d%%" % value, value)
```

### Key Components Explained
- **`name` and `slug`**: Define the report's display name and unique identifier.
- **`fields`**: Specifies available filters, like `DatespanFilter`.
- **`group_by`**: Defines columns for the SQL `GROUP BY` clause.
- **`table_name`**: The source table for the query.
- **`filters`**: Returns a list of `SqlFilter` objects, here using `BETWEEN` for dates.
- **`filter_values`**: Provides values for filters, dynamically using `self.datespan`.
- **`keys`**: Specifies expected rows, useful for adding missing data rows.
- **`columns`**: Defines the report columns using `DatabaseColumn` and `AggregateColumn`, including custom formatting functions (`username`, `calc_percentage`, `format_percent`).
```

--------------------------------

### SQL Model Example with Sync Mixins

Source: https://commcarehq.readthedocs.io/en/latest/couch_to_sql_models.html

Example of a generated SQL model class. It includes `db_table` for easier renaming and a column for the CouchDB document ID. If your model uses submodels, you'll need to override `_migration_sync_to_sql` and `_migration_sync_to_couch`. Beware that sync mixins capture exceptions, making bugs easy to miss.

```python
class SQLMyDocType(SyncCouchToSQLMixin, SyncSQLToCouchMixin):
    """SQL model for MyDocType"""
    couch_id = models.TextField(primary_key=True)
    # TODO: Add columns for other fields
    # Example:
    # name = models.TextField()
    # date_created = models.DateTimeField()

    class Meta:
        db_table = "my_doc_type"
```

--------------------------------

### Run Pillowtop processes

Source: https://commcarehq.readthedocs.io/en/latest/elasticsearch.html

Starts all Pillowtop processes to listen for changes and update ElasticSearch.

```bash
$ ./manage.py run_ptop --all
```

--------------------------------

### Handle GET and POST Requests in CommCare View

Source: https://commcarehq.readthedocs.io/en/latest/class_views.html

Implement specific logic for GET and POST requests within a CommCare view. The POST method can optionally redirect to a GET request.

```python
class MySectionPage(BaseSectionPageView):
    ...

    def get(self, request, *args, **kwargs):
        # do stuff related to GET here...
        return super(MySectionPage, self).get(request, *args, **kwargs)

    def post(self, request, *args, **kwargs):
        # do stuff related to post here...
        return self.get(request, *args, **kwargs)  # or any other HttpResponse object

```

--------------------------------

### Set Start Offset

Source: https://commcarehq.readthedocs.io/en/latest/es_query.html

Sets the starting offset for pagination, analogous to the `OFFSET` clause in SQL.

```python
start(_start_)
```

--------------------------------

### Constant Value Deserialization Example

Source: https://commcarehq.readthedocs.io/en/latest/_modules/corehq/motech/value_source.html

Demonstrates deserializing a constant value. The example shows how 'foo' is deserialized to 1.0, illustrating type casting during deserialization.

```python
>>> one = ConstantValue.wrap({
...     "value": 1,
...     "value_data_type": COMMCARE_DATA_TYPE_INTEGER,
...     "commcare_data_type": COMMCARE_DATA_TYPE_DECIMAL,
...     "external_data_type": COMMCARE_DATA_TYPE_TEXT,
... })
>>> info = CaseTriggerInfo("test-domain", None)
>>> one.deserialize("foo")
1.0
```

--------------------------------

### jQuery Usage Example

Source: https://commcarehq.readthedocs.io/en/latest/js-guide/libraries.html

Demonstrates how to select elements using jQuery. Prefix jQuery variables with '$'.

```javascript
var $rows = $("#myTable tr"),
    firstRow = $rows[0];
```

--------------------------------

### Performing Aggregate Queries

Source: https://commcarehq.readthedocs.io/en/latest/es_query.html

Example of how to use the CaseES query builder to perform a TermsAggregation to count cases by user.

```APIDOC
## Aggregate Query Example

### Description
Calculates how many cases of a specific type each user has opened within a defined date range using TermsAggregation.

### Request Example
```python
res = (CaseES()
       .domain(self.domain)
       .case_type('pregnancy')
       .date_range('opened_on', gte=startdate, lte=enddate))
       .aggregation(TermsAggregation('by_user', 'opened_by')
       .size(0))
```

### Response
- **aggregations** (object) - A namedtuple containing the wrapped aggregation results.
- **buckets** (object) - The specific bucket data for the aggregation, accessible via the name provided at instantiation.
```

--------------------------------

### Define a FormQuestion

Source: https://commcarehq.readthedocs.io/en/latest/openmrs.html

Example JSON structure for referencing a form question value using its path.

```json
{
  "form_question": "/data/foo/bar"
}
```

--------------------------------

### Knockout HTML Binding Example

Source: https://commcarehq.readthedocs.io/en/latest/js-guide/libraries.html

Illustrates Knockout bindings for HTML elements, using observable properties for visibility and value.

```html
<input data-bind="visible: type === 'large' && oTotal() > 10, value: oTotal" />

Current total: <span data-bind="text: oTotal"></div>
```

--------------------------------

### Define Module Dependencies

Source: https://commcarehq.readthedocs.io/en/latest/js-guide/migrating.html

Examples showing the transition from legacy hqImport calls to explicit RequireJS dependency arrays.

```javascript
hqDefine("app/js/utils", function() {
   var $this = $("#thing");
   hqImport("otherApp/js/utils").doSomething($thing);
   ...
});
```

```javascript
hqDefine("app/js/utils", [
   "jquery",
   "otherApp/js/utils"
], function(
   $,
   otherUtils
) {
   var $this = $("#thing");
   otherUtils.doSomething($thing);
   ...
});
```

--------------------------------

### Import custom code

Source: https://commcarehq.readthedocs.io/en/latest/extensions.html

Example import statement for code located within the custom namespace package.

```python
from custom.app1 models import *
```

--------------------------------

### Knockout Observable Example

Source: https://commcarehq.readthedocs.io/en/latest/js-guide/libraries.html

Shows how to define a Knockout model with an observable property. Prefix knockout observables with 'o'.

```javascript
var myModel = function (options) {
    var self = this;
    self.type = options.type;
    self.oTotal = ko.observable(0);
};
```

--------------------------------

### Extension point result formatting

Source: https://commcarehq.readthedocs.io/en/latest/extensions.html

Examples of default, flattened, and first-result return formats for extension points.

```python
> get_things(10, "seuss", True)
[["thing2", "thing1"], ["thing3", "thing4"]]
```

```python
@extensions.extension_point(result_format=ResultFormat.FLATTEN)
def get_things(...):
    pass

> get_things(...)
["thing2", "thing1", "thing3", "thing4"]
```

```python
@extensions.extension_point(result_format=ResultFormat.FIRST)
def get_things(...):
    pass

> get_things(...)
["thing2", "thing1"]
```

--------------------------------

### Constant Value Get Value Example

Source: https://commcarehq.readthedocs.io/en/latest/_modules/corehq/motech/value_source.html

Demonstrates getting the value of a ConstantValue. The example shows that '1.0' is returned, not '1', due to casting to commcare_data_type first.

```python
>>> one.get_value(info)  # Returns '1.0', not '1'. See note below.
'1.0'
```

--------------------------------

### Build Documentation Locally

Source: https://commcarehq.readthedocs.io/en/latest/documenting.html

Navigate to the docs/ directory and run 'make html' to build a local copy of the documentation for testing changes.

```bash
make html
```

--------------------------------

### Month Start Date Expression Configuration

Source: https://commcarehq.readthedocs.io/en/latest/_modules/corehq/apps/userreports/expressions/date_specs.html

Use this JSON structure to retrieve the first day of the month for a given date expression.

```json
{
    "type": "month_start_date",
    "date_expression": {
```

--------------------------------

### Good Example: Consolidated setUpClass

Source: https://commcarehq.readthedocs.io/en/latest/testing.html

Combine tests that share the same expensive `setUpClass` operations into a single test class to ensure `setUpClass` is executed only once.

```python
# GOOD EXAMPLE

class MyBigTestClass(TestCase):

    @classmethod
    def setUpClass(cls):
        ...

    def test1(self):
        ...

    def test2(self):
        ...

```

--------------------------------

### Initialize RMI Service in JavaScript

Source: https://commcarehq.readthedocs.io/en/latest/js-guide/integration-patterns.html

Use the dimagi/jquery.rmi library to initiate Remote Method Invocation (RMI) calls to Django views. This example shows how to start the notifications service by providing the URL for the RMI view.

```javascript
<script type="text/javascript" src="{% static '/notifications/js/NotificationsService.ko.js' %}"></script>
<script type="text/javascript">
    $(function () {
        $('#js-settingsmenu-notifications').startNotificationsService('{% url 'notifications_service' %}');
    });
</script>

```

--------------------------------

### Report API Data Format Example

Source: https://commcarehq.readthedocs.io/en/latest/reporting.html

Example structure of the data returned by the Report API.

```python
data = [
  {
    'slug1': 'abc',
    'slug2': 2
  },
  {
    'slug1': 'def',
    'slug2': 1
  }
  ...
]
```

--------------------------------

### Session Variables for Module A - Patient Case Example

Source: https://commcarehq.readthedocs.io/en/latest/advanced_app_features.html

Illustrates the session variables for Module A, including loading a 'patient' case and a variable for a 'new visit' case.

```text
case_id:		load patient case
case_id_new_visit:	id for new visit case ( uuid() )

```

--------------------------------

### Atom Feed XML Examples

Source: https://commcarehq.readthedocs.io/en/latest/openmrs.html

Example XML structures for patient and encounter Atom feeds used by MOTECH.

```xml
<?xml version="1.0" encoding="UTF-8"?>
<feed xmlns="http://www.w3.org/2005/Atom">
  <title>Patient AOP</title>
  <link rel="self" type="application/atom+xml" href="http://www.example.com/openmrs/ws/atomfeed/patient/recent" />
  <link rel="via" type="application/atom+xml" href="http://www.example.com/openmrs/ws/atomfeed/patient/32" />
  <link rel="prev-archive" type="application/atom+xml" href="http://www.example.com/openmrs/ws/atomfeed/patient/31" />
  <author>
    <name>OpenMRS</name>
  </author>
  <id>bec795b1-3d17-451d-b43e-a094019f6984+32</id>
  <generator uri="https://github.com/ICT4H/atomfeed">OpenMRS Feed Publisher</generator>
  <updated>2018-04-26T10:56:10Z</updated>
  <entry>
    <title>Patient</title>
    <category term="patient" />
    <id>tag:atomfeed.ict4h.org:6fdab6f5-2cd2-4207-b8bb-c2884d6179f6</id>
    <updated>2018-01-17T19:44:40Z</updated>
    <published>2018-01-17T19:44:40Z</published>
    <content type="application/vnd.atomfeed+xml"><![CDATA[/openmrs/ws/rest/v1/patient/e8aa08f6-86cd-42f9-8924-1b3ea021aeb4?v=full]]></content>
  </entry>
  <entry>
    <title>Patient</title>
    <category term="patient" />
    <id>tag:atomfeed.ict4h.org:5c6b6913-94a0-4f08-96a2-6b84dbced26e</id>
    <updated>2018-01-17T19:46:14Z</updated>
    <published>2018-01-17T19:46:14Z</published>
    <content type="application/vnd.atomfeed+xml"><![CDATA[/openmrs/ws/rest/v1/patient/e8aa08f6-86cd-42f9-8924-1b3ea021aeb4?v=full]]></content>
  </entry>
  <entry>
    <title>Patient</title>
    <category term="patient" />
    <id>tag:atomfeed.ict4h.org:299c435d-b3b4-4e89-8188-6d972169c13d</id>
    <updated>2018-01-17T19:57:09Z</updated>
    <published>2018-01-17T19:57:09Z</published>
    <content type="application/vnd.atomfeed+xml"><![CDATA[/openmrs/ws/rest/v1/patient/e8aa08f6-86cd-42f9-8924-1b3ea021aeb4?v=full]]></content>
  </entry>
</feed>
```

```xml
<?xml version="1.0" encoding="UTF-8"?>
<feed xmlns="http://www.w3.org/2005/Atom">
  <title>Patient AOP</title>
  <link rel="self" type="application/atom+xml" href="https://13.232.58.186/openmrs/ws/atomfeed/encounter/recent" />
  <link rel="via" type="application/atom+xml" href="https://13.232.58.186/openmrs/ws/atomfeed/encounter/335" />
  <link rel="prev-archive" type="application/atom+xml" href="https://13.232.58.186/openmrs/ws/atomfeed/encounter/334" />
  <author>
    <name>OpenMRS</name>
  </author>
  <id>bec795b1-3d17-451d-b43e-a094019f6984+335</id>
  <generator uri="https://github.com/ICT4H/atomfeed">OpenMRS Feed Publisher</generator>
  <updated>2018-06-13T08:32:57Z</updated>
  <entry>
    <title>Encounter</title>
    <category term="Encounter" />
    <id>tag:atomfeed.ict4h.org:af713a2e-b961-4cb0-be59-d74e8b054415</id>
    <updated>2018-06-13T05:08:57Z</updated>
    <published>2018-06-13T05:08:57Z</published>
    <content type="application/vnd.atomfeed+xml"><![CDATA[/openmrs/ws/rest/v1/bahmnicore/bahmniencounter/0f54fe40-89af-4412-8dd4-5eaebe8684dc?includeAll=true]]></content>
  </entry>
  <entry>
    <title>Encounter</title>
    <category term="Encounter" />
    <id>tag:atomfeed.ict4h.org:320834be-e9c8-4b09-a99e-691dff18b3e4</id>
    <updated>2018-06-13T05:08:57Z</updated>
    <published>2018-06-13T05:08:57Z</published>
    <content type="application/vnd.atomfeed+xml"><![CDATA[/openmrs/ws/rest/v1/bahmnicore/bahmniencounter/0f54fe40-89af-4412-8dd4-5eaebe8684dc?includeAll=true]]></content>
  </entry>
  <entry>
    <title>Encounter</title>
    <category term="Encounter" />
    <id>tag:atomfeed.ict4h.org:fca253aa-b917-4166-946e-9da9baa901da</id>
    <updated>2018-06-13T05:09:12Z</updated>
    <published>2018-06-13T05:09:12Z</published>
    <content type="application/vnd.atomfeed+xml"><![CDATA[/openmrs/ws/rest/v1/bahmnicore/bahmniencounter/c6d6c248-8cd4-4e96-a110-93668e48e4db?includeAll=true]]></content>
  </entry>
</feed>
```

--------------------------------

### Good: Get by ID

Source: https://commcarehq.readthedocs.io/en/latest/elasticsearch.html

Use the 'get' API for fetching documents by their ID. This is a more efficient method compared to searching by ID.

```http
GET /hqcases_2016-03-04/case/<case_id>?_source_include=name

```

--------------------------------

### Enable Dev Setup for Static Files

Source: https://commcarehq.readthedocs.io/en/latest/js-guide/static-files.html

Configure `localsettings.py` to disable compression and offline processing for development. This allows for server-side on-the-fly LESS compilation without combining files.

```python
COMPRESS_ENABLED = False
COMPRESS_OFFLINE = False

```

--------------------------------

### Python Code Block with Pygments

Source: https://commcarehq.readthedocs.io/en/latest/documenting.html

This Python code block requires the 'pygments' library to be installed ('pip install pygments') for syntax highlighting.

```python
# You need to "pip install pygments" to make this work.

for i in range(10):
    like()


```

--------------------------------

### Python Literal Code Block Example

Source: https://commcarehq.readthedocs.io/en/latest/documenting.html

A basic Python code example demonstrating a function and a loop, formatted as a literal code block.

```python
def like():
    print("I like Ice Cream")

for i in range(10):
    like()


```

--------------------------------

### Configure Sharded Form and Case Data

Source: https://commcarehq.readthedocs.io/en/latest/databases.html

Set up partitioned databases for form and case data using PLPROXY. Ensure total shards are a power of 2 and shard ranges are continuous and inclusive.

```python
USE_PARTITIONED_DATABASE = True

DATABASES = {
    'proxy': {
        ...
        'PLPROXY': {
            'PROXY': True
        }
    },
    'p1': {
        ...
        'PLPROXY': {
            'SHARDS': [0, 511]
        }
    },
    'p2': {
        ...
        'PLPROXY': {
            'SHARDS': [512, 1023]
        }
    }
}

```

--------------------------------

### Session Variables for Module B (Child of A) - Initial

Source: https://commcarehq.readthedocs.io/en/latest/advanced_app_features.html

Shows the initial session variables for Module B, a child of Module A. It highlights different naming conventions for loading the 'mother' case and a 'child' case.

```text
case_id_mother:	load mother case
case_id_child:	load child case

```

--------------------------------

### Ledger Balances Indicator Example

Source: https://commcarehq.readthedocs.io/en/latest/ucr.html

Creates columns for each specified product code, saving ledger data. Requires 'type', 'column_id', 'ledger_section', and 'product_codes'. An optional 'case_id_expression' can be provided.

```json
{
    "type": "ledger_balances",
    "column_id": "soh",
    "display_name": "Stock On Hand",
    "ledger_section": "stock",
    "product_codes": ["aspirin", "bandaids", "gauze"],
    "case_id_expression": {
        "type": "property_name",
        "property_name": "_id"
    }
}
```

--------------------------------

### Conditional Expression Example

Source: https://commcarehq.readthedocs.io/en/latest/_modules/corehq/apps/userreports/expressions/specs.html

This example demonstrates a conditional expression that evaluates a test condition and returns one of two possible outcomes. Ensure data types are consistent for comparisons, like casting age to an integer.

```json
{
    "type": "conditional",
    "test": {
        "operator": "gt",
        "expression": {
            "type": "property_name",
            "property_name": "age",
            "datatype": "integer"
        },
        "type": "boolean_expression",
        "property_value": 21
    },
    "expression_if_true": {
        "type": "constant",
        "constant": "legal"
    },
    "expression_if_false": {
        "type": "constant",
        "constant": "underage"
    }
}
```

--------------------------------

### Implement a custom SQL report using SqlData

Source: https://commcarehq.readthedocs.io/en/latest/reporting.html

Example implementation of a report class inheriting from SqlTabularReport and CustomProjectReport, demonstrating the configuration of columns, filters, and data aggregation.

```python
class DemoReport(SqlTabularReport, CustomProjectReport):
    name = "SQL Demo"
    slug = "sql_demo"
    fields = ('corehq.apps.reports.filters.dates.DatespanFilter',)

    # The columns to include the the 'group by' clause
    group_by = ["user"]

    # The table to run the query against
    table_name = "user_report_data"

    @property
    def filters(self):
        return [
            BETWEEN('date', 'startdate', 'enddate'),
        ]

    @property
    def filter_values(self):
        return {
            "startdate": self.datespan.startdate_param_utc,
            "enddate": self.datespan.enddate_param_utc,
            "male": 'M',
            "female": 'F',
        }

    @property
    def keys(self):
        # would normally be loaded from couch
        return [["user1"], ["user2"], ['user3']]

    @property
    def columns(self):
        return [
            DatabaseColumn("Location", SimpleColumn("user_id"), format_fn=self.username),
            DatabaseColumn("Males", CountColumn("gender"), filters=self.filters+[EQ('gender', 'male')]),
            DatabaseColumn("Females", CountColumn("gender"), filters=self.filters+[EQ('gender', 'female')]),
            AggregateColumn(
                "C as percent of D",
                self.calc_percentage,
                [SumColumn("indicator_c"), SumColumn("indicator_d")],
                format_fn=self.format_percent)
        ]

    _usernames = {"user1": "Location1", "user2": "Location2", 'user3': "Location3"}  # normally loaded from couch
    def username(self, key):
        return self._usernames[key]

    def calc_percentage(num, denom):
        if isinstance(num, Number) and isinstance(denom, Number):
            if denom != 0:
                return num * 100 / denom
            else:
                return 0
        else:
            return None

    def format_percent(self, value):
        return format_datatables_data("%d%%" % value, value)
```

--------------------------------

### OpenMRS Start Datetime Mapping

Source: https://commcarehq.readthedocs.io/en/latest/openmrs.html

Configuration for mapping the encounter start datetime from OpenMRS. This setting specifies the direction of data flow, the JSON path for the datetime, the corresponding case property, and the external and CommCare data types.

```json
"openmrs_start_datetime": {
  "direction": "in",

```

--------------------------------

### Run Django Tests

Source: https://commcarehq.readthedocs.io/en/latest/testing.html

Tests are invoked using the standard Django convention `./manage.py test` because the `nosetests` command does not perform necessary Django setup.

```bash
./manage.py test
```

--------------------------------

### Retrieve all live cases with one query

Source: https://commcarehq.readthedocs.io/en/latest/restore-logic.html

Recursive SQL query to resolve the entire tree of parent and extension cases for a device in a single execution.

```sql
with owned_case_ids as (
  select case_id
  from cases
  where
    domain = OWNER_DOMAIN and
    owner_id in OWNER_IDS and
    is_open = true
), recursive parent_tree as (
  -- parent cases (outgoing)
  select parent_id, child_id, child_type, array[child_id] as path
  from case_index
  where domain = OWNER_DOMAIN
    and child_id in owned_case_ids
  union
  -- parents of parents (recursive)
  select ci.parent_id, ci.child_id, ci.child_type, path || ci.child_id
  from case_index ci
    inner join parent_tree as refs on ci.child_id = refs.parent_id
  where ci.domain = OWNER_DOMAIN
    and not (ci.child_id = any(refs.path)) -- stop infinite recursion
), recursive child_tree as (
  -- child cases (incoming)
  select parent_id, child_id, child_type, array[parent_id] as path
  from case_index
  where domain = OWNER_DOMAIN
    and (parent_id in owned_case_ids or parent_id in parent_tree)
    and child_type = EXTENSION
  union
  -- children of children (recursive)
  select
    ci.parent_id,
    ci.child_id,
    ci.child_type,
    path || ci.parent_id
  from case_index ci
    inner join child_tree as refs on ci.parent_id = refs.child_id
  where ci.domain = OWNER_DOMAIN
    and not (ci.parent_id = any(refs.path)) -- stop infinite recursion
    and child_type = EXTENSION
)
select
  case_id as parent_id,
  null as child_id,
  null as child_type,
  null as path
from owned_case_ids
union
select * from parent_tree
union
select * from child_tree
```

--------------------------------

### Toxic Example: Global Variables Without Closure

Source: https://commcarehq.readthedocs.io/en/latest/js-guide/code-organization.html

This is a toxic example that should not be followed. It demonstrates the negative consequences of exposing variables and functions directly to the global scope without using a closure, leading to potential overwrites and namespace pollution.

```javascript
/* This is a toxic example, do not follow */

// actually a global
var myPrivateGreeting = "Hello";
// also a global
var sayHi = function (name) {
    console.log(myPrivateGreeting + " from my module, " + name);
};
// also a global
myModule = {
    sayHi: sayHi,
    favoriteColor: “blue”,
};

```

--------------------------------

### Initialize LedgerToElasticsearchPillow

Source: https://commcarehq.readthedocs.io/en/latest/_modules/corehq/pillows/ledger.html

Creates and configures the LedgerToElasticsearchPillow instance with Kafka change feed and checkpoint management.

```python
def get_ledger_to_elasticsearch_pillow(pillow_id='LedgerToElasticsearchPillow', num_processes=1,
                                       process_num=0, **kwargs):
    """Ledger pillow

    Note that this pillow's id references Elasticsearch, but it no longer saves to ES.
    It has been kept to keep the checkpoint consistent, and can be changed at any time.

    Processors:
      - :py:class:`corehq.pillows.ledger.LedgerProcessor`
    """
    assert pillow_id == 'LedgerToElasticsearchPillow', 'Pillow ID is not allowed to change'
    IndexInfo = namedtuple('IndexInfo', ['index'])
    checkpoint = get_checkpoint_for_elasticsearch_pillow(
        pillow_id, IndexInfo("ledgers_2016-03-15"), [topics.LEDGER]
    )
    change_feed = KafkaChangeFeed(
        topics=[topics.LEDGER], client_id='ledgers-to-es', num_processes=num_processes, process_num=process_num
    )
    return ConstructedPillow(
        name=pillow_id,
        checkpoint=checkpoint,
        change_feed=change_feed,
        processor=LedgerProcessor(),
        change_processed_event_handler=KafkaCheckpointEventHandler(
            checkpoint=checkpoint, checkpoint_frequency=100, change_feed=change_feed
        ),
    )
```

--------------------------------

### Define a CaseProperty

Source: https://commcarehq.readthedocs.io/en/latest/openmrs.html

Example JSON structure for referencing a specific case property.

```json
{
  "case_property": "dob"
}
```

--------------------------------

### Define a CaseOwnerAncestorLocationField

Source: https://commcarehq.readthedocs.io/en/latest/openmrs.html

Example JSON structure for referencing a location metadata value.

```json
{
  "doc_type": "CaseOwnerAncestorLocationField",
  "location_field": "openmrs_uuid"
}
```

--------------------------------

### Quickcache with Vary On Parameters

Source: https://commcarehq.readthedocs.io/en/latest/caching_and_memoization.html

Use @quickcache to cache function results based on specific parameters. The `vary_on` argument specifies which parameters (or their attributes) determine cache uniqueness. This example caches based on domain name and user ID.

```python
@quickcache(['domain_obj.name', 'user._id'], timeout=10)
def count_users_forms_by_device(domain_obj, user):
    return {
        FormAccessors(domain_obj.name).count_forms_by_device(device.device_id)
        for device in user.devices
    }

```

--------------------------------

### Get User ES Processor

Source: https://commcarehq.readthedocs.io/en/latest/_modules/corehq/pillows/user.html

Returns a BulkElasticProcessor configured for user document indexing.

```python
def get_user_es_processor():
    return BulkElasticProcessor(
        elasticsearch=get_es_new(),
        index_info=USER_INDEX_INFO,
        doc_prep_fn=transform_user_for_elasticsearch,
    )
```

--------------------------------

### Implement Celery Task with Soil Progress Tracking

Source: https://commcarehq.readthedocs.io/en/latest/celery.html

Use DownloadBase and expose_cached_download to manage task progress and file availability.

```python
from soil import DownloadBase
from soil.progress import update_task_state
from soil.util import expose_cached_download

@task
def my_cool_task():
    DownloadBase.set_progress(my_cool_task, 0, 100)

    # do some stuff

    DownloadBase.set_progress(my_cool_task, 50, 100)

    # do some more stuff

    DownloadBase.set_progress(my_cool_task, 100, 100)

    expose_cached_download(payload, expiry, file_extension)
```

--------------------------------

### Basic Shadow Module Menu Structure XML

Source: https://commcarehq.readthedocs.io/en/latest/advanced_app_features.html

Illustrates the basic menu structure for a shadow module, where it has its own unique menu element separate from its source module.

```xml
<menu id="m0">
    <text>
        <locale id="modules.m0"/>
    </text>
    <command id="m0-f0"/>
</menu>
<menu id="m1">
    <text>
        <locale id="modules.m1"/>
        </text>
    <command id="m1-f0"/>
</menu>
```

--------------------------------

### Run Static File Management Commands

Source: https://commcarehq.readthedocs.io/en/latest/js-guide/static-files.html

Execute these commands in sequence to collect static files, fix LESS import paths, and compile JavaScript internationalization. This setup mimics production static file handling.

```bash
manage.py collectstatic
manage.py fix_less_imports_collectstatic
manage.py compilejsi18n

```

--------------------------------

### Get Reporting Groups Expression

Source: https://commcarehq.readthedocs.io/en/latest/ucr.html

Retrieves the reporting groups assigned to a given user ID.

```APIDOC
## Get Reporting Groups Expression

### Description
Returns an array of reporting groups assigned to a provided user ID. Each element in the array represents one reporting group.

### Method
N/A (Configuration Expression)

### Endpoint
N/A (Configuration Expression)

### Parameters
#### Request Body
- **type** (string) - Required - Must be "get_reporting_groups".
- **user_id_expression** (object) - Required - An expression that resolves to a user ID.

### Request Example
```json
{
    "type": "get_reporting_groups",
    "user_id_expression": {
        "type": "property_path",
        "property_path": ["form", "meta", "userID"]
    }
}
```

### Response
N/A (This is a configuration expression, not an API endpoint.)
```

--------------------------------

### Get Total Documents

Source: https://commcarehq.readthedocs.io/en/latest/es_query.html

Returns the total number of documents that matched the query criteria from the ESQuerySet.

```python
total
```

--------------------------------

### Get Values

Source: https://commcarehq.readthedocs.io/en/latest/es_query.html

Retrieves specific fields from the query results, modeled after Django's `QuerySet.values`.

```python
values(_*fields_)
```

--------------------------------

### Run tests via command line

Source: https://commcarehq.readthedocs.io/en/latest/js-guide/testing.html

Execute tests for all apps or specific apps using Grunt.

```bash
$ grunt test
```

```bash
$ grunt test:<app_name> // (e.g. grunt test:app_manager)
```

```bash
$ grunt list
```

--------------------------------

### GET /bulk_user

Source: https://commcarehq.readthedocs.io/en/latest/api.html

Retrieves a list of users in bulk with support for querying, pagination, and field selection.

```APIDOC
## GET /bulk_user

### Description
This resource is used to get basic user data in bulk. It is optimized for speed and is useful for retrieving specific user attributes across a domain.

### Method
GET

### Endpoint
/bulk_user

### Parameters
#### Query Parameters
- **q** (string) - Optional - Query string to filter users.
- **limit** (integer) - Optional - Maximum number of results returned.
- **offset** (integer) - Optional - Use with limit to paginate results.
- **fields** (string) - Optional - Restrict the fields returned to a specified set.

### Request Example
?q=foo&fields=username&fields=first_name&fields=last_name&limit=100&offset=200

### Response
#### Success Response (200)
- **id** (string) - User ID
- **email** (string) - User email address
- **username** (string) - User username
- **first_name** (string) - User first name
- **last_name** (string) - User last name
- **phone_numbers** (array) - List of user phone numbers
```

--------------------------------

### Month Start Date Expression

Source: https://commcarehq.readthedocs.io/en/latest/_modules/corehq/apps/userreports/expressions/date_specs.html

Calculates the first day of the month for a given date expression.

```APIDOC
## Month Start Date Expression

### Description
Calculates the first day of the month based on a provided date expression.

### Method
N/A (Class definition)

### Endpoint
N/A

### Parameters
#### Path Parameters
N/A

#### Query Parameters
N/A

#### Request Body
N/A

### Request Example
```json
{
    "type": "month_start_date",
    "date_expression": {
        "type": "property_name",
        "property_name": "dob"
    }
}
```

### Response
#### Success Response (200)
- **date** (datetime.date) - The first day of the month.

#### Response Example
```json
{
  "date": "2023-10-01"
}
```
```

--------------------------------

### Calculate User Case Counts with TermsAggregation

Source: https://commcarehq.readthedocs.io/en/latest/es_query.html

Demonstrates how to group pregnancy cases by user and retrieve the document count for each bucket.

```python
res = (CaseES()
       .domain(self.domain)
       .case_type('pregnancy')
       .date_range('opened_on', gte=startdate, lte=enddate))
       .aggregation(TermsAggregation('by_user', 'opened_by')
       .size(0)

buckets = res.aggregations.by_user.buckets
buckets.user1.doc_count
```

--------------------------------

### Define FormUserAncestorLocationField Configuration

Source: https://commcarehq.readthedocs.io/en/latest/openmrs.html

Example JSON configuration for a FormUserAncestorLocationField, which references a location metadata value.

```json
{
  "doc_type": "FormUserAncestorLocationField",
  "location_field": "dhis_id"
}
```

--------------------------------

### Get Hits from ESQuerySet

Source: https://commcarehq.readthedocs.io/en/latest/es_query.html

Returns the actual documents (hits) from the raw Elasticsearch response within an ESQuerySet.

```python
hits
```

--------------------------------

### List extension points management command

Source: https://commcarehq.readthedocs.io/en/latest/extensions.html

Command to list all existing extension points and their implementations.

```bash
python manage.py list_extension_points
```

--------------------------------

### Get Document IDs from ESQuerySet

Source: https://commcarehq.readthedocs.io/en/latest/es_query.html

Returns only the document IDs from the raw Elasticsearch response within an ESQuerySet.

```python
doc_ids
```

--------------------------------

### Configure Manual Choice Lists

Source: https://commcarehq.readthedocs.io/en/latest/ucr.html

Provides a fixed set of options for the user to select from.

```json
{
  "type": "choice_list",
  "slug": "role",
  "field": "role",
  "choices": [
    {"value": "doctor", "display": "Doctor"},
    {"value": "nurse"}
  ]
}
```

--------------------------------

### Define Iteration Number Expression

Source: https://commcarehq.readthedocs.io/en/latest/_modules/corehq/apps/userreports/expressions/specs.html

Returns the index of a repeat item starting from 0 when used with a base_item_expression.

```json
{
    "type": "base_iteration_number"
}
```

--------------------------------

### Creating a Case in Unit Tests

Source: https://commcarehq.readthedocs.io/en/latest/forms_and_cases.html

Utilize the `CaseFactory` to create case instances in unit tests. The `run_with_all_backends` decorator should be applied if the test requires execution on both SQL and Couch.

```python
from corehq.form_processor.tests.utils import run_with_all_backends
from casexml.apps.case.mock import CaseFactory

@run_with_all_backends
def test_my_case_function(self):
    factory = CaseFactory(domain='foo')
    factory.create_case(
        case_type='my_case_type',
        owner_id='owner1',
        case_name='bar',
        update={'prop1': 'abc'}
    )
```

--------------------------------

### Identify Slow Function

Source: https://commcarehq.readthedocs.io/en/latest/profiling.html

Example of a typical Django view function that might need performance investigation.

```python
from django.http import HttpResponse
from corehq.apps.domain.decorators import login_and_domain_required
from corehq.util.view_utils import Format

@login_and_domain_required
def location_export(request, domain):
    response = HttpResponse(mimetype=Format.from_format('xlsx').mimetype)
    response['Content-Disposition'] = 'attachment; filename="locations.xlsx"'
    dump_locations(response, domain)
    return response

```