12662 “DataViewUtils: Add documentation for usage of the package”

12576 “DataViewUtils: Prepare documentation for the package”
Updates a style of the commands

docs/api/converter-helper.md

@@ -0,0 +1,168 @@
+# converterHelper
+> The ```converterHelper``` provides functions in order to check properties of the dataView.
+
+The ```powerbi.extensibility.utils.dataview.converterHelper``` module provides the following functions:
+
+* [categoryIsAlsoSeriesRole](#categoryisalsoseriesrole)
+* [getSeriesName](#getseriesname)
+* [isImageUrlColumn](#isimageurlcolumn)
+* [isWebUrlColumn](#isweburlcolumn)
+* [hasImageUrlColumn](#hasimageurlcolumn)
+
+## categoryIsAlsoSeriesRole
+
+This function checks if the category is also series.
+
+```typescript
+function categoryIsAlsoSeriesRole(dataView: DataViewCategorical, seriesRoleName: string, categoryRoleName: string): boolean;
+```
+
+### Example
+
+```typescript
+import DataViewCategorical = powerbi.DataViewCategorical;
+import converterHelper = powerbi.extensibility.utils.dataview.converterHelper;
+
+// This object is actually part of the dataView object.
+let categorical: DataViewCategorical = {
+    categories: [{
+        source: {
+            displayName: "Microsoft",
+            roles: {
+                "power": true,
+                "bi": true
+            }
+        },
+        values: []
+    }]
+};
+
+converterHelper.categoryIsAlsoSeriesRole(categorical, "power", "bi");
+
+// returns: true
+```
+
+## getSeriesName
+
+This function returns a name of the series.
+
+```typescript
+function getSeriesName(source: DataViewMetadataColumn): PrimitiveValue;
+```
+
+### Example
+
+```typescript
+import DataViewMetadataColumn = powerbi.DataViewMetadataColumn;
+import converterHelper = powerbi.extensibility.utils.dataview.converterHelper;
+
+// This object is actually part of the dataView object.
+let metadata: DataViewMetadataColumn = {
+    displayName: "Microsoft",
+    roles: {
+        "power": true,
+        "bi": true
+    },
+    groupName: "Power BI"
+};
+
+converterHelper.getSeriesName(metadata);
+
+// returns: Power BI
+```
+
+## isImageUrlColumn
+
+This function checks if the column contains an image url.
+
+```typescript
+function isImageUrlColumn(column: DataViewMetadataColumn): boolean;
+```
+
+### Example
+
+```typescript
+import DataViewMetadataColumn = powerbi.DataViewMetadataColumn;
+import converterHelper = powerbi.extensibility.utils.dataview.converterHelper;
+
+// This object is actually part of the dataView object.
+let metadata: DataViewMetadataColumn = {
+    displayName: "Microsoft",
+    type: {
+        misc: {
+            imageUrl: true
+        }
+    }
+};
+
+converterHelper.isImageUrlColumn(metadata);
+
+// returns: true
+```
+
+## isWebUrlColumn
+
+This function checks if the column contains a web url.
+
+```typescript
+function isWebUrlColumn(column: DataViewMetadataColumn): boolean;
+```
+
+### Example
+
+```typescript
+import DataViewMetadataColumn = powerbi.DataViewMetadataColumn;
+import converterHelper = powerbi.extensibility.utils.dataview.converterHelper;
+
+// This object is actually part of the dataView object.
+let metadata: DataViewMetadataColumn = {
+    displayName: "Microsoft",
+    type: {
+        misc: {
+            webUrl: true
+        }
+    }
+};
+
+converterHelper.isWebUrlColumn(metadata);
+
+// returns: true
+```
+
+## hasImageUrlColumn
+
+This function checks if the dataView has a column with image url.
+
+```typescript
+function hasImageUrlColumn(dataView: DataView): boolean;
+```
+
+### Example
+
+```typescript
+import DataView = powerbi.DataView;
+import converterHelper = powerbi.extensibility.utils.dataview.converterHelper;
+
+// This object is actually part of the dataView object.
+let dataView: DataView = {
+    metadata: {
+        columns: [
+            {
+                displayName: "Microsoft"
+            },
+            {
+                displayName: "Power BI",
+                type: {
+                    misc: {
+                        imageUrl: true
+                    }
+                }
+            }
+        ]
+    }
+};
+
+converterHelper.hasImageUrlColumn(dataView);
+
+// returns: true
+```

docs/api/data-role-helper.md

@@ -0,0 +1,190 @@
+# DataRoleHelper
+> The ```DataRoleHelper``` provides functions in order to check roles of the dataView object.
+
+The ```powerbi.extensibility.utils.dataview.DataRoleHelper``` module provides the following functions:
+
+* [getMeasureIndexOfRole](#getmeasureindexofrole)
+* [getCategoryIndexOfRole](#getcategoryindexofrole)
+* [hasRole](#hasrole)
+* [hasRoleInDataView](#hasroleindataview)
+* [hasRoleInValueColumn](#hasroleinvaluecolumn)
+
+## getMeasureIndexOfRole
+
+This function finds the measure by role name and returns an index of it.
+
+```typescript
+function getMeasureIndexOfRole(grouped: DataViewValueColumnGroup[], roleName: string): number;
+```
+
+### Example
+
+```typescript
+import DataViewValueColumnGroup = powerbi.DataViewValueColumnGroup;
+import DataRoleHelper = powerbi.extensibility.utils.dataview.DataRoleHelper;
+
+// This object is actually part of the dataView object.
+let columnGroup: DataViewValueColumnGroup[] = [{
+    values: [
+        {
+            source: {
+                displayName: "Microsoft",
+                roles: {
+                    "company": true
+                }
+            },
+            values: []
+        },
+        {
+            source: {
+                displayName: "Power BI",
+                roles: {
+                    "product": true
+                }
+            },
+            values: []
+        }
+    ]
+}];
+
+DataRoleHelper.getMeasureIndexOfRole(columnGroup, "product");
+
+// returns: 1
+```
+
+## getCategoryIndexOfRole
+
+This function finds the category by role name and returns an index of it.
+
+```typescript
+function getCategoryIndexOfRole(categories: DataViewCategoryColumn[], roleName: string): number;
+```
+
+### Example
+
+```typescript
+import DataViewCategoryColumn = powerbi.DataViewCategoryColumn;
+import DataRoleHelper = powerbi.extensibility.utils.dataview.DataRoleHelper;
+
+// This object is actually part of the dataView object.
+let categoryGroup: DataViewCategoryColumn[] = [
+    {
+        source: {
+            displayName: "Microsoft",
+            roles: {
+                "company": true
+            }
+        },
+        values: []
+    },
+    {
+        source: {
+            displayName: "Power BI",
+            roles: {
+                "product": true
+            }
+        },
+        values: []
+    }
+];
+
+DataRoleHelper.getCategoryIndexOfRole(categoryGroup, "product");
+
+// returns: 1
+```
+
+## hasRole
+
+This function checks if the provided role is defined in the metadata.
+
+```typescript
+function hasRole(column: DataViewMetadataColumn, name: string): boolean;
+```
+
+### Example
+
+```typescript
+import DataViewMetadataColumn = powerbi.DataViewMetadataColumn;
+import DataRoleHelper = powerbi.extensibility.utils.dataview.DataRoleHelper;
+
+// This object is actually part of the dataView object.
+let metadata: DataViewMetadataColumn = {
+    displayName: "Microsoft",
+    roles: {
+        "company": true
+    }
+};
+
+DataRoleHelper.hasRole(metadata, "company");
+
+// returns: true
+```
+
+## hasRoleInDataView
+
+This function checks if the provided role is defined in the dataView.
+
+```typescript
+function hasRoleInDataView(dataView: DataView, name: string): boolean;
+```
+
+### Example
+
+```typescript
+import DataView = powerbi.DataView;
+import DataRoleHelper = powerbi.extensibility.utils.dataview.DataRoleHelper;
+
+// This object is actually part of the dataView object.
+let dataView: DataView = {
+    metadata: {
+        columns: [
+            {
+                displayName: "Microsoft",
+                roles: {
+                    "company": true
+                }
+            },
+            {
+                displayName: "Power BI",
+                roles: {
+                    "product": true
+                }
+            }
+        ]
+    }
+};
+
+DataRoleHelper.hasRoleInDataView(dataView, "product");
+
+// returns: true
+```
+
+## hasRoleInValueColumn
+
+This function checks if the provided role is defined in the value column.
+
+```typescript
+function hasRoleInValueColumn(valueColumn: DataViewValueColumn, name: string): boolean;
+```
+
+### Example
+
+```typescript
+import DataViewValueColumn = powerbi.DataViewValueColumn;
+import DataRoleHelper = powerbi.extensibility.utils.dataview.DataRoleHelper;
+
+// This object is actually part of the dataView object.
+let valueColumn: DataViewValueColumn = {
+    source: {
+        displayName: "Microsoft",
+        roles: {
+            "company": true
+        }
+    },
+    values: []
+};
+
+DataRoleHelper.hasRoleInValueColumn(valueColumn, "company");
+
+// returns: true
+```

docs/api/data-view-object.md

@@ -0,0 +1,59 @@
+# DataRoleHelper
+> The ```DataViewObject``` provides functions in order to extract values of the object.
+
+The ```powerbi.extensibility.utils.dataview.DataViewObject``` module provides the following functions:
+
+* [getValue](#getvalue)
+* [getFillColorByPropertyName](#getfillcolorbypropertyname)
+
+## getValue
+
+This function returns a value of the object by property name.
+
+```typescript
+function getValue<T>(object: IDataViewObject, propertyName: string, defaultValue?: T): T;
+```
+
+### Example
+
+```typescript
+import DataViewObject = powerbi.extensibility.utils.dataview.DataViewObject;
+
+// This object is actually part of the dataView object.
+let object: powerbi.DataViewObject = {
+    "windows": 5,
+    "microsoft": "Power BI"
+};
+
+DataViewObject.getValue(object, "microsoft");
+
+// returns: Power BI
+```
+
+## getFillColorByPropertyName
+
+This function returns a solid color of the object by property name.
+
+```typescript
+function getFillColorByPropertyName(object: IDataViewObject, propertyName: string, defaultColor?: string): string;
+```
+
+### Example
+
+```typescript
+import DataViewObject = powerbi.extensibility.utils.dataview.DataViewObject;
+
+// This object is actually part of the dataView object.
+let object: powerbi.DataViewObject = {
+    "windows": 5,
+    "fillColor": {
+        "solid": {
+            "color": "green"
+        }
+    }
+};
+
+DataViewObject.getFillColorByPropertyName(object, "fillColor");
+
+// returns: green
+```

docs/api/data-view-objects-parser.md

@@ -0,0 +1,124 @@
+# DataViewObjectsParser
+> The ```DataViewObjectsParser``` provides the simplest way in order to parse properties of the formatting panel.
+
+The ```powerbi.extensibility.utils.dataview.DataViewObjectsParser``` class provides the following methods:
+
+* [getDefault](#getdefault)
+* [parse](#parse)
+* [enumerateObjectInstances](#enumerateobjectinstances)
+
+
+## getDefault
+
+This static method returns an instance of DataViewObjectsParser.
+
+```typescript
+static getDefault(): DataViewObjectsParser;
+```
+
+### Example
+
+```typescript
+import DataViewObjectsParser = powerbi.extensibility.utils.dataview.DataViewObjectsParser;
+
+DataViewObjectsParser.getDefault();
+
+// returns: an instance of the DataViewObjectsParser
+```
+
+## parse
+
+This method parses properies of the formatting panel and returns an instance of ```DataViewObjectsParser```.
+
+```typescript
+static parse<T extends DataViewObjectsParser>(dataView: DataView): T;
+```
+
+### Example
+
+```typescript
+import IVisual = powerbi.extensibility.IVisual;
+import DataViewObjectsParser = powerbi.extensibility.utils.dataview.DataViewObjectsParser;
+import VisualUpdateOptions = powerbi.extensibility.visual.VisualUpdateOptions;
+
+/**
+ * This class describes properties of the formatting panel.
+ * Name of the property and name of the property described in the capabilities should be the same.
+ */
+class DataPointProperties {
+    public fillColor: string = "red"; // This value is a default value of the property.
+}
+
+class PropertiesParser extends DataViewObjectsParser {
+    /**
+     * This property describes a group of properties.
+     */
+    public dataPoint: DataPointProperties = new DataPointProperties();
+}
+
+export class YourVisual extends IVisual {
+    // implementation of the IVisual.
+
+    private propertiesParser: PropertiesParser;
+
+    public update(options: VisualUpdateOptions): void {
+        // Parses properties.
+        this.propertiesParser = PropertiesParser.parse<PropertiesParser>(options.dataViews[0]);
+
+        // You can use the properties after parsing
+        console.log(this.propertiesParser.dataPoint.fillColor); // returns "red" as default value, it will be updated automatically after any change of the formatting panel.
+    }
+}
+```
+
+## enumerateObjectInstances
+
+This static method enumerates properties and returns an instance of [VisualObjectInstanceEnumeration](https://github.com/Microsoft/PowerBI-visuals-tools/blob/master/templates/visuals/.api/v1.2.0/PowerBI-visuals.d.ts#L1015).
+We recommend you execute this method in ```enumerateObjectInstances``` method of the visual.
+
+```typescript
+static enumerateObjectInstances(dataViewObjectParser: DataViewObjectsParser, options: EnumerateVisualObjectInstancesOptions): VisualObjectInstanceEnumeration;
+```
+
+### Example
+
+```typescript
+import IVisual = powerbi.extensibility.IVisual;
+import EnumerateVisualObjectInstancesOptions = powerbi.EnumerateVisualObjectInstancesOptions;
+import VisualObjectInstanceEnumeration = powerbi.VisualObjectInstanceEnumeration;
+import DataViewObjectsParser = powerbi.extensibility.utils.dataview.DataViewObjectsParser;
+import VisualUpdateOptions = powerbi.extensibility.visual.VisualUpdateOptions;
+
+/**
+ * This class describes properties of the formatting panel.
+ * Name of the property and name of the property described in the capabilities should be the same.
+ */
+class DataPointProperties {
+    public fillColor: string = "red";
+}
+
+class PropertiesParser extends DataViewObjectsParser {
+    /**
+     * This property describes a group of properties.
+     */
+    public dataPoint: DataPointProperties = new DataPointProperties();
+}
+
+export class YourVisual extends IVisual {
+    // implementation of the IVisual.
+
+    private propertiesParser: PropertiesParser;
+
+    public update(options: VisualUpdateOptions): void {
+        // Parses properties.
+        this.propertiesParser = PropertiesParser.parse<PropertiesParser>(options.dataViews[0]);
+    }
+
+    /**
+     * This method will be executed if the formatting panel is open.
+     */
+    public enumerateObjectInstances(options: EnumerateVisualObjectInstancesOptions): VisualObjectInstanceEnumeration {
+        return PropertiesParser.enumerateObjectInstances(this.propertiesParser, options);
+    }
+}
+```

docs/api/data-view-objects.md

@@ -0,0 +1,106 @@
+# DataViewObjects
+> The ```DataViewObjects``` provides functions in order to extract values of the objects.
+
+The ```powerbi.extensibility.utils.dataview.DataViewObjects``` module provides the following functions:
+
+* [getValue](#getvalue)
+* [getObject](#getobject)
+* [getFillColor](#getfillcolor)
+
+## getValue
+
+This function returns the value of the given object.
+
+```typescript
+function getValue<T>(objects: DataViewObjects, propertyId: DataViewObjectPropertyIdentifier, defaultValue?: T): T;
+```
+
+### Example
+
+```typescript
+import DataViewObjectPropertyIdentifier = powerbi.DataViewObjectPropertyIdentifier;
+import DataViewObjects = powerbi.extensibility.utils.dataview.DataViewObjects;
+
+let property: DataViewObjectPropertyIdentifier = {
+    objectName: "microsoft",
+    propertyName: "bi"
+};
+
+// This object is actually part of the dataView object.
+let objects: powerbi.DataViewObjects = {
+    "microsoft": {
+        "windows": 5,
+        "bi": "Power"
+    }
+};
+
+DataViewObjects.getValue(objects, property);
+
+// returns: Power
+```
+
+## getObject
+
+This function returns an object of the given object.
+
+```typescript
+function getObject(objects: DataViewObjects, objectName: string, defaultValue?: IDataViewObject): IDataViewObject;
+```
+
+### Example
+
+```typescript
+import DataViewObjects = powerbi.extensibility.utils.dataview.DataViewObjects;
+
+// This object is actually part of the dataView object.
+let objects: powerbi.DataViewObjects = {
+    "microsoft": {
+        "windows": 5,
+        "bi": "Power"
+    }
+};
+
+DataViewObjects.getObject(objects, "microsoft");
+
+/* returns: {
+    "bi": "Power",
+    "windows": 5
+    
+}*/
+```
+
+## getFillColor
+
+This function returns a solid color of the objects.
+
+```typescript
+function getFillColor(objects: DataViewObjects, propertyId: DataViewObjectPropertyIdentifier, defaultColor?: string): string;
+```
+
+### Example
+
+```typescript
+import DataViewObjectPropertyIdentifier = powerbi.DataViewObjectPropertyIdentifier;
+import DataViewObjects = powerbi.extensibility.utils.dataview.DataViewObjects;
+
+let property: DataViewObjectPropertyIdentifier = {
+    objectName: "power",
+    propertyName: "fillColor"
+};
+
+// This object is actually part of the dataView object.
+let objects: powerbi.DataViewObjects = {
+    "power": {
+        "fillColor": {
+            "solid": {
+                "color": "yellow"
+            }
+        },
+        "bi": "Power"
+    }
+};
+
+DataViewObjects.getFillColor(objects, property);
+
+// returns: yellow
+```

docs/dev/development-workflow.md

@@ -20,25 +20,33 @@ Firstly, you should clone a copy of the repository by using one of the following
 
 After that, you should change the current working directory to ```powerbi-visuals-utils-dataviewutils``` by using the following command:
 
-```cd powerbi-visuals-utils-dataviewutils```
+```bash
+cd powerbi-visuals-utils-dataviewutils
+```
 
 The final step is installation of dependencies by using the following command:
 
-```npm install```
+```bash
+npm install
+```
 
 The repository is ready for development now.
 
 ## How to build
 We use [TypeScript](https://github.com/Microsoft/TypeScript) as a language and a compiler for the repository. To build source code you should run the following command:
 
-```npm run build```
+```bash
+npm run build
+```
 
 This command compiles TypeScript code to JavaScript and provides declaration file for the Intellisense. The result of the compilation is available in the ```lib``` directory.
 
 ## How to lint the source code
 We use [TSLint](https://github.com/palantir/tslint) as a linter for TypeScript code. To check source code you should run the following command:
 
-```npm run lint```
+```bash
+npm run lint
+```
 
 This command checks style of TypeScript code and provides a list of problems. Please address all of problems reported by TSLint before sending a pull request to the [repository](https://github.com/Microsoft/powerbi-visuals-utils-dataviewutils).
 
@@ -46,11 +54,15 @@ This command checks style of TypeScript code and provides a list of problems. Pl
 We use [Jasmine](https://github.com/jasmine/jasmine) and [Karma](https://github.com/karma-runner/karma) to run unit tests. Please note, Karma requires Google Chrome to run unit tests.
 To run unit tests locally on your machine you should run the following command:
 
-```npm run test```
+```bash
+npm run test
+```
 
 ## How to debug unit tests locally
 To debug unit tests in Google Chrome browser you should run the following command:
 
-```npm run test -- --single-run=false```
+```bash
+npm run test -- --single-run=false
+```
 
 This command runs unit tests in the browser and watches tests files, in other words, you have an ability to run unit tests automatically after any changing.

docs/usage/installation-guide.md

@@ -14,7 +14,7 @@ To use the package you should have the following things:
 ## Installation
 To install the package you should run the following command in the directory with your current custom visual:
 
-```
+```bash
 npm install powerbi-visuals-utils-dataviewutils --save
 ```
 

docs/usage/usage-guide.md

@@ -1 +1,10 @@
-# This page is under development process :exclamation: :soon:
+# Usage Guide
+> The Usage Guide describes a public API of the package. You will find a description and a few examples for each public interface of the package.
+
+This package contains the following classes, interfaces and methods:
+
+* [DataRoleHelper](../api/data-role-helper.md) - helps to check roles of the dataView object
+* [DataViewObjects](../api/data-view-objects.md) - extracts values of the objects
+* [DataViewObject](../api/data-view-object.md) - extracts values of the object
+* [converterHelper](../api/converter-helper.md) - helps to check properties of the dataView
+* [DataViewObjectsParser](../api/data-view-objects-parser.md) - parses properties of the formating panel