Outline Class

© 2012, Martin Rinehart

Prerequisite: ability to program JavaScript objects.

23, Oct. 2013. Change of heart! The height has been eliminated in favor of outlines that are simply as tall as their content requires. (They expand/contract as topics are opened/closed.)

There are two places in the library where the height code has been commented out. The height argument to the view methods is no longer operative.

The top-line "-" and "+" sign buttons fold/unfold every topic. The standard, in-outline buttons fold/unfold the topic they prefix. To operate this widget with substantial outlines, visit our Pro HTML tables page.

The top-line buttons to the right of the title select the outline numbering style. Unfold some topics and give them a try.

The code that creates this outline is:

var sample_ref = document.getElementById( 'sample' );

var table = [
'Biology',
'    Plants',
'        Trees',
'            Deciduous',
'            Coniferous',
'        Other Plants',
'    Animals',
'        Birds',
'            Carnivores',
'            Herbivores',
'        Other Animals',
];

var outline = new Outline( table );
    outline.view_with_header( sample_ref, 150 );

(Leading tabs are not HTML friendly. Mentally find/replace four spaces with a tab character.)

The following documentation is not helpful if you want to use these outlines. Study the example above and click on the sample until you think you know everything. You probably do.

The following documents the internals and will be of interest to those who want to modify/improve these outlines in fundamental ways.

Outline Basics

An Outline is created from a table a Table (or array—see below). You can supply styles to suit your design. The example above shows the default styles.

To include the outline widget in your DOM, you use one of its view() methods. The standard one, shown above, is view_with_header(). It takes a parent DOM element and a height (in pixels).

The table will automatically be created from an array of strings with leading tabs that looks like an outline:

[ 'topic',
'    sub-topic 1',
'        minor detail 1',
'        minor detail 2',
'    sub-topic 2'
]

You may supply a Table, if you have one. Otherwise, the Outline() constructor uses a string array like the one above to create a Table. The Table holds an array of outline entry data. Each row (entry) is an array of at least two elements: an 'outline number' and a 'topic'. Additional elements will be bundled into an additional table column called "Content". The first element of the content array, if any, is used as a tooltip when the user hovers over a topic.

The outline numbers, called 'OutNum's, are arrays of numbers written in technical specification style as, for example, "5.3.2" (section 5, subsection 3, sub-subsection 2). This example is represented as OutNum [5, 3, 2].

The OutNum arrays in the input Table are in sorted order: subsection 4.10 comes after subsection 4.9 (warning: that's neither numeric nor lexicographic).

The first row of the table has an empty array for its OutNum. The first row's topic is the outline title.

The 'parent' is the DOM element within which the outline will appear. The outline's div is the last child of the parent when it is created.

The Outline Class

See the "Introduction" section (above) to create and use an Outline. The first parameter, table should be created by passing an array of appropriately indented strings, as shown above. See the code if you already have a Table.

The outline Class Methods

Note: The outline code (no uppercase) serves as a class for objects instantiated by the Outline constructor, which instantiates objects and contains the prototype property where instance methods are found.

These are the instance methods of the outline class. (Class statics, in Java terminology.) Some may be useful in other applications. The roman numerals have not been extended to their full range (3,000), but the code clearly shows how this can be done.

The outline.letter() Method

Returns one of 'A', 'B', ... 'Z' given number 1, 2, ... 26. Throws exception for larger number input.

The outline.letter_lower() Method

Returns one of 'a', 'b', ... 'z' given number 1, 2, ... 26. Throws exception for larger number input.

The outline.roman() Method

Returns one of 'I', 'II', ... 'C' given number 1, 2, ... 100. Throws exception for larger number input.

The outline.roman_lower() Method

Returns one of 'i', 'ii', ... 'c' given number 1, 2, ... 100. Throws exception for larger number input.

The Outline.section_number() Method

Returns "1.2.3" given [ 1, 2, 3 ].

The Outline.outline_number() Method

Returns section numbers aligned per the specific requirements of these outlines. ([ 1 ] returns "I. ". [ 1, 2 ] returns "2. ", and so on.)

The Outline Instance Methods

In normal use, display the outline with one of the view methods. The other methods are internal.

The Outline.click_header_minus_plus() Method

Listener assigned to header "-" and "+" buttons click event. Called by browser (if not IE) with event, (parameter not used). Folds or unfolds one level. Enables or disables "-" and "+" buttons as appropriate.

The Outline.click_numbering_button() Method

Listener assigned to header numbering buttons. Also called with unused parameter. (The "this" variable is used in the function.) Assigns a numbering style (none, outline style or technical manual style). Disables self and enables the other two numbering buttons.

The Outline.enable_header_minus_plus() Method

Enables, if first parameter is true or disables a header "-" or "+" button. Second parameter specifies the button: the minus button if true.

The Outline.numbering_button_enable() Method

Enables or disables a numbering button. The button parameter is one of 'none', 'out' or 'tech'. The enable parameter specifies enabling, if it is true; disabling if false.

The Outline.repaint() Method

Causes the repainting of the outline entries portion of the widget. The job is to paint only visible entries and to display the "-" or "+" prefix button, as needed.

The Outline.view() Method

A convenience synonym for view_plain().

The Outline.view_plain() Method

outline.view_plain( parent, height );

Displays the outline widget in the parent DOM element (document.body is the default) at the specified height in pixels (default: 500).

The Outline.view_with_header() Method

Same syntax as view_plain(). Moves the outline's first entry up into a header row as the title. Adds plus/minus buttons to the left and numbering style buttons to the right of the title.

The OutlineEntry Class

Each line of the outline (after the top line) is an OutlineEntry object. These indent, display the name, add the "+" or "-" sign prefix (if needed) and show the outline level numbers ("1.2.3" or "I.B.3") if numbering is selected.

The OutlineEntry objects are widget parts that are unique to the parent widget. They have no known use outside the Outline class.

The OutlineEntry Instance Methods

The OutlineEntry.fold() Method

Called by OutlineEntry.click_entry_plus() to fold (or unfold) the entry. A folded entry does not show its children.

The OutlineEntry.mouseover() and mouseout() Methods

This methods change the backgruond color and the cursor to those specified by outline.data. Defaults: white background, pointer cursor on mouseover() and widget background color, default cursor otherwise.

The OutlineEntry.click_entry_plus() Method

This method responds to a click on the "+" sign (or, after a "+" click, the "-" sign), unfolding (or folding) the topic. It marks the topic as unfolded (or folded) and calls the outline.repaint() method which handles the display.

The OutlineEntry.click_topic() Method

This method responds to a click on the topic. It should be overridden with an outline-specific method. The default alerts that there is no link available for the topic.

Feedback: MartinRinehart at gmail dot com

# # #