This is a plugin for Textpattern.
soo_required_files has four options for loading files and forms:
- all contexts (by tag contents)
- per page (for files with matching names)
- per section (for files with matching names)
- per article (by custom field)
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.
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 --> </txp:soo_required_files>
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(boolean) Whether to enable per-page loading
per_section(boolean) Whether to enable per-section 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.
Works the same as per-page loading, except based on the current section name (and the
The Requires field takes a comma-separated list. List items can include:
- CSS file names (e.g, “style.css”)
- Txp form names
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.
Files and forms are loaded in the following order:
- Tag contents
- Per-page files
- Per-section files
- 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:
||Custom field name||Requires|
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:
followed by whatever is in the form named “require_foo”.
<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
<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.7 (2017/3/14)
- Removes the preference added in 0.2.6 in favor of the global doctype preference. (NB: see Upgrade notes.)
Version 0.2.6 (2017/2/23)
- Added HTML version preference, which controls whether or not the
typeattribute is added to
scripttags. (NB: see Upgrade notes.)
Version 0.2.5 (2017/2/13)
- Txp 4.6 compatibility update
Version 0.2.3 (2010/12/20), 0.2.4 (2010/12/27)
- Code cleaning only; no functional changes
Version 0.2.2 (2010/07/10)
- Tag contents can now include other Txp tags, allowing e.g. Txp conditional tags for further automation options.
Version 0.2.1 (2009/10/03)
- Fixed to work with sub-directory installations
Version 0.2 (2009/09/25)
- New features:
- Per-section and/or per-page file loading
- Container tag mode for additional files/forms
- All preferences can now be overriden by tag attributes
- Note: new attribute names for default js and css directories. Users upgrading from version 0.1.1 should check preferences and update these values if needed.
Version 0.1.1 (2009/09/18)
- Added compatibility with soo_plugin_pref for preference management
Version 0.1 (2009/05/15)
- Initial release. Per-article loading of js/css files, Txp forms.