universal theme

APEX 5.0 How-To: Dynamic Menus (Universal Theme)

January 20, 2016 by David 8 Comments

The basic WriteTrack menu. Does not change based on user data. A dynamic navigation menu, driven by user data. This past weekend, I implemented a significant change to WriteTrack, which drastically improves the navigation within the application. Specifically, I changed from a static navigation menu (which you can see on the left) to a dynamic one (on the right), which adjusts itself based on the active user’s data.

The old navigation system required a user to go to the main Calendar page and then select the correct challenge from a page item which was displayed on the right sidebar of the page if they wanted to change which challenge they were actively working on. This page item, due to screen real estate limitations, only displayed the name of the challenge; there was no indication of which challenges were upcoming, current, or past. And that’s assuming the user figured out that they needed to look on the opposite side of the page in the first place.

The new menu places all of the user’s challenges at the forefront, grouped intelligently into Current, Upcoming, and Past challenges; each group only shows up when there’s something there. (Friends’ challenges are also on the menu now, grouped by the friend’s user names.) So changing the active challenge is much easier and more intuitive.

This is fairly easy to implement, though it does take several steps.

Create a view which encapsulates the logic for the menu. Necessary columns are a number indicating the nesting level (1 for a top-level entry, 2 for a child, 3 for a second-level child, etc.); the label; the target URL; and a YES/NO flag indicating if the menu entry should be highlighted for the current page. You can also add a Font Awesome icon (which I did for the top-level entries) and attributes for the icon (which I didn’t bother with). I also found it very useful to include several sort columns, at least one per level, so I could ensure that the menu displayed properly.Here’s a snippet from my view:
```
select 1 lvl,
    'Current Challenge(s) ['||( select count(*)
                                from ...)||']' label,
    'f?p='||v('APP_ID')||':211:'||v('APP_SESSION') target,
    case
        when ':211:' like '%:'||v('APP_PAGE_ID')||':%'
        then 'YES' else 'NO'
    end as is_current,
    'fa-book' icon,
    10 orderby_1,
    ''  orderby_2,
    0  orderby_3,
    ''  orderby_4
from dual
where exists (  select null
                from ... )
union all
...
```
Note that I don’t call prepare_url on the target link; APEX handles that for me. Also, the is_current column could be written in a simpler form, but this style allows me to have more complicated logic if the entry is highlighted for multiple pages, for instance.
Next, create a dynamic list by going through the wizard from the APEX shared objects page. The query will look something like this:
```
select lvl,
    label,
    target,
    is_current,
    icon,
    '' image_attribute,
    '' image_alt_attribute
from wt_menu
order by orderby_1, orderby_2, orderby_3, orderby_4
```
You could skip the first step and build all of your logic into the list SQL directly, of course, but I find that these queries become very long (multiple UNION ALL statements, as well as nested queries), so the view helps keep things organized.
Finally, go to Shared Components > User Interface Attributes, and edit your default user interface. (You’re likely to only have one interface unless you’ve created a mobile one.) Under the Navigation Menu section, change the Navigation Menu List to the list you created in step 2, hit Apply Changes, and you’re done!

Oh, and incidentally, you may have noticed in my sample query that the label included a count subquery in brackets. There is a feature in the Universal Theme that will take a navigation menu entry like “Current Challenges [14]” and render the number in the bracket as a small box that floats to the right.

Label Cannot Be Rendered error in Universal Theme

May 27, 2015 by David 4 Comments

The Universal Theme, which was introduced in APEX 5.0, has some really nice features. One of the coolest is that it’s responsive–no matter what size window you’re using, the pages should look decent and be fully functional. (Side note: back when I was in college, many websites proudly bore banners declaring that they were designed to be viewed at specific resolutions; if you were using some other size window, they often didn’t look very good. I’ve never understand why anyone ever thought that was a good idea.)

The way this works is through what’s called the “grid” system, where (basically) the page is divided into twelve more-or-less equal columns. If the window is too narrow, some of the columns will automatically stack on top of each other. There’s a fair amount of behind-the-scenes magic, but the vast majority of the time, you won’t need to worry about it.

Of course, that phrase–“the vast majority of the time”–does mean that there will be some times where you do, in fact, need to worry about it. If you decide to have multiple items on the same row, you’re likely to run into an error that says something like:

Label of Page Item P1_TEXT_1 cannot be rendered as the label column span grid setting for this page item is invalid. It is set to be displayed with a Label Column Span of 3. This is not supported as the page item itself only has 3 Column(s)available.

