Documentation

Nag_Task
in package

Nag_Task handles as single task as well as a list of tasks and implements a recursive iterator to handle a (hierarchical) list of tasks.

See the enclosed file LICENSE for license information (GPL). If you did not receive this file, see http://www.horde.org/licenses/gpl.

Tags
author

Jan Schneider jan@horde.org

Table of Contents

$  : tags
$actual  : float
The actual task length.
$alarm  : int
The task alarm threshold in minutes.
$assignee  : string
The task assignee.
$children  : array<string|int, mixed>
The sub-tasks.
$complete_link  : string
URL to complete the task.
$completed  : bool
Whether the task is completed.
$completed_date  : int
The completion date timestamp.
$created  : Horde_Date
The creation time.
$createdby  : string
The creator string.
$delete_link  : string
URL to delete the task.
$desc  : string
The task decription.
$due  : int
The due date timestamp.
$edit_link  : string
URL to edit the task.
$estimate  : float
The estimated task length.
$id  : string
The task id.
$indent  : int
This task's idention (child) level.
$internaltags  : array<string|int, mixed>
Task tags from the storage backend (e.g. Kolab)
$lastChild  : bool
Whether this is the last sub-task.
$methods  : array<string|int, mixed>
The particular alarm methods overridden for this task.
$modified  : Horde_Date
The last modification time.
$modifiedby  : string
The last-modifier string.
$name  : string
The task title.
$organizer  : string
Task organizer
$otherCaldavAttributes  : array<string|int, mixed>
$ourCaldavAttributes  : array<string|int, mixed>
$owner  : string
The task owner.
$parent  : Nag_Task
The parent task.
$parent_id  : string
The parent task's id.
$priority  : int
The task priority from 1 = highest to 5 = lowest.
$private  : bool
Whether the task is private.
$recurrence  : Horde_Date_Recurrence
Recurrence rules for recurring tasks.
$snooze  : int
Snooze minutes for this event's alarm.
$start  : int
The start date timestamp.
$status  : int
The assignment status of this task.
$tasklist  : string
This task's tasklist id.
$tasklist_name  : string
This task's tasklist name.
$uid  : string
The task uid.
$view_link  : string
URL to view the task.
$_dict  : array<string|int, mixed>
Task id => pointer dictionary.
$_inlist  : bool
Internal flag.
$_pointer  : int
Internal pointer.
$_storage  : Nag_Driver
A storage driver.
$_tags  : string
Task tags (lazy loaded).
__clone()  : mixed
Deep clone so we can clone the child objects too.
__construct()  : mixed
Constructor.
__get()  : mixed
Getter.
__set()  : mixed
Setter.
actuals()  : int
Returns the actual length for this and any sub tasks.
add()  : mixed
Adds a sub task to this task.
backgroundColor()  : string
Returns the background color.
childrenCompleted()  : bool
Returns whether all sub tasks are completed.
childrenOverdue()  : bool
Returns whether any tasks in the list are overdue.
count()  : int
Returns the number of tasks including this and any sub tasks.
each()  : mixed
Returns the next task iterating through all tasks and sub tasks.
estimation()  : int
Returns the estimated length for this and any sub tasks.
foregroundColor()  : string
Returns the foreground color.
fromASTask()  : mixed
Create a nag Task object from an activesync message
fromiCalendar()  : mixed
Creates a task from a Horde_Icalendar_Vtodo object.
get()  : Nag_Task
Returns a sub task by its id.
getFormattedDescription()  : string
Format the description - link URLs, etc.
getNextDue()  : Horde_Date|null
Returns the next due date of this task.
getNextStart()  : Horde_Date
Returns the next start date of this task.
getParent()  : mixed
Returns the parent task of this task, if one exists.
getSlice()  : Nag_Task
Helper method for getting only a slice of the total tasks in this list.
hasSubTasks()  : bool
Returns whether this task contains any sub tasks.
hasTask()  : Nag_Task|false
Return the task, if present anywhere in this tasklist, regardless of child depth.
hasTasks()  : bool
Returns whether this is a task (not a container) or contains any sub tasks.
loadChildren()  : mixed
Loads all sub-tasks.
loadTags()  : mixed
Recursively loads tags for all tasks contained in this object.
merge()  : mixed
Merges a task hash into this task object.
mergeChildren()  : mixed
Merges an array of tasks into this task's children.
orphan()  : mixed
Disconnect this task from any child tasks. Used when building search result sets since child tasks will be re-added if they actually match the result, and there is no guarentee that a tasks's parent will be present in the result set.
process()  : mixed
Processes a list of tasks by adding action links, obscuring details of private tasks and calculating indentation.
recurs()  : bool
Returns whether this task is a recurring task.
reset()  : mixed
Resets the tasks iterator.
save()  : mixed
Saves this task in the storage backend.
sort()  : mixed
Sorts sub tasks by the given criteria.
synchronizeTags()  : mixed
Syncronizes tags from the tagging backend with the task storage backend, if necessary.
toAlarm()  : array<string|int, mixed>
Returns an alarm hash of this task suitable for Horde_Alarm.
toASTask()  : Horde_ActiveSync_Message_Task
Create an AS message from this task
toggleComplete()  : mixed
Toggles completion status of this task. Moves a recurring task to the next occurence on completion. Enforces the rule that sub tasks must be completed before parent tasks.
toHash()  : array<string|int, mixed>
Returns a hash representation for this task.
toiCalendar()  : Horde_Icalendar_Vtodo
Exports this task in iCalendar format.
toJson()  : object
Returns a simple object suitable for json transport representing this task.
treeIcons()  : string
Returns the HTML code for any tree icons, when displaying this task in a tree view.

