KWizCom Corporation. List Aggregator App. User Guide

Transcription

1 KWizCom Corporation List Aggregator App User Guide

2 Copyright KWizCom Corporation. All rights reserved. Company Headquarters KWizCom 95 Mural Street, Suite 600 Richmond Hill, ON L4B 3G2 Canada Web site: Sales Telephone: Copyright KWizCom Corp. All rights reserved. Page 2 of 23

3 CONTENTS Contents... 3 introduction... 4 General... 4 Product Overview... 5 Key Features... 5 Installation... 6 Software Requirements... 6 Server Requirements... 6 Client Requirements... 6 Installation Procedure... 6 Administration Guide... 7 List Aggregator how does it work?... 7 Adding the List Aggregator web part to your page... 7 List Aggregator web part Basic configuration... 8 Creating data sources Customizing the List Aggregator Display Template How does a template work? Available controls Configuring Controls Advanced Customizations Using Formulas and Code Snippets Copyright KWizCom Corp. All rights reserved. Page 3 of 23

4 INTRODUCTION GENERAL This document provides all the information needed to install, evaluate and deploy this KWizCom product: Product Overview Installation Guide Administration Guide Copyright KWizCom Corp. All rights reserved. Page 4 of 23

5 PRODUCT OVERVIEW The KWizCom List Aggregator App is a SharePoint Online add-in that aggregates list items and documents from multiple sources across sites and site-collections. The retrieved items are displayed in a fully-customizable grid display, enabling you to have the exact aggregated view you need, including custom menus and actions. KEY FEATURES Feature Use standard SharePoint views to define cross-site queries for content aggregation Aggregation of various list types Cross-site aggregation Supports Cross-site-Collection aggregation Aggregate lists and libraries by content type Refine the aggregation scope by site/list name patterns Much more flexible than only aggregating by content types! Includes various templates for grouping, page navigation, global and per-item actions Fully customizable display template KWizCom List Aggregator App Copyright KWizCom Corp. All rights reserved. Page 5 of 23

6 INSTALLATION SOFTWARE REQUIREMENTS SERVER REQUIREMENTS SharePoint 2013/2016 configured for app hosting SharePoint online (Office 365) CLIENT REQUIREMENTS Windows 7+ Microsoft Internet Explorer 9+, Mozilla Firefox (Latest version), Google Chrome (Latest version). INSTALLATION PROCEDURE Please refer to installation instruction on KWizCom s website: Copyright KWizCom Corp. All rights reserved. Page 6 of 23

7 ADMINISTRATION GUIDE LIST AGGREGATOR HOW DOES IT WORK? The List Aggregator web part runs a defined query on configured data sources, and displays the retrieved items in a customizable grid display. How is the query defined? Instead of requiring you to edit your query by listing the columns you want to see, configuring a filtering criteria and sorting order, we simply let you select a list view. That list view definition is used as the query definition which defines which column to retrieve, column-based filtering criteria and sorting order. What are data sources? A data source defines boundaries for running the query, including: Root url to start querying from Scope of query (site-collection, specific site, specific lists etc.) Searched List types Site and list name patterns Searched content type As mentioned above, the List Aggregator web part can run your search query on multiple data sources. ADDING THE LIST AGGREGATOR WEB PART TO YOUR PAGE List Aggregator app is part of KWizCom Data View Tools. After you install the package according to installation instructions, you will see the following web parts in the gallery: Copyright KWizCom Corp. All rights reserved. Page 7 of 23

8 Click List Aggregator to add the List Aggregator web part to your page. LIST AGGREGATOR WEB PART BASIC CONFIGURATION To configure the web edit the web part settings: You will see the web part s toolpane: Copyright KWizCom Corp. All rights reserved. Page 8 of 23

9 Property Description Select list view used as query definition SharePoint site url SharePoint list List view Maximum number of items Maximum number of items per list Site where the list that includes the view you want to use as query definition is located. Select the list that includes the view you want to use as query definition. Select the view that will be used as the query definition. This property allows you to limit the number of items returned from the data source. This property allows you to limit the number of items returned from each list. Copyright KWizCom Corp. All rights reserved. Page 9 of 23

10 New Item Url The List Aggregator default display template includes an Add Item menu. You can provide a url for this menu (or remove it using the template designer see later in this admin guide) CREATING DATA SOURCES To create a new data source, click the Add new data source button below the Manage data sources section in the toolpane: This will open the Configure Data Source dialog: Copyright KWizCom Corp. All rights reserved. Page 10 of 23

11 Property Friendly name Aggregation scope Starting SharePoint site url Choose sub site Description Provide a clear name for the data source. example: Project tasks Select the scope for your aggregation: Entire site collection Specific site Specific site and sub-sites Specific lists This is the root site of the data source, which is the top-level location where aggregation in the current data source starts from. This property is visible only when the scope is not Entire site collection. This drop-down list enables you to select the actual sub-site which is below the starting site url, which will be the aggregation starting point. Copyright KWizCom Corp. All rights reserved. Page 11 of 23

