The chrome is that part of the browser window that lies outside the browsers's content area. It encompasses the toolbars, Aurora tree views launched from toolbars, and embedded menus (for those platforms that support them). This spec will not cover configurable menus.

This document is divided into several sections, and is all work in process. The first section outlines those aspects of the chrome that are configurable and provides a comprehensive listing of the properties that each front end should respond to. The second section covers policies for user-level modification of the chrome. The third section deals with downloadable chrome and the problems that must be dealt with in order to make such a scheme work in practice. The last section describes some of our current thinking about the default appearance of the chrome, i.e., what the toolbars and tree views will look like when the user first runs Netscape 5.0. We are running usability studies so this is likely to change.

1. Configurable Properties

The entire chrome structure is hierarchically organized into nodes that are managed by RDF and HT. There is a top-level chrome node whose children represent the two toolbars. Their children in turn represent the buttons and objects found on the toolbars. Tree views and toolbars therefore are all nothing more than collections of leaf nodes (commands/URLS) and container nodes (which contain hierarchies of commands/containers/URLS). By associating certain properties with specific nodes, we can define both appearance and behavior for elements of the chrome such as toolbars, buttons, and tree views. Depending on how a nodal hierarchy is being displayed (e.g., as a toolbar, single button, or tree), different properties of the root node of that hierarchy will be used to determine the appearance and behavior of objects in the view.

All nodes have two basic properties that should always be specified:
name - The node's name (e.g., Navigation Toolbar, Info Toolbar, Bookmarks, History, etc.). This is a localizable property.
href/id - The URL or id for the node. This property is not localizable.

Custom Icon Properties

Any node that will potentially be displayed in a tree, toolbar, or menu can have a custom icon associated with it. A custom icon can be an arbitrary gif/jpeg, and it can be animated. There are five different icon properties that can be specified. Icon properties are NOT localizable.
smallIcon - The icon that should normally be used for the node when displayed in trees and menus.
toolbarEnabledIcon - The icon that should be used by default for an item in a toolbar view.
toolbarRolloverIcon - The icon that should be used when the user mouses over the item in a toolbar view.
toolbarPressedIcon - The icon that should be used when the user clicks on the item in a toolbar view.
toolbarDisabledIcon - The icon to use when the command is inaccessible.

If only the toolbarEnabledIcon property is specified for a node, then Navigator should be prepared to apply the appropriate transformations to that icon if no other custom icons are specified. For example, if a custom icon is specified only for the normal state of the Back button on the Navigation Toolbar, then Navigator should grey out that icon if the Back command becomes disabled. It is permissible to assume, if the smallIcon property is not specified, that the node in question does not have a custom icon at all.

View Properties

A view can be either a toolbar or tree view. The following properties should be responded to by all views. For any of these properties, a special value, System Default, can be specified. This special value indicates to the rendering platform that the OS-specific default value should be used.

Property Name	Default Value if HT_GetTemplateData fails	Localizable?
viewBGURL - The URL that points to a "skin" that is tiled onto the view background. Whenever two contiguous toolbars or contiguous elements in the tree area (title bar, column headers, tree) share the same background URL, the background should flow smoothly between them. The tiling should occur over the entire area shared by the contiguous elements.	NULL	No
viewBGColor - The background color that should be used in the view. Should be shown if the background fails to load or if a background is not present. Should also be used as the basis for computation of appropriate highlight and shadow colors for any 3D effects (e.g., separators) that will be drawn in the view.	Platform-specific chrome color	No
viewFGColor - The foreground color that should be used in the view.	Platform-specific text color	No
viewRolloverColor - The foreground color used when an item is moused over in the view.	Platform-specific text color	No
viewPressedColor - The foreground color used when an item is pressed in the view.	Platform-specific text color	No
viewDisabledColor - The foreground color used when an item is disabled in the view.	Platform-specific text color	No
htmlURL - If the view wishes to display an HTML area, then this property indicates what URL should initially be displayed.	NULL	No
htmlHeight - Indicates the size of the HTML pane that appears in the view. Can be specified as pixels, as a percentage, or as . If this value is nonzero (or ), then the view should display the HTML area and load the URL present in htmlURL initially.	0	No

