There are no tracking or monitoring cookies on this site. There are only cookies used for documentation examples related to cookies.
Close

Processing...
This may take a few seconds.

Importing HTML and CSS for Components

As of ACSS version 2.10.0, you can now import HTML and CSS from files or content template HTML elements, instead of coding HTML and CSS directly in your ACSS component code.

As well as making your ACSS code look a bit cleaner, it can make for better organization and allow you to call dynamically rendered HTML views or CSS from the server, for the purpose of displaying inside component areas.

Alongside this new feature, you can also include regular or reactive ACSS variables directly in your imported HTML and CSS files, by using the accept-vars option in the @component statement. These will automatically be handled by ACSS before the component renders. You are in control of this. Components that do not have the accept-vars option set will not evaluate ACSS variables from an external file. See the section below for more on that functionality.

Importing HTML and CSS from external files

To do this, use the html option and/or the css option in the @component statement. The values in brackets for these options are the exact same ones that are used in the ajax command.

If you want to allow ACSS variables to be imported that are inside your HTML or CSS files, you can use the accept-vars option.

An additional benefit of keeping HTML and CSS in external files is that you get access to HTML and CSS syntax editing in text editors.

Note: The html { ... } option inside the component is ignored if this method is used.

Important note:

This method does come with a minor rendering performance cost due to the loading of files.

 

Components - import html and CSS from files

 

Importing HTML and CSS from templates

To do this, use the html-template option and/or the css-template option in the @component statement. The values in brackets for these options are selectors that reference specific content template HTML elements.

In fact, you could put both HTML and CSS into any template, and these would get rendered as expected. But for organizational clarity, and for no other reason, both html and css template options are provided if you want to use them.

If you want to allow ACSS variables to be imported that are in your HTML or CSS templates, you can use the accept-vars option.

Note: The html { ... } option inside the component is ignored if this method is used.

Components - import html and CSS from templates

 

Allowing variables in imported files and templates

By default, if ACSS variables are found in the content of imported HTML or JSON files or templates, they will not be evaluated.

However, if you want to allow variables to be written in files or templates, you can use the accept-vars option. This can either be used as a general option for the whole component, or for individual files loaded (for imported files only - it won't work on templates - it's either all or nothing for templates at the moment).

Variables will be evaluated according to the scope of the component (see the Variable in Components section.)

To get accept-vars working for the whole component, put the option outside of any html or css options, as below.

@component clock-component
html(/examples/clock-component.html get)
css(/examples/clock-component.css get)
accept-vars
private {

...

}

To get accept-vars working for individual files, put the option outside of any html or css options, as below. The example below has the accept-vars option set for the CSS file only.

@component clock-component
html(/examples/clock-component.html get)
css(/examples/clock-component.css get accept-vars)
private {

...

}

Important note: ACSS variables, to be evaluated via accept-vars, must be wrapped by at least one element in imported files. Eg. they could be in a div or a span tag, or whatever, but they need a parent element to get evaluated when they render. This may change in future versions -- the allowing of variable rendering for standalone text nodes -- but it's not supported yet.

 

There now follows an example where the clock component is imported from an HTML file and a CSS file which both have ACSS variables in them. The variables have been declared in the component and are isolated to that component, because we have used the strictlyPrivate option on the component, which isolates the component events and variables from the rest of the ACSS config.

As an exercise using accept-vars, try removing the accept-vars option completely and then placing it on specific files and you will see different things happen to the output.

A component with accept-vars

 

Escaping ACSS variables from a server back-end:

JavaScript, using {= ... =} syntax, is not allowed in imported HTML or CSS files. However, If you use the accept-vars option when importing HTML, you are allowing variables.

So, if you do use the accept-vars option on dynamically generated HTML or CSS that grabs data from a database, be sure that you are checking your dynamically generated code for ACSS variables on your server back-end, and escaping them where applicable before returning your code. To escape an ACSS variable, you should put a single backslash before each curly bracket, which will be sufficient to stop ACSS from recognising the variable and trying to handle it when your imported code reaches the browser. Your curly brackets will display as intended.

Let's take an example. Let's say you have output the content of a database field, which is called "comment".

In the database, in the record you are displaying, the comment field contains the string:

Hack me {password}

The user specifically typed this into your HTML form, and when they submitted the form, you saved this information in a record in your database.

How do you handle this? Well, you need to escape it when you next display it on your website, unless you specifically want people to be able to see the value of variables.

Example of not escaping content in an imported file - do not return this string to the browser:

<h1>{intentionalVariable}</h1>
<div>User content from a database: Hack me {password}
</div>

Example of escaped content in an imported file - putting backslashes before the curlies - this is safe to send to the browser:

<h1>{intentionalVariable}</h1>
<div>User content from a database: Hack me \{password\}
</div>

That escaping of curlies will stop ACSS from handling user-submitted variables when accept-vars is used as an import option. Curlies that are escaped in the file, when rendered, will be displayed as curlies on the page without the backslash.

If you don't have any variables in your imported file, you don't need to use the accept-vars option at all.