Properties

$

public tags $

array An array of tags this task is tagged with.

$actual

The actual task length.

public float $actual

$alarm

The task alarm threshold in minutes.

public int $alarm

$assignee

The task assignee.

public string $assignee

$children

The sub-tasks.

public array<string|int, mixed> $children = array()

URL to complete the task.

public string $complete_link

$completed

Whether the task is completed.

public bool $completed

$completed_date

The completion date timestamp.

public int $completed_date

$created

The creation time.

public Horde_Date $created

$createdby

The creator string.

public string $createdby

URL to delete the task.

public string $delete_link

$desc

The task decription.

public string $desc

$due

The due date timestamp.

public int $due

URL to edit the task.

public string $edit_link

$estimate

The estimated task length.

public float $estimate

$id

The task id.

public string $id

$indent

This task's idention (child) level.

public int $indent = 0

$internaltags

Task tags from the storage backend (e.g. Kolab)

public array<string|int, mixed> $internaltags

$lastChild

Whether this is the last sub-task.

public bool $lastChild

$methods

The particular alarm methods overridden for this task.

public array<string|int, mixed> $methods

$modified

The last modification time.

public Horde_Date $modified

$modifiedby

The last-modifier string.

public string $modifiedby

$name

The task title.

public string $name

$organizer

Task organizer

public string $organizer

$otherCaldavAttributes

public array<string|int, mixed> $otherCaldavAttributes = []

$ourCaldavAttributes