Tree Properties

The following properties apply only to a view that is displayed as a tree.

Property Name	DefaultValue if HT_GetTemplateData fails	Localizable?
titleBarFGColor, titleBarBGColor, titleBarBGURL - Colors and images to use for the title bar above the tree view.	Platform-specific colors	No
showTitleBar - Whether or not to show the title bar at all.	No	No
titleBarShowText - Whether or not to display any text in the title bar. If this property is set to "No", then the background URL could be used to supply a slick branding logo in place of the text.	Yes	No
controlStripFGColor, controlStripBGColor, controlStripBGURL - Colors and images to use for the control strip between the title bar and the tree view.	Platform-specific colors	No
showControlStrip - Whether or not to show the control strip at all.	No.	No.
controlStripAddText, controlStripEditText, controlStripCloseText - Text strings that represent what to display on the control strip. If omitted, no UI widget should be present for the item.	Add Page, Manage, and Close	Yes
selectionFGColor, selectionBGColor - The colors to use for selected items in the tree view.	Platform-specific colors	No
columnHeaderFGColor, columnHeaderBGColor, columnHeaderBGURL - Colors and images to use for the column headers below the title bar and above the tree view. The foreground color should be used to draw the horizontal lines above and below the columns, the text in the columns, the arrows that appear on the columns, and the dividers between the columns.	Platform-specific colors	No
showTreeConnections - Whether or not to display the triggers and the vertical bars/lines between sibling nodes. Has a value of "Yes" or "No". (Case-insensitive.)	Platform-specific choice	No
treeConnectionColor - The colors to use for tree connections.	Platform-specific color	No
showDividers - Whether or not to display the horizontal divider lines between nodes. Has a value of "Yes" or "No".	Platform-specific choice	No
dividerColor - The color to use for the horizontal divider lines.	Platform-specific color	No
selectedColumnHeaderFGColor, selectedColumnHeaderBGColor - The colors to use for the column header that is in an ascending or descending sort state.	Platform-specific color	No
sortColumnFGColor, sortColumnBGColor - The colors to use for the column in the tree view itself when a sort is imposed on that column.	Platform-specific color	No
showColumnHeaders - Whether or not the column headers should be displayed. Has a value of "Yes" or "No". If the column headers are omitted, then the title bar and the tree view should join smoothly, i.e., there should be no dividing line between them.	Yes	No
useSingleClick - Whether or not the view should use a single click or double click model. Has a value of "Yes" or "No". If the view uses a single click model, then this should apply to all elements in the tree view regardless of type.	No	No
useInlineEditing - Whether or not the tree view should allow inline editing of nodes. Has a value of "Yes" or "No". This attribute usually has a value of "No" if useSingleSlick is enabled.	Yes	No
loadOpenState - Whether or not the tree view should auto-open those folders that were saved as such. Has a value of "Yes" or "No".	Yes	No
saveOpenState - Whether or not the tree view should save its open state when it is destroyed.	Yes	No

Toolbar Properties

The following properties apply only to a view that is displayed as a toolbar. Again, the value System Default can be specified. If it is, then the platform should use a default that is appropriate for the OS.

Property Name Default value if HT_GetTemplateData fails Localizable?

toolbarBitmapPosition - Can be either "side" or "top". Where to display the bitmap relative to the text on the buttons in the toolbar. (This property is "top" for the command toolbar and "side" for the personal toolbar.) If omitted, the bitmaps should be placed on the side. Side No

toolbarButtonsFixedSize - Can be either "yes" or "no". If yes, then the buttons on the toolbar are the same size as the largest button on the toolbar. (This property is set for the command toolbar in the browser.) Note that URL bars and separators are not affected by this restriction. If omitted, the buttons should size dynamically. No No

