Skip to content

Latest commit

 

History

History
673 lines (507 loc) · 16 KB

README.md

File metadata and controls

673 lines (507 loc) · 16 KB

(MODX)EvolutionCMS.snippets.ddStringTools

Tools for modifying strings.

Requires

Installation

Using (MODX)EvolutionCMS.libraries.ddInstaller

Just run the following PHP code in your sources or Console:

// Include (MODX)EvolutionCMS.libraries.ddInstaller
require_once(
	$modx->getConfig('base_path')
	. 'assets/libs/ddInstaller/require.php'
);

// Install (MODX)EvolutionCMS.snippets.ddStringTools
\DDInstaller::install([
	'url' => 'https://github.com/DivanDesign/EvolutionCMS.snippets.ddStringTools',
]);
  • If ddStringTools is not exist on your site, ddInstaller will just install it.
  • If ddStringTools is already exist on your site, ddInstaller will check it version and update it if needed.

Manually

1. Elements → Snippets: Create a new snippet with the following data

  1. Snippet name: ddStringTools.
  2. Description: <b>2.2</b> Tools for modifying strings..
  3. Category: Core.
  4. Parse DocBlock: no.
  5. Snippet code (php): Insert content of the ddStringTools_snippet.php file from the archive.

2. Elements → Manage Files:

  1. Create a new folder assets/snippets/ddStringTools/.
  2. Extract the archive to the folder (except ddStringTools_snippet.php).

Parameters description

  • inputString

    • Description: The input string.
    • Valid values:
      • string
      • The input string can also be set as a PHP object or array (e. g. for calls through $modx->runSnippet). In this case, it will be converted to JSON first.
        • object
        • array
    • Default value: ''

  • tools

    • Description: List of string tools to be applied to inputString. Tools are called in accordance with the specified order.
    • Valid values:
      • stirngJsonObject — as JSON
      • stringHjsonObject — as HJSON
      • stringQueryFormatted — as Query string
      • It can also be set as a PHP object or array (e. g. for calls through $modx->runSnippet).
        • arrayAssociative
        • object
    • Default value: '{}'

  • tools->{$toolName}

    • Description: A tool, when the key is the tool name and the value is the tool parameters.
      • Tool names are case insensitive (the following names are equal: caseConverter, Caseconverter, caseconverter, etc).
    • Valid values:
      • object — an object with tool parameters (see below)
      • boolean — for simple tools without parameters or if you need to use default parameters (if possible), just pass true
    • Default value: —.

Case converter

  • tools->caseConverter

    • Description: Perform case folding on a string. Unicode is supported.
    • Valid values: object
    • Default value: —.

  • tools->caseConverter->toLower

    • Description: Make a string lowercase.
    • Valid values: boolean
    • Default value: false

  • tools->caseConverter->toUpper

    • Description: Make a string uppercase.
    • Valid values: boolean
    • Default value: false

Markdown parser

  • tools->markdownParser

    • Description: Parse Markdown using Parsedown library.
    • Valid values:
      • boolean — if you need to parse with default params, just pass true
      • object — or an object with parameters (see below)
    • Default value: false

  • tools->markdownParser->parseInline

    • Description: Parse only inline elements.
    • Valid values: boolean
    • Default value: false

