TemplateTag::replace - jcobban/Genealogy GitHub Wiki

$tag‑>replace($match, $replace)

Up: class TemplateTag

This method assists scripts to generate language specific warning and error messages based upon information in the template. If the instance of TemplateTag is an HTML paragraph element "p" then the method acts on the outerHTML value of the tag, otherwise it acts on the innerHTML value. The results therefore depend upon what is defined in the template. Messages indicating a problem which will prevent the script from working should be enclosed in <span>, while warning messages should be enclosed in <p>.

This method exists to make the code clearer as well as slightly shorter. The PHP function str_replace suffers because of non-intuitive parameter order. In most PHP string functions the first parameter is the string, followed by the parameters to control the function. But in str_replace the parameters come first followed by the string. This is particularly strange because str_replace is in a sense an extension of str_pos that not only finds the search text but also replaces it, but in str_pos, as with all other basic string functions the string to search, the "haystack", comes first followed by the search value, the "needle". This should be addressed by object-oriented strings, for example $string->replace('match','replace'), but unlike almost every other modern language PHP does not support this.

Parameters:

parameter contents
$match This identifies the token[s] in the template identified by '$xxxxx' whose values are to be replaced. If there is only one substitution this is a string. If there is more than one substitution this is an array of strings. Each value is the complete string that is to be replaced. For example if you intend to replace '$value' then this should be '$value'.
$replace This provides the value[s] to replace the tokens identified by $match. If $match is an array then $replace must be an array with the same number of entries.

For example:

    $msg     .= $template[$id]->replace('$value',$value);

is equivalent to the following if $id identifies a paragraph <p> tag:

    $text    = $template[$id]->outerHTML;
    $msg     .= str_replace('$value',
                            $value,
                            $text);

otherwise it is equivalent to:

    $text    = $template[$id]->innerHTML;
    $msg     .= str_replace('$value',
                            $value,
                            $text);

An example of message templates is:

  <div class="hidden" id="templates">
      <span id="CensusMissing">
          Census identifier not specified. 
      </span>
      <span id="invalidCensusId">
          Invalid value of CensusID='$value'. 
      </span>
      <p id="offsetIgnored">
        Offset value $value ignored.
      </p>

So you could customize an invalid CensusID message by:

    $msg       .= $template['invalidCensusId']->replace('$value',$censusvalue);

and warn about an an invalid starting offset by:

    $warn      .= $template['offsetIgnored']->replace('$value',$offset);

Next: TemplateTag::addChild($atag)

⚠️ **GitHub.com Fallback** ⚠️