Akumina Developer Documentation

Akumina Developer Documentation

  • API
  • Docs
  • Blog

›Widget Builder

Akumina

  • Quickstart

Modern

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

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

Virtual Page Builder

  • Akumina Virtual Page Builder
  • Using Virtual Page Layouts

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

Yo Akumina

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

Widget Info

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

Site Deployer

  • Overview
  • Version 4.8
  • Version 5.0
  • List Attribute Deployments
  • NPM Commands
  • SPA Updates and Deploying to multiple sites
  • Using site deployer with MFA

Headless

  • Quickstart
  • Headless Troubleshooting

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

Widget Builder Structure

Overview

This article will detail the Akumina Widget structure and the default templating contained within. Explanation of terms and purposes of certain properties and files will also be documented within.

Widget directory structure

   YourWidget
        ├───config
        │       config.json
        ├───contenttypes
        │       contenttypes.xml
        ├───js
        │   └───widgets
        │           yourwidget.js
        ├───views
        │       view1.html
        │       view2.html
        │       view3.html
        └───terms
                terms.xml

config.json

An empty config.json

{
    "Definition": {
        "Name": "",
        "Class": "",
        "ContentTypes": [],
        "Version": "",
        "Dependencies": [],
        "Properties": [
            {
                "name": "",
                "friendlyname": "",
                "value": "",
                "type": ""
            }
        ],
        "Views": [
            {
                "Name": "",
                "Path": "",
                "Id": ""
            }
        ],
        "JS": {
            "Default": ""
        }
    },
    "Instances": [
        {
            "Name": "",
            "Description": "",
            "Icon": "",
            "Id": "",
            "Properties": [
                {
                    "name": "",
                    "value": ""
                }
            ],
            "SelectedView": "",
            "AvailableViews": [],
            "HiddenFields": []
        }
    ],
    "Options": {
        "IsPartialDefinition": false,
        "IsDashboardWidget": false
    }
}

The "Definition" property

This property will create the corrosponding widget definition within the Akumina implementation. Remember the widget definition is used as the 'configuration' for your widget. It is not inserted into any page, but rather sets the blue print for the instances of the widgets created. Think of the defintion as the 'class' and an instance as the 'object' - You cannot create instances without the defintion. The instances are what ends up being insert into the page. Anytime you create a new instance, think of your instance as 'passing through' the definition. Some of the properties, such as 'views' control which views are available when creating the instance, this helps enforce rules for your business users.

"Definition": {
        "Name": "YourWidget", //Unique name for your widget
        "Class": "CustomerName.Widgets.YourWidget", // Akumina will create a new instance of this class and call the Init() method
        "ContentTypes": [], //array of content types to be imported into sharepoint - found in /contenttypes directory
        "Version": "", 
        "Dependencies": [], //array of other widgetnames to be loaded by getwidgetjs bundle, this allows for other module code to be used - IE you want to use the GenericListWidget code - the only way to inject the JS code is to set this value.  The framework will handle getting this module code from the getwidgetjs bundle. - see sample section below for more detail
        "Properties": [
            {
                "name": "propertyname",
                "friendlyname": "property friendly name",
                "value": "default value",
                "type": "string"
            },
            {
                "name": "propertyname2",
                "friendlyname": "property friendly name 2",
                "value": "default value 2",
                "type": "bool"
            }
        ],
        "Views": [
            {
                "Name": "view 1", //unique name used by instance
                "Path": "/Style%20Library/DigitalWorkPlace/Content/Templates/YourWidget/view1.html",
                "Id": "a04c9e8c-03d1-47a8-83c7-a9b942600f2d" //random guid
            },
            {
                "Name": "view 2", //unique name used by instance
                "Path": "/Style%20Library/DigitalWorkPlace/Content/Templates/YourWidget/view2.html",
                "Id": "f54c4053-9431-a2be-9922-651c15a24554" //random guid
            }
        ],
        "JS": {
            "Default": "/Style%20Library/DigitalWorkPlace/JS/widgets/yourwidget.js" //location in style library where widget module js gets deployed - the getwidgetJS bundle will return this if widget is detected on page
        }
}

Dependencies Array for Definition

If you have a custom widget that requires the use of another widget. A widget is just a class, the class is not available unless that class has been "injected" into the page - in the event you have a widget that is doing something like:


   var control = new Akumina.AddIn.GenericListControlWidget();
   control.Init(this.listRequest);


You would add 'GenericListWidget' to the 'Dependencies' this so that Akumina.AddIn.GenericListControlWidget is defined automatically:

{
  "Definition": {
    "Name": "CustomWidget",
    "Description": "CustomWidget",
    "Class": "Customer.Widgets.CustomWidget",
    "Dependencies": ["GenericListWidget"], //this "value" can be found within the App Manager - Widget Manager under Widget Definitions - simply take a value from the appropriate 'Widget Type' column

Without this feature the developer would be resonsible for making a call to the digitalworkplace.core.genericlistcontrolwidget.min.js on their own so that is defined prior to new'ing up that class.

Available Property Types for Widget Defintions

This values can be used in the "type" field value

type
int
string
bool
choice
json
listselector¹
itemselector²
groupselector

Figure 1 (listselector)

Figure 2 (itemselector)

The "Instance" property

"Instances": [
        {
            "Name": "Your widget instance",
            "Description": "Your widfet instance description",
            "Icon": "fa fa-circle", //font awesome icon
            "Id": "b32c3fef-83d0-e48e-2519-55da67b8a3c6", //uniqueid for your widget
            "Properties": [
                {
                    "name": "propertyname",
                    "value": "actual value"
                },
                {
                    "name": "propertyname2",
                    "value": "actual value 2"
                }
            ],
            "SelectedView": "view 1", //view name from the definition - this is so we dont define paths twice
            "AvailableViews": ["view 2"],
            "HiddenFields": ["propertyname2"] //this property wont show for the user on the front end when changing properties
        }
    ],

The "Options" property

"Options": {
        "IsPartialDefinition": false, //when set to true the import process will only import the instance, most commonly used in subsites or deploying instances of OOB Akumina widgets, IE you dont have the full definition, but you want to deploy an instance, think Generic List Control
        "IsDashboardWidget": false
}
← Google Analytics for Modern PagesAkumina Widget Builder →
  • The "Definition" property
    • Dependencies Array for Definition
    • Available Property Types for Widget Defintions
  • The "Instance" property
  • The "Options" property
Akumina Developer Documentation
Docs
Akumina Framework 5.0Akumina Widget BuilderAkumina Yeoman GeneratorSite Deployer
Community
Akumina Community Site
More
GitHubStar
Copyright © 2023 Akumina