dd / evolutioncms-snippets-ddgetdocumentfield
Snippet gets the necessary document fields (and TVs) by its id.
Installs: 2
Dependents: 1
Suggesters: 0
Security: 0
Stars: 1
Watchers: 3
Forks: 0
Open Issues: 0
Type:modxevo-snippet
Requires
- php: >=5.6.0
- dd/evolutioncms-libraries-ddtools: >=0.60.0
- dd/evolutioncms-snippets-ddtypograph: >=2.5.0
README
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:
//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
1. Elements → Snippets: Create a new snippet with the following data
- Snippet name:
ddGetDocumentField
. - Description:
<b>2.15</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.
2. Elements → Manage Files:
- Create a new folder
assets/snippets/ddGetDocumentField/
. - 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 JSONstringHjsonObject
— as HJSONstringQueryFormatted
— 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 inoutputterParams->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 fieldstringSeparated
— document field and it's alias
- Required
- Description: Fields and their aliases must be separated by
-
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 JSONstringHjsonObject
— as HJSONstringQueryFormatted
— 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.
- Available placeholders:
- Valid values:
stringChunkName
string
— use inline templates starting with@CODE:
- Required
- Description: Chunk to parse result.
-
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]
.
- Arrays are supported too:
- Valid values:
object
- Default value: —
- Description: Additional data has to be passed into
-
outputterParams->docFieldsGlue
- Description: String for join the fields (if
outputterParams->tpl
is not used). - Valid values:
string
- Default value:
''
- Description: String for join the fields (if
-
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
- Description: Remove resource fields with empty values (
Outputter → Object (&outputter=`object`
)
-
outputterParams->removeEmptyFields
- Description: Remove resource fields with empty values (
''
) from result. - Valid values:
boolean
- Default value:
false
- Description: Remove resource fields with empty values (
-
outputterParams->format
- Description: Output format.
- Values are case insensitive (the following values are equal:
'stringjsonauto'
,'stringJsonAuto'
,'STRINGJSONAUTO'
, etc).
- Values are case insensitive (the following values are equal:
- Valid values:
- The snippet can return result as a string:
'stringJsonAuto'
—stringJsonObject
orstringJsonArray
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
orarray
depends on result object'objectStdClass'
—stdClass
'objectArray'
—array
- The snippet can return result as a string:
- Default value:
'stringJsonAuto'
- Description: Output format.
-
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 indataProviderParams->resourceFields
- Valid values:
stringChunkName
string
— use inline templates starting with@CODE:
- Required
- Desctription: You can use templates for some fields.
-
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
.
- Regardless of the type in which the parameter is set, the result will always be converted to
- Valid values:
stringJsonObject
— as JSON objectstringJsonArray'
— as JSON arraystringHjsonObject
— as HJSON objectstringHjsonArray
— as HJSON arraystringQueryFormatted
— 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)
- Description: What will be returned if the snippet result is empty?
Other parameters
-
mode
- Description: Mode.
- Valid values:
''
— default mode'ajax'
—docId
gets from the$_REQUEST['id']
. Use thesecurityFields
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 HJSONstringQueryFormatted
— 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
[[ddGetDocumentField?
&dataProviderParams=`{
resourceFields: pagetitle
}`
]]
Get the introtext
of document which ID is 7
and return from chunk
[[ddGetDocumentField?
&dataProviderParams=`{
resourceId: 7
resourceFields: introtext
}`
&outputterParams=`{
tpl: testChunk
}`
]]
testChunk
code:
<div class="test">[+introtext+]</div>
Get the longtitle
of a document or pagetitle
if longtitle
is empty
<title>[[ddGetDocumentField? &dataProviderParams=`{ resourceFields: longtitle resourceFieldsAlternative: pagetitle }` ]]</title>
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
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:
<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>
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:
<p>[+title+], [+date+]</p>
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
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
[[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
[[ddGetDocumentField?
&dataProviderParams=`{
resourceFields: pagetitle,id=link
}`
&outputter=`object`
&outputterParams=`{
templates: {
pagetitle: <h1>[+value+]</h1>
link:
'''
<a href="[~[+value+]~]">[+pagetitle+]</a>
'''
}
}`
]]
Returns:
{ "pagetitle": "<h1>KINO</h1>", "link": "<a href=\"bands/timeless/kino\">KINO</a>" }
Run the snippet through \DDTools\Snippet::runSnippet
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
\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?', )