Table of Contents
Compatible with DokuWiki
- 2022-07-31 "Igor" unknown
- 2020-07-29 "Hogfather" yes
- 2018-04-22 "Greebo" yes
- 2017-02-19 "Frusterick Manners" yes
Post-hogfather version: https://github.com/turnermm/xcom/archive/refs/heads/ns-ixr.zip
This handles the new code for accessing the XML-RPC client ( not present in
The Dashboard Interface
With this plugin users can conveniently communicate with DokuWiki's xmlrpc library. The user can then communicate with and exchange data between the local wiki and a remote wiki. It can access data on any DokuWiki, including the one which you are currently logged into by treating it as a remote. The xmlrpc library exposes many of the back-end elements of the wiki which may be of use in management.
At its simplest you enter the URL of the remote wiki into the
Remote URL text box, you select a query from the
Select query drop-down menu, and you click
Send query. So, for instance, if you select
getAllPages, the result will be a list of all the pages on the remote wiki. Often, however, queries require an id. For these, you enter the id in the
ID textbox. For example, if you enter a paged id, then select
listLinks, a list of all the links for that page, and their types, will be returned.
- Top Row: Buttons for controlling what appears on the screen and the
Send Querybutton for submitting the query.
- Second and third rows: inputs for constructing the query
- Third row:
- A drop-down menu for selecting pre-defined remote sites and their credentials
- A button for saving remote data to the local wiki and the credentials of the local wiki
- A status bar with action links to clear the various views and to display the current query
- Above the status bar is the output window where the results of the query are displayed. They open automatically when the query is completed.
- The remote site can be the local wiki. Some users might find this particularly useful in combination with the
xcom.GetMetaDataquery, which makes it possible to check the metadata entries on the local wiki.
Instructions for creating the query
- Enter the URL to the remote site. If your remote site is at
http://www.example.comand the name of the wiki is
my_wiki, then you would enter
As explained above the 'remote site' simply refers to the site which holds the xmlrpc interface with which you are communicating and could therefore be the site that you are currently logged into.
- Enter the remote user name and password for the remote site. In your configuration settings you must enable the “Remote API system” and identify the remote user(s) or group(s).
- Select your query type from the drop-down
Select querymenu. Important: Query types that begin with
xcommust have the xcom plugin installed on both the local and the remote server, preferably the same version.
- If your query requires an id, enter that in the
IDtext box. The id must be the complete id that identifies the page on the remote server, in other words, including the namespace. For an optional way to enter an id, see the section on action links below.
- Some queries may require additional options. Clicking the
Query typesbutton will bring up a listing of query types and their options. Enter these options, in the order listed, separated by commas, in the
Optionstext box. Do not re-enter the
idin this additional list of options.
- Options which expect arrays are enclosed in parentheses:
(option). See the
Query typeslisting for details on how to handle array options for specific queries.
- There are more query types found on DokuWiki's xmlrpc page than are listed in the
Select querymenu. If you want to use one of those, then enter the complete listing, including the function name into the
Optionsbox. The function name must come first and then, in order listed, the options. They must all be separated by commas, including the function name. For instance:
- The queries that start with
plugin.xcom) were written specifically for the xcom plugin.
Timestamps: Some queries require a timestamp as a parameter. Xcom will create the timestamp for you. Enter the date in the
Optionsbox in this format:
yyyy-mm-dd, for instance 2014-05-29.
There are three display views: HTML, Edit, and Code. These are all contained within an “Output” window. When the result of a query is displayed, this window opens and the contents of your query will appear in one of these three views, depending upon the output. More than one view can be open at any one time, so that, for instance, you can be looking at the markup for a page while also viewing it as HTML. You can close and re-open these views using the buttons at the top right of the screen. And you can close the Output window entirely.
Editview enables you to make changes to the markup and save it back to the remote wiki which, as noted above, could be the wiki you are currently logged into. It also enables you to add material to a page by appending.
HTML viewis used to display wiki pages and to display query results that can be conveniently formatted as HTML.
Code viewis preformatted text. It is used for simple plain text responses, error codes, and arrays from queries not in xcom's list of
Action Viewholds the results obtained with action links
In the status bar at the bottom of the screen there are command links which enable you to
Clear the contents from each of the three view windows.
Local save button makes it possible to move pages and media from the remote wiki to the local wiki. Enter the id of a remote page or media file into the
ID field and click the
Local save button. If you select a page id, the page and all of its referenced media will be copied to the local server. All will be copied to the correct namespaces, including the page itself. If, instead of a page id,you enter a media id, the media file will also be copied to the correct namespace.
To use this feature you must fill in the local user's xmlrpc user name and password in the text boxes. The local url will be automatically retrieved from the system.
Query Types with First Column IDs
There are several query types which return lists of pages and media with the ids in the first column. Among them are:
dokuwiki.getPagelistwill take a namespace in the
IDfield and return all the pages in that namespace.
wiki.getAllPageswill return all the pages on the remote wiki.
- wiki.getAttachments (media files)
wiki_getAttachmentsreturns media files and behaves exactly as
dokuwiki.getPagelist. It takes a namespace in the ID field and requires a regular expression in the Options field. The regular expression must be placed between hashes and passed in as an array. For instance, if you want to get all PNG images in a namespace, you would enter the following expression in the options field:
dokuwiki.searchbehaves like DokuWiki's Search mechanism. It returns snippets of text with some highlighted matches and links to the pages where the matches occur which. Clicking these links accesses the pages with all their matches highlighted. The search text is entered as a string, e.g.
The ids of the first three query types are
Action links make it possible to act upon lists from either the local or the remote server.
If the results of a query is formatted as a table and the first column is headed
id, the first column is an action link. Clicking one of these can have one of two results:
- If no query is selected, the item identified by the id will be imported into the local wiki from the remote wiki. If this is a wiki page, all of its media will also be imported. This is in effect a short-cut to a manually set
- If a query is selected from the Query Selection menu which requires an id, the query will be applied to that id on the remote site. Other options may still be set in the options textbox.
A table with action links
Remote Sites Menu
You can create an initialization file,
xcom.ini, for automatic filling in of the remote site fields in the xcom dashboard. A
sample.xcom.ini is found in the scripts directory. Use of
xcom.ini is not required but it can be convenient. The file structure is based on the php.ini format:
[title] url=http://www.example.com/mywiki/ user=rpcuser pwd=rpcpwd
For each remote wiki that you work with, enter another data block. Only the title is required. The titles of these remote sites will appear in the drop-down menu, and when you select a menu item, the fields with entries will be entered into the remote wiki text boxes. The title entry must be set flush against the left-hand margin, i.e. no spaces between
[title] and margin.
The fact that the fields are optional means that you don't have to fill in the password field (or even user name). But as another security feature, you can move xcom.ini out of the web server's access. For this, there is a configuration option,
inidir, for setting an alternate directory for this file, and this can be anywhere on your server. But the file and its directory must of course be readable to PHP.
inidir: Alternate directory for xcom.ini
textbox_size: Size of Remote URL text box. Size is number of characters wide; this does not affect the number of characters that can be entered into the box. You may need this to adjust for browser layout width
local_url: Local IP address, e.g. http://192.168.0.5/dokuwiki. May be needed in some cases for local saves where the the dokuwiki is accessed by a local alias instead of its IP address. It may also be possible to use 127.0.0.1.
Last 10 Commits
- updates version (2022-02-13 18:10)
- Removes extra input form remote that after delay removes error messag… (2022-02-12 23:59)
- In script.js::xcom_check_opts pass back in temp array to xcom_params … (2022-02-12 23:05)
- Removed some debugging in xcom_params (2022-02-12 04:07)
- Adds code in script.js::xcom_params to detect if function has been se… (2022-02-12 04:03)
- Adds no function selected language string (2022-02-11 12:27)
- makes option field optional for getPagelist, adds code to default opt… (2022-02-10 22:06)
- Had to revert to previous, default for getPagelist not ready (2022-02-10 17:06)
- defaults dokuwiki.getPagelist to : and (hash) (2022-02-10 16:50)
- added sample.xcom.ini (2022-02-10 01:35)
- Mon Oct 24
fixed error return in xml.php
fixed copying error in xml.php
enabled depth param for dokuwiki.getPagelist()
corrected xref url in funtions list
- Sun Dec 13
Implemented INPUT for REQUEST variables
- Sat Dec 12
added tool tip to function select menu
- Fri Dec 11
fixed missing ';' in script.js
- Mon Aug 24
Translation update (de)
- Sun Mar 8
Fixed some html glitches in admin.php
- Mon Jun 9
new langauge strings
uri-decode error messages of array types
action links activate pre-selected query
- Thu Jun 5
deleted putAttachment from functions docs
- Wed Jun 4
fixed bug in Local save
added handling for commas in options; updated functions list
by-pass uridecoding for json objects; fix opstring processing
- Tue Jun 3
added search facility to getAttachments and getPaglist using array syntax
added hash option to getPaglist function
- Mon Jun 2
support for new function plugin.xcom.listNamespaces
- Fri May 30
assigned wiki.getAttachmentInfo result to table
added wiki.listLinks to tables
- Thu May 29
documentation, lang string updates
clicking on id action link in table, with query selected, applies query to the id
refactored table header access
Update to howto.txt documentation
adds mouseover titles to query selection, javscript timestamp support;fix for some error messages
- Tue May 27
added action links to tables with ids to import files directly via the links
added local save for media files; updated docs
- Mon May 26
added language support for xcom_save.php; new textbox size config option
added local page save module to xcom_save
- Sun May 25
integratied interwiki copy into admin panel; some updates and fixes
- Tue May 20
added option to locate xcom.ini in alternate directory
- Sun May 18
GUI updates and xcom.ini implementation
- Thu May 15
adds facility for hiding and showing password
- Wed May 14
added plugin.xcom.getMedia to table type and refactored types of tables
plugin.xcom.getMedia now returns media for Dokuiwiki distributions prior to Binky
Open results window when opening a view
corrected ampersand escape
- Tue May 13
escape ampersands in text data; otherwise query fails
added putPage and appendPage
- Sun May 11
support for dokuwiki.search
table and GUI additions
- Thu May 8
added getPageVersions table and upgraded table handling
- Mon May 5
Initial file upload