UI 3.0 implementation

A primer about the 3.0 UI and how we go about doing it.

There are some bugs that must be fixed before main_side layouts can be landed:

[[https://launchpad.net/bugs/403641 | 403641 base-layout must support a Set menu]]

There may be three modification links that are global to an object.

[[https://launchpad.net/bugs/403651 | 403651 base-layout must support an Involvement menu]]

There is a static menu to encourage cross application use

We want to minimise the number of developers writing HTML and CSS until there are more HTML examples and CSS rules in place.

Layouts

locationless: A page without tabs, search, or side portlets ::

This is used by non-app pages like errors. Most (maybe all) pages that uses this layout have been converted.

searchless: A page without global search or side portlets ::

This is for pages that implement their own search in the main area. The Launchpad front page, uses this layout. Other pages may want to switch to this layout.

main_only: A page without side portlets ::

This will be the most common layout because modification pages and some listing pages do not have items that qualify for side portlets.

main_side: A page with everything ::

This page is for artefacts that have actions that create notifications, have subscribers, or have notifications that can be placed in the side

Estimate conversion table

Converting a template to a layout

* Choose the layout

• ? The page does not belong to an application, can be shown anywhere
  • ! use locationless.
  ? Does the page implement search in the main area, and does it contradict
  • with global search ! use searchless
  ? Does the page have actions that create objects or notifications, does
  • it have a subscriber's list, does it have notification (events) to show recent activity? ! use main_side
  ? All other cases (simple artefacts or modification pages)
  • ! use main_only

* Mechanical changes

• Switch the layout:
  • Update the macro
    • - xml:lang="en" - lang="en" - dir="ltr" - metal:use-macro="context/@@main_template/master" + metal:use-macro="view/macro:page/main_only"
  • Update the heading?

    • If this is the index of an object move <h1> to the heading slot.

      • The page layout is probable main_side. The rule could also be stated as the context.title above the bread crumbs should not also be repeated in maincontent.
• Remove 0.0 and 1.0-isms
  • Delete all portlet slots
  • Delete the help
    • You may want to extract the help to a separate file and link to it
• YUI-ify
  • If there is more than on block on the page:
    • First block is class="top-portlet"
    • All following blocks are class="portlet"
• Launchpadify
  • Convert crafted links into fmt:link or fmt:link-icon
    • We may want to extend the formatter to handle alternate link text.
    • We probably need to add links the menus.
  • Create valid css-ids using fmt:css-id
    • It takes an optional prefix fmt:css-id/prefix-

* Design changes

• Menus and links
  • Dismantle the context, app, and navigation menus.
    • Move the links inline.
      • Are the links really needed in the page?

    • Many pages will require a "related <nouns>" portlet at the bottom

      • of the page that has a list of links to other pages. Edit pages might link to other edit pages for example.
      • Create a navigation menu if the links are shared between views.
        • Use the related pages adapter to render the view's menu.

          <tal:menu replace="structure view/@@+related-pages" /> The disabled links and the current page are removed the from list.

  • Define the global Modification/Set links
    • Some links cannot be moved into the page because the act on the
      • entire object or on some unseen object. eg. Change password and Change Details. The menu should be very small.
• Side portlets
  • Build the side portlets that convey activity
    • Are there subscribers that need to be shown?
    • Are there items to download?
    • Are there events or notification to display?
• Main portlets
  • The 'first' problem:
    • The css requires that the div contain all three classes to describe a portlet, but 'first' is not reusable in this way. The portlet certainly knows it is class="yui-u portlet", but only the calling template knows if the portlet is 'first'. One solution is to ignore first and order the portlets last to first in the page. Another solution is to add a CSS rule that makes 'first' work as a parent tag.
  • If there is a lot of content, divide the main area into columns

    • Create a parent column <div class="yui-g">

    • Create first portlet <div class="yui-u first portlet">

    • Add all other portlets <div class="yui-u portlet">

  • Use the <div class="yui-u portlet"> structure to create the correct

    • margins and borders around the chunk of content.
    • Note that the new CSS makes better use of content. The portlet
      • presentation changes based on its location on the page.
• Common structures
  • Replace 0.0-2.0 html structures with 3.0 so that the layout is
    • consistent for all pages

    • Horizontal lines of links are now <ul class="horizontal">

      • to normalise spacing
    • Table and CSS that created content that was left-aligned to heading
      • are removed. The subordinate information appears below the heading

        now. They are may be replaced with <dl> that may have many <dd> per <dt>

• Ensure the CSS works because the classes are right, the css that works
  • on ids is being removed.

* Implementation changes

• Many pages are creating links that should be codified in a menu for the

  • app (ApplicationMenu), context (ContextMenu), or view (NavigationMenu)

• base-layout will use view/page_title before falling back pagetitles
  • to insert the page title into the HTML.
  • If the view is used by one template, the moving the title rule from
    • pagetitles to view/page_title is simple.
  • If several templates use the view you may be able to write a more
    • complex rule create the title
  • You can choose to not convert the page title, let the template
    • fall back to page titles.

* Test changes.

• Lots of pagetests/stories will break.
  • Does the test verifying page titles, heading, and links work between
    • pages?
    • Fix them.
  • Does the test check forms, or verify the primary content of the page?
    • Throw out the test, create a unittest or browser/doctest that
      • verifies the view's contracts and purpose.
  • Does the page verify the that an object's state was changed.
    • Throw out the test, create unittest or browser/doctest that
      • verifies the state.
  • Does the test verify an external script?
    • Throw out the test and create unittest or doctest that verifies
      • the script ran and states changed.

======= 3.0 CSS

Launchpad is using classes for styling, ids are used for testing and scripts. YUI is doing layout, Launchpad is decorating the layout, so many divs will have a yui and a launchpad class.

YUI (layout)

• yui-g: A grid column yui-u: A unit of content
  • Probably always paired with portlet Probably should have an id for testing and scripts
  first: The first item in the yui-g (fixes issues in css 2.x browsers)
  • (See the note above about problems with this class)

Launchpad (decoration)

• portlet: A chunk on content distinguished by margins, padding, and borders
  • Probably always paired with yui-u
  top-portlet: The first portlet in the page, probably a description.

There are may css classes we have not written yet because we have not discovered all the kinds of html structures we need to make the layout consistent.

============== Example layout

A common layout will be an intro on top of two columns of content. You can see examples of the four layouts in lib/lp/app/browser/tests/testfiles/

<html

• ..

  metal:use-macro="view/macro:page/main_only"> <body> <tal:heading metal:fill-slot="heading">

  • <h1>Zaphod Beeblebrox</h1>

  </tal:heading>

  <tal:main metal:fill-slot="main">

  • <div class="top-portlet">

    • Description

    </div>

    <div class="yui-g">

    • <div class="yui-u first portlet">

      • content

      </div> <div class="yui-u portlet">

      • more content

      </div> <div class="yui-u portlet">

      • and more content

      </div>

    </div>

  </tal:main>

  <tal:side metal:fill-slot="side">

  • <div id="actions" class="yui-u first portlet">

    • content

    </div> <div id="attachments" class="yui-u portlet">

    • more content

    </div> <div id=""subscribers class="yui-u portlet">

    • and more content

    </div>

  </tal:side> </body>

</html>

=========================== Infrastructure improvements

The MenuAPI needs performance fixing. Once we start rendering, link states should never be re-calculated. There should be no cost to using a menu in three templates to render a page.