OutlookBridge Extensibility Guide

Transcription

1 OutlookBridge Extensibility Guide Version: 19 Date Created: Apr 10, 2014

2 Table of Contents Overview... 3 What is OutlookBridge Extensibility... 3 OutlookBridge Extensibility Conceptual Model... 3 OutlookBridge Extensibility Architecture... 4 OutlookBridge Extensibility Package Structure... 4 Extending with InvisibleStudio Change a Label or Message... 5 Change an Image... 6 Show a Field at a Form... 6 Hide a Field at a Form... 6 Add a Field... 6 Remove a Field... 7 Make a Field Read-Only... 7 Add a Top Level Object Type*... 7 Remove a Top Level Object Type*... 7 Add a Child Object Type*... 8 Remove a Child Object Type... 8 Make an Object Type Read-Only... 8 Add a Business Rule... 8 Change a Form, Subform or Dialog Layout*... 9 Page 2

3 Overview Overview This document provides an overview of the architecture and customization package structure of InvisibleCRM OutlookBridge Extensibility technology and illustrates typical product extension tasks with configuration and code examples. Refer to OutlookBridge Extensibility Reference Documentation for XML Schema and JavaScript API details. Refer to InvisibleStudio User Manual for InvisibleStudio usage details. What is OutlookBridge Extensibility OutlookBridge Extensibility is a customization package format that significantly simplifies, compared to traditional customization package, configuration of OutlookBridge technology. OutlookBridge Extensibility consists of the extensibility format specification and runtime library that implements the specification on top of the OutlookBridge platform. The specification is designed to represent only the logical model of the data and UI behavior with the ultimate goal of having one customization package for all platforms in use: desktop, mobile, online. OutlookBridge Extensibility Conceptual Model The conceptual model of the OutlookBridge Extensibility format is shown and explained below. OutlookBridge Extensibility format allows specifying the following: Object types with their respective: o Fields; o Security permissions; Page 3

4 OutlookBridge Extensibility Architecture o o Custom validation rules; Custom event handlers. Links between types: many-to-one, many-to-many. Forms with predefined extension regions, where data type specific widgets can be utilized, and custom UI event handlers. OutlookBridge Extensibility Architecture OutlookBridge implementation of the extensibility technology is built on top of the traditional customization implementation, it involves the following components, as shown at the diagram below: Extensibility The runtime library of OutlookBridge Extensibility implementation, it reads and interprets the extensible format specification customization.xml file. OutlookBridge The traditional runtime library that consumes all the traditional customization package files, some of which are generated from customization.xml file when the extensible package is built. Connector The server product specific component that consumes the metainfo.xml that specifies the server-side data model. OutlookBridge Extensibility Package Structure The OutlookBridge Extensibility customization package consists of XML and JavaScript files. The following files serve as input for the customization, while other files are either updated based on these or copied as-is: customization.xml The main configuration file that defines the data model, the forms and package settings; customization_helpers.js Contains JavaScript handlers and auxiliary functions; package_res.xml Contains English resources, strings and images; package_res.*.xml Contains localized resources, strings and images; forms_xx.xml Defines the layout of the forms, i.e. place of the extensible regions at the forms contents of the regions themselves is defined in customization.xml; metainfo.xml Defines server side data model and connector specific settings; connector_configuration.xml Defines synchronization settings. The following diagram shows the dependencies between the package files dependent files are generated during the package build process: Page 4

5 Extending with InvisibleStudio Extending with InvisibleStudio InvisibleStudio is a SharpDevelp IDE extended to simplify development of OutlookBridge customization packages. Typical package customization workflow is as follows: 1. Prerequisites: a. Install the OutlookBridge product to customize, perform data synchronization in order to download the current customization package from the server; b. Install InvisibleStudio. 2. Import the package into InvisibleStudio using File New Import project... main menu item. 3. Perform the customization as described in the following sections. 4. Build the package using Build Build Solution main menu item, resolve build errors, if any. 5. Deploy the package locally and run the customized package in Microsoft Outlook for testing using Debug Run main menu item. 6. When the customization is finished, upload the new package to the server. Tip: To simplify navigation inside customization.xml, fold on level 3 using Edit Folding Toggle on level: 3 main menu item in order to collapse irrelevant details and easily see all type names. Typical product extension tasks are described step-by-step below. Advanced tasks are marked with *. Change a Label or Message 1. Find out the resource id: a. Label: b. Message: i. Open customization.xml file; ii. Find the type corresponding to the form, subform or dialog that needs to be changed; iii. Open the ui_containers tag under the type and seek the widget corresponding to the label; iv. Copy the label resource id inside the label tag, but without the leading # (hash) symbol. i. Open customization.xml file; ii. Find the type corresponding to the message; Page 5

