Embedded SharePoint Library | Gutenberg Blocks for WordPress

Preview notice

We are working hard on a new  WPO365 tutorials site and we are very happy to invite you to visit instead the tutorial to embed a SharePoint Library in WordPress.

Use this guide, if you want to embed a (folder in a) SharePoint Online / OneDrive library in a WordPress page or post with the help of an easy-to-use Gutenberg Block (also see the following video https://youtu.be/iF0Opz82cpc).

Features

DOCUMENTS | BASIC

  • Connect to a SharePoint Online library and display files from the root folder.
  • Provide translations for error messages.
  • Test the configuration before you publish the page.

The basic edition of the Documents Gutenberg Block is included in the free edition of the WPO365 | LOGIN plugin.

DOCUMENTS | PREMIUM

  • Allow users to navigate into folders (and back up with an easy-to-use breadcrumb navigation).
  • Grant access for anonymous users (using the Azure AD preview permission for Sites.Selected).
  • Choose between SharePoint Online, OneDrive and Recently Used Documents as a data source.
  • Choose to show a link to open the current location in SharePoint.
  • Configure (custom list item fields and) columns and how they appear (using simple CSS properties).
  • Provide translations for column headers.

The premium edition of the  Documents Gutenberg Block can be purchased as a stand-alone extension WPO365 | DOCUMENTS as well as in the WPO365 | INTRANET bundle.

Before you start

  • You must already have configured the single sign-on capability of the WordPress + Office 365 plugin (unless your intention is to grant anonymous users access to the SharePoint Online library).
  • Additionally, you must also already have configured the integration capability of the plugin.
  • You are a Global Administrator for your company’s Office 365 tenant / Azure AD directory (or have at least the ability to edit the Azure Active Directory App registration that was created previously when the single sign-on capability was configured).
  • You are an Administrator for your WordPress website.
Also make sure that you have configured WordPress permalinks or else connections to the WPO365 REST API for Microsoft Graph may fail.

App registration

Scenario "User must sign in with Microsoft"

  • In Azure Portal click the 'hamburger' (icon with three horizontal lines in the upper corner) to open the menu.
  • Navigate to Azure Active Directory > App registrations.
  • Select the App registration that you created when you configured the single sign-on capability of the plugin.
  • Click API permissions from the 'App registration' menu on the left
  • Click + Add a permission.
  • Select Microsoft Graph > Delegated permissions.
  • Check
    • Sites.Read.All
  • Click  Add permissions.
  • Click Grant admin consent for … as an administrator for to grant consent for all users in your tenant to use this ‘App registration’.
Since you are granting so-called  delegated permissions users will only be able to access files they have been granted access to. The name  Sites.Read.All may be a bit misleading in this case.

Scenario "Allow anonymous users"

  • In Azure Portal click the 'hamburger' (icon with three horizontal lines in the upper corner) to open the menu.
  • Navigate to Azure Active Directory > App registrations.
  • Select the App registration that you created when you configured the app-only integration capability of the plugin.
  • Click API permissions from the 'App registration' menu on the left
  • Click + Add a permission.
  • Select Microsoft Graph > Application permissions.
  • Check
    • Sites.Selected
  • Click  Add permissions.
  • Click Grant admin consent for … as an administrator for to grant consent for all users in your tenant to use this ‘App registration’.

To grant permission for WordPress to read the content of a given site collection, you must now grant Read permissions to the application that is represented by the App registration in Azure AD. Along with the API permission Sites.Selected this will result in only those sites that have had Read permission granted being accessible from WordPress. For example, to grant Read permission to an App registration / application with display name "App-only permissions" and Application (Client) ID 50b593ab-6567-4bc0-9fba-xxxxxxxxxxx you must make the following call: 

POST https://graph.microsoft.com/beta/sites/{siteId}/permissions
Content-Type: application/json
{
    "roles": ["read"],
    "grantedToIdentities": [{
            "application": {
                "id": "50b593ab-6567-4bc0-9fba-xxxxxxxxxxx",
                "displayName": "App-only permissions"
            }
        }
    ]
}

In the previous example you must replace {siteId} with the full ID of the SharePoint site collection for which you want to grant WordPress Read permission for. To find the site ID for a SharePoint site with hostname wpo365demo.sharepoint.com and a server relative path sites/contoso you must make the following call: 

GET https://graph.microsoft.com/beta/sites/wpo365demo.sharepoint.com:/sites/contoso
Content-Type: application/json

To make this and the previous call you can use Microsoft's Graph Explorer tool as shown below.

Please note that when using this tool you may need to Modify permissions and add and consent to Sites.FullControl.All permission to be able to make the call to create the Read permission.

With this configuration in place anonymous website visitors are now able to view SharePoint documents in this specific SharePoint site collection. With the default column configuration, however, they are not able to download the documents. Please consult the paragraph Edit columns for anonymous access for steps how to update the column definition so that your anonymous visitors are able to download documents from SharePoint.

Integration

  • Navigate to WP Admin > WPO365 > Integration.
  • Check the option to Enable WPO365 REST API for Microsoft Graph.
  • Require that Users must be signed in with Microsoft (unless you intend to give users that did not sign in with Microsoft access to a SharePoint Document Library as explained in the previous paragraph).
  • Leave the option to Allow apps to request any Microsoft Graph endpoint unchecked (unless you know what you are doing).
  • Add your SharePoint Home URL e.g. https://[your-tenant].sharepoint.com to the list of Allowed endpoints and do not check the box to allow application-level permissions for that endpoint (unless you intend to give users that did not sign in with Microsoft access).
  • Check the option to Allow Microsoft Graph proxy-type requests. 

  • Click Save configuration.
Choosing to allow anonymous users to use the embedded SharePoint library on the one hand will instruct the app to use the Sites.Selected permission that you configured before. Choosing to allow anonymous users access the WPO365 REST API for Microsoft Graph on the other hand has a much broader impact and is not recommended, depending on other permissions that you may have assigned to the App registration in Azure AD.

Allow access to the WPO365 REST API for Microsoft Graph

For the block to be able to connect to Microsoft Graph it must be able to connect to a custom WordPress REST API. This custom REST API is installed as part of the basic infrastructure provided by the WPO365 | LOGIN plugin. Perform the following steps to prevent the plugin from blocking access to this WordPress REST API.

  • Navigate to WP Admin > WPO365 > Single Sign-On.
  • Scroll down to the list of Pages freed from authentication and add /wp-json/wpo365/v1/graph (if not already added).
  • Click + to add this entry to list.
  • Scroll to the bottom of the page and click Save configuration.

Configure Block

Perform the following steps to add and edit a Documents Gutenberg Block to display the contents of a (folder in a) SharePoint Online / OneDrive library .

  • Click + Add block to add a new Gutenberg Block to your post or page as shown below.

  • Once added, click the block to select it. This will load the block's configurator in the Block Editor panel.

  • Now you can continue with the configuration of the various options. Please note that some options are only available if you purchased the PREMIUM edition of the block.
Test connection

Before you start the configuration of the various option click Start test. The first test that the block will perform is to see whether it can connect to the WPO365 (WordPress) REST API that is installed as part of the basic infrastructure provided by the WPO365 | LOGIN plugin (version 13 or higher). Make sure the first test is passed before you continue.

Datasource

This option allows you to switch between three different different data sources for the block's main app:

  • SharePoint Library Choosing this option allows you to specify a (folder in a) SharePoint library in a SharePoint Online site as the data source for the block.
  • OneDrive Choosing this option specifies the currently logged-in user's OneDrive library as the data source for the block.
  • Recent documents Choosing this option will take the currently logged-in user's recently viewed and accessed documents (from Microsoft Graph's insights API) as the data source for the block.
