lci/modx-menubuilder

Alternative/Replacement for the Wayfinder extra.

v0.2.2 2019-08-12 21:19 UTC

Requires

• ext-json: *
• ext-pdo: *
• lci/orchestrator: ^1.0.0

MIT

• Joshua Gulledge

• modx

README

An easy way to build HTML navigation menus. MenuBuilder is an alternative/replacement for the Wayfinder extra.

Features

• Use different Chunks for every level of your menu if you choose
• Performance, loads all menu items from a single SQL query
• Simpler design and usage, faster to get up and going and more flexible.

Install

Requires an installation of MODX

• Install Orchestrator
• Add to the composer.json file as below
• Add to your .env file parameters in the sample.env file and customize.
• Run composer update
• If you did not set up Orchestrator as the LocalOrchestrator example or you want to manually call the install script.
  Run $ php vendor/bin/orchestrator orchestrator:package lci/modx-menubuilder from where you have composer.json.

Composer.json

Add the following to your composer.json file

{
  "require": {
    "lci/modx-menubuilder": "dev-master"
  },
  "repositories": [
    {
      "type": "vcs",
      "url": "https://github.com/LippertComponents/MenuBuilder"
    }
  ],
  "extra": {
    "auto-install": [
      "lci/modx-menubuilder"
    ]
  },
  "minimum-stability": "dev"
}

What is installed in MODX

• Custom database table: modx_mb_sequence
• Snippets menuBuilder
• A Plugin: buildMenuSequence and attach System Events:
  • OnDocFormSave
  • OnResourceSort
  • OnCacheUpdate
• Save or sort a Resource in the MODX Tree and it will populate the database and will for every on change.
• MODX namespace: menubuilder
• System settings will allow you to turn off when the menu sequence rebuilds happen:
  • menubuilder.rebuildOnCacheUpdate
  • menubuilder.rebuildOnDocFormSave
  • menubuilder.rebuildOnResourceSort
  • menubuilder.logDebug

Build a navigation menu

Place a Snippet call into your appropriate Template/Chunk/Resource. Like:

[[menuBuilder?
    &startId=`1`
]]

Chunks used

By default will generate an unordered list.

Note (bool) stands for boolean which is true/false or 1/0.

Property	Description	Default
chunkItem	The Chunk name that will be used to render the item/Resource/link
chunkWrapper	The Chunk that will wrap a level or list of items
chunkItem#Level	Replace #Level with a number, it will override the chunkItem Chunk for related level
chunkWrapper#Level	Replace #Level with a number, it will override the chunkWrapper Chunk for related level
chunkItemResource#ID	Replace #ID with a valid Resource ID number, it will override the chunkItem and related chunkItem#Level
chunkWrapperResource#ID	Replace #ID with a valid Resource ID number, it will override the chunkWrapper and related chunkWrapper#Level

General options

Property	Description	Default
startId	The starting point (Resource ID) for the menu to list documents from. Specify 0 to start from the site root.	0
displayStart	Show the document as referenced by &startId in the menu.	(bool) 0
level	Depth (number of levels) to build the menu from. '0' goes through all levels.	0
limit	The limit parameter the total number of items specified
limitLevelItems	JSON style ex: &limitLevelItems=`{"1":"5","2":"4"}` The name/left is the level and the right is the limit.
resourceColumns	Comma separated list of Resource columns to add to existing columns to be included for items	id, context_key, pagetitle, longtitle, menutitle, parent, menuindex, link_attributes, template
viewHidden	(bool) Hide/Show based on the value of "Hide From Menus" checkbox	0
viewHiddenFromTree	(bool) Hide/Show based on the value of the column show_in_tree, 1 will show all, 0 will filter where show_in_tree=1	0
viewUnpublished	(bool)	0
viewDeleted	(bool)	0
placeholder	Name of a placeholder to send results to, instead of directly returning the output.
debug	(bool) Set to '1' to enable debug mode for extra troubleshooting.	0
debugSql	(bool) Will output the SQL that is generated by your property settings	0
iterateType	getIterator or PDO	getIterator
where	JSON style filtering option. For example when trying to hide blog or news from the Articles addon: &where=[{"class_key:!=": "Article"}]
contexts	Comma separated list of Context_keys to use for building the menu.	Default is current context
scheme	format for how URLs are generated.	System Setting
rawTvs	Comma separated list of TVs to include you will then use like: [[+tvMainImage]], the first letter of the name will be made uppercase
processTvs	Comma separated list of TVs to process include you will then use like: [[+tvMainImage]], the first letter of the name will be made uppercase. Note: the iterateType property must be set to getIterator
hereClass	CSS class passed to all resource items in current/active branch, showing where you are located.	active
selfClass	CSS class passed only to the current resource/item.