Download the PHP package dd/evolutioncms-snippets-ddstringtools without Composer

(MODX)EvolutionCMS.snippets.ddStringTools

Tools for modifying strings.

Requires

• PHP >= 5.6
• (MODX)EvolutionCMS >= 1.1
• (MODX)EvolutionCMS.libraries.ddTools >= 0.60
• (MODX)EvolutionCMS.snippets.ddtypograph >= 2.6 (if the tools->typographer parameter is used)
• PHP.libraries.Parsedown >= 1.8.0-beta-7 (contains in archive)

Installation

Using (MODX)EvolutionCMS.libraries.ddInstaller

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

• 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.3</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:
  • 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 —, 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: ''

Numberer

• tools->numberer

  • Description: Convert and format numbers.
  • Valid values: object
  • Default value: —

• tools->numberer->isFloatAllowed

  • Description: Float number availability status.
  • Valid values: boolean
  • Default value: true

• tools->numberer->decimalsNumber

  • Description: Number of chars standing after comma.
  • Valid values:
    • integer
    • 0 — any
  • Default value: 0

• tools->numberer->isDecimalsFixed

  • Description: Allows formatting a number using fixed-point notation (e. g. 10.00) according to tools->numberer->decimalsNumber.
  • Valid values: boolean
  • Default value: false
• tools->numberer->thousandsSeparator
  • Description: Character used to separate thousands (e. g. ' ' for 1 234 567 or ',' for 1,234,567).
  • 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

All examples are written using HJSON, but if you want you can use vanilla JSON instead.

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

Returns:

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

Remove all tags completely

Returns:

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.

Returns:

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

Returns:

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

Returns:

Escape special characters for JavaScript (tools->charEscaper)

Returns:

Convert Markdown to HTML (tools->markdownParser)

Returns:

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

Returns:

Typography text (tools->typographer)

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

Returns:

Simple call with default parameters

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

Returns:

Thumbnail suffix (tools->pregReplacer)

Returns:

Numberer (tools->numberer)

Convert string to integer

Returns: 42

Convert string to float with maximum 2 decimal places

Returns: '42.76'

Format product price with fixed decimal places

Returns: '1999.00'

Format large number with space as thousands separator

Returns: '1 234 567'

Format price with comma as thousands separator and fixed decimal places

Returns: '1,234,567.89'

Parse price string with currency symbol, spaces and other invalid chars

Returns: '1234000.56'

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

Returns:

Use multiple tools together

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.

Returns:

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

Links

• Home page
• Telegram chat
• Packagist
• GitHub