DokuWiki

It's better when it's simple

User Tools

Site Tools


plugin:move

This is an old revision of the document!


Move Plugin

Compatible with DokuWiki

Hrun, Detritus, "Elenor Of Tsort"

plugin Move pages, media files and namespaces while maintaining the link structure

Last updated on
2017-01-07
Provides
Helper, Admin, Action
Repository
Source
Conflicts with
autolink2, snippets, cherokee-based, sxs

This extension has not been updated in over 2 years. It may no longer be maintained or supported and may have compatibility issues.

Similar to editx, openas, pagemove

Tagged with maintenance, move, namespace, rename

This plugin allows to move pages and namespaces including media files and automatically adjusts all links and media references that point to these pages. Unlike the old pagemove plugin this plugin uses the DokuWiki parser which allows it to correctly identify all links and nothing else.

Parts of this plugin, like some of the translated strings, some parts of the structure of the code and parts of the user interface have been taken from the old pagemove plugin by Gary Owen, Arno Puschmann and Christoph Jähnigen.

Installation and Precautions

This plugin moves files inside your DokuWiki data directory and can automatically change a lot of pages. Even though the plugin has been successfully tested it is always possible that something doesn't work as expected in your case and your wiki might be left in an inconsistent state. This plugin is also still rather new and might behave incorrectly in certain cases.

Please make a backup before using this plugin, especially if you plan to make larger changes!

Warning: This plugin does not update ACL rules. For example if you had an ACL rule that read-protected a certain wiki page this rule won't have any effect anymore after moving that page.

Install the plugin using the Plugin Manager and the download URL above, which points to latest version of the plugin. Refer to Plugins on how to install plugins manually.

:!: When updating an existing installation of this plugin in DokuWiki versions older than Release Summer 2015 “Detritus” it might be necessary to de-install the old plugin version first and re-install the new version thereafter. Severe problems (e.g. inconsistent application menues with the old plugin screen combined with several unlogical [admin] buttons) have been observed after upating the plugin. For instance when originally installed on Dokuwiki release 2014-09-29 “Hrun” and updated onto Dokuwiki release 2015-08-10 “Detritus”.

If, for any reason, you used an FTP client to upload pages, you should “hit” (open) them in a browser to be sure the index is refreshed, otherwise the move plugins will fail to work on the page, or worth, forget to update link on those page.

Usage

Except for the single page rename, the plugin requires manager privileges to use it.

Move current page or namespace

Screenshot

This is the main part of the plugin. To use it navigate to the page (or page in namespace) you want to change, then open the Admin menu and select the Move plugin from the list of additional plugins.

In the box switch between the current page or namespace and give a new location. Clicking start will preview your changes and you can start the move operation. To move a namespace with some pages in subspaces but none directly under the namespace, use the tree based move method.

Tree based move

To plan more complicated restructuring of your wiki, the move plugin comes with a tree-based Move Manager. Open it by clicking on the link in the Move screen, pictured above.

Screenshot

The Move Manager allows you to plan all moves and renames to be executed by drag'n'drop operations. Simply move pages, media files and namespaces to their desired locations until the tree represents the new layout you want to have. Starting from version 2017-01-07, multiple pages, media files or namespaces can be selected using checkboxes. When one of the selected items is moved, all selected items are moved to the target. The move fails (i.e., nothing is changed) if any of the selected items cannot be moved to the target (due to a naming conflict).

As of version 2017-01-07, new namespaces can be created by clicking on the “+”-icon next to the root namespace. Newly created namespaces can then be moved to the desired target location and can also be renamed. Note that only namespaces which contain a page, media file or (non-empty) namespace will be saved.

Simple Page Rename

Screenshot

This feature is available to users and groups that have been configured through the allowrename option in the config manager. It is automatically available on all templates that implement the TEMPLATE_PAGETOOLS_DISPLAY event and can be disabled in the config manager.

Users can simply rename (or move) the page they are currently on.

 Screenshot

Support for other plugins

The move plugin allows plugins to move their own data and to adapt their syntax when a page or media file is moved. Currently the following plugins support this:

Plugins not explicitly stating their compatibility are most probably not adjusted.

Technical Review for users

