Load JavaScript and CSS files on a per-article basis


soo_required_files version 0.2.8, 4.5 KB
(If it won’t install try the compressed version)

Optional: soo_plugin_pref version 0.2.3, 3.7 KB
(If it won’t install try the compressed version)

I am a reluctant JavaScript user, and don’t like to load scripts where they aren’t being used. On occasion I use Shadowbox, which, like many similar JavaScript-based packages, requires loading some files in the <head> of an HTML page. There’s no obvious and simple way to do this in Textpattern on a per-article basis, hence this plugin.


This is a plugin for Textpattern.



Automatic loading of CSS and JavaScript files in the page <head> (or anywhere you like). For background, see Article-specific CSS & JavaScript in Textpattern.

soo_required_files has four options for loading files and forms:

These may be used in any combination.


No special requirements, except that per-article use requires a custom field (named Requires by default).

All my plugins are generally developed in the latest Txp public release and may not have been tested in earlier versions.

soo_required_files is compatible with soo_plugin_pref, which requires Txp version 4.2.0 or greater.


For per-article file and form loading, name one of your custom fields “Requires”. (If you wish to name it something else, change the custom field setting in plugin preferences (see Preferences & defaults, below.)

Install the optional soo_plugin_pref if you want to change default settings (Txp version 4.2.0 or greater required).

Upgrading from 0.1.1

If you are upgrading from version 0.1.1 with soo_plugin_pref, check preferences after installation. Two attribute names have been changed in this version, meaning any custom settings for those attributes (default js and css directories) will be overwritten on upgrade.

Upgrading to 0.2.6

Version 0.2.6 adds a new preference, html_version. If you are running soo_plugin_pref, after installing the new version of soo_required_files you must disable and re-enable it to install the preference. (The new preference will function at its default value even if you don’t do this.)

Upgrading to 0.2.7

Oops, I really didn’t need to add that preference to 0.2.6. Version 0.2.7 removes it, in favor of the global doctype preference. So if you previously installed or upgraded to 0.2.6 and are running soo_plugin_pref, to drop the now-useless preference from the database, after upgrading to 0.2.7, disable and re-enable the plugin. Sorry about that.


Place the soo_required_files tag in the page <head>. It works as either a single or container tag:

<txp:soo_required_files />


	<!-- comma-separated list of file and form names -->


You can override any of the preferences with its corresponding attribute; the following are the ones you might actually want to set this way:

Per-page loading

When this option is enabled, either through preferences or by the per_page attribute, the plugin will look for a css and a js file with the same name as the current page. For example, if the current section uses a page called “article”, the plugin will look for files named “article.css” and “article.js” in their respective directories.

Per-section loading

Works the same as per-page loading, except based on the current section name (and the per_section attribute/preference).

Per-article loading

The Requires field takes a comma-separated list. List items can include:

Any item ending in “.js” is assumed to be a JavaScript file. It will result in a <script> element loading the specified file from the default JavaScript directory (see Defaults, below).

Any item ending in “.css” is assumed to be a CSS file. It will result in a <link> element loading the specified file in the default CSS directory (see Defaults, below).

Anything else is assumed to be the name of a Txp form. The plugin will attempt to output the named form (first adding the default prefix; see Defaults, below).

Loading tag contents

If you use soo_required_files as a container, the tag contents are treated in the same way as the Requires field contents, above. That is, the tag contents should be a comma-separated list and can be any combination of css files, js files, and Txp form names.

As of version 0.2.2 you can include Txp tags in the tag contents, allowing e.g. Txp conditional tags for further automation options.

Load order

Files and forms are loaded in the following order:

  1. Tag contents
  2. Per-page files
  3. Per-section files
  4. Requires field contents

Preferences & defaults

You can change the default values for various settings and attributes by installing the soo_plugin_pref plugin. Once installed you can access the preferences by clicking the Options link for soo_required_files in the plugin list.

The initial defaults are:

Attribute Description Default
custom_field Custom field name Requires
css_dir CSS directory css/
js_dir JS directory js/
form_prefix Form-name prefix require_
per_page Per-page loading No
per_section Per-section loading No


Using the Requires field

With defaults as above, entering script1.js, style1.css, foo in the Requires field will get <txp:soo_required_files /> to output something like:

<script type="text/javascript" src=""></script>
<link rel="stylesheet" type="text/css" href="" />

followed by whatever is in the form named “require_foo”.

Forms are especially useful for preset combinations of files. For example, some scripts (e.g. Shadowbox) require a mix of JavaScript and CSS files. Putting the appropriate <script> and <link> elements in a form allows you to call this up with a single entry in the Requires field. So to load my “require_Shadowbox” form (which loads the scripts and CSS required for Shadowbox), I enter Shadowbox in the Requires field.

Combining per-section/page, per-article, and tag content file loading

For my personal website I have CSS files named after each section (including the default section), plus a file called “base.css” for common styles. Some articles have specific js/css requirements, so I also have a Requires field, used as above. I have a form called page_top that creates the <head> element for every section. It doesn’t have any <script> or <link> tags, just this:


Because I have enabled per-section loading in preferences, every HTML page automatically gets both the base stylesheet and the section-specific stylesheet, and individual article pages will also load anything listed in Requires.


Version 0.2.8 (2020/3/15)

Version 0.2.7 (2017/3/14)

Version 0.2.6 (2017/2/23)

Version 0.2.5 (2017/2/13)

Version 0.2.3 (2010/12/20), 0.2.4 (2010/12/27)

Version 0.2.2 (2010/07/10)

Version 0.2.1 (2009/10/03)

Version 0.2 (2009/09/25)

Version 0.1.1 (2009/09/18)

Version 0.1 (2009/05/15)