6 iii. Seek the validator corresponding to the message under the fields or validation tag; iv. Copy the label resource id inside the validator tag, but without the leading # (hash) symbol. c. Alternatively, you may open package_res.xml file and find the text or message itself there, then take its id and find all usages of the id in customization.xml file. 2. Change the text in English: a. Open package_res.xml file; b. Find the resource string corresponding to the id copied at the previous step; c. Change the text inside the str tag. 3. Change the text in other languages: a. Similarly to the English version, change locale specific package_res.??_??.xml files. Change an Image 1. Find out the image resource id similarly to a label id above. 2. Open package_res.xml file. 3. Find the img tag with key attribute equal to the image resource id from step Replace the content of the img tag with Base64 encoded image. You may make use of any online Base64 image convertor intended for web developers, however you should skip leading "data:image/*;base64," from the encoded string. Show a Field at a Form 1. Open customization.xml file. 2. Find the type corresponding to the form, subform or dialog that needs to be changed. 3. Find the field to show under fields tag and copy its id. 4. Open the ui_containers tag under the type and seek the region where the filed should be shown. You can see location of the regions at the form, subform or dialog using the UI Designer tab available for forms_xx.xml file. You may also seek the widget showing a field relatively to which the new field should be shown. 5. Add the widget appropriate for the field under the region tag, specify the field id and other widget parameters. See widget_base tag usages in the reference documentation for available widgets. Hide a Field at a Form 1. Similarly to the previous section, find the widget showing the field. 2. Remove the widget. Add a Field 1. Ensure that the filed to add is specified in the metainfo.xml file refer to product specific documentation for the details. 2. Open customization.xml file. 3. Find the type to add the field to, open fields tag under it. 4. Add the tag corresponding to the type of filed under fields tag. See fields element reference documentation for the list of available field types. Page 6

7 5. Specify the default value and validators under the field tag as needed. Some validators require that the resource id of the message to show is provided, corresponding resource texts need to be added to package_res.xml file and localized package_res.??_??.xml files. 6. Show the field at a form as specified in the section above. Remove a Field 1. Open customization.xml file. 2. Find the type to remove the field from and the field itself under the fields tag. 3. Find and remove any usages of the field in widgets and links by searching for the field id inside customization.xml file. 4. Remove the field. 5. You may want to remove the field from the metainfo.xml file too refer to product specific documentation for the details. Make a Field Read-Only 1. Open customization.xml file. 2. Find the field to make read-only under the fields tag of the corresponding type. 3. Add read_only attribute equal to true to the field tag. 4. Alternatively, you mat specify read_only attribute of a widget to make a filed read-only at a specific form, but editable at other forms. Add a Top Level Object Type* 1. Add server-side type definition: a. Add the top level object type definition to metainfo.xml. Refer to product specific connector documentation for the details about the format. 2. Add client-side type definition: 3. Add the UI: a. Open customization.xml file. b. Add the type tag under the root and specify the following: i. Attributes required as per the schema; ii. Fields under the child field tag. c. Optionally, you may specify business rules such as security restrictions, custom validation, events, etc. a. Open forms_xx.xml file. b. Add a form and setup its layout as described in the Change a Form, Subform or Dialog Layout section below. c. Add ui_containers/form tag under the newly added type tag in customization.xml and provide widgets in corresponding regions to present the object at the form. Remove a Top Level Object Type* This section describes how to remove a custom top level object built-in vanilla objects may need product script changes in addition to the instructions below to be removed. 1. Locate the type: Page 7

8 a. Open customization.xml file. b. Locate the type tag corresponding to the type you want to remove and note its id attribute. 2. Remove references to the type: a. Search for link_to="<the type id>", where <the type id> must be replaced with the actual id of the type, in customization.xml to find all the links to this type. b. Remove these links. 3. Remove references to the type in JavaScript: a. Go through events and custom validation handlers within the type and its fields, and remove all JavaScript functions that are used by these handlers only. b. Search for get_type() == "<the type id>", where <the type id> must be replaced with the actual id of the type, in customization.xml and customization_helpers.js to find uses of the type in other JavaScript handlers and remove or change them accordingly. 4. Remove the UI: a. Open forms_xx.xml file and remove all forms referenced by form and subform tags under ui_containers tag under the type take each form id and search for it in the forms_xx.xml file. b. Open dialogs.xml file and remove all dialogs referenced by dialog tags under ui_containers tag under the type take each dialog id and search for it in the dialogs.xml file. 5. Remove client-side type definition: a. Remove the complete type tag and its internals from customization.xml file. 6. Remove server-side type definition: a. Remove the top level object type definition from metainfo.xml. Refer to product specific connector documentation for the details about the format. Add a Child Object Type* Add the child object similarly to adding a top level object as described in Add a Top Level Object above. In addition, do the following: 1. Add links to the parent type and corresponding opposite links from the parent type. 2. Add widgets to the parent type forms to show child objects at them. Remove a Child Object Type Remove the child object similarly to removing a top level object as described in Remove a Top Level Object above. In addition, do the following: 1. Remove widgets from the parent type forms. Make an Object Type Read-Only 1. Open customization.xml file. 2. Locate the type you want to make read-only. 3. Add security/modify_filter tag with false content inside under the type tag. Add a Business Rule OutlookBridge Extensibility allows defining the following types of business rules: 1. Filed level: Page 8

9 2. Type level: 3. Link level: a. Default value see default_value and default_value_fn elements in the XML Schema reference; b. Standard validators for every data type see individual data type elements under metadata/types/fields element in the XML Schema reference. a. Security permissions see metadata/type/security element in the XML Schema reference; b. Custom validators see metadata/type/validation element in the XML Schema reference; c. Events see metadata/type/events element in the XML Schema reference; d. Natural keys see metadata/type/natural_keys element in the XML Schema reference. a. Events see individual link type elements under metadata/types/links element in the XML Schema reference. Change a Form, Subform or Dialog Layout* 1. Open forms_xx.xml file. 2. Locate the form you want to update. 3. Add, edit or remove the extensible regions as needed regions are defined by stack elements with container_id attribute specified, which is the region id. 4. Update the regions under metadata/type/ui_containers respectively. Page 9