Akumina Developer Documentation

Akumina Developer Documentation

  • API
  • Docs
  • Blog

›Advanced

Akumina

  • Quickstart

Yo Akumina

  • Yo Akumina
  • Start with Yeoman
  • React
  • Simple template

Widget Builder

  • Widget Builder Structure
  • Akumina Widget Builder
  • Skipping instances
  • Token replacement for widget properties

Widget Development Quickstart

  • Setting up the Project
  • Configuring .env file
  • Configuring - akumina.sitedployer.config.json file
  • Configuring - akumina.config.json file
  • Extras

Widget Info

  • Akumina Widgets Overview
  • Building a New Widget Instance
  • Widget Views
  • Widget Properties
  • Global vs Local widgets (Widget Scoping)
  • Akumina React Widgets
  • Callbacks
  • RenderChildWidgets
  • Vendor Package List

Virtual Page Builder

  • Akumina Virtual Page Builder
  • Using Virtual Page Layouts
  • Creating a Custom Layout

Stream Card Builder

  • Installation
  • Stream Card Builder
  • Custom Cards
  • Activity Comments Config
  • Akumina Activity Stream PUSH Subscription using PowerAutomate to connect to ServiceNow
  • Akumina Activity Stream PUSH Subscription using PowerAutomate to connect to Dynamic 365

Site Deployer

  • Overview
  • Version 6.0
  • List Attribute Deployments
  • NPM Commands
  • SPA Updates and Deploying to multiple sites

Authoring

  • Content Action Event
  • Publish Validation Integration
  • Field Event Integration
  • CK Editor external plugins

Headless

  • Quickstart
  • Headless Teams support
  • Headless Troubleshooting

Modern

  • Overview
  • FAQ
  • Single Page Application
  • Modern Web Part Library
  • Google Analytics for Modern Pages

Site Creator

  • Overview
  • Adding A Custom Site Definition
  • Core Step Classes
  • Custom Site Definition Components
  • Custom Site Definition XML
  • Custom Subsite Definitions
  • Sample Step Code
  • Supported Tokens

Azure DevOps

  • CI/CD using Azure DevOps
  • Setting up a build to deploy a site package
  • Setting up a build to deploy file to App Manager hosted in an app service

Configuration

  • Configuration Context Overview
  • Edit the Redis cache timeout
  • Using a key vault for the client id and client secret

Debugging

  • Debugging in Akumina

Advanced

  • Central Site Collection Support
  • Eventing OOB Digital Workplace Events
  • Working with custom JSX Views
  • Page Indexing

Service Hub

  • Quickstart

Patch Notes

  • Patch Notes

Central Site Collection Support

Central Site Collection

The following configuration allows for rapid re-use of Akumina tooling across many site collections using an 'install once' model. This allows for easy maintenance, upgrades and code deployments. Deploy once and affect all sites configured to use it.

  • Central Site - site collection where the following Akumina specific components reside - this is where 'developers' will primarily being deploying too
    • Widgets
    • Widget Views
    • Configuration settings (DigispaceConfigurationIDS_AK)
    • Lists that need to be shared across many sites - may be specific to your implementation
  • Delivery Site - site collection that will be configured to point to the 'Central Site' - this is where you will be site specific lists and libraries - especially those that are not going to be shared across other sites.

Your enterprise environment can also contain MULTIPLE Central Site's - Possibly 1 site collection for where Akumina widgets are installed and 1 site collection where shared lists can reside.

For example:

  • Central Site (Akumina) - /sites/akumina-assets
    • Code / Widget deployment
  • Central Site (Client Specific) /sites/customer-shared-assets
    • Specific lists / libraries / data

It is up to your information archecture on how many 'Central Sites' you want to use. Akumina recommends at least 1 central site for the Akumina bits as denoted above.

Quick usecases for a Central/Cross site

  • Maybe you want to share a MENU across multiple sites, allowing a content author to update a menu item in 1 list and have it reflect on all sites sharing using that MENU
  • You may have a GLOBAL ALERT List where content authors can add a new alert in one location and have it show up across all sites
  • You want to have a GLOBAL FOOTER where you dont have to manage the content for the footer in each site
  • You want to roll out a new menu DESIGN / HTML / CSS across all sites without duplicating code or deploying to each site

