Akumina Widgets Overview (4.1) - Akumina Community

Akumina Widgets Overview (4.1)

Estimated reading time: 9 min

Akumina has introduced a fundamentally new approach in our widget framework, and how widgets in general can be used to quickly and easily add functionality to a site.

Key to this new approach is the separation of the widget’s functionality and the presentation or display of widget data.

 

It starts with the base widget definition.  There are many base widget definitions included with AppManager, and developers can easily add more.  The base definition really determines what data will be made available by the widget, as well as any manipulation of the data that may be done.

Next is the “View“.  The view is an html template developed by the designer (or the developer can also create).  The key is that the view is separate and distinct from the base widget, but uses the data the base widget provides.  Combining the base widget and the view provides the functionality and presentation for the site.

By separating the widget’s base functionality and the “view” that is used to display its data on the site, a single widget can serve many purposes by merely changing the “view” of the data. Each widget, whether it’s an image gallery, quick list or calendar widget, can have multiple “views” that control the display of the content.

This saves developer’s time from having to create new widgets to simply display content in different contexts, and leaves designers free to create new views using the available data without having to deal with editing the widget core code.

Each time a base widget definition and one of its views is used on a site it is called an “instance“.  As in the example below, from one Quicklinks base widget you can create three instances for the site: one for the main menu, one for the department menu, and one for the convenience links listing.  Each of these have their own property values, and each can use their own view.

The following sections cover how to create instances, create and map views, and then add widget instances to your site.  Development of new base widget definitions is covered in the Developers Guide.

Using the Widget Manager

The Widget Manager is used for three primary functions

  1. For developers to add new widget definitions (see the Developer Wiki for more information).
  2. For designers to add new “views” to widgets (see Managing Widget Views)
  3. For site admins to create new “instances” of widgets to be used on their site

For this guide, we will cover items 2 and 3.

The Widget Manager is accessed from the Management Apps Tab in the AppManager.

 

 

A list of all available “widget definitions” is displayed when entering the Widget Manager.  From this screen

  • New widgets can be “imported” for use on the site (see Importing and Exporting Widgets|topic=Using the Widget Export/Import in AppManager)
  • New instances can be created for a widget (see Creating a Widget Instance)
  • New Views can be added to a widget definition (see Managing Widget Views)

Creating a Widget Instance

Each unique appearance of a widget on a site needs to have an “instance” defined.  The instance specifies the property values and view that will be used in rendering the contents of the widget.

A defined instance can be used as many times as needed on a site.  If you want the same information to appear in the same widget across any number of pages, then it is best to use the same instance.  That way, and changes to the instance will appear on all pages automatically.

In this example, let’s create an instance of the “Important Dates” widget to use on a site page.

IMPORTANT: New with the 4.1 Release is the support of Content Types. Content Types are definitions of the SharePoint list structure that is required for a widget. Each of the Akumina OOTB widgets that utilize a SharePoint list for data has a Content Type associated with it (see Akumina Widgets Reference Guide (4.1)). This means that when a new widget instance is created, you have the option of automatically creating a new SharePoint list to go with it! This is a huge time savings, and means that designers and even business users can create new widget instance as they never need to access SharePoint to do so.

 

To create the instance:

  • Access the Widget Manager and click on the “View Instances” button associated with the Important Dates widget definition  .  Here you will see any existing instances of the widget.
  • Click on the “+ ADD WIDGET INSTANCE” button at the top of the page. 
  • Since the Important Dates widget using list data, it has a Content Type associated with it (AkuminaImportantDates). When a new instance is added, a wizard is first displayed asking the user what action they want to take for the supporting list. The options are:
    • Select an existing list to use that has the correct Content Type
    • Create a new list automatically with the specified name
    • Skip creating or mapping a list and just create the instance

 

Once the wizard is completed, or if a new instance is being created of a widget that DOES NOT use a Content Type, the widget properties page will be displayed.

  • Give a unique title as well as a description to this new instance.

Make the title and description of the instance as descriptive as possible to help identify its use.  This is especially important when the widget is made available for the Click/Drag/Drop dynamic widget management.
  • Set the property values for this instance of the widget.  Don’t worry, you can update them anytime as needed from either the front-end widget editor or by coming back to the Widget Manager.

NOTE: If the wizard was used, the specified list will automatically be mapped to the listname field.

NOTE: The Hide Field column can be used to “hide” any of the properties from the front-end widget editor.  This is useful if there are certain properties that you don’t want users who have access to the front-end widget editor to change.
  • Finally, select the view(s) that you want to use for this instance.  If there are multiple views available for the widget definition, you can select
  • The views available for this instance (for the front-end editing)
  • The default selected view

 

Adding Widgets to Pages

Manually Adding a Widget to a Page

Manually adding a widget to a page involves the following steps:

  1. Put the page in Edit mode
  1. Add a SharePoint “Content Editor” web part (located in the “Media and Content” Category of the web part gallery) to the page in the position you want the control

 

  1. After adding the web part, click inside the Content Block web part.  The SharePoint ribbon options will change and the “” button will appear.
  2. Click on Edit Source and an HTML Source window will open in which you can paste the widget instance code that you copied from the widget instance you wanted to add.  The widget instance code is available in the Widget Manager for the instance you created:

 

 

NOTE: If you are adding a new Content Editor web part to the page, you should edit the web part to turn the “Chrome Type” to None so that the Content Editor web part title will not be displayed on the page.

 

