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');
$tag->rules->autoReopen();
$tag->rules->denyChild('X');
Method calls can be chained for convenience. The same example can be written as:
$configurator = new Configurator;
$tag = $configurator->tags->add('B');
$tag->rules->autoReopen()
->denyChild('X');
Rules can be:
- boolean — they accept
true
orfalse
as argument, withtrue
being the default. - targeted — they accept a tag name as argument.
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.
- allowChild
-
Example:
$tag->rules->allowChild('X');
Allows tag X to be used as a child of given tag.
- allowDescendant
-
Example:
$tag->rules->allowDescendant('X');
Allows tag X to be used as a non-child descendant of given tag.
- autoClose
-
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>
. - autoReopen
-
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, ifI
has an autoReopen rule, it will automatically be reopened whenB
closes. - breakParagraph
-
Example:
$tag->rules->breakParagraph();
This tag will break current paragraph if applicable.
- closeAncestor
-
Example:
$tag->rules->closeAncestor('X');
Forces all ancestor tags X to be closed when this tag is encountered.
- closeParent
-
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
. - createChild
-
Example:
$tag->rules->createChild('LI');
Automatically creates a LI tag at the first non-whitespace position after current tag.
- createParagraphs
-
Example:
$configurator->rootRules->createParagraphs();
Automatically creates paragraphs (HTML element
<p>
) to host content. Using two consecutive new lines indicates a paragraph break in content. - denyChild
-
Example:
$tag->rules->denyChild('X');
Prevents tag X to be used as a child of this tag.
- denyDescendant
-
Example:
$tag->rules->denyDescendant('X');
Prevents tag X to be used as a non-child descendant of this tag.
- disableAutoLineBreaks
-
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.
- enableAutoLineBreaks
-
Example:
$tag->rules->enableAutoLineBreaks();
Turns on the conversion of new lines to
<br/>
. Conversion applies to descendants as well, unless selectively disabled or suspended. - fosterParent
-
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.
- ignoreSurroundingWhitespace
-
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.
- ignoreTags
-
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.
- ignoreText
-
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.
- isTransparent
-
Example:
$tag->rules->isTransparent();
Indicates that this tag uses the transparent content model and their allow/deny rules are inherited from its parent.
- preventLineBreaks
-
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.
- requireParent
-
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.
- requireAncestor
-
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.
- suspendAutoLineBreaks
-
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. - trimFirstLine
-
Example:
$tag->rules->trimFirstLine();
Removes the first character inside given tag if it's a newline.