%META:TOPICINFO{author="TWikiContributor" date="1688110919" format="1.1" version="$Rev$"}%
---+!! Replace Text Plugin
<!--
   Contributions to this plugin package are appreciated. Please update this page at
   http://twiki.org/cgi-bin/view/Plugins/ReplaceTextPlugin or provide feedback at
   http://twiki.org/cgi-bin/view/Plugins/ReplaceTextPluginDev.
   If you are a TWiki contributor please update the extension in the SVN repository.
-->
<sticky>
<div style="float:right; background-color:#EBEEF0; margin:0 0 20px 20px; padding: 0 10px 0 10px;">
%TOC{title="Page contents"}%
</div>
</sticky>
%SHORTDESCRIPTION%

---++ Replace Text Form

%X% ATTENTION: Use with caution, it is possible to change many topics at once!

<noautolink>
%SET{"webList" value="%WEBLIST{ separator=", " depth="2" limit="30" }%"}%<nop>
%TABLE{ sort="off" columnwidths="40,550" }%<nop>
<form name="replace" id="replaceForm" action="%SCRIPTURLPATH{view}%/%WEB%/%TOPIC%" method="get">
| *Replace Text* ||
| Web: | <select name="web" id="webName" class="twikiSelect"><option>%URLPARAM{ "web" default="Select..." }%</option>%CALCULATE{$LISTJOIN($sp, $LISTEACH(<option>$item</option>, %GET{webList}%))}%</select> |
| From: | <input name="from" id="fromText" type="text" value="%URLPARAM{ "from" encode="entity" }%" size="30" class="twikiInputField" /> |
| To: | <input name="to" id="toText" type="text" value="%URLPARAM{ "to" encode="entity" }%" size="30" class="twikiInputField" /> |
| Test: | <label> <input name="dryrun" id="dryRun" type="checkbox" value="checked" %URLPARAM{ "dryrun" encode="entity" }% class="twikiCheckbox" /> Dry run, don't replace </label> |
| | <div id="replaceButtonContainer"><input type="submit" value="Replace" class="twikiSubmit" id="replaceButton" /> [[%TOPIC%][Clear]] </div> |
| Result: | <span id="resultNote">%REPLACETEXT{ action="%URLPARAM{ "action" encode="quote" }%" web="%URLPARAM{ "web" encode="quote" }%" from="%URLPARAM{ "from" encode="quote" }%" to="%URLPARAM{ "to" encode="quote" }%" search="\b$from\b" replace="$to" dryrun="%URLPARAM{ "dryrun" encode="quote" }%" }%</span> |
<input type="hidden" name="action" value="replace" />
</form>
%JQTHEME{"smoothness"}%
<div class="ogray" style="display:none" id="confirmReplace" title="Replace Text"></div>
</noautolink>
<script>
$(document).ready(function() {
  $('#replaceButton').on('click', function(event) {
    event.preventDefault();
    var web    = $('#webName').val();
    var from   = $('#fromText').val();
    var to     = $('#toText').val();
    var dryRun = $('#dryRun:checked').length;
    if(web==='Select...' || from==='' || to==='') {
        alert('Please specify all fields');
        return;
    }
    $('#confirmReplace').html('<p><b>' + from + '</b> <tt>===&gt;</tt> <b>' + to + '</b></p><p>Replace this in the ' + web + ' web?</p>');
    $('#confirmReplace').dialog({
        resizable: false,
        height: 'auto',
        width: 500,
        modal: true,
        buttons: {
          Replace: function() {
            $(this).dialog('close');
            $('#replaceButtonContainer').html('%ICON{processing}%');
            window.setTimeout(function() {
                $('#replaceForm').submit();
            }, 200);
          },
          Cancel: function() {
            $(this).dialog('close');
          }
        }
    }).show();
    return false;
  });
});
</script>

---++ Syntax Rules

=%<nop>REPLACETEXT{ action="..." web="..." from="..." to="..." }%=

%INCLUDE{ "VarREPLACETEXT" section="parameters" }%

See details at [[VarREPLACETEXT][REPLACETEXT]].

---++ Security and Known Issues

   * This plugin ignores locked topics, it writes over locked topics.
   * This plugin is potentially dangerous. Security measures:
      1 The operations of this plugin is restricted to members of the %USERSWEB%.TWikiAdminGroup. This can be changed with the =$TWiki::cfg{Plugins}{ReplaceTextPlugin}{AccessGroup}= configure setting.
      1 For public sites, it is recommended to enable this plugin only for the short time when needed (it is enabled if the following variable shows "installed": %REPLACETEXT{action="check"}%).
   * This plugin has been tested. However, operator errors can be done quite easily, especially if regular expressions are not well understood. This plugin does not have ANY WARRANTY, does not even have the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.

#CustomReplacement
---++ Custom Replacement For Developers

You can ignore this section unless you want to add custom search and replace code.

%TWISTY{
 mode="div"
 showlink="Show details %ICONURL{toggleopen}% "
 hidelink="Hide details %ICONURL{toggleclose}% "
}%

