Menus, page structure and the homepage
Since 1.12.0 an agent can work on a site’s structure as well as its content: the navigation menus of a block theme, where items sit in a classic menu, which page sits under which, and what the homepage shows. Like every tool, each one here starts off until you enable it.
Block-theme navigation
Section titled “Block-theme navigation”A block theme keeps its menus as navigation posts, the ones a Navigation block shows. Two tools work on them. Classic menus are a different thing, and the menu tools work on those.
- List navigations (
aafm/list-navigations), a read tool. It lists each navigation by id, title and status, with its links as a nested tree of label, URL and children. Blocks the tree can’t show, such as a page list or a search box, are named underother_blocks. A site with no navigations, usually one on a classic theme, gets an empty list. - Update navigation (
aafm/update-navigation), a write tool. It replaces the links of one navigation with the list you send: each item a label and a URL, with optional children. It can also set the title.
Both need a user who can edit theme options (edit_theme_options). The Read only
access preset reaches List
navigations; Update navigation is in no preset except Custom.
What Update navigation accepts
Section titled “What Update navigation accepts”| Limit | Value |
|---|---|
| Depth | Three levels |
| Items | At least 1 and at most 100 in all, counting nested ones |
| Labels | 1 to 200 characters of plain text |
| URLs | An http, https, mailto or tel link, a path starting with /, or an anchor starting with # |
A URL with any other scheme is refused, and so is an empty list.
What gets replaced
Section titled “What gets replaced”The whole navigation is replaced, including any blocks List navigations names
under other_blocks. Each link is saved as a plain custom link, so per-link
settings such as open in a new tab, rel, CSS classes and a link’s binding to a
page or post are not kept. The tool reads the saved navigation back and returns
it, and returns an error if WordPress stored something other than the list it sent.
A navigation owned by a page builder is refused, and so is one whose owner the plugin can’t tell.
Classic menu items
Section titled “Classic menu items”Update menu item (aafm/update-menu-item) can
move an item as well as rename it:
parent_idnests the item under another item of the same menu, or 0 moves it to the top level. The item itself or one of its own sub-items is refused.positionsets the item’s stored position (its menu order), 1 or more. Items sort by this value and the other items keep theirs, so two items can share one.
Menus are not recorded in the change history.
Page parent and template
Section titled “Page parent and template”Create page and Update page take two more inputs, for pages only:
parent_idputs the page under another page, or 0 for none. The parent must be a page outside the Trash, and Update page refuses a parent that would put the page under itself or one of its own sub-pages.templatepicks one of the page templates the active theme offers (a file name on a classic theme, a template slug on a block theme), ordefault. Any other value is refused.
A page in a tool’s response now carries parent_id and template too. Sending either
input for a post is refused. The change history records and restores both for
Update page.
The static homepage
Section titled “The static homepage”Update site settings (aafm/update-site-settings)
accepts three homepage keys, and Get site settings
returns them:
| Key | Value |
|---|---|
show_on_front |
posts or page |
page_on_front |
The id of a published page, or 0 for none |
page_for_posts |
The id of a published page, or 0 for none |
The plugin checks the three together before it writes anything. The front page and
the posts page must be different pages, and show_on_front: page needs a front
page. A negative id is refused. It then writes them in the order page_on_front,
page_for_posts, show_on_front.
A call that sends any homepage key gets three lists back: landed (saved),
unchanged (already held that value) and failed (not saved). If one did not
save, the call returns an error naming them. It also gets side_effects, the
homepage keys the request did not name that another plugin changed during the
call. The Events Calendar, for example, clears page_on_front when show_on_front
becomes posts.
Both settings tools need manage_options. Update site settings is a destructive
tool, and site settings are not recorded in the change history.
Next steps
Section titled “Next steps”- Undo and change history: which tools the Changes tab can revert.
- Page builders: editing Avada and WPBakery Page Builder pages.
- Abilities catalog: every tool, with its permission and risk.