Embedded SharePoint Library | Gutenberg Blocks for WordPress

[PRELIMINARY DOCUMENTATION FOR v13 - NOT YET RELEASED]

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

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.
  • 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.

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’.

Please note 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.

Integration

  • Navigate to WP Admin > WPO365 > Integration.
  • Click Enable WPO365 API for Microsoft Graph.
  • Click Delete tokens.
  • Click Save configuration.
  • Sign out of your WordPress website.
  • Now sign in again with Microsoft.

Please note Deleting tokens and then signing out and in again will ensure that the access token that the plugin retrieves on your behalf has all the right permissions. It may also be a good idea to clear your browser's cache for the website.

WordPress REST API

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.
  • 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.gwpo365demo.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).
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. 

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"
    }
  }
]
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