Documentation

Nag_Api extends Horde_Registry_Api
in package

Nag

Nag external API interface.

This file defines Nag's external API interface. Other applications can interact with Nag through this API.

$_links : array<string|int, mixed>: Links.
addTask() : mixed: Adds a task.
addTasklist() : string: Adds a new task list.
ajaxDefaults() : array<string|int, mixed>: Returns a number of defaults necessary for the ajax view.
browse() : array<string|int, mixed>: Browse through Nag's object tree.
delete() : bool: Deletes a task identified by UID.
deleteTask() : mixed: Deletes a task identified by tasklist and ID.
deleteTasklist() : mixed: Deletes a task list.
export() : string: Exports a task, identified by UID, in the requested content type.
exportTasklist() : string: Exports a tasklist in the requested content type.
getActionTimestamp() : int: Returns the timestamp of an operation for a given uid an action.
getChanges() : array<string|int, mixed>: Method for obtaining all server changes between two timestamps. Basically a wrapper around listBy(), but returns an array containing all adds, edits and deletions.
getChangesByModSeq() : array<string|int, mixed>: Return all changes occuring between the specified modification sequences.
getDefaultShare() : string: Retrieve the UID for the current user's default tasklist.
getDisplayedTasklists() : array<string|int, mixed>: Returns the displayed task lists.
getHighestModSeq() : int: Return the largest modification sequence from the history backend.
getTask() : Nag_Task: Returns a task object.
getTasklist() : Horde_Share_Object: Returns a task list.
import() : string: Imports one or more tasks represented in the specified content type.
listBy() : array<string|int, mixed>: Returns an array of UIDs for tasks that have had $action happen since $timestamp.
listCostObjects() : mixed: CostObject API: Lists active tasks as cost objects.
listTagInfo() : array<string|int, mixed>: Retrieve the list of used tag_names, tag_ids and the total number of resources that are linked to that tag.
listTasklists() : array<string|int, mixed>: Returns a list of task lists.
listTasks() : array<string|int, mixed>: Retrieves the current user's task list from storage.
listTimeObjectCategories() : mixed
listTimeObjects() : mixed: Lists active tasks as time objects.
listUids() : array<string|int, mixed>: Returns an array of UIDs for all tasks that the current user is authorized to see.
modified() : int: Returns the last modification timestamp of a given uid.
path_delete() : string: Deletes a file from the Nag tree.
put() : array<string|int, mixed>: Saves a file into the Nag tree.
quickAdd() : array<string|int, mixed>: Imports one or more tasks parsed from a string.
replace() : bool: Replaces the task identified by UID with the content represented in the specified content type.
saveTimeObject() : mixed: Saves properties of a time object back to the task that it represents.
searchTags() : array<string|int, mixed>: SearchTags API: Returns an application-agnostic array (useful for when doing a tag search across multiple applications)
setDisplayedTasklists() : mixed: Sets the displayed task lists.
sources() : array<string|int, mixed>: Returns a list of available sources.
toggleCompletion() : bool|string: Toggles the task completion flag.
updateAttendee() : mixed: Updates an attendee's response status for a specified task assignment.
updateCostObject() : mixed: CostObject API: Update a single costobject.
updateTask() : mixed: Changes a task identified by tasklist and ID.
updateTasklist() : mixed: Updates an existing task list.

$_links

Links.


    protected
        array<string|int, mixed>
    $_links
     = array('show' => '%application%/view.php?tasklist=|tasklist|&task=|task|&uid=|uid|')

addTask()

Adds a task.


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

Parameters

$task : array<string|int, mixed>: A hash with task information.

Return values

mixed —

addTasklist()

Adds a new task list.


    public
                    addTasklist(string $name[, string $description = '' ][, string $color = '' ][, array<string|int, mixed> $params = array() ]) : string

Parameters

$name : string

Task list name.

$description : string = ''

Task list description.

$color : string = ''

Task list color.

$params : array<string|int, mixed> = array()

