Forums/Getting Started/Documentation

Vizit Pro Configuration Profiles

Jacob
posted this on September 02, 2011 10:18

Like Vizit Essential™, Vizit Pro™ has a mechanism for configuring how it looks as well as how users interact with documents in their SharePoint environment. Configuration profiles provide an interface for specifying which toolbar actions are available to end users, how keyboard shortcuts are configured, which parts of the Vizit Pro™ interface are available, as well as offering a way to handle certain events in a user's workflow allowing for even more custom interaction. Some of the options shown below are only available in version 4.0 of Vizit™.

The Mechanics

In its simplest form, a configuration profile is a JavaScript file that specifies a series of settings used by Vizit Pro™. You can place this file to a Document Library in your SharePoint farm or deploy it to your Layouts directory in the SharePoint root. Which ever option you decide, you will specify the URL to that file on Vizit™'s Configure Settings page in Central Administration. 

When Vizit Pro™ loads, the configuration profile URL that's specified in Central Administration is loaded as well. At that time, the ConfigureVizit function is called which must return the appropriate configuration object. The configuration object is comprised of multiple sections which can be used to adjust each area within Vizit Pro™. Some parts of Vizit Pro™ that can be configured are the Annotation Tree, the Property Editor, the Document Explorer, the annotation context menu, toolbar actions, the default zoom level of documents, and keyboard shortcuts. Here is an example of a simple configuration profile:

function ConfigureVizit() {
    return {
          PropertyEditor: {
               enabled: true
          },
          ExplorerGrid: {
               enabled: true,
               collapsed: true
          },
          Toolbars: [{
               title: 'Tools',
               items: [
                    'file.save',
                    'page.previous',
                    'page.next'
               ]
          }]
    };
} 

When a custom configuration profile is used, any options that are left blank have defaults. Those defaults are that every feature is disabled and there are no actions in the toolbars. Attached to this article is the configuration profile that ships with Vizit Pro™. It can be used as a starting point to make Vizit Pro™ fit your process.

SharePoint Client Object Model

One great benefit of working with SharePoint 2010 is the availability of the Client Object Model. You can use it to do many of the same things that can be done with the .NET object model to query and set values of various SharePoint objects. To provide even more power within the Vizit Pro™ Configuration Profiles, we've added the SharePoint Client Object Model so it is available in all events and custom actions that you configure.

Section by Section

Each section of the configuration profile corresponds to a different area of Vizit Pro™ that can be modified. Below is a list of those sections along with each of their options:

  • ExplorerGrid: This is referred to as the Document Explorer in the UI. It is a view into the SharePoint hierarchy allowing users to navigate through their Document Libraries and open additional documents in Vizit Pro™.
  • ToolsPanel: This is the collapsible panel that lives inside the Document Tab and houses the Property Editor and Annotation Tree.
  • PropertyEditor: This is where you can view and modify the metadata and other Document Library and Content Type fields for a particular document.
  • AnnotationTree: This shows all of the annotations that are on the document including information about their location within the document as well as name of the user who created it.
  • AnnotationProperties: This is the context menu that appears when right clicking on annotations.
  • DocumentPanel: This is the area where the document is displayed.
  • Search: This refers to both Column Query as well as SharePoint's keyword search.
  • Document: This allows for configuration of various document-related events and save-related options.
  • Tabbar: This is the toolbar that displays above each document in the side-by-side view.
  • Quickbar: This is the toolbar that is in the upper right hand corner of Vizit Pro™. The About Vizit™ button displays in this toolbar.
  • Toolbars: This is the main toolbar within the interface. It is a series of tabs that contain actions.
  • Keyboard: This refers to any keyboard shortcuts that are mapped to actions.

ExplorerGrid

The Document Explorer can be either collapsed or disabled entirely. Paging and the width of the control is also configured here. Here is an example of the ExplorerGrid section of the configuration profile:

...

ExplorerGrid: {
     enabled: true,
     collapsed: false,
     pagingEnabled: true,
     pageSize: 100,
     width: 250
},

...

The example above describes the Document Explorer as being expanded and having a width of 250 pixels. A paging toolbar will be placed at the bottom of the control allowing users to navigate across large document libraries in 100-item chunks.

Some other options are below:

  • navigationDisabled: A boolean value indicating whether or not the user will be able to navigate into and out of subfolders, libraries, or subsites. This defaults to false.
  • onNavigate: This is a delegate that is fired when the user navigates out of a subfolder, library, or subsite. The parameter passed to this delegate contains a Location property which specifies the Url destination that the Document Explorer will be navigated to. If false is returned, the navigation will be canceled. This can be used to lock allow users to navigate within the document library of the active document while preventing them from navigating to other document libraries and lists.
  • onLoad: This is a delegate that is fired with the Document Explorer loads for the first time. Like the onNavigate delegate, the parameter passed contains the Location property indiciating the Url destination that the Document Explorer will load. If false is returned, the load will be canceled.

