; Copyright (c) 2012 Mike Green <myatus@gmail.com>
;
;For the full copyright and license information, please view the LICENSE
;file that was distributed with this source code.

[overview]
content = "<p>This screen provides access to the Cookillian settings, where you can customize how the Cookillian filters cookies and appears on your website.</p>

<p>Cookillian can automatically add new or unknown cookies to the <strong>Cookies</strong> list, which helps you identify cookies being used throughout the website. The <strong>Cookies</strong> list can also be retrieved using the <code>[cookillian cookies]</code> shortcode, or filtered by a specific group using <code>[cookillian cookies=\"group name\"]</code>. This eases the task of providing the visitor with details about the cookies used throughout the website.</p>

<p>To increase the user experience of your website, only visitors from selected countries will have their cookies filtered and be alerted about the use of cookies. Cookillian can use the geoPlugin service to determine the visitors' geographic location. If you are a CloudFlare subscriber, you may wish to use CloudFlare's own geolocation service to benefit of a significant increase in speed.</p>

<p>An alert can be displayed automatically, or you can insert the HTML code for the alert manually by editing your theme and inserting <code>&lt;?php cookillian_insert_alert_block(); ?&gt;</code> at the desired location. Alternatively, you can use the <code>[cookillian alert]</code> shortcode within a post, page or other WordPress element that supports shortcodes. The default alert text can be altered to suit your website's needs, or alternatively you can provide your own HTML code for full customization.</p>

<p>If the visitor has permitted the use of cookies, additional JavaScript can be loaded at the header and/or footer using the two provided fields. As an example, this could be used to load analytics scripts that make use of cookies to track the visitor. For more complex use of JavaScript, select the <strong>JavaScript</strong> help tab.</p>

<p>PHP sessions based on cookies are filtered unless they are required. Many plugins will use WordPress' own session handling methods, however, if the website is tightly integrated with other web applications then you may need to disable the filtering.</p>

<p>An optional <em>Debug Mode</em> allows logged-in users to see the alert in action, to assist with designing a website. Additional debug information can be viewed in the JavaScript console, ie. using FireBug.</p>"

[html]
title = "Custom Alert"
content = "<p>When creating a custom alert, you can provide the visitor the option to permanently opt in to receive cookies, or opt out. To do so, simply direct the visitor to any page adding to the URI <code>?cookillian_resp=1</code> to opt in or <code>?cookillian_resp=0</code> to opt out. This could be done with a link as simple as <code>&lt;a href=\"\?cookillian_resp=1\"&gt;Opt In&lt;/a&gt;</code>.</p>

<p>Once the opt in/out preference has been saved in the cookies <code>cookillian_opt_in</code> or <code>cookillian_opt_out</code> respectively, the visitor will be returned to the original page from which the request was made.</p>

<p>For exampes of different alert styling, please visit the <a href=\"http://myatus.com/projects/cookillian\" target=\"_blank\">official website</a>.</p>

<p><strong>Tip:</strong> If you wish to provide the option for a visitor to change their opt-in or opt-out choice, add the <code>?cookillian_resp=2</code> to the URI. This will reset the previous choice and the visitor will be asked again subsequently.</p>"

[javascript]
title = "JavaScript"
content = "<p>Cookillian provides a simple method to add JavaScript when cookies are permitted. However, if your circumstances require more complex use of JavaScript, Cookillian also exposes several JavaScript variables that can be used:</p>

<ul>
    <li><code>cookillian.blocked_cookies</code> - A boolean statement that is set to <code>true</code> if cookies are blocked / not permitted, or <code>false</code> if cookies are accepted / permitted.</li>
    <li><code>cookillian.deleted_cookies</code> - A boolean statement that is set to <code>true</code> if cookies were deleted by the plugin. If the <em>Advanced Options</em> specifies that cookies need to be deleted <em>after</em> a visitor has opted out, or if <em>Debug Mode</em> is used, this value should be used in conjunction, or instead of <code>cookillian.blocked_cookies</code></li>
    <li><code>cookillian.opted_out</code> - A boolean statement, which is set to <code>true</code> if the visitor has specifically opted <em>out</em> of cookies (and thus <code>cookillian.blocked_cookies</code> will also be <code>true</code>).</li>
    <li><code>cookillian.opted_in</code> - A boolean statement, which is set to <code>true</code> if the visitor has specifically opted <em>in</em> of cookies (and thus <code>cookillian.blocked_cookies</code> will be <code>false</code>).</li>
    <li><code>cookillian.implied_consent</code> - A boolean statement, which is set to <code>true</code> if the visitor has opted <em>in</em> by means of implied consent. This should be used in conjunction with <code>cookillian.opted_in</code>.</li>
</ul>

<p>Cookillian also provides a few helper functions. These are synchronous AJAX calls, in that they can be performed without leaving the web page. These functions are:<p>

<ul>
    <li><code>cookillian.deleteCookies()</code> - Deletes all detected cookies, except those that are required for the website to operate.</li>
    <li><code>cookillian.optIn()</code> - Opts a vistor in, allowing the visitor to receive cookies.</li>
    <li><code>cookillian.optOut()</code> - Opts a visitor out, blocking cookies. <em>Note:</em> this will not delete any existing cookies until the next call or unless used in conjunction with <code>cookillian.deleteCookies()</code>.</li>
    <li><code>cookillian.resetOptinout()</code> - Resets the visitor's opt in or opt out preference.</li>
</ul>

<p><strong>Note:</strong> When Asynchronous AJAX initialization is enabled, before using the variables, wait for the document events <em>cookillian_load</em> (immediately called after initializing the variables) or <em>cookillian_ready</em> (called after variables have been initialized and the document is ready).</p>

<p>The helper function <code>cookillian.insertString(where, true_string, false_string, tf_value)</code> will make it easier for inserting arbitrary strings, including <code>&lt;script></code> tags, regardless Asynchronous AJAX is used. It accepts the following parameters:</p>

<ul>
    <li><code>where</code> - A CSS selector for the element where the string should be inserted</li>
    <li><code>true_string</code> - A string to insert when <code>tf_value</code> is true</li>
    <li><code>false_string</code> - A string to insert when <code>tf_value</code> is false</li>
    <li><code>tf_value</code> - Either a boolean, or a string that refers to one of Cookillian's variables, i.e. <code>\"blocked_cookies\"</code></li>
</ul>
"

[PHP]
title="PHP API"
content = "<p>Cookillian provides an API functions to help customize the website using PHP. They can be used by plugins or the WordPress theme to respond to various situations where the visitor has opted in, out or not yet decided about cookies:</p>

<ul>
    <li><code>cookillian_get_alert_block()</code> and WordPress filter <code>cookillian_alert</code> - Retrieves the alert block as defined by the plugin user. This is a full <abbr title=\"Hypertext Markup Language\">HTML</abbr> block.</li>
    <li><code>cookillian_insert_alert_block()</code> - As above, but prints (echo) the alert block immediately.</li>
    <li><code>cookillian_blocked_cookies()</code> - Returns a boolean, indicating if cookies are to be blocked (true) or not (false). This may not neccesarily mean cookies have been deleted, depending on the <em>Advanced Option</em> for <em>Delete Cookies</em>.</li>
    <li><code>cookillian_deleted_cookies()</code> - Returns a boolean, indicating if Cookillian attempted to delete all cookies (except required cookies) if set to true.</li>
    <li><code>cookillian_opted_in()</code> - Returns a boolean, indicating if the visitor has specifically opted <em>in</em> (true) or not (false).</li>
    <li><code>cookillian_opted_out()</code> - Returns a boolean, indicating if the visitor has specifically opted <em>out</em> (true) or not (false).</li>
    <li><code>cookillian_implied_consent()</code> - Returns a boolean, indicating if the visitor has opted in by means of implied consent (true) or not (false). Generally used in conjunction with <code>cookillian_opted_in()</code>.</li>
    <li><code>cookillian_do_delete_cookies()</code> - Function that deletes the visitor's cookies.</li>
    <li><code>cookillian_do_opt_in()</code> - Function that programatically opts the visitor <em>in</em> of receiving cookies.</li>
    <li><code>cookillian_do_opt_out()</code> - Function that programatically opts the visitor <em>out</em> of receiving cookies.</li>
    <li><code>cookillian_do_reset_optinout()</code> - Function that resets the visitors opt in or out preferences.</li>
</ul>

<p><strong>Note:</strong> the PHP return values are <u>invalid</u> when a caching plugin such as <em>WP Super Cache</em> or <em>W3 Total Cache</em> is used. Please use the JavaScript variables in such cases.<p>"

[maxmind]
title = "MaxMind"
content = "<p>Cookillian supports the MaxMind GeoIP Country and GeoLite Country databases, as well as output from its <a href=\"http://www.maxmind.com/app/mod_geoip\" target=\"_blank\">GeoIP Apache module</a> or <a href=\"http://wiki.nginx.org/HttpGeoipModule\" target=\"_blank\">NginX GeoIP Module</a>.<p>

<p>For maximum performance, the preferred method is the Apache module or NginX GeoIP Module as these can handle requests up to millions per second. However, Cookillian can use a local database directly, which may still provide faster and more reliable geolocation services opposed to using a remote service.</p>

<p>To use the local database, first obtain the required <strong>Binary Format</strong> files from <a href=\"http://www.maxmind.com/app/geolitecountry\" target=\"_blank\">MaxMind</a>. You can then use the specified option on the <strong>Settings</strong> page to upload the <em>GeoIP.dat</em> (IPv4) and <em>GeoIPv6.dat</em> (IPv6) files. It is possible to compress each individual database prior to uploading, using the ZIP format.</p>"

[side_tab]
content = "<p><strong>For more information:</strong></p>

<p><a target=\"_blank\" href=\"http://myatus.com/projects/cookillian/\">Cookillian Home Page</a></p>

<p><a target=\"_blank\" href=\"http://wordpress.org/support/plugin/cookillian\">Support Forum</a></p>

<p><a target=\"_blank\" href=\"http://www.geoplugin.net\">GeoPlugin</a></p>

<p><a target=\"_blank\" href=\"http://www.cloudflare.com\">CloudFlare</a></p>

<p><a target=\"_blank\" href=\"http://www.maxmind.com\">MaxMind</a></p>"