Any addtional parameters needed. @since 4.2.1

synchronize: (boolean) If true, add task list to the list of task lists to syncronize. DEFAULT: false (do not add to the list).

Return values

string —

The new tasklist's id.

ajaxDefaults()

Returns a number of defaults necessary for the ajax view.


    public
                    ajaxDefaults() : array<string|int, mixed>

Return values

array<string|int, mixed> —

A hash with default values.

browse()

Browse through Nag's object tree.


    public
                    browse([string $path = '' ][, array<string|int, mixed> $properties = array() ]) : array<string|int, mixed>

Parameters

$path : string = '': The level of the tree to browse.
$properties : array<string|int, mixed> = array(): The item properties to return. Defaults to 'name', 'icon', and 'browseable'.

Return values

array<string|int, mixed> —

The contents of $path

delete()

Deletes a task identified by UID.


    public
                    delete(string|array<string|int, mixed> $uid) : bool

Parameters

$uid : string|array<string|int, mixed>: Identify the task to delete, either a single UID or an array.

Return values

bool —

Success or failure.

deleteTask()

Deletes a task identified by tasklist and ID.


    public
                    deleteTask(string $tasklist, string $id) : mixed

Parameters

$tasklist : string: A tasklist id.
$id : string: A task id.

Return values

mixed —

deleteTasklist()

Deletes a task list.


    public
                    deleteTasklist(string $id) : mixed

Parameters

$id : string: A task list id.

Return values

mixed —

export()

Exports a task, identified by UID, in the requested content type.


    public
                    export(string $uid, string $contentType[, array<string|int, mixed> $options = array() ]) : string

Parameters

$uid : string

Identify the task to export.

$contentType : string

What format should the data be in? A string with one of:

text/calendar: iCalendar 2.0. Recommended as this is specified in RFC 2445.
text/x-vcalendar: vCalendar 1.0 format. Still in wide use.
activesync: Horde_ActiveSync_Message_Task.
raw: Nag_Task.

$options : array<string|int, mixed> = array()

Any additional options for the exporter.

Return values

string —

The requested data.

exportTasklist()

Exports a tasklist in the requested content type.


    public
                    exportTasklist(string $tasklist, string $contentType) : string

Parameters

$tasklist : string

The tasklist to export.

$contentType : string

What format should the data be in? A string with one of:

text/calendar (VCALENDAR 2.0. Recommended as
               this is specified in rfc2445)
text/x-vcalendar (old VCALENDAR 1.0 format.
                 Still in wide use)

Return values

string —

The iCalendar representation of the tasklist.

getActionTimestamp()

Returns the timestamp of an operation for a given uid an action.


    public
                    getActionTimestamp(string $uid, string $action[, string $tasklist = null ][, bool $modSeq = false ]) : int

Parameters

$uid : string: The uid to look for.
$action : string: The action to check for - add, modify, or delete.
$tasklist : string = null: The tasklist to be used. If 'null', the user's default tasklist will be used.
$modSeq : bool = false: Request a modification sequence instead of a timestamp. @since 4.1.1

Return values

int —

The timestamp for this action.

getChanges()

Method for obtaining all server changes between two timestamps. Basically a wrapper around listBy(), but returns an array containing all adds, edits and deletions.


    public
                    getChanges(int $start, int $end[, bool $isModSeq = false ][, string $tasklist = null ]) : array<string|int, mixed>

Parameters

$start : int: The starting timestamp
$end : int: The ending timestamp.
$isModSeq : bool = false: If true, $timestamp and $end are modification sequences and not timestamps. @since 4.1.1
$tasklist : string = null: The sources to check. @since 4.2.0

Return values

array<string|int, mixed> —

An hash with 'add', 'modify' and 'delete' arrays.

getChangesByModSeq()

Return all changes occuring between the specified modification sequences.


    public
                    getChangesByModSeq(int $start, int $end[, string $tasklist = null ]) : array<string|int, mixed>

Parameters

