Config files

The DropScriptTemplate.php provides support for configuration files.

This functionality is shared between all the DropScripts which are based on DropScriptTemplate.php (AutoTitle.php, UpdateClass.php...).

Configuration files are JSON-based text files which can contain any settings the DropScript might need.

Setting names in these files are double-quoted, and they are case-sensitive.

The config files are not space-sensitive.

In the sample files I've moved individual settings to a separate line for readability. The setting separator character is a comma, which is to be used to separate multiple settings.

Some shared settings have values that are pre-defined by the DropScriptTemplate.php.

In a config file, you can either override some predefined default settings, or you can set script-specific settings as desired.

Global vs Project-Specific Settings

Config files are retrieved from two possible locations.

First of all, you can store a config file 'beside' the PHP file for the DropScript.

For an example, look at the screenshot below: you should see MyNewScript.config.txt next to MyNewScript.php.

This is the 'global' config file. Here, a user of the script can set up their system-wide configuration options.

Additionally, config files can also be retrieved from the parent folder of a file being processed (most often the OEBPS folder for the exploded EPUB).

This is to allow project-specific settings.

This way, a user could set up the script one way, and then override some of those settings for just one particular EPUB.

When one of the EPUB files (e.g. WaterlooExpress_int-1.xhtml) from the above screenshot is processed with the MyNewScript.php script, the script will prioritize the leftmost settings file.

The program logic follows a hierarchy for resolving settings.

At the bottom level, the DropScriptTemplate.php contains some settings 'baked in'.

These settings are then augmented and/or overridden by a config file next to the .php file (e.g. AutoTitle.config.txt...).

These settings, in turn, are further augmented or overridden by a settings file of the correct name embedded in the EPUB project.

The settings files need not contain all possible settings.

They only need to specify what is different from the global or baked-in settings.

Backup Of Dropped Files

By default, when a file is processed by a script based on this DropScriptTemplate.php, one or more backups will be retained.

Note: it is normal to drag/drop a file, and see no backup file is made.

This happens when the file did not need any processing - e.g. you'd use AutoTitle on a file that already has a title. The file is not changed, and hence, no backup is made.

Backup File Name Extension

The file name extension to use for backup files is defined by a setting in the config file.

By default the file name extension is old.

If you add the "backupFileNameExtension" setting to your config file you can override this and pick a different file name extension.

Make sure to include commas between the different settings in the config file.

Example: you could change the AutoTitle.config.txt file to look as follows:

{
	"forcedReplaceTitle": 0,
	"keepTitleSubtags":   0,
	"backupFileNameExtension": "autotitle.xhtml"
}

and from then on, the backup files processed with the AutoTitle DropScript would get file name extension autotitle.xhtml

How Many Backups To Retain

By default, up to 5 backup files will be retained for any processed file.

You can change this by modifying the maxBackupCount config setting.

If maxBackupCount is 0, no backups are made.

If maxBackupCount is greater than zero the backups will be

    SomeFile.xhtml ->
        SomeFile.xhtml.old
        SomeFile.xhtml_1.old
        SomeFile.xhtml_2.old
        ...
        SomeFile.xhtml_5.old

The SomeFile.xhtml.old (without numerical _n infix) is special: once made, it is never overwritten.

It stores the content of the original file from before you ran the script for the first time.

SomeFile.xhtml_1.old, SomeFile.xhtml_2.old..., on the other hand, rotate.

The _1 file is the newest, the _5 file is the oldest.

The DropToScript App's Requirements For DropScripts

The 'DropToScript' drag-and-drop app will work with many kinds of scripts.

The main requirement is that they need to be command-line scripts which take a single parameter, which is the path to the file to be processed.

For example, if the file to be processed is /my/file/test.html and the command line script is located at /Users/kris/Desktop/sampleScript.php then the following command line should process the file and replace it with a new file:

php /Users/kris/Desktop/sampleScript.php /my/file/test.html

After this, the test.html file should have been updated with whatever changes are performed by sampleScript.php

DropToScript is not limited to just php scripts. It can handle all kinds of scripts: command-line scripts, PHP scripts, Python scripts, Node.js scripts or any other kind of script.

DropScript Template

To make developing these scripts easier, I've made a 'template' PHP script.

The features of this template are shared in scripts like AutoTitle.php and UpdateClass.php

It should be fairly easy to make a similar template for Python or JavaScript, but PHP works just fine, so I only did one.

The template is located at

https://github.com/BCLibCoop/nnels-a11y-publishing/tree/master/DropScripts/DropScriptTemplate

It contains some ready-made infrastructure for useful features.

Basic Structure

Any DropScript based on this template has two areas: a common area which is shared between all scripts derived from this template, and a custom area where the actual 'meat' of the script is located.

If you open up DropScriptTemplate.php in a text editor, you should see a line

// -- AUTO-GENERATED CODE BELOW. DO NOT EDIT BELOW

Anything above that line is the custom area.

Anything including or below that line is the common area.

To create a new DropScript, make a copy of the DropScriptTemplate directory.

Rename the directory and the files in it. E.g. if I want to create a new script 'MyNewScript' I'd set things up as follows:

Now you will open up the new files and modify them as desired. Do not make any changes below the line

// -- AUTO-GENERATED CODE BELOW. DO NOT EDIT BELOW

There is an automated release script in the DropScripts folder, makerelease.command.

When double-clicked on a properly installed Mac, this script will automatically update all DropScripts and refresh the common area of all the scripts with a copy of the 'master' from the DropScriptTemplate.

It will then create a new release of the DropToScript...zip file in the Releases folder, and your new script will automatically be included.

Make sure to increase the script version number in DropScripts/version.txt prior to running makerelease.command.

To make changes in the common area, you should always make them in the DropScriptTemplate.php, then re-run makerelease.command. Do not change the common area in any other DropScript, as it will be overwritten on the next run of makerelease.command.

Command-line Use

The DropScriptTemplate.php starts with:

#!/usr/bin/php
<?php
...

and it is set to be an executable script.

That means that any PHP scripts derived from this template can be used as command-line tools on Mac and Linux: no need to prefix the script with /usr/bin/php to run it.

Default Settings

The default settings that are baked in are:

{
  "acceptFileNameExtensions": [ "html", "htm", "xhtml", "xht" ],
  "backupFileNameExtension": "old",
  "maxBackupCount": 5,
  "logLevel": 0,
  "logEntryExit": 0,
  "logToFile": 0,
  "logToConsole": 1,
  "ignoreDOMParserErrors": 1
}

Logging

The DropScriptTemplate.php contains logging infrastructure.

The idea is that anytime anything fails or causes something unexpected, a log... function should be called.

In the config file, you can set a "logLevel" setting to 0, 1, 2, 3, or 4.

Depending on the number, more or less logging information will be provided.

The default when this is omitted is:

    "logLevel": 0

Also, most common functions have calls to logEntry and logExit.

By changing your config file to have a "logEntryExit": 1 setting this feature is turned on.

At the same time, you also need to set "logLevel": 3 (LOG_NOTE) - otherwise the entry/exit logging will be suppressed.

This is useful for diagnosing issues.

Diagnosing issues

When something does not work as expected, you'd first edit the config file and set the logLevel to 2 or higher, and then you'd use the script from the command line (to make it easier to read the logging information).

Try to avoid diagnostics with using the DropToScript wrapper: it is hard to read the logging info.

It is OK to add a logLevel and logEntryExit entry to a project-specific settings file.