Hostname
  • If you picked SharePoint Library as your data source, you must specify your SharePoint Online home address hostname without https:// e.g. wpo365demo.sharepoint.com.
  • Click Start test to test if the block can connect to the SharePoint tenant that you specified. Make sure the second test is passed before you continue.

Server relative path

  • If you picked SharePoint Library as your data source, you must specify a server relative address for the site collection e.g. sites/contoso.
  • Click Start test to test if the block can connect to the SharePoint site collection that you specified. Make sure the third test is passed before you continue.

Library title

  • If you picked SharePoint Library as your data source, you must specify the title of the library where the block should connect to e.g. Documents.
  • Click Start test to test if the block can connect to the SharePoint library that you specified. Make sure the fourth test is passed before you continue.

Folder

  • If you picked SharePoint Library as your data source, you can optionally specify a folder path where the block should connect to e.g. General/HR-Forms.
  • Click Start test to test if the block can connect to the SharePoint folder that you specified. Make sure the fourth test is passed before you continue.
Hide message bar
  • You can choose to suppress the message bar (that is mainly used to show a message that the BASIC edition does not offer support for folder navigation).

Show "Open in SharePoint" link

  • You can choose to show a link to open the current location in SharePoint.
Allow anonymous users
  • Choose this option if you want to allow anonymous users (that did not sign in with Microsoft and with whom you did not explicitly shared the SharePoint Online library) to be able to see the files from the SharePoint Online location that you have specified. 

