Add ".noConflict()" to prevent conflict with third party scripts

tomsouthall · FagnerMartinsBrack · commit a105e27b63eb · 2015-04-21T16:36:50.000-03:00
Closes js-cookiegh-24.
diff --git a/README.md b/README.md
@@ -82,6 +82,18 @@ Cookies.remove('name', { path: '/' }); // => true
 
 *Note: when deleting a cookie, you must pass the exact same path, domain and secure options that were used to set the cookie, unless you're relying on the default options that is.*
 
+## Namespace conflicts
+
+If there is any danger of a conflict with the namespace `Cookies`, the `noConflict` method will allow you to define a new namespace and preserve the original one. This is especially useful when running the script on third party sites e.g. as part of a widget or SDK.
+
+```javascript
+// Assign the js-cookie api to a different variable and restore the original "window.Cookies"
+var Cookies2 = Cookies.noConflict();
+Cookies2.set('name', 'value');
+```
+
+*Note: The `.noConflict` method is not necessary when using AMD or CommonJS, thus it is not exposed in those environments.*
+
 ## Configuration
 
 ### raw
diff --git a/src/js.cookie.js b/src/js.cookie.js
@@ -18,7 +18,12 @@
 		module.exports = factory(jQuery);
 	} else {
 		// Browser globals
-		window.Cookies = factory(window.jQuery);
+		var _OldCookies = window.Cookies;
+		var api = window.Cookies = factory(window.jQuery);
+		api.noConflict = function() {
+			window.Cookies = _OldCookies;
+			return api;
+		};
 	}
 }(function ($) {
 
diff --git a/test/index.html b/test/index.html
@@ -5,6 +5,7 @@
 		<title>JavaScript Cookie Test Suite</title>
 		<link href="http://code.jquery.com/qunit/qunit-1.14.0.css" rel="stylesheet">
 		<script src="http://code.jquery.com/qunit/qunit-1.14.0.js"></script>
+		<script>Cookies = 'existent global'</script>
 		<script src="../src/js.cookie.js"></script>
 		<script src="polyfill.js"></script>
 		<script src="tests.js"></script>
diff --git a/test/tests.js b/test/tests.js
@@ -362,3 +362,15 @@ test('read converter with raw = true', function() {
 	Cookies.set('c', '1');
 	strictEqual(Cookies.get('c', Number), 1, 'does not decode, but converts read value');
 });
+
+module('noConflict', lifecycle);
+
+test('do not conflict with existent globals', function() {
+	expect(2);
+	var Cookies = window.Cookies.noConflict();
+	Cookies.set('c', 'v');
+	strictEqual(Cookies.get('c'), 'v', 'should work correctly');
+	strictEqual(window.Cookies, 'existent global', 'should restore the original global');
+	window.Cookies = Cookies;
+});
+
