> For the complete documentation index, see [llms.txt](https://aurelia-1.gitbook.io/v1-docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://aurelia-1.gitbook.io/v1-docs/components/template-compilation-using-processcontent.md).

# Template compilation using processContent

The `processContent` function is a powerful feature in Aurelia 1 that allows developers to manipulate the content of a custom element's view before it's compiled. This feature is crucial for scenarios where you need to preprocess templates, implement custom syntax, or modify the DOM structure before Aurelia's standard compilation process.

#### Syntax

```javascript
@processContent(contentProcessorFunction)
```

### Implementing processContent

#### Basic Structure

To use `processContent`, add it as a decorator to your custom element class:

```javascript
import { customElement, processContent } from 'aurelia-framework';

@customElement('my-element')
@processContent((compiler, resources, node, instruction) => {
  // Your content processing logic here
  return true;
})
export class MyElement {
  // Your element logic
}
```

#### Parameters

The `processContent` function receives four parameters:

1. `compiler`: The `ViewCompiler` instance, used for compiling views.
2. `resources`: The `ViewResources` instance, containing view-related resources.
3. `node`: The DOM node representing the view (usually a `DocumentFragment`).
4. `instruction`: The `BehaviorInstruction` for the custom element.

#### Return Value

* `true`: Aurelia will compile the content normally after your processing.
* `false`: Aurelia will not compile the content, leaving it as-is.

### Use Cases and Examples

#### 1. Preprocessing Text Content

Replace placeholders in the template:

```javascript
@customElement('date-display')
@processContent((compiler, resources, node, instruction) => {
  const content = node.textContent;
  node.textContent = content.replace(/\{\{TODAY\}\}/g, new Date().toLocaleDateString());
  return true;
})
export class DateDisplay {}
```

#### 2. Modifying DOM Structure

Add or remove elements from the template:

```javascript
@customElement('enhanced-list')
@processContent((compiler, resources, node, instruction) => {
  const list = node.querySelector('ul');
  if (list) {
    const wrapper = document.createElement('div');
    wrapper.className = 'list-wrapper';
    list.parentNode.insertBefore(wrapper, list);
    wrapper.appendChild(list);
  }
  return true;
})
export class EnhancedList {}
```

#### 3. Implementing Custom Syntax

Process custom attribute syntax:

```javascript
@customElement('custom-button')
@processContent((compiler, resources, node, instruction) => {
  const button = node.querySelector('button');
  if (button && button.hasAttribute('custom-color')) {
    const color = button.getAttribute('custom-color');
    button.style.backgroundColor = color;
    button.removeAttribute('custom-color');
  }
  return true;
})
export class CustomButton {}
```

#### 4. Conditional Compilation

Selectively compile parts of the template:

```javascript
@customElement('conditional-element')
@processContent((compiler, resources, node, instruction) => {
  const shouldCompile = node.hasAttribute('compile');
  if (!shouldCompile) {
    // Remove all bindable attributes to prevent compilation
    Array.from(node.attributes).forEach(attr => {
      if (attr.name.startsWith('bind-')) {
        node.removeAttribute(attr.name);
      }
    });
  }
  return shouldCompile;
})
export class ConditionalElement {}
```

### Advanced Techniques

#### Accessing ViewResources

Use the `resources` parameter to register custom elements or attributes:

```javascript
@processContent((compiler, resources, node, instruction) => {
  resources.registerElement('custom-tag', CustomTagClass);
  return true;
})
```

#### Working with the ViewCompiler

Utilize the `compiler` to manually compile parts of the view:

```javascript
@processContent((compiler, resources, node, instruction) => {
  const customPart = node.querySelector('.custom-part');
  if (customPart) {
    const factory = compiler.compile(customPart, resources);
    // Use the factory as needed
  }
  return true;
})
```

### Best Practices

1. Performance Considerations:
   * Use `processContent` judiciously, as it runs for each instance of the custom element.
   * Keep manipulations focused and efficient.
2. Maintainability:
   * Document the purpose and behavior of your `processContent` function.
   * Consider extracting complex logic into separate functions for clarity.
3. Compatibility:
   * Be aware that DOM manipulations may affect Aurelia's binding system.
   * Test thoroughly, especially with complex templates or bindings.
4. Alternatives:
   * Consider using value converters, custom attributes, or composition for simpler cases.

### Conclusion

The `processContent` function is a powerful tool in Aurelia 1 for customizing template compilation. It offers unparalleled flexibility in manipulating views before they're processed by Aurelia's standard compilation. While powerful, it should be used thoughtfully, considering both performance and maintainability implications.


---

# 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://aurelia-1.gitbook.io/v1-docs/components/template-compilation-using-processcontent.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.