dd / modxevo-snippet-ddgetdocuments
A snippet for fetching and parsing resources from the document tree or custom DB table by a custom rule.
Installs: 17
Dependents: 0
Suggesters: 0
Security: 0
Stars: 0
Watchers: 3
Forks: 0
Open Issues: 4
Type:modxevo-snippet
Requires
- php: >=5.6.0
- composer/installers: ~1.0.0
- dd/evolutioncms-libraries-ddtools: >=0.62.0
This package is auto-updated.
Last update: 2024-10-06 19:25:14 UTC
README
A snippet for fetching and parsing resources from the document tree or custom DB table by a custom rule.
Requires
- PHP >= 5.6
- MySQL >= 8 or MariaDB >= 10.3.10 (not tested in older versions).
- (MODX)EvolutionCMS >= 1.1
- (MODX)EvolutionCMS.libraries.ddTools >= 0.62
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.ddGetDocuments \DDInstaller::install([ 'url' => 'https://github.com/DivanDesign/EvolutionCMS.snippets.ddGetDocuments', ]);
- If
ddGetDocuments
is not exist on your site,ddInstaller
will just install it. - If
ddGetDocuments
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:
ddGetDocuments
. - Description:
<b>1.8</b> A snippet for fetching and parsing resources from the document tree or custom DB table by a custom rule.
. - Category:
Core
. - Parse DocBlock:
no
. - Snippet code (php): Insert content of the
ddGetDocuments_snippet.php
file from the archive.
2. Elements → Manage Files:
- Create a new folder
assets/snippets/ddGetDocuments/
. - Extract the archive to the folder (except
ddGetDocuments_snippet.php
).
Parameters description
Core parameters
fieldDelimiter
- Description: The field delimiter to be used in order to distinct data base column names in those parameters which can contain SQL queries directly, e. g.
providerParams->groupBy
,providerParams->orderBy
andproviderParams->filter
. - Valid values:
string
- Default value:
'`'
- Description: The field delimiter to be used in order to distinct data base column names in those parameters which can contain SQL queries directly, e. g.
Data provider parameters
-
provider
- Description: Name of the provider that will be used to fetch documents.
- Data provider names are case insensitive (the following names are equal:
parent
,Parent
,pArEnT
, etc).
- Data provider names are case insensitive (the following names are equal:
- Valid values:
'parent'
'select'
- Default value:
'parent'
- Description: Name of the provider that will be used to fetch documents.
-
providerParams
- 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
$modx->runSnippet
):arrayAssociative
object
- Default value: —
-
providerParams->filter
- Description: The filter condition in SQL-style to be applied while resource fetching.
- Notice that all fields/tvs names specified in the filter parameter must be wrapped in
fieldDelimiter
.
- Notice that all fields/tvs names specified in the filter parameter must be wrapped in
- Valid values:
string
- Default value:
'`published` = 1 AND `deleted` = 0'
- Description: The filter condition in SQL-style to be applied while resource fetching.
-
providerParams->total
- Description: The maximum number of the resources that will be returned.
- Valid values:
integer
- Default value: — (all)
-
providerParams->offset
- Description: Resources offset.
- Valid values:
integer
- Default value:
0
-
providerParams->groupBy
- Description: Group items that have the same values into summary item (like SQL
GROUP BY
). - Valid values:
stringCommaSeparated
- Default value: —
- Description: Group items that have the same values into summary item (like SQL
-
providerParams->groupBy[$i]
- Description: Document field or TV by which the items will be grouped.
- Valid values:
string
- Required
-
providerParams->orderBy
- Description: A string representing the sorting rule.
- TV names also can be used.
- Valid values:
string
- Default value: —
- Description: A string representing the sorting rule.
Providers → Parent (&provider=`parent`
)
-
providerParams->parentIds
- Description: Parent ID(s).
- Valid values:
array
stringCommaSeparated
- Default value:
[0]
-
providerParams->parentIds[i]
- Description: Document ID.
- Valid values:
integer
- Required
-
providerParams->depth
- Description: Depth of children documents search.
- Valid values:
integer
- Default value:
1
-
providerParams->excludeIds
- Description: The document IDs which need to exclude.
- Valid values:
array
stringCommaSeparated
- Default value: —
-
providerParams->excludeIds[i]
- Description: Document ID.
- Valid values:
integer
- Required
Providers → Select (&provider=`select`
)
-
providerParams->ids
- Description: Document IDs to output.
- Valid values:
array
stringCommaSeparated
- Required
-
providerParams->ids[i]
- Description: Document ID.
- Valid values:
integer
- Required
Providers → Customdbtable (&provider=`customdbtable`
)
Get resources from custom DB table.
providerParams->resourcesTableName
- Description: DB table to get resources from.
- Valid values:
string
- Required
Output format parameters
-
outputter
- Description: Format of the output.
- Outputter names are case insensitive (the following names are equal:
string
,String
,sTrInG
, etc).
- Outputter names are case insensitive (the following names are equal:
- Valid values:
'string'
'json'
'sitemap'
'yandexmarket'
'raw'
- Default value:
'string'
- Description: Format of the output.
-
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
$modx->runSnippet
):arrayAssociative
object
- Default value: —
-
outputterParams->templates
- Description: Output templates.
- Valid values:
object
- Default value: —
Outputter → String (&outputter=`string`
)
-
outputterParams->templates->item
- Description: Item template.
- Available placeholders:
[+
any document field or tv name+]
— Any document field name or TV.[+
any of extender placeholders+]
— Any extender placeholders (see extenders description below).[+
any placeholders fromplaceholders
param+]
— Any custom placeholders (seeoutputterParams->placeholders
description below).[+itemNumber+]
— Item number started from 1.[+itemNumberZeroBased+]
Item number started from 0.[+total+]
— number of returned items[+totalFound+]
— number of found items
- Available placeholders:
- Valid values:
stringChunkName
string
— use inline templates starting with@CODE:
- Required
- Description: Item template.
-
outputterParams->templates->itemFirst
- Description: Template for the first item.
- Has the same placeholders as
outputterParams->templates->item
.
- Has the same placeholders as
- Valid values:
stringChunkName
string
— use inline templates starting with@CODE:
- Default value: ==
outputterParams->templates->item
.
- Description: Template for the first item.
-
outputterParams->templates->itemLast
- Description: Template for the last item.
- Has the same placeholders as
outputterParams->templates->item
.
- Has the same placeholders as
- Valid values:
stringChunkName
string
— use inline templates starting with@CODE:
- Default value: ==
outputterParams->templates->item
.
- Description: Template for the last item.
-
outputterParams->templates->wrapper
- Description: Wrapper template.
- Available placeholders:
[+
any document field or tv name+]
— Any document field name or TV.[+
any of extender placeholders+]
— Any extender placeholders (see extenders description below).[+
any placeholders fromplaceholders
param+]
— Any custom placeholders (seeoutputterParams->placeholders
description below).[+ddGetDocuments_items+]
[+total+]
— number of returned items[+totalFound+]
— number of found items
- Available placeholders:
- Valid values:
stringChunkName
string
— use inline templates starting with@CODE:
- Default value: —
- Description: Wrapper template.
-
outputterParams->templates->noResults
- Description: A chunk or text to output when no items found.
- Has the same placeholders as
outputterParams->templates->wrapper
.
- Has the same placeholders as
- Valid values:
stringChunkName
string
— use inline templates starting with@CODE:
- Default value: —
- Description: A chunk or text to output when no items found.
-
outputterParams->placeholders
- Description: Additional data has to be passed into
templates->item
,templates->itemFirst
,templates->itemLast
andtemplates->wrapper
.- 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->placeholders->{$name}
- Description: Key for placeholder name and value for placeholder value.
- Valid values:
string
- Required
-
outputterParams->itemGlue
- Description: The string that combines items while rendering.
- Valid values:
string
- Default value:
''
Outputter → Json (&outputter=`json`
)
-
outputterParams->docFields
- Description: Document fields to output (including TVs).
- Valid values:
array
stringCommaSeparated
- Default value:
'id'
-
outputterParams->docFields[i]
- Description: Document field or TV.
- You can use custom aliases instead of field names for output using the
'='
separator (for example:'pagetitle=title'
,'content=text'
, etc).
- You can use custom aliases instead of field names for output using the
- Valid values:
string
— document fieldstringSeparated
— document field and it's alias separated by'='
- Required
- Description: Document field or TV.
-
outputterParams->templates->{$docFieldName}
- Description: You can use templates for some document fields.
- Templates will be used before JSON conversion of results. So you don't need to care about characters escaping.
- 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 document field name or TV specified inoutputterParams->docFields
[+itemNumber+]
— item number started from 1[+itemNumberZeroBased+]
— item number started from 0
- Valid values:
stringChunkName
string
— use inline templates starting with@CODE:
- Default value: —
- Description: You can use templates for some document fields.
-
outputterParams->templates->noResults
- Description: A chunk or text to output when no items found.
- Valid values:
stringChunkName
string
— use inline templates starting with@CODE:
- Default value:
'[]'
-
outputterParams->templates->wrapper
- Description: Wrapper template.
- Available placeholders:
[+ddGetDocuments_items+]
[+total+]
— number of returned items[+totalFound+]
— number of found items
- Available placeholders:
- Valid values:
stringChunkName
string
— use inline templates starting with@CODE:
- Default value:
'[+ddGetDocuments_items+]'
- Description: Wrapper template.
Outputter → Sitemap (&outputter=`sitemap`
)
Output in Sitemap XML format.
-
outputterParams->priorityTVName
- Description: Name of TV which sets the relative priority of the document.
- Valid values:
stringTvName
- Default value:
'general_seo_sitemap_priority'
-
outputterParams->changefreqTVName
- Description: Name of TV which sets the change frequency.
- Valid values:
stringTvName
- Default value:
'general_seo_sitemap_changefreq'
-
outputterParams->templates->item
- Description: Item template.
- Available placeholders:
[+
any document field or tv name+]
— Any document field name or TV.[+
any of extender placeholders+]
— Any extender placeholders (see extenders description below).[+itemNumber+]
— Item number started from 1.[+itemNumberZeroBased+]
Item number started from 0.
- Available placeholders:
- Valid values:
stringChunkName
string
— use inline templates starting with@CODE:
- Default:
<url> <loc>[(site_url)][~[+id+]~]</loc> <lastmod>[+editedon+]</lastmod> <priority>[+[+priorityTVName+]+]</priority> <changefreq>[+[+changefreqTVName+]+]</changefreq> </url>
- Description: Item template.
-
outputterParams->templates->wrapper
- Description: Wrapper template.
- Available placeholders:
[+
any document field or tv name+]
— Any document field name or TV.[+
any of extender placeholders+]
— Any extender placeholders (see extenders description below).[+ddGetDocuments_items+]
- Available placeholders:
- Valid values:
stringChunkName
string
— use inline templates starting with@CODE:
- Default value:
<urlset xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns="http://www.sitemaps.org/schemas/sitemap/0.9" xsi:schemaLocation="http://www.sitemaps.org/schemas/sitemap/0.9 http://www.sitemaps.org/schemas/sitemap/0.9/sitemap.xsd"> [+ddGetDocuments_items+] </urlset>
- Description: Wrapper template.
Outputter → Yandexmarket (&outputter=`yandexmarket`
)
Output in YML format.
-
outputterParams->shopData
- Description: Shop data.
- Valid values:
object
- Required
-
outputterParams->shopData->shopName
- Description: Short shop name, length <= 20.
- Valid values:
string
- Required
-
outputterParams->shopData->companyName
- Description: Company legal name. Internal data that not be displayed but required by Yandex.
- Valid values:
string
- Required
-
outputterParams->shopData->agency
- Description: Web developers agency name.
- Valid values:
string
- Default value: —
-
outputterParams->shopData->currencyId
- Description: Currency code (see Yandex docs).
- Valid values:
string
- Default value:
'RUR'
-
outputterParams->shopData->platform
- Description:
<platform>
tag content. - Valid values:
string
- Default value:
'(MODX) Evolution CMS'
- Description:
-
outputterParams->shopData->version
- Description:
<version>
tag content. - Valid values:
string
- Default value:
'[(settings_version)]'
- Description:
-
outputterParams->categoryIds_last
- Description: Allows to add additional parent elements in the category section. If empty only immediate parents of goods will be returned.
- Valid values:
stringCommaSeparated
- Default value: —
-
outputterParams->categoryIds_last[i]
- Description: Document ID.
- Valid values:
integer
- Required
-
outputterParams->offerFields
- Description: Offer fields parameters.
- Valid values:
object
- Required
-
outputterParams->offerFields->{$fieldName}
- Description: Offer field parameter.
- Valid values:
string
— the parameter can be set as a document field nameobject
— or as an object with additional params (see below)
- Default value: —
-
outputterParams->offerFields->{$fieldName}->docFieldName
- Description: A document field name that contains offer field value.
- Valid values:
stringTvName
- Required
-
outputterParams->offerFields->{$fieldName}->disableEscaping
- Description: You can disable escaping special characters (
'
,"
,&
,<
,>
) in the field value. - Valid values:
boolean
- Default value:
false
- Description: You can disable escaping special characters (
-
outputterParams->offerFields->{$fieldName}->valuePrefix
- Description: You can set custom string that will be added before the field value.
- Valid values:
string
- Default value: —
-
outputterParams->offerFields->{$fieldName}->valueSuffix
- Description: You can set custom string that will be added after the field value.
- Valid values:
string
- Default value: —
-
outputterParams->offerFields->price
- Description: A document field name, that contains offer price.
- If a document field value is empty, but
outputterParams->offerFields->priceOld
is set, the last will be used instead.
- If a document field value is empty, but
- Valid values:
stringTvName
- Required
- Description: A document field name, that contains offer price.
-
outputterParams->offerFields->priceOld
- Description: A document field name, that contains old offer price (must be less then
outputterParams->offerFields->price
or will not be used). - Valid values:
stringTvName
- Default value: —
- Description: A document field name, that contains old offer price (must be less then
-
outputterParams->offerFields->picture
- Description: A document field name, that contains offer picture.
- Valid values:
stringTvName
- Default value: —
-
outputterParams->offerFields->name
- Description: A document field name, that contains offer name.
- If a document field value is empty, the
pagetitle
field will be used instead.
- If a document field value is empty, the
- Valid values:
stringDocFieldName
stringTvName
- Default value:
'pagetitle'
- Description: A document field name, that contains offer name.
-
outputterParams->offerFields->model
- Description: A document field name, that contains offer model.
- Valid values:
stringDocFieldName
stringTvName
- Default value: —
-
outputterParams->offerFields->model
- Description: A document field name, that contains offer vendor.
- Valid values:
stringDocFieldName
stringTvName
- Default value: —
-
outputterParams->offerFields->available
- Description: A document field name, that contains offer availability status (
true
|false
). - Valid values:
stringTvName
''
— always display'true'
.
- Default value:
''
- Description: A document field name, that contains offer availability status (
-
outputterParams->offerFields->description
- Description: A document field name, that contains offer description (less than 3 000 chars).
- Valid values:
stringDocFieldName
stringTvName
- Default value: —
-
outputterParams->offerFields->salesNotes
- Description: A document field name, that contains offer <sales_notes>.
- Valid values:
stringDocFieldName
stringTvName
- Default value: —
-
outputterParams->offerFields->manufacturerWarranty
- Description: A document field name, that contains offer manufacturer warraynty status (
true
|false
). - Valid values:
stringTvName
- Default value: —
- Description: A document field name, that contains offer manufacturer warraynty status (
-
outputterParams->offerFields->countryOfOrigin
- Description: A document field name, that contains offer country of origin.
- Valid values:
stringDocFieldName
stringTvName
- Default value: —
-
outputterParams->offerFields->homeCourierDelivery
- Description: A document field name, that contains offer courier delivery status (
true
|false
). - Valid values:
stringTvName
- Default value: —
- Description: A document field name, that contains offer courier delivery status (
-
outputterParams->offerFields->dimensions
- Description: A document field name, that contains offer dimensions (length, width, height) including packaging.
- Specify dimensions in centimeters. Format: three positive numbers with accuracy of 0.001, using a dot as the decimal separator.
- The numbers must be separated by the slash character
/
without spaces.
- Valid values:
stringDocFieldName
stringTvName
- Default value: —
- Description: A document field name, that contains offer dimensions (length, width, height) including packaging.
-
outputterParams->offerFields->weight
- Description: Item weight in kilograms including packaging.
- Some categories have limits on the minimum or maximum weight.
- Download a list of minimum and maximum weight values.
- In any category, the weight can be specified accurate to one thousandth (for example, 1.001, using a dot as a decimal point).
- If the minimum value is set to
0
, there is no minimum weight limit and it can be specified starting from one gram (0.001 kg).
- Valid values:
stringDocFieldName
stringTvName
- Default value: —
- Description: Item weight in kilograms including packaging.
-
outputterParams->offerFields->additionalParams
- Description: A document field name, that contains offer <param> elements.
- Valid values:
stringDocFieldName
stringTvName
- Default value: —
-
outputterParams->offerFields->customData
- Description: A document field name, that contains custom text that must be inserted before
</offer>
. - Valid values:
stringDocFieldName
stringTvName
- Default value: —
- Description: A document field name, that contains custom text that must be inserted before
-
outputterParams->templates->wrapper
- Description: Wrapper template.
- Available placeholders:
[+
any document field or tv name+]
— Any document field name or TV.[+
any of extender placeholders+]
— Any extender placeholders (see extenders description below).[+ddGetDocuments_items+]
- Available placeholders:
- Valid values:
stringChunkName
string
— use inline templates starting with@CODE:
- Default value:
<?xml version="1.0" encoding="utf-8"?> <yml_catalog date="[+generationDate+]"> <shop> <name>[+shopData.shopName+]</name> <company>[+shopData.companyName+]</company> <url>[(site_url)]</url> <platform>[+shopData.platform+]</platform> <version>[+shopData.version+]</version> [+shopData.agency+] <currencies> <currency id="[+shopData.currencyId+]" rate="1" /> </currencies> <categories>[+ddGetDocuments_categories+]</categories> <offers>[+ddGetDocuments_items+]</offers> </shop> </yml_catalog>
- Description: Wrapper template.
-
outputterParams->templates->categories_item
- Description: Category item template.
- Available placeholders:
[+id+]
— Category doc ID.[+value+]
— Category name.[+parent+]
— Category parent ID.[+attrs+]
— Attributes string (e. g.parentId="42"
).
- Available placeholders:
- Valid values:
stringChunkName
string
— use inline templates starting with@CODE:
- Default value:
<category id="[+id+]"[+attrs+]> [+value+] </category>
- Description: Category item template.
-
outputterParams->templates->offers_item
- Description: Offer item template.
- Available placeholders:
[+
any document field or tv name+]
— Any document field name or TV.[+
any of extender placeholders+]
— Any extender placeholders (see extenders description below).[+itemNumber+]
— Item number started from 1.[+itemNumberZeroBased+]
Item number started from 0.
- Available placeholders:
- Valid values:
stringChunkName
string
— use inline templates starting with@CODE:
- Default:
<offer id="[+id+]" available="[+available+]"> <url>[(site_url)][~[+id+]~]</url> [+name+] [+price+] [+priceOld+] [+shopData.currencyId+] [+categoryId+] [+picture+] [+vendor+] [+model+] [+description+] [+salesNotes+] [+manufacturerWarranty+] [+countryOfOrigin+] [+delivery+] [+dimensions+] [+weight+] [+additionalParams+] [+customData+] </offer>
- Description: Offer item template.
-
outputterParams->templates->{'offers_item_elem' . $FieldName}
- Description: You can set custom template for any offer element.
- Specify an element name in accordance with
offerFields->
parameters, e. g.outputterParams->templates->offers_item_elemCountryOfOrigin
. - Available placeholders:
[+tagName+]
— Element tag name.[+value+]
— Element value.
- Specify an element name in accordance with
- Valid values:
stringChunkName
string
— use inline templates starting with@CODE:
- Default: —
- Description: You can set custom template for any offer element.
Extenders parameters
-
extenders
- Description: Comma-separated string determining which extenders should be applied to the snippet.
- Be aware that the order of extender names can affect the output.
- Valid values:
stringCommaSeparated
- Default value: —
- Description: Comma-separated string determining which extenders should be applied to the snippet.
-
extenders[i]
- Description: Extender name.
- Be aware that the order of extender names can affect the output.
- Extender names are case insensitive (the following names are equal:
pagination
,Pagination
,pAgInAtIoN
, etc).
- Valid values:
'pagination'
'tagging'
'search'
'sortFromURL'
- Required
- Description: Extender name.
-
extendersParams
- Description: Parameters to be passed to their corresponding extensions.
- You can avoid extender name if you are using only one extender (see examples below).
- 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
$modx->runSnippet
):arrayAssociative
object
- Default value: —
- Description: Parameters to be passed to their corresponding extensions.
-
extendersParams->{$extenderName}
- Description: Parameters of an extender, when the key is the extender name and the value is the extender parameters.
- Valid values: `object
- Default value: —
Extenders → Pagination (&extenders=`pagination`
)
-
extendersParams->pagination->wrapperTpl
- Description: Chunk to be used to output the pagination.
- Available placeholders:
[+previous+]
— HTML code of navigation block to the previous page (see parameters description below).[+next+]
— HTML code of navigation block to the next page (see parameters description below).[+pages+]
— HTML code of pages navigalion block (see parameters description below).[+totalPages+]
— Total number of pages.
- Available placeholders:
- Valid values:
stringChunkName
string
— use inline templates starting with@CODE:
- Default value:
<div class="pagination_container"> <div class="pagination clearfix"> <div class="pagination_links">[+previous+]</div> <div class="pagination_pages">[+pages+]</div> <div class="pagination_links">[+next+]</div> </div> </div>
- Description: Chunk to be used to output the pagination.
-
extendersParams->pagination->pageTpl
- Description: Chunk to be used to output pages within the pagination.
- Available placeholders:
[+url+]
— Page URL.[+page+]
— Page number.
- Available placeholders:
- Valid values:
stringChunkName
string
— use inline templates starting with@CODE:
- Default value:
<a href="[~[*id*]~][+url+]" class="strl">[+page+]</a>
- Description: Chunk to be used to output pages within the pagination.
-
extendersParams->pagination->currentPageTpl
- Description: Chunk to be used to output the current page within the pagination.
- Available placeholders:
[+url+]
— Page URL.[+page+]
— Page number.
- Available placeholders:
- Valid values:
stringChunkName
string
— use inline templates starting with@CODE:
- Default value:
<a href="[~[*id*]~][+url+]" class="strl active">[+page+]</a>
- Description: Chunk to be used to output the current page within the pagination.
-
extendersParams->pagination->nextTpl
- Description: Chunk to be used to output the navigation block to the next page.
- Available placeholders:
[+url+]
— Next page URL.[+totalPages+]
— Total number of pages.
- Available placeholders:
- Valid values:
stringChunkName
string
— use inline templates starting with@CODE:
- Default value:
<a href="[~[*id*]~][+url+]" class="pagination_next strl"><span>Следующая</span> →</a><br> <small><a href="[~[*id*]~]?page=[+totalPages+]" class="pagination_last strl"><span>Последняя</span> →</a></small>
- Description: Chunk to be used to output the navigation block to the next page.
-
extendersParams->pagination->nextOffTpl
- Description: Chunk to be used to output the navigation block to the next page if there are no more pages after.
- Available placeholders:
[+totalPages+]
— Total number of pages.
- Available placeholders:
- Valid values:
stringChunkName
string
— use inline templates starting with@CODE:
- Default value:
<span class="pagination_next"><span>Следующая</span> →</span><br> <small><span class="pagination_last"><span>Последняя</span></span> →</small>
- Description: Chunk to be used to output the navigation block to the next page if there are no more pages after.
-
extendersParams->pagination->previousTpl
- Description: Chunk to be used to output the navigation block to the previous page.
- Available placeholders:
[+url+]
— Next page URL.[+totalPages+]
— Total number of pages.
- Available placeholders:
- Valid values:
stringChunkName
string
— use inline templates starting with@CODE:
- Default value:
<a href="[~[*id*]~][+url+]" class="pagination_prev strl">← <span>Предыдущая</span></a><br> <small><a href="[~[*id*]~]" class="pagination_first strl">← <span>Первая</span></a></small>
- Description: Chunk to be used to output the navigation block to the previous page.
-
extendersParams->pagination->previousOffTpl
- Description: Chunk to be used to output the navigation block to the previous page if there are no more pages before.
- Available placeholders:
[+totalPages+]
— Total number of pages.
- Available placeholders:
- Valid values:
stringChunkName
string
— use inline templates starting with@CODE:
- Default value:
<span class="pagination_prev">← <span>Предыдущая</span></span><br> <small><span class="pagination_first">← <span>Первая</span></span></small>
- Description: Chunk to be used to output the navigation block to the previous page if there are no more pages before.
Extenders → Tagging (&extenders=`tagging`
)
-
extendersParams->tagging->tagsDocumentField
- Description: The document field (TV) contains tags.
- Valid values:
stringTvName
- Default value:
'tags'
-
extendersParams->tagging->tagsDelimiter
- Description: Tags delimiter in the document field.
- Valid values:
string
- Default value:
', '
-
extendersParams->tagging->tagsRequestParamName
- Description: The parameter in
$_REQUEST
to get the tags value from. - Valid values:
string
- Default value:
'tags'
- Description: The parameter in
Extenders → Search (&extenders=`search`
)
-
extendersParams->search->docFieldsToSearch
- Description: Document fields to search in (including TVs).
- Valid values:
array
stringCommaSeparated
- Default value:
'pagetitle,content'
-
extendersParams->search->docFieldsToSearch[i]
- Description: Document fields or TV.
- Valid values:
stringDocFieldName
stringTvName
- Required
Extenders → SortFromURL (&extenders=`sortFromURL`
)
$_GET['orderBy']
- Description: A string representing the sorting rule similar to
providerParams->orderBy
. - Valid values:
string
- Default value: —
- Description: A string representing the sorting rule similar to
Examples
All examples are written using HJSON, but if you want you can use vanilla JSON instead.
Simple fetching child documents from a parent with ID = 1
[[ddGetDocuments? &providerParams=`{ parentIds: 1 depth: 1 }` &outputterParams=`{ templates: { item: ''' @CODE:<div> <h2>[+pagetitle+]</h2> <p>[+introtext+]</p> [+someTV+] </div> ''' } }` ]]
Simple fetching child documents from a parent with ID = 1
with the providerParams->filter
Add a filter that would not output everything. Let's say we need only published documents.
Don't forget about fieldDelimiter
.
[[ddGetDocuments?
&fieldDelimiter=`#`
&providerParams=`{
parentIds: 1
depth: 1
filter: "#published# = 1"
}`
&outputterParams=`{
templates: {
item: documents_item
}
}`
]]
So we can filter as much as we like (we can use AND
and OR
, doucument fields and TVs):
[[ddGetDocuments?
&fieldDelimiter=`#`
&providerParams=`{
parentIds: 1
depth: 1
filter:
'''
#published# = 1 AND
#hidemenu# = 0 OR
#SomeTVName# = 1
'''
}`
&outputterParams=`{
templates: {
item: documents_item
}
}`
]]
Sorting by TV with the date
type (providerParams->orderBy
)
Dates in DB stored in specific format (01-02-2017 08:59:45
) and sorting works unexpectedly at first sight.
So, we can't just type:
&providerParams=`{
orderBy: "#TVName# DESC"
}`
For correct working we need to convert date from DB to Unixtime for sorting:
&providerParams=`{
orderBy: "STR_TO_DATE(#TVName#, '%d-%m-%Y %H:%i:%s') DESC"
}`
When TVName
— TV name for sorting by.
Outputters → JSON (&outputter=`json`
): Fetch documents and output in JSON
[[ddGetDocuments?
&providerParams=`{parentIds: 1}`
&outputter=`json`
]]
Returns:
[ {"id": "2"}, {"id": "3"}, {"id": "4"} ]
Outputters → JSON (&outputter=`json`
): Set documents fields to output
[[ddGetDocuments?
&providerParams=`{parentIds: 1}`
&outputter=`json`
&outputterParams=`{
docFields: id,pagetitle,menuindex,someTV
}`
]]
Returns:
[ { "id": "2", "pagetitle": "About", "menuindex": "0", "someTV": "Some value" }, { "id": "3", "pagetitle": "Partners", "menuindex": "1", "someTV": "" }, { "id": "4", "pagetitle": "Contacts", "menuindex": "2", "someTV": "" } ]
Outputters → JSON (&outputter=`json`
): Use custom aliases instead of field names
[[ddGetDocuments?
&providerParams=`{
parentIds: 1
}`
&outputter=`json`
&outputterParams=`{
docFields: pagetitle=name,menuindex=position
}`
]]
Returns:
[ { "name": "Denial", "position": "0", }, { "name": "Anger", "position": "1", }, { "name": "Bargaining", "position": "2", }, { "name": "Depression", "position": "3", }, { "name": "Acceptance", "position": "4", } ]
Group items that have the same field values into summary item (providerParams->orderBy
)
For example we have the following documents with TV gender
:
- Mary Teresa, female
- Mahatma Gandhi, male
- Tenzin Gyatso, male
- Dmitry Muratov, male
- ICAN, none
And we want to make a gender list with unique items:
[[ddGetDocuments?
&fieldDelimiter=`#`
&providerParams=`{
// The parent of our documents
parentIds: 42
// The field by which the items will be grouped
groupBy: "#gender#"
}`
&outputter=`json`
&outputterParams=`{
docFields: gender
}`
]]
Returns:
[ {"gender": "female"}, {"gender": "male"}, {"gender": "none"} ]
Extenders → Pagination (&extenders=`pagination`
)
[[ddGetDocuments?
&fieldDelimiter=`#`
&providerParams=`{
parentIds: "[*id*]"
filter: "#published# = 1"
total: 3
orderBy: "#pub_date# DESC`"
}`
&outputterParams=`{
templates: {
item: documents_item
wrapper:
''''
@CODE:[+ddGetDocuments_items+]
[+extenders.pagination+]
'''
noResults: "@CODE:"
}
}`
&extenders=`pagination`
&extendersParams=`{
pagination: {
wrapperTpl: general_pagination
nextTpl: general_pagination_next
previousTpl: general_pagination_prev
nextOffTpl: general_pagination_nextOff
previousOffTpl: general_pagination_prevOff
pageTpl: general_pagination_page
currentPageTpl: general_pagination_pageCurrent
}
}`
]]
&providerParams=`{parentIds: "[*id*]"}`
— fetch current doc children.&providerParams=`{filter: "#published# = 1"}`
— only published.&providerParams=`{total: 3}`
— items per page.&providerParams=`{orderBy: "#pub_date# DESC"}
— sort by publish date, new first.&outputterParams=`{templates: {item: documents_item}}`
— item template (chunk name).&outputterParams=`{templates: {wrapper: "@CODE:[+ddGetDocuments_items+][+extenders.pagination+]"}}`
— we need set where pagination will being outputted.&outputterParams=`{templates: {noResults: "@CODE:"}}`
— return nothing if nothing found.&extendersParams=`{pagination: {}}`
— pagination templates (see the parameters description).
Extenders → Search (&extenders=`search`
)
Call the snippet at the page with search results. Let's specify where and how deep we will search. Set up filter to get only necessary documets.
[[ddGetDocuments?
&fieldDelimiter=`#`
&providerParams=`{
parentIds: 1
depth: 3
filter:
'''
#published# = 1 AND
#deleted# = 0 AND
#template# = 11
'''
}`
&extenders=`search`
&extendersParams=`{
docFieldsToSearch: pagetitle,content,someTv
}`
&outputterParams=`{
templates: {
item: documents_item
}
}
]]
Then just add to the page URL ?query=Some query text
and the snippet returns only documents contain that string in the pagetitle
, content
or someTv
fields.
We recommend to use cashed snippet calls and turn on document caching type with $_GET parameters in CMS configuration.
Run the snippet through \DDTools\Snippet::runSnippet
without DB and eval
// Include (MODX)EvolutionCMS.libraries.ddTools require_once( $modx->getConfig('base_path') . 'assets/libs/ddTools/modx.ddtools.class.php' ); // Run (MODX)EvolutionCMS.snippets.ddGetDocuments \DDTools\Snippet::runSnippet([ 'name' => 'ddGetDocuments', 'params' => [ // It is convenient to set the parameter as a native PHP array or object 'providerParams' => [ 'parentIds' => 1, ], 'outputter' => 'json', ], ]);