VersionThreeDotO/UI/Conversion

Not logged in - Log In / Register

Revision 19 as of 2009-08-12 17:16:41

Clear message

UI 3.0 implementation

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

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

Layouts

Estimate conversion table

    Old layout                        New layout
  5 default(2.0)                      main_side
 30 applicationhome                   main_only
 10 pillarindex                       main_side
  1 search                            searchless
256 context/@@main_template/master    main_??
158 onecolumn                         main_??

See the Conversion report for a summary of our progress.

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 probably 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 they 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 YUI CSS requires that the div that contains 'first' also contain the
          'yui-u' class. The portlet template can define its div and set the 'portlet'
          class. The calling template will set the yui classes. Something like this:
            <div class="first yui-u"
              tal:content="structure context/@@+portlet-top-contributors" />
        * 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">
          * Note the 'first' problem above, if you separate the portlet to another file,
            keep the YUI classes in the calling template: <div class="yui-u first">
         * Use the <div class="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.
      * (Note: AFAICS, it's using context.title with no fallback, so currently
        I'm explicitly setting the heading slot - noodles 20090806)
        Wrong. The heading slot in the main page, not the HTML <title>.
        Look around line 28.  
      * pagetitles.py is deprecated. Do not add to it. Do no one use
        CONTEXTS/fmt:pagetitle
      * 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, The YUI layout rules are not portable between templates, do not use the in the same element that uses a launchapd class. Do not use YUI in the portlet templates because the instruction may break another page that also uses the portlet

YUI (layout)::

yui-g: A row
yui-u: A column
first: The first column

You can image the yui-g as a table row, and the yui-u as a table column. This creates the holes as you said above, and this behaves just link designing pages with tables. This is called YUI-Grid afterall. It assumes all content is essential. It's uses of the 'first' class makes portlet reusablity difficult without careful template creation.

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.

/!\ Mixing YUI classes on elements that use launchpad classes may lead to broken layouts when templates are refactored.

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 layouts

A common layout will be an intro on top of two columns of content below it in the main slot . This layout is the easiest to do. The portlets will not align so it may look ugly.

<html
  ...
  metal:use-macro="view/macro:page/main_side">
  <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="first yui-u">
       # Call the essential portlets.
       # Call the optional portlets. 
      </div>
      <div class="yui-u">
       # Call the essential portlets.
       # Call the optional portlets.
      </div>
    </div>
  </tal:main>

  <tal:side metal:fill-slot="side">
    <div id="actions" class="first portlet">
      content
    </div>
    <div id="attachments" class="portlet">
      more content
    </div>
    <div class="portlet"
       tal:content="structure context/@@+latest-announcements" />
  </tal:side>
  </body>

The more complex approach is to create a row (yui-g) for each pair of essential content so that some of the page aligns and looks nice. In the last row (yui-g), call all the optional portlets. The pushed the only part of the layout below the fold. You can also interleave single column portlets between the yui-g rows to improve the layout.

  <tal:main metal:fill-slot="main">
    <div class="top-portlet">
      Description
    </div>

    <div class="yui-g">
      <div class="first yui-u">
       # Call the essential portlet.
      </div>
      <div class="yui-u">
       # Call the essential portlet.
      </div>
    </div>

    <div class="yui-g">
      <div class="first yui-u">
       # Call the essential portlet.
      </div>
      <div class="yui-u">
       # Call the essential portlet.
      </div>
    </div>

    <div>
      # an essential or optional portlet that is one column
    </div>

    <div class="yui-g">
      <div class="first yui-u">
       # Call the optional portlets. 
      </div>
      <div class="yui-u">
       # Call the optional portlets.
      </div>
    </div>
  </tal:main>

Adding a NavigationMenu

Launchpad uses NavigationMenus to associate outbound links to a view. The menu and view are bound together by a marker interface. Links that are used in more than one menu should be defined in a mixin class to ensure that there is a single canonical definition of them.

The menu can be rendered as an action menu in the side portlets or as a list of related pages in the main content.

Working with more than one menu

There is a lot or duplicate definitions of links. Some even have different text, summaries, or icons. There should be only one definition on a link. If a link is used in more than one menu, move it to a mixin.

Do not try to subclass an ApplicationMenu to a NavigationMenu to reuse a link. Bad things will happen. Use a mixin.

A browser module example

   1 from zope.interface import implements, Interface
   2 
   3 from canonical.launchpad.webapp.menu import NavigationMenu
   4 from canonical.launchpad.webapp.publisher import LaunchpadView
   5 
   6 from lp.myapp.interfaces.myobject import IObject
   7 
   8 
   9 class ObjectLinksMixin:
  10     """A mixin class that provides links used by more than one menu."""
  11 
  12 
  13 # Classes to create menus on more than one view
  14 class IObjectEditMenu(Interface):
  15     """A marker interface for the edit navigation menu."""
  16 
  17 
  18 class ObjectEditMenu(NavigationMenu, ObjectLinksMixin):
  19     """A menu for different aspects of editing a object."""
  20     # Bind the menu to the view.
  21     usedfor = IObjectEditMenu
  22     facet = 'overview'
  23     title = 'Change object'
  24     links = ['edit', 'images', 'reassign', 'review', 'administer']
  25 
  26 
  27 class ObjectEditView(LaunchpadView):
  28     """A view to set branding."""
  29     # Bind the menu to the view.
  30     implements(IObjectEditMenu)
  31 
  32 
  33 class ObjectImagesView(LaunchpadView):
  34     """A view to set images."""
  35     # Bind the menu to the view.
  36     implements(IObjectEditMenu)
  37 
  38 
  39 # Class to create a menu for the object, irrespective of the view.
  40 class ObjectActionMenu(NavigationMenu, ObjectLinksMixin):
  41     """An action menu to modify the object."""
  42 
  43     usedfor = IObject
  44     facet = 'overview'
  45     title = 'Action object'
  46     links = ['review', 'administer']
  47 
  48 
  49 # Menus are normally registered using the menu ZCML directive. They can
  50 # be registered in Python. To register them: 
  51 provideAdapter(
  52     ObjectEditMenu, [IObjectEditMenu], INavigationMenu, name="overview")
  53 provideAdapter(
  54     ObjectActionMenu, [IObject], INavigationMenu, name="overview")

A ZCML example to register a menu

    <browser:menus
        classes="
            ObjectEditMenu
            ObjectActionMenu"
        module="lp.myapp.browser.myobject"/>

Rendering a NavigationMenu

To render an action menu use this TALES view:

To render a related pages:

Two menus on the same page

There maybe a few cases where a page may need two menus. One for actions that change an object that are not possible to move into the main content, the other for pages related to the content of the page. NavigationMenus can be created for content objects and views.

Do not do this without first talking to Martin about the reason. The exmaples that have been given so far have not been legitimate.

Infrastructure improvements

[X] The MenuAPI now caches menus per request. They are faster and there is no danger of a link changing during rendering. [ ] We need a unittest that can verify that every menu makes links to an adaptable view.