$start : int: The starting modseq.
$end : int: The ending modseq.
$tasklist : string = null: The sources to check. @since 4.2.0

Return values

array<string|int, mixed> —

The changes @see getChanges()

getDefaultShare()

Retrieve the UID for the current user's default tasklist.


    public
                    getDefaultShare() : string

Return values

string —

UID.

getDisplayedTasklists()

Returns the displayed task lists.


    public
                    getDisplayedTasklists() : array<string|int, mixed>

Return values

array<string|int, mixed> —

Displayed tasklists.

getHighestModSeq()

Return the largest modification sequence from the history backend.


    public
                    getHighestModSeq([string $id = null ]) : int

Parameters

$id : string = null: Limit the check to this tasklist. @since 4.2.0

Return values

int —

The modseq.

getTask()

Returns a task object.


    public
                    getTask(string $tasklist, string $id) : Nag_Task

Parameters

$tasklist : string: A tasklist id.
$id : string: A task id.

Return values

Nag_Task —

The matching task object.

getTasklist()

Returns a task list.


    public
                    getTasklist(string $name) : Horde_Share_Object

Parameters

$name : string: A task list name.

Return values

Horde_Share_Object —

The task list.

import()

Imports one or more tasks represented in the specified content type.


    public
                    import(string $content, string $contentType[, string $tasklist = null ]) : string

If a UID is present in the content and the task is already in the database, a replace is performed rather than an add.

Parameters

$content : string: The content of the task.
$contentType : string: What format is the data in? Currently supports: text/calendar text/x-vcalendar
$tasklist : string = null: The tasklist into which the task will be imported. If 'null', the user's default tasklist will be used.

Return values

string —

The new UID on one import, an array of UIDs on multiple imports,

listBy()

Returns an array of UIDs for tasks that have had $action happen since $timestamp.


    public
                    listBy(string $action, int $timestamp[, string $tasklist = null ][, int $end = null ][, bool $isModSeq = false ]) : array<string|int, mixed>

Parameters

$action : string: The action to check for - add, modify, or delete.
$timestamp : int: The time to start the search.
$tasklist : string = null: The tasklist to be used. If 'null', the user's default tasklist will be used.
$end : int = null: The optional ending timestamp.
$isModSeq : bool = false: If true, $timestamp and $end are modification sequences and not timestamps. @since 4.1.1

Return values

array<string|int, mixed> —

An array of UIDs matching the action and time criteria.

listCostObjects()

CostObject API: Lists active tasks as cost objects.


    public
                    listCostObjects(array<string|int, mixed> $criteria) : mixed

Parameters

$criteria : array<string|int, mixed>: Filter attributes

Return values

mixed —

listTagInfo()

Retrieve the list of used tag_names, tag_ids and the total number of resources that are linked to that tag.


    public
                    listTagInfo([array<string|int, mixed> $tags = null ][, mixed $user = null ]) : array<string|int, mixed>

Parameters

$tags : array<string|int, mixed> = null: An optional array of tag_ids. If omitted, all tags will be included.
$user : mixed = null

Return values

array<string|int, mixed> —

An array containing tag_name, and total

listTasklists()

Returns a list of task lists.


    public
                    listTasklists([bool $owneronly = false ][, int $permission = Horde_Perms::SHOW ][, bool $smart = true ]) : array<string|int, mixed>

Parameters

$owneronly : bool = false: Only return tasklists that this user owns? Defaults to false.
$permission : int = Horde_Perms::SHOW: The permission to filter tasklists by.
$smart : bool = true: Include smart tasklists in results.

Return values

array<string|int, mixed> —

The task lists.

listTasks()

Retrieves the current user's task list from storage.


    public
                    listTasks([arary $options = array() ]) : array<string|int, mixed>

This function will also sort the resulting list, if requested.

Parameters

$options : arary = array()

Options array:

