Graph Layer Components

This project provides a set of frontend components for rendering content from Microsoft Graph pulled in via graph-layer.

Building

To build the project, run the build script:

$ npm run build

The build process places build products in the dist directory.

Testing

Before using the testing framework, you must build it using the following command:

$ npm run build-test

The testing framework is designed to be loaded as a testing module in the graph-layer test program. Just pass the path to the test directory to the test program.

Usage

To use the library, install it in your project:

$ npm install --save @tccl/graph-layer-components

This library is designed to work in two significant ways:

• In a Vue.js application as a component library
• Or dynamically loading components on certain HTML elements (i.e. scanning)

Note: you are not limited to using the library in exclusively one of the aforementioned methods. You may use both at once if needed.

See the sections below for in-depth discussion of various usage topics.

Sizing of components

In general, each component is designed to work within any size parent container. By default, the component will grow/shrink in height depending on how much content it renders.

Fixed-height components

Each component is designed to also work within a fixed-height parent container. In the case of a fixed-height component, subdivisions of the component content will overflow logically. For example, a Drive component will overflow the subdivision that renders the file listing entries while the header subdivision remains fixed in place. In this way, a component functions as a widget within a fixed area of the page.

To implement fixed-height components, you must create a column-oriented flexbox parent element. This element will have a fixed height of your choosing. As a convenience, the library provides the global CSS class graph-layer for this purpose.

It is a good idea to assign the graph-layer class to a parent element in all cases. It works for both fixed-height and dynamic-height parent containers. If the height styling of the parent container changes from dynamic to fixed, the presence of the graph-layer class will automatically ensure the component works as expected in the fixed case.

Anonymous Requests

The Graph Layer server allows clients to issue so-called "anonymous" requests. Such requests indicate that the server use a preconfigured user identity instead of requiring the user to authenticate with Microsoft Graph to obtain an access token. This feature allows the library to access resources on behalf on an anonymous client.

If you are to use anonymous requests, you should understand any and all implications of allowing such access to resources in your tenant. This feature was designed for web applications running on secure, private networks.

Anonymous requests are not enabled by default. You must configure the Graph Layer server and the library to enable anonymous requests. See the section on Global Configuration below for more on how to configure anonymous requests in the library client.

Each library component has an anonymous property that determines when anonymous requests are used. If this property is set to fallback, then the component will enable anonymous requests based on the anonymousFallback library option. (Note that fallback is the default value.) Otherwise the property either enables or disables anonymous requests explicitly via a truthy value (e.g. "off" or "enable").

Using as a Vue.js component library

To use the library in your Vue.js application, import the library and register the components. This allows you to access the components globally.

import Vue from "vue";
import GraphLayer from "@tccl/graph-layer-components";

Vue.use(GraphLayer);

Now you can access components:

<template>
  <div class="my-view graph-layer">
    <graph-layer-user :user-principle-name="user" />
  </div>
</template>

<script>
  export default {
    name: "MyView",

	data: (() => {
	  user: "myuser@myorg.org"
	})
  };
</script>

<style>
  .my-view {
    min-height: 100%;
  }
</style>

Using the library in scan mode

The library is also designed to be used outside the context of a Vue.js application using scan mode. This mode involves scanning the HTML document for elements containing attributes that indicate how to load a Graph Layer component.

Examples:

<div class="graph-layer">
  <div data-graph-layer="user" data-graph-layer--me="1"></div>
</div>

<div class="graph-layer">
  <div data-graph-layer="drive" data-graph-layer--me="1" data-graph-layer--top="20"></div>
</div>

The following code executed at page load will create Graph Layer components from the above HTML:

import GraphLayer from "@tccl/graph-layer-components";

const graphLayer = new GraphLayer();
graphLayer.scanAll();

Note: if you are not using a build system such as rollup or webpack, you can still access the GraphLayer export via the GraphLayer global variable provided by the UMD bundle.

Explanation of attributes:

Attribute Name	Description
data-graph-layer	Indicates the element will load a Vue.js Graph Layer component; the value indicates which component is loaded.
data-graph-layer--PROP	Passes a property value to the Vue.js component; substitute PROP for the name of the property

When substituting PROP for a property name, make sure to convert a camel case property name to a hyphenated property name. Example: propertyName becomes property-name.

Library Options

The library has a few configuration options that are globally configured. You set these on the GraphLayer instance via the setOption method.

Explanation of available configuration properties:

