[#menubars-layout]
= MenuBars Layout

:Notice: Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at. http://www.apache.org/licenses/LICENSE-2.0 . Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR  CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.
:page-partial:


The `org.apache.causeway.applib.layout.menubars` package and subpackages define a number of interfaces classes that allow the layout of domain service actions to be organised across menu bars, menus and menu sections.

The classes define a hierarchical structure of menu bars, menus and menu sections.
Similar to the xref:applib-classes:layout.adoc[object layout] classes, the concrete menu classes support bootstrap3; support for other layout systems is possible.

The component class `ServiceActionLayoutData` defines action metadata, being broadly equivalent to the "layout" annotations for actions, ie xref:refguide:applib:index/annotation/ActionLayout.adoc[@ActionLayout].
This is similar to the `ActionLayoutData` component class used for object layouts, but also captures the identity of the "owning" domain service.
Service actions are grouped into menu sections.

All of the classes in this package are JAXB-annotated, meaning that they can be serialized to/from XML (in the `https://causeway.apache.org/applib/layout/menubars/bootstrap3` XSD namespace).
This ability to serialize to/from XML is used by the xref:refguide:applib:index/services/menu/MenuBarsLoaderService.adoc[MenuBarsLoaderService], the default implementation of which reads the grid layout for a domain class from a `.layout.xml` file on the classpath.
It also allows the menu bars to be exposed through the REST API provided by the xref:vro:ROOT:about.adoc[REST API (Restful Objects viewer)], as either XML or JSON.

The service action component also allows a link to be associated with it.
Each such link is populated by the framework automatically when exposing the menu bars layout through the REST API, pointing back to the standard Restful Objects resources.
This design greatly assists in the implementation of generic REST clients.


== Menus

The menu classes reside in the `org.apache.causeway.applib.layout.menubars.bootstrap3` package, consisting of:

* `BS3MenuBars`

+
The top-level structure that define three fields: a primary `BS3MenuBar`, secondary `BS3MenuBar` and tertiary `BS3MenuBar`.
The xref:vw:ROOT:about.adoc[Web UI (Wicket viewer)] places the primary bar to the left, the secondary bar aligned right, and the tertiary bar (expected to consist of just one `BS3Menu`) under the user names.

* `BS3MenuBar`

+
consisting of one or many ``BS3Menu``s.

* `BS3Menu`

+
consisting of one or many ``BS3MenuSection``s.
The xref:vw:ROOT:about.adoc[Web UI (Wicket viewer)] renders a separator between each section.

* `BS3MenuSection`

+
consisting of one or many actions (``ServiceActionLayoutData``s)

== Components

The service action class reside in the `org.apache.causeway.applib.layout.component` package, consisting of just:

* `ServiceActionLayoutData` class

+
which correspond to the xref:refguide:applib:index/annotation/ActionLayout.adoc[@ActionLayout] annotation.

This is similar to `ActionLayoutData` (of the xref:applib-classes:layout.adoc[object layout] classes), however it also identifies the domain service to which it belongs.
(This isn't required for the object layouts because the owner in that case is implicit).

== Link

The link classes reside in the `org.apache.causeway.applib.layout.links` package, and consist of just the `Link` class.

The XSD for these classes is available at link:https://causeway.apache.org/applib/layout/links/links.xsd[].
