pdoMenu

Last updated May 8th, 2019 | Page history | Improve this page | Report an issue

Support the team building MODX with a monthly donation.

The budget raised through OpenCollective is transparent, including payouts, and any contributor can apply to be paid for their work on MODX.

Backers

Budget

$301 per month—let's make that $500!

Learn more

Menu generator snippet. It can replace Wayfinder, and allows more flexibility to specify properties.

For example, it can build menus from several parents, showing them both together and as separate branches.

Provides a substantial increase in speed, although only on first page view if the Wayfinder menu is cached.

If you never used Wayfinder before, it is a good idea to read the Wayfinder documentation, because pdoMenu reuses many of the Wayfinder concepts and settings. You can find the docs here, or download the excellent (but 184 page) Wayfinder ebook from this thread.

Properties¶

Name	Default	Description
&parents	Current resource	Comma-separated list of parents to search for results. If set to 0 will use all top-level resources. If the parent ID starts with a hyphen, it and its children are excluded from the result.
&level	0 (no limit)	The level(depth) of the generated menu.
&resources		Comma-separated list of resources to add into the results. If the ID of the resource starts with a dash, this resource is excluded from the results.
&templates		Comma-separated list of templates to filter results. If the template ID starts with a dash, resources using it are excluded from the results.
&where		An array of additional parameters encoded as JSON.
&displayStart	0	Include display of parent node. It is useful when you specify more than one «parents».
&context		Specifying the Context of the resources to build the menu from.
&showHidden	0	Show resources that are marked to be hidden in the menu.
&showUnpublished	0	Show unpublished resources to everyone.
&previewUnpublished	0	Show unpublished resources only for logged-in Manager users with permission to view unpublished.
&hideSubMenus	0	Hide inactive submenu branches.
&select		Comma-separated list of fields to retrieve. You can specify a JSON string array, for example {"modResource":"id,pagetitle,content"}. By default, all fields of the modResource object are selected. You don't need this option if you want to use fields like `[[+introtext]]` because they are already available. This option should be used if you do not want to retrieve all fields, but only those which you specify.
&sortby	menuindex	Any resource field for sorting, including TV option the property &includeTVs is set. A JSON string can be specified with an array of several fields, for example {"tvname":"ASC", "pagetitle":"DESC"}. To randomly select sorting use «RAND()».
&sortdir	ASC	Sort Direction: Ascending or Descending. If parameters &sortby and &sortdir will be empty the sorting will be in the order of resources in &resources parameter.
&limit	0	Limit the number of results. Can be set to «0» for no limit.
&offset	0	Results skip from the beginning. It should be used with &limit
&checkPermissions		Specify which user permissions to check when listing resources. If no permissions are specified, permissions will not be checked at all. For example, &checkPermissions=`list`
&countChildren	0	Count of the number of children of each parent resource and output it to the placeholder `[[+children]]`. It makes additional queries to the database, so is 0 by default.
&toPlaceholder		If not empty, the snippet will save its output to a placeholder with the same name, instead of returning the generated menu.
&plPrefix	wf.	Prefix for placeholders used in the template chunks
&showLog	0	Show debugging details on the processing of the snippet. Only displayed to logged-in Manager users.
&fastMode	0	Quick mode for processing chunks. All raw tags (output modifiers, snippets, etc.) are removed.
&cache	0	Caching snippet results.
&cacheTime	3600	Duration of the cache in seconds.
&scheme	-1 (relative to site_url)	How the URL is generated, based on values valid for the modX::makeUrl() API.
&useWeblinkUrl	1	When set to 1, the URL specified in a weblink resource will be output to the placeholder «[[+link]]» instead of the link to the weblink resource itself.
&rowIdPrefix		If set, this parameter creates a unique ID for each item. The value will be rowIdPrefix + docId.
&hereId		Define the current ID to use for the snippet. Use a value of `[[id]]` if the template specified by &tplHere* and &tplParentRowActive is not applied correctly to the menu item.
&includeTVs		Define comma delimited list of TVs to include. For example, «action,time» will yiled placeholders `[[+action]]` & `[[+time]]`
&tvPrefix		Prefix TV property.

Template Properties¶

These properties specify the chunks that contain the templates to format the parts of the generated menus.

As stated above, if you never used Wayfinder before, at least skim through the Wayfinder docs before using your own chunks, even though pdoMenu uses a slightly different chunk hierarchy.

Even if you don't read the docs, make sure to include [[+wrapper]] in your chunks. Contrary to its name, it is a placeholder for wrapper content (it is similar to [[*content]] in your Resources). It will be replaced with your lower-level menu content. If you leave it out, parts of your menu or the whole menu will disappear without any error message.

Name	Description
&tplOuter	Chunk to wrap the entire menu block. default: `@INLINE <ul[[+classes]]>[[+wrapper]]</ul>`
&tpl	Chunk for processing each resource. If not specified, the contents of the resource fields will be printed to the screen. Default: `@INLINE <li[[+classes]]><a href="[[+link]]" [[+attributes]]>[[+menutitle]]</a>[[+wrapper]]</li>`
&tplParentRow	Chunk for container item with children.
&tplParentRowHere	Chunk for current container item.
&tplHere	Chunk for the current resource
&tplInner	Chunk wrapper for submenu sections. If empty will use &tplOuter
&tplInnerRow	Chunk for submenu rows.
&tplInnerHere	Chunk for submenu current item.
&tplParentRowActive	Chunk for active category.
&tplCategoryFolder	Special chunk for category resources. Category resources have isfolder = 1, and «(empty)» template or attribute «rel = category». Useful for creating top-level menu items that are not themselves active links.
&tplStart	Chunk for the parent resource, provided that &displayStart is also used. Default: `@INLINE <h2[[+classes]]>[[+menutitle]]</h2>[[+wrapper]]`

Properties for CSS classes¶

These properties specify the value of the placeholder [[+classes]] and [[+classnames]] for the various parts of the menu.

Name	Description
&firstClass	Class for the first menu item. Default: first
&lastClass	Class for the last menu item. Default: last
&hereClass	Class for the active menu item and its parents. Default: active
&parentClass	Class for parent items.
&rowClass	Class for each menu row.
&outerClass	Class for outer wrapper.
&innerClass	Class for inner submenu wrappers.
&levelClass	Class for each level of the menu. For example, if you specify «level», it will produce «level1», «level2» etc.
&selfClass	Class for the current document in the menu.
&webLinkClass	Class for the weblink resources.

Examples¶

A simple top-level menu:

[[pdoMenu?
    &parents=`0`
    &level=`1`
]]

2-level menu with the exception of certain parents:

[[pdoMenu?
    &parents=`-10,-15`
    &level=`2`
    &checkPermissions=`load,list,view`
]]

Menu generated from two parents, showing the parents:

[[pdoMenu?
    &parents=`10,15`
    &displayStart=`1`
]]

List all resources in one step:

[[pdoMenu?
    &parents=`0`
    &level=`2`
    &tplInner=`@INLINE [[+wrapper]]`
    &tplParentRow=`@INLINE <li[[+classes]]><a href="[[+link]]" [[+attributes]]>[[+menutitle]]</a> ([[+children]])</li>[[+wrapper]]`
    &countChildren=`1`
]]