Skip to content

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.

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 under other_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.

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.

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.

Update menu item (aafm/update-menu-item) can move an item as well as rename it:

  • parent_id nests 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.
  • position sets 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.

Create page and Update page take two more inputs, for pages only:

  • parent_id puts 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.
  • template picks one of the page templates the active theme offers (a file name on a classic theme, a template slug on a block theme), or default. 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.

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.