By default, the plugin uses =from=, =to=, =search=, =replace= parameters, as documented at [[VarREPLACETEXT][REPLACETEXT]]. The =search= and =replace= parameters allows for more complex search and replace operations using regular expression grouping.

If you need even more control over search and replace you can write your own search and replace module, such as to sort a list based on the search and replace operation. For this you can clone and modify =twiki/lib/TWiki/Plugins/ReplaceTextPlugin/CustomReplace.pm=. Specify the name of your module in the =$TWiki::cfg{Plugins}{ReplaceTextPlugin}{CustomReplace}= configure setting, such as ='TWiki::Plugins::ReplaceTextPlugin::MyReplace'=.

Add a function as follows:

=replaceText( $web, $topic, $text, $search, $replace ) -> $text=

   * =$web:     <nop>=Name of web
   * =$topic:   <nop>=Name of topic
   * =$text:    <nop>=Text of topic
   * =$search:  <nop>=Text to search for
   * =$replace: <nop>=Text to replace with
   * =return:   <nop>=Text with replacement

%ENDTWISTY%

---++ Plugin Installation &amp; Configuration

You do not need to install anything on the browser to use this plugin. These instructions are for the administrator who installs the plugin on the TWiki server.

%TWISTY{
 mode="div"
 showlink="Show details %ICONURL{toggleopen}% "
 hidelink="Hide details %ICONURL{toggleclose}% "
}%

   * For an __automated installation__, run the [[%SCRIPTURL{configure}%][configure]] script and follow "Find More Extensions" in the in the __Extensions__ section.
      * See the [[http://twiki.org/cgi-bin/view/Plugins/BuildContribInstallationSupplement][installation supplement]] on TWiki.org for more information.

   * Or, follow these __manual installation__ steps:
      * Download the ZIP file from the Plugins home (see below).
      * Unzip ==%TOPIC%.zip== in your twiki installation directory. Content:
        | *File:* | *Description:* |
        | ==data/TWiki/ReplaceTextPlugin.txt== | Plugin topic |
        | ==data/TWiki/VarREPLACETEXT.txt== | Variable documentation |
        | ==lib/TWiki/Plugins/ReplaceTextPlugin.pm== | Plugin Perl module |
        | ==lib/TWiki/Plugins/ReplaceTextPlugin/Config.spec== | Configuration spec file |
        | ==lib/TWiki/Plugins/ReplaceTextPlugin/Core.pm== | Plugin core module |
        | ==lib/TWiki/Plugins/ReplaceTextPlugin/CustomReplace.pm== | Template for custom replace module |
      * Set the ownership of the extracted directories and files to the webserver user.

   * Plugin configuration:
      * Run the [[%SCRIPTURL{configure}%][configure]] script and enable the plugin in the __Plugins__ section.

   * Test if the configuration is successful:
      * Try the replacement form above, preferably with the Sandbox web

%ENDTWISTY%

#PluginInfo
---++ Plugin Info

   * Set SHORTDESCRIPTION = Globally search and replace text in all topics of a web

%TABLE{ tablewidth="100%" columnwidths="170," }%
|  Author: | TWiki:Main.PeterThoeny, [[http://twiki.org/][TWiki.org]] |
|  Copyright: | &copy; 2019-2023 ALPS Plastic. %BR% &copy; 2019-2023 TWiki:Main.PeterThoeny %BR% &copy; 2019-2023 TWiki:TWiki.TWikiContributor |
|  License: | GPL ([[http://www.gnu.org/copyleft/gpl.html][GNU General Public License]]) |
|  Sponsor: | [[https://amidigroup.com/alps-plastic][ALPS Plastic]] |
|  Version: | 2023-06-26 |
%TWISTY{
 mode="div"
 showlink="Show Change History %ICONURL{toggleopen}%"
 hidelink="Hide Change History %ICONURL{toggleclose}% "
}%
%TABLE{ tablewidth="100%" columnwidths="170," }%
|  2023-06-30: | TWikibug:Item7864: Add topic="", filter="", and showlist="" parameters |
|  2021-04-21: | TWikibug:Item7864: Escape special characters such as parenthesis in from parameter |
|  2019-05-05: | TWikibug:Item7864: Support special case when using $1, $2, etc in replace |
|  2019-05-04: | TWikibug:Item7864: Initial version of !ReplaceTextPlugin |
%ENDTWISTY%
%TABLE{ tablewidth="100%" columnwidths="170," }%
|  TWiki Dependency: | $TWiki::Plugins::VERSION 1.2 |
|  CPAN Dependencies: | none |
|  Other Dependencies: | none |
|  Perl Version: | 5.008 |
|  [[TWiki:Plugins.Benchmark][Plugin Benchmark]]: | %SYSTEMWEB%.GoodStyle nn%, %SYSTEMWEB%.FormattedSearch nn%, %TOPIC% nn% |
|  Home: | http://TWiki.org/cgi-bin/view/Plugins/ReplaceTextPlugin |
|  Feedback: | http://TWiki.org/cgi-bin/view/Plugins/ReplaceTextPluginDev |
|  Appraisal: | http://TWiki.org/cgi-bin/view/Plugins/ReplaceTextPluginAppraisal |

__Related:__ VarREPLACETEXT