toolbarMinChars, toolbarMaxChars - If the buttons are allowed to size dynamically, and if button text is the constraining factor, then the button text should be clipped with ellipses so that it falls into the range specified by these attributes. The defaults if omitted are 15/30 for dynamic toolbars and 15/15 for fixed size toolbars. The toolbar layout manager is allowed to shrink and grow the buttons as needed to fit them on the toolbar, as long as it obeys these constraints. 15/15 for fixed size buttons, 15/30 otherwise. No

toolbarDisplayMode - How to display the toolbar. Has three values: "text", "pictures", and "picturesAndText". Buttons can use this property to override the property given for the toolbar. PicturesAndText No

toolbarCollapsed - Whether or not the toolbar is collapsed. Has a value of "Yes" or "No". No No

toolbarVisible - Whether or not the toolbar is visible. Has a value of "Yes" or "No". Yes No

Note: The "grippy" on the far left of the toolbars is not customizable. It should, in the normal state, blend in with the viewBGColor.

Toolbar Button Properties

The following properties apply to buttons on a toolbar.

Property Name	Default value if HT_GetTemplateData fails	Localizable?
buttonTooltipText - The tooltip text that should be used for the button	Use the name property	Yes
buttonStatusbarText - The status bar text that should be used for the button. Defaults to the node's URL for non-containers and to the node's title for containers.	Use the name property for containers. Use the URL for all other nodal types.	Yes
buttonBorderStyle - The type of border that should be used with this button. Has three values: "None", "Solid", and "Beveled".	Beveled	No
buttonTreeState - Whether or not a popup launched from this button comes up in a "docked", "popup", or "menu" state.	Popup	No

Note: The back and forward timed menus must be hacked in by each FE. There is no time in the schedule to craft a general solution for dynamically constructed context-sensitive menus.

URLBar Properties

The following properties apply only to a URL bar on a toolbar:
urlbar - If set to "Yes", then the toolbar item is assumed to be a URL bar. This property is not localizable. It defaults to "No".
width - The width of the URL bar. Can be specified as pixels, a percentage, or with a * (indicating that the URL bar should expand to fill as much space on its current row as it can). If omitted, a value of 100 pixels is used. This property is not localizable.

Animation Properties

The animation is a special node that describes the look of the animation. Since the animation can appear as one of two sizes, four different images are required to describe it. The animation also makes use of the buttonTooltipText and buttonStatusbarText properties to describe its tooltip and status information. The animation node's href property is used to determine where the user goes when the animation is clicked.

Properties unique to the animation are:
largeStaticIconURL, smallStaticIconURL - The icons to use when the animation is at rest. Not localizable. Defaults to internal bitmaps.
largeAnimatedIconURL, smallAnimatedIconURL - URLs that point to animated GIFs that should be used when animating. Not localizable. Defaults to internal bitmaps.

Separator Properties

A node can be specified as a separator by using "separator" as the ID of the node. Separators show up everywhere, in the trees, toolbars, and menus. A separator is rendered using highlight and shadow colors that are computed dynamically by using the viewBGColor property for the view in which it is found.

Internal Commands

Internal commands on toolbars and in menus are represented with a special internal URL that should only be obeyed when invoked from the toolbars or menus within an appropriate view (one that knows how to respond to the commands). Examples of these special URLs are "command:back", "command:forward", etc. etc.

Each front end should maintain a map from backend URLs to frontend resources and should handle the enabling/disabling of the items themselves.

Templates

There are several special nodes used to describe the default appearance for tree views and toolbars. Specifically one node is used for the toolbar and popup tree defaults, and another is used for the standalone tree defaults. These nodes have properties as if they were the root nodes of a view, and the HT layer will look for these defaults when HT_GetTemplateData is called before failing.

The basic rule is that if a node specifies the property then that property should always be used. If the node omits a property, then HT should look for a template for that view. If the property is defined in the template, then it should be used. If no property is specified, then the front end must use the appropriate default values

Note that the FE never needs to think about these templates.

2. User Modification of the Chrome

Editing Properties - Without exception, every single property specified in section 2 can be edited by the user. Properties specific to a given node can always be editing by selecting Properties on the item from the context menu and then editing the values in the HTML dialogs that are displayed. The Undo system should be able to reverse any changes that were made in a single session with a properties dialog.

