Wednesday, April 22, 2015

Migrating from the Navbar Plug-in to the builtin Navigation Menu

While working at Enkitec I built a plug-in called Navbar which was really a port of Bootstrap's Navbar component. The plug-in was really successful in the APEX community because it provided nested tabs for primary navigation, was list based and thus easier to use than tabs, and it looked pretty good!

APEX 5.0 makes this plug-in, as well as tabs for that matter, obsolete. That's right, I said it, tabs are obsolete! Take a moment to do your happy dance and continue reading when you're ready... :D


You don't have to stop using the Navbar plug-in or tabs, they should continue working just fine, but it's very likely you'll want to migrate you application(s) at some point to theme 42 and when you do you should probably move to the builtin Navigation Menu.

The Navigation Menu is a beautiful work of art that blends seamlessly with theme 42. It can be displayed either on the left hand side (the default) which is becoming the norm in web apps or along the top which would mimic the tabs of old. In the following tutorial, I'll walk you through the steps involved with converting an application using and old theme and the Navbar plug-in to the theme 42 with the Navigation Menu.

Here's our starting application just before exporting and importing into an APEX 5.0 instance. It's still using an old(er) theme and the Navbar plug-in:
Here's a link to the demo application if you'd like to import it into an APEX 5.0 instance and follow along.

Add theme 42 to app

Your application will not have theme 42 installed by default. Follow these steps to add theme 42 to your application from the theme repository. You'll be leaving all the default options so this is pretty simple. Navigate to the Shared Components > Themes page and complete the following steps:
  1. Click Create >.
  2. Click Next >.
  3. Click Next >.
  4. Click Next >.
  5. Click Create.

Switch to theme 42

Adding a theme to an application doesn't mean your using it. Let's switch from our current theme to theme 42. This is something that is pretty trivial in my application but it will not be as simple in a real application that has many pages, regions, and other components which results in lots of templates and template classes being used. You may wish to back up your application before completing this step so you can start over if you like. If not already there, navigate back to the Shared Components > Themes page and complete the following steps:
  1. Click Switch Theme.
  2. Set Currently Active Theme to the theme you're currently using.
  3. Set Switch to Theme to 42. Universal Theme.
  4. Click Next >.
  5. Do your best to select templates in the To Template column based on the From Template column. If you don't see a good option make a note of it as you'll need to review and potentially fix later (not covered in this tutorial). I just left all the defaults.
  6. Click Next >.
  7. Click Switch Theme.

Sweet, check out our fancy new application with the navbar hovering in an awkward part of the page!


Removing the old Navbar

It's okay that the navbar isn't working right in the application at this point as we're just going to get rid of it. Navigate to the Page Designer for page 0, the global page in this application, and follow these steps to do just that:
  1. Right-click on the Navbar region and click on Delete.
  2. Click Save (upper right-hand corner).

At this point, unless you've used the plug-in more than once in the application, you should be able to delete the plug-in (not cover that in this tutorial).

Use your old list to drive the Navigation Menu

Our application currently has a Navigation Menu that is being driven off a list that was created when we switched to theme 42. That list was created based on the tabs that were in our application - even though we weren't actually using them. Of course we were already using a different list to power the navbar so let's update the Navigation Menu to use that instead. Navigate to the Shared Components > User Interface Attributes and complete the following steps:
  1. Click the "edit" button (paper & pencil) for the Desktop user interface.
  2. In the Navigation Menu region, set Navigation Menu List to Navigation List.
  3. Click Apply Changes.
At this point we have swapped the lists. Now when you run the application you'll see the following:

As you can see, the menu is still on the left rather than the top as it was with the navbar. No worries, we'll change that shortly! I just wanted you to know that this is an option and a good one at that.

Display the Navigation Menu on the top

If you prefer the look of "tabs" fear not, it's a very easy switch. If not already there, return to the Shared Components > User Interface Attributes and do the following:

  1. Click the "edit" button (paper & pencil) for the Desktop user interface.
  2. In the Navigation Menu region, set Position to Top.
  3. Set List Template to Top Navigation Menu.
  4. Click Apply Changes.
That's it! We now have one snazzy looking application!