dd / evolutioncms-snippets-ddmenubuilder
Simple and flexible template-driven menu builder. Initially inspired by combination of the Wayfinder and Ditto advantages with significant code simplification.
Installs: 2
Dependents: 0
Suggesters: 0
Security: 0
Stars: 0
Watchers: 3
Forks: 0
Open Issues: 2
Type:modxevo-snippet
Requires
- php: >=5.6.0
- dd/modxevo-library-ddtools: >=0.59.0
This package is auto-updated.
Last update: 2024-11-06 09:23:22 UTC
README
Simple and flexible template-driven menu builder. Initially inspired by combination of the Wayfinder and Ditto advantages with significant code simplification.
Requires
- PHP >= 5.6
- (MODX)EvolutionCMS >= 1.1
- (MODX)EvolutionCMS.libraries.ddTools >= 0.59
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.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.
Manually
1. Elements → Snippets: Create a new snippet with the following data
- 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.
2. Elements → Manage Files:
- Create a new folder
assets/snippets/ddMenuBuilder/
. - Extract the archive to the folder (except
ddMenuBuilder_snippet.php
).
Parameters description
Data provider parameters
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: —
Providers → Parent (&provider=`parent`
)
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
Providers → Select (&provider=`select`
)
Just output selected documents.
-
providerParams->ids
- Desctription: Document IDs.
- Valid values:
array
stringCommaSepareted
- Required
-
providerParams->ids[i]
- Desctription: Document IDs.
- Valid values:
integerDocumentID
- Required
General parameters
-
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
Template parameters
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.
Item 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
Parent item templates
-
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
Outer template
-
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
Examples
All examples are written using HJSON, but if you want you can use vanilla JSON instead.
Providers → Parent
[[ddMenuBuilder? &provider=`parent` &providerParams=`{ parentId: 1 depth: 2 }` ]]
Providers → Select
[[ddMenuBuilder? &provider=`select` &providerParams=`{ ids: [ 1 2 3 ] }` ]]
Pass additional data into outer chunk (the placeholders
parameter)
[[ddMenuBuilder? &templates=`{ outer: ''' @CODE:<ul class="[+class+]">[+children+]</ul>[+somePlaceholder2+] ''' }` &placeholders=`{ class: someClass somePlaceholder2: <p>Some value for placeholder.</p> }` ]]
Using Query string instead of JSON
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"}` ]]
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.ddMenuBuilder \DDTools\Snippet::runSnippet([ 'name' => 'ddMenuBuilder', 'params' => [ 'providerParams' => [ 'parentId' => 1 ] ] ]);