Item

A paragraph of text in an Outline .

Items cannot be created directly. Use Outline::createItem to create items.

Items may contain other child items to form a hierarchy. When you move an item its children move with it. See the “Structure” and “Mutate Structure” sections for associated APIs. To move an item while leaving it’s children in place see the methods in Outline s “Insert & Remove Items”.

Items may have associated attributes. You can add your own attributes by using the APIs described in the “Item Attributes” section. For example you might add a due date using the data-due-date attribute.

Items have an associated paragraph of body text. You can access it as plain text or as an immutable AttributedString . You can also add and remove attributes from ranges of body text. See “Item Body Text” for associated APIs. While you can add these attributes at runtime, TaskPaper won’t save them to disk since it saved in plain text without associated text run attributes.

Examples

Create Items:

var item = outline.createItem('Hello World!');
outline.root.appendChildren(item);

Add attributes to body text:

var item = outline.createItem('Hello World!');
item.addBodyAttributeInRange('B', {}, 6, 5);
item.addBodyAttributeInRange('I', {}, 0, 11);

Reading attributes from body text:

var effectiveRange = {};
var textLength = item.bodyString.length;
var index = 0;
while (index < textLength) {
  console.log(item.getBodyAttributesAtIndex(index, effectiveRange));
  index += effectiveRange.length;
}

Properties

::id: Read-only unique String identifier.
::outline: Read-only Outline that this item belongs to.

Clone

::clone(deep?)

Clones this item.

Argument	Description
`deep?`	defaults to true.

Return Values
Returns a duplicate `Item` with a new `::id` .

Structure

::isInOutline

Read-only true if item is contained by root of owning Outline .

::isOutlineRoot

Read-only true if is ::outline root Item .

::depth

Read-only depth of Item in outline structure. Calculated by summing the Item::indent of this item and it’s ancestors.

::parent

Read-only parent Item .

::firstChild

Read-only first child Item .

::lastChild

Read-only last child Item .

::previousSibling

Read-only previous sibling Item .

::nextSibling

Read-only next sibling Item .

::previousBranch

Read-only previous branch Item .

::nextBranch

Read-only next branch Item .

::ancestors

Read-only Array of ancestor Item s.

::descendants

Read-only Array of descendant Item s.

::lastDescendant

Read-only last descendant Item .

::branchItems

Read-only Array of this Item and its descendants.

::lastBranchItem

Last Item in branch rooted at this item.

::previousItem

Read-only previous Item in the outline.

::nextItem

Read-only next Item in the outline.

::hasChildren

Read-only has children Boolean .

::children

Read-only Array of child Item s.

.getCommonAncestors(items)

Given an array of items determines and returns the common ancestors of those items.

Argument	Description
`items`	`Array` of `Item` s.

Return Values
Returns a `Array` of common ancestor `Item` s.

::contains(item)

Determines if this item contains the given item.

Argument	Description
`item`	The `Item` to check for containment.

Return Values
Returns `Boolean` .

Mutate Structure

::indent

Visual indent of Item relative to parent. Normally this will be 1 for children with a parent as they are indented one level beyond there parent. But items can be visually over-indented in which case this value would be greater then 1.

::insertChildrenBefore(children, referenceSibling?)

Insert the new children before the referenced sibling in this item’s list of children. If referenceSibling isn’t defined the new children are inserted at the end. This method resets the indent of children to match referenceSibling’s indent or to 1.

Argument	Description
`children`	`Item` or `Array` of `Item` s to insert.
`referenceSibling?`	The referenced sibling `Item` to insert before.

::appendChildren(children)

Append the new children to this item’s list of children.

Argument	Description
`children`	`Item` or `Array` of `Item` s to append.

::removeChildren(children)

Remove the children from this item’s list of children. When an item is removed its the parent’s ::depth is added to the removed item’s ::indent , preserving the removed items depth if needed later.

Argument	Description
`children`	`Item` or `Array` of child `Item` s to remove.

::removeFromParent()

Remove this item from it’s parent item if it has a parent.

Item Attributes

::attributes

Read-only key/value object of the attributes associated with this Item .

::attributeNames

Read-only Array of this Item ‘s attribute names.

::hasAttribute(name)

