====== openas Plugin ====== ---- plugin ---- description: File utility for moving/renaming files, saving copies, creating new pages from templates author : Myron Turner email : turnermm02@shaw.ca type : syntax,action lastupdate : 2022-02-14 compatible : Anteater, Rincewind, Angua, Adora Belle, Weatherwax, Binky, Ponder Stibbons, Hrun, Ddetritus, Elenor of Tsort, Frusterick Manners, Greebo, Hogfather depends : newpagetemplate conflicts : similar : bureaucracy, move tags : pagemove, file, template,rename,move,form downloadurl: https://github.com/turnermm/OpenAs-plugin-for-Dokuwiki/tarball/master bugtracker : https://github.com/turnermm/OpenAs-plugin-for-Dokuwiki/issues sourcerepo : https://github.com/turnermm/OpenAs-plugin-for-Dokuwiki/ donationurl: http://mturner.org/userfiles/donate.php ---- ===== Installation ===== :!: **External requirements:** This plugin requires the following additional component that must be installed separately if you wish to use the templating facility: [[plugin:newpagetemplate]] Search and install the plugin using the [[plugin:extension|Extension Manager]]. Refer to [[:Plugins]] on how to install plugins manually. ===== Examples/Usage ===== This plugin facilitates renaming (i.e. moving) pages, saving as (i.e. saving a page under a new name without deleting the original), and creating new pages from templates. There are three syntax formats: ~~SaveAS>newname~~ ~~MoveTO>newname~~ ~~OpenAS>newname#template>newpagevars~~ - ''newname'' is the page name with its namespace, as in '':namespace:newname'' - ''template'' is the name of a template which will be found in :''pagetemplates'' - ''newpagevars'' has this format: @macro_1@,value_1;@macro_2@,value_2;. . . * this follows the format of the [[plugin:newpagetemplate#example|newpagetemplate]] plugin for specifying macros and their substitution values. ==== SaveAS ==== The SaveAS form will create a new page from the old page but leave the old page intact. ==== MoveTO ==== The MoveTO form will create a new page from the old page and delete the old page. However, it will not delete the old page unless it is certain that the new page is in place, so that there is no danger of losing the old page. The MoveTo form performs a limited page move: it preserves backlinks and implements a number of other features, as described below in the [[#pagemove]] section. ==== OpenAS ==== The OpenAS form requires the newpagetemplate plugin. This form will open the page ''newname'', using the specified template. The ''newpagevars'' attribute follows the format described on the [[:plugin:newpagetemplate|newpagetemplate page]]. Here is a sample: ~~OpenAS>hello_temp#:pagetemplates:homepagetemplate>@HI@,HOWDY!;@BYE@,Good Bye~~ This will open up the page :hello_temp, using the ''homepagetemplate'' in the '':pagetemplatesnamespace'', and it will fill in any of the substitution variables defined on the newpagetemplate plugin page, as well as the variables defined by ''newpagevars'' (which in this example are: @HI@ and @BYE@). Please see the [[:plugin:newpagetemplate|newpagetemplate page]] for complete details on using the newpagetemplate plugin. There is an expanded syntax for this form of the plugin which gives it significantly greater flexiblity. See [[#expanded_syntax_for_the_openas_format|below]]. ===== How it works ===== Once the page with the syntax markup is saved, it will now show a yellow box with a link. Clicking on this link will perform the desired action. In the case of pages which have been moved or saved-as, the new page will already be created, but links will not be updated until the new page is accessed from the link in the yellow box. In the case of a page which has been moved, the original page will remain on the server until you have linked to the new page, at which time the old page will be deleted. In the case of new page templates, the new page will open with the macro values filled in. The %%~~SaveAS>name~~%% and %%~~MoveTO>name~~%% will be removed from the newly created pages. === Relative Links === Relative links will be re-written to the newly created file as absolute links. This is true of both the SaveAS and the MoveTO forms, ===== Pagemove ===== In the MoveTo option, all backlinks to the page being moved are updated to the page id of the new page. The plugin takes into consideration page locking. So, if a page with backlinks is currently in use, it is not updated until the user with the lock exits the page. The original page remains in place until all of the pages with backlinks have been updated. Once all backlinks have been updated, the original page is removed. == Metadata and Indexing== This plugin does not update the DokuWiki history or indexing for the updated files If you want to re-index your site, you can use the [[plugin:searchindex]] plugin. == Images == The plugin in its present form does not update relative image links. If images are inserted using the media manager, this should not be an issue. For this situation try the [[plugin:move]] plugin. == Backup == There is a backup system. A new meta directory is created: ''data/meta/openas'', where the original backlink pages are stored. The pre-updated versions of these pages are created with the ''.mvd'' extension. And the page which has been moved to the new id is backed up with the ''.orig'' extension. The ''.orig'' and ''.mvd'' files are numbered, with the highest number being the most recent. ===== Security ===== There is basic built-in security for the **SaveAS** and **MoveTo** operations. They check to make sure that the user has at least ''edit'' permission for the file which is being copied from and ''create'' permission for the new file that is being created. Both **SaveAS** and **MoveTo** can be protected as well by standard acl rules which control who has access to the pages where the plugin code is embedded. Similarly the **OpenAs** operation can be protected by the site's [[:acl|]] rules. ==== Spoofed URLs ==== The plugin also intercepts any attempts to access the file system through spoofed urls. For these cases the url is redirected to another page. By default the redirection goes to an image in the plugin's images directory, which displays a 404 notice. This can be changed in the Configuration manager either to a new image or page in the images directory or to an external url. If you use the images directory, your url should take this form: * ''lib/plugins/openas/images/404.jpg''. \\ Note: this url does not take the domain. ===== Expanded Syntax for the OpenAs Format===== With the expanded syntax, it is not necessary to pre-insert the ''newpagevars'' and their values into the page, as described [[#openas|above]]. Instead you can create an HTML Form, from which the plugin will take the names of the variables and their values. The benefit of this, of course, is that the values are not pre-set by the plugin. Different values can be entered for each access of the form. This is the expanded syntax. ~~OpenAsVarsStart~~ ~~OpenAsVAR>VAR-1~~ ~~OpenAsVAR>VAR_2~~ ~~OpenAsNUM>VAR_3~~ ~~OpenAsVAR>TAreaOpen:VAR_4~~ ~~OpenAsVAR>TAreaClose~~ ~~OpenAsVarsClose~~ ~~OpenAS>SAVEAS_PAGE#template>~~ The ''OpenAsVAR'' creates an HTML textbox 24 characters wide, whereAS ''OpenAsNUM'' creates a textbox 10 charaCters wide. The ''TArea'' pair creates an HTML textarea. The ''~~OpenAS>SAVEAS_PAGE#yourtemplate>~~'' entry must be outside of the ''VarsStart'' and ''VarsClose'' block. :!: Important: ''SAVEAS_PAGE'' is a placeholder and must appear in your plugin markup exactly as illustrated above. It will place a textbox on your page which asks for the ''page id''. The user will get a link to ''SAVEAS_PAGE''. When the user clicks on the link, this placeholder will be replaced by the ''page id'' from the textbox. See the illustration [[#result|below]]. This above markup will create a Form with two text boxes and one textarea. ''ReplacementVar'' is the name of a variable which is included in the template. So, for instance, if the ''ReplacementVar'' is ''NAME'', then the plugin will replace ''@NAME@'' in the template with the value entered into the textbox. You can create as many textboxes as you need. Each instance of ~~OpenAsVAR>ReplacementVar~~ can be prefaced by a descriptive label, for instance: First Name: ~~OpenAsVAR>FNAME~~ ** First Name: ** ~~OpenAsVAR>FNAME~~ The Replacement variables are case-sensitive. There are two formatting features. The first will help to arrange the input elements on your page; this is the Dokuwiki line-break: ''%%\\%%''. The input elements can be interspersed with text. The double asterisks are place-holders for marking up the text as one of: ''bold'', ''underline'', ''italic'', or ''none''. The selection of which markup to use is made in the Configuration Manager by means of the ''label'' option. You can use the ''~~OpenAS>SAVEAS_PAGE#yourtemplate>~~'' with or without predefined values. It is also possible to include predefined values, as illustrated in the basic syntax form [[#openas|above]], and to combine predefined values with values captured from the Form. The link will redirect to a new page which has been invoked by the link with data captured from the parameters in the form. ===== Example ===== ===== Markup ===== ~~OpenAsVarsStart~~ ** Name: ** ~~OpenAsVAR>name~~ ** Age:** ~~OpenAsVAR>AGE~~\\ ** Address: ** ~~OpenAsVAR>ADDR1~~ ** Address 2: ** ~~OpenAsVAR>ADDR2~~\\ ** Details: ** ~~OpenAsVAR>TAreaOpen:DETAILS~~ ~~OpenAsVAR>TAreaClose~~ ~~OpenAsVarsClose~~ ~~OpenAS>wiki:SAVEAS_PAGE#test:openas:template_1>@HI@,HOWDY!;@BYE@,Good Bye~~ This labels surrounded by asterisks (i.e. %%**%% Name: %%**%%) can be configured from the Configuration Settings as bold, italic, or underlined. Default is ''none'', no formatting. ===== Result ===== {{ https://i.imgur.com/JchEQ5b.png?480&recache }} The Name, Age and Addr fields will be added to the HI and BYE fields. The HI and BYE are constants, pre-set, the others are set by the user and will differ from page to page. ==== Change Log ==== {{rss>https://github.com/turnermm/OpenAs-plugin-for-Dokuwiki/commits/master.atom date count=15}} Complete listing of changes: https://github.com/turnermm/OpenAs-plugin-for-Dokuwiki/commits/master ===== Discussion ===== For discussion, please use the DokuWiki [[https://forum.dokuwiki.org/|forum]], the above-listed Bugs button, or the [[~:discussion]] page.