DokuWiki

It's better when it's simple

User Tools

Site Tools


Sidebar

Translations of this page?:

Learn about DokuWiki

Advanced Use

Corporate Use

Our Community


Follow us on Facebook, Twitter and other social networks.

tips:summary_enforcement

Summary Enforcement

This enhancement requires the user to either provide a summary or check “minor changes” before saving a section or a page, thus requiring that all major changes be given a description. You may also tweak it to always require a summary, regardless of whether “minor changes” is checked.

Description

The enhancement is very simple. When the user edits a section or a page, the Save button is initially disabled and cannot be pressed. The user may press Preview to preview the page, but in order to save the page the user must first either:

  • Provide a non-blank summary; or
  • Check the “minor changes” checkbox

The Save button is enabled whenever there is a summary in the summary field or whenever the “minor changes” checkbox is checked. Of course, the user may both enter a summary and check “minor changes”, and the Save button will be enabled.

It's possible to modify the code so that a summary is always required, as explained below.

Plugin available

There's also a plugin available, which provides the function: enforcesummary

Dokuwiki 2011-11-10 “Angua”

To install this enhancement, put the following Javascript code into the script.js file in your template directory. You'll need to create the file if it doesn't already exist.

This code uses jQuery, which has been included with Dokuwiki since 2011-11-10 “Angua”. If you are using an older version, you should upgrade (or use the older code for this enhancement, given below).

script.js
jQuery(document).ready(function() {
	minSummaryLength = 15;
	$editButton = jQuery("#edbtn__save");
	$minorEdit = jQuery("#minoredit");
	$summary = jQuery("#edit__summary");
	$summary.keyup(enforceSummary).focus(enforceSummary);
	$minorEdit.change(enforceSummary);
	enforceSummary(); // To disable form submission on page load.
});
function enforceSummary() {
	if ($summary.val() && $summary.val().length < minSummaryLength && !$minorEdit.is(':checked')) {
		$summary.addClass("missing");
		$editButton.attr("disabled", true).css("color", "#999");
	} else {
		$summary.removeClass("missing");
		$editButton.removeAttr("disabled").css("color", "black");
	}
}

Older Dokuwiki versions

To install this enhancement, put the following Javascript code into the script.js file in your template directory. You'll need to create the file if it doesn't already exist.

function installSummaryEnforcement()
{
    var summary_input = document.getElementById('edit__summary');
    if(summary_input !== null)
    {
        var minoredit_input = document.getElementById('minoredit');
 
        addEvent(summary_input, 'change', enforceSummary);
        addEvent(summary_input, 'keyup', enforceSummary);
        addEvent(minoredit_input, 'change', enforceSummary);
        addEvent(minoredit_input, 'click', enforceSummary);
        enforceSummary(); // summary may be there if we're previewing
    }
}
 
function enforceSummary()
{
    var btn_save = document.getElementById('edbtn__save');
    var summary_input = document.getElementById('edit__summary');
    var minoredit_input = document.getElementById('minoredit');
    var disabled = false;
 
    if(summary_input.value.replace(/^\s+/,"") === '' && !minoredit_input.checked)
        {disabled = true;}
 
    if(disabled != btn_save.disabled || btn_save.disabled === null)
    {
        btn_save.className = disabled ? 'button button_disabled' : 'button';
        btn_save.disabled = disabled;
    }
}
 
addInitEvent(function(){installSummaryEnforcement();});

If you want to always require a summary, regardless of whether “minor changes” is checked, replace this line:

    if(summary_input.value.replace(/^\s+/,"") === '' && !minoredit_input.checked)

with this line:

    if(summary_input.value.replace(/^\s+/,"") === '')

The CSS

Most browsers will not give you a visual indication that the button is disabled; they just won't let you click on the button. If you want a disabled Save button to be grayed out, include the following CSS in one of your template's stylesheets:

div.dokuwiki input.button_disabled {
  color: #999;
}

If your template doesn't already have a custom stylesheet, you'll need to create one. You might call it style.css, putting it in your template directory. Add the following to the style.ini file found in the template directory, placing it within the [stylesheets] section of the file (and using your filename, of course):

style.css = screen

Troubleshooting

If you aren't getting the summary enforcement behavior, you may need to clear the cache to have the CSS and Javascript files rebuilt.

Discussion

