1. Atlassian Avatar Atlassian
  2. Project: Atlassian
  3. aui-adg

Wiki

Clone wiki

aui-adg / tutorial / add-page-layout-and-navigation

View History

#Add page layout and navigation

On this page, you learn about decorators and layout. You then make your plugin compliant with the ADG by adding more AUI library code to your plugin. Finally, you’ll learn how to add a horizontal navigation bar to your plugin.

Table of contents

[TOC]

##Backgrounder: Decorating Your Stuff
The best plugin design shows customers they are in an Atlassian product and that they are using your plugin. The ADG gives you three places to to this:

  • The application header has a common pattern across the entire Atlassian application suite. The left side of the header has the unique application logo and navigation. The right side of the header is for search, administrative menu, help menu, and user menu.
  • The page header gives context to the page content. It should have a title but might also have an avatar, metadata, and context specific actions.
  • The page footer contains product information like version, system, and support links. You can add more but keep in mind that in design sometimes less is more powerful.

![Identify](images/indentify.jpeg)

Designers call common elements for a site design, page decorations.

  1. Add Basic Page Decorator
    The AUI basic page layout is based on a grid. The grid is the foundation for harmonious element positioning. The grid’s goal is bring a consistent and coherent look to each page. The resulting page should convey calm and display content that is easy scanned by users. In this section, you add the alt.general decorator to generate a basic layout like this:

```
<body class=“aui-layout aui-theme-default”> <div id=“page”> <header id=“header” role=“banner”> </header> <section id=“content” role=“main”> </section> <footer id=“footer” class=“refapp-footer”> </footer> </div>
</body>
```

To add the decorator to your project, do the following:

  • In your project directory, open your helloaui.vm template.
  • Add the atl.general decorator to your page code:

```
<html> <head> <title>MyServlet Admin</title> <meta name=“decorator” content=“atl.general”> </head> <body> <h2>Plugin Form</h2> </body>
</html>
```

  • Save and close the file.
  • Back in your browser reload your servlet page.
  • The live reload automatically picks up your template change. Your plugin page that before looked like this:

![Reloaded](images/reloaded.jpeg)

After the change should look like this:

![Decorator](images/decorator1.jpeg)

The decorator added an application header and footer.

  • View the source of this new page.
    You can use your browser’s developer tools to inspect the the document object model (DOM). In Chrome, you inspect a browser page by right-clicking in the page and choosing Inspect Element from the context menu.

![Inspect](images/inspect.jpeg)

  • Examine the `<body>` contents in the generated page.
    Compared to your template, you’ll find a lot of AUI layout controls. These were generated for you by adding the `atl.general` decorator.

To space the elements on a page grid, you need to set up specify some padding and margins. The decorator does a lot of this for you through classes. Notice in your generated page the `<body>` element now has `aui-layout` and `aui-theme-default` classes.

  1. Add AUI Page Layout
    In this step, you add some layout classes that the atl.general decorator did not give you. You also add more content to the page.

  • Edit the helloaui.vm page and update the header with a <header> and a <div> tag.

```
<header class=“aui-page-header”> <div class=“aui-page-header-inner”> <h2>Plugin Form</h2> </div>
</header>
```

You’ll notice adding these to elements with their special classes refined the alignment of your page header.

Add a content placeholder beneath your page header.
You do this by adding two div elements and a section. Each element has a specific class: `aui-page-panel`, `aui-page-panel-inner` and `aui-page-panel-content`. When you are done. Your code in your velocity template should appear as follows:

``` <body> <header class=“aui-page-header”> <div class=“aui-page-header-inner”> <h2>Plugin Form</h2> </div> </header> <div class=“aui-page-panel”> <div class=“aui-page-panel-inner”> <section class=“aui-page-panel-content”> Content </section> </div> </div>
</body>
```

Save your changes.

The [http://docs.atlassian.com/aui/latest/](AUI documentation) contains examples of page layouts and components, along with their associated classes.

  1. Add a Horizontal Nav
    The guidelines instruct you use to use horizontal or vertical navigation to navigate between page contexts. If an individual context has multiple views, you use tabs to switch between these multiple views.
  • Edit the helloaui.vm file.
    Add a `<nav>` block to your file right after the `<header>` block.

```
<nav id=“main-nav” class=“aui-navgroup aui-navgroup-horizontal”>
</nav>
```

You can see that this block is horizontal. By switching the class, you could easily implement vertical navigation later.

  • Ensure the spacing for your navigation bar by providing an inner and then primary <div> component.

```
<nav id=“main-nav” class=“aui-navgroup aui-navgroup-horizontal”> <div class=“aui-navgroup-inner”> <div class=“aui-navgroup-primary”> </div> </div> </nav>
```

At this point, if you are saving after each change, you haven’t seen the live reload make any changes in you page.

  • Add the navigation tabs into the primary `<div>` block.

```
<nav id=“main-nav” class=“aui-navgroup aui-navgroup-horizontal”> <div class=“aui-navgroup-inner”> <div class=“aui-navgroup-primary”> <ul class=“aui-nav”> <li id=“general-nav-item” class=“aui-nav-selected”><a href=”#”>General</a></li> <li id=“advanced-nav-item”><a href=”#”>Advanced</a></li> </ul> </div> </div>
</nav>
```

  • Save the `helloaui.vm` file.
    You should see the following in your dialog:

![Inspect](images/new_tabs.jpeg)

  1. Step 4. Add Content to Your Nav Panels
    You have navigation but no content under each page. You use an aui-page-panel to hold your page content.

  • Edit the `helloaui.vm` file.
  • Replace the contents within the `aui-page-panel-content` section.

```
<section class=“aui-page-panel-content”> <div class=“nav-content” id=“content-1”> General Content </div> <div class=“nav-content” id=“content-2”> Advanced Content </div>
</section>
```

Save the file.

Of course, you might have noticed that the nav on your page doesn’t work. Also, the content is all under the General section. The next section fixes both problems.

  1. Next Steps
    You should now understand how adding a decorator quickly makes a plugin look like an Atlassian plugin. You made your plugin ADG themed by adding specific AUI layout components that referenced AUI classes. Finally, you learned how to add a horizontal navigation bar to your plugin. In the next section, you make your UI interactive.

Next: [Add a form to your plugin](add-a-form-to-your-plugin)

Updated