Skip to content

Latest commit

 

History

History
100 lines (88 loc) · 3.59 KB

service_management.md

File metadata and controls

100 lines (88 loc) · 3.59 KB

Service Management

Service management is split in two different parts:

  1. Service / script embedding
  2. Listing of a service in the Modal

This gives you the freedom to define these two things independently from each other (add multiple scripts with the same identifier or add a script to the template directly and just define it in klaro).

Require Files or Scripts

We built silverstripe-klaro to match the pattern of the regular silverstripe requirement process. In order to add scripts to a page, you can use the following functions:

use Syntro\SilverstripeKlaro\KlaroRequirements;

// Add a javascript file
KlaroRequirements::klaroJavascript('path/to/file.js', 'myservice');
// Add a css file
KlaroRequirements::klaroCss('path/to/file.css', 'myservice');
// Add a custom script
KlaroRequirements::customKlaroScript(<<<JS alert('hello') JS, 'myservice');

The API is very similar to the original javascript(), css() and customScript() with the only real difference being the addition of the second argument which states the name (or id) of the service which klaro uses to enable it.

Define Services and Purposes

Klaro works by using a set of services and grouping those via purposes. You can add new services and purposes by adding them via yaml config:

Syntro\SilverstripeKlaro\Config:
    klaro_purposes:
        mypurpose:
            title: My Purpose
            description: This is my purpose
    klaro_services:
        myservice:
            title: My Service
            purposes: [ 'mypurpose' ]

Each service can be configured using the options available:

  • title* : (string) the title of the service
  • purposes* : (string[]) purposes this service is listed under
  • description : (string) the description of the service
  • default : (boolean) specifying the state in the selection modal
  • cookies : (string[]|array[]) cookies used by the service, see https://kiprotect.com/docs/klaro/annotated-configuration
  • required : (boolean) specify if this service is required
  • optOut : (boolean) make this service opt out
  • onlyOnce : (boolean) load this service only once
  • extDependsOn : (array) make this service dependent on the ones in the array

Each Purpose can be configured with a title and a description.

Cookies

Klaro can manage cookies set by other scripts (removing present cookies). For this, you can specify the cookies key in the service configuration. you can specify strings or an array of 3 strings (read the klaro docs for info):

Syntro\SilverstripeKlaro\Config:
    klaro_services:
        myservice:
            title: My Service
            purposes: [ 'mypurpose' ]
            cookies:
                - _cookie
                - [ 'cookie', '/', 'yourdomain.com']
                - '/^_cookie(_.*)?/'
                - ['/^_cookie(_.*)?/', '/', 'yourdomain.com']

Note about regular expressions: You will have to write them as string in yaml config or in PHP code. They will be hydrated in the frontend.

Configure klaro

Global options are available via the klaro_options config option:

Syntro\SilverstripeKlaro\Config:
    klaro_options:
        default: true
        mustConsent: true

Available options are:

  • testing
  • elementID
  • storageMethod
  • storageName
  • htmlTexts (default: true)
  • cookieDomain
  • cookieExpiresAfterDays
  • default
  • mustConsent
  • acceptAll
  • hideDeclineAll
  • hideLearnMore