Basics

This document will walk you through how to set up a Blueberry project and the basics of how the system works.

How it works

Based on information in the stylesheet's HTTP request Blueberry selects a particular set of custom CSS properties (opens in a new tab) to serve. When you want to let your users edit their theme, you have them navigate to a link generated with the API that specifies the same metadata Blueberry uses to lookup the stylesheet. They can then override the styles with their own choices all facilitated by Blueberry's javascript theming tools.

Creating A Project

Once you have signed up and logged in the first step to using Blueberry is creating a project. A project should correspond to a single set of themable styles. In most cases, you would only want a single project for a single website.

You can create a project by logging in and navigating to Projects > Create New Project

Picking Theme Lookup Strategy

The Theme Lookup Strategy is the most important concept to understand when creating a project so bear with us in a brief explanation. You have three possible choices:

URL Segment Based

The URL segment-based strategy will serve a different customizable stylesheet based on the value at the end of the stylesheet URL.

The included stylesheet will look like this:

https://segment-based-styles.useblueberry.io/PROJECT_ID/KEY_OF_YOUR_CHOOSING

The key at the end determines which theme is served:

https://segment-based-styles.useblueberry.io/AAAA1234-BB12-CC12-DD12-EEEEEE123456/theme-a → Theme A
https://segment-based-styles.useblueberry.io/AAAA1234-BB12-CC12-DD12-EEEEEE123456/theme-b → Theme B

When you want a user to edit their theme you send a request to the API to give you a magic link called a theme modification url that you can redirect the user to, which will allow them to use the blueberry toolbar to edit only their theme. More information about how to make this request can be found here.

This strategy is most useful if you have public user profiles being served from the same domain.

For example, if you have two user profile pages like:

www.example.com/user_profiles/cool_kid_90
www.example.com/user_profiles/burner_profile

You can have each of these pages serve dynamic HTML linking to the appropriate stylesheet.

The first profile would use:

<link 
    rel="stylesheet" 
    crossOrigin='anonymous' 
    href="https://segment-based-styles.useblueberry.io/PROJECT_GUID/cool_kid_90" />

The second profile would use:

<link
    rel="stylesheet" 
    crossOrigin='anonymous' 
    href="https://segment-based-styles.useblueberry.io/PROJECT_GUID/burner_profile" />

Domain Based

The domain-based strategy will serve a different customizable stylesheet based on the referring domain in the Referer header.

The included stylesheet will look like this:

https://domain-based-styles.useblueberry.io/PROJECT_ID

The referring domain determines which theme is served:

> Referrer: johnsdogfood.com
https://domain-based-styles.useblueberry.io/AAAA1234-BB12-CC12-DD12-EEEEEE123456 → Theme A
 
> Referrer: johnsdogfood.com/checkout
https://domain-based-styles.useblueberry.io/AAAA1234-BB12-CC12-DD12-EEEEEE123456 → Theme A
 
> Referrer: johnsdogfood.com/about-us
https://domain-based-styles.useblueberry.io/AAAA1234-BB12-CC12-DD12-EEEEEE123456 → Theme A
 
> Referrer: danielsdonuts.com
https://domain-based-styles.useblueberry.io/AAAA1234-BB12-CC12-DD12-EEEEEE123456 → Theme B
 
> Referrer: danielsdonuts.com/buy-donuts
https://domain-based-styles.useblueberry.io/AAAA1234-BB12-CC12-DD12-EEEEEE123456 → Theme B

This strategy is best when you are distributing something like a WordPress plugin and each theme should be changeable per domain.

As you can see in the example above the stylesheet linked is the same for every domain.

<link
    rel="stylesheet" 
    crossOrigin='anonymous' 
    referrerPolicy='no-referrer-when-downgrade'
    href="https://domain-based-styles.useblueberry.io/PROJECT_GUID" />

⚠️

Note the link tag using the domain-based strategy must add the referrerPolicy='no-referrer-when-downgrade' attribute. If this is not set the referrer headed will not be properly passed in the http request.

Path Based

Very similar to the domain-based strategy the path-based strategy will also serve a different customizable stylesheet based on the Referer header. This strategy using the path value and not the domain. Query parameters do not affect the theme served.

The included stylesheet will look like this:

https://path-based-styles.useblueberry.io/PROJECT_ID

The referring path determines which theme is served:

> Referrer: photosharing.com/users/1/
https://path-based-styles.useblueberry.io/AAAA1234-BB12-CC12-DD12-EEEEEE123456 → Theme A
 
> Referrer: photosharing.com/users/1?cats=dogs+dragons=wizards
https://path-based-styles.useblueberry.io/AAAA1234-BB12-CC12-DD12-EEEEEE123456 → Theme A
 
> Referrer: photosharing.com/users/2
https://path-based-styles.useblueberry.io/AAAA1234-BB12-CC12-DD12-EEEEEE123456 → Theme B
 
> Referrer: photosharing.com/users/2/
https://path-based-styles.useblueberry.io/AAAA1234-BB12-CC12-DD12-EEEEEE123456 → Theme B

As you can see in the example above the stylesheet linked is the same for every domain.

<link
    rel="stylesheet" 
    crossOrigin='anonymous' 
    referrerPolicy='no-referrer-when-downgrade'
    href="https://path-based-styles.useblueberry.io/PROJECT_GUID" />

This strategy is best when it is difficult to dynamically change the stylesheet injected into the page.

Integrating

The next step is to add the stylesheet and JavaScript bundle to your project. If you are using a domain-based or path-based strategy this is as simple as adding a stylesheet to your project like this:

Domain based

<script async type="module" src="https://client.useblueberry.io/application.js" />
<link
    rel="stylesheet" 
    crossOrigin='anonymous' 
    referrerPolicy='no-referrer-when-downgrade'
    href="https://domain-based-styles.useblueberry.io/PROJECT_GUID" />

Path based

<script async type="module" src="https://client.useblueberry.io/application.js" />
<link
    rel="stylesheet" 
    crossOrigin='anonymous' 
    referrerPolicy='no-referrer-when-downgrade'
    href="https://path-based-styles.useblueberry.io/PROJECT_GUID" />

URL Segment Based

Segment-based is slightly more complicated. Whatever process is responsible for generating the page needs to add the dynamic key to the end of the URL.

<script async type="module" src="https://client.useblueberry.io/application.js" />
<link
    rel="stylesheet" 
    crossOrigin='anonymous' 
    href="https://segment-based-styles.useblueberry.io/PROJECT_GUID" />

Once you have integrated the stylesheet and javascript the final step is to generate a theme modification URL and try it out!

Home Generating A Theme Modification URL