ConnectByRestPlugin

This plugin wraps functions from the TWiki API in REST functions. The intention is to offer external applications access to TWiki by implementing a REST interface.

The functions of this plugin include:

  • create and update topics
  • read topics and meta data
  • read and update form fields of a topic

The intention is to enable other web based applications to connect to TWiki. By calling the REST functions of this plugins applications can read, change or create topics in TWiki.

Topic content sent to the plugin for update or creation has to obey TWiki syntax - especially when providing special meta data like form fields, permissions, etc.

Calling the REST functions always requires successful authorization.

REST Functions

Function Readtopic

Description

This function returns the content of a topic as a string. It reads the topic that was specified in the parameter topic and returns the topic text as a string.

Parameters

Parameter Direction Type Description
username in string  
password in string  
topic in string use full topic name: web.topic
text out string topic text

Security

  • The function checks if the given user has read access to the topic.

Function Getmetastring

Description

This function returns the meta data of a topic as a string. It reads the topic that was specified in the parameter topic and uses the stringify method of the Meta-Object to return the complete meta data as a string

Parameters

Parameter Direction Type Description
username in string  
password in string  
topic in string use full topic name: web.topic
metastring out string full meta data

Security

  • The function checks if the given user has read access to the topic.

Function Updateformfield

Description

The function updates a single form field attached to a topic.

Parameters

ParameterSorted ascending Direction Type Description
formfield in string form field name
newval in string new form field value
password in string  
topic in string use full topic name: web.topic
username in string  

Security

  • The functions checks if the given user has write access to the topic.

Function Savetopic

Description

The function creates a new topic or updates an existing topic in the specified web.

Parameters

Parameter Direction Type Description
username in string  
password in string  
topic in string name of the new topic; use full topic name: web.topic
text in string topic content, including meta data

Security

  • The functions checks if the given user has write access to the web.

Syntax Rules

Examples

Plugin Settings

Plugin settings are stored as preferences variables. To reference a plugin setting write %<plugin>_<setting>%, i.e. %NEWPLUGIN_SHORTDESCRIPTION%

  • One line description, is shown in the TextFormattingRules topic:
    • Set SHORTDESCRIPTION = Call TWiki API functions via REST calls

  • Debug plugin: (See output in data/debug.txt)
    • Set DEBUG = 0

Plugin Installation Instructions

Note: You do not need to install anything on the browser to use this plugin. The following instructions are for the administrator who installs the plugin on the TWiki server.

  • Download the ZIP file from the Plugin Home (see below)
  • Unzip ConnectByRestPlugin.zip in your twiki installation directory. Content:
File: Description:
data/TWiki/ConnectByRestPlugin.txt Plugin topic
lib/TWiki/Plugins/ConnectByRestPlugin.pm Plugin Perl module
data/Sandbox/ConnectByRestPluginTest.txt Plugin test topic

  • Configure the Plugin:
    • TWiki 4.0 and up: Run the configure script to enable the Plugin
    • Change the Plugin settings as needed
  • Test if the installation was successful:
    • enter samples here

Plugin Info

  • One line description
    • Set SHORTDESCRIPTION = Call TWiki API functions via TWiki REST functions.

Plugin Author: TWiki:Main/MichaelGulitz
Copyright: © 2011, TWiki:Main/MichaelGulitz
License: GPL (GNU General Public License)
Plugin Version: 2012-12-17 (V1.000)
Change History:
2012-12-17: Update Comment regarding DatePickerPlugin
2010-05-05: Initial version
TWiki Dependency: $TWiki::Plugins::VERSION 1.1
CPAN Dependencies: none
Other Dependencies: none
Perl Version: 5.005
Benchmarks: GoodStyle nn%, FormattedSearch nn%, ConnectByRestPlugin nn%
Plugin Home: http://TWiki.org/cgi-bin/view/Plugins/ConnectByRestPlugin
Feedback: http://TWiki.org/cgi-bin/view/Plugins/ConnectByRestPluginDev
Appraisal: http://TWiki.org/cgi-bin/view/Plugins/ConnectByRestPluginAppraisal

Related Topics: TWikiPlugins, DeveloperDocumentationCategory, AdminDocumentationCategory, TWikiPreferences