Delivery Site Contents - Classic

Master page updates

The classic Sharepoint master page should contain the following references

  • JS
    • /sites/centralsite/digitalworkplace.vendor.min.js
    • /sites/centralsite/digitalworkplace.vendor-nomin.js
    • /sites/centralsite/digitalworkplace.min.js
    • /sites/localsite/digitalworkplace.env.js (this will contain configuration items to communicate with the appropriate central site)
  • CSS
    • /sites/centralsite/digitalworkplace.min.css

digitalworkplace.env.js updates

var LoaderConfiguration = LoaderConfiguration || {};
if ((typeof LoaderConfiguration.Environment) === 'undefined') {
    //Add shipped steps to loader

    LoaderConfiguration.Environment = {
        Init: function (config) {
            // tenant config:
           Akumina.Digispace.ConfigurationContext.InterchangeURL = "<AppManagerUrl>";
           Akumina.Digispace.ConfigurationContext.InterchangeQueryKey = "<AppManagerQueryKey>";
        }
    }
}

var AdditionalSteps = AdditionalSteps || {};
if ((typeof AdditionalSteps.EnvSteps) === 'undefined') {
    AdditionalSteps.EnvSteps = {
        Init: function () {
            var steps = [];
            steps.push({ stepName: "Auto Clear Local Cache", additionalSteps: [{ name: "Custom SetConfig", callback: AdditionalSteps.EnvSteps.SetConfig }] });
            return steps;
        },
        SetConfig: function () { 
            //uniqueId from central site collection (see below)
            Akumina.Digispace.SiteContext.UniqueId = "<UniqueId>"; 
            //Configure where views are loaded from
            Akumina.Digispace.ConfigurationContext.TemplateURLPrefix = "<Central Site CollectionUrl>"; //can be CDN as well
            //Configure what site the widgets/widget instances come from
            Akumina.Digispace.ConfigurationContext.WidgetInstanceSiteUrl = "<Central Site CollectionUrl>";

            Akumina.Digispace.AppPart.Eventing.Publish('/loader/onexecuted/');
        }
    }
}

Delivery Site Contents - Modern

Modern usage in this mode is very minimal - this mode is refered to as "SPA" - Single Page Application - this means there is only 1 driver page

  • App
    • akumina-single-page-application-client-side-solution.spkg
  • Site Pages
    • akumina.aspx

You can think of the single page application spkg as the replacement to the env.js we managed in Classic - it also contains the 'VirtualPageWidget' instance which handles all of the future Akumina page rendering and minipulation

Getting UniqueId

Widget Scope

Using the central site model, widgets can be either global or local. Where the widget is deployed dictates how broadly it can be used and the degree of local control over the widget instance that can be exercised. A site collection will use its own widgets or else the central site widget instances; the instance IDs can be the same for both. In both cases the widget instances are in the Akumina Assets central site collection; the site id and web id values are different to denote where the widget applies. A widget deployed to the Akumina Assets central site can be used within any site collection that uses the central site. A widget deployed to a specific site collection can be used only in that site collection, as shown below.

Delivery site 2 will use the same instance as delivery site 1 – any change made will affect the widget on all sites. Delivery site 2 can use an instance with the same ID as delivery site 1, however, it is its own instance, needing to be deployed and managed independently. A change to the properties of the delivery site 1 instance will affect only delivery site 1, likewise a change to the properties of the delivery site 2 instance will affect only delivery site 2, etc.

NOTE: The widget instances can be overridden when used within a virtual page as well, giving further local control under either model.

Widget Support for Cross site collection data retrieval

There are many widgets which support a hidden property called 'sitecollectionurl' - the code of the widgets are written to understand this property. If you donot see the property in your installation, you can simply add a new text property to the widget definition.

