Box UI Elements with Vue 3

Frontend development is currently pretty diverse in terms of frameworks and libraries. Although React is pretty common, there are also multiple apps written in Vue.js, Angular, or other trending libraries. In this post, I explore the possibility of using Box UI Elements in a Vue 3 app.

What are UI Box Elements?

They are a set of pre-built UI components that allow developers to add elements of the main Box web application into their own applications, e.g., upload content, preview files, and folders stored on Box. If you would like to view a tutorial on using them, check out my colleague Rui Barbosa’s blog post series.

Prerequisites: Box developer account; node.js; optionally yarn

Steps to create the app

1. Configure the Vue 3 app
2. Create the Box app in the Developer Console
3. Select one of the below approaches

Approach 1: install the box-ui-elements package

• Use node 14 with NVM
• Install package
• Add peerDependences to main package.json
• Import Box UI Elements from node modules to your component
• Initialize a UI Element using the Composition API

OR

Approach 2: add the CDN script

• Install @vue/head
• Inject the CDN script to document’s head using @vue/head
• Initialize a UI Element using the Composition API

1. Set up the Vue 3 app

Create a Vue 3 project using the command below in your terminal. For more details, visit the Vue 3 documentation.

yarn init vue@latest

Choose a name for your project and settings. For this demo, I included: Vue Router, ESLint, and Prettier. Once the project is created, change the directory and run it!

cd <your-project-name>
yarn install
yarn dev

The project default local link is: http://127.0.0.1:5173, we’ll use it in the next step to set CORS domains in the Box Developer Console.

2. Create the Box app in the Developer Console

Log into your developer account and in the bottom left corner, click Dev Console. If you don’t have an account, visit the signup page. Fill out the text boxes and click Get Started. You’ll need to set up two-factor authentication to make changes to apps.

Now you can create a new app or use an existing one.

Set up CORS

Go to your app’s configuration tab, scroll down to CORS domains, and paste the local address of your Vue 3 project: http://127.0.0.1:5173

Set access rights

This step is useful when using, for example, the Content Uploader component. By default, access from an external app is read-only; optionally, to allow file upload or removal from your custom app, navigate to Applications Scopes and check the Write all files and folders stored in Box option.

Generate a token and add it to your app

Scroll to the Developer Token section and generate one. Remember, the token is valid for just one hour. ⚠️ When the token is no longer valid, go back to the developer console to revoke it and replace the old one in your project.

In the root of the Vue 3 project, create an env file to store the developer token for authentication. Make sure you add the prefix VITE_ to the variable name. This will expose it to the client application.

VITE_BOX_DEVELOPER_TOKEN=yourDeveloperToken

3. Choose an approach

Now, we can choose between two approaches:

1. The first one is installing the whole package (all Box UI Elements) and its peer dependencies directly into the project (including, e.g., React). This requires using node 14 (see below) and will increase the final bundle size.
2. The second approach is to inject scripts from a CDN per component. The trade-off in this approach might be the current lack of a subresource integrity tag.

For more details, check out our documentation site.

Approach 1: installing the box-ui-elements package

Use node 14 with NVM

Vite (the Vue 3 build tool) requires node v14 or v16. However, Box UI Elements currently require node v14. You may need to change your local node version to v14, using NVM. For more details about this tool, check the documentation.

Install the package

Additional information about installation is also available on the box-ui-elements npm page.

yarn add box-ui-elements

Add peerDependences to package.json

Go to your node modules in your project and find the box-ui-elements folder. Open the package.json file and copy the entries from the peerDependency section. Paste the entries into the dependencies section of your app’s main package.json file. Next, in your terminal, install them using yarn. Once the process is finished, we can run our project.

Create Vue component

Now, let’s create a component that us to display the Content Explorer. I decided to write the code using the Composition API; however, the Options API is still valid in Vue 3. First, we need a container with an id where the content can be rendered. In this example, the component will accept just one property: the Box folder id. Import Box UI Elements from node modules. Next, define the Content Explorer instance and initialise it using via the onMounted lifecycle hook. For more information about the Content Explorer, visit our documentation.

In order to display the component, just import it to App.vue or to a separate view and pass the folder id as a prop. The value “0” is dedicated to the root folder.

Here you can see a running Vue 3 app with the Content Explorer component.

Feel free to experiment with other UI elements, such as the Content Uploader. You may also download the working demo from the Github repository. To get it running, remember to include your developer token in the.env file.

Approach 2: add the CDN script

The second approach is based on injecting script and styles from our CDN. As mentioned, the code is split by component, so there is no need to add them all to the project.

Install and configure @vueuse/head

@vueuse/head is the document head tag manager for Vue 3. It helps inject scripts into the document’s head directly from single file components.

yarn add @vueuse/head

To use @vueuse/head, we need to import it in the app’s main.js file and activate it. For more details, check the @vueuse/head documentation page. Due to the fact that Vue 3 is quite young, dedicated packages are still under development, and currently the documentation for @vueuse/head is not finished yet.

Create Vue component

Like in the first approach, we need a template including a container with an id where the Content Explorer can be rendered. In this example, the component will accept just one property: the Box folder id.

<template>
    <div id="box-content-explorer"></div>
</template>

Inject the CDN script into the head of the document.

First, import the useHead method from the @vueuse/head plugin to the component. Next, go to the Box documentation site and copy the CDN links for the Content Explorer. Since we are building an app that has no React library included in the main app, choose the script marked as JS with React. On the contrary, links marked as JS without React are dedicated to apps that already use this library.

To make things a bit more pretty on the frontend side, let’s the link to the Content Explorer CSS style sheet too.

The useHead method allows you to define script attributes such as the onload callback. As a result, we can initialise the Content Explorer after the CDN scripts have been fully loaded.

Similarly, like in the first approach, in order to display the component, just import it to App.vue or to a separate view and pass the folder id as a prop. The value “0” is dedicated to the root folder.

The component should be displayed in the app and look exactly like it did in the first approach. I prepared a separate repository that demonstrates this approach. You can check the source code in this Github repo. After pasting a valid developer token into the .env file, the demo will work properly.

As next steps, you may customise the logo in the Content Explorer or add other UI Elements, like the Content Uploader. Read more about different cases of integrating Box in Peter Christensen’s blog post.

I hope you enjoyed this tutorial, and feel free to reach out to us on the developer forum for support, or via Box Pulse to make suggestions on how to improve Box UI Elements.