Brand Alignment Custom Plugin Tutorial

Learn how to build a minimal custom plugin and apply your brand colors to align your plugin visually with the rest of your Staffbase platform.

Employee App
Staffbase Intranet
Intermediate

Custom plugins are mini web applications that integrate seamlessly with the Staffbase platform to provide tailored functionality. Administrators can add and publish them in the same way they manage standard Staffbase plugins. Learn more about plugins.

This is an intermediate tutorial. If you’re new to custom plugin development, start with the basic Hello User tutorial.

In this tutorial, you will:

  • Develop a minimal custom plugin using PHP.
  • Access and apply your organization’s theme text and background colors to content and buttons in your custom plugin.
  • Align your custom plugin UI with your Staffbase platform.

By the end, you’ll be familiar with the basics of aligning your custom plugin with your branding, an essential step for creating a visually cohesive user experience. This can be done to any custom plugin and allows you to align your plugin visually with the rest of your Staffbase platform.

The image above conceptualizes how the Brand Alignment plugin could look after it’s available to users on the Staffbase platform.

This tutorial is designed to help you gain hands-on experience with plugin development for the Staffbase platform. It walks you through developing the plugin locally. To use it on the Staffbase platform, you will need to complete the following, which are not covered in the tutorial:

  • You have a basic understanding of Staffbase plugins and are familiar with terminal/command line usage.
  • PHP is installed on your system.
  • You have a code editor. For example, Visual Studio Code.

Download composer

To start building the plugin, you need to use the plugin SDK for PHP. This SDK provides the basic functionality to parse and verify the PHP token. Staffbase provides the SDK via a composer.

Run the following commands in your terminal:

  1. Create a folder for your project.
mkdir MyCustomPlugin
cd MyCustomPlugin
  1. Download the composer installer to the current directory.
    You should now see a file named composer.phar in your folder.

Install dependencies

Now you can use the composer to install the specific dependencies required for the plugin SDK.

  1. Install the custom plugin dependencies using composer.
./composer.phar require staffbase/plugins-sdk-php
  1. List the files installed.
ls -l

You should see:

  • composer.json
  • composer.lock
  • vendor

These are your dependency and package management files.

Open the folder in the code editor

  • Launch your project folder MyCustomPlugin, in your preferred code editor. It looks as shown in the screenshot:

Develop the plugin

Now that you have all the dependencies, you can create PHP files and a structure for plugin development.

Inside the vendor folder, you have the plugin SDK and all other dependencies it requires.

  1. Create an index.php file inside the project folder. In the index.php file, provide a namespace for the plugin.
<?php


namespace MyCustomPlugin;
  1. Import the library from the SDK to verify the SSO token. The SSO token here is a JSON Web Token that verifies whether the information is valid.
use Staffbase\plugins\sdk\SSOToken;
  1. Authenticate the user with an app secret.
try {


    $appSecret = '{enter your secret here}';

The $appSecret is a public key that the plugin uses to verify the signature of any JWT received. For now, you can leave it blank. You receive the key from Staffbase when you register your plugin with Staffbase and need to provide it if you want to make the plugin available on the Studio Plugins page.

  1. Use the SSOToken class to validate the incoming JWT token. This typically happens via a GET request when a user accesses your plugin:
$sso = new SSOToken($appSecret, $_GET['jwt'] ?? '');

Here’s what a sample request looks like:

https://my.plugin.com/index.php?jwt=MII3ksglkgfglfgnfdl

This step ensures that the user is authenticated and the token data is valid before rendering any content or executing plugin logic.

  1. Use the exception library to add an exception rule for when the user accessing the plugin does not have the required permissions.
use Exception;


} catch (\Exception $e) {
    print "Access denied.";
    exit;
}

You can now ensure your custom plugin aligns with your Staffbase platform’s active theme. Use the following code snippet to apply the theme’s text and background colors to content and buttons:

print "<html>
  <body>
    <h1 style='color: " . $sso->getThemeTextColor() . ";'>Hello!</h1>
    <button style='background-color: " . $sso->getThemeBackgroundColor() . "; color: " . $sso->getThemeTextColor() . ";'>
      Open Link
    </button>
  </body>
</html>";

The getThemeTextColor() method retrieves the appropriate text color from the decoded JWT for the user. This color is used for both the h1 element and the button text. The getThemeBackgroundColor() method retrieves the background color defined by the active theme. This color is used for the button background.

The entire code snippet in the index.php file should look like this:

<?php


namespace MyCustomPlugin;


use Staffbase\plugins\sdk\SSOToken;


try {


    $appSecret = '{enter your secret here}';
    $sso = new SSOToken($appSecret, $_GET[`jwt`]?? "");


    // https://my.plugin.com/index.php?jwt={enter-the-jwt-token}


    // Display a personalized greeting


    print "<html>
      <body>
        <h1 style='color: " . $sso->getThemeTextColor() . ";'>Hello!</h1>
        <button style='background-color: " . $sso->getThemeBackgroundColor() . "; color: " . $sso->getThemeTextColor() . ";'>
          Open Link
        </button>
      </body>
    </html>";


} catch (\Exception $e) {
    print "Access denied. ";
    exit;
}

You’ve successfully developed a custom plugin that visually aligns with the rest of your Staffbase platform. The example above is the foundation for visually aligning to your brand colors.