Drag & Drop - Drag and drop can be used to reorder buttons on the toolbar or to place new buttons on the toolbar. The user can create or remove entire toolbars and/or reorder/set the properties for specific nodes within the chrome.

Policies for Fixing Mistakes - Nodes can be deleted from toolbars or properties of nodes can be changed that render the view unusable. It is important therefore to provide the user with a way to recover if he/she makes a mistake. The first line of defense for deletion is to bring up a dialog that double-checks the deletion request. No item should be deleted without first prompting the user. Next, all changes should be reversible using the Undo system. Finally, there is a blanket reset option for the toolbars that returns them to the state specified in the user's original remote RDF file.

3. Downloadable Chrome

What is downloadable chrome? - The user's default chrome appearance and behavior are specified using a remote RDF file that resides on a trusted Internet site. This trusted site is known as the chrome provider. Since the chrome provider dynamically serves up the chrome, changes can be made to the appearance, layout, and even functionality of Navigator, without any change being required in the executable itself. By default, NetCenter is the trusted chrome provider.

The Chrome Cache - The entire chrome description is contained in a single RDF file that by default resides on NetCenter. This file specifies the initial appearance of the chrome, appearance/behavior defaults for views, and smart browsing services. This RDF file, as well as any custom icons that will appear in the chrome, are all contained in a special cache. The only items that can reside in this cache are RDF files required for proper chrome display and all RDF custom icons.

The chrome cache directory is called "Chrome", and it resides within the user's profile directory. This ensures that users who manually delete all files in their "Cache" directory don't end up deleting their chrome files.

The Navigator installer should place copies of the images and the RDF file for the default chrome appearance into the chrome cache during installation.

When the user runs 5.0, the cached copy is ALWAYS used to initially display the chrome. Cached icons are also used. This ensures that the chrome is always immediately available and displayable, and it also ensures that no connection is opened if the user is offline. The Chrome Cache should never initiate a network connection to retrieve a file that is already in the cache. It should only initiate a connection if the file is not found in the cache, and if the user is not in offline mode. It should, of course, cache any items that it is forced to retrieve.

The specifics of the cache behavior are outlined below:

The chrome cache has its own module in the cache architecture with its own garbage collection scheme, and it has its own directory, which is separate from the normal cache directory.
The server can specify an expiration date (using a standard HTTP header response) on the RDF file that goes into the cache. The server is guaranteed that the client will not contact it again until that time has elapsed.
When RDF initializes during client startup, it will always go ahead and use the cached RDF file. If no cached file is found (because something horrible happened, e.g., the user manually deleted his RDF file from his chrome cache), then either a hardcoded chrome set will be used (user is in offline mode) or the file will be fetched from the chrome provider (user is online).
After serving up the cached RDF file, the client will check the expiration date time against the current time to determine if it needs to refetch the RDF file.
If the server does need to be contacted, then the client will still use the cached copy to lay out the chrome and then in the background it will update its cached copy, resetting the expiration date.
The front end fetch of custom icons works the exact same way as the back end's fetch of the RDF file. Front ends serve up from the cache and then if the file has expired go off and refetch it.

The Chrome Cache's size is 1 megabyte initially and this size should be editable by the user. The Chrome Cache should consider the RDF files required for the chrome and custom icons that will show up in the toolbars to be of the highest priority, and it should flush all other files before getting rid of these.

Chrome Provider Changes to the Chrome - If the RDF file from a given chrome provider changes, then the chrome is simply updated behind the scenes. The changes are picked up the next time the user runs Navigator after refetching the RDF file. There is a boolean pref called browser.ChromeProvider.AcceptChrome that determines whether or not the user sees changes to the chrome.

Whenever the user rejects a chrome provider's change, the user's current chrome RDF file is cloned into a new RDF file, called navbackup.rdf, which sits in the user's NavCen subdirectory, and this new file is used as the default instead of the chrome provider's file. Although the RDF layer uses this new file to lay out the chrome, it should continue to check for updates with the chrome provider and to refetch the RDF file from NetCenter to ensure that it has an up-to-date copy on the user's machine.