altsortby: (string) The secondary sort field. Same values as sortdir. DEFAULT: altsortby pref is used.
completed: (integer) Which task to retrieve. DEFAULT: show_completed pref is used.
sortby: (string) A Nag::SORT_* constant for the field to sort by. DEFAULT: sortby pref is used.
sortdir: (string) Direction of sort. NAG::SORT_ASCEND or NAG::SORT_DESCEND. DEFAULT: sortdir pref is used.
include_tags: (boolean) Autoload all tags. DEFAULT: false (Tags are lazy loaded as needed.)
json: (boolean) Return data as JSON. DEFAULT: false (Data is returned as Nag_Task)
tasklists: (array) An array of tasklists to include. DEFAULT: Use $GLOBALS['display_tasklists'];

Return values

array<string|int, mixed> —

An array of the requested tasks.

listTimeObjectCategories()


    public
                    listTimeObjectCategories() : mixed

Return values

mixed —

listTimeObjects()

Lists active tasks as time objects.


    public
                    listTimeObjects(array<string|int, mixed> $categories, mixed $start, mixed $end) : mixed

Parameters

$categories : array<string|int, mixed>: The time categories (from listTimeObjectCategories) to list.
$start : mixed: The start date of the period.
$end : mixed: The end date of the period.

Return values

mixed —

listUids()

Returns an array of UIDs for all tasks that the current user is authorized to see.


    public
                    listUids([mixed $tasklists = null ]) : array<string|int, mixed>

Parameters

$tasklists : mixed = null: The tasklist or an array of taskslists to list.

Return values

array<string|int, mixed> —

An array of UIDs for all tasks the user can access.

modified()

Returns the last modification timestamp of a given uid.


    public
                    modified(string $uid[, string $tasklist = null ]) : int

Parameters

$uid : string: The uid to look for.
$tasklist : string = null: The tasklist to look in.

Return values

int —

The timestamp for the last modification of $uid.

path_delete()

Deletes a file from the Nag tree.


    public
                    path_delete(string $path) : string

Parameters

$path : string: The path to the file.

Return values

string —

The event's UID

put()

Saves a file into the Nag tree.


    public
                    put(string $path, string $content, string $content_type) : array<string|int, mixed>

Parameters

$path : string: The path where to PUT the file.
$content : string: The file content.
$content_type : string: The file's content type.

Return values

array<string|int, mixed> —

The event UIDs

quickAdd()

Imports one or more tasks parsed from a string.


    public
                    quickAdd(string $text[, string $tasklist = null ]) : array<string|int, mixed>

Parameters

$text : string: The text to parse into
$tasklist : string = null: The tasklist into which the task will be imported. If 'null', the user's default tasklist will be used.

Return values

array<string|int, mixed> —

The UIDs of all tasks that were added.

replace()

Replaces the task identified by UID with the content represented in the specified content type.


    public
                    replace(string $uid, string $content, string $contentType) : bool

If you want to replace multiple tasks with the UID specified in the VCALENDAR data, you may use $this->import instead. This automatically does a replace if existings UIDs are found.

Parameters

$uid : string

Identify the task to replace.

$content : string

The content of the task.

$contentType : string

What format is the data in? Currently supports:

text/x-vcalendar
text/calendar

Return values

bool —

Success or failure.

saveTimeObject()

Saves properties of a time object back to the task that it represents.


    public
                    saveTimeObject(array<string|int, mixed> $timeobject) : mixed

At the moment only the title, description and due date are saved.

Parameters

$timeobject : array<string|int, mixed>: A time object hash.

Return values

mixed —

searchTags()

SearchTags API: Returns an application-agnostic array (useful for when doing a tag search across multiple applications)


    public
                    searchTags(array<string|int, mixed> $names[, int $max = 10 ], int $from[, string $resource_type = '' ][, string $user = null ][, bool $raw = false ]) : array<string|int, mixed>

The 'raw' results array can be returned instead by setting $raw = true.

Parameters

$names : array<string|int, mixed>: An array of tag_names to search for.
$max : int = 10: The maximum number of resources to return.
$from : int: The number of the resource to start with.
$resource_type : string = '': The resource type [bookmark, '']
$user : string = null: Restrict results to resources owned by $user.
$raw : bool = false: Return the raw data?