ToolsPanel

The Tools Panel can be collapsed and the width can be specified. To disable this control, you must disable both the Property Editor as well as the Annotation Tree. An example can be found below:

...

ToolsPanel: {
     collapsed: true,
     width: 400
},

...

Here, the Tools Panel would be collapsed, but when expanded it would be 400 pixels wide.

PropertyEditor

The Property Editor can be collapsed or disabled entirely. Because it is part of the Tools Panel, the width and the overall collapsed state of that control must be adjusted in that section. You can also indicate whether or not the ENTER key can be used to save the document when in edit mode, attach to specific events, and force the Property Editor to open in Edit Mode automatically.

...

PropertyEditor: {
     enabled: true,
     collapsed: false,
     saveOnEnterKey: true,
     openInEditMode: true
},

...

In this example, the Property Editor will be immediately ready for the user to make changes to an open document. They will also be able to quickly save the document by pressing the ENTER key.

Here is an other example highlighting attaching to the onBeforeSave event:

...

PropertyEditor: {
     enabled: true,
     collapsed: false,
     onBeforeSave: function(args) {
          if(args.ListUrl.indexOf('/path/to/a/document_library/') >= 0)
               return false;
     }
},

...

This second example creates a Property Editor that simply cancels the save if the document being modified is part of a specific document library. The args parameters that are passed to both the onLoad and onBeforeSave functions contain the same 3 properties:

  • IsEditMode: A boolean value indicating whether or not the Property Editor is in Edit Mode.
  • ListUrl: A string representing the URL that the current document is in.
  • DOM: A reference to the Property Editor iframe's Document Object Model.
Returning false from the onBeforeSave event cancels the operation. The return value from the onLoad event handler is ignored.

AnnotationTree

The AnnotationTree can be collapsed or disabled entirely. Just like the Property Editor, the width and collapsing of the overall Tools Panel must be specified in the ToolsPanel section of the configuration profile.

...

AnnotationTree: {
     enabled: true,
     collapsed: false
},

...

Here, the annotation tree will be expanded. If neither the Property Editor and Annotation Tree are collapsed, the Property Editor will take precedence and the Annotation Tree will be collapsed.

AnnotationProperties

The context menu for annotations can only be enabled or disabled. This is what that would look like.

...

AnnotationProperties: {
     enabled: true
},

...

 

DocumentPanel

The Document Panel has a thumbnail viewer in it that can either be hidden or displayed when a document is opened. The user will always have the ability to show the thumbnails using the double arrow icon in the lower left hand corner of the Document Panel. The default behavior of Vizit Pro™ is to hide the thumbnails to maximize the space available to view the document. Here's an example of showing thumbnails by default:

...

DocumentPanel: {
     hideThumbnails: false
},

...


Search

Both the Column Query and Keyword Search can be disabled by modifying this section of the configuration profile. You can also enable or disable paging and set the paging size. Here is an example:

...

Search: {
     enabled: true,
     pagingEnabled: true,
     pageSize: 100
},

...

This example has search enabled. The user will be able to navigate through 100-item batches using the paging toolbar that's presented to them after a search is performed.

Document

The Document section is where certain save-related options can be configured. Events relating to saving, loading, splitting, and merging are also available. Here is an example:

...

Document: {
     alwaysPromptOnSave: true,
     quickSave: true
},

...

Here is a complete list of the properties of the Document section of the configuration profile:

  • alwaysPromptOnSave: A boolean value indicating whether or not the user should be prompted to save even if versioning is not enabled for the document library. This defaults to false. This value is ignored if quickSave is set to true.
  • quickSave: A boolean value indicating whether or not automatic minor versioning with an empty comment should be applied when the document is saved. This defaults to false.
  • saveSourceAfterSplit: A boolean value indicating whether or not the source document should automatically be saved after a split operation is performed. The user will be prompted if quickSave and alwaysPromptOnSave are configured accordingly. This defaults to false.
  • openResultsAfterSplit: A boolean value indicating whether or not all documents resulting from a split operation will be opened after a split operation is completed. The source document will remain the active tab after all the resulting documents have opened. This defaults to false.
  • onSaved: A delegate that is called after a save operation is performed. The argument passed to this delegate contains two properties: VizitWindow and OpeningWindow. VizitWindow is the JavaScript window object of the Vizit™ browser window. OpeningWindow is the JavaScript window object of the window that Vizit™ was opened from. With those parameters, this event can be used to reload the opening window and/or close the Vizit™ window as part of an integration's workflow process.
  • onLoad: A delegate that is called after a document is done loading. The argument that is passed to this delegate contains the following properties:
    • IsSupported: A boolean value indicating whether or not the document is supported by Vizit Pro™ for viewing and/or editing.
    • IsDocumentTab: A boolean value indicating whether or not the tab that has completed loading is a document tab. This is always true for this delegate.
    • ListUrl: The Url of the SharePoint document library that the document is in. This is undefined if the document is not in SharePoint.
    • WebUrl: The Url of the SharePoint Site that the document is in. This is undefined if the document is not in SharePoint.
    • ItemId: The numerical ID of the document. This is undefined if the document is not in SharePoint.
  • onChange: A delegate that is called after the tab changes. The argument that is passed to this delegate is identical to the one passed to the onLoad event. The IsDocumentTab property will only be true if the tab that is being changed to is a document tab. All other properties will be undefined if the newly activated tab is a document tab.
  • onSplit: A delegate that is called after a split operation is performed. The argument that is passed to this delegate contains the following properties:
    • success: A boolean value indicating whether or not the split operation was successful.
    • message: A string representing the error message returned from the server if the split operation failed. This will be undefined if the operation was successful.
    • docs: An array of all the document objects created as a result of the split. The first document object represents the source document. This will be undefined if the operation was not successful.
  • onMerge: A delegate that is called after a merge operation is performed. The argument that is passed to the delegate contains the following properties: 
    • success: A boolean value indicating whether or not the merge operation was successful.
    • message: A string representing the error message returned from the server if the split operation failed. This will be undefined if the operation was successful.

