Custom Code

Overview

LiveTiles Intranet Hub provides some hooks for developers to add their own custom code. This enables developers to

  • provide their own widgets, item templates, etc.
  • provide custom expressions to handle complex (and reusable) logic that might be too cumbersome to fit in to the hub JSON
  • use modern and well known approaches and patterns for development, like TypeScript, unit tests (e.g. with Jest), decent project structures, etc.

The way this works is pretty straight forward:

  1. You must create a single JavaScript file that does what ever you need.
  2. You must serve this script from somewhere and register its URL in the global hub config.
  3. During the page load we check the hub config if a custom script is registered. If this is the case, we add script tag containing the script's URL to the head of the DOM. This will load and execute your script file.
  4. We provide some hooks and a simple API (incl. TypeScript typings) that makes it easier for you to access our functionality.

Setup

To use custom code you must register your script (i.e. JS file) in the global hub config using ctrl + m. Add a new property to the root object containing a customScript object with a scriptUrl member that points to your script:

"customScript": {
  "scriptUrl": "http://localhost:8080/index.js"
}

Please note that for production environments, the referenced script file needs to be located within the current SharePoint tenant. If you want to override this, you can use the serveFromAnywhere-flag.

Development

Sample Project

To make development easier and to prevent you from having to create the usual project boilerplate we provide a sample project that can also be used as a project template. You can find this on GitHub.

It contains following things:

  • package.json with
    • The required dependencies like
      • TypeScript
      • React (the same versions that "MatchPoint UI Core" uses)
      • Weback
    • Build scripts for dev and prod (using Webpack)
  • The typings for the MatchPoint Client API
  • A web server (that will serve the script file during development)
  • Sample components
    • A custom widget
    • A custom item template

DIY

In case you want to use the MatchPoint Client API in your own project or reference it in an existing SPFx project, you can npm i it:

npm i @livetiles/livetiles-intranet-hub

Please note that in order to make use of the functionality required by the MatchPoint Client API you need to have the "LiveTiles Intranet Hub"-app installed where ever you intend to run the code.

Deployment

To use the script in a production environment you need to

  • Upload the script to a location within your SharePoint tenant
  • Register the URL in the customScript config object

Targeting .JS files for different pages

Admins can now configure the scopedSettings in a way to target custom scripts for various pages. The admins will need an identifier for each page that they want to be targeted by the .js files. The admins can configure multiple scripts that will be executed or a single script. Here is a configuration example:

 "scopedSettings": [
    {
      "identifier": {
        "url": "https://tenant.sharepoint.com/sites/sitename/SitePages/Hub.aspx"
      },
      "settings": {
        "scripts": [
          {
            "scriptUrl": "https://tenant.sharepoint.com/sites/sitename/ScriptsFolder/script1.js"
          },
          {
            "scriptUrl": "https://tenant.sharepoint.com/sites/sitename/ScriptsFolder/script2.js"
          }
        ],
      }
    },
    {
      "identifier": {
        "url": "https://tenant.sharepoint.com/sites/sitename/SitePages/Page1.aspx"
      },
      "settings": {
        "scripts": {
          "scriptUrl": "https://tenant.sharepoint.com/sites/sitename/ScriptsFolder/script3.js"
        }
      }
    },
    {
      "identifier": null,
      "settings": {
        "scripts": [
          {
            "scriptUrl": "https://tenant.sharepoint.com/sites/sitename/ScriptsFolder/wildcardscript1.js"
          },
          {
            "scriptUrl": "https://tenant.sharepoint.com/sites/sitename/ScriptsFolder/wildcardscript2.js"
          }
        ]
      }
    }
  ],

The last scripts will act like "wildcard" scripts meaning that if a page's identifier does not match any of the identifiers from the scopedSettings, then the scripts from the setting with the null identifier will be executed.

As a mention, if a customScript node is already defined in the root node of the Intranet Hub Config, then that script will be executed on every page along the other scripts that are defined in the scopedSettings.

← SharePoint IntegrationNotifications →