← Back to branch summary

~kosova/+junk/tuxfamily-twiki

« back to all changes in this revision

Viewing changes to foswiki/pub/System/JavascriptFiles/foswikiPref.js

  • Committer: James Michael DuPont
  • Date: 2009-07-18 19:58:49 UTC
  • Revision ID: jamesmikedupont@gmail.com-20090718195849-vgbmaht2ys791uo2
added foswiki

Show diffs side-by-side

added added

removed removed

Lines of Context:
foswiki/pub/System/JavascriptFiles/foswikiPref.js
 
1
/*
 
2
Contains:
 
3
Cookie Functions -- "Night of the Living Cookie" Version (25-Jul-96)
 
4
Written by:  Bill Dortch, hIdaho Design <bdortch@hidaho.com>
 
5
The following functions are released to the public domain.
 
6
 
 
7
Refactored for Foswiki by Arthur Clemens 2006.
 
8
*/
 
9
 
 
10
/**
 
11
The preferred way for reading and writing cookies is using getPref and setPref, otherwise the limit of 20 cookies per domain is reached soon. See http://foswiki.org/Support/DataStorageInUserCookie
 
12
*/
 
13
var foswiki; if (foswiki == undefined) foswiki = {};
 
14
foswiki.Pref = {
 
15
        
 
16
        FOSWIKI_PREF_COOKIE_NAME:"FOSWIKIPREF",
 
17
        /**
 
18
        Separates key-value pairs
 
19
        */
 
20
        COOKIE_PREF_SEPARATOR:"|",
 
21
        /**
 
22
        Separates key from value
 
23
        */
 
24
        COOKIE_PREF_VALUE_SEPARATOR:"=",
 
25
        /**
 
26
        By default expire one year from now.
 
27
        */
 
28
        COOKIE_EXPIRY_TIME:365 * 24 * 60 * 60 * 1000,
 
29
 
 
30
        /**
 
31
        Writes data to a user cookie, using key-value notation. If the key already exists, the value is overwritten. If the key is new, a new key/value pair is created.
 
32
        Characters '|' and '=' are reserved as separators.
 
33
        @param inPrefName : (String) name of the preference to write, for instance 'SHOWATTACHMENTS'
 
34
        @param inPrefValue : (String) stringified value to write, for instance '1'
 
35
        */
 
36
        setPref:function(inPrefName, inPrefValue) {
 
37
                var prefName = foswiki.Pref._getSafeString(inPrefName);
 
38
                var prefValue = (isNaN(inPrefValue)) ? foswiki.Pref._getSafeString(inPrefValue) : inPrefValue;
 
39
                var cookieString = foswiki.Pref._getPrefCookie();
 
40
                var prefs = cookieString.split(foswiki.Pref.COOKIE_PREF_SEPARATOR);
 
41
                var index = foswiki.Pref._getKeyValueLoc(prefs, prefName);
 
42
                if (index != -1) {
 
43
                        // updating this entry is done by removing the existing entry from the array and then pushing the new key-value onto it
 
44
                        prefs.splice(index, 1);
 
45
                }
 
46
                // else not found, so don't remove an existing entry
 
47
                var keyvalueString = prefName + foswiki.Pref.COOKIE_PREF_VALUE_SEPARATOR + prefValue;
 
48
                prefs.push(keyvalueString);
 
49
                foswiki.Pref._writePrefValues(prefs);
 
50
        },
 
51
        
 
52
        /**
 
53
        Reads the value of a preference.
 
54
        Characters '|' and '=' are reserved as separators.
 
55
        @param inPrefName (String): name of the preference to read, for instance 'SHOWATTACHMENTS'
 
56
        @return The value of the preference; an empty string when no value is found.
 
57
        */
 
58
        getPref:function(inPrefName) {
 
59
                var prefName = foswiki.Pref._getSafeString(inPrefName);
 
60
                return foswiki.Pref.getPrefValueFromPrefList(prefName, foswiki.Pref.getPrefList());
 
61
        },
 
62
        
 
63
        /**
 
64
        Reads the value of a preference from an array of key-value pairs. Use in conjunction with getPrefList() when you want to store the key-value pairs for successive look-ups.
 
65
        @param inPrefName (String): name of the preference to read, for instance 'SHOWATTACHMENTS'
 
66
        @param inPrefList (Array): list of key-value pairs, retrieved with getPrefList()
 
67
        @return The value of the preference; an empty string when no value is found.
 
68
        */
 
69
        getPrefValueFromPrefList:function(inPrefName, inPrefList) {
 
70
                var keyvalue = foswiki.Pref._getKeyValue(inPrefList, inPrefName);
 
71
                if (keyvalue != null) return keyvalue[1];
 
72
                return '';
 
73
        },
 
74
        
 
75
        /**
 
76
        Gets the list of all values set with setPref.
 
77
        @return An Array of key-value pair pref values; null if no value has been set before.
 
78
        */
 
79
        getPrefList:function() {
 
80
                var cookieString = foswiki.Pref._getPrefCookie();
 
81
                if (!cookieString) return null;
 
82
                return cookieString.split(foswiki.Pref.COOKIE_PREF_SEPARATOR);
 
83
        },
 
84
        
 
85
        /**     
 
86
        Retrieves the value of the cookie specified by "name".
 
87
        @param inName : (String) identifier name of the cookie
 
88
        @return (String) the cookie value; null if no cookie with name inName has been set.
 
89
        */
 
90
        getCookie:function(inName) {
 
91
                var arg = inName + "=";
 
92
                var alen = arg.length;
 
93
                var clen = document.cookie.length;
 
94
                var i = 0;
 
95
                while (i < clen) {
 
96
                        var j = i + alen;
 
97
                        if (document.cookie.substring(i, j) == arg) {
 
98
                                return foswiki.Pref._getCookieVal(j);
 
99
                        }
 
100
                        i = document.cookie.indexOf(" ", i) + 1;
 
101
                        if (i == 0) break; 
 
102
                }
 
103
                return null;
 
104
        },
 
105
        
 
106
        /**
 
107
        Creates a new cookie or updates an existing cookie.
 
108
        @param inName : (String) identifier name of the cookie
 
109
        @param inValue : (String) stringified cookie value, for instance '1'
 
110
        @param inExpires : (Date) (optional) the expiration data of the cookie; if omitted or null, expires the cookie at the end of the current session
 
111
        @param inPath : (String) (optional) the path for which the cookie is valid; if omitted or null, uses the path of the current document
 
112
        @param inDomain : (String) (optional) the domain for which the cookie is valid; if omitted or null, uses the domain of the current document
 
113
        @param inUsesSecure : (Boolean) (optional) whether cookie transmission requires a secure channel (https)
 
114
        @use
 
115
        To call setCookie using name, value and path, write:
 
116
        <pre>
 
117
        foswiki.Pref.setCookie ("myCookieName", "myCookieValue", null, "/");
 
118
        </pre>  
 
119
        To set a secure cookie for path "/myPath", that expires after the current session, write:
 
120
        <pre>
 
121
        foswiki.Pref.setCookie ("myCookieName", "myCookieValue", null, "/myPath", null, true);
 
122
        </pre>
 
123
        */
 
124
        setCookie:function(inName, inValue, inExpires, inPath, inDomain, inUsesSecure) {
 
125
                var cookieString = inName + "=" + escape (inValue) +
 
126
                        ((inExpires) ? "; expires=" + inExpires.toGMTString() : "") +
 
127
                        ((inPath) ? "; path=" + inPath : "") +
 
128
                        ((inDomain) ? "; domain=" + inDomain : "") +
 
129
                        ((inUsesSecure) ? "; secure" : "");
 
130
                document.cookie = cookieString;
 
131
        },
 
132
        
 
133
        /**
 
134
        Function to delete a cookie. (Sets expiration date to start of epoch)
 
135
        @param inName : (String) identifier name of the cookie
 
136
        @param inPath : (String) The path for which the cookie is valid. This MUST be the same as the path used to create the cookie, or null/omitted if no path was specified when creating the cookie.
 
137
        @param inDomain : (String) The domain for which the cookie is valid. This MUST be the same as the domain used to create the cookie, or null/omitted if no domain was specified when creating the cookie.
 
138
        */
 
139
        deleteCookie:function(inName, inPath, inDomain) {
 
140
                if (foswiki.Pref.getCookie(inName)) {
 
141
                        document.cookie = inName + "=" + ((inPath) ? "; path=" + inPath : "") + ((inDomain) ? "; domain=" + inDomain : "") + "; expires=Thu, 01-Jan-70 00:00:01 GMT";
 
142
                }
 
143
        },
 
144
        
 
145
        /* PRIVILIGED METHODS */
 
146
        
 
147
        /**
 
148
        Finds a key-value pair in an array.
 
149
        @param inKeyValues: (Array) the array to iterate
 
150
        @param inKey: (String) the key to find in the array
 
151
        @return The first occurrence of a key-value pair, where key == inKey; null if none is found.
 
152
        */
 
153
        _getKeyValue:function(inKeyValues, inKey) {
 
154
                if (!inKeyValues) return null;
 
155
                var i = inKeyValues.length;
 
156
                while (i--) {
 
157
                        var keyvalue = inKeyValues[i].split(foswiki.Pref.COOKIE_PREF_VALUE_SEPARATOR);
 
158
                        if (keyvalue[0] == inKey) return keyvalue;      
 
159
                }
 
160
                return null;
 
161
        },
 
162
        
 
163
        /**
 
164
        Finds the location of a key-value pair in an array.
 
165
        @param inKeyValues: (Array) the array to iterate
 
166
        @param inKey: (String) the key to find in the array
 
167
        @return The location of the first occurrence of a key-value tuple, where key == inKey; -1 if none is found.
 
168
        */
 
169
        _getKeyValueLoc:function(inKeyValues, inKey) {
 
170
                if (!inKeyValues) return null;
 
171
                var i = inKeyValues.length;
 
172
                while (i--) {
 
173
                        var keyvalue = inKeyValues[i].split(foswiki.Pref.COOKIE_PREF_VALUE_SEPARATOR);
 
174
                        if (keyvalue[0] == inKey) return i;     
 
175
                }
 
176
                return -1;
 
177
        },
 
178
        
 
179
        /**
 
180
        Writes a cookie with the stringified array values of inValues.
 
181
        @param inValues: (Array) an array with key-value tuples
 
182
        */
 
183
        _writePrefValues:function(inValues) {
 
184
                var cookieString = (inValues != null) ? inValues.join(foswiki.Pref.COOKIE_PREF_SEPARATOR) : '';
 
185
                var expiryDate = new Date ();
 
186
                foswiki.Pref._fixCookieDate (expiryDate); // Correct for Mac date bug - call only once for given Date object!
 
187
                expiryDate.setTime (expiryDate.getTime() + foswiki.Pref.COOKIE_EXPIRY_TIME);
 
188
                foswiki.Pref.setCookie(foswiki.Pref.FOSWIKI_PREF_COOKIE_NAME, cookieString, expiryDate, '/');
 
189
        },
 
190
        
 
191
        /**
 
192
        Gets the FOSWIKI_PREF_COOKIE_NAME cookie; creates a new cookie if it does not exist.
 
193
        @return The pref cookie.
 
194
        */
 
195
        _getPrefCookie:function() {
 
196
                var cookieString = foswiki.Pref.getCookie(foswiki.Pref.FOSWIKI_PREF_COOKIE_NAME);
 
197
                if (cookieString == undefined) {
 
198
                        cookieString = "";
 
199
                }
 
200
                return cookieString;
 
201
        },
 
202
        
 
203
        /**
 
204
        Strips reserved characters '|' and '=' from the input string.
 
205
        @return The stripped string.
 
206
        */
 
207
        _getSafeString:function(inString) {
 
208
                var regex = new RegExp(/[|=]/);
 
209
                return inString.replace(regex, "");
 
210
        },
 
211
        
 
212
        /**
 
213
        Retrieves the decoded value of a cookie.
 
214
        @param inOffset : (Number) location of value in full cookie string.
 
215
        */
 
216
        _getCookieVal:function(inOffset) {
 
217
                var endstr = document.cookie.indexOf (";", inOffset);
 
218
                if (endstr == -1) {
 
219
                        endstr = document.cookie.length;
 
220
                }
 
221
                return unescape(document.cookie.substring(inOffset, endstr));
 
222
        },
 
223
        
 
224
        /**
 
225
        Function to correct for 2.x Mac date bug.  Call this function to
 
226
        fix a date object prior to passing it to setCookie.
 
227
        IMPORTANT:  This function should only be called *once* for
 
228
        any given date object!  See example at the end of this document.
 
229
        */
 
230
        _fixCookieDate:function(inDate) {
 
231
                var base = new Date(0);
 
232
                var skew = base.getTime(); // dawn of (Unix) time - should be 0
 
233
                if (skew > 0) { // Except on the Mac - ahead of its time
 
234
                        inDate.setTime(inDate.getTime() - skew);
 
235
                }
 
236
        },
 
237
 
 
238
    // Set to true to suppress mandatory field validation on save
 
239
    // (see foswiki_edit.js)
 
240
    validateSuppressed : false
 
241
}