Importing HTML, CSS and JSON for Components

You can import HTML and CSS from files or content template HTML elements, instead of coding HTML and CSS directly in your ACSS component code. You can also import JSON prior to the component rendering, using the technique described herein.

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 JSON from external files

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

Variables will automatically be created, in the same way as the ajax action command.

This method has the advantage of over using an ajax action command inside the component, because the component renders after the json is fully loaded and all variables are set up.

 

Components - import JSON from file

 

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.

Handling file loading errors

The afterAjax series of events are used to handle file loading errors when importing content in the methods stated above.

A component will not render at all if there has been a file loading error.

The events are attached to the component name itself, like this:

clock-component:afterAjaxError {
    /* do something */
}


clock-component:afterAjax404 {
    /* do something */
}

These events live outside of the component, because they kick in before the component is entered for rendering. All initial file loading actions take place prior to the component being generated, if the methods on this page are used.