(Yet Another Cookie Script)
Version 1.01
Date: April 2001
Download
the most recent version: http://www.welkweb.com/scripts/download/download.pl?task=YACS
(C) MD 2001 - redistribution and/or
modifications allowed under the terms of the GNU General Public License.
Any
reactions, questions, suggestions, bugreports etc. welcome at yacs@welkweb.com
YACS (Yet Another Cookie Script) provides a complete JavaScript tool to easily create, read and modify cookies on the client side. The advantage of YACS is the fact that it takes named arguments, wich makes manipulating your data quite easy.
Browser compatibility
I've tested the script with IE 4+ and NN 4+ on a Windows 98 platform. It assumably works fine with any version>3 browser. (wich probably covers over 99% of all currently used browsers)For general information on the subject of cookies I'd suggest reading http://developer.netscape.com/docs/manuals/js/client/jsref/cookies.htm
The method 'exist()' didn't work properly in version 1.0 due to a mistype in the script, assumably made after the final test. Works fine now
Insert something like the next line into the <HEAD> section of your HTML code:
<script language=javascript src=path to YACS>
So when YACS is in your HTML directory the line would read:
<script language=javascript src=yacs.js>
Having done this, you can create a new cookie object anywhere in the <BODY> section of the HTML code with:
<script>
var some_variable = new Cookie("cookiename");
</script>What this statement does, is:
create a new cookie object and a handle to it named 'some_variable'
look for a cookie with the specified name on the clients harddisk
If it finds one, initiate the cookie object with the values from the found cookie
Next you can apply any of the methods to the cookie object.
Applying methods to the just created cookie object is won't mean any problem to anyone familiar with JavaScript. The general form for applying methods to objects is:
objectname.methodname([argument 1][,argument 2][...][,argument n]);
in wich everything between [] may be optional (depending on the method).
This current version of YACS (version 1.0) has 5 methods, wich doesn't seem much but wich will prove to do everything you'll want to be able doing.
method: get()
This method can be discussed in a few lines: it retrieves a cookie from the client's harddisk. The only sensible argument (the name of the cookie to be retrieved) can be ommited as it's already known by the cookie object.
Note: at defining a cookie object, wich is what you do by saying:
var some_variable = new Cookie('cookiename')
the get() method is called automatically by the object constructor, making all values of the particular cookie accessible to your script. So there's little chance you will ever actually use the get() method.
method: set()
The script's major method. With this method you write the cookie to the client's harddisk, set the contents of the cookie (as one single value or as a set of different named values), the expiringdate, path and domain.
set() knows 4 arguments that are all optional:
About the notation
I have chosen to let the script (only) take (some form of) named arguments. Note this:
Each argument must be enclosed by quotes and within the argument the value part must either again be enclosed by quotes or be preceded by a '/' (slash) if it's a string.Example
set("an_argument=/Hello World","another_argument=myVariable");
The advantages of this notation are clear: all arguments are optional and order doesn't matter. For the value argument it opens the road to using multiple name/value pairs.
Arguments to set()
I'll discuss the value arument comprehensively and the expire argument shortly, after which the others will speak for themselves.value
The actual contents of the cookie.
There are 2 ways in wich the value argument can be applied:some_cookie.set(value=some_value);
or
some_cookie.set(value=name1->value1,name2->value2,name3...etc);
As said before, values that are strings go between quotes or are preceeded by a slash. In the first (above) case that could be some_value and in the second value1 and value2 etc.
Example
<script>
subj="small animals";
some_cookie = new Cookie('data');
some_cookie.set("value=subject->subj,names->'mice cats dogs',url->location.href");
</script>
To retrieve any of the values in the cookie (in the above case): see the Properties section
expire
Denotes the time period before the cookie outdates.
+<number>Y sets expiring date to <number> years ahead of the current time.
+<number>D sets expiring date to <number> days ahead of the current time.
The same goes for (H)ours, M(inutes) and (S)econds.Example
The next example will set a cookie with the name "someName", the value "Just an example" and the cookie expires after 1 hour 10 minutes and 30 seconds.
<script>
myCookie = new Cookie("someName");
myCookie.set("value=/Just an example","expire=/+1H+10M+30S");
<script>
Take note of the fact that the value of expire is a string so it should be enclosed by quotes or be preceded by a slash.
path, domain
After having read about the use of the value argument and the expire argument, these two speak for themselves. Remember that both the path and the domain values are strings so must be enclosed by quotes or preceded by a slash.
By default domain is set to the current domain and path is set to '/'.
method: exist()
function to check the existence of a cookie. Returns 1 if the given cookie exists and 0 if it doesn't.
Example
<script>
a = new Cookie('niceCookie');
if(a.exist())
{c = a.values.counter;
c++;
a.set("value=counter->c","expire=/+1Y");
}
else
{a.set("value=counter->1","expire=/+1Y"}
</script>
function: accept()
Tests if the used browser accepts cookies. If it does, the function returns 1 and if it doesn't the function returns 0.
As this function concerns the browser and not a particular cookie, you needn't apply it to a cookie object.Example
<script>
if(accept())
{a="This browser accepts cookies"}
else
{a="This browser doesn't accept cookies"}
document.write(a);
</script>
function: del()
Deletes the cookie to wich this method is applied.
Example
<script>
myCookie=new Cookie("data");
myCookie.del();
</script>
Properties summary
After retrieving a cookie you -of course- want to access it's properties (variables) in order to retrieve the information you need. Following a summary of the cookie-object's properties.
read
write
<objectname>.name
name of the cookie
x <objectname>.value
the entire string you assigned to value at setting the cookie
x x <objectname>.values.<valuename>
In case you used multiple values each of them can be accessed by filling in the <valuename> you used
x x <objectname>.expire
the expiringdate of the cookie
x x <objectname>.path
path you assigned to the cookie x x <objectname>.domain
domain you assigned to the cookie x x <objectname>.scriptName
filename of the script that set the cookie x <objectname>.sinceLast
Number of milliseconds since the cookie was last set
x <objectname>.cookieDate
Date & time the cookie was last set
x currentDate Current date (day month dd yyyy) x currentTime Current time (hh:mm:ss) x
Example
...soon to come...