Widgets that support sitecollectionurl
The plan is to have every widget support this feature in future releases - if a widget is missing this support it is easy to patch / hotfix - submit a request on our support form: https://www.akumina.com/technical-support/

  • BannerWidget
  • CollatedDepartmentNewsWidget
  • ContentBlockWidget
  • DepartmentListWidget
  • DepartmentNewsWidget
  • DepartmentNewsItemWidget
  • DepartmentNewsListWidget
  • EventDetailWidget
  • GenericItemWidget
  • GenericListWidget
  • ImportantDatesWidget
  • LatestMediaWidget
  • MyFormsWidget
  • QuickLinksWidget
  • BlogDetailWidget
  • BlogsWidget
  • BreakingNewsDetailWidget
  • FoundationJobVacanciesWidget
  • MyAnnouncementsWidget
  • NewsCommentWidget
  • NewsDetailWidget
  • RelatedNewsWidget
  • SpecialAnnouncementsDetailWidget

sitecollectionurl usage

name: sitecollectionurl - type: text - value: empty

Widget Definition

Current user experience for setting the site collection url

Coming soon - site selector when choosing a list - this site picker may exist in the list selector

Using GetList to query across site collections

The GetList method supports a request object allowing you to specify the site collection you want to query, this allows for cross site collection data retrieval..

Example to query Central Site:


    var request = {};
    request.listName = 'FoundationTopNavigation_AK';
    request.selectFields = 'ID,Title';
    //set the site collection url here
    //if contenxtSiteUrl is NOT set, it will query the list in the current site that the widget is rendering in
    request.contextSiteUrl = 'https://tenant.sharepoint.com/sites/centralsite'
    var legacyQuery = true;
    new Akumina.Digispace.Data.DataFactory(legacyQuery).GetList(request).then(function(x) {
        var listEnumerator = x.response.listItems.getEnumerator();
        var itemArr = [];
        while(listEnumerator.moveNext()) {
             var listItem = listEnumerator.get_current();
             var id = listItem.get_item('ID');
            var title = listItem.get_item('Title');
            itemArr.push({'ID': id, 'Title': title});
        }
        console.log(itemArr);
    });
    

Deployment scenarios and Package setup

With the additional site collections in use, your deployment methodology will change slightly as the information architecture has changed Here is an example project setup

  • Project for Widgets - This project will deploy to /sites/akumina-assets
  • Project for Global Lists / Assets - this project will deploy to /sites/customer-shared-assets
  • Project for a Particular Site - this project will deploy to /sites/foundationsite

This allows for different deployment configurations and minimal impact depending on the scenario - IE, I have to deploy a widget change, I only deploy the Widget Project. If I need to deploy a global update for an asset or list, I dont interfere with the other sites directly or mess around with Akumina bits.

akumina-assetscustomer-shared-assetsdelivery
PrerequisiteCore installCore Content TypesCore Content Types or Foundation Delivery
Site Deployer Stepsakumina-assetscustomer-shared-assetsdelivery
masterpagex
jsx
cssx
listsxx
layoutsx
pagesx
virtualpagesx
controlsx
widgetsx
contentfiles*
imagefilesx
homepagex
fonts*
updatelistsxx
addtermsets*x
cdnassets
sleep
exportlists
uploadfiles*x
spusersearch
webpartgallery*
groups***
sitepropertiesx
spusersearch
virtuallayoutx
updatepagecache

* optional

Sample Site Packages for use with Site Deployer

We can easily share site deployer packages for use with rolling up minimal delivery environments for both classic and modern - the goal is to eventually have these as an option in the Site Creator Management App within App Manager which allows business users to deploy Akumina functionality to any site they wish.. Look for those in upcoming point releases.

  • Classic Minimal Site Deployer package (for developers) - Coming soon
  • Modern Minimal Site Deploery package (for developers) - Coming soon
← Debugging in AkuminaEventing OOB Digital Workplace Events →
Akumina Developer Documentation
Docs
Akumina Framework 5.0Akumina Widget BuilderAkumina Yeoman GeneratorSite Deployer
Community
Akumina Community Site
More
GitHubStar
Copyright © 2024 Akumina