Integrating Blueberry With Rails

What is Blueberry?

Blueberry is a tool that allows websites to make their UI customizable by the user. It does so by leveraging CSS custom properties. Each CSS custom property becomes a widget in the Blueberry toolbar allowing anyone to configure their website.

For example, given the following stylesheet:

:root {
  --primary-color: #5591f5;
  --text-color: rgb(64, 53, 53);
  --background-color: #ffffff;
}
 
.primary-color {
  fill: var(--primary-color);
}
 
.text-color {
  color: var(--text-color);
}
 
.background {
  background-color: var(--background-color);
}

This stylesheet would automatically be detected by the Blueberry JavaScript and the variables would be shown in the Blueberry toolbar.

Here's a more detailed usage example taken for the demo on the getblueberry.io homepage.

The mechanics of how Blueberry accomplishes this is detailed in the documentation (opens in a new tab).

Integrating with Rails

Integrating the Blueberry developer tool with a Ruby on Rails application involves several steps to enable dynamic theme modification for users. Here's how you can go about it:

Step 1: Create a project

After creating an account navigate to the projects page and create a project. You'll need the project guid for the stylesheet link in the next step!

Step 2: Add Stylesheet and JavaScript

# app/views/layouts/application.html.erb 
<!-- 
    This Javascript enables the toolbar and custom property detection 
-->
<script async type="module" src="https://client.useblueberry.io/application.js"></script>
 
<!-- 
  This stylesheet is responsible for loading custom styles.
  There are a variety of different strategies to tell Blueberry 
  which stylesheet to load. This is using the "path based strategy" 
  which will use the path to determine which stylesheet to serve, 
  more on this can be found in the docs https://docs.getblueberry.io/quick-start/basics
-->
<link
    rel="stylesheet" 
    crossOrigin='anonymous' 
    referrerPolicy='no-referrer-when-downgrade'
    href="https://path-based-styles.useblueberry.io/PROJECT_GUID" />

Step 3: Create an API Token

Next generate an API token from the Blueberry dashboard, which you'll need to authenticate API requests.

Step 4: Set Up Your Rails Controller

In your Rails application, create a controller action that handles theme modification. Here, you'll use the Blueberry API to generate a theme modification URL when a user requests to change their theme. This URL will allow users to edit and save theme changes.

class ModifyThemesController
  def change_theme
    user = authenticate_user(request) # Ensure the user is authenticated
    response = HTTParty.post(
      "https://api.getblueberry.io/public_api/theme_modification_urls",
      headers: {
          "X-Auth-Token" => ENV['BLUEBERRY_TOKEN'],
          "Content-Type" => "application/json"
      },
      body: {
          project_guid: ENV["BLUEBERRY_PROJECT_GUID"],
          lookup_value: user_theme_identifier(user), # Define how you identify the user's theme
          redirect_url: user_return_url(user) # Define where the user should return after theme modification
          saveable: true
      }.to_json
    )
 
    if modification_url_response["success"]
      redirect_to modification_url_response["url"], allow_other_host: true # Redirect the user to modify their theme
    else
      render :error # Handle errors appropriately
    end
  end
end

Step 5: Handle the Redirect

After the user modifies the theme, Blueberry will redirect them back to your application using the redirect_url you specified. This should be the page that the user wants to customize.

Step 6: Update Your View

Embed the theme modification link in your Rails views, allowing users to autenticate and navigate to a special link which will allow them to edit their theme.

<%= link_to "Modify Your Theme", modify_themes_change_theme_url %>

By following these steps, you can integrate Blueberry into your Rails application to provide a dynamic and user-friendly theme customization experience.

This post is an overview of how to integrate for specifics check out the docs (opens in a new tab).

2024 © Blueberry Software