Return values

array<string|int, mixed> —

An array of results:

 'title'    - The title for this resource.
 'desc'     - A terse description of this resource.
 'view_url' - The URL to view this resource.
 'app'      - The Horde application this resource belongs to.
 'icon'     - URL to an image.

setDisplayedTasklists()

Sets the displayed task lists.


    public
                    setDisplayedTasklists(array<string|int, mixed> $list) : mixed

Parameters

$list : array<string|int, mixed>: Displayed tasklists.

Return values

mixed —

sources()

Returns a list of available sources.


    public
                    sources([bool $writeable = false ][, bool $sync_only = false ]) : array<string|int, mixed>

Parameters

$writeable : bool = false: If true, limits to writeable sources.
$sync_only : bool = false: Only include synchable address books.

Return values

array<string|int, mixed> —

An array of the available sources. Keys are source IDs, values are source titles.

toggleCompletion()

Toggles the task completion flag.


    public
                    toggleCompletion(string $task_id, string $tasklist_id) : bool|string

Parameters

$task_id : string: The task ID.
$tasklist_id : string: The tasklist that contains the task.

Return values

bool|string —

True if the task has been toggled, a due date if there are still incomplete recurrences, otherwise false.

updateAttendee()

Updates an attendee's response status for a specified task assignment.


    public
                    updateAttendee(Horde_Icalendar_Vtodo $response[, string $sender = null ]) : mixed

Parameters

$response : Horde_Icalendar_Vtodo: A Horde_Icalendar_Vtodo object, with a valid UID attribute that points to an existing task. This is typically the vTodo portion of an iTip task-request response, with the attendee's response in an ATTENDEE parameter.
$sender : string = null: The email address of the person initiating the update. Attendees are only updated if this address matches.

Return values

mixed —

updateCostObject()

CostObject API: Update a single costobject.


    public
                    updateCostObject(string $id, array<string|int, mixed> $data) : mixed

Parameters

$id : string: The task id.
$data : array<string|int, mixed>: The data to update. Currently support: -: hours The amount of hours to add to the existing actual hours.

Return values

mixed —

updateTask()

Changes a task identified by tasklist and ID.


    public
                    updateTask(string $tasklist, string $id, array<string|int, mixed> $task) : mixed

Parameters

$tasklist : string: A tasklist id.
$id : string: A task id.
$task : array<string|int, mixed>: A hash with overwriting task information.

Return values

mixed —

updateTasklist()

Updates an existing task list.


    public
            static        updateTasklist(string $name, array<string|int, mixed> $info) : mixed

Parameters

$name : string: A task list name.
$info : array<string|int, mixed>: Hash with task list information.

Return values

mixed —

Nag_Api extends Horde_Registry_Api in package Nag

Table of Contents

Properties

$_links

Methods

addTask()

Parameters

Tags

Return values

addTasklist()

Parameters

Return values

ajaxDefaults()

Return values

browse()

Parameters

Return values

delete()

Parameters

Return values

deleteTask()

Parameters

Return values

deleteTasklist()

Parameters

Return values

export()

Parameters

Return values

exportTasklist()

Parameters

Return values

getActionTimestamp()

Parameters

Tags

Return values

getChanges()

Parameters

Return values

getChangesByModSeq()

Parameters

Tags

Return values

getDefaultShare()

Tags

Return values

getDisplayedTasklists()

Return values

getHighestModSeq()

Parameters

Tags

Return values

getTask()

Parameters

Return values

getTasklist()

Parameters

Return values

import()

Parameters

Return values

listBy()

Parameters

Tags

Return values

listCostObjects()

Parameters

Tags

Return values

listTagInfo()

Parameters

Return values

listTasklists()

Parameters

Return values

listTasks()

Parameters

Return values

listTimeObjectCategories()

Return values

Nag_Api extends Horde_Registry_Api
in package

Nag