API Documentation
\
Nag
Backup

\Nag_Api

Nag external API interface.

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

Summary

Methods
Properties
Constants
ajaxDefaults()
listTasks()
listTasklists()
getTasklist()
addTasklist()
updateTasklist()
updateAttendee()
deleteTasklist()
getDisplayedTasklists()
setDisplayedTasklists()
modified()
browse()
put()
path_delete()
listUids()
listBy()
getChanges()
getChangesByModSeq()
getActionTimestamp()
getHighestModSeq()
import()
addTask()
quickAdd()
toggleCompletion()
export()
getTask()
exportTasklist()
delete()
deleteTask()
replace()
updateTask()
listCostObjects()
updateCostObject()
listTimeObjectCategories()
listTimeObjects()
saveTimeObject()
sources()
getDefaultShare()
listTagInfo()
searchTags()
No public properties found
No constants found
No protected methods found
$_links
N/A
No private methods found
No private properties found
N/A

Properties

$_links

$_links : array

Links.

Type

array

Methods

ajaxDefaults()

ajaxDefaults() : array

Returns a number of defaults necessary for the ajax view.

Returns

array —

A hash with default values.

listTasks()

listTasks(\arary  $options = array()) : array

Retrieves the current user's task list from storage.

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

Parameters

\arary $options

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'];

Returns

array —

An array of the requested tasks.

listTasklists()

listTasklists(boolean  $owneronly = false, integer  $permission = \Horde_Perms::SHOW, boolean  $smart = true) : array

Returns a list of task lists.

Parameters

boolean $owneronly

Only return tasklists that this user owns? Defaults to false.
integer $permission

The permission to filter tasklists by.
boolean $smart

Include smart tasklists in results.

Returns

array —

The task lists.

getTasklist()

getTasklist(string  $name) : \Horde_Share_Object

Returns a task list.

Parameters

string $name

A task list name.

Returns

\Horde_Share_Object —

The task list.

addTasklist()

addTasklist(string  $name, string  $description = '', string  $color = '', array  $params = array()) : string

Adds a new task list.

Parameters

string $name

Task list name.
string $description

Task list description.
string $color

Task list color.
array $params

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).

Returns

string —

The new tasklist's id.

updateTasklist()

updateTasklist(string  $name, array  $info)

Updates an existing task list.

Parameters

string $name

A task list name.
array $info

Hash with task list information.

updateAttendee()

updateAttendee(\Horde_Icalendar_Vtodo  $response, string  $sender = null)

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

Parameters

\Horde_Icalendar_Vtodo $response

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.
string $sender

The email address of the person initiating the update. Attendees are only updated if this address matches.

Throws

\Nag_Exception,

Horde_Exception_PermissionDenied

deleteTasklist()

deleteTasklist(string  $id)

Deletes a task list.

Parameters

string $id

A task list id.

getDisplayedTasklists()

getDisplayedTasklists() : array

Returns the displayed task lists.

Returns

array —

Displayed tasklists.

setDisplayedTasklists()

setDisplayedTasklists(array  $list)

Sets the displayed task lists.

Parameters

array $list

Displayed tasklists.

modified()

modified(string  $uid, string  $tasklist = null) : integer

Returns the last modification timestamp of a given uid.

Parameters

string $uid

The uid to look for.
string $tasklist

The tasklist to look in.

Returns

integer —

The timestamp for the last modification of $uid.

browse()

browse(string  $path = '', array  $properties = array()) : array

Browse through Nag's object tree.

Parameters

string $path

The level of the tree to browse.
array $properties

The item properties to return. Defaults to 'name', 'icon', and 'browseable'.

Returns

array —

The contents of $path

put()

put(string  $path, string  $content, string  $content_type) : array

Saves a file into the Nag tree.

Parameters

string $path

The path where to PUT the file.
string $content

The file content.
string $content_type

The file's content type.

Returns

array —

The event UIDs

path_delete()

path_delete(string  $path) : string

Deletes a file from the Nag tree.

Parameters

string $path

The path to the file.

Throws

\Nag_Exception

Returns

string —

The event's UID

listUids()

listUids(mixed  $tasklists = null) : array

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

Parameters

mixed $tasklists

The tasklist or an array of taskslists to list.

Throws

\Horde_Exception_PermissionDenied
\Nag_Exception

Returns

array —

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

listBy()

listBy(string  $action, integer  $timestamp, string  $tasklist = null, integer  $end = null, boolean  $isModSeq = false) : array

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

Parameters

string $action

The action to check for - add, modify, or delete.
integer $timestamp

The time to start the search.
string $tasklist

The tasklist to be used. If 'null', the user's default tasklist will be used.
integer $end

The optional ending timestamp.
boolean $isModSeq

If true, $timestamp and $end are modification sequences and not timestamps. @since 4.1.1

Throws

\Horde_History_Exception
\InvalidArgumentException

Returns

array —

An array of UIDs matching the action and time criteria.

getChanges()

getChanges(integer  $start, integer  $end, boolean  $isModSeq = false, string  $tasklist = null) : array

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

Parameters

integer $start

The starting timestamp
integer $end

The ending timestamp.
boolean $isModSeq

If true, $timestamp and $end are modification sequences and not timestamps. @since 4.1.1
string $tasklist

The sources to check. @since 4.2.0

Returns

array —

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

getChangesByModSeq()

getChangesByModSeq(integer  $start, integer  $end, string  $tasklist = null) : array

