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

(MODX)EvolutionCMS.snippets.ddGetDocumentField

Snippet gets the necessary document fields (and TVs) by its id.

Requires

• PHP >= 5.6
• (MODX)EvolutionCMS >= 1.1
• (MODX)EvolutionCMS.libraries.ddTools >= 0.60
• (MODX)EvolutionCMS.snippets.ddTypograph >= 2.5 (if typography is required)

Installation

Using (MODX)EvolutionCMS.libraries.ddInstaller

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

• If ddGetDocumentField is not exist on your site, ddInstaller will just install it.
• If ddGetDocumentField 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: ddGetDocumentField.
2. Description: <b>2.15</b> Snippet gets the necessary document fields (and TVs) by its id..
3. Category: Core.
4. Parse DocBlock: no.
5. Snippet code (php): Insert content of the ddGetDocumentField_snippet.php file from the archive.

2. Elements → Manage Files:

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

Parameters description

Data provider parameters

• dataProviderParams

  • Description: Parameters to be passed to the provider.
  • Valid values:
    • stringJsonObject — as JSON
    • stringHjsonObject — as HJSON
    • stringQueryFormatted — as Query string
    • It can also be set as a native PHP object or array (e. g. for calls through \DDTools\Snippet::runSnippet or $modx->runSnippet):
      • arrayAssociative
      • object
  • Default value: —

• dataProviderParams->resourceId

  • Description: Document identifier.
  • Valid values: integer
  • Default value: $modx->documentIdentifier (current document)

• dataProviderParams->resourceFields

  • Description: Document field(s) to get separated by commas.
  • Valid values:
    • stringCommaSeparated
    • '' — if the parameter is empty, the snippet will try to search fields in outputterParams->tpl (something like [+docField+]).
  • Default value: ''

• dataProviderParams->resourceFields[i]

  • Description: Fields and their aliases must be separated by '=' if aliases are required while returning the results (for example: 'pagetitle=title,content=text').
  • Valid values:
    • string — document field
    • stringSeparated — document field and it's alias
  • Required

• dataProviderParams->resourceFieldsAlternative

  • Description: Alternative document field(s) to get if the main is empty separated by commas.
  • Valid values: stringCommaSeparated
  • Default value: —
• dataProviderParams->resourceFieldsAlternative[i]
  • Description: Document field.
  • Valid values: string
  • Required

Output format parameters

• outputter

  • Description: Format of the output.
  • Valid values:
    • 'string'
    • 'object'
  • Default value: 'string'

• outputterParams

  • Description: Parameters to be passed to the specified outputter.
  • Valid values:
    • stringJsonObject — as JSON
    • stringHjsonObject — as HJSON
    • stringQueryFormatted — as Query string
    • It can also be set as a native PHP object or array (e. g. for calls through \DDTools\Snippet::runSnippet or $modx->runSnippet):
      • arrayAssociative
      • object
  • Default value: —

• outputterParams->typography

  • Description: Need to typography result?
  • Valid values:
    • 0
    • 1
  • Default value: 0

• outputterParams->escapeForJS

  • Description: Need to escape special characters from result?
  • Valid values:
    • 0
    • 1
  • Default value: 0
• outputterParams->URLEncode
  • Description: Need to URL-encode result string?
  • Valid values:
    • 0
    • 1
  • Default value: 0

Outputter → String (&outputter=`string`)

• outputterParams->tpl

  • Description: Chunk to parse result.
    • Available placeholders:
      • [+anyNameFromDocFieldParameter+] — Any document field (or TV).
      • [+url+] — Document URL.
  • Valid values:
    • stringChunkName
    • string — use inline templates starting with @CODE:
  • Required

• outputterParams->placeholders

  • Description: Additional data has to be passed into outputterParams->tpl.
    • Arrays are supported too: some[a]=one&some[b]=two => [+some.a+], [+some.b+]; some[]=one&some[]=two => [+some.0+], [some.1].
  • Valid values: object
  • Default value: —

• outputterParams->docFieldsGlue

  • Description: String for join the fields (if outputterParams->tpl is not used).
  • Valid values: string
  • Default value: ''

