Snippet gets the necessary document fields (and TVs) by its id.
- PHP >= 5.6
- (MODX)EvolutionCMS >= 1.1
- (MODX)EvolutionCMS.libraries.ddTools >= 0.48
- (MODX)EvolutionCMS.snippets.ddTypograph >= 2.5 (if typography is required)
- Snippet name:
ddGetDocumentField
. - Description:
<b>2.11.1</b> Snippet gets the necessary document fields (and TVs) by its id.
. - Category:
Core
. - Parse DocBlock:
no
. - Snippet code (php): Insert content of the
ddGetDocumentField_snippet.php
file from the archive.
- Create a new folder
assets/snippets/ddGetDocumentField/
. - Extract the archive to the folder (except
ddGetDocumentField_snippet.php
).
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.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.
-
dataProviderParams
- Desctription: Parameters to be passed to the provider.
- Valid values:
stringJsonObject
— as JSONstringHjsonObject
— as HJSONstringQueryFormated
— as Query string- It can also be set as native PHP object or array (e. g. for calls through
\DDTools\Snippet::runSnippet
or$modx->runSnippet
):arrayAssociative
object
- Default value: —
-
dataProviderParams->resourceId
- Desctription: Document identifier.
- Valid values:
integer
- Default value:
$modx->documentIdentifier
(current document)
-
dataProviderParams->resourceFields
- Desctription: Document field(s) to get separated by commas.
If the parameter is empty, the snippet will try to search fields inoutputterParams->tpl
(something like[+docField+]
). - Valid values:
stringCommaSeparated
- Default value: —
- Desctription: Document field(s) to get separated by commas.
-
dataProviderParams->resourceFields[i]
- Desctription: 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 fieldstringSeparated
— document field and it's alias
- Required
- Desctription: Fields and their aliases must be separated by
-
dataProviderParams->resourceFieldsAlternative
- Desctription: Alternative document field(s) to get if the main is empty separated by commas.
- Valid values:
stringCommaSeparated
- Default value: —
-
dataProviderParams->resourceFieldsAlternative[i]
- Desctription: Document field.
- Valid values:
string
- Required
-
outputter
- Desctription: Format of the output.
- Valid values:
'string'
'json'
- Default value:
'string'
-
outputterParams
- Desctription: Parameters to be passed to the specified outputter.
- Valid values:
stringJsonObject
— as JSONstringHjsonObject
— as HJSONstringQueryFormated
— as Query string- It can also be set as native PHP object or array (e. g. for calls through
\DDTools\Snippet::runSnippet
or$modx->runSnippet
):arrayAssociative
object
- Default value: —
-
outputterParams->typography
- Desctription: Need to typography result?
- Valid values:
0
1
- Default value:
0
-
outputterParams->escapeForJS
- Desctription: Need to escape special characters from result?
- Valid values:
0
1
- Default value:
0
-
outputterParams->URLEncode
- Desctription: Need to URL-encode result string?
- Valid values:
0
1
- Default value:
0
-
outputterParams->emptyResult
- Desctription: What will be returned if the snippet result is empty?
- Valid values:
string
- Default value:
''
-
outputterParams->tpl
-
Desctription: 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
-
Desctription: Additional data has to be passed into
result_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
- Desctription: String for join the fields (if
outputterParams->tpl
is not used). - Valid values:
string
- Default value:
''
- Desctription: String for join the fields (if
outputterParams->removeEmptyFields
- Desctription: Remove resource fields with empty values (
''
) from result. - Valid values:
boolean
- Default value:
false
- Desctription: Remove resource fields with empty values (
-
mode
- Desctription: Mode.
- Valid values:
''
— default mode'ajax'
—docId
gets from the$_REQUEST['id']
. Use thesecurityFields
param in this case!
- Default value:
''
-
securityFields
- Desctription: The fields for security verification.
- Valid values:
stringJsonObject
— as JSON (e. g.{"template": 15, "published": 1}
)stringHjsonObject
— as HJSONstringQueryFormated
— as Query string (e. g.template=15&published=1
)- It can also be set as native PHP object or array (e. g. for calls through
\DDTools\Snippet::runSnippet
or$modx->runSnippet
):arrayAssociative
object
- Default value: —
[[ddGetDocumentField?
&dataProviderParams=`{
"resourceFields": "pagetitle"
}`
]]
[[ddGetDocumentField?
&dataProviderParams=`{
"resourceId": 7,
"resourceFields": "introtext"
}`
&outputterParams=`{
"tpl": "testChunk"
}`
]]
testChunk
code:
<div class="test">[+introtext+]</div>
<title>[[ddGetDocumentField?
&dataProviderParams=`{
"resourceFields": "longtitle",
"resourceFieldsAlternative": "pagetitle"
}`
]]</title>
[[ddGetDocumentField?
&dataProviderParams=`{
"resourceId": 7,
"resourceFields": "phone1,phone2"
}`
&outputterParams=`{
"docFieldsGlue": ", "
}`
]]
For example, we are getting something with the Ditto snippet. Into Ditto chunk result_tpl
we need to get phone number & fax, if phone is not empty or nothing. Chunk code:
<div class="test_row">
[+content+]
[[ddGetDocumentField?
&dataProviderParams=`{
"resourceId": "[+id+]",
"resourceFields": "phone"
}`
&outputterParams=`{
"tpl": "test_row_phone",
"placeholders": {
"fax": "[+fax+]",
"someTitle": "Call me!"
}
}`
]]
</div>
The test_row_phone
chunk code:
<p class="phone" title="[+someTitle+]">[+phone+], [+fax+]</p>
[[ddGetDocumentField?
&dataProviderParams=`{
"resourceFields": "pagetitle=title,pub_date=date"
}`
&outputterParams=`{
"tpl": "testChunk"
}`
]]
The testChunk
chunk code:
<p>[+title+], [+date+]</p>
[[ddGetDocumentField?
&dataProviderParams=`{
"resourceFields": "pagetitle=title,introtext=text,content"
}`
&outputter=`json`
]]
Returns:
{
"title": "The title of a document",
"text": "The annotation",
"content": "The content"
}
Let that document pagetitle
is set and longtitle
is empty.
[[ddGetDocumentField?
&dataProviderParams=`{
"resourceFields": "pagetitle,longtitle"
}`
&outputter=`json`
]]
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=`json`,
&outputterParams=`{
"removeEmptyFields": true
}`
]]
Returns:
{
"pagetitle": "The title of a document"
}
\DDTools\Snippet::runSnippet([
'name' => 'ddGetDocumentField',
'params' => [
//Can be set as native PHP array
'dataProviderParams' => [
'resourceId' => 42,
'resourceFields' => 'pagetitle,question'
]
]
]);