Build a content portal using Box UI Elements, React, Tailwind CSS & Vercel Part 1
Box is fantastic all by itself, but sometimes you might have a use case where you want to give external users a customized experience that has a specific user interface. Enter content portals!
In part 1 of this portal series, I will be going through how to use one of Box’s sample code repositories to jumpstart your portal development using Box UI Elements, React, Tailwind CSS, and Vercel.
Custom Portals Overview
If you don’t know, a portal is basically an overlay on top of Box. This allows any user, be it internal employees, vendors, or external customers to use Box as the storage layer for a business process.
The portal you create can have a completely customized user experience, and Box APIs make it easy to interact with the content cloud whether on desktop or mobile devices.
The best part, Box’s industry leading security mechanisms remain in place, allowing content to only be accessed by those who should be accessing it.
Customer Use Cases
We have tons of customers using portals, whether its for insurance claims or wealth management. Below are some examples.
Morgan Stanley created the digital vault which uses Box APIs to manage financial and tax documents for clients to collaborate with advisors.
Fundwell, which connects new or small businesses to lenders, uses a portal for new customer loan applications, as well as storing loan documentation.
& Nationwide uses a Box content portal for the bulk of their entire insurance claim process.
Walkthrough
In the demo today, we will be walking through how to create a simple financial document portal for an imaginary bank called Increo Financial, using Box UI elements. You can use this sample code as the inspiration to begin further development of your own portal.
If you aren’t familiar, UI Elements are Box Platform’s easy to use, customizable, React UI components. and with version 19 and above, they are also now responsive.
There are several types, like the content explorer which allows file upload, download, and view or the preview element, which allows you to just display a file to a user. Our portal will use a variety of them.
Box features and scopes are built in. For example, if you wanted a user to see metadata on a file or use Box AI, you can easily do so with a small configuration change.
Every modern desktop and mobile browser is supported, and you can even customize the logo.
As of UI Elements v20, you can use up to React v17.0.2 and Node 18.18.0.
🚨IMPORTANT NOTE 🚨
This demo is for demonstration purposes only and is not production-ready. It lacks complete authentication measures, making it unsuitable for live environments without further development.
Prerequisites
In order to complete part 1 of the tutorial, you’ll need the following items:
- GitHub account
- Vercel account — suggested to login with GitHub account.
- Box developer account — must use a Box wide unique email address
Configure a Box Application
- Create a New Application: Go to the Box Developer Console, click ‘Create New App’, choose ‘Custom App’, name your app, then ‘Server Authentication with JWT’. Note — we are setting this up with the JWT authorization type, even though the demo doesn’t actually need it. This is due to advisement that a real world deployment use JWT for management of app users and a higher level of security.
- Set Application Scopes: Ensure the application is configured with the necessary permissions: App + Enterprise, read/write all files, manage users/groups/enterprise properties, Box AI (Box AI is only available to Enterprise+ licenses and above), and generate user access tokens. Again, some of these scopes are not used in the demo deployment, but in a real world scenario would be necessary.
- Generate a Public/Private Keypair: Click the button to generate a public/private keypair. Note this will require 2FA. You will have to set this up if you have done so before. A pop up will show you the steps to do so. After it is setup, you’ll need to click through the keypair flow again.
- Download the JSON Config File: This file is automatically downloaded upon keypair generation. Keep this file close. We will need the information in this file in a future step.
- Save: Save the changes using the button in the top right.
Authorize the Box Application
Like always, a server authentication application will need to be authorized by the administrator of the Box instance. Follow the steps outlined at Custom App Approval to authorize the application. Post-authorization, a service account email is assigned to the app. Anytime someone makes changes the app will need to be reauthorized.
Box Dummy Content Setup
In order for the demo to work, we are going to create some dummy content. In a real world scenario, most of this could be automated during a user being created or signing up with Increo Financial, but for the sake of simplicity and speed, we are just going to do it manually.
Create a root folder for all the portal content to live in. Call it Portal Demo.
Collaborate the service account email address of the JWT application you created earlier into the portal demo root folder. If you don’t remember where to grab this email, you can find it in the general settings tab of your application in the Box Developer Console.
Imagining that the portal will have multiple end users, lets create a folder for one. Create a new folder in the demo root folder. Give it the name of a fake user, for example, Robert Smith.
While we won’t be using app users in this demo, in a production implementation of a content portal, utilizing app users would be vital to maintain proper security posture. You can read more on that topic here & here.
Under Mr. Smith’s folder, create a two more folders: one for Applications and one for Statements.
In the statements folder, upload a copy of this dummy statement.
In the user’s root folder, upload a copy of this dummy terms and conditions file. In a real world scenario, this file might live somewhere else, but to show you the Preview Box UI Element, we need to have an example file to actually preview.
For each of the pieces we created, you will need the ids in the following step, so keep Box open!
Deploy Initial Site with Vercel
Now that we have made a Box application and some dummy content, we can deploy a copy of the default portal from Box’s sample repository.
🚨IMPORTANT 🚨
It is advised to have already created your Vercel account and have it open in a tab. Deploying to Vercel without having an account already or a tab open, could cause some confusion. The first time you deploy something from GitHub, it will ask you to connect GitHub and Vercel via a third party integration. This is normal.
Deploy to Vercel by clicking HERE. It will ask you for several options, so let’s walk through them.
First, if you don’t see the below screen upon clicking the above link, you are probably not logged into Vercel. Login in the top right, close the window, and click the link again.
Once you reach the below screen, click create in the bottom right of the first box. This will create a GitHub repository in your account and clone in the code from Box’s sample repository.
For next part, we need to paste in several environment variables. Using the built in Vercel environment variables is a fantastic way to maintain your security posture. You can find the Box content IDs in the url bar for the respective pieces. For example, in the below screenshot, the ID shown at the end of the URL slug is the Folder ID for the Statements folder.
Go through each value field and fill in the requested variable. After you are finished, click deploy.
- The REACT_APP_BOX_CONTENT_UPLOADER_FOLDER_ID variable goes with the statements folder.
- The REACT_APP_UPLOADED_FOLDER_ID variable goes with the applications folder.
- The REACT_APP_BOX_PREVIEW_FILE_ID variable goes with the terms and conditions file.
- The rest of the variables will all come from your JSON config file that was automatically download. For security purposes, I won’t be showing those pasted in, but just copy paste them — no qoutes. Note, the private key is out of order and is the longest of all of them. Make sure to include the /n in the value pasted.
After clicking deploy, you will see the screen change to the below. This process may take a couple of minutes.
You might see the following error. If you do, there is a workaround. In the top left, click your name to go to your dashboard.
Select the portal project by clicking on it.
On the settings tab of the project, scroll down and find the Node.js version section. In the dropdown, select 18.x. Click Save.
Now, flip to the deployments tab for the portal project. You should see the deployment that failed. Click the ellipsis, and select redeploy.
In the popup, leave the defaults. Click redeploy.
After a couple of minutes, if successful, you should see the below with a status of ready.
Click the visit button. You should see the home page of the deployed sample content portal.
Post-Deployment Configuration
In order to test out the default portal, we need to add the CORS domains to the Box application configuration section. You can find them under the visit button. We will want to add both the standard page, as well as the deployment URL — if you plan to visit/use the deployment URLs during testing. Do not include the ending slashes, and comma separate them.
After adding the URLs, click the save button in the top right.
Testing the Default Portal
The default deployed portal doesn’t have any authentication built in, so you can leave the email field blank. In the password field, you may paste in a developer token grabbed from the Box application configuration section.
Click generate developer token. Copy the token.
Paste in the token to the password field, and click sign in.
After signing in, you should see the below screen. Click the My Statements header option.
If everything worked as it should, you should see the statement folder with the dummy statement we uploaded. This page uses the content uploader UI element, meaning it can do a lot! Click the statement.
A preview of the statement you appear. Now, click logout in the top right.
You will be invited to go back to the homepage.
Coming up next
In the subsequent blogs in this portal series, we will be looking at several enhancements, including adding additional pages, improving authentication, using Box AI, customizing colors, and more!
Closing Thoughts
As you’ve just seen in part 1, Box UI Elements and Box APIs make it incredibly easy to create a custom experience for internal or external users.
In the next part, we will focus on extending the default portal with additional functionality.
Until then— happy coding!
As always, if you have any feedback for the Box Developer Relations team, feel free to drop us a line on the developer forum.
