GUIDES Creating A New Uize Example Page
- 1. Introduction
- 2. What Type of Example Page Are You Creating?
- 3. Implement the Example Page
- 4. Location and Filename
- 5. Example Page Requirements
- 5.1. Title
- 5.2. Meta Description
- 5.3. Meta Keywords
- 5.4. Main Layout
- 5.5. Maximum Dimensions
- 5.6. Comments
- 5.7. Conform to the HTML Style Guide
- 6. What's Done for You Automatically
- 7. Announce a New Example Page or Tool
- 8. Revisit This Guide, As Needed
2. What Type of Example Page Are You Creating?
3. Implement the Example Page
When implementing your new UIZE example page, there are a number of considerations to keep in mind.
Find an appropriate existing example page or tool to use as a starting point / skeleton for your new example page or tool.
4. Location and Filename
Example pages are all located at the root level of the "examples" folder - examples are not organized into subfolders.
The filename for an example page should be derived from the title of the page, according to the following scheme...
|use the first portion up to the first " | " separator|
|lowercase all the characters|
|replace all occurrences of one or more non-word characters with a "-" (hyphen) character|
|append the |
EXAMPLE PAGE TITLE
EXAMPLE PAGE FILENAME
As you can see from the above example, we have taken the "Hover Fader Text Shadow Animation" text from the example page's title, then we have lowercased all the letters, replaced non-word characters (only spaces in this case) with hyphens, and then appended the
.html file extension. The result is the filename
There are some exceptions to this rule, but most of these exceptions are legacy - going forward, all filenames for example pages should be derived from their title.
Example pages that are still under development and that are not yet ready for primetime release can be distinguished from released example pages by adding a "~" (tilde) character as a prefix.
For one thing, the tilde prefix makes all the example pages still under development clump together in a sort of the
examples folder's contents. This is useful in easily seeing which examples are still works in progress. More importantly, however, the tilde prefix is observed by any build scripts that iterate through the contents of the
examples folder to create example index pages, example source pages, and the like.
5. Example Page Requirements
The text of the
title tag of an example page or tool should conform to the following format...
EXAMPLE TITLE FORMAT
A value for the
[example name] token should conform to the following rules...
|should be in title case|
|should, ideally, be no more than 64 characters long|
|should not contain the "|" (pipe) character|
|may contain non-word characters (except "|")|
|should include words that capture / express essential aspects of the example|
In the above example, our example title has the text "Hover Fader Text Shadow Animation" for the
[example name] token.
Put some careful thought into the creation of the value for the
[example name] token, since it gets used in other places...
|By convention, the |
|make sure it is no more than 150 characters in length|
|use the SEO tag editor widget|
|make sure the example|
|only choose keywords if the example is a particularly exemplary showcase for that keyword, not if it just barely exhibits the quality or qualities represented by the keywords (provide an example of this principle)|
|with instructions to the user where appropriate so that things that are not always self-evident are not missed by the user|
|explanation should link to the module (or modules) that are the focus of the example|
|don't need to link to all modules used by the example's code (if your example happens to use Uize.Dom.Basics in a rather mundane way and merely in support of the main crux of the example, then it's not terribly compelling to call the user's attention to this)|
|inline code, such as static and instance method names, or the names of state properties, etc. should be enclosed in the |
|main content of example should not be so large as to prevent the entire example from being visible inside a 1024x768 window, even if explanation has to be scrolled out of view. There can be exceptions to this guideline.|
|find a way with the layout of the examples to put space around active draggable UI, to minimize the risk of drag taking the mouse outside the window and resulting in the sticky drag effect|
|where appropriate, examples should contain demos of programmatic interface, ideally below main content of example|
On a 1024x768 display with the browser maximized, an example page should never require horizontal scrolling.
The styling of the UIZE Web site imposes a maximum width of
780 pixels on the main content area for all pages, including example pages. The main layout for an example should be designed to fit within that width.
On a 1024x768 display with the browser maximized, an example page should ideally not require vertical scrolling.
This requirement is not as important as the requirement to avoid horizontal scrolling, but it preferable that example pages not require vertical scrolling. Where possible, modify the various elements of the main layout (such as the explanation text, the main content, and the programmatic interface demos) as needed to ensure that the combined height does not introduce vertical scrolling.
The styling of example pages includes a dotted marker line that indicates the maximum height for the combined contents of an example page.
The maximum height marker is subtle so as to not be too intrusive for those viewing the examples, but it's easy enough to spot when you're designing an example page. The position of the marker takes into account a worst case scenario of a browser with a lot of vertical chrome - window title bar, window menu bar, location bar, personal bookmarks bar, developer toolbar, and tabs. So, if your example page fits above that fold line, chances are there'll be enough breathing room to avoid scrolling on most notebook and netbook displays, and ample room to view the entire example in Safari on an iPad.
Avoiding vertical scrolling in example pages offers the following important benefits...
|Improved User Experience - By avoiding vertical scrolling wherever possible, the user experience of taking a tour through a series of examples is improved - the user gets to see in a single glance the overal layout / structure of the example to get the gist of what's going on, and the interation of stepping through multiple examples to find an example of interest is not punctuated by messing with scrolling to see if there's anything of interest below the fold.|
|Easier Screenshots - Avoiding vertical scrolling increases the chances of an example's entire UI fitting nicely into a screenshot, and thumbnails used to represent the example can better capture what's offered in the example.|
There will always be a few cases where it is just not possible to avoid vertical scrolling and still produce a viable example page.
Some example pages that have more content than can fit above the maximum height marker include...
|Hover Fader for Thumbnails|
|Populating Photo Details|
Apart from exceptional cases like those listed above, the overwhelming majority of the example pages are designed very deliberately so that their entire contents fits into a 1024x768 browser window without requiring vertical or horizontal scrollbars.
Whenever working on an example page where vertical scrolling may be necessary, consider the following guidelines...
|The main content of an example page should never be pushed below or deep into the maximum height marker because the explanation is too long.|
|If the main content of an example page must extend beneath the maximum height marker, make sure at least to fit a compelling portion of the main content above the maximum height marker, so that the user viewing the example can at least get a good sense of what it offers at first glance - there must be something sufficiently juicy within plain view.|
|refer to the HTML Style Guide|
6. What's Done for You Automatically
When you create a new example page, various build scripts perform some functions for you automatically.
For every example page (excluding unreleased example pages), a corresponding source code page is automatically generated.
Generated source code pages are all placed within the
examples/source-code folder, and the filename for each source code page is identical to the filename of its corresponding example.
Every example page you create (excluding unreleased example pages) is automatically listed in appropriate example index pages, using the title, meta description, and meta keywords you provided for the example.
The example pages listed in any of the examples by keyword listings, as well as the all examples listing, can be viewed in a step-by-step tour (see example), so any example page you create will be available in at least one tour, and possibly more (depending on how many category keywords you supply).
7. Announce a New Example Page or Tool
8. Revisit This Guide, As Needed
Therefore, take the process of creating example pages seriously. Don't be afraid to revisit this document as a refresher when adding a new example page, and as a last step / checklist before finally committing your new example page to the framework. If it takes a few minutes to skim through this document and see if you've forgotten or missed anything, it might be a few minutes well spent.