Overview

GenHelm makes it very easy to reuse and override script and css styles. These can be defined in four separate locations:

1. Definitions specified in site_settings apply to the entire website. This is where you should define site-wide styles and scripts that are used by many pages in the site.
2. Definitions attached to a layout apply to any pages rendered with this layout. These can either override or supplement the site wide definitions.
3. Definitions defined on a specific page only pertain to that page. These can override or supplement the definitions set at the layout and/or site level.
4. Finally, it is possible to introduce or override definitions using dollar functions or as part of run time processing.

Many of the fields associates with styles and scripts are the same. We will begin by reviewing these common fields. In many of the examples and descriptions we may discuss stylesheets but the same rules also apply to JavaScript files.

After describing the common fields we will discuss the fields that are specific to styles followed by those that are specific to scripts.

The definitions may appear intimidating but be aware that most of the columns are options. In many cases you will just fill in two or three columns.

Identifiers

Notice that the first column of the script and CSS definition grids is known as an identifier. This is used as a key during the run time setup processing when web pages are rendered. For example, if a css stylesheet defined on the site_settings definition has an identifier of "common-styles" this stylesheet will be incorporated in all pages of the site except for pages that define a different stylesheet using this same identifier. To exclude this stylesheet (but not replace it with an alternate stylesheet) you can add a row using the identifier to be excluded but specify a value of none in the media column. Similarly, for JavaScript files you can prevent a site-wide script by adding a new script row at the page level with the same identifier used in the site settings but specify a script location of nowhere.

Similar rules apply to overriding styles and script at the layout level.

File Location

In most cases, style and script files will be taken from the styles and support folders of the site itself. In such a case, it is not necessary to enter anything into the File Location column. Alternatively, you can enter the keyword SITE in upper case to make it clear that a file belongs to the current site.

In many cases, script and sometimes styles will be stored in the inherited pseudo site (which defaults to system). To draw on these system files, enter the uppercase keyword FRAMEWORK.

If your site inherits from an industry pseudo site (as indicated in site_settings) use INHERIT to specify that the script or css file is to be drawn from this site.

You also have the option of specifying DYNAMIC as the file location. In this case, the component will be loaded from the current site if it exists there. If it is not found within the current site it will be loaded from the inherited site if such a site is specified within site_settings and if the inherited site defines the component to be loaded. Finally, the component will be loaded from the system pseudo site if it is found there.

Another possibility is that you may want to pull files from a remote server such as a CDN (Content Delivery Network). For example, Google serves the jQuery framework from the url https://ajax.googleapis.com/ajax/libs/jquery/3.3.1/jquery.min.js, Therefore, the path portion if this file (specifically https://ajax.googleapis.com/ajax/libs/jquery/3.6.0/jquery.min.js could be entered into the File Location field to pull jQuery from this location. The advantage of using popular CDN files is that there is a good chance that your web users have visited other sites that refer to these same files so the files may be cached in your user's browser even if they have never visited your site before.

File Name

Enter the file name to be used (not including the folder or path). For CSS files this file will normally have the extension .css and for JavaScript files the extension will usually be .js.

Placement

This field allows you to specify where within the html the styles or script file is to be included. For script, this can be in one of three locations:

1. In the head section of the rendered html, this is normally after the styles have been declared.
2. In the head_top section of the rendered html. This is used in rare cases where the script needs to be above the styles.
3. At the very top of the body section of the html.
4. At the very bottom of the body section.

In the case of styles, you have the option of placing these in the head section or at the bottom of body section. Usually styles go into the head section however for large stylesheets this can result in delays since the loader must wait for the styles to be loaded before continuing to load the rest of the html. Google recommends sculpting CSS to render essential CSS in the head section but postpone non-essential CSS until after the "above the fold" content is loaded. To follow this recommendation you should generally do the following:

1. Start by moving all of the styles to the bottom of the html by selecting position bottom.
2. Try loading the various pages of your site making note of flickering behaviour. Generally, the flickering is caused by the fact that spatial styling (padding, margins, etc.) is delayed so the page ends up being rendered in the top-left of the screen then it gets moved once the styles are loaded.
3. Move important styles out of the main stylesheet and put them into a dedicated stylesheet that is loaded in the head section of the page with the inline option. Avoid copying too many styles since you want to keep the number of inline styles fairly small.
4. Continue this process until you have created an acceptable loading experience.

Additionally, you can select nowhere if you want to prevent a (non-final) script and styles defined at a higher level from being included.

Priority

