SPFE Documentation | Collections > SPFE Development > Processing strings
Processing strings
Think
Strings are a means of inserting variable text into a topic. If you design a topic type, or write your own resolve code for a topic type, you may need to write code to process strings. In this case, you will need to understand how string processing works.
Strings are a core feature of SPFE, but different plugins may extend the strings feature in different ways. This topic explains how strings are implemented in core SPFE and the EPPO-simple plugin.
Core SPFE allows you to define strings in the configuration file. Strings can be specified at the content set level in /content-set/strings and at the topic set level in /topic-set/strings.
In your scripts, you can retrieve strings directly from the $config variable or you can retrieve individual strings using the sf:string function.
In EPPO-simple, SPFE's strings are treated as global strings and can be retrieved from anywhere in code or in content. In content, a string is retrieved using the string-ref element. Strings can be defined in content, in particular, they can be defined inside of fragment and fragment-ref elements as local-strings. A string defined locally within a fragment overrides a global string with the same id. A string defined in a fragment is carried over to all references to that fragement with the fragment-ref tag. However, local strings can also be defined in the fragment-ref tag, and these will override the strings defined in the original fragment. In effect, this allows you to call a fragment with a set of string substitutions.
Given an inline fragment definition like this:
<fragment id="my-fragment">
<local-strings>
<string id="boy-name">Jack</string>
<string id="girl-name">Jill</string>
<local-strings>
<p><string-ref id-ref="boy-name"/> and <string-ref id-ref="girl-name"/>
went up the hill.</p>
</fragment>
This will be resolved by the default EPPO-simple resolve scripts into:
<p>Jack and Jill went up the hill.</p>
But if this fragment is then inserted in a different place using <fragment-ref>, the string values can be redefined locally for that use.
<fragment-ref id-ref="my-fragment">
<local-strings>
<string id="girl-name">Emily</string>
</local-strings>
</fragment-ref>
The default EPPO-simple synthesis routines will use the local value the girl-name string, rendering the fragment as:
<p>Jack and Emily went up the hill.</p>
Plan
- Do I need to do something to support string processing in my own synthesis routines?
-
Strings are resolved during the synthesis process. If you write your own synthesis scripts you must provide support for string processing, if you want it for your topic type. However, if you use the standard EPPO-simple script modules that implement string processing, and you do not require any special string processing of your own, you will not need to do anything specific to support string processing.
If you are writing a synthesis script for a new topic type, make sure that the $strings variable is properly defined and that the $in-scope-strings variable is passed as a tunneling parameter to the top level content processing template. If you are not using schema componets that do this, you must do it yourself.
- Why would I want to do custom string processing?
-
In most cases, you will not want to do custom string processing. Custom string processing essentially allows you to control which definition of a string is used for string substitution. Unless you want to control string substitution in some way, there is no reason
The most likely reason for wanting to do custom string processing is to create an element that creates a local string scope. In the default EPPO-simple schemas, two elements fragment, and fragment-ref create local string scopes. This is so that you can define a different set of string substitutions each time you use a fragment. If you wanted to create an element that has local string values defined, the best approach would be to copy the method used in fragment and fragment-ref.