Attributes

In addition to its title and text, each Tinderbox note has a long list of attributes that describe aspects of the note: its name, color, position, shape, and size. You can define your own attributes as well. Attributes let you (and Tinderbox) put meaningful information in a known place.

For an informal note, you might simply write information in the note’s text:

Read Gibbon’s Decline and Fall of the Roman Empire

In other contexts — research notes for a dissertation, say — you

might prefer to be a bit more formal:

Author: Edward Gibbon

Title: The Decline and Fall of the Roman Empire

Author and Title are examples of attributes; by putting the name of the author in a specific place, it is easy for us (and for our Tinderbox agents) to distinguish a book by Gibbon from a book that is about Gibbon.

You don’t have to define Tinderbox attributes before you begin making and using notes. Tinderbox is designed to encourage experimentation and evolutionary change in your work. As your needs change and your understanding grows, you can add, change, and delete attributes whenever you like.

Each attribute has a value; values can be numbers, character strings, boolean (true/false) values, dates, colors, files, and so forth. Whenever you rename, edit, or change a note in Tinderbox, you are actually changing the value of one or more attributes of that note.

There are two types of attributes:

• System attributes: information built into all Tinderbox documents such as the color of the note, or its width and height. Tinderbox keeps this information about every note, and you may view, use, and change it.
• User attributes: you may add your own attributes that every note will have. For instance, you could add the attribute "Priority," and assign every note a priority level from one to five. Or in a bibliography, create the attribute "Type" and tag the note for each source as either "primary" or "secondary."

A few System attributes are

• Read-only attributes: information such as the date and time the note was created, or the date and time it was last modified. Other read-only attributes, such as TextLength and ChildCount, describe properties derived from the document’s current state and are inherently read-only. Tinderbox keeps this information about every note, and you may view and use it, but you cannot change it.

Tip: attribute names are case sensitive—"Height" is not the same as "height."

You can inspect and change the value of any attribute in a note's Get Info... window (choose Get Info from the Note menu). Inherited values are in gray; values set specifically for this note are in black, and read-only values are italicized.

Key Attributes

A note's key attributes are significant attribute-value pairs that you want to be displayed at the top of the note’s text window. You can choose the key attributes by setting the value of the attribute named KeyAttributes -- just enter the names of the attributes you'd like to make key attributes, separating them with semi-colons.

To add a key attribute to a note's text window

Select the key attribute from the Key Attributes menu in the text window sidebar, OR

Drag the key attribute from the Attributes palette and drop it into the text window, OR

Select the note and press Enter to view the note’s Rename dialog. Choose key attributes from the Key Attributes popup menu, and press OK.

You may drag key attributes to up or down to rearrange their sequence, or drag them out of the key attributes table into the text area of the note to remove them.

To see other attributes in a text window

In a text window

• click the Attributes triangle
• choose a type of attribute from the popup menu (General, HTML, etc.)
• scroll down to view attributes of that type

THE ATTRIBUTE PALETTE

The attribute palette is a convenient way to see what attributes your document has, and to change the default values for attributes.

Tip: the attributes palette does not allow you to change the value of an attribute for a selected individual note or notes. (The Quick Stamp is a good way to do that.).

To open the attributes palette

• choose Attributes from the Window menu or press Cmd-2

• The System tab of the attribute palette shows attributes that are built in to Tinderbox and that every note has. Attributes you can modify are listed in plain text. Read-only attributes are listed in italics.
• The User tab of the attribute palette shows attributes that you have created and added to this Tinderbox document.

TO CHANGE AN ATTRIBUTE'S VALUE

There are several ways to change an attribute's value for a selected note or notes:

• Using the quick stamp palette allows you to change the value of that attribute for one selected note or for many selected notes.
• In the Info window for a note shows all the note’s attributes and allows you to change the value of any attribute.
• The Value menu contains Stamps that allow you to change the value of that attribute for selected notes.

To use the quick stamp

From anywhere,

• select the desired note or notes
• choose Quick Stamp from the Window menu to open the quick stamp palette

In the quick stamp palette,

• select the desired attribute from the popup menus in the palette
• type the desired value into the Value text field
• click Apply to apply that value to that attribute in the selected note or notes

Changing some attributes—such as Width or Color—will alter the appearance or other visible properties of the note(s).

To change an attribute value using an info window

For some attributes, particularly attributes (such as HTMLExportTemplate) for which you are choosing a file, an info window is a more convenient way to change the attribute’s value.

From anywhere,

• select the desired note
• press Cmd-option-I or click the blue "i" button in the text window sidebar to open the info window

From the info window,

• double-click the desired attribute in the right-hand column of the list. (The left-hand column shows the attributes, the right-hand column shows their values.)
• in the dialog box, enter a new value for the attribute
• click OK or press Return to dismiss the dialog

You cannot change the values of attributes that are exclusively set by Tinderbox. (These attributes appear italicized in the list of attributes.)

Changing some attributes—such as Width, or Color—will alter the appearance or other visible properties of the note.

To set an attribute's default value

When Tinderbox checks the value of an attribute, it first sees whether a specific value has been assigned to that note. If a specific value has not been assigned, and there is also no prototype from which to take a value, most attributes define a default value that applies whenever no specific value exists. (Most attributes define their default value themselves; for a few, the default is set by a Preference pane.)