Adding a Widget to a Page Using Click/Drag/Drop

If a page has been setup to support adding widgets “dynamically” (such as for a personalized dashboard) then the method to add a widget is much more straightforward than the manual approach.

The dynamic adding of widgets to a page is supported by manually adding a widget such as the “DashboardContainerDragDropWidget” to the page to create the zones.  This can be added along with other widgets on the same page.

 

Example: Adding Widgets to the “Dashboard” page

When a user first accesses the dashboard page it is not populated with any widgets as it allows them to “customize” to just the widgets they want.  Changes are made by “editing” the page using the Edit Page Mode.

To access the “Edit Page” mode

  • Click on the tab on the right side of the screen. The Edit Page flyout will appear.
  • Click on “Edit Page” to enter edit mode

 

Once you enter the edit mode, you will see the list of available widgets for adding to the Dashboard.  First, we want to add the “My Team” widget.  Either search for “Team” in the widget search or scroll down the list of widgets and clickon the “My Team” entry.  This will add the widget to the page at the top of the left drop zone.

 

While still in Edit Mode, you can also change the location of any of the widgets by simply dragging and dropping them to new locations.  You will see the new location highlighted by a dotted line until you drop the widget.

 

You can “collapse” or hide the flyout while you are dragging and dropping to make it easier.

Finally, to remove an existing widget, simply click on the “x” on the widget.

NOTE: the data associated with the widget will not be deleted, only the widget itself.  If you decide to add the widget back in later, your previous data will still be intact.

To commit any of the changes you have made, you must click on the “Save” button at the lower right of the flyout.  If you want to exit without saving any of your changes, simply click the “Exit Edit Page” button.

 

Editing Widget Instance Properties

There are two ways to edit the properties for an instance of a widget.

Editing Widget Instance Properties from the Widget Manager

As was discussed when creating the instance, you can always go the Widget Manager, access the widget instance and edit the properties.

 

Editing Widget Instance Properties from the Front-End Site

Widget Instance Properties can also be accessed from the front-end site on which the instance appears.

  • Access the “Widget Edit” mode by clicking on the pencil icon in the Akumina spinner.
  • Mouse over the widget you wish to edit until it is highlighted with a green outline.  Then click.
  • The widget edit panel will open for the instance.  It will display the properties including the views which can be modified for the widget (some properties may be hidden by the settings in the Widget Manager)
  • In addition to editing the displayed properties, from the widget edit panel you can alsoJump directly to the widget instance in the AppManager using the “Manage Widget Instance” button
    • Access and Edit the View(s) associated with the instance using the Views tab
    • Jump to the Content App which is associated with this instance of the widget (if there is a content app mapped) using the Related Apps tab
  • Once the property changes are complete, clicking on the “Update” button will close the widget edit panel and instantly update the widget instance.

Be aware that if the same instance is being used on multiple pages of the site, a change to the properties of the instance will be reflected everywhere it is used.  If you do not want this to happen, use a separate instance for each page.

 

Managing Widget Views

Views can be added to Widgets to change how the data is displayed for that widget.

To add or edit a “view” for a widget, a combination of the View Manager, Widget Manager management apps and Widget Edit Panel are used.

Adding a View using View Manager

The View Manager app is targeted at the designer (or developer) to provide them a tool to manage the views (html templates) that are available for all the widgets in the system.

 

To make a new view available in the system:

  • From the View Manager, select the folder to which you want to add the new view

The folders are just organizational tools – any view from any folder can be mapped to a widget.  However, using the folders makes it easier to associate the view with the intended widget definition
  • Click on the “ADD NEW” button which will display an upload file dialog.  Select the html file associated with the new view to upload.  NOTE: If there is also custom css that is required to support the new view, that css file must be added separately to the Style Library.   It can then be mapped using the Widget Manager
  • The new view will be available to add to the widget definition (see next section)

Although the View Manager supports editing of an existing view directly, it is recommended to always edit and re-upload the html file.

Mapping the Views to a Widget Definition

Views are added to the base Widget Definition to make them available for selection in the widget instances.

 

To add a new view to a Widget Definition:

  • Access the Widget Manager
  • Click on the “EDIT WIDGET” button on the Widget Definition to which you want to add the new view
  • In the WidgetViews section, click on the “+” sign to add a new row for the view
  • Enter the View Name (which will appear in the selection list for the view)
  • Enter the path to the new view template.  You can use the “VIEW PICKER” button which will open the same folder tree structure you saw in the View Manager to select your view and fill in the path automatically.
  • If there is custom css that is associated with the view, you can also specify the css file that the widget will use in the WidgetCSS section.  This css file will need to have been placed in the Style Library in SharePoint by the designer.

 

Editing Views Directly From the Front-end Site

You can also edit a view directly from the front-end widget properties panel.

  • Select the view in the views drop-down that you want to edit
  • You can “Preview” the view right in place
  • Click on the URL displayed for the view to edit the view
  • An edit panel will open with fully highlighted html where you can make your edits, save, and immediately see the effect of the changes!

 

Which Views are being used?

From the Widget Manager, you can use the “SHOW ASSIGNED VIEWS” button to get a list of the views that are currently selected for each of the widget instances on the current site.

 

Was this article helpful?
Dislike 1
Views: 144
//]]>