> For the complete documentation index, see [llms.txt](https://developer.singular.live/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://developer.singular.live/composition-scripting/cheat-sheets/best-practices.md).

# Best practices

Use these cheat sheets to follow best practices in common scripting tasks.

### Communication between sub-compositions

An efficient option for exchanging data between sub-compositions is by adding functions to the composition object.

#### Receiving data in a sub-composition

Extend a composition object by adding the function comp.updateContent() 

{% code title="Lower subcomposition Script" %}

```javascript
(function() {
  return {

    init: function(comp, context) {
      console.log("Initialize Composition script " + comp.name);

      // extend the composition object
      // receive data in the updateContent function
      comp.updateContent = function(data) {
        console.log("updateContent() - data =", data);
      }

    },

    close: function(comp, context) {
      console.log("Close Composition script " + comp.name);
    }
  };
})();
```

{% endcode %}

#### Sending data to a sub-composition

Get reference to the receiving composition and send data by calling its updateContent() function.

{% code title="Root Script" %}

```javascript
((function() {

  return {

    init: function(comp, context) {
      console.log("Initialize Composition script " + comp.name);

      // get composition reference
      const compLower = comp.find("Lower")[0];

      comp.addListener('payload_changed', (event, msg, e) => {
        console.log("Composition payload " + comp.name, event, msg);
        const payload = comp.getPayload2();

        // send data to destination
        compLower.updateContent(payload);
        e.stopPropagation();
      });

    },

    close: function(comp, context) {
      console.log("Close Composition script " + comp.name);
    }
  };
})();
```

{% endcode %}

### Updating overlay content from the composition script

A typical use case is receiving data in sub-composition control nodes, interpreting them, and updating properties within the sub-composition.

In such a case, it is recommended to unlink the receiving control nodes from properties and directly update widget properties.

#### **Reading control nodes, generating HTML, and updating the widget’s text property**

{% code title="Lower subcomposition Script" %}

```javascript
(function() {
  return {

    init: function(comp, context) {
      console.log("Initialize Composition script " + comp.name);

      const wiFullname = comp.findWidget("fullname")[0];

      comp.addListener('payload_changed', (event, msg, e) => {
        console.log("Composition payload " + comp.name, event, msg);
        
        // read control nodes content
        const p = comp.getPayload2();
        const htmlText = `<HTML>${p.firstname} <b>${p.lastname}</b></HTML>`;

        // update text widget
        wiFullname.setPayload({
          "text": htmlText
        });
        
        e.stopPropagation();
      });

    },

    close: function(comp, context) {
      console.log("Close Composition script " + comp.name);
    }
  };
})();
```

{% endcode %}


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://developer.singular.live/composition-scripting/cheat-sheets/best-practices.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.