PHPackages                             dd/evolutioncms-snippets-ddgetdocumentfield - PHPackages - PHPackages  [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register)

1. [Directory](/)
2. /
3. [Utility & Helpers](/categories/utility)
4. /
5. dd/evolutioncms-snippets-ddgetdocumentfield

ActiveModxevo-snippet[Utility & Helpers](/categories/utility)

dd/evolutioncms-snippets-ddgetdocumentfield
===========================================

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

2.15.0(1y ago)121PHPPHP >=5.6.0

Since Apr 23Pushed 5mo ago1 watchersCompare

[ Source](https://github.com/DivanDesign/EvolutionCMS.snippets.ddGetDocumentField)[ Packagist](https://packagist.org/packages/dd/evolutioncms-snippets-ddgetdocumentfield)[ Docs](https://code.divandesign.ru/modx/ddgetdocumentfield)[ RSS](/packages/dd-evolutioncms-snippets-ddgetdocumentfield/feed)WikiDiscussions master Synced 1w ago

READMEChangelog (10)Dependencies (2)Versions (15)Used By (1)

(MODX)EvolutionCMS.snippets.ddGetDocumentField
==============================================

[](#modxevolutioncmssnippetsddgetdocumentfield)

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

Requires
--------

[](#requires)

- PHP >= 5.6
- [(MODX)EvolutionCMS](https://github.com/evolution-cms/evolution) >= 1.1
- [(MODX)EvolutionCMS.libraries.ddTools](https://code.divandesign.ru/modx/ddtools) >= 0.60
- [(MODX)EvolutionCMS.snippets.ddTypograph](https://code.divandesign.ru/modx/ddtypograph) >= 2.5 (if typography is required)

Installation
------------

[](#installation)

### Using [(MODX)EvolutionCMS.libraries.ddInstaller](https://github.com/DivanDesign/EvolutionCMS.libraries.ddInstaller)

[](#using-modxevolutioncmslibrariesddinstaller)

Just run the following PHP code in your sources or [Console](https://github.com/vanchelo/MODX-Evolution-Ajax-Console):

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

//Install (MODX)EvolutionCMS.snippets.ddGetDocumentField
\DDInstaller::install([
	'url' => 'https://github.com/DivanDesign/EvolutionCMS.snippets.ddGetDocumentField',
	'type' => 'snippet'
]);
```

- 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

[](#manually)

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

[](#1-elements--snippets-create-a-new-snippet-with-the-following-data)

1. Snippet name: `ddGetDocumentField`.
2. Description: `2.15 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:

[](#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
----------------------

[](#parameters-description)

### Data provider parameters

[](#data-provider-parameters)

- `dataProviderParams`

    - Description: Parameters to be passed to the provider.
    - Valid values:
        - `stringJsonObject` — as [JSON](https://en.wikipedia.org/wiki/JSON)
        - `stringHjsonObject` — as [HJSON](https://hjson.github.io/)
        - `stringQueryFormatted` — as [Query string](https://en.wikipedia.org/wiki/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

[](#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](https://en.wikipedia.org/wiki/JSON)
        - `stringHjsonObject` — as [HJSON](https://hjson.github.io/)
        - `stringQueryFormatted` — as [Query string](https://en.wikipedia.org/wiki/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` `)

[](#outputter--string-outputterstring-)

- `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` `)

[](#outputter--object-outputterobject-)

- `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](https://en.wikipedia.org/wiki/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](https://en.wikipedia.org/wiki/JSON) object
        - `stringJsonArray'` — as [JSON](https://en.wikipedia.org/wiki/JSON) array
        - `stringHjsonObject` — as [HJSON](https://hjson.github.io/) object
        - `stringHjsonArray` — as [HJSON](https://hjson.github.io/) array
        - `stringQueryFormatted` — as [Query string](https://en.wikipedia.org/wiki/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

[](#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](https://en.wikipedia.org/wiki/JSON) (e. g. `{"template": 15, "published": 1}`)
        - `stringHjsonObject` — as [HJSON](https://hjson.github.io/)
        - `stringQueryFormatted` — as [Query string](https://en.wikipedia.org/wiki/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
--------

[](#examples)

All examples are written using [HJSON](https://hjson.github.io/), but if you want you can use vanilla JSON instead.

### Get the `pagetitle` of current document

[](#get-the-pagetitle-of-current-document)

```
[[ddGetDocumentField?
	&dataProviderParams=`{
		resourceFields: pagetitle
	}`
]]

```

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

[](#get-the-introtext-of-document-which-id-is-7-and-return-from-chunk)

```
[[ddGetDocumentField?
	&dataProviderParams=`{
		resourceId: 7
		resourceFields: introtext
	}`
	&outputterParams=`{
		tpl: testChunk
	}`
]]

```

`testChunk` code:

```
[+introtext+]
```

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

[](#get-the-longtitle-of-a-document-or-pagetitle-if-longtitle-is-empty)

```
[[ddGetDocumentField?
	&dataProviderParams=`{
		resourceFields: longtitle
		resourceFieldsAlternative: pagetitle
	}`
]]
```

### Get a few phones from TVs and join them with comma

[](#get-a-few-phones-from-tvs-and-join-them-with-comma)

```
[[ddGetDocumentField?
	&dataProviderParams=`{
		resourceId: 7
		resourceFields: phone1,phone2
	}`
	&outputterParams=`{
		docFieldsGlue: ", "
	}`
]]

```

### Additional data into result chunk

[](#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:

```

	[+content+]
	[[ddGetDocumentField?
		&dataProviderParams=`{
			resourceId: "[+id+]"
			resourceFields: phone
		}`
		&outputterParams=`{
			tpl: test_row_phone
			placeholders: {
				fax: "[+fax+]"
				someTitle: Call me!
			}
		}`
	]]

```

The `test_row_phone` chunk code:

```
[+phone+], [+fax+]
```

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

[](#using-field-aliases-while-returning-the-results-in-the-outputterparams-tpl-chunk)

```
[[ddGetDocumentField?
	&dataProviderParams=`{
		resourceFields: pagetitle=title,pub_date=date
	}`
	&outputterParams=`{
		tpl: testChunk
	}`
]]

```

The `testChunk` chunk code:

```
[+title+], [+date+]
```

### Using field aliases with JSON format

[](#using-field-aliases-with-json-format)

```
[[ddGetDocumentField?
	&dataProviderParams=`{
		resourceFields: pagetitle=title,introtext=text,content
	}`
	&outputter=`object`
]]

```

Returns:

```
{
	"title": "The title of a document",
	"text": "The annotation",
	"content": "The content"
}
```

### Remove resource fields with empty values from result

[](#remove-resource-fields-with-empty-values-from-result)

Let that document `pagetitle` is set and `longtitle` is empty.

```
[[ddGetDocumentField?
	&dataProviderParams=`{
		resourceFields: pagetitle,longtitle
	}`
	&outputter=`object`
]]

```

Returns:

```
{
	"pagetitle": "The title of a document",
	"longtitle": ""
}
```

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

```
[[ddGetDocumentField?
	&dataProviderParams=`{
		resourceFields: pagetitle,longtitle
	}`
	&outputter=`object`
	&outputterParams=`{
		removeEmptyFields: true
	}`
]]

```

Returns:

```
{
	"pagetitle": "The title of a document"
}
```

### Return resource fields as a JSON array

[](#return-resource-fields-as-a-json-array)

```
[[ddGetDocumentField?
	&dataProviderParams=`{
		resourceFields: pagetitle,longtitle
	}`
	&outputter=`object`
	&outputterParams=`{
		format: stringJsonArray
	}`
]]

```

Returns:

```
[
	"The title of a document",
	"The long title of a document"
]
```

### Use templates for fields in JSON

[](#use-templates-for-fields-in-json)

```
[[ddGetDocumentField?
	&dataProviderParams=`{
		resourceFields: pagetitle,id=link
	}`
	&outputter=`object`
	&outputterParams=`{
		templates: {
			pagetitle: [+value+]
			link:
				'''
				[+pagetitle+]
				'''
		}
	}`
]]

```

Returns:

```
{
	"pagetitle": "KINO",
	"link": "KINO"
}
```

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

[](#run-the-snippet-through-ddtoolssnippetrunsnippet-without-db-and-eval)

```
\DDTools\Snippet::runSnippet([
	'name' => 'ddGetDocumentField',
	'params' => [
		//Can be set as a native PHP array
		'dataProviderParams' => [
			'resourceId' => 42,
			'resourceFields' => 'pagetitle,question',
		],
	],
]);
```

### Return resource fields as a native PHP array

[](#return-resource-fields-as-a-native-php-array)

```
\DDTools\Snippet::runSnippet([
	'name' => 'ddGetDocumentField',
	'params' => [
		'dataProviderParams' => [
			'resourceId' => 42,
			'resourceFields' => 'pagetitle,question',
		],
		'outputter' => 'object',
		'outputterParams' => [
			'format' => 'objectArray',
		],
	],
]);
```

Returns:

```
array(
	'pagetitle' => 'The title of a document',
	'question' => 'What is the meaning of life?',
)
```

Links
-----

[](#links)

- [Home page](https://code.divandesign.ru/modx/ddgetdocumentfield)
- [Telegram chat](https://t.me/dd_code)
- [Packagist](https://packagist.org/packages/dd/evolutioncms-snippets-ddgetdocumentfield)
- [GitHub](https://github.com/DivanDesign/EvolutionCMS.snippets.ddGetDocumentField)

###  Health Score

33

—

LowBetter than 75% of packages

Maintenance53

Moderate activity, may be stable

Popularity4

Limited adoption so far

Community9

Small or concentrated contributor base

Maturity58

Maturing project, gaining track record

 Bus Factor1

Top contributor holds 100% of commits — single point of failure

How is this calculated?**Maintenance (25%)** — Last commit recency, latest release date, and issue-to-star ratio. Uses a 2-year decay window.

**Popularity (30%)** — Total and monthly downloads, GitHub stars, and forks. Logarithmic scaling prevents top-heavy scores.

**Community (15%)** — Contributors, dependents, forks, watchers, and maintainers. Measures real ecosystem engagement.

**Maturity (30%)** — Project age, version count, PHP version support, and release stability.

###  Release Activity

Cadence

Every ~128 days

Recently: every ~233 days

Total

13

Last Release

672d ago

PHP version history (2 changes)2.9.0PHP >=5.4.0

2.11.0PHP >=5.6.0

### Community

Maintainers

![](https://www.gravatar.com/avatar/09b81986267e62b5fde1473b40aa6f11f7bc26c1c29d5f80f2768c8788e08110?d=identicon)[dd](/maintainers/dd)

---

Top Contributors

[![Ronef](https://avatars.githubusercontent.com/u/1333424?v=4)](https://github.com/Ronef "Ronef (83 commits)")

---

Tags

modxMODX Evoevoevolution-cmsmodx evolutionevo cmsevolutioncmsdivandesigndd studiodd groupddgetdocumentfieldget document field

### Embed Badge

![Health badge](/badges/dd-evolutioncms-snippets-ddgetdocumentfield/health.svg)

```
[![Health](https://phpackages.com/badges/dd-evolutioncms-snippets-ddgetdocumentfield/health.svg)](https://phpackages.com/packages/dd-evolutioncms-snippets-ddgetdocumentfield)
```

PHPackages © 2026

[Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)