DokuWiki

It's better when it's simple

User Tools

Site Tools


plugin:xcom

xcom Plugin

Compatible with DokuWiki

  • 2024-02-06 "Kaos" unknown
  • 2023-04-04 "Jack Jackrum" unknown
  • 2022-07-31 "Igor" unknown
  • 2020-07-29 "Hogfather" yes

plugin An xmlrpc cross-communication facility that enables two wikis to interact by means of a dashboard interface, including administration, importing of pages and media, and editing on the remote wiki

Last updated on
2022-02-13
Provides
Admin, Remote
Repository
Source

Tagged with import, metadata, xmlrpc

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

The Dashboard Interface

Purpose

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.

Basics

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.

Dashboard Layout

  • Top Row: Buttons for controlling what appears on the screen and the Send Query button for submitting the query.
  • Second and third rows: inputs for constructing the query
  • Third row:
    1. A drop-down menu for selecting pre-defined remote sites and their credentials
    2. 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.GetMetaData query, which makes it possible to check the metadata entries on the local wiki.

Instructions for creating the query

  1. Enter the URL to the remote site. If your remote site is at http://www.example.com and the name of the wiki is my_wiki, then you would enter http://www.example.com/my_wiki. 1)
    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.
  2. 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).
  3. Select your query type from the drop-down Select query menu. Important: Query types that begin with plugin.xcom or xcom must have the xcom plugin installed on both the local and the remote server, preferably the same version.
  4. If your query requires an id, enter that in the ID text 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.
  5. Some queries may require additional options. Clicking the Query types button will bring up a listing of query types and their options. Enter these options, in the order listed, separated by commas, in the Options text box. Do not re-enter the id in this additional list of options.
  6. Options which expect arrays are enclosed in parentheses: (option). See the Query types listing for details on how to handle array options for specific queries.
  7. There are more query types found on DokuWiki's xmlrpc page than are listed in the Select query menu. If you want to use one of those, then enter the complete listing, including the function name into the Options box. 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:
    wiki.function,parameter_1, parameter_2
  8. The queries that start with xcom (or plugin.xcom) were written specifically for the xcom plugin.
  9. Timestamps: Some queries require a timestamp as a parameter. Xcom will create the timestamp for you. Enter the date in the Options box in this format: yyyy-mm-dd, for instance 2014-05-29.

Views

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.

  1. Edit view 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.
  2. HTML view is used to display wiki pages and to display query results that can be conveniently formatted as HTML.
  3. The Code view is preformatted text. It is used for simple plain text responses, error codes, and arrays from queries not in xcom's list of Query types.
  4. Action View holds the results obtained with action links

Status Bar

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

The 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:

  1. dokuwiki.getPagelist
    dokuwiki.getPagelist will take a namespace in the ID field and return all the pages in that namespace.
  2. wiki.getAllPages
    wiki.getAllPages will return all the pages on the remote wiki.
  3. wiki.getAttachments (media files)
    wiki_getAttachments returns 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: (#\.png#).
  4. dokuwiki.search
    dokuwiki.search behaves 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. :playground dokuwiki.

The ids of the first three query types are action links.

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:

  1. 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 Local save.
  2. 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.

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.

Security

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.

Configuration Options

  1. inidir: Alternate directory for xcom.ini
  2. 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
  3. 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.

Changes

Last 10 Commits

2016

  • 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

2015

  • 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

2014

  • 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
    Corrected IXR_Date object month value for Javascript zero-start month field
    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
    GUI improvements
  • Sun May 11
    GUI improvements
    support for dokuwiki.search
    table and GUI additions
  • Thu May 8
    added getPageVersions table and upgraded table handling
    added to status line; fixed date conversion from php to javascript
  • Mon May 5
    Initial file upload
1)
Note: the complete url and not for instance: “example.com/my_wiki”
plugin/xcom.txt · Last modified: 2023-10-30 22:26 by Klap-in

Except where otherwise noted, content on this wiki is licensed under the following license: CC Attribution-Share Alike 4.0 International
CC Attribution-Share Alike 4.0 International Donate Powered by PHP Valid HTML5 Valid CSS Driven by DokuWiki