PHP Class Nag_Api, horde

This file defines Nag's external API interface. Other applications can interact with Nag through this API.
Inheritance: extends Horde_Registry_Api
Show file Open project: horde/horde

Protected Properties

Property Type Description
$_links array Links.

Public Methods

Method Description
addTask ( array $task ) Adds a task.
addTasklist ( string $name, string $description = '', string $color = '', array $params = [] ) : string Adds a new task list.
ajaxDefaults ( ) : array Returns a number of defaults necessary for the ajax view.
browse ( string $path = '', array $properties = [] ) : array Browse through Nag's object tree.
delete ( string | array $uid ) : boolean Deletes a task identified by UID.
deleteTask ( string $tasklist, string $id ) Deletes a task identified by tasklist and ID.
deleteTasklist ( string $id ) Deletes a task list.
export ( string $uid, string $contentType, array $options = [] ) : string Exports a task, identified by UID, in the requested content type.
exportTasklist ( string $tasklist, string $contentType ) : string Exports a tasklist in the requested content type.
getActionTimestamp ( string $uid, string $action, string $tasklist = null, boolean $modSeq = false ) : integer Returns the timestamp of an operation for a given uid an action.
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.
getChangesByModSeq ( integer $start, integer $end, string $tasklist = null ) : array Return all changes occuring between the specified modification sequences.
getDefaultShare ( ) : string Retrieve the UID for the current user's default tasklist.
getDisplayedTasklists ( ) : array Returns the displayed task lists.
getHighestModSeq ( string $id = null ) : integer Return the largest modification sequence from the history backend.
getTask ( string $tasklist, string $id ) : Nag_Task Returns a task object.
getTasklist ( string $name ) : Horde_Share_Object Returns a task list.
import ( string $content, string $contentType, string $tasklist = null ) : string Imports one or more tasks represented in the specified content type.
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.
listCostObjects ( array $criteria ) CostObject API: Lists active tasks as cost objects.
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.
listTasklists ( boolean $owneronly = false, integer $permission = Horde_Perms::SHOW, boolean $smart = true ) : array Returns a list of task lists.
listTasks ( array $options = [] ) : array Retrieves the current user's task list from storage.
listTimeObjectCategories ( )
listTimeObjects ( array $categories, mixed $start, mixed $end ) Lists active tasks as time objects.
listUids ( mixed $tasklists = null ) : array Returns an array of UIDs for all tasks that the current user is authorized to see.
modified ( string $uid, string $tasklist = null ) : integer Returns the last modification timestamp of a given uid.
path_delete ( string $path ) : string Deletes a file from the Nag tree.
put ( string $path, string $content, string $content_type ) : array Saves a file into the Nag tree.
quickAdd ( string $text, string $tasklist = null ) : array Imports one or more tasks parsed from a string.
replace ( string $uid, string $content, string $contentType ) : boolean Replaces the task identified by UID with the content represented in the specified content type.
saveTimeObject ( array $timeobject ) Saves properties of a time object back to the task that it represents.
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)
setDisplayedTasklists ( array $list ) Sets the displayed task lists.
sources ( boolean $writeable = false, boolean $sync_only = false ) : array Returns a list of available sources.
toggleCompletion ( string $task_id, string $tasklist_id ) : boolean | string Toggles the task completion flag.
updateAttendee ( Horde_Icalendar_Vtodo $response, string $sender = null ) Updates an attendee's response status for a specified task assignment.
updateCostObject ( string $id, array $data ) CostObject API: Update a single costobject.
updateTask ( string $tasklist, string $id, array $task ) Changes a task identified by tasklist and ID.
updateTasklist ( string $name, array $info ) Updates an existing task list.

Method Details

addTask() public method

Adds a task.
public addTask ( array $task )
$task array A hash with task information.

addTasklist() public method

Adds a new task list.
public addTasklist ( string $name, string $description = '', string $color = '', array $params = [] ) : string
$name string Task list name.
$description string Task list description.
$color string Task list color.
$params 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 string The new tasklist's id.

ajaxDefaults() public method

Returns a number of defaults necessary for the ajax view.
public ajaxDefaults ( ) : array
return array A hash with default values.

browse() public method

Browse through Nag's object tree.
public browse ( string $path = '', array $properties = [] ) : array
$path string The level of the tree to browse.
$properties array The item properties to return. Defaults to 'name', 'icon', and 'browseable'.
return array The contents of $path

