Skip to content

Commit

Permalink
Version 2.1.1
Browse files Browse the repository at this point in the history
  • Loading branch information
Ronef committed Apr 12, 2020
2 parents 9b6c531 + 9402407 commit 3d3da5f
Show file tree
Hide file tree
Showing 5 changed files with 580 additions and 51 deletions.
6 changes: 6 additions & 0 deletions CHANGELOG.md
Original file line number Diff line number Diff line change
@@ -1,6 +1,11 @@
# (MODX)EvolutionCMS.snippets.ddMenuBuilder changelog


## Version 2.1.1 (2020-04-12)
* \+ README: Improvements.
* \+ README_ru.


## Version 2.1 (2020-03-07)
* \+ Snippet: All templates has the following placeholders:
* \+ `[+totalAllChildren+]` — total number of displayed children at all levels.
Expand Down Expand Up @@ -135,4 +140,5 @@
* \+ The first release.


<link rel="stylesheet" type="text/css" href="https://DivanDesign.ru/assets/files/ddMarkdown.css" />
<style>ul{list-style:none;}</style>
271 changes: 268 additions & 3 deletions README.md
Original file line number Diff line number Diff line change
@@ -1,11 +1,11 @@
# (MODX)EvolutionCMS.snippets.ddMenuBuilder


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](https://github.com/evolution-cms/evolution) >= 1.1
* [(MODX)EvolutionCMS.libraries.ddTools](https://code.divandesign.biz/modx/ddtools) >= 0.24.1
Expand All @@ -20,7 +20,7 @@ Initially inspired by combination of the Wayfinder and Ditto advantages with sig
#### 1. Elements → Snippets: Create a new snippet with the following data

1. Snippet name: `ddMenuBuilder`.
2. Description: `<b>2.1</b> Simple and flexible template-driven menu builder.`.
2. Description: `<b>2.1.1</b> Simple and flexible template-driven menu builder.`.
3. Category: `Core → Navigation`.
4. Parse DocBlock: `no`.
5. Snippet code (php): Insert content of the `ddMenuBuilder_snippet.php` file from the archive.
Expand All @@ -32,4 +32,269 @@ Initially inspired by combination of the Wayfinder and Ditto advantages with sig
2. Extract the archive to the folder (except `ddMenuBuilder_snippet.php`).


## [Home page →](http://code.divandesign.biz/modx/ddmenubuilder)
### 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 [JSON](https://en.wikipedia.org/wiki/JSON)
* `stringQueryFormated` — as [Query string](https://en.wikipedia.org/wiki/Query_string)
* 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'`

* `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 [JSON](https://en.wikipedia.org/wiki/JSON)
* `stringQueryFormated` — as [Query string](https://en.wikipedia.org/wiki/Query_string)
* Default value: —


##### 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`

* `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`

* `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`


##### 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>'`

* `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 [JSON](https://en.wikipedia.org/wiki/JSON)
* `stringQueryFormated` — as [Query string](https://en.wikipedia.org/wiki/Query_string)
* Default value: —


### Examples


#### Providers → Parent

```html
[[ddMenuBuilder?
&provider=`parent`
&providerParams=`{
"parentId": 1,
"depth": 2
}`
]]
```


#### Providers → Select

```html
[[ddMenuBuilder?
&provider=`select`
&providerParams=`{
"ids": [
1,
2,
3
]
}`
]]
```


#### Pass additional data into outer chunk (the `placeholders` parameter)

```html
[[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.

```html
[[ddMenuBuilder?
&provider=`parent`
&providerParams=`parentId=1&depth=2`
&templates=`outer=general_nav`
&placeholders=`pladeholder1={"someName": "someValue"}&pladeholder2={"name": "John"}`
]]
```


## [Home page →](http://code.divandesign.biz/modx/ddmenubuilder)


<link rel="stylesheet" type="text/css" href="https://DivanDesign.ru/assets/files/ddMarkdown.css" />
Loading

0 comments on commit 3d3da5f

Please sign in to comment.