Use query string for configuration

  • Choose this option if you want to "inject" the configuration of the app's hostname, server relative path, library title and folder by means of a dynamically assembled query string. Refer to the example below to understand how to build the query string.
https://your-wordpress-website/page-with-embedded-app/?serverRelativePath=sites%2Fcontoso&listTitle=Documents&libraryRelativeFolderPath=General%2FCollateral

Please note that enabling this option itself does not give anonymous users access to a specific SharePoint resource. Instead you must perform the steps detailed in the previous paragraph Integration > Scenario "Allow anonymous users".

Edit columns

You can edit the columns that the block will display and can connect each of those columns with a (custom) SharePoint list item field. You can use the following guidance on the available properties and their intrinsic log when editing the columns.

  • type The type property tells the block's column rendering engine what type of column to render. The following options are supported:
    • date
    • icon
    • link
    • name
    • number
    • text
  • field The field property is used to connect the block's column with a SharePoint list item field e.g. lastModifiedDateTime will get the last modified date and time of the current item. You can use a period "." to select nested fields e.g. lastModifiedBy.user.displayName to get the display name of the user that last modified the current item. Items that are returned by Microsoft Graph are represented as driveItem resources. The driveItem has been expanded and the SharePoint list item fields are therefore available under the driveItem's listItem.fields property. For example, to connect to the SharePoint list item's ContentType field you would simply write listItem.fields.ContentType. To get an understanding what fields are available you can click Start test and then look at the data (by clicking Show data) for the fourth and last test. Copy that data and format it as JSON in your favorite editor e.g. VS Code will help you see how the data is structured and what fields are available.
  • hrefField If the column's type specifies to render a hyperlink then you must add a hrefField property to configure the href attribute of the link.
  • hrefTarget If the column's type specifies to render a hyperlink then you can add a hrefTarget property to configure the target attribute of the link.
  • formatStringDate If the column's type specifies to render a date then you can add a momentjs formatting string.
  • formatStringNumber If the column's type specifies to render a number then you can add a numeraljs formatting string.
  • isResizable If true the user can resize the column.
  • isCollapsible If true the column may be collapsed (not shown) depending on the screen size.
  • maxWidth The max width as a number of the column in pixel.
  • minWidth The max width as a number of the column in pixel.
  • css A JavaScript object with custom CSS for rendering a column's cell e.g. { lineHeight: '24px', backgroundColor: '#c2c2c2' }.
  • title The title of the column.

The following is the default column configuration that serves here as an example and boiler plate for your own customizations. 

[
  {
    "type": "icon",
    "isResizable": true,
    "minWidth": 32,
    "maxWidth": 50
  },
  {
    "field": "name",
    "hrefField": "webUrl",
    "hrefTarget": "_blank",
    "isResizable": true,
    "minWidth": 100,
    "title": "Name",
    "type": "name",
    "css": {
      "lineHeight": "32px",
      "textDecoration": "underline",
      "color": "blue",
      "fontSize": "14px",
      "cursor": "pointer"
    }
  },
  {
    "field": "lastModifiedDateTime",
    "formatStringDate": "l LT",
    "isResizable": true,
    "minWidth": 100,
    "title": "Modified",
    "type": "date",
    "css": {
      "lineHeight": "32px",
      "fontSize": "14px"
    }
  },
  {
    "field": "lastModifiedBy.user.displayName",
    "isResizable": true,
    "minWidth": 120,
    "title": "Modified by",
    "type": "text",
    "css": {
      "lineHeight": "32px",
      "fontSize": "14px"
    }
  },
  {
    "field": "size",
    "formatStringNumber": "0.0 b",
    "isResizable": true,
    "isCollapsible": true,
    "minWidth": 70,
    "title": "Size",
    "type": "number",
    "css": {
      "lineHeight": "32px",
      "fontSize": "14px"
    }
  }
]

Edit columns for anonymous access

Please update the column definition as shown below and update the hrefField to @microsoft.graph.downloadUrl for the name column as shown below to allow anonymous website visitors to download documents from SharePoint.

Did this answer your question? Thanks for the feedback There was a problem submitting your feedback. Please try again later.

Still need help? Contact Us Contact Us