Docs Developer Site
Enonic XPCMSContributions

Page contributions

Contents

Page contributions enable parts, layouts, macros and other controllers contribute content to the response HTML’s header or footer.

Example use cases are:

  • Let a part contribute JavaScript to the page’s <head> section.

  • Let a part contribute custom CSS to the <head> of that page.

  • A layout might add a JavaScript tracker to the end of the <body> of the page.

Introduction

Contributions are typically used to add content to specific segments of the response HTML.

Page contributions will only be activated if the response type is text/html (which is the default)

There are four positions in HTML where contributed content can be inserted:

headBegin

After the <head> opening tag.

headEnd

Before the </head> closing tag.

bodyBegin

After the <body> opening tag.

bodyEnd

Before the </body> closing tag.

To use page contributions, your component needs to return a pageContributions property in it’s HTTP response object. The response might look like something like this (as always, the return goes at the end of your component’s controller):

return {
  body: '<p>Some markup</p>',
  pageContributions: {
    headEnd: [
      "<script>My script</script>"
    ]
  }
};

Changing the headEnd to one of the other possible positions will affect where the code you contributed is added in the page’s HTML before returning it to the end-user.

Sample with multiple contributions 
return {
  "body": "<div>...</div>",
  "pageContributions": {
    "headEnd": "value",
    "bodyEnd": [
      "value1", "value2"
    ]
  }
};

  • All pageContributions fields are optional.

  • Contribution values are treated as plain text.

  • Values must be unique within each injection point, duplicates will be truncated.

  • If the target tag does not exist in the response body, the contribution will be ignored. I.e. if there is no <head> tag, the contributions to headBegin and headEnd will be ignored.

  • For consistency, all positions are automatically treated arrays in the aggregated response object, even if there is only a single value.

Contribution merging

Contributions are merged into the response body immediately after response processors, and before site mapping filters get access to the response.

All contributions from the previous rendering steps will be merged into the response body. Any duplicate page contributions will automatically be removed, so developers do not have to worry about this.

Contents