delete() public method

Deletes a task identified by UID.
public delete ( string | array $uid ) : boolean
$uid string | array Identify the task to delete, either a single UID or an array.
return boolean Success or failure.

deleteTask() public method

Deletes a task identified by tasklist and ID.
public deleteTask ( string $tasklist, string $id )
$tasklist string A tasklist id.
$id string A task id.

deleteTasklist() public method

Deletes a task list.
public deleteTasklist ( string $id )
$id string A task list id.

export() public method

Exports a task, identified by UID, in the requested content type.
public export ( string $uid, string $contentType, array $options = [] ) : string
$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 Any additional options for the exporter.
return string The requested data.

exportTasklist() public method

Exports a tasklist in the requested content type.
public exportTasklist ( string $tasklist, string $contentType ) : string
$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 string The iCalendar representation of the tasklist.

getActionTimestamp() public method

Returns the timestamp of an operation for a given uid an action.
public getActionTimestamp ( string $uid, string $action, string $tasklist = null, boolean $modSeq = false ) : integer
$uid string The uid to look for.
$action string The action to check for - add, modify, or delete.
$tasklist string The tasklist to be used. If 'null', the user's default tasklist will be used.
$modSeq boolean Request a modification sequence instead of a timestamp. @since 4.1.1
return integer The timestamp for this action.

getChanges() public method

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 ( integer $start, integer $end, boolean $isModSeq = false, string $tasklist = null ) : array
$start integer The starting timestamp
$end integer The ending timestamp.
$isModSeq boolean If true, $timestamp and $end are modification sequences and not timestamps. @since 4.1.1
$tasklist string The sources to check. @since 4.2.0
return array An hash with 'add', 'modify' and 'delete' arrays.

getChangesByModSeq() public method

Return all changes occuring between the specified modification sequences.
Since: 4.1.1
public getChangesByModSeq ( integer $start, integer $end, string $tasklist = null ) : array
$start integer The starting modseq.
$end integer The ending modseq.
$tasklist string The sources to check. @since 4.2.0
return array The changes @see getChanges()

getDefaultShare() public method

Retrieve the UID for the current user's default tasklist.
Since: 4.2.0
public getDefaultShare ( ) : string
return string UID.

getDisplayedTasklists() public method

Returns the displayed task lists.
public getDisplayedTasklists ( ) : array
return array Displayed tasklists.

getHighestModSeq() public method

Return the largest modification sequence from the history backend.
Since: 4.1.1
public getHighestModSeq ( string $id = null ) : integer
$id string Limit the check to this tasklist. @since 4.2.0
return integer The modseq.

getTask() public method

Returns a task object.
public getTask ( string $tasklist, string $id ) : Nag_Task
$tasklist string A tasklist id.
$id string A task id.
return Nag_Task The matching task object.

getTasklist() public method

Returns a task list.
public getTasklist ( string $name ) : Horde_Share_Object
$name string A task list name.
return Horde_Share_Object The task list.

import() public method

If a UID is present in the content and the task is already in the database, a replace is performed rather than an add.
public import ( string $content, string $contentType, string $tasklist = null ) : string
$content string The content of the task.
$contentType string What format is the data in? Currently supports: text/calendar text/x-vcalendar
$tasklist string The tasklist into which the task will be imported. If 'null', the user's default tasklist will be used.
return string The new UID on one import, an array of UIDs on multiple imports,

listBy() public method

Returns an array of UIDs for tasks that have had $action happen since $timestamp.
public listBy ( string $action, integer $timestamp, string $tasklist = null, integer $end = null, boolean $isModSeq = false ) : array
$action string The action to check for - add, modify, or delete.
$timestamp integer The time to start the search.
$tasklist string The tasklist to be used. If 'null', the user's default tasklist will be used.
$end integer The optional ending timestamp.
$isModSeq boolean If true, $timestamp and $end are modification sequences and not timestamps. @since 4.1.1
return array An array of UIDs matching the action and time criteria.

listCostObjects() public method

CostObject API: Lists active tasks as cost objects.
public listCostObjects ( array $criteria )
$criteria array Filter attributes

listTagInfo() public method

Retrieve the list of used tag_names, tag_ids and the total number of resources that are linked to that tag.
public listTagInfo ( array $tags = null, $user = null ) : array
$tags array An optional array of tag_ids. If omitted, all tags will be included.
return array An array containing tag_name, and total