The move plugin uses the search index of DokuWiki to find pages that contain links to moved pages or media files and then uses DokuWiki's parser to identify all links to pages or media files in the affected pages and changes them if necessary. Whenever a page is modified, a new revision of the page is created (but changes are batched, so when you move many pages e.g. using the tree-based move manager you should still only see 1-2 new revisions per affected page). In contrast to a simple search and replace this can identify much more complex situation e.g. when a link is Foo Bar it will be found if the page foo_bar is moved and using DokuWiki's parser makes sure that e.g. code blocks or special plugin syntax is not modified. Plugins can also add support, so e.g. the syntax of the include plugin will also be adjusted accordingly. This structure should contribute to stability. Individual pages can be easily reverted using the builtin revert functionality of DokuWiki.

When a page or namespace is moved are all the internal links in the document / book / parent namespace checked and changed with an option to undo? Is there a Yes/no? check feature?

  • Yes, all links should be adapted as you already noted (both relative links in the moved page as well as links to the moved page/media file). There is currently no such check feature. However, as the plugin is using DokuWiki's parser it should really only change links that actually point to the moved page/media file and nothing else. When a page is changed, a new revision is created so you can later inspect the changes and, if necessary, revert them.

Are other housekeeping chores associated with “ moving” such as media. What else is needed to have a clean move?

  • Both pages and media files have a list of revisions and saved, old versions in attic/media_attic respectively. These files need to be moved, too. Pages also have other metadata. Further, the search index needs to be adjusted (e.g. by re-indexing the page at the new location). The move plugin takes care of all that when you rename or move a page or media file. Depending on the plugins you are using there might be additional data to be moved. Plugins can add support for moving their data when a page is moved using the move plugin, e.g. the struct plugin adapts its database when a page is moved.

What happens to old revisions and recent changes?

  • Unordered List ItemOld revisions are moved together with the page (and a new revision reflecting the move is added). In the recent changes, two changes are added, documenting both the deletion at the old name and the creation at the new name. As only one change per page is displayed in the recent changes, this means that older changes of the page won't be displayed in the recent changes.

For plugin authors

The move plugin emits the following events:

  • PLUGIN_MOVE_PAGE_RENAME
    • The before action is executed before a single page is moved, if the default action is prevented the move won't be executed (but it won't trigger an error/abort the move, FIXME this should be changed)
    • The after action is executed after the page has been moved. Plugins can use this in order to move their own data that is associated to the page $ID and it can add additional pages whose syntax needs to be adjusted because of this move.
    • data is an array with the following keys:
      • opts ⇒ array – compatibility to old plugins, shouldn't be used
      • affected_pages ⇒ array – page ids that are (possibly) affected by this move, initially populated from the relation_references metadata index. can be adjusted
      • src_id ⇒ string – the original ID of the page
      • dst_id ⇒ string – the new ID of the page
  • PLUGIN_MOVE_MEDIA_RENAME
    • Same as before, but for media files
  • PLUGIN_MOVE_HANDLERS_REGISTER
    • This event is called when the page content shall be rewritten. This can either happen
      • if the page itself is moved, then you will get the new id and the page id will also be part of the moves or
      • if other moves affect the page and the page is viewed for the first time.
    • Note that before moving the page itself it will be rewritten so it will never be that the page itself is moved while the links are adjusted.
    • data:
      • id – the id of the page that shall be modified
      • moves – the page moves that might affect the page
      • media_moves – the media moves that might affect the page
      • handlers – the array of handlers, see below for more information
    • Plugin handlers can be registered in the $handlers array, the key is the plugin name as it is given to the handler. The handler needs to be a valid callback, it will get the following parameters:
      • $match, $state, $pos, $pluginname, $handler. The first three parameters are equivalent to the parameters of the handle()-function of syntax plugins, $pluginname is just the plugin name again so handler functions that handle multiple plugins/plugin parts can distinguish for which the match is. The last parameter is the handler object. It has the following properties and functions that can be used:
        • id, ns: id and namespace of the old page
        • new_id, new_ns: new id and namespace (can be identical to id and ns)
        • moves: array of page moves, the same as moves in the event
        • media_moves: array of media moves, the sames as media_moves in the event
        • adaptRelativeId($id): adapts the relative $id according to the moves

Have a look at the include plugin for a relatively simple case of a plugin that handles page moves. These events might be subject to change though I'll try to keep them as compatible as possible. If you add your plugin to the list of supported plugins I'll have a look if I could break it before changing anything that might affect plugins.

Feel free to open a bug report if your plugin needs additional support from the move plugin.

Issues and feature requests

Please report bugs and feature requests in the issue tracker.

plugin/move.1484704892.txt.gz · Last modified: 2017-01-18 03:01 by rgleason

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