Aligning interfaces for widgets and nav menus

[westonruter]

Widgets and nav menus are very similar in how they are structured in that both consist of collections of items which can be ordered. Indeed, nav menus could be entirely removed from core and in their place widgets could be used to build out navigation, with a “nav menu item” widget that has all the properties of a nav menu item. Nevertheless, there are some big differences in how widgets and nav menus are represented in the WP DB and as such there are certain restrictions on how they can be manipulated, but it would be great to align the REST APIs to reduce the cognitive load by harmonizing the interfaces.

Current: Nav Menus

• Nav menu items are stored as a nav_menu_item post type.
• A nav menu item can be uniquely identified by a single numeric ID (a post ID).
• Nav menus items are associated with a nav menu by means of a nav_menu taxonomy.
• Nav menu items' position within their assigned nav menu is stored in post.menu_order.
• Since nav menu item positions are stored in post.menu_order, a nav menu item cannot be associated with more than one nav menu since there is only one position available.
• A nav menu is a mutatable data type which persists across theme switches.
• A nav menu is associated with a nav menu location and this is how it is displayed.
• The WordPress UI does not allow nav menu items to exist without an associated nav menu taxonomy term. (There are no orphaned nav menu items.)

  Current: Widgets

• Widget instances are stored in WP options, with an array of widgets for a given type stored in a single options (e.g. widget_text contains a serialized array of all widget instances, where the array indicies indicate the widget numbers which then get used to construct widget IDs such as text-123).
• A widget cannot be uniquely identified by a numeric ID, but must always include the id_base since the number is merely an array index for the array of widgets of that type. In this way, widgets in Core are currently in a similar situation as shared terms in Core, where a taxonomy term could not be uniquely identified by a term ID alone and a taxonomy name had to be supplied as well. For more information, see https://github.com/WP-API/wp-api-menus-widgets-endpoints/issues/12#issuecomment-177275265.
• Widgets are associated with a sidebar by storing a list of the widget IDs in a sidebars_widgets option which consists of an array of arrays, keyed by the sidebar ID and with the values being arrays of widget IDs for the respective sidebars.
• Widgets are positioned within a sidebar by their relative ordering in the sidebars_widgets option. Technically a widget could appear in multiple sidebars, but the UI does not support this.
• A sidebar is not mutable, being defined statically in a theme. A sidebar is theme-dependent.
• A sidebar is the way a grouping of widgets is associated with a location in a theme.
• Widgets can exist without being associated with a sidebar, and as such they can be listed among inactive or orphaned widgets.

  Harmonization possibilities

• Widgets could be associated with multiple sidebars with an update to the UI.
• Nav menu items could be associated with multiple nav menus if the nav menu item positions were stored in the term meta for a given nav menu (e.g. nav_menu_item_positions, consisting of a list of post IDs).
• A “widget group” object could be introduced which would be analogous to a nav menu, where widget groups would be assigned to sidebars. Widget groups would have mutatable properties (e.g. title), and they would persist across theme switches. For more information, see Trac #19912.
• Widget instances could be stored as posts, where integer IDs could uniquely identify a widget without needing a corresponding id_base. Sidebars could be taxonomy terms, with the widget positions stored in term meta. See #35669.

[danielbachhuber]

Great writeup, Weston :+1:

[westonruter]

Added points contrasting how widget instances and nav menu items are identified, with widgets being addressed in a similar way to terms prior to term splitting. Opened core ticket to harmonize by storing widgets in custom post type: https://core.trac.wordpress.org/ticket/35669