The Attributes window lets you change the default value of attributes. If you set the default value of Color to red, then all newly-created notes will be red, and all notes for which no specific color was chosen will also become red.

From anywhere,

• choose Attributes from the Window menu

Then, in the attribute palette,

• select the tab of the palette corresponding to the type of attribute you want to modify built in to Tinderbox
• select the desired attribute in the scrolling list of attributes
• type the desired default value in the text field on the palette
• click Change

To create a new attribute

You might not ever need to create a new attribute, but you might think of a few that suit your needs.

First, in the attribute palette,

• select the User tab of the palette
• click Create...

Or, from any info window,

• click the New button at the bottom of the window

Then,

• in the dialog box, choose a name, a type, and a default value for the new attribute
• click OK or press Return to dismiss the dialog

All notes will have this new attribute and will get the default value for the new attribute, until you set it otherwise in particular notes.

ATTRIBUTE TYPES

Attributes can be of various types, to contain various kinds of data:

string

Any sequence of text. "Yes," "Marie Hancock-Lowickie, Jr.," and the first paragraph of the Gettysburg Address would all be valid values for a string attribute. HTMLExportExtension is an example of a string attribute.

color

Color values are accepted in these formats:

• named colors. The name of a color that either comes pre-defined in Tinderbox, or which you have defined for this Tinderbox document using the Colors pane of the attribute palette. Examples: blue, red, minty-fresh-green.
• hexadecimal: six hexadecimal digits, the format used for describing colors in HTML. A hexadecimal value should be preceded by a number/hash sign sign. Example: #A482BF
• hue-saturation-value: Hue—a value from 0 to 360 degrees; saturation and value—from 0 to 100 percent. Preceded by HSV, and enclosed in parentheses. Examples: HSV(0,100,50), HSV(240,80,80).
• RGB: Red, green, and blue, with intensity levels represented as integers from 0 to 250. Examples: rgb(0,0,0) and rgb(68,153,68)

BorderColor, which controls the color of a note's main border, is an example of a color attribute.

You may drag color swatches out of the Colors pane of the Attributes palette, and drop them on notes in the map, outline or treemap views.

file

The pathname to a file. Used for such System attributes as HTMLExportTemplate.

boolean

A true/false value. May use either 1/0 or true/false. ShowTitle is an example of a boolean attribute.

date

A date and time. Month/day/year format, with an optional time. When entering a value for a date, you can also use the terms yesterday, today, and tomorrow, and add or subtract units of time. For example, these are all acceptable values for a date attribute:

10/25/2002

10/25/02

10/25 (assumes the current year)

November 15, 1955

Nov 15 55

today

today - 7 days

yesterday + 4 months (expressing date values relative to the current time is often convenient when defining agents and actions.)

Wednesday (interpreted as next Wednesday)

11/25/2002 12:43

Created is an example of a date attribute.

number

Either an integer or a floating point number, positive or negative.

set

Sets are strings separated by semicolons, and are useful for lists of topics, categories, and tags.

Status: urgent;delegatedToMartha

Topics: programming;computer languages;courses;news

Tags: tips and techniques; readme; TuesdayMeeting

Sets are much like string attributes, and anything that can change a string can change a set, but the operators + and - have different meanings in sets. In a set, "+" adds an element to a set and "-" removes it.

"Hello"+"world"="Hello;world"

"Hello;world"+"world"="Hello;world"

"Hello;world"-"hello"="world"

Sets can be assigned with Stamps, Quickstamp, the Get Info Window, or the Key Attributes table. They may also be set by agents and other actions.

KeyAttributes is an example of a set attribute.

ATTRIBUTES AND AGENTS

Agents often use attributes to locate notes accurately. If you define a user attribute Author, agents will locate books in your notes written by Booker T. Washington and ignore notes on Seattle, Washington.

Agents can also set the value of attributes. An agent could look for items that are due within a week and automatically set the priority to "urgent."

ATTRIBUTES AND HTML

The value of any attribute can be exported to HTML using the expression ^get(attribute_name). For example, if we have stored the location of an image in user attribute ImageName, we might export:

<img src="^get(ImageName)^">

OTHER PANES IN THE ATTRIBUTES PALETTE

COLORS - Tinderbox uses color names to refer to specific colors. In the Colors panel, you can change the color scheme and add their own. For example, if you prefer a subtler color scheme, you might redefine "black" to a medium gray, "blue" to a slate blue, and red to a rusty earth tone.

Each named color has seven variants. For example:

darkest red

darker red

dark red

red

light red

lighter red

lightest red

The Colors panel offers color swatches corresponding to each color variant, and lets you redefine existing colors.

STAMPS are actions that set attributes. Like a rubber stamp, a Stamp changes the selected note or notes to which you apply it, providing you a custom tool kit for your needs. See the Stamps chapter of this manual for details.

LINK TYPES - a list of the types of links possible between notes. Users may change the name and color of links here, make link types invisible in map views, or create their own link types.

MACROS - Macros bundle complex export expressions into simpler, more memorable packages. See the Using Macros section of the HTML Templates chapter for more.