Return all changes occuring between the specified modification sequences.

Parameters

integer $start

The starting modseq.
integer $end

The ending modseq.
string $tasklist

The sources to check. @since 4.2.0

Returns

array —

The changes @see getChanges()

getActionTimestamp()

getActionTimestamp(string  $uid, string  $action, string  $tasklist = null, boolean  $modSeq = false) : integer

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

Parameters

string $uid

The uid to look for.
string $action

The action to check for - add, modify, or delete.
string $tasklist

The tasklist to be used. If 'null', the user's default tasklist will be used.
boolean $modSeq

Request a modification sequence instead of a timestamp. @since 4.1.1

Throws

\InvalidArgumentException
\Horde_Exception_PermissionDenied

Returns

integer —

The timestamp for this action.

getHighestModSeq()

getHighestModSeq(string  $id = null) : integer

Return the largest modification sequence from the history backend.

Parameters

string $id

Limit the check to this tasklist. @since 4.2.0

Returns

integer —

The modseq.

import()

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

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

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

string $content

The content of the task.
string $contentType

What format is the data in? Currently supports: text/calendar text/x-vcalendar
string $tasklist

The tasklist into which the task will be imported. If 'null', the user's default tasklist will be used.

Returns

string —

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

addTask()

addTask(array  $task)

Adds a task.

Parameters

array $task

A hash with task information.

Throws

\Horde_Exception_PermissionDenied

quickAdd()

quickAdd(string  $text, string  $tasklist = null) : array

Imports one or more tasks parsed from a string.

Parameters

string $text

The text to parse into
string $tasklist

The tasklist into which the task will be imported. If 'null', the user's default tasklist will be used.

Throws

\Horde_Exception_PermissionDenied

Returns

array —

The UIDs of all tasks that were added.

toggleCompletion()

toggleCompletion(string  $task_id, string  $tasklist_id) : boolean|string

Toggles the task completion flag.

Parameters

string $task_id

The task ID.
string $tasklist_id

The tasklist that contains the task.

Returns

boolean|string —

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

export()

export(string  $uid, string  $contentType, array  $options = array()) : string

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

Parameters

string $uid

Identify the task to export.
string $contentType

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.
array $options

Any additional options for the exporter.

Returns

string —

The requested data.

getTask()

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

Returns a task object.

Parameters

string $tasklist

A tasklist id.
string $id

A task id.

Returns

\Nag_Task —

The matching task object.

exportTasklist()

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

Exports a tasklist in the requested content type.

Parameters

string $tasklist

The tasklist to export.
string $contentType

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)

Returns

string —

The iCalendar representation of the tasklist.

delete()

delete(string|array  $uid) : boolean

Deletes a task identified by UID.

Parameters

string|array $uid

Identify the task to delete, either a single UID or an array.

Returns

boolean —

Success or failure.

deleteTask()

deleteTask(string  $tasklist, string  $id)

Deletes a task identified by tasklist and ID.

Parameters

string $tasklist

A tasklist id.
string $id

A task id.

replace()

replace(string  $uid, string  $content, string  $contentType) : boolean

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

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

string $uid

Identify the task to replace.
string $content

The content of the task.
string $contentType

What format is the data in? Currently supports:

  • text/x-vcalendar
  • text/calendar

Returns

boolean —

Success or failure.

updateTask()

updateTask(string  $tasklist, string  $id, array  $task)

Changes a task identified by tasklist and ID.

Parameters

string $tasklist

A tasklist id.
string $id

A task id.
array $task

A hash with overwriting task information.

listCostObjects()

listCostObjects(array  $criteria)

CostObject API: Lists active tasks as cost objects.

Parameters

array $criteria

Filter attributes

updateCostObject()

updateCostObject(string  $id, array  $data)

CostObject API: Update a single costobject.

Parameters

string $id

The task id.
array $data

The data to update. Currently support: -: hours The amount of hours to add to the existing actual hours.

listTimeObjectCategories()

listTimeObjectCategories()

listTimeObjects()

listTimeObjects(array  $categories, mixed  $start, mixed  $end)

Lists active tasks as time objects.

Parameters

array $categories

The time categories (from listTimeObjectCategories) to list.
mixed $start

The start date of the period.
mixed $end

The end date of the period.

saveTimeObject()

saveTimeObject(array  $timeobject)

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

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

Parameters

array $timeobject

A time object hash.

Throws

\Nag_Exception

sources()

sources(boolean  $writeable = false, boolean  $sync_only = false) : array

Returns a list of available sources.

Parameters

boolean $writeable

If true, limits to writeable sources.
boolean $sync_only

Only include synchable address books.

Returns

array —

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

getDefaultShare()

getDefaultShare() : string

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

Returns

string —

UID.

listTagInfo()

listTagInfo(array  $tags = null,   $user = null) : array

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

Parameters

array $tags

An optional array of tag_ids. If omitted, all tags will be included.
$user

Returns

array —

An array containing tag_name, and total

searchTags()

searchTags(array  $names, integer  $max = 10, integer  $from, string  $resource_type = '', string  $user = null, boolean  $raw = false) : array

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

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

Parameters

array $names

An array of tag_names to search for.
integer $max

The maximum number of resources to return.
integer $from

The number of the resource to start with.
string $resource_type

The resource type [bookmark, '']
string $user

Restrict results to resources owned by $user.
boolean $raw

Return the raw data?

Returns

array —

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.