Write the document <head>

This how-to explains how any element on your page can add its own scripts, stylesheets, or whatever they choose to to the document's <head> section.

Let's see a few solutions first. You will find an explanation after them.


Various solutions

Boomla has several engines that have different ways of writing to the document <head>. You will need one of these solutions plus setting the Content-Security-Policy headers in case you are embedding an external resource.


sjs-4 engine

In this engine, you write JavaScript code that runs on the server. Here is how you can embed a script in the head.



If you want to add a script file that is on your website's filesystem, you most likely want to add the o1-cache parameter to leverage browser caches and make your website load faster. The sjs-4 engine provides a helper function to do this for you, in which case you only need to provide the file's path, the rest will be done for you:



sjs-4e, sjs-4et engines

Similar to the sjs-4 engine above, except you are writing HTML by default. You can embed JavaScript code similar to php, by wrapping your code in <? ... ?> tags. You don't need to close the last tag, hence we omit it here.



To add a local script file:


Note that a common mistake is to leave off the starting ../. In case it doesn't work, try adding an extra ../.


html-1 engine

This engine has a special syntax for writing the document head, by wrapping your code in a <head>...</head> section. Note that the html-1 engine will extract whatever is found between these tags, so the <head> tags won't appear within your document's body.



Content-Security-Policy headers

You will need to set the Content-Security-Policy headers of the response or browsers will refuse to load them.

This is a 2-step process:

  • Create a file named .ContentSecurityPolicy and add the desired rules as described in the .ContentSecurityPolicy docs.

  • Load this .ContentSecurityPolicy file according the the engine you have used to render the element. 

    The sjs-4 engine family uses the util.addCSP() method as described in the util.addCSP() docs. The html-1 engine will automatically pick up the .ContentSecurityPolicy file if it exists.



Understanding what's going on

They key thing to understand is that every element returns a separate head and body string to be embedded in the response.

The way this happens is that a so called response file is created when rendering any of the elements. To add HTML code to the <body> area, you write the response file's body, to add HTML code to the <head> area, you write the response file's head attribute.

Your element may be embedded in other elements. For example, a gallery element may be placed in a grid layout element. In this case, the gallery element may write its own response file's head attribute. Once the gallery is rendered on the server, its response file will be returned to the grid layout app. This grid layout app will embed the gallery's body into its own code and append the gallery's head to it's own response file's head attribute.

Finally, after the top-most element is rendered, Boomla will format the resulting HTML code and return it to the client.