Sometimes it is important for one stylesheet to be included before another stylesheet (since styles indicated in the later sheet will override like named style definitions in earlier sheets). Similarly, sometimes script in one file may need to be physically positioned ahead of script in another file. The priority column allows you to control this sequencing by placing a lower number in the priority column for files that need to come before other files (that are assigned a higher priority value).

In many cases the priority is not important and you can leave this column blank. If you do need to use it you may want to leave some gaps in the priorities in case you later need to define files that must be included between existing files. The default priority is 5000 so if you set a file to have priority, say 4000, it will be loaded before those that do not have a priority set.

Group

Each script file or stylesheet requires the browser to make a request to the server. There is a fair amount of overhead in each file request so people often combine all of their styles or scripts into one file. The problem with this strategy is that you end up with file "bloat". That is, a certain page may only need a hand full of styles but nevertheless you include a stylesheet that contains hundreds of styles.

A cleaner strategy is to group styles into smaller subsets that are commonly used together. For example, you may have a set of styles for handing responsive grids and another set of styles to support carousels, etc. This way you need only include the styles that pertain to the items on your specific page. This strategy introduces a new problem in that the browser may need to make several round trips, one to load each separate file.

The group column seeks to solve this quandary. It allows you to logically divide content into different files while at the same time combine these files into one common file to be served at runtime. For example, say your page needs five separate css stylesheets. If these stylesheets are all given the same group name the five sheets will be combined and served under a common name. This way, the browser only needs to fetch one file. The runtime framework handles the process of combining these files automatically.

Note then when grouping files, be sure to use the version column to make sure that newer versions of a file are re-cached.

Device

The device column makes it easy to include files that are device specific. For example, suppose you use a set of styles for phone devices and these same style names are defined differently for desktop devices. In this case, you can control which stylesheet gets loaded into each type of device.

Version

Browsers generally cache JavaScript and Stylesheets for a number of days or even weeks after visiting a site in case the user returns to the site. When the browser finds a cached version of a file it will use this version rather than reloading the file from the server. This can create challenges for web developers since they can make changes to these files and publish these changes but browsers may continue to use older versions of the file(s). The Version column allows you to enter a version number for each file. Later, when you need to make a change to a file, you can increment the version number to force browsers to request the latest version of the file.

Integrity and Crossorigin

When serving files from a Content Delivery Network it is important to ensure that you have been delivered the expected files without manipulation.

The Integrity property allows the browser to check the file source to ensure that the content is never loaded if the source has been manipulated.

The Crossorigin Property should be used when a request is loaded using "CORS" which is now a requirement of SRI checking when not loaded from the "same-origin" host.

Basically, if you are loading files from a CDN and if the provider supplies suggested values for the Integrity and Crossorigin fields, enter these in the same row as the CDN file you are referencing.

Final

Recall that it is normally possible to override a file defined in site_settings at a lower level (either at the layout or page level). Similarly, layout files can be overridden at the page level. Sometimes you may not want to permit certain files from being overridden. For example, if a site wide script is used to support a security requirement, you would not want a certain page to disable this. In such cases you can designate a file as being final by checking the final column.

Comment

It is a good idea to use the Comment column to describe the purpose of a script file or stylesheet.

CSS Specific Fields

Media

The Media column reflects the media attribute of a stylesheet link definition. It is used to indicate that a stylesheet applies to the print media, speech, etc. or you can even code a complex media query in this column.

Inline

One way to make the rendering of a page faster is to include the styles inline rather than forcing the browser to load an external stylesheet. The disadvantage of this approach is that the browser does not cache inline styles (only those loaded from a separate stylesheet). For this reason, it is only recommended to inline stylesheets that are relatively small, say up to 20 or 30 lines.

JavaScript Specific Fields

Script Synchronization

By default, the loading if scripts interrupts the loading of other html content since the browser normally waits for the script to completely load before proceeding. Depending on how your script has been coded, it may be possible to set this option to async to tell the browser that it is okay to load the script in parallel with the html content.

The defer option should be specified if it is important to tell the browser not to execute the script until the entire page has been loaded.

Use the inline option in cases where you want to render the script inline rather than forcing the browser to make a round-trip to the server to load the script. The inline option should only be used for small scripts since the browser will not cache inline scripts.

Mime Type

For most normal JavaScript files the Mime Type column will be left blank. This column should be used if the file contain json or other special content.

Adding or Changing Scripts and Styles On-The-Fly

One of the powerful features of the GenHelm framework is that scripts and styles can be added on demand. This helps to prevent resource "bloat" which is common in other frameworks that don't support the granular loading of scripts and styles conditionally. To learn how this is done please refer to the help associated with the custom model.