Tag rules

Rules are contained in s9e\TextFormatter\Configurator\Collections\Ruleset.
They are set on a per-tag basis, for example:

$configurator = new Configurator;

$tag = $configurator->tags->add('B');

Method calls can be chained for convenience. The same example can be written as:

$configurator = new Configurator;

$tag = $configurator->tags->add('B');

Rules can be:

  • boolean -- they accept true or false as argument, with true being the default
  • targeted -- they accept a tag name as argument
  • other -- defaultChildRule() and defaultDescendantRule() accept either "allow" or "deny"

Rules that apply to descendants also apply to children. Rules that apply to ancestors also apply to the parent. A tag that is explicitly denied cannot be allowed by another rule.


Example: $tag->rules->allowChild('X');

Allows tag X to be used as a child of given tag.


Example: $tag->rules->allowDescendant('X');

Allows tag X to be used as a descendant of given tag.


Example: $tag->rules->autoClose(true);

Start tags of this tag are automatically closed if they are not paired with an end tag. This rule exists primarily to deal with void elements such as <img>.


Example: $tag->rules->autoReopen(false);

Automatically reopens this tag if it's closed by a non-matching tag. This rule helps dealing with misnested tags such as <B><I></B></I>. In this case, if I has an autoReopen rule, it will automatically be reopened when B closes.


Example: $tag->rules->breakParagraph();

This tag will break current paragraph if applicable.


Example: $tag->rules->closeAncestor('X');

Forces all ancestor tags X to be closed when this tag is encountered.


Example: $tag->rules->closeParent('LI');

Forces current parent LI to be closed when this tag is encountered. Helps dealing with optional end tags. For instance, if LI has a closeParent rule targeting LI, the following <LI>one<LI>two is interpreted as <LI>one</LI><LI>two.


Example: $tag->rules->createChild('LI');

Automatically creates a LI tag at the first non-whitespace position after current tag.


Example: $configurator->rootRules->createParagraphs();

Automatically creates paragraphs (HTML element <p>) to host content. Using two consecutive new lines indicates a paragraph break in content.


Example: $tag->rules->defaultChildRule('deny');

If defaultChildRule is set to 'deny', all tags that are not targeted by an allowChild rule will be denied. By default, defaultChildRule is set to 'allow', which means that all tags are allowed as children unless they are targeted by a denyChild rule.


Example: $tag->rules->defaultDescendantRule('deny');

Same as defaultChildRule but with descendants.


Example: $tag->rules->denyChild('X');

Prevents tag X to be used as a child of this tag.


Example: $tag->rules->denyDescendant('X');

Prevents tag X to be used as a descendant of this tag.


Example: $tag->rules->disableAutoLineBreaks();

Turns off the conversion of new lines in the scope of this tag. Conversion can be turned back on by descendants.


Example: $tag->rules->enableAutoLineBreaks();

Turns on the conversion of new lines to <br/>. Conversion applies to descendants as well, unless selectively disabled or suspended.


Example: $tag->rules->fosterParent('X');

Forces current parent X to be closed when this tag is encountered, and reopened as its child. If this tag is a self-closing tag, X is reopened as its next sibling.


Example: $tag->rules->ignoreSurroundingWhitespace();

Whether whitespace around this tag should be ignored. Useful for allowing whitespace around block elements without extra newlines being displayed. Limited to 1 newline before the template, 1 newline at the start and at the end of its content, and up to 2 newlines after it.


Example: $tag->rules->ignoreTags();

Silently ignore all tags until current tag is closed. Does not effect the automatic conversion of new lines or system tags such as line breaks, paragraphs breaks and ignore tags.


Example: $tag->rules->ignoreText();

Prevents plain text from being displayed as a child of this tag. Also disables line breaks. This rule deals with elements that do not allow text, such as lists. Does not apply to descendants.


Example: $tag->rules->isTransparent();

Indicates that this tag uses the transparent content model and their allow/deny rules are inherited from its parent.


Example: $tag->rules->preventLineBreaks();

Prevent manual line breaks in this tag's context. Does not apply to descendants. Does not apply to automatic line breaks.


Example: $tag->rules->requireParent('X');

Prevents this tag from being used unless it's as a child of X. If multiple requireParent rules are set, only one has to be satisfied.


Example: $tag->rules->requireAncestor('X');

Prevents this tag from being used unless it's as a descendant of X. If multiple requireAncestor rules are set, all of them must be satisfied.


Example: $tag->rules->suspendAutoLineBreaks();

Temporarily turns off the conversion of new lines into br elements in this tag's text. Does not apply to descendants.


Example: $tag->rules->trimFirstLine();

Removes the first character inside given tag if it's a newline.