Name	Description	Default
baseUrl	The base URL for Graph Layer requests	/graph/layer
cookieId	The name of the cookie that stores the Graph Layer session ID	GRAPH_LAYER_SESSID
theme	The theme class to apply to themeable components	default
anonymousAppId	Configures the Graph layer application ID to use in anonymous requests; these also enables anonymous requests	-
anonymousHeader	Configures the HTTP header name used to indicate an anonymous request to the server.	X-Graph-Layer-Anonymous
anonymousFallback	Determines whether components enable anonymous requests by default when no anonymous property is provided and the user has no session.	false
hideContentAccessDenied	Determines whether components hide content when access to content is denied	false

Components

The following components are provided by this library:

Vue.js Component Name	Data Attribute Value	Description
graph-layer-user	user	Renders basic user profile information
graph-layer-drive	drive	Renders a read-only drive (i.e. document library)
graph-layer-drive-browser	driveBrowser	Widget for selecting a drive object (browser style)
graph-layer-drive-picker	drivePicker	Widget for selecting a drive object (tree style)
graph-layer-list	list	Renders a Sharepoint site list
graph-layer-list-browser	listBrowser	Widget for selecting a site list

Browser components (e.g. graph-layer-drive-browser, ETC.) generate serialized strings that are designed to be passed to a corresponding component's value property (or via data-graph-layer--value if scanning). All configuration that can be done through value can also be done via individual properties.

User

The User component renders a user profile summary.

Properties

Property Name	Description
id	The ID of the user to render
userPrincipleName	The principle name of the user to render
me	Flag indicating that the widget should render the current user

Drive

The Drive component renders a folder/file listing from a Microsoft drive object (i.e. document library). The listing is read-only and opens files in a new window under Microsoft 365.

Properties

Property Name	Description
value	Serialized drive value (i.e. generated from DriveBrowser or DrivePicker)
overrideLabel	Title label (overrides drive name)
id	Loads a drive by its drive ID (Deprecated; use value)
groupId	Loads a drive by its parent group ID
siteId	Loads a drive by its parent site ID
userIdOrPrincipleName	Loads a drive by its parent user ID or user principle name
me	Loads the drive belonging to the current user
top	The maximum number of items to show per page
sortBy	The field that will be initially used to sort the items in the drive; if omitted, then the sort order returned by the API will be used
sortDirection	Either asc or dsc to indicate the sort direction

Drive Browser

The DriveBrowser component is used to browse and select a drive (i.e. document library) within an organization. This includes document libraries under users, groups and sites. The browser allows the initial drive sort field and sort order to be configured.

Properties:

Property Name	Description
domainLabel	The label of the top-level domain category.
title	The heading title for the component. Defaults to Select a document library.
formElement	Allows the component to function as a <form> element; the property value is assigned as the form element name.
browseMe	Enables browsing of current user's drives
browseUsers	Enables browsing of users (filtered for Members)
browseGuests	Enables browsing of guest users
browseGroups	Enables browsing of groups
browseSites	Enables browsing of sites
browseFollowedSites	Enables the component to browse a user's followed sites.

List

Properties

Property Name	Description
value	The serialized list value. (This value can be obtained via a ListBrowser.)
id	The ID of the list to query and render.
siteId	The ID of the list's parent site.
columns	List of columns to load by ID or Name. (This overrides any columns specified via value.)
config	List configuration object or serialized object string
children	For events lists only. Array of child list objects. Each object has the schema { id, siteId, config }.
overrideLabel	Title label to render in place of list name.
listType	The type of list to render. (e.g. generic or events)
top	Determines the number of items shown per page

List Browser

The ListBrowser component is used to browse and select a SharePoint site list within an organization. Site lists only exist under sites.

Properties

Property Name	Description
domainLabel	The label of the top-level domain category.
title	The heading title for the component. Defaults to Select a document library.
formElement	Allows the component to function as a <form> element; the property value is assigned as the form element name.
browseSites	Flag enabling browsing of sites
browseFollowedSites	Flag enabling browsing of followed sites
listType	Indicates the type of list to render. Supported values include: generic, events
filterTemplate	Indicates the list template(s) to display in the browser.

About list types and template filtering

SharePoint site lists can be used to represent multiple types of content. Currently, graph-layer-components supports the following list types:

• Generic: renders a default 2-dimensional list view
• Events: renders a calendar view

The list type in the upstream list object is indicated by its template property. When you create a SharePoint calendar, the system creates a list with a template of events. A generic list has template type genericList.

You can use the filterTemplate property to filter which templates are displayed in the list browser. This is either an Array of template names or a singleton string with template names separated by a : character.