Skip to main content

Getting Started with BUX

Pierre Fortier

The Buckeye UX design system is an incredible tool for designers, developers and content editors. It keeps designers from reinventing the wheel every time they design an interface, it increases developer productivity by providing ready-to-use code, and content editors can focus on their content without having to worry about look and feel. But let's say you don’t have BUX in your project yet: how do you get started? In this short post, I’ll walk you through how to do just that.

Initial set-up and requirements​

The preferred way to utilize BUX in your projects is through a package manager. Currently, we support both NPM and Composer, for Node.js projects and PHP projects, respectively. If your project doesn’t currently utilize a package manager, I would recommend using NPM to start.

Both packages are hosted on the University Code Repository (UCR), the university’s GitLab instance.

NPM​

If not already done, install Node.js and NPM by following their instructions.

In your command line tool of choice, navigate to your project’s directory. If you haven’t already, initiate NPM by running npm init and following the prompts.

Next you need to add UCR’s namespace to your project. Do this by creating a .npmrc file in your project directory and adding the following line to it:

@osu:registry=https://code.osu.edu/api/v4/packages/npm/

Now, you need to authenticate NPM with UCR to be able to pull the project. Create a personal access token with API access by following GitLab’s instructions. Next, add your access token to your project by running:

npm config set -- //code.osu.edu/api/v4/projects/23121/packages/npm/:_authToken=<yourToken>

Finally, you can install the project! Run:

npm install @osu/bux-source

Now BUX is installed in your node_modules folder.

Composer​

If your project uses Composer, such as is the case with a Drupal site, you can add BUX by first adding these lines to your composer.json file: 

"repositories": [ 

  { 

    "type": "composer", 

    "url": "https://code.osu.edu/api/v4/group/6209/-/packages/composer/packages.json" 

  } 

]

Next you need to authenticate UCR in composer by creating a personal access token in UCR with API access, and running: 

composer config gitlab-domains code.osu.edu 

composer config --global gitlab-token.code.osu.edu <myToken>

You can now run:

composer require osu/bux-composer

The BUX project will now be added to your vendor folder.

Now the fun part​

Now that BUX is included in your project, you have direct access to it! The dist folder contains all the components, CSS and JS you need to start using BUX. For example, if you have a PHP-based project like Drupal, you can reference the twig templates in the dist folder directly and declare the required variables. Here’s an example from my team’s Drupal theme: 

{% set vars … %} 
<div{{attributes.addClass(classes)}}> 

  {{ title_suffix }} 

  {% include '@bux/featured-card.twig' %} 

</div>

The above example is taken from a twig template file for our Featured Card. We first set variables from field values in Drupal. Those then get passed on to the included BUX twig templates. The CSS and JavaScript that the components require is also included in our theme’s library file.

If you aren’t in a PHP project, you can also plug the contents of the HTML folder directly into your favorite templating language to get going.

A great advantage of using a package manager is that not only are the project files all organized for you in one place, but you can easily keep them up to date when a new BUX release is out by updating the package manager.

What if I’m not using a package manager?​

If you aren’t using a package manager, you can still leverage the power of our design system. To start, you can download everything contained in the BUX package and include it manually in your project. You can also link to the BUX CSS and JS directly in your HTML. For the CSS you can add this in the <head> tag:

<link rel="stylesheet" href="https://assets.bux.osu.edu/v1.2.0/css/bux-styles.min.css"/>

And for the JS, you can add this after the <body> tag:

<script src="https://assets.bux.osu.edu/v1.2.0/js/bux.min.js"></script>

If you’d like to stay dynamically up to date with releases, you can change the version number to ‘v1.x’ in those links.

Additionally, every component page on this website has HTML example code and its Twig template that you can also use as a reference.

Now you’re ready to start developing with BUX!

If you have any additional questions or run into any issues along the way, please reach out to us!

Back to top