12 List title pattern Site title pattern List types Content type Enabled/Disable This property enables limiting search results by filtering the retrieved items by list title. You can provide also partial strings using asterisks. example: using Project* will aggregate items only from lists that their names start with the string Project. This property enables limiting search results by filtering the retrieved items by site title. You can provide also partial strings using asterisks. example: using Project* will aggregate items only from lists that are in sites that their names start with the string Project. This multi-select list enables selecting multiple list types; only items from the selected list types will be aggregated. This list enables limiting the aggregation scope further by a selected content type. This toggle enables enabling or disabling the data source, so items will be aggregated from the data source only if it is enabled. IMPORTANT: After you configured your data source/s, don t forget to save the web part settings. As mentioned in previous sections, you can create multiple data sources. List Aggregator web part will run the defined query on all enabled data sources and will present the retrieved items in the following grid: As you can see, this grid has some pre-defined settings which include: Paging Bulk actions (actions that work on multiple-selected items) there s one action which is Delete selected Copyright KWizCom Corp. All rights reserved. Page 12 of 23

13 Per-item actions such as: view item end item Global menus at the bottom the New item menu. All these are just default settings of the used template. The following picture shows the parts of which the web part is composed: Each part is called control, so in this example you can see that the main content of the web part includes the Menu bar control, Paging control and Table control. You can fully customize this template, by using these and other controls and customize each of these controls properties, to make it match your exact requirements. See details in the next section. Copyright KWizCom Corp. All rights reserved. Page 13 of 23

14 CUSTOMIZING THE LIST AGGREGATOR DISPLAY TEMPLATE HOW DOES A TEMPLATE WORK? The List Aggregator UI can be customized by using the template designer. To open the designer, while in edit mode, click the web part s Open designer button: This will open the following template designer, side-by-side with the web part so you ll be able to see the immediate results of your customizations: Copyright KWizCom Corp. All rights reserved. Page 14 of 23

15 The List Aggregator template is made of the following parts: Web part header This part is always displayed at the top of the web part and displays several levels of headers: title, sub-title, small title and description. These properties are displayed at the top part, and are optional (you can leave them empty or part of them). main content This is the container object of the entire web part. From this point the contained parts (controls) are structured as a hierarchy where each control contains another control. This way you can create a template that has a flexible layout, where you control how many controls are displayed and what is their order of display. Copyright KWizCom Corp. All rights reserved. Page 15 of 23

16 Controls These are the parts that compose the UI of the List Aggregator UI. Each control has its own properties and can optionally contain another control that will be displayed after it. Example: For the following template: We have the following control hierarchy: Copyright KWizCom Corp. All rights reserved. Page 16 of 23

17 main content contains Menu bar control Menu bar contains Paging control Paging contains Table control AVAILABLE CONTROLS The template designer includes the following controls: Control Menu bar Description Displays top/bottom menu bar with configurable menus Example: Groups A collapsible group control that groups your items by a specific column. You can also add custom buttons to the group. Example: in this template we used Group control to group aggregated tasks by their status Copyright KWizCom Corp. All rights reserved. Page 17 of 23

18 column. Tabs A Tabs control that groups your items based on a column, and displays them in separate tabs. Example: in this template we used Tabs control to divide the aggregated tasks to tabs by Assigned To column. Paging A paging control that splits your items into several pages, useful when you have large list of items. You can select how many items per page or change the display of the paging control in the control configuration settings. Example: Table A simple table control that shows all columns from your data source. You can add up to 4 item actions, and control the item click behavior. Copyright KWizCom Corp. All rights reserved. Page 18 of 23

19 Example: List An inbox-style responsive list control that always looks great. You can display up to 4 labels, add up to 4 custom item actions, and control the item-click behavior. Example: Filter (Pro. edition) Dynamic filter control, enabling you to filter the connected list by various columns. In addition, end-user can add additional columns to the filter control by drag&drop the required column to the filter control area. Copyright KWizCom Corp. All rights reserved. Page 19 of 23

20 CONFIGURING CONTROLS Once you select a control to display, you can also customize its behavior by configuring its settings. Each type of control has its relevant settings. Example: The Paging control has the following settings, which are self-explanatory: Copyright KWizCom Corp. All rights reserved. Page 20 of 23

21 ADVANCED CUSTOMIZATIONS USING FORMULAS AND CODE SNIPPETS With the template designer, you can also include formulas and code snippets using knockout. Adding custom formulas and creating custom actions requires knowledge of knockout. Click here to learn more about knockout. When a property allows you to include a formula or script, you will see edit formula... link below the field, such as in the following screenshot: Formulas enable you to display dynamic content in various places in your aggregator web part instead of hardcoded captions. Example 1: In the following List Aggregator web part UI, you can see at the top part a caption showing the number of selected items: Copyright KWizCom Corp. All rights reserved. Page 21 of 23

22 This is implemented using the Description property which was updated with the formula editor, by simply selecting the Selected items count component snippet: The result script is the following, which you can of course customize according to your needs: {text:selectedcount() === 0? 'no selected items...' : SelectedCount() === 1? 'one item selected' : SelectedCount() + ' items selected'} Copyright KWizCom Corp. All rights reserved. Page 22 of 23

23 Example 2: In the following List Aggregator web part UI, you can see the following 4 item actions: These 4 actions were configured in the List control. Here s how the view item properties action ( ) was created using the script editor: Copyright KWizCom Corp. All rights reserved. Page 23 of 23