Skip to content

Custom Substitutions

Jump to bottom
9yz edited this page Aug 6, 2025 · 8 revisions

TextSubstitutions allows users to create custom substitutions that behave the same as the built-in substitutions. ts_customSubs.txt, ts_folderAssignments.txt, ts_hotCodes.txt, and ts_usefulSubstitutions.txt are provided as a framework to build upon when creating substitutions.

There is no limit to the number of custom substitution files, but they must follow these criteria:

  • Start with ts_
  • Be a .txt file.
  • Be in Bridge's Startup Scripts folder or the Startup Scripts/substitutions/ subdirectory.

Each custom substitution file contains multiple substitution rules. Each rule contains a single target and at least one replacement. Each portion of a rule is separated by the tab character and rules are separated by a newline.

The target is the string that you type, wrapped in a delimiter, and gets replaced by a replacement when the script is run. A rule should look like this:

target	replacement #1	replacement #2	replacement #3
//     ^tab            ^tab            ^tab

If a substitution has multiple replacements, the first one will be used unless another is specified. To specify a replacement, follow the target with a # and then the (1-indexed) index of the replacement:

[[target#2]]
// this would return "replacement #2"

Custom substitution rules can be multi-line to make complex substitutions easier to read. If the last character of a substitution rule is a backslash (\), the newline will be ignored and the substitution will continue to be read from the next line.

  • Leading tabs on the following line will be ignored.
  • If the following line is commented out or only contains tabs, it will be ignored and the next line will be used. For example:
favoritefruits	I love: \
apples, \
	ban\
		anas, \
	// I hate oranges
and mangoes!

Will result in [[favoritefruits]] being replaced with I love: apples, bananas, and mangoes!

Additional notes:

  • Custom substitutions are reloaded when Bridge is opened, when the "Reload Custom Substitutions" button in the preferences is pressed, or when changes are detected to an already-loaded substitution file.
  • Any blank lines or lines beginning with // (no leading whitespace) will be ignored.
  • Custom substitutions are case-sensitive (builtin substitutions are not).
  • Custom substitution files are not checked for correctness when loaded - incorrect formatting may lead to errors when running the script.
  • Duplicate substitutions (two substitutions with the same target) are not supported. This is not checked and may lead to undefined behavior.
  • The ordering of custom substitutions in their files is not important.

Examples

Example 1 - Basics

mywebsite	https://example.com

This would cause the text [[mywebsite]] to be replaced with https://example.com.

Example 2 - Recursive Substitution I

shortlocation	[[mCity]], [[mState]]

If the file's IPTC City and State fields are set to San Francisco and California, respectively, this would cause [[shortlocation]] to be replaced with San Francisco, California.

Example 3 - Recursive Substitution II

shortlocation	[[mCity]], [[mState]]
timeplace	Taken on [[tdateps]] in [[shortlocation]].

For a photo taken on 2024-01-20 with the IPTC City and State fields set to San Francisco and California respectively, this would cause [[timeplace]] to be replaced with Taken on January 20, 2024 in San Francisco, California.

Example 4 - Enumerated Replacements

subject	Dash F.	San Francisco	Photographer

By default, [[subject]] will be replaced with Dash F.. To access the rest of the replacements, follow the target with a # and the (1-indexed) index of the value you wish to access. For example, [[subject#1]] will be replaced with Dash F., [[subject#2]] with San Francisco, and [[subject#3]] with Photographer.

Example 5 - Recursive Substitution III

s983746	Jane Smith	JS	Chicago
s509124	Jane Smith	JS	Chicago
s192883	Brock Thock	BT	London
s039091	River Shea	RS	Taipei
s49281	River Shea	RS	Taipei

photogName	[[s[[cSerial]]#1]]
photogAbbr	[[s[[cSerial]]#2]]
photogCity	[[s[[cSerial]]#3]]

Substitutions can be nested and recurse to any depth.

Above is a list of camera serial numbers and the photographers they are assigned to, along with the photographer's initals and location. Using the substitutions below the list, a photo editor looking in to quickly swap in the photographer's name just has to use the target [[photogName]]. This will be replaced by [[s[[cSerial]]#1]]. [[cSerial]] is a builtin replacement that returns the serial number of the camera that took the picture. If the camera's SN is 039091, this will resolve to [[s039091#1]]. Finally, when s039091 is looked up, it will be identified as one of River's cameras and #1 will grab the first replacement - River Shea

Clone this wiki locally