GUIDES Using The Documentation
1. Introduction
To learn all about UIZE, you'll have to rely heavily on the documentation. This document discusses tips for using the documentation more effectively.
2. Navigating This Site
Navigating the documentation - and the entire UIZE Web site, in general - can be done by mousing over the UIZE logo at the top left and then using the drop down menu that pops up. Easy!
3. Sections of This Web Site
3.1. Example Pages
If you haven't already taken a tour through the many example pages available with the UIZE JavaScript Framework, you're encouraged to browse through these examples under the "Examples" section.
3.1.1. Viewing Example Source Code
If you stumble onto an example where you see something you particularly like, you can then view the source code by clicking on the convenient "SOURCE" button on the right hand side of the example's title bar.
If you scroll to the bottom of the source page, you'll see a Uize.module
declaration that sets up the page widget for the page. This block of code will give you a sense of which UIZE modules are used in the page.
3.1.2. Designed to be Demonstrative
The many examples included are designed to be demonstrative, and are not guaranteed to be the prettiest possible embodiments of widgets.
UIZE widgets can look very slick and elegant with appropriate design and styling, but the focus of the example pages is keeping the source code as clean and simple as possible, so that one can quickly cut through the fluff and get to the essence of how UIZE classes can be used in a page.
Similarly, UIZE widgets can be combined together in intricate ways to produce sophisticated applications. However, when trying to learn how to use a specific UIZE class, trying to get your head around a complex chunk of code when you just want to see how to use a single class can feel frustrating and counterproductive.
So, the many example pages offered with the documentation are deliberately designed to be quite elemental in nature. Some demonstrate how code components can interact with one another. However, the examples are not necessarily designed to be compelling - they're designed to be instructive. We trust you will use your imagination in applying the UIZE JavaScript Framework towards the development of your own compelling applications.
3.2. Guides
Learn how to use the UIZE JavaScript Framework by reading through the various topic oriented documents in the Guides section.
This section covers things from a subject matter perspective, and deals with such topics as Classes and Inheritance, JavaScript Events, JavaScript Modules, JavaScript Templates, JavaScript Widgets, JavaScript Localization, JavaScript Documentation, JavaScript Code Compression, JavaScript Build Scripts, and lots more.
Because the pages in this section are topic oriented, they will likely refer to many different module reference documents, link to examples, and cross-reference other guides.
3.3. Module Reference
Every module in the UIZE JavaScript Framework has a corresponding reference document that can be found under the "Module Reference" section.
3.3.1. Structure of the Module Reference Section
The contents list under this section is structured according to the class and namespace hierarchy of the modules, themselves.
So, for example, the reference document for the Uize.Widget.Page
class would be the item "Page" under the section "Widget" under the section "Uize" (i.e. "Uize" -> "Widget" -> "Page"). For modules that also have modules underneath them, the item for the module will be named [[ BASE ]]
and will be inside the section named after the last level in the module's name. For instance, the class Uize.Widget
is represented as the item "[[ BASE ]]" under the section "Widget" under the section "Uize" (i.e. "Uize" -> "Widget" -> "[[ BASE ]]"). This allows "Widget" to be a section that contains all the other subclasses and deeper namespaces alongside the Uize.Widget
base class.
3.3.2. Viewing Module Source Code
On any one of the module reference documents, you can conveniently view the source code of the module by clicking the "SOURCE" button on the right hand side of the title bar.
Then, to get back to the reference document from a module's source code page, just click the "VIEW REFERENCE" button on the right hand side of the page's title bar.
3.3.3. Playing Catch-up
There is module reference documentation that still needs to be written.
The documentation under the "Module Reference" section is generated automatically by a build script that runs through all the JavaScript modules and extracts documentation styled SimpleDoc comments. In reality, there are a number of modules that don't yet have documentation written. The documentation is still playing catch-up to the code development, so you may stumble across many a sad looking module reference page - with nothing on it but a lonely heading. Documentation is being written all the time, so please be patient with this effort.
Even for modules that aren't yet documented, you can still use the module reference pages as a starting point for search, by clicking on the convenient "SEARCH" link to the right of the module name in their title bar (see the section Searching for References to a Module), or as a way of viewing the source code for modules while browsing the site (see the section Viewing Module Source Code).
3.4. Tests
The tests section contains pages that are likely more interesting to developers on the UIZE JavaScript Framework than developers using the framework, with performance tests that have helped determine some implementation choices for the UIZE JavaScript Framework.
3.5. Appendixes
Various miscellaneous documents are thrown under the "Appendixes" section.
This section includes such things as a credits list, endorsements of software and utilities, a glossary or terms, style guides, UIZE licensing terms, some JavaScript trivia, and more. Sniff around and see what you find.
4. Search Tips
If you're looking for information on something in particular, be sure to use the convenient "SEARCH" link located in the lower left - at the very bottom of the contents menu pane.
You may be looking for references to a certain topic (such as "Ajax"), or you may be looking for references to method names (eg "Uize.Dom.Basics.setStyle"), or module names (e.g. "Uize.Widget.Calendar"), or types of widgets (e.g. "calendar"). Search for anything within the UIZE Web site. Just click the "SEARCH" link, enter your search query in the search page that loads in, and then click on one of the search buttons for the various main sections of the site - your search will be conducted within that section.
4.1. Searching for References to a Module
When you're reading up on a particular JavaScript module and you want to understand more about it by viewing examples that use it, or by reading guides that reference it, or by seeing how it's used by other modules, etc., then a dedicated feature of the module reference documents will make your life easier.
Simply browse to the reference document for a particular module under the "Module Reference" section. When the reference document loads in, you'll notice a "( SEARCH )" link in parentheses, just after the module name in the title bar. This special search features makes it easy to find references to a module (or its subclasses or extensions) inside different sections of the site. Click on this link and you will be taken to a page where you can choose the section you'd like to search in.
4.1.1. ENTIRE SITE
To find pages throughout the entire UIZE Web site that reference the module you're searching on, use this link. Your search results could include pages from all sections of the site, including the example pages, example source code pages, module reference documents, module source code pages, guides, appendixes, etc.
4.1.2. IN EXAMPLES
To learn how to use a module, it may be helpful to see how it is used in example pages. If you want to find examples that directly use a module, or that reference it somewhere in the source, use this link.
Your search will be performed within the examples/source-code
section of the site, so the results will contain the source code documents for examples that reference the module you're searching on. If you click a search result you will then see the source code for an example. You can read through the source code to see how the module is referenced. To view the live example, just click the "VIEW EXAMPLE" button on the right hand side of the title bar.
4.1.3. IN MODULES
To learn how to use a module, it may be helpful to see how it is used by other modules. To find modules that directly use a module, or that reference it somewhere in the source, use this link.
Your search will be performed within the reference/source-code
section of the site, so the results will contain the source code documents for modules that reference the module you're searching on. If you click a search result you will then see the source code for a module. You can read through the source code to see how the module you're searching on is referenced. To view the reference document for the module, just click the "VIEW REFERENCE" button on the right hand side of the title bar.
4.1.4. IN GUIDES
To find guides that reference the module you're searching on (or its subclasses or extensions), use this link. Your search will be performed within the guides
section of the site.
5. General Documentation Tips
A number of features of the documentation are available within all documents in the UIZE Web site.
5.1. Contents Lists
5.1.1. Expanding One Level Deep
For all contents trees in the UIZE Web site, a collapsed section can be expanded to only one level deep by holding down the shift key while clicking on the expander arrow, allowing you to "peel back the layers", one at a time.
5.1.2. Expading All
For all contents trees in the UIZE Web site, a collapsed section can be fully expanded (so that all deeper subsections are also fully expanded) by holding down the ctrl key while clicking on the expander arrow.
5.1.3. Contents List Tooltips
For any item in a document page's contents list, a tooltip is displayed when hovering over the item, that provides a snapshot / preview of the section by showing a portion of the first paragraph of the section (provided that the section has a first paragraph).
For module reference documents, the first paragraph is typically a one or two sentence summary of a method, property, event, DOM node, etc., so you can use the contents tree as a kind of feature summary or cheat sheet.
5.2. Hyperlinked Section Numbering
A feature of the documentation that may come in handy on occasion and that is kind of buried is the hyperlinking of the section numbering.
Basically, every number in the numbering of sections links back to the start of that section node, so you can conveniently "prune" back to a higher section level just by clicking on the appropriate linked number. This is best explained by using an example, so let's say that you are reading in section "1.2.3." of a document. Then, if you clicked the number "3" in the section number, you would be taken to the top of section "1.2.3.". If you clicked the number "2", you would be taken to the top of section "1.2.". And if you clicked the number "1", you would be taken to the top of section "1.". This is kind of like a more sophisticated "back to top" feature.