ebl_buildJs Plugin Help

Plugin Name: ebl_buildJs

Description:

The ebl_buildJs plugin generates <script> tags for JavaScript files located in a specific theme’s directory in a Textpattern CMS installation. It supports bulk loading, single-file loading, exclusions, and natural sorting of files for easy integration of JavaScript assets.

Usage:

To use the plugin, insert the following tag in your Textpattern template or page:

<txp:ebl_buildJs theme="theme_name" directory="js_directory" />

Attributes:

theme (Required):

• Description: Specifies the name of the theme (skin) where the JavaScript files are located.
• Example: theme="my_theme"

directory (Optional):

• Description: Specifies the subdirectory inside the theme folder where the JavaScript files are stored.
• Default: An empty string (i.e., the JavaScript files are expected directly in the theme folder).
• Example: directory="scripts"

name (Optional):

• Description: Specifies a single JavaScript file to load. The file name should be provided without the .js extension (e.g., name="script1").
• Behavior: If this attribute is used, only the specified file is loaded, ignoring bulk loading.
• Example: name="script1"

exclude (Optional):

• Description: Specifies a comma-separated list of filenames (without the .js extension) to exclude from bulk loading.
• Behavior: This attribute is ignored if the name attribute is used.
• Example: exclude="script1,script2"

Examples:

Example 1: Bulk Loading with Exclusions

To load all JavaScript files in a theme’s js directory except for script1.js:

<txp:ebl_buildJs theme="my_theme" directory="js" exclude="script1" />

Directory structure:

my_theme/
  js/
    script1.js
    script2.js
    script3.js

Output:

<script src="https://your-site.com/skins/my_theme/js/script2.js" defer></script>
<script src="https://your-site.com/skins/my_theme/js/script3.js" defer></script>

Example 2: Load a Single File

To load only script1.js from the js directory:

<txp:ebl_buildJs theme="my_theme" directory="js" name="script1" />

Output:

<script src="https://your-site.com/skins/my_theme/js/script1.js" defer></script>

Example 3: Sorting Files

Files are naturally sorted (e.g., numerically or alphabetically) before being loaded. For example, files named 01-file.js, 02-file.js, and 10-file.js will load in numerical order.

Error Handling:

Common Errors:

• No Theme Specified:
  • Cause: The theme attribute is missing.
  • Output: <!-- Error: No theme name specified -->
• Directory Not Found:
  • Cause: The specified directory does not exist.
  • Output: <!-- Error: Specified directory does not exist: [full_path_to_directory] -->
• No JS Files Found:
  • Cause: The specified directory exists, but it contains no .js files.
  • Output: <!-- Error: No JS files found in directory: [full_path_to_directory] -->
• Specified File Not Found:
  • Cause: The name attribute specifies a file that does not exist in the directory.
  • Output: <!-- Error: Specified file does not exist: [file_name.js] -->

Installation:

1. Copy the plugin code into the Textpattern Plugins interface.
2. Install and enable the plugin.

Changelog:

Version 1.2:

• Added support for single-file loading via name attribute.
• Added exclusion feature via exclude attribute.
• Implemented natural sorting for bulk-loaded files.

Version 1.1:

• Initial release with core functionality.