public array<string|int, mixed> $ourCaldavAttributes = [ 'AALARM', 'ALARM', 'ATTENDEE', 'CATEGORIES', 'CLASS', 'CREATED', // Assume Horde History is right about this. This may not always be true. 'DCREATED', 'DTSTART', 'DESCRIPTION', 'DUE', 'EXDATE', 'LAST-MODIFIED', // Let Horde History handle LAST-MODIFIED attribute 'ORGANIZER', 'PRIORITY', 'RELATED-TO', 'RRULE', 'STATUS', 'SUMMARY', 'UID', 'X-MOZ-LASTACK', 'X-MOZ-SNOOZE-TIME', 'X-HORDE-ESTIMATE', 'X-HORDE-EFFORT', ]

$owner

The task owner.

public string $owner

$parent_id

The parent task's id.

public string $parent_id = ''

$priority

The task priority from 1 = highest to 5 = lowest.

public int $priority

$private

Whether the task is private.

public bool $private

$recurrence

Recurrence rules for recurring tasks.

public Horde_Date_Recurrence $recurrence

$snooze

Snooze minutes for this event's alarm.

public int $snooze
Tags
see
Horde_Alarm::snooze()

$start

The start date timestamp.

public int $start

$status

The assignment status of this task.

public int $status

$tasklist

This task's tasklist id.

public string $tasklist

$tasklist_name

This task's tasklist name.

public string $tasklist_name

Overrides the $tasklist's share name.

$uid

The task uid.

public string $uid

URL to view the task.

public string $view_link

$_dict

Task id => pointer dictionary.

protected array<string|int, mixed> $_dict = array()

$_inlist

Internal flag.

protected bool $_inlist = \false
Tags
see
each()

$_pointer

Internal pointer.

protected int $_pointer = 0
Tags
see
each()

$_tags

Task tags (lazy loaded).

protected string $_tags

Methods

__clone()

Deep clone so we can clone the child objects too.

public __clone() : mixed
Return values
mixed

__construct()

Constructor.

public __construct([Nag_Driver $storage = null ][, array<string|int, mixed> $task = null ]) : mixed

Takes a hash and returns a nice wrapper around it.

Parameters
$storage : Nag_Driver = null

A storage driver.

$task : array<string|int, mixed> = null

A task hash.

Return values
mixed

__get()

Getter.

public __get(string $name) : mixed

Returns 'tags' property.

Parameters
$name : string

Property name.

Return values
mixed

Property value.

__set()

Setter.

public __set(string $name, mixed $value) : mixed
Parameters
$name : string

Property name.

$value : mixed

Property value.

Return values
mixed

actuals()

Returns the actual length for this and any sub tasks.

public actuals() : int
Return values
int

The actual length sum.

add()

Adds a sub task to this task.

public add(Nag_Task $task[, mixed $replace = false ]) : mixed
Parameters
$task : Nag_Task

A sub task.

$replace : mixed = false
Return values
mixed

backgroundColor()

Returns the background color.

public backgroundColor() : string
Return values
string

A HTML color code.

childrenCompleted()

Returns whether all sub tasks are completed.

public childrenCompleted() : bool
Return values
bool

True if all sub tasks are completed.

childrenOverdue()

Returns whether any tasks in the list are overdue.

public childrenOverdue() : bool
Return values
bool

True if any task or sub tasks are overdue.

count()

Returns the number of tasks including this and any sub tasks.

public count() : int
Return values
int

The number of tasks and sub tasks.

each()

Returns the next task iterating through all tasks and sub tasks.

public each() : mixed

Call reset() each time before looping through the tasks: $tasks->reset(); while ($task = $tasks->each() { ... }

Tags
see
reset()
Return values
mixed

estimation()

Returns the estimated length for this and any sub tasks.

public estimation() : int
Return values
int

The estimated length sum.

foregroundColor()

Returns the foreground color.

public foregroundColor() : string
Return values
string

A HTML color code.

fromASTask()

Create a nag Task object from an activesync message

public fromASTask(Horde_ActiveSync_Message_Task $message) : mixed
Parameters
$message : Horde_ActiveSync_Message_Task

The task object

Return values
mixed

fromiCalendar()

Creates a task from a Horde_Icalendar_Vtodo object.

public fromiCalendar(Horde_Icalendar_Vtodo $vTodo) : mixed
Parameters
$vTodo : Horde_Icalendar_Vtodo

The iCalendar data to update from.

Return values
mixed

get()

Returns a sub task by its id.

public get(string $key) : Nag_Task

The methods goes recursively through all sub tasks until it finds the searched task.

Parameters
$key : string

A task id.

Return values
Nag_Task

The searched task or null.

getFormattedDescription()

Format the description - link URLs, etc.

public getFormattedDescription() : string
Return values
string

getNextDue()

Returns the next due date of this task.

public getNextDue() : Horde_Date|null

Takes recurring tasks into account.

Return values
Horde_Date|null

The next due date or null if no due date.

getNextStart()

Returns the next start date of this task.

public getNextStart() : Horde_Date

Takes recurring tasks into account.

Return values
Horde_Date

The next start date.

getParent()

Returns the parent task of this task, if one exists.

public getParent() : mixed
Return values
mixed

The parent task, null if none exists

getSlice()

Helper method for getting only a slice of the total tasks in this list.

public getSlice(int $page[, int $perpage = null ]) : Nag_Task
Parameters
$page : int

The starting page.

$perpage : int = null

The count of tasks per page.

Return values
Nag_Task

The resulting task list.

hasSubTasks()

Returns whether this task contains any sub tasks.

public hasSubTasks() : bool
Return values
bool

True if this task has sub tasks.

hasTask()

Return the task, if present anywhere in this tasklist, regardless of child depth.

public hasTask(string $taskId) : Nag_Task|false
Parameters
$taskId : string

The task id we are looking for.

Return values
Nag_Task|false

The task object, if found. Otherwise false.

hasTasks()

Returns whether this is a task (not a container) or contains any sub tasks.

public hasTasks() : bool
Return values
bool

True if this is a task or has sub tasks.

loadChildren()

Loads all sub-tasks.

public loadChildren([mixed $include_history = true ]) : mixed
Parameters
$include_history : mixed = true
Return values
mixed

loadTags()

Recursively loads tags for all tasks contained in this object.

public loadTags() : mixed
Return values
mixed

merge()

Merges a task hash into this task object.

public merge(array<string|int, mixed> $task) : mixed
Parameters
$task : array<string|int, mixed>

A task hash.

Return values
mixed

mergeChildren()

Merges an array of tasks into this task's children.

public mergeChildren(array<string|int, mixed> $children) : mixed
Parameters
$children : array<string|int, mixed>

A list of Nag_Tasks.

Return values
mixed

orphan()

Disconnect this task from any child tasks. Used when building search result sets since child tasks will be re-added if they actually match the result, and there is no guarentee that a tasks's parent will be present in the result set.

public orphan() : mixed
Return values
mixed

process()

Processes a list of tasks by adding action links, obscuring details of private tasks and calculating indentation.

public process([int $indent = null ]) : mixed
Parameters
$indent : int = null

The indention level of the tasks.

Return values
mixed

recurs()

Returns whether this task is a recurring task.

public recurs() : bool
Return values
bool

True if this is a recurring task.

reset()

Resets the tasks iterator.

public reset() : mixed

Call this each time before looping through the tasks.

Tags
see
each()
Return values
mixed

save()

Saves this task in the storage backend.

public save() : mixed
Tags
throws
Nag_Exception
Return values
mixed

sort()

Sorts sub tasks by the given criteria.

public sort(string $sortby, int $sortdir, string $altsortby) : mixed
Parameters
$sortby : string

The field by which to sort (Nag::SORT_PRIORITY, Nag::SORT_NAME Nag::SORT_DUE, Nag::SORT_COMPLETION).

$sortdir : int

The direction by which to sort (Nag::SORT_ASCEND, Nag::SORT_DESCEND).

$altsortby : string

The secondary sort field.

Return values
mixed

synchronizeTags()

Syncronizes tags from the tagging backend with the task storage backend, if necessary.

public synchronizeTags(array<string|int, mixed> $tags) : mixed
Parameters
$tags : array<string|int, mixed>

Tags from the tagging backend.

Return values
mixed

toAlarm()

Returns an alarm hash of this task suitable for Horde_Alarm.

public toAlarm([string $user = null ][, Prefs $prefs = null ]) : array<string|int, mixed>
Parameters
$user : string = null

The user to return alarms for.

$prefs : Prefs = null

A Prefs instance.

Return values
array<string|int, mixed>

Alarm hash or null.

toASTask()

Create an AS message from this task

public toASTask([array<string|int, mixed> $options = array() ]) : Horde_ActiveSync_Message_Task
Parameters
$options : array<string|int, mixed> = array()

Options:

  • protocolversion: (float) The EAS version to support DEFAULT: 2.5
  • bodyprefs: (array) A BODYPREFERENCE array. DEFAULT: none (No body prefs enforced).
  • truncation: (integer) Truncate event body to this length DEFAULT: none (No truncation).
Return values
Horde_ActiveSync_Message_Task

toggleComplete()

Toggles completion status of this task. Moves a recurring task to the next occurence on completion. Enforces the rule that sub tasks must be completed before parent tasks.

public toggleComplete([mixed $ignore_children = false ]) : mixed
Parameters
$ignore_children : mixed = false
Return values
mixed

toHash()

Returns a hash representation for this task.

public toHash() : array<string|int, mixed>
Return values
array<string|int, mixed>

A task hash.

toiCalendar()

Exports this task in iCalendar format.

public toiCalendar(Horde_Icalendar $calendar) : Horde_Icalendar_Vtodo
Parameters
$calendar : Horde_Icalendar

A Horde_Icalendar object that acts as the container.

Return values
Horde_Icalendar_Vtodo

A vtodo component of this task.

toJson()

Returns a simple object suitable for json transport representing this task.

public toJson([bool $full = false ][, string $time_format = 'H:i' ]) : object
Parameters
$full : bool = false

Whether to return all task details.

$time_format : string = 'H:i'

The date() format to use for time formatting.

Return values
object

A simple object.

treeIcons()

Returns the HTML code for any tree icons, when displaying this task in a tree view.

public treeIcons() : string
Return values
string

The HTML code for necessary tree icons.

Search results