b:format.substring

Substring splits the contents in side it into a smaller portion. This is often used when previewing content, like first few lines of a news item.

You can keep only a certain amount of characters from the beginning or the end, or until certain character or word is found.

Attributes

start (optional)	If start is a positive number, the returned string will start at the given position in string, counting from zero. If start is negative, the returned string will start at the given character from the end of string. If startbefore or startafter is defined, this attribute has no effect.
end (optional)	If end is a positive number, the resulting string will end at the given position in string (exclusive), counting from zero. If end is negative, the resulting string will end at the given position from the end of string. If any of length, endbefore or endafter are defined, this attribute has no effect.
length (optional)	Limits the length of the resulting string to given amount of characters. If length is negative, the resulting string will end at the given position from the end of string. When using a negative position, acts just like end attribute. Overrides end, endbefore and endafter attributes.
startbefore (optional)	Starts the resulting string from the first encountered given string. Overrides start attribute, if given.
startafter (optional)	Starts the resulting string after the first encountered given string. Overrides start attribute.
endbefore (optional)	Ends the resulting string before the first encountered given string. Overrides end attribute and is overridden by length attribute.
endafter (optional)	Ends the resulting string after the first encountered given string. Overrides end attribute and is overridden by length attribute.
prefix (optional)	Inserts given string before the resulting string if the start position has moved from the original starting position.
suffix (optional)	Inserts given string after the resulting string if the end position has moved from the original end position.

Examples

Previewing news items

Here's a common use for sub string, where we show first few lines of news items in the front page of the site.

<h3>Latest news</h3>
<b:get from="news" name="n" amount="2" orderby="metadata.created" direction="desc">
   <div class="newsitem">
       <h4><b:n.topic/></h4>
       <p>
           <b:format.substring length="24" suffix="..."><b:n.content/></b:format.substring>
           <a href="<b:n.metadata.url/>">Read more</a>
      </p>
   </div>
</b:get>

HTML source output

<h3>Latest news</h3>
   <div class="newsitem">
       <h4>News 1</h4>
       <p>
           The quick brown fox jump...
           <a href="/news/news-1">Read more</a>
      </p>
   </div>
   <div class="newsitem">
       <h4>News 2</h4>
       <p>
           The quick brown fox jump...
           <a href="/news/news-2">Read more</a>
      </p>
   </div>

Using attributes

Here's how different attributes behave. Let's assign a sentence in <b:value.story/> and start splitting that.

<b:value.story set="The quick brown fox jumps over the lazy dog"/>

<b:format.substring length="14"><b:value.story/></b:format.substring>
Outputs: The quick brow

<b:format.substring start="14"><b:value.story/></b:format.substring>
Outputs: n fox jumps over the lazy dog

<b:format.substring end="14"><b:value.story/></b:format.substring>
Outputs: The quick brow

<b:format.substring start="16" length="10"><b:value.story/></b:format.substring>
Outputs: fox jumps

<b:format.substring start="-5"><b:value.story/></b:format.substring>
Outputs: y dog

<b:format.substring end="-5"><b:value.story/></b:format.substring>
Outputs: The quick brown fox jumps over the laz

<b:format.substring startbefore="quick"><b:value.story/></b:format.substring>
Outputs: quick brown fox jumps over the lazy dog

<b:format.substring startafter="quick"><b:value.story/></b:format.substring>
Outputs:  brown fox jumps over the lazy dog

<b:format.substring endbefore="lazy"><b:value.story/></b:format.substring>
Outputs: The quick brown fox jumps over the

<b:format.substring endafter="lazy"><b:value.story/></b:format.substring>
Outputs: The quick brown fox jumps over the lazy

<b:format.substring startbefore="fox" endbefore="over"><b:value.story/></b:format.substring>
Outputs: fox jumps

<b:format.substring startafter="quick" prefix="The sneaky"><b:value.story/></b:format.substring>
Outputs: The sneaky brown fox jumps over the lazy dog