Typographer

  • tools->typographer

    • Description: Typography text using EvolutionCMS.snippets.ddTypograph.
      • Parameters have to be passed to EvolutionCMS.snippets.ddTypograph.
      • More info in its documentation.
    • Valid values:
      • boolean — if you need to typography with default params, just pass true
      • object — or an object with parameters (see below)
    • Default value: false

  • tools->typographer->optAlign

    • Description: Optical alignment (hanging punctuation).
    • Valid values: boolean
    • Default value: false

  • tools->typographer->optAlign_useClasses

    • Description: Use CSS classes instead of inline styles for optical alignment (<span class="oa_comma_b"> instead of <span style="margin-right:-0.2em;">).
      • If the parameter is enabled, don't forget to specify the following CSS rules on your site: 
         .oa_obracket_sp_s {margin-right:0.3em;}
 .oa_obracket_sp_b {margin-left:-0.3em;}
 .oa_obracket_nl_b {margin-left:-0.3em;}
 .oa_comma_b {margin-right:-0.2em;}
 .oa_comma_e {margin-left:0.2em;}
 .oa_oquote_nl {margin-left:-0.44em;}
 .oa_oqoute_sp_s {margin-right:0.44em;}
 .oa_oqoute_sp_q {margin-left:-0.44em;}
    • Valid values:
      • 0
      • 1
    • Default value: 0

  • tools->typographer->text_paragraphs

    • Description: Section signs and line breaks insertion.
    • Valid values: boolean
    • Default value: false

  • tools->typographer->text_autoLinks

    • Description: Marking links (including email ones).
    • Valid values: boolean
    • Default value: false

  • tools->typographer->etc_unicodeConvert

    • Description: Convert HTML entities into Unicode (— instead of &mdash;, etc).
    • Valid values: boolean
    • Default value: true

  • tools->typographer->noTags

    • Description: Whether HTML element insertion is allowed or not.
      • There are cases when using tags causes the text to be invalid, for example, using the snippet inside of an HTML attribute.
    • Valid values: boolean
    • Default value: false

  • tools->typographer->excludeTags

    • Description: HTML tags which content will be ignored by snippet.
    • Valid values: stringCommaSeparated
    • Default value: 'notg,code'

Tag remover

  • tools->tagRemover

    • Description: Strip HTML and PHP tags from a string.
    • Valid values:
      • boolean — if you need to remove all tags, just pass true
      • object — or an object with parameters (see below)
    • Default value: false

  • tools->tagRemover->allowed

    • Description: Use the parameter to specify tags which should not be stripped (e. g. <p><div>).
    • Valid values: string
    • Default value: ''

Special char converter

  • tools->specialCharConverter
    • Description: Convert special characters to HTML entities.
    • Valid values: boolean
    • Default value: false

Chars escaper (e. g. for JS)

  • tools->charEscaper

    • Description: Escape special characters for JS.
    • Valid values:
      • boolean — if you need to escape with default params, just pass true
      • object — or an object with parameters (see below)
    • Default value: false

  • tools->charEscaper->backslashes

    • Description: Escape backslashes ('\\' will be replaced to '\\\\').
    • Valid values: boolean
    • Default value: true

  • tools->charEscaper->lineBreaks

    • Description: Escape line breaks ("\r\n", "\r", "\n" will be replaced to '\r\n').
    • Valid values: boolean
    • Default value: true

  • tools->charEscaper->tabs

    • Description: Escape tabs (' ' (tab) will be replaced to ' ' (space)).
    • Valid values: boolean
    • Default value: true

  • tools->charEscaper->modxPlaceholders

    • Description: Escape (MODX)EvolutionCMS placeholders ('[+' and '+]' will be replaced to '\[\+' and '\+\]').
    • Valid values: boolean
    • Default value: true

  • tools->charEscaper->quotes

    • Description: Escape quotes ("'" and '"' will be replaced to "\'" and '\"').
    • Valid values: boolean
    • Default value: true

URL encoder

  • tools->urlEncoder
    • Description: URL-encode according to RFC 3986.
    • Valid values: boolean
    • Default value: false

Placeholder remover

  • tools->placeholderRemover
    • Description: Remove placeholders like [+placeholder+].
    • Valid values: boolean
    • Default value: false

Preg replacer

  • tools->pregReplacer

    • Description: Perform a regular expression search and replace.
    • Valid values: object
    • Default value: —

  • tools->pregReplacer->pattern

    • Description: The pattern to search for.
      • You can omit /, the default will be / + /u.
    • Valid values: string
    • Required

  • tools->pregReplacer->replacement

    • Description: The string to replace.
    • Valid values: string
    • Default value: ''