Return Boolean true if this item has the given attribute.

Argument	Description
`name`	The `String` attribute name.

::getAttribute(name, clazz?, array?)

Return the value of the given attribute. If the attribute does not exist will return null. Attribute values are always stored as String s. Use the class and array parameters to parse the string values to other types before returning.

Argument	Description
`name`	The `String` attribute name.
`clazz?`	Class ( `Number` or `Date` ) to parse string values to objects of given class.
`array?`	`Boolean` true if should split comma separated string value to create an array.

Return Values
Returns attribute value.

::setAttribute(name, value)

Adds a new attribute or changes the value of an existing attribute. id is reserved and an exception is thrown if you try to set it. Setting an attribute to null or undefined removes the attribute. Generally all item attribute names should start with data- to avoid conflict with built in attribute names.

Attribute values are always stored as String s so they will stay consistent through any serialization process. For example if you set an attribute to the Number 1.0 when you ::getAttribute the value is the String "1.0". See ::getAttribute for options to automatically convert the stored String back to a Number or Date .

Argument	Description
`name`	The `String` attribute name.
`value`	The new attribute value.

::removeAttribute(name)

Removes an item attribute.

Argument	Description
`name`	The `String` attribute name.

Item Body Text

::bodyString

Body text as plain text String .

::bodyContentString

Body “content” text as plain text String . Excludes trailing tags and leading syntax. For example used when displaying items to user’s in menus.

::bodyAttributedString

Body text as immutable AttributedString . Do not modify this AttributedString, instead use the other methods in this “Body Text” section. They will both modify the string and create the appropriate Mutation events needed to keep the outline valid.

::bodyHighlightedAttributedString

Syntax highlighted body text as immutable AttributedString . Unlike bodyAttributedString this string contains attributes created by syntax highlighting such as tag name and value ranges.

Do not modify this AttributedString, instead use the other methods in this “Body Text” section. They will both modify the string and create the appropriate Mutation events needed to keep the outline valid.

::getBodyAttributesAtIndex(characterIndex, effectiveRange?, longestEffectiveRange?)

Argument	Description
`characterIndex`	The character index.
`effectiveRange?`	`Object` whose `location` and `length` properties are set to effective range of the attributes.
`longestEffectiveRange?`	`Object` whose `location` and `length` properties are set to longest effective range of the attributes.

Return Values
Returns an `Object` with keys for each attribute at the given character characterIndex, and by reference the range over which the attributes apply.

::getBodyAttributeAtIndex(attribute, characterIndex, effectiveRange?, longestEffectiveRange?)

Argument	Description
`attribute`	Attribute `String` name.
`characterIndex`	The character index.
`effectiveRange?`	`Object` whose `location` and `length` properties are set to effective range of the attribute.
`longestEffectiveRange?`	`Object` whose `location` and `length` properties are set to longest effective range of the attribute.

Return Values
Returns the value for an attribute with a given name of the character at a given characterIndex, and by reference the range over which the attribute applies.

::addBodyAttributeInRange(attribute, value, location, length)

Adds an attribute to the characters in the given range.

Argument	Description
`attribute`	The `String` attribute name.
`value`	The attribute value.
`location`	Start character index.
`length`	Range length.

::addBodyAttributesInRange(attributes, location, length)

Adds attributes to the characters in the given range.

Argument	Description
`attributes`	`Object` with keys and values for each attribute
`location`	Start index.
`length`	Range length.

::removeBodyAttributeInRange(attribute, location, length)

Removes the attribute from the given range.

Argument	Description
`attribute`	The `String` attribute name
`location`	Start character index.
`length`	Range length.

::replaceBodyRange(location, length, insertedText)

Replace body text in the given range.

Argument	Description
`location`	Start character index.
`length`	Range length.
`insertedText`	`String` or `AttributedString`

::appendBody(text)

Append body text.

Argument	Description
`text`	`String` or `AttributedString`

Debug

::branchToString()

Return Values
Returns debug string for this item and it’s descendants.

::toString()

Return Values
Returns debug string for this item.

Item

Item

Examples

Properties

Clone

Structure

Mutate Structure

Item Attributes

Item Body Text

Debug

results matching ""

No results matching ""