@nebula.js/sn-funnel-chart - npm Package Compare versions

Comparing version 1.2.0 to 1.3.0

api-specifications/plugins.json

@@ -6,3 +6,3 @@ {
     "description": "Funnel chart plugins API definitions",
-    "version": "1.2.0",
+    "version": "1.3.0",
     "license": "MIT",
@@ -9,0 +9,0 @@ "stability": "experimental",

api-specifications/properties.json

@@ -6,3 +6,3 @@ {
     "description": "Funnel chart generic object definition",
-    "version": "1.2.0",
+    "version": "1.3.0",
     "license": "MIT",
@@ -9,0 +9,0 @@ "stability": "experimental",

package.json

 {
   "name": "@nebula.js/sn-funnel-chart",
-  "version": "1.2.0",
+  "version": "1.3.0",
   "description": "A sequential chart visualizing a linear process with connected stages, for example a sales process with potential revenue at each stage.",
@@ -5,0 +5,0 @@ "author": "QlikTech International AB",

README.md

@@ -7,5 +7,4 @@ # @nebula.js/sn-funnel-chart
 
-Requires `@nebula.js/stardust` version `1.2.0` or later. 
+Requires `@nebula.js/stardust` version `1.2.0` or later.
 
-
 ## Installing
@@ -180,1 +179,124 @@
 ```
+
+## Funnel chart plugins
+
+A plugin can be passed into a funnel chart to add or modify its capability
+or visual appearance.
+A plugin needs to be defined before it can be rendered together with the chart.
+
+```js
+// Step 1: define the plugin
+
+// Modifying the look of the dimension title
+const dimensionTitlePlugin = {
+  info: {
+    name: 'dimension-title-plugin',
+    type: 'component-definition',
+  },
+  fn: ({ keys, layout }) => {
+    const componentDefinition = {
+      type: 'text',
+
+      // Provide the same name as the exisiting component to override it
+      key: keys.COMPONENT.DIMENSION_TITLE,
+      text: 'The percentage of candidates remain after each hiring stage',
+      layout: {
+        dock: 'bottom',
+      },
+    };
+    return componentDefinition;
+  },
+};
+
+// Step 2: passing the plugin definition into the render function
+
+// Render a funnel chart with plugins
+nuked.render({
+  element: document.querySelector('#object'),
+  type: 'sn-funnel-chart',
+  plugins: [dimensionTitlePlugin],
+  fields: ['Hiring Stage', '=Sum(NumberOfCandidates)'],
+  properties: {
+    title: 'Recruitment Process',
+  },
+});
+```
+
+The plugin definition is an object, with two properties `info` and `fn`.
+The `fn` returns a `picasso.js` component. To build this component,
+some important chart internals are passed into the argument object of `fn`.
+
+```js
+// Structure of the argument object of fn
+const pluginArgs = {
+  layout,
+  keys: {
+    SCALE: { FILL },
+    COMPONENT: { FUNNEL, FUNNEL_LABELS, DIMENSION_TITLE },
+  },
+};
+```
+
+With plugins, you can either add new components or modify existing components
+of the funnel chart.
+
+### Modify existing components
+
+As an example, the positions and the appearance of the funnel labels
+can be modified by plugins.
+
+To overide an existing component, `fn` should returns a `picasso.js` component
+that has the same `key` as the existing component
+(`keys.COMPONENT.FUNNEL_LABELS` in
+this example)
+
+```js
+// Modifying the look of the funnel labels
+const funnelLabelsPlugin = {
+  info: {
+    name: 'funnel-labels-plugin',
+    type: 'component-definition',
+  },
+  fn: ({ keys, layout }) => {
+    const componentDefinition = {
+      type: 'labels',
+
+      // Provide the same name as the exisiting component to override it
+      key: keys.COMPONENT.FUNNEL_LABELS,
+      layout: { displayOrder: 2 },
+      settings: {
+        sources: [
+          {
+            component: keys.COMPONENT.FUNNEL,
+            selector: '.labelLeft',
+            strategy: {
+              type: 'rows',
+              settings: { align: 0, fill: 'gray', fontSize: '15px' },
+            },
+          },
+          {
+            component: keys.COMPONENT.FUNNEL,
+            selector: '.labelCenter',
+            strategy: {
+              type: 'rows',
+              settings: { align: 0.5, fill: 'darkred', fontSize: '15px' },
+            },
+          },
+        ],
+      },
+    };
+    return componentDefinition;
+  },
+};
+```
+
+### Add new components
+
+The new component can be a standard Picasso component
+or a custom Picasso component. The code for adding a new component is
+similar to that for modifying an existing component, the only difference
+is that the `key` should be different from that of
+any of the existing components.
+
+Images of these examples and more details
+can be found in the `examples` folder.

No alert changes

Improved metrics

Total package byte prevSize

1889847

increased by0.18%

Number of lines in readme file

301

increased by68.16%

No dependency changes