• outputterParams->emptyResult

  • Description: What will be returned if the snippet result is empty?
  • Valid values: string
  • Default value: ''
• outputterParams->removeEmptyFields
  • Description: Remove resource fields with empty values ('') from result.
  • Valid values: boolean
  • Default value: true

Outputter → Object (&outputter=`object`)

• outputterParams->removeEmptyFields

  • Description: Remove resource fields with empty values ('') from result.
  • Valid values: boolean
  • Default value: false

• outputterParams->format

  • Description: Output format.
    • Values are case insensitive (the following values are equal: 'stringjsonauto', 'stringJsonAuto', 'STRINGJSONAUTO', etc).
  • Valid values:
    • The snippet can return result as a string:
      • 'stringJsonAuto' — stringJsonObject or stringJsonArray depends on result object
      • 'stringJsonObject'
      • 'stringJsonArray'
      • 'stringQueryFormatted' — Query string
      • 'stringHtmlAttrs' — HTML attributes string (e. g. width='100' height='50')
    • The snippet can also return result as a native PHP object or array (it is convenient to call through \DDTools\Snippet::runSnippet).
      • 'objectAuto' — stdClass or array depends on result object
      • 'objectStdClass' — stdClass
      • 'objectArray' — array
  • Default value: 'stringJsonAuto'

• outputterParams->templates

  • Desctription: Output templates.
  • Valid values: object
  • Default value: —

• outputterParams->templates->{$docFieldName}

  • Desctription: You can use templates for some fields.
    • Templates will be used before final conversion of results. So you don't need to care about characters escaping for JSON e. g.
    • It is useful for manipulations with doc field values through running snippets.
    • Available placeholders:
      • [+value+] — the field value
      • [+any document field or tv name+] — any name/alias of document field or TV specified in dataProviderParams->resourceFields
  • Valid values:
    • stringChunkName
    • string — use inline templates starting with @CODE:
  • Required
• outputterParams->emptyResult
  • Description: What will be returned if the snippet result is empty?
    • Regardless of the type in which the parameter is set, the result will always be converted to outputterParams->format.
  • Valid values:
    • stringJsonObject — as JSON object
    • stringJsonArray' — as JSON array
    • stringHjsonObject — as HJSON object
    • stringHjsonArray — as HJSON array
    • stringQueryFormatted — as Query string
    • It can also be set as a native PHP object or array (e. g. for calls through \DDTools\Snippet::runSnippet or $modx->runSnippet):
      • arrayAssociative
      • object
  • Default value: — (an empty object in outputterParams->format format)

Other parameters

• mode

  • Description: Mode.
  • Valid values:
    • '' — default mode
    • 'ajax' — docId gets from the $_REQUEST['id']. Use the securityFields param in this case!
  • Default value: ''
• securityFields
  • Description: The fields for security verification.
  • Valid values:
    • stringJsonObject — as JSON (e. g. {"template": 15, "published": 1})
    • stringHjsonObject — as HJSON
    • stringQueryFormatted — as Query string (e. g. template=15&published=1)
    • It can also be set as a native PHP object or array (e. g. for calls through \DDTools\Snippet::runSnippet or $modx->runSnippet):
      • arrayAssociative
      • object
  • Default value: —

Examples

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

Get the pagetitle of current document

Get the introtext of document which ID is 7 and return from chunk

testChunk code:

Get the longtitle of a document or pagetitle if longtitle is empty

Get a few phones from TVs and join them with comma

Additional data into result chunk

For example, we are getting something with the Ditto snippet. Into Ditto chunk outputterParams->tpl we need to get phone number & fax, if phone is not empty or nothing. Chunk code:

The test_row_phone chunk code:

Using field aliases while returning the results in the outputterParams->tpl chunk

The testChunk chunk code:

Using field aliases with JSON format

Returns:

Remove resource fields with empty values from result

Let that document pagetitle is set and longtitle is empty.

Returns:

If fields with empty values is no needed, just set outputterParams->removeEmptyFields to true:

Returns:

Return resource fields as a JSON array

Returns:

Use templates for fields in JSON

Returns:

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

Return resource fields as a native PHP array

Returns:

Links

• Home page
• Telegram chat
• Packagist
• GitHub