Documentation

Code Walk-Through

If you elect to include the jQuery link Step 5, the code will begin with that.

<script type="text/javascript" src="//ajax.googleapis.com/ajax/libs/jquery/1.7.2/jquery.min.js"></script>

JQuery is a JavaScript library that provides additional features, and it is required for this plugin to work properly. However, it is very common — so you might have another plugin or tool that is already providing it to your site. That’s why including it here is optional.

Most of the functionality of the plugin is built into a single JavaScript file, which you do not have to add to your site — this code imports it for you.

<script type="text/javascript" src="//privacypolicies.com/cookie-consent/releases/latest/cookie-consent.js"></script>

If you really want to see that code, or download it and host it yourself, you can do so here.

Your Customized Options

The Cookie Consent plugin implements your site-specific options (which you choose in the form on the homepage) here. This part will look different depending on what options you selected.

The options are found inside the $.cookieconsent object.

<script type="text/javascript"> $(function(){ var cookieconsent = $.cookieconsent({ // This is where options can be manually added. // // Options should be listed one-to-a-line, // with option name first, then a colon, // then the option, then a comma. // // If the option value is a string, // it should be wrapped in 'single quotes'. // default_level_id: 'level-two-permissions', edit_settings_element: $('#edit-cookieconsent-settings'), // // // The levels option is an array of level definitions, based on your input in the form. // // If you do not specify any custom levels, this option will not appear. // levels:[ { id: 'strictly-necessary-and-performance', title: 'Strictly necessary & Performance', permissions: ['Remember what is in your shopping basket', 'Remember how far you are through an order'], callback: function(){ /* put your level code here. This is the base level and will be executed on every page load. */ } }, { id: 'level-two-permissions', title: 'Level Two Permissions', permissions: ['Do something with a cookie', 'Do something else with a cookie'], callback: function(){ /* put your level code here. */ } } ] }); }); </script>

Level-specific code

You can add code that will only be executed if the use selects a particular level, or higher. This is place inside the curly brackets at:

callback: function(){ /* put your level code here. */ }

Adding options

You can add more options into the $.cookieconsent() object. Just add them, one per line, after the edit_settings_element: line.

The available options are listed below. Make sure your options take the following form:

option_name: option value,

If the option value is a string (an exact line of text), it should be in single-quotes. Option values can also be numbers, functions, or booleans (true / false values).

After each name: value pair, use a comma to separate it from the next pair.

Full List of Options

The following options can be added to the $.cookieconsent() object, as described above.

autorun

type
boolean
default
true

The popup runs automatically, but you can force it to wait by setting the autorun value to false. You might want to do this if you need to modify configuration after instantiation, but before initializaiton.

If you have autorun set to false, you must call the cookieconsent.run(); method later, when you want the pop-up to actually occur.

Example

Set the contents of a level’s callback function outside of the options:

var cookieconsent = $.cookieconsent({ // ... autorun:false, // ... }); cookieconsent.get_levels()[1].callback = function(){ /* tracking or analytics code here */ }; cookieconsent.run();

cookieconsent_css_filepath

type
string
default
the CSS file hosted on our website

If you would like modify the way that the plug-in looks/feels, this option allows you to specify where the CSS file is located on your website.

You can also use the JQuery Theme Roller to created your themed CSS. See the option below for more details.

type
a JS Date() object
default
365 from the current date

This sets the expiration date for cookie(s) set by the plugin.

type
string
default
'cookie_consent_level'

The plugin sets a cookie in the user’s browser, with the name of the selected Cookie Consent level as the value. You can adjust the name of the cookie here.

type
string
default
the text shown in the demo

This html is shown in the popup when a user first lands on the website. You can see it live on the homepage of this site.

type
integer
default
10

The time in seconds that the popup will be displayed before being automatically hidden.

Set this value to 0 (zero) to prevent auto-hiding.

type
string
default
empty

By law, you must have a page on your site explaining how cookies are used on your site and how you manage personal data.

If this property is not supplied here, you should have a link elsewhere on your website.

default_level_id

type
string
default
determined by form selection

Required, if you have created your own set of levels.

This option only appears in the generated code if you have added your own permission levels in the form — but you can add it if you want to change the default level while using the default set of permission levels.

The value should match the id value of one of the level definitions.

edit_settings_element

type
string (element selector string or JQuery object)
default
determined by form selection

Required.

You need to provide a link to the Edit Setting window on every page of your site (usually in the footer).

This option specifies an element on the page (usually by ID) which will be turned into a clickable link by the plugin. Clicking on the element will open the Edit Settings panel.

You should add some link text into the element explaining what the link does. If you leave the element empty, the plugin will add some link text for you.

You can either supply a jQuery object ( $('#my-button') ) or a selector string ( '#my-button' ).

edit_settings_intro

type
string
default
the text shown in the demo

This is the user-facing explanatory text in the Edit Settings panel.

jqueryui_theme_css

type
string
default
determined by form selection

This plug-in is geared towards using existing CSS classes defined in jQuery UI themes, which enables super-fast skinning.

You can select one of their existing themes in Step One of the form on the homepage, or you can use the jQueryUI Theme Roller to easily create your own.

If you choose to create your own, you’ll need to download the created CSS and host it on your site. Then, put the URL of that CSS file in this option.

levels

type
array
default
four levels as shown in demo

This array of values will only appear if you use the builder to create your own set of levels.

Each item in the array needs to have the following options:

Each level can also have another option:

Example

levels: [ { id: 'level-1', title: 'level 1', permissions: ['Foo', 'Bar'], callback: function(){ alert('hello'); } }, { id: 'level-2', title: 'level 2', permissions: ['Hey', 'Ho'], callback: function(){ alert('world'); } }, { id: 'level-3', title: 'level 3', permissions: ['Something'], callback: function(){ alert('woof'); } } ]

If the user had chosen level-2 in their settings (or if level-2 was the default_level_id option value) the user would get two alerts: - 'hello' - 'world'

In this case, the callback for level-3 would not be executed, because it is “higher” than the first two.

Important Note: If the user has used the Magic Button (consenting to cookies on all sites that use Cookie Consent), every level’s callback function will be called.

on_change

type
function
default
empty function

A function that is called whenever the permission level changes.

By default, the plug-in does not execute any of the level callbacks when the user clicks a button. However you can use the on_change function to do this, as shown in the code below.

on_change: function(){ var saved_level = cookieconsent.saved_level(); saved_level.callback(); }

(This code assumes that your local variable name for the plug-in is cookieconsent, as shown on the homepage.)

type
string (element selector string or JQuery object)
default
the <body> element

This specifies the HTML element to which the popup is appended.

You can either supply a jQuery object (for example: $('#body') ) or a selector string ( for example: #container ).

Methods

These are all methods of the cookieconsent object.

.edit_settings()

Opens the edit settings dialog.

.get_level(level_id)

Returns the level object which has the ‘id’ supplied in the level_id parameter.

.get_levels()

Returns all of the levels in an array.

.is_granted(level_id)

Returns a boolean which states whether the level who’s id is suppled is allowed to be executed.

See the ‘levels’ option above for a more in-depth description of how levels work.

.run()

Initialises and fires up the plugin. To be used in conjuntion with the ‘autorun’ option.

.saved_level()

Returns the level object that the user currently has set.

.select_level(level_id)

Sets the current level. The level parameter can be a level id or the level object itself.

Additional Features

The Magic Button

The Cookie Consent pop up has a special feature built in that helps the whole network of sites that use the plugin: the Magic Button.

This can be seen in the home page demo if you click the Not Concerned About Cookies button. You’ll see an extra options panel on the Edit Settings page explaining the Magic Buttons. This enables the user to elect to allow cookies on all sites that use the Cookie Consent button.

If the user has made that selection on any site in the Cookie Consent network, they will not see the popup on your site. Furthermore, the highest permission level of cookies will be set, along with the relevant callback functions being run.

CSS Classes

In addition to the options and methods above, you have further ways to modify the look and feel of the Cookie Consent plug-in, as many of the elements used have CSS class names that you can use in your own style sheets for customization.

You can use your favorite DOM inspector (such as Firebug) to peek at what’s classed up and how.