Tpl parser

  • tools->tplParser

    • Description: Gets the chunk contents by its name and parse it.
      • If inputString is empty, the chunk content will not be returned, just an empty string.
    • Valid values: object
    • Default value: —

  • tools->tplParser->tpl

    • Description: Chunk name or code via @CODE: prefix.
      • Available placeholders:
        • [+snippetResult+] — the inputString modified by previous tools
    • Valid values:
      • stringChunkName
      • string — use inline templates starting with @CODE:
    • Required

  • tools->tplParser->placeholders

    • Description: Additional data has to be passed into the tools->tplParser->tpl.
      • Nested objects and arrays are supported too:
        • {"someOne": "1", "someTwo": "test" } => [+someOne+], [+someTwo+].
        • {"some": {"a": "one", "b": "two"} } => [+some.a+], [+some.b+].
        • {"some": ["one", "two"] } => [+some.0+], [+some.1+].
    • Valid values: object
    • Default value: —

Examples

Convert characters to lowercase (tools->caseConverter->toLower)

[[ddStringTools?
	&inputString=`Some STRING with DiFFerEnt case`
	&tools=`{
		"caseConverter": {
			"toLower": true
		}
	}`
]]

Returns:

some string with different case

Strip HTML and PHP tags from a string (tools->tagRemover)

Remove all tags completely

[[ddStringTools?
	&inputString=`<div class="someTrash"></div><p><b>Some</b> <a href="#">sample</a> <i>text</i>.</p>`
	&tools=`{
		"tagRemover": true
	}`
]]

Returns:

Some sample text.

Remove all tags except <p> and <a> (tools->tagRemover->allowed)

If you want to preserve some tags, pass an object with property allowed instead of true.

[[ddStringTools?
	&inputString=`<div class="someTrash"></div><p><b>Some</b> <a href="#">sample</a> <i>text</i>.</p>`
	&tools=`{
		"tagRemover": {
			"allowed": "<p><a>"
		}
	}`
]]

Returns:

<p>Some <a href="#">sample</a> text.</p>

Convert special characters to HTML entities (tools->specialCharConverter)

[[ddStringTools?
	&inputString=`<p>Some <a href="#">sample</a> text.</p>`
	&tools=`{
		"specialCharConverter": true
	}`
]]

Returns:

&lt;p&gt;Some &lt;a href="#"&gt;sample&lt;/a&gt; text.&lt;/p&gt;

URL-encode according to RFC 3986 (tools->urlEncoder)

[[ddStringTools?
	&inputString=`tags[]=Maps&tags[]=URLs`
	&tools=`{
		"urlEncoder": true
	}`
]]

Returns:

tags%5B%5D%3DMaps%26tags%5B%5D%3DURLs

Escape special characters for JavaScript (tools->charEscaper)

<script>
	$('body').append('[[ddStringTools?
		&inputString=`
			<p class="test">Some <a href="#">sample</a> text.</p>
			<p>New line.</p>
		`
		&tools=`{
			"charEscaper": true
		}`
	]]');
<script>

Returns:

<script>
	$('body').append('\r\n <p class=\"test\">Some <a href=\"#\">sample</a> text.</p>\r\n <p>New line.</p>\r\n ');
<script>

Convert Markdown to HTML (tools->markdownParser)

[[ddStringTools?
	&inputString=`
# Markdown example

Some text in _Markdown_.
	`
	&tools=`{
		"markdownParser": true
	}`
]]

Returns:

<h1>Markdown example</h1>
<p>Some text in <em>Markdown</em>.</p>

You can also parse inline markdown only (tools->markdownParser->parseInline)

[[ddStringTools?
	&inputString=`Some text in _Markdown_.`
	&tools=`{
		"markdownParser": {
			"parseInline": true
		}
	}`
]]

Returns:

Some text in <em>Markdown</em>.

Typography text (tools->typographer)

With optical alignment (tools->typographer->optAlign)