This is great! I love it. A few problems…

  1. You should place the CSS code for greying out the Save button in conf/userstyle.css, this way it's used for all templates.
  2. For the same reason, you should place the JavaScript code in conf/userscript.js.
  3. It doesn't work if a user is not logged in – they can save without entering the summary, any ideas why?

Thanks again!
Joseph Nahmias 2006-07-26 17:34



Thanks for this nice trick. My suggestions:

  • install it on this wiki!!!
  • add
  cursor: default;

to the css

  • add some explanations to the inc/lang/??/edit.txt file, like
Edit the page, fill the "Edit summary" field and hit ''Save''.
  • it could be nice to add an “alert('Please fill the summary field too.')”, but I'm not good at js enough.
  • I modified the script like below to display an alert box:
function installSummaryEnforcement()
{
        var btn_save = document.getElementById('edbtn__save');
        addEvent(btn_save, 'click', enforceSummary);
}
 
function enforceSummary()
{
        var summary_input = document.getElementById('edit__summary');
        var minoredit_input = document.getElementById('minoredit');
 
        if(summary_input.value.replace(/^\s+/,"") === '' && !minoredit_input.checked)
        {
                alert("No summary entered!");
                return false;
        }
        else
        {
                return true;
        }
}
addInitEvent(function(){installSummaryEnforcement();});


Grahack 2007-06-11 14:59

Grahack - I prefer your version, but it doesnt work for me. It looks like the saveButton's onlick method is overwritten nowadays by DW (in edit.js?)
pike 2008-05-21
Sorry, I won't have time to investigate soon. Did you clear the caches ? — Grahack 2008/05/22 10:47
I tried the version by Grahack, but it had a problem that “preview” would also cause the alert to be shown.
instead, I did following hack to lib/scripts/edit.js:
diff -u -r1.2 edit.js
--- lib/scripts/edit.js	3 Jun 2008 10:17:18 -0000	1.2
+++ lib/scripts/edit.js	30 Jun 2008 16:47:44 -0000
@@ -397,10 +397,24 @@
  */
 var textChanged = false;
 
+// keep state if summary was not entered
+var summary_missing = false;
+var in_save = false;
+
 /**
  * Check for changes before leaving the page
  */
-function changeCheck(msg){
+function changeCheck(msg)
+{
+    if (in_save)
+    {
+        in_save = false;
+        if (summary_missing)
+        {
+            alert("summary must be given to enable save");
+            return false;
+        }
+    }
   if(textChanged){
     var ok = confirm(msg);
     if(ok){
@@ -462,8 +476,8 @@
 
     // reset change memory var on submit
     var btn_save        = document.getElementById('edbtn__save');
-    btn_save.onclick    = function(){ textChanged = false; };
-    btn_save.onkeypress = function(){ textChanged = false; };
+    btn_save.onclick    = function(){ textChanged = false; in_save = true; };
+    btn_save.onkeypress = function(){ textChanged = false; in_save = true; };
     var btn_prev        = document.getElementById('edbtn__preview');
     btn_prev.onclick    = function(){ textChanged = false; };
     btn_prev.onkeypress = function(){ textChanged = false; };
@@ -493,8 +507,10 @@
     var sum = document.getElementById('edit__summary');
     if(sum.value === ''){
         sum.className='missing';
+        summary_missing = true;
     }else{
         sum.className='edit';
+        summary_missing = false;
     }
 }
 

I think a better way to handle this would be to have some variable to indicate what submit button was pressed. Then allow adding validation functions to a vector of validation fucntion. if any of the validation functions fail do not go on with the save operation.

Yaron Yogev 2008/06/30 18:44

I have an alternate version of the enforceSummary function which uses a popup instead

function enforceSummary()
{
    var btn_save = document.getElementById('edbtn__save');
    var summary_input = document.getElementById('edit__summary');
    var minoredit_input = document.getElementById('minoredit');
 
    if(summary_input.value.replace(/^\s+/,"") === '' && !minoredit_input.checked)
    {
        btn_save.onclick=function(e)
        {
            alert("You must enter an edit summary first");
            return false;
        }
    }
}

— James 2011/3/9

Great plugin!

But right now Dokuwiki fills the “Edit Summary” field automatically when someone uses the Section Editing feature (such as right now while I'm editing).

How do I disable this feature, to enforce a really meaningful summary?

— Augusto 2016-03-07

tips/summary_enforcement.txt · Last modified: 2016-03-07 14:20 by 147.65.4.95