listTasklists() public method

Returns a list of task lists.
public listTasklists ( boolean $owneronly = false, integer $permission = Horde_Perms::SHOW, boolean $smart = true ) : array
$owneronly boolean Only return tasklists that this user owns? Defaults to false.
$permission integer The permission to filter tasklists by.
$smart boolean Include smart tasklists in results.
return array The task lists.

listTasks() public method

This function will also sort the resulting list, if requested.
public listTasks ( array $options = [] ) : array
$options 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 array An array of the requested tasks.

listTimeObjectCategories() public method

public listTimeObjectCategories ( )

listTimeObjects() public method

Lists active tasks as time objects.
public listTimeObjects ( array $categories, mixed $start, mixed $end )
$categories array The time categories (from listTimeObjectCategories) to list.
$start mixed The start date of the period.
$end mixed The end date of the period.

listUids() public method

Returns an array of UIDs for all tasks that the current user is authorized to see.
public listUids ( mixed $tasklists = null ) : array
$tasklists mixed The tasklist or an array of taskslists to list.
return array An array of UIDs for all tasks the user can access.

modified() public method

Returns the last modification timestamp of a given uid.
public modified ( string $uid, string $tasklist = null ) : integer
$uid string The uid to look for.
$tasklist string The tasklist to look in.
return integer The timestamp for the last modification of $uid.

path_delete() public method

Deletes a file from the Nag tree.
public path_delete ( string $path ) : string
$path string The path to the file.
return string The event's UID

put() public method

Saves a file into the Nag tree.
public put ( string $path, string $content, string $content_type ) : array
$path string The path where to PUT the file.
$content string The file content.
$content_type string The file's content type.
return array The event UIDs

quickAdd() public method

Imports one or more tasks parsed from a string.
public quickAdd ( string $text, string $tasklist = null ) : array
$text string The text to parse into
$tasklist string The tasklist into which the task will be imported. If 'null', the user's default tasklist will be used.
return array The UIDs of all tasks that were added.

replace() public method

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.
public replace ( string $uid, string $content, string $contentType ) : boolean
$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 boolean Success or failure.

saveTimeObject() public method

At the moment only the title, description and due date are saved.
public saveTimeObject ( array $timeobject )
$timeobject array A time object hash.

searchTags() public method

The 'raw' results array can be returned instead by setting $raw = true.
public searchTags ( array $names, integer $max = 10, integer $from, string $resource_type = '', string $user = null, boolean $raw = false ) : array
$names array An array of tag_names to search for.
$max integer The maximum number of resources to return.
$from integer The number of the resource to start with.
$resource_type string The resource type [bookmark, '']
$user string Restrict results to resources owned by $user.
$raw boolean Return the raw data?
return 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.

setDisplayedTasklists() public method

Sets the displayed task lists.
public setDisplayedTasklists ( array $list )
$list array Displayed tasklists.

sources() public method

Returns a list of available sources.
Since: 4.2.0
public sources ( boolean $writeable = false, boolean $sync_only = false ) : array
$writeable boolean If true, limits to writeable sources.
$sync_only boolean Only include synchable address books.
return array An array of the available sources. Keys are source IDs, values are source titles.

toggleCompletion() public method

Toggles the task completion flag.
public toggleCompletion ( string $task_id, string $tasklist_id ) : boolean | string
$task_id string The task ID.
$tasklist_id string The tasklist that contains the task.
return boolean | string True if the task has been toggled, a due date if there are still incomplete recurrences, otherwise false.

updateAttendee() public method

Updates an attendee's response status for a specified task assignment.
public updateAttendee ( Horde_Icalendar_Vtodo $response, string $sender = null )
$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 The email address of the person initiating the update. Attendees are only updated if this address matches.

updateCostObject() public method

CostObject API: Update a single costobject.
public updateCostObject ( string $id, array $data )
$id string The task id.
$data array The data to update. Currently support: -: hours The amount of hours to add to the existing actual hours.

updateTask() public method

Changes a task identified by tasklist and ID.
public updateTask ( string $tasklist, string $id, array $task )
$tasklist string A tasklist id.
$id string A task id.
$task array A hash with overwriting task information.

updateTasklist() public static method

Updates an existing task list.
public static updateTasklist ( string $name, array $info )
$name string A task list name.
$info array Hash with task list information.

Property Details

$_links protected property

Links.
protected array $_links
return array