Simple and flexible template-driven menu builder. Initially inspired by combination of the Wayfinder and Ditto advantages with significant code simplification.
- PHP >= 5.6
- (MODX)EvolutionCMS >= 1.1
- (MODX)EvolutionCMS.libraries.ddTools >= 0.59
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.ddMenuBuilder
\DDInstaller::install([
'url' => 'https://github.com/DivanDesign/EvolutionCMS.snippets.ddMenuBuilder',
'type' => 'snippet'
]);
- If
ddMenuBuilder
is not exist on your site,ddInstaller
will just install it. - If
ddMenuBuilder
is already exist on your site,ddInstaller
will check it version and update it if needed.
- Snippet name:
ddMenuBuilder
. - Description:
<b>2.2</b> Simple and flexible template-driven menu builder.
. - Category:
Core → Navigation
. - Parse DocBlock:
no
. - Snippet code (php): Insert content of the
ddMenuBuilder_snippet.php
file from the archive.
- Create a new folder
assets/snippets/ddMenuBuilder/
. - Extract the archive to the folder (except
ddMenuBuilder_snippet.php
).
Providers get documents data to output.
-
provider
- Desctription: Name of the provider that will be used to fetch documents.
- Valid values:
'parent'
'select'
- Default value:
'parent'
-
providerParams
- Desctription: Parameters to be passed to the provider.
- Valid values:
stringJsonObject
— as JSONstringHjsonObject
— as HJSONstringQueryFormatted
— 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: —
Select children documents from required parent(s).
-
providerParams->parentIds
- Desctription: Parent IDs — the starting points for the menu. Specify '0' to start from the site root.
- Valid values:
array
stringCommaSepareted
- Default value:
'0'
-
providerParams->parentIds[i]
- Desctription: Parent ID.
- Valid values:
integerDocumentID
- Required
-
providerParams->depth
- Desctription: The depth of documents to build the menu.
- Valid values:
integer
- Default value:
1
Just output selected documents.
-
providerParams->ids
- Desctription: Document IDs.
- Valid values:
array
stringCommaSepareted
- Required
-
providerParams->ids[i]
- Desctription: Document IDs.
- Valid values:
integerDocumentID
- Required
-
sortDir
- Desctription: The sorting direction (by
menuindex
field). - Valid values:
'ASC'
'DESC'
- Default value:
'ASC'
- Desctription: The sorting direction (by
-
showPublishedOnly
- Desctription: Show only published documents.
- Valid values:
0
1
- Default value:
1
-
showInMenuOnly
- Desctription: Show only documents visible in the menu.
- Valid values:
0
1
- Default value:
1
templates
- Desctription: Templates.
Placeholders available in all templates:[+id+]
[+menutitle+]
— will be equal to[+pagetitle+]
if empty.[+pagetitle+]
[+published+]
[+isfolder+]
[+totalAllChildren+]
[+totalThisLevelChildren+]
[+level+]
- Valid values:
stringJsonObject
— as JSONstringHjsonObject
— as HJSONstringQueryFormatted
— 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: —
- Desctription: Templates.
-
templates->item
- Desctription: The menu item template.
- Valid values:
stringChunkName
string
— use inline templates starting with@CODE:
- Default value:
'@CODE:<li><a href="[~[+id+]~]" title="[+pagetitle+]">[+menutitle+]</a></li>'
-
templates->itemHere
- Desctription: The menu item template for the current document.
- Valid values:
stringChunkName
string
— use inline templates starting with@CODE:
- Default value:
'@CODE:<li class="active"><a href="[~[+id+]~]" title="[+pagetitle+]">[+menutitle+]</a></li>'
-
templates->itemActive
- Desctription: The menu item template for a document which is one of the parents to the current document when the current document doesn't displayed in the menu (e. g. excluded by the
depth
parameter). - Valid values:
stringChunkName
string
— use inline templates starting with@CODE:
- Default value: =
templates->itemHere
- Desctription: The menu item template for a document which is one of the parents to the current document when the current document doesn't displayed in the menu (e. g. excluded by the
-
templates->itemUnpub
- Desctription: The menu item template for unpublished document (when
showPublishedOnly
==0
). - Valid values:
stringChunkName
string
— use inline templates starting with@CODE:
- Default value: =
templates->item
- Desctription: The menu item template for unpublished document (when
-
templates->itemUnpubActive
- Desctription: The menu item template for unpublished document which is one of the parents to the current document when the current document doesn't displayed in the menu (e. g. excluded by the
depth
parameter). - Valid values:
stringChunkName
string
— use inline templates starting with@CODE:
- Default value: =
templates->itemActive
- Desctription: The menu item template for unpublished document which is one of the parents to the current document when the current document doesn't displayed in the menu (e. g. excluded by the
-
templates->itemParent
- Desctription: The menu item template for documents which has a children displayed in menu.
- Valid values:
stringChunkName
string
— use inline templates starting with@CODE:
- Default value:
'@CODE:<li><a href="[~[+id+]~]" title="[+pagetitle+]">[+menutitle+]</a><ul>[+children+]</ul></li>'
-
templates->itemParentHere
- Desctription: The menu item template for the current document when it has children displayed in menu.
- Valid values:
stringChunkName
string
— use inline templates starting with@CODE:
- Default value:
'@CODE:<li class="active"><a href="[~[+id+]~]" title="[+pagetitle+]">[+menutitle+]</a><ul>[+children+]</ul></li>'
-
templates->itemParentActive
- Desctription: The menu item template for a document which has the current document as one of the children.
- Valid values:
stringChunkName
string
— use inline templates starting with@CODE:
- Default value: =
templates->itemParentHere
-
templates->itemParentUnpub
- Desctription: The menu item template for unpublished documents which has a children displayed in menu.
- Valid values:
stringChunkName
string
— use inline templates starting with@CODE:
- Default value: =
templates->itemParent
-
templates->itemParentUnpubActive
- Desctription: The menu item template for an unpublished document which has the current document as one of the children.
- Valid values:
stringChunkName
string
— use inline templates starting with@CODE:
- Default value: =
templates->itemParentActive
-
templates->outer
- Desctription: Wrapper template.
Available placeholders:[+children+]
— Generated HTML with all items.
- Valid values:
stringChunkName
string
— use inline templates starting with@CODE:
- Default value:
'@CODE:<ul>[+children+]</ul>'
- Desctription: Wrapper template.
-
placeholders
- Desctription:
Additional data has to be passed into the
templates->outer
.
Arrays are supported too:some[a]=one&some[b]=two
=>[+some.a+]
,[+some.b+]
;some[]=one&some[]=two
=>[+some.0+]
,[some.1]
. - Valid values:
stringJsonObject
— as JSONstringHjsonObject
— as HJSONstringQueryFormatted
— 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: —
- Desctription:
Additional data has to be passed into the
All examples are written using HJSON, but if you want you can use vanilla JSON instead.
[[ddMenuBuilder?
&provider=`parent`
&providerParams=`{
parentId: 1
depth: 2
}`
]]
[[ddMenuBuilder?
&provider=`select`
&providerParams=`{
ids: [
1
2
3
]
}`
]]
[[ddMenuBuilder?
&templates=`{
outer:
'''
@CODE:<ul class="[+class+]">[+children+]</ul>[+somePlaceholder2+]
'''
}`
&placeholders=`{
class: someClass
somePlaceholder2: <p>Some value for placeholder.</p>
}`
]]
JSON syntax is more clear than Query string, but sometimes it's not convenient. For example, if you want to pass JSON string as string.
[[ddMenuBuilder?
&provider=`parent`
&providerParams=`parentId=1&depth=2`
&templates=`outer=general_nav`
&placeholders=`pladeholder1={"someName": "someValue"}&pladeholder2={"name": "John"}`
]]
//Include (MODX)EvolutionCMS.libraries.ddTools
require_once(
$modx->getConfig('base_path') .
'assets/libs/ddTools/modx.ddtools.class.php'
);
//Run (MODX)EvolutionCMS.snippets.ddMenuBuilder
\DDTools\Snippet::runSnippet([
'name' => 'ddMenuBuilder',
'params' => [
'providerParams' => [
'parentId' => 1
]
]
]);