devot:eeDevoted to ExpressionEngine

PARAMETERS
**********************
type=‘word’, ‘char’, or ‘find’
to determine if count will count words or characters, or if it will find the first/last/all occurrence(s) of split_after or split_before. Default is ‘char’, if not specified.

    When using type=‘word’ these parameters apply:
     - count
     - insert
     - else_insert

    When using type=‘char’ these parameters apply:
     - count
     - insert
     - else_insert
     - round_words

    When using type=‘find’ these parameters apply:
     - split_after
     - insert (used with split_after)
     - split_before
     - insert_before (used with split_before)
     - split_when (applies to both split_after and split_before)
     - word_offset (applies only to split_after)

count=
position after which to insert the insert parameter text. Only applies to ‘word’ char ‘char’ types. Default is ‘0’, if not specified. HTML is counted, so be sure to consider your markup when counting.

insert=
text/html to be inserted IF length of original string between tag pairs is >= count parameter. Required for type=‘word’, type=‘char’, and when the split_after parameter is used with type=‘find’.

insert_before=
text/html to be inserted before the split_before string when type=‘find’. Required when split_before parameter is used.

else_insert=
text/html to be inserted IF length of original string between tag pairs is less than count parameter. Only applies to ‘word’ and ‘char’ types. Optional.

round_words= ‘y’ or ‘n’
Default is ‘y’. For type=‘char’ round_words=‘y’ will round up to the end of the current word before inserting insert. End of word is defined as a space. Optional.

split_after=
search string for type=‘find’ when splitting after this search string. Either split_after or split_before is required when type=‘find’.

split_before=
search string for type=‘find’ when splitting before this search string. Either split_after or split_before is required when type=‘find’.

split_when= ‘first’, ‘last’, ‘all’
Default is ‘first’. For type=‘find’ split_when=‘all’ will split each occurrence of split_after or split_before. For split_when=‘first’ it will only split the first occurrence of split_after or split_before. For split_when=‘last’ it will only split the last occurrence of split_after or split_before.

word_offset=
instead of inserting the value of the insert parameter immediately after where search_after is found, word_offset will offset the insert position by word_offset number of words. Currently only works with split_after. Optional.
 
 
USAGE
**********************
Wrap the text/html you want to divide between the String Divide tag pairs. There are three ways you can choose where to divide the string.

Example 1: Insert string after specific word count

{exp:string_divide type='word' count='2' insert=' green'}
	I love apples.
{/exp:string_divide}

Returns:
I love green apples.
 
 
Example 2: Insert string after specific character count

{exp:string_divide type='char' count='6' insert=' red'}
	I love apples.
{/exp:string_divide}

Returns:
I love red apples.
 
 
Example 3: Insert string after first occurrence of a custom string

{exp:string_divide type='find' split_after='</p>' insert='</div><div class="toggle">'}
<div>
  <p>paragraph one</p>
  <p>paragraph two</p>
  <p>paragraph three</p>
</div>
{/exp:string_divide}

Example 3 will return:

<div>
  <p>paragraph one</p>
</div>
<div class="toggle">
  <p>paragraph two</p>
  <p>paragraph three</p>
</section>

 
 
Example 4: Dividing at another custom string

{exp:string_divide type='find' split_after='-->' insert='</p></div><div class="toggle"><p>'}
<div>
  <p>Let's manually divide and insert here.<!-- divide here -->Then this long paragraph will appear in the next div.</p>
</div>
{/exp:string_divide}

Returns:

<div>
  <p>Let's manually divide and insert here.<!-- divide here --></p>
</div>
<div class="toggle">
  <p>Then this long paragraph will appear in the next div.</p>
</div>

 
 
Example 5: Insert channel field into another channel field!
Say your main body has multiple paragraphs. You can insert an image from another field into that content after the first paragraph so clients don’t have to try to make it work in the editor.

{exp:channel:entries channel="articles"}
  {exp:string_divide
      type="find"
      split_after="</p>"
      insert="<img src='{custom_image_field}' alt=''>"
      }
    {body_content}
  {/exp:string_divide}
{/exp:channel:entries}

Returns:

<p>
  Copy from body_content field. Donec ullamcorper nulla non metus auctor fringilla. 
</p>
<img src='/images/entries-image.jpg' alt=''>
<p>
  Integer posuere erat a ante venenatis dapibus posuere velit aliquet.
</p>

 
 
Example 6: Insert inner wrapper with initial offset of 2 words for all occurrences

{exp:string_divide type='find' split_after='<h1>' insert='<span>' word_offset='2' split_before='</h1>' insert_before='</span>' split_when='all'}
  <h1>You're So Freaking Sexy!</h1>
  <p>paragraph here</p>
  <h1>You're So Smooth on the Dance Floor!</h1>
  <p>paragraph here</p>
{/exp:string_divide}

Returns:

  <h1>You're So <span>Freaking Sexy!</span></h1>
  <p>paragraph here</p>
  <h1>You're So <span>Smooth on the Dance Floor!</span></h1>
  <p>paragraph here</p>

 
 
ADDITIONAL NOTES
**********************
- Remember to include in the count value any carriage returns between the exp:string_divide tag pairs.
- Leading and trailing spaces are trimmed off from the insert parameter but it is possible to insert a space using ‘ ’
 
 
CHANGELOG
**********************
Version 1.3 2013-07-14
- VERY IMPORTANT: renamed split_after_first to split_after
- added split_before parameter to insert something before a search string; split_after and split_before can be used together
- added split_when (first, last, all; default=first) for type=“find”
- added word_offset parameter to insert something word_offset words after split_after; only works for type=“find” split_after and not split_before

Version 1.2 2013-04-15
- fixed type=“word” to not drop punctuation (like < and /)
- added type=“find” and split_after_first parameter
- trim spaces, returns, tabs, etc from original string

Version 1.1 2012-12-11
- added else_insert parameter for if count is beyond the end of str
- added round_words parameter to “round up” to the end of the word when type = ‘char’

Version 1.0 2012-10-05
- original release