Tabbar

The Tabbar is the toolbar that is displayed within a Document's tab when in comparison view. The actions are limited to those that do not modify documents. Here is an example of a Tabbar configuration:

...

Tabbar: [
     'view.zoomIn',
     'view.zoomOut',
     '|',
     'fit.width',
     'fit.height',
     '|',
     'page.previous',
     'page.next'
],

...

Please see the section on Actions for a full list of actions available for all toolbars in Vizit Pro™. 

Quickbar

The Quickbar is the toolbar that appears in the upper right hand corner of Vizit Pro™. By default, this is where the About Vizit™ and Help actions are located, but any actions can be placed here. Unlike the Tabbar, actions placed here act on the currently active document. The About Vizit action cannot be removed from the Quickbar. If it is not specified, it will be placed to the far right of the toolbar. Here is an example of a Quickbar configuration:

...

Quickbar: [
     'file.save'
],

...

This example places the save action in the Quickbar along with the About Vizit™ action which is added automatically.

Toolbars

The Toolbars section allows you to configure the main area at the top of Vizit Pro™ where actions usually reside. Toolbars are an array of tabs and each of those tabs contain actions. If only one tab is specified, the tab and section title will not be shown. By default Vizit™ is localized in many languages so the title is specified using the titleKey property which is looked up at the time the viewer is loaded in a particular locale. For custom configuration profiles, you can specify a title property instead. Here is a Toolbars configuration:

...

Toolbars: [{
     title: 'Actions',
     items: [
           'file.mail',
           'file.export',
           '|',
           'page.previous',
           'page.next'
     ]
}],

...

The example above shows a simple single-tab toolbar that only has actions for mailing, exporting, and navigating the document.

Keyboard

The Keyboard section provides a way for specifying keyboard shortcuts to actions within Vizit Pro™. It is comprised of an array of objects that specify the action that will be triggered by the keyboard shortcut, the keys that can trigger the action, and any modifier keys that are required in addition to trigger keys. Some keyboard shortcuts have default behaviors in the web browser, to prevent that default action, you can stop the event by setting the stopEvent property to true. Unfortunately, there are some keyboard combinations that are reserved by the browser and cannot be used. These combinations vary from browser to browser.

Here are the parameters that can be set in a single keyboard shortcut configuration:

  • action: The key of the action that will be triggered when the keyboard shortcut is used.
  • key: The keycode or array of keycodes that will trigger the event. If multiple keycodes are provided, any one of those keycodes will trigger the action.
  • ctrl: A boolean value indicating whether or not the CTRL key must be held while the specified key is pressed to trigger the action. This defaults to false.
  • shift: A boolean value indicating whether or not the SHIFT key must be held while the specified key is pressed to trigger the action. This defaults to false.
  • stopEvent: A boolean value indicating whether or not the keyboard shortcut will not also trigger the browser's default behavior for that keyboard combination. This defaults to false. 

Here is a sample Keyboard configuration:

...

Keyboard: [{
     action: 'file.save',
     key: 's',
     ctrl: true,
     shift: true,
     stopEvent: true
}],

... 

The key property must be specified as the number indicating the JavaScript keycode. For many of the characters, we look up the keycode for you automatically. You just need to specify the character in quotes as seen in the above example instead of the keycode.

Here you will find a link to our documentation for Vizit.API calls for Vizit Version 4.1: Vizit.API

Attached to this KB is also the default configuration profile for Vizit Pro™ which can be used as a starting point for creating your own configuration profile.
 
Topic is closed for comments