1===== Purpose =====
2
3With this app users can conveniently communicate with Dokuwiki's xmlrpc library. It can be on any Dokuwiki, including the one which you are currently logged into.  The user can then communicate and exchange data between the local wiki and a remote wiki.
4
5===== Basics =====
6
7At its simplest you enter the URL of the remote wiki into the ''Remote URL'' text box, you select a query form 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. If you enter a paged id, then select listLinks, a list of all the links for that page, and their types, will be returned.
8
9===== Dashboard Layout =====
10
11  * Top Row:  Buttons for controlling what appears on the screen and the ''Send Query''  button for submitting the query.
12  * Second and third rows:  inputs for constructing the query
13  * Third row:
14      - A drop-down menu for selecting pre-defined remote sites and their credentials
15      - A button for saving remote data to the local wiki and the credentials of the local wiki
16  * A status bar with action links to clear the various views and to display the current query
17  * Above the status bar is the output window where the results of the query are displayed.  They open automatically when the query is completed.
18
19==== Instructions for creating the query ====
20
21  - Enter the URL to the remote site. If your remote site is at ''<nowiki>http://www.example.com</nowiki>''  and the name of the wiki is ''my_wiki'', then you would enter ''<nowiki>http://www.example.com/my_wiki</nowiki>''. \\ 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.
22  - 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).
23  - Select your query type from the drop-down ''Select query''  menu.
24  - 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.
25  - 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.
26  - 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.
27  - There are more query types found on Dokuwiki's [[https://dokuwiki.org/devel:xmlrpc|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''
28  - ''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.
29
30==== Views ====
31
32There 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.
33
34  - ''Edit''  view enables you to make changes to the markup and save it back to the remote wiki which, as nted above, could be the wiki you are currently logged into. It also enables you to add material to a page by appending.
35  - ''HTML view''  is used to display wiki pages and to display query results that can be conveniently formatted as HTML.
36  - The ''Code view''  is preformatted text. It's used for simple plain text responses and complex arrays which may in later versions of xcom be re-formatted as tables.
37
38==== Status Bar ====
39
40In 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. The status bar also contains a ''Query'' field where the current query is displayed. At the far right is a link which enables you to submit the query.
41==== Local Save ====
42
43The ''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.
44
45To use the feature you must fill in the local user's xmlrpc user name and password in the text boxes. The local url will be automtically retrieved from the system.
46
47There is an alternate way of importing pages and media from the remote to the local wiki. There are several query types which return lists of pages and/or media with the ids in the first column. These are:
48
49  * dokuwiki.getPagelist
50  * wiki.getAllPages
51  * wiki.getAttachments (media files)
52  * dokuwiki.search
53
54**''dokuwiki.getPagelist''**  will take a namespace in the ''ID''  field and return all the pages in that namespace. **''wiki.getAllPages''**  will return all the pages on the remote wiki.  Finally, **''wiki_getAttachments''**  returns media files and behaves exactly as **''dokuwiki.getPagelist''**. The latter 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#)''. **''dokuwiki.search''** takes a query string as described in [[doku>search]] and returns a page of snippets from pages with the matching texts; clicking on the page id's for these snippets opens the full page with all matching texts highlighted.
55
56The results of these queries are formatted as tables in which the first column is an action link. If you click that link, the item will be imported into the local wiki from the remote wiki. If this is a page, all of its media will also be imported.
57
58Action links can also work with queries selected from the drop-down query menu. For more information about this, see the [[doku>plugin:xcom#action_links|xcom plugin page]].
59
60==== Remote Sites Menu ====
61
62There is an initialization file named ''xcom.ini'' which is found in the scripts directory. Use of this file is not required but it can be convenient. The file structure is based on the php,ini format:
63<code>
64      [title]
65        url=http://www.example.com/mywiki/
66        user=rpcuser
67        pwd=rpcpwd
68</code>
69
70For 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's text boxes.  **Note:** the title entry must be set flush against the left-hand margin.
71
72=== Security ===
73
74The fact that the fields are optional means that you don't have to enter passwords (or even user names). 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 be readable.
75