Note that once the user gets into the state where he has "locked out" changes from the chrome provider, he has the option of saying "Accept Now!" to bring his chrome back into sync with the chrome provider's specification. When this happens, the cloned chrome RDF file is discarded, and the user once more depends solely on the chrome provider's RDF file.

Chrome Providers - The chrome provider can be changed through a preference. This pref is not visible anywhere in the UI. Signed JavaScript will be used by sites who offer to become the new chrome provider for users. Whenever a user is about to accept a new "theme", the browser should use JavaScript to open a new window which displays the chrome for the user to preview. (This step is optional, but it helps the user to decide if the chrome is right for him/her.) Once the user accepts the new chrome, Navigator updates dynamically.

If the user doesn't like the new chrome, then he/she should have the option of hitting Undo to revert back to the old chrome.

Note also that on a per-window basis (using JavaScript) different chrome providers can be specified for various windows. This allows for the creation of Web-based apps with dynamic toolbars and popup tree views specified by the apps themselves. The site can leverage Navigator's toolbar/tree widgetry.

4. The Default Chrome Appearance

This spec is likely to change, since we are still doing usability testing to help determine the ideal default appearance.

Toolbars

The primary goal for the 5.0 toolbars is to simplify simplify simplify. In 5.0, we will actually reduce the amount of chrome consumed by the toolbars in the browser and provide a clearer distinction between the purposes of the toolbars. There are only two toolbars in the 5.0 chrome by default.

Navigation Toolbar - This toolbar contains elements related to the user's navigation history, including both the current page and any pages the user might have been to in the past. Any element that is not dependent on the current page or on navigation history should NOT be placed on this toolbar. In 5.0, this toolbar will contain a back button, a reload/stop button, a forward button, a location bar, and a smart browsing button (name to be determined). The back, forward, and reload buttons are borderless and do not have text associated with them. The location bar sits in the middle of the toolbar and always expands to consume all remaining space on the toolbar.

Info Toolbar - The info toolbar contains collections of hierarchical links that expose different forms of organized information to the user. The info toolbar by default contains a bookmarks button, a history button, a files button, the My Netscape button, and copies of the contents of the user's 4.x personal toolbar (to avoid an infinite recursion in bookmarks). This toolbar can wrap to multiple rows.

Note that in nearly all cases, a user will see a reduction in the space occupied by the toolbars when upgrading from 4.x to 5.0. The first time the user runs 5.0, both toolbars will be displayed (4.x toolbar prefs will be ignored, as none of them really have any meaning any more).

Tree views in the 5.0 product exist in one of four states: popup, docked, standalone, and embedded.

Popup - Tree view appears directly underneath a folder button that has been clicked on.
Docked - Tree view is embedded on the left side of the browser window.
Standalone - Tree view appears in its own window.
Embedded - Tree view appears inside an HTML page.

A tree view can always be docked or standalone, regardless of its initial state. (The obvious exception to this rule is the embedded tree, which cannot be removed from the HTML page.)

Folder Buttons and the Smart Browsing Button - Both the smart browsing button and the folder button on the info toolbar display trees of information when they are pressed. The smart browsing button brings up a docked tree by default. The folder buttons on the Info Toolbar bring up popup trees by default.

Popup trees should appear directly underneath the buttons they are associated with, and they should be destroyed when they lose focus (unless they have been docked or undocked by the user).

All buttons that bring up trees (whether docked or popup) should do so on a mouse up. They should be drawn in a pressed state as long as the tree is either popped up or docked. If the tree is either undocked or destroyed, the button should return to its normal state. If the button is clicked again while in the pressed state, then the tree should disappear and the button should return to its normal state.

It is permissible to have a docked view and a popup view up simultaneously. This means that up to two buttons on the toolbars can appear in a depressed state at any given point in time.

Smart Browsing Defaults - When 5.0 is launched for the first time, the smart browsing button should be depressed and the docked smart browsing tree should be displayed.