[[ddStringTools?
	&inputString=`<p>Some text containing "quoted" text.</p>`
	&tools=`{
		"typographer": {
			"optAlign": true
		}
	}`
]]

Returns:

<p>Some text containing<span style="margin-right:0.44em;"> </span><span style="margin-left:-0.44em;">“</span>quoted” text.</p>

Simple call with default parameters

[[ddStringTools?
	&inputString=`Some text for typography.`
	&tools=`{
		"typographer": true
	}`
]]

Remove placeholders like [+placeholder+] (tools->placeholderRemover)

[[ddStringTools?
	&inputString=`Some [+thing+] with [+placeholder1+] and [+placeholder2+].`
	&tools=`{
		"placeholderRemover": true
	}`
]]

Returns:

Some  with  and .

Thumbnail suffix (tools->pregReplacer)

[[ddStringTools?
	&inputString=`assets/images/someImage.png`
	&tools=`{
		"pregReplacer": {
			"pattern": "(.*)(\.\D*)",
			"replacement": "$1_50x50$2"
		}
	}`
]]

Returns:

assets/images/someImage_50x50.png

Get the chunk content and pass some placeholders (tools->tplParser)

[[ddStringTools?
	&inputString=`Some input string text.`
	&tools=`{
		"tplParser": {
			"tpl": "@CODE:[+before+]<p>[+snippetResult+]</p>[+after+]",
			"placeholders": {
				"before": "<p>Some start text.</p>",
				"after": "<p>Some end text.</p>"
			}
		}
	}`
]]

Returns:

<p>Some start text.</p><p>Some input string text.</p><p>Some end text.</p>

Use multiple tools together

[[ddStringTools?
	&inputString=`<div class="someTrash"></div><p><b>Some</b> <a href="#">sample</a> <i>text</i>. [+somePlaceholder+]</p>.`
	&tools=`{
		"placeholderRemover": true,
		"typographer": true,
		"tagRemover": {
			"allowed": "<p><a>"
		},
		"caseConverter": {
			"toLower": true
		},
		"charEscaper": true
	}`
]]

Tools are called in accordance with the specified order:

  1. First placeholders like [+somePlaceholder+] will removed, then
  2. Text will typographied,
  3. All HTML tags except <p> and <a> will removed,
  4. Text will converted to lowercase,
  5. And escaped for JS.

Pass inputString as an array through $modx->runSnippet

The input string can also be set as a PHP object or array (e. g. for calls through $modx->runSnippet). In this case, it will be converted to JSON first.

$modx->runSnippet(
	'ddStringTools',
	[
		// This is an array, not string
		'inputString' => [
			'someObjectField' => '[+somePlaceholder+] need to be removed.',
			// And this is an array too
			'otherObjectField' => [
				'deepField' => '[+placeholders+] will be removed in any depth.',
			],
		],
		'tools' => [
			'placeholderRemover' => true,
		],
	]
);

Returns:

{
	"someObjectField": " need to be removed.",
	"otherObjectField": {
		"deepField": " will be removed in any depth."
	}
}

Run the snippet through \DDTools\Snippet::runSnippet without DB and eval

// Include (MODX)EvolutionCMS.libraries.ddTools
require_once(
	$modx->getConfig('base_path') .
	'assets/libs/ddTools/modx.ddtools.class.php'
);

// Run (MODX)EvolutionCMS.snippets.ddStringTools
\DDTools\Snippet::runSnippet([
	'name' => 'ddStringTools',
	'params' => [
		'inputString' => '<div class="someTrash"></div><p><b>Some</b> <a href="#">sample</a> <i>text</i>. [+somePlaceholder+]</p>.',
		// `tools` in this case can be set as a native PHP array or object
		'tools' => [
			'placeholderRemover' => true,
			'typographer' => true,
			'tagRemover' => [
				'allowed' => '<p><a>',
			],
			'caseConverter' => [
				'toLower' => true,
			],
			'charEscaper' => true,
		],
	],
]);

Links