@uaveiro/systems-bar
v1.0.10
Published
Downloads
1,797
Readme
Table of Contents
Get started
@uaveiro/systems-bar is a reusable component library that helps the University of Aveiro contributors, developers and colleges. Add a universal navigation bar with all the university services.
Installation
@uaveiro/systems-bar components are written in Web Component using LitElement. Add @uaveiro/systems-bar components to your project.
npm install --save @uaveiro/systems-barOr with yarn
yarn add @uaveiro/systems-barStyles
Some styles have to be loaded on the page for the service bar to function properly. These styles contain the icons part, the font-family and the grid itself.
<link rel="stylesheet" href="https://fonts.googleapis.com/css?family=Roboto:100,300,400,500,700,900"/>
<link rel="stylesheet" href="https://static.ua.pt/css/font-awesome-pro/5.8.1/css/all.min.css"/>
<link rel="stylesheet" href="https://static.ua.pt/css/ua/static-lib/grid.css"/>
<link rel="stylesheet" href="https://static.ua.pt/css/portal-ua/1.0/systembar.min.css"/>Usage
Use the component anywhere you use HTML: in your main document, a CMS, Markdown, or a framework like React or Vue.
import "@uaveiro/systems-bar";or
<!--For older browser like IE 11 load the scripts below-->
<script src="https://unpkg.com/@webcomponents/[email protected]/webcomponents-bundle.js"></script>
<!--Gets the most recent version-->
<script src="https://unpkg.com/@uaveiro/systems-bar"></script>
<!--Or With fixed version-->
<script src="https://unpkg.com/@uaveiro/[email protected]"></script>and use them like so
<ua-systems-bar></ua-systems-bar>Example with props
<ua-systems-bar
publicLinks={JSON.stringify([
{ text: "My Custom Link", href: "#" },
{ text: "Another Custom Link", href: "#" },
])}
userLinks={JSON.stringify([
{ text: "Open link", href: "#" },
{ text: "Custom Link", href: "#" },
])}
lang="pt"
containerFluid
/>Authentication
Authentication is done with a JWT token. This token is located on LocalStorage. The system bar interprets the localStorage token location with the following name sb-ua-auth-token.
It is up to the developer to configure the authentication flow in his application so that the system bar can take advantage of its authenticated functionalities.
Below is the entire authentication configuration flow. The sample code below is done through React but it is possible to do it with simple javascript, since the system bar is agonistic to frameworks.
The settings below are based on the environment. This example are the default values when no authentication settings are entered.
<ua-systems-bar
authConfig={JSON.stringify({
login: "https://wso2-is.dev.ua.pt/oauth2/authorize",
logout: "https://wso2-is.dev.ua.pt/oidc/logout",
clientId: "D2wPaAQ3_dfgJgeStXAfwJRCKu0a",
idToken: localStorage.getItem("sb-ua-auth-id-token"),
callbackUri: "http://localhost:8081/pt/login",
})}
/>Authentication Callback - /login route
When the user clicks the "Login" link on the service bar, he is redirected to the University's IDP authentication page, after a successful authentication he is redirected (a callback is made) to the route /login, it is on this route where the token is interpreted and stored in LocalStorage.
For this, the developer has to add a route with the login name to his route system in the application.
import React, { useEffect } from "react";
//Router
import { useHistory } from "react-router-dom";
//Components
import { Loading } from "@uaveiro/ui";
//utils
import queryString from "query-string";
const AuthenticationCallback = () => {
const history = useHistory();
const getUserAuthToken = async (access_token, id_token) => {
try {
const res = await fetch(
`https://api-portal.dev.ua.pt/api/v1/authentication/wso2/portal/login/${access_token}?local=true`
);
const { token } = await res.json();
localStorage.setItem("sb-ua-auth-token", token);
localStorage.setItem("sb-ua-auth-id-token", id_token);
window.location.href = "/";
} catch (error) {
window.location.href = "/404";
}
};
useEffect(() => {
if (typeof window !== "undefined") {
const { access_token, id_token } = queryString.parse(
history.location.hash
);
getUserAuthToken(access_token, id_token, lastPath);
}
}, []);
return <Loading />;
};
export default AuthenticationCallback;Authentication Utilities
Below is a set of utilities to facilitate the manipulation of authentication in the application.
External packages
yarn add jwt-decode query-stringgetAuthUserInformation
This function makes use of the token that is stored in LocalStorage. Use this function to determine if the user is logged in or even to collect personal information such as the User ID. This function makes use of the jwt-decode package to decode the token
const parseJwt = (token) => {
var base64Url = token.split(".")[1];
var base64 = base64Url.replace(/-/g, "+").replace(/_/g, "/");
var jsonPayload = decodeURIComponent(
atob(base64)
.split("")
.map(function (c) {
return "%" + ("00" + c.charCodeAt(0).toString(16)).slice(-2);
})
.join("")
);
return JSON.parse(jsonPayload);
};
const getAuthUserInformation = () => {
const token = localStorage.getItem("sb-ua-auth-token");
const defaultResponse = {
token: "",
authenticated: false,
};
if (token !== null) {
const tokenData = parseJwt(token);
if (Date.now().valueOf() / 1000 < tokenData.exp) {
return {
authenticated: true,
token,
photo: "https://via.placeholder.com/150",
...tokenData,
};
} else {
return defaultResponse;
}
} else {
return defaultResponse;
}
};API
Component Props
Component ua-systems-bar is based on a set of modifiable props, below the table represents the type of property and its description
| Name | Description | Default | Type | | -------------- | ------------------------------------------------------------ | ----------------------------------- | ------------------------- | | containerFluid | Container width whether fluid or container | false | Bool | | publicLinks | The links that are represented in the navigation center | [] | Array<{PublicLinksProps}> | | userLinks | The links that are represented in the user's Avatar dropdown | [] | Array<{UserLinksProps}> | | lang | The current language | "pt" | String | | apiURL | The API URL for User Services | https://api-portal.dev.ua.pt/api/v1 | String | | authConfig | The Auth Config Object | {} | Object |
AuthConfig Props
context The context collects the most appropriate information for each application where the bar is implemented
| Name | Type | Default | | ----------------- | ------ | ------ | | login | String | https://wso2-is.dev.ua.pt/oauth2/authorize | | logout | String | https://wso2-is.dev.ua.pt/oidc/logout | | clientId | String | | idToken | String | | callbackUri | String | http://localhost:8081/pt/login |
Public Links Props
publicLinks represents an array of objects with a data set to build central navigation
| Name | Description | Type | | ---- | ----------------------------------- | ------ | | text | The Text representation of the link | String | | href | The url path for the link | String |
User Links Props
userLinks represents an array of objects with a data set to build the user's Avatar dropdown
| Name | Description | Type | | ---- | ----------------------------------- | ------ | | text | The Text representation of the link | String | | href | The url path for the link | String |
Troubleshooting
Styling reset
If the service bar has style problems, you may not have reset the basic browser styles yet. Reset stylesheet helps to reduce browser inconsistencies in things like default line heights, margins and font sizes of headings, and so on.
<style>
*,
*:before,
*:after {
margin: 0;
padding: 0;
box-sizing: border-box;
}
</style>