2009
New jQuery Plugin dirtyFields: Bring Attention to Changed/Unsaved Fields
JavaScript , jQuery , Web development Add commentsI just finished a project that included an administrative page where users could make changes to a parent record and numerous child records via multiple forms. All of the form submissions were done via AJAX, so I needed a way to illustrate which of the forms on the page contained changed or "dirty" data, and which forms had no unsaved changes.
This dirtyFields plugin is derived from the functions I wrote to handle that task in that project.
It applies a CSS class to a contextual DOM element associated with any form field that has been changed from its original value. For text inputs, <textarea>, and <select> elements, the <label> element associated with the field (via the "for" attribute) will be styled with the class. For <checkbox> and <radio> elements, you can specify the text associated with each element using "checkboxRadioTextTarget" plugin option (the default setting is "next span").
It works by storing the current value or state of each form field within the data store of the field using the jQuery data() function.ﾠ As the value or state of the form field is changed, its current value/state is compared to the one within its data store, and if they aren't equal the field is considered "dirty".ﾠ The plugin includes a function called "resetForm" that can be used after the form has been submitted to update the data store of each field with the new field value and mark all the form fields as clean.ﾠ There is also an option to apply a CSS class to the form itself to indicate whether or not it contains dirty fields.
(UPDATE: I've now added support for a "formIsDirty" callback function that can be used in conjunction with the "denoteFormDirty" option to run your own functions once a form has been determined to be clean or dirty.)
Links to a demo and to a downloadable .zip file containing both a document, un-minified version and a minfied version of the plugin can be found below the following screenshot, which shows the style changes to the labels and text of form elements that have been changed:
Aug 25, 2009 at 4:45 PM Brian,
I have a function that does several things to a page as soon as anything in the form is dirty. Can you model for me how to connect that to your plugin?
For example, as soon as a form is dirty, I want to disable links that would navigate away from the form, and enable a default-disabled "Save Changes" button. Thanks.
Aug 26, 2009 at 7:48 AM @BogeyBill: The current version of the plugin doesn't have any callbacks built into it, so there's not a way to "connect" the plugin to your current functions such that the execution of a plugin function triggers your functions to run (or vice-versa).
However, depending on how your functions are designed, it might be possible to run the plugins and your functions in parallel.
Aug 26, 2009 at 9:59 PM @BogeyBill: I just uploaded a new version of the plugin that has a "formIsDirty" callback function you can use to trigger your code for disabling links and enabling/disabling the submit button. So go ahead and download it and see if that works for your.
Aug 28, 2009 at 7:55 AM @Uday: using the "formIsDirty" callback is simply a matter of defining your callback function and passing it into the plugin as a setting. The callback returns the form as a jQuery object ("$(this)") and a Boolean value denoting if the form is dirty (true) or not (false). Here's an example of how to add the callback as a setting:
var settings= {
formIsDirty: function(result) {
if(result)
{
$(this).css("border","3px solid blue");
}
else
{
$(this).css("border","1px solid #ccc");
}
}
};
$("form").dirtyFields(settings);
...However, having said all that, I don't think my plugin is going to help you to send only dirty form fields back to the server. The plugin doesn't keep track of which form fields are currently dirty, and it applies the CSS class to the labels and text nodes that provide names and context to the form fields, not the form fields themselves, so you couldn't write a jQuery selector to go find the dirty fields based on that CSS class.
It might be worth adding that sort of functionality to the plugin. I'll think about it.
Aug 30, 2009 at 12:12 PM @Uday: I've updated the plugin to include a new callback that is executed every time a field is changed, and changed the formIsDirty plugin to include an array with the names of all the form fields that are "dirty"/have been changed. That should help you with what you want to do.
I've written a documentation page that covers everything about the plugin now. It's at:
http://www.thoughtdelimited.org/thoughts/page.cfm/demos-downloads/dirtyfields-jquery-plugin-documentation
The download file has also been updated with these changes.
Sep 13, 2009 at 10:44 AM I like to use it for a form but is there a way to set it to 'dirty' by default? So nothing is changed in the form but I want to force that it is saved first.
Sep 13, 2009 at 11:59 AM @Oscar: If you're willing to have one or more of the form fields be marked as dirty, it could be done...
1. In the HTML code, set the starting value of one or more of the form elements to a blank string (""). And give the form the CSS class that indicates that the form is dirty.
2. After you apply the plugin to the form, use jQuery functions to set the values of the form elements in step 1 to what you really want for the starting values.
3. Since the new values of those form elements don't match the values they had when the plugin was applied to the form, the fields will be considered dirty, and hence the form will remain dirty.
...Not a perfect solution, admittedly, but it's the best I can think of. I'm not sure why you would want to force/encourage users to save the initial form right away, before they even make changes to it.
Sep 13, 2009 at 2:57 PM Thanks for the info! I will try it.
Why I need it is rather a long story. But I work with forms in tabs and must have something to prevent switching tabs when a new item is created. Not very clear but this is it in a nutshell..;) Thanks again!
Sep 13, 2009 at 4:15 PM Well it's not working.
I do exactly your 3 steps but the callback function is never called.
Oscar
Sep 13, 2009 at 9:08 PM @Oscar: I assume you mean the "formIsDirty" callback? Hmm. If you've configured that callback, it should run every time a field is changed, regardless of whether or not the form is dirty. But the callback will only work if the denoteFormDirty option is set to true (by default, it's set to false).
Oct 1, 2009 at 7:35 AM Announcement: I've released a more powerful and more flexible version of the dirtyFields plugin. It now has it's own website, where you can learn more about it: http://www.thoughtdelimited.org/dirtyFields.
Nov 15, 2011 at 4:20 PM FYI - The download page is giving me a "HTTP Error 404 - File or directory not found." :(
Nov 16, 2011 at 7:26 AM @Jim: I'll look into that download issue. In the meantime, you can also get it from GitHub: https://github.com/bcswartz/dirtyFields-jQuery-Plugin
Nov 16, 2011 at 7:40 AM @Jim: Regular download link should work now.
Jun 23, 2012 at 4:50 PM Hi Brian,
I am new to JQuery , when I came accross this plugin, it's really good. I have few questions around this plugin.
1. If application form is having more number of elements, will there be any performance issue?
2. Text input fields are not making form dirty untill and unless they are un-foucus, Is there any way to make them dirty when value is changing?
3. Is there any limitation with any browsers?
4. Plug-in is able to identify any dyanamically added element with changed value, But I want to mark form as dirty even any element is added dyanamically with default value, Can you plz tell me , how I can do that?
5. If we want to escape few elements, marking as dirty , How I can achive that?