Contact your application administrator.

Let me be honest: I don’t like this error, or this error message. I don’t think it’s very friendly or clear. There’s nothing in Page Designer or Component View to indicate that you have a problem, and the message doesn’t really tell you what the problem is–or how to fix it.

Remember how I said that the Universal Theme uses a twelve column grid? That’s what causes this error. Every page item uses a certain number of columns for its label and for the item itself; by default, the Universal Theme uses three columns for the label, and one for the item. So if you have three items in a row, you’re fine (the labels use a total of nine columns, and the items another three, for a total of 12), but if you try to put a fourth item on the row, you get the error. (Side note: Hidden labels still take up columns, which helps ensure that items line up properly.)

Once you run into the error, there are several ways to fix it:

The easiest, of course, is to just not put so many items on the same row, but sometimes that’s just not an option.
You can put the item labels above their respective items by using the Optional – Above or Required – Above label templates; this gets rid of the three columns reserved for the label. Alternatively, you may be able to set your region’s template options to have the Label Position as Show Form Labels Above; this will, of course, affect all items in the region, but if that works for you, it’s easier than editing each item individually.
You can also manually adjust how many columns the label and/or item uses by adjusting the Label Column Span and Column Span attributes (respectively); these are in the Grid section of the Page Designer.
It’s also possible to change the number of columns used by default by changing the page template, but this won’t work if you’re using the Universal Theme subscribed to the Theme Repository, which I recommend (since you’ll automatically get any fixes we release in new versions of APEX). And, of course, this would impact all of the page items throughout your application, and is likely to cause issues on pages you’re not intending to change.

Depending on your situation, I’d suggest that the second or third options are likely to be best.

Upgrading Applications to the Universal Theme

March 30, 2015 by David 7 Comments

I’m going to take a short break from the Hidden Gems series (more gems coming, I promise!) to talk about the process of converting applications to the new Universal Theme (I’ll call it UT for convenience) in APEX 5.0, because there are several items to watch out for in the process.

Naturally, the first question is, do I need to make the change? The short answer, of course, is no; all old applications should continue to work in APEX 5.0, regardless of the theme. The longer answer, though, is that you probably should, even if you’re using a custom theme–the HTML generated by the UT is designed to be responsive, so it’ll work on pretty much any device, as well as to be accessible, so people with screen readers & such shouldn’t have many issues with your site. And it looks more flat/modern, though whether the style is what you want is up to you. (Luckily, you can change things pretty easily–and drastically!–with the theme roller, so you’re no longer stuck with what the APEX team provides.)

Next, you need to create the UT in your application. Go to Shared Components/Themes, and hit the Create button. Just go through the wizard–the default options should lead you straight to the UT.

Once you’re back at the Theme page, it’s time to hit the Switch Theme button. This is where things get complicated, and the amount of manual work you need to do afterwards is largely dependent on getting this step right.

Getting this right will make your life much easier.

The first field is the “Currently Active Theme”; just select your current desktop theme. Then select the UT as the “Switch to Theme”. If you’re currently using theme 25 (or a custom theme based on it), you can leave the “Reset Grid” field alone; if you’re using any other theme, though, you’ll want to change that to “Reset fixed region positions” at least, or you’ll run into errors when you run the page complaining about trying to put multiple regions in column one. That’s a very frustrating error, since you won’t see it until you actually run the page. The final option, “Match Template Classes”, should be set to No. Really–pay attention to this one, or you’re going to be really frustrated with the next step! If you have it set to Yes, then APEX will try to only offer you templates that are from the same “class” as your existing ones. However, the classes used for different region types are likely to be changed.

The second page of the wizard, titled “Verify Compatibility”, is where the bulk of the work happens. You need to go through all of the templates used in your application and make sure they’re using appropriate templates. If you don’t see many options in some of the “To Template” drop-downs–if, for instance, the Standard Region only allows you to select the Interactive Report template–then you need to go back to the previous page and change the “Match Template Classes” option to No. Take your time on this page; it’s a lot easier to get things right here than it is to clean them up later. Trust me.

The third page of the wizard is the confirmation page, which is your last chance to bail out. Go ahead and hit the Switch Theme button.

From this point, it’s simply a matter of running your application and fixing all of the areas where something doesn’t look quite right. But if you got the template mappings correct, you should have a much easier time of it!