Merge pull request #87 from setaman/dev

Dev

Author: setaman

README.md

@@ -69,6 +69,7 @@ After you have initialized the component, use it everywhere you want in your app
   lineMode="in 10"
   :legend="true"
   :legendValue="180"
+  :legendFormatter="({currentValue}) => new Intl.NumberFormat('de-DE').format(currentValue)"
   legendClass="legend-custom-style"
   dash="60 0.9"
   animation="reverse 700 400"
@@ -111,6 +112,7 @@ This table below provides a quick overview over all available options. To gain m
 | **[`emptyColorFill`](#emptycolorfill)** | String \| Object | same as `color` |  "transparent" |
 | **[`legend`](#legend)** | Boolean | |  true |
 | **[`legendValue`](#legendvalue)** | Number \| String | any number, accepts a `.` or `","` as decimals delimiter |   |
+| **[`legendFormatter`](#legendformatter)** [![npm](https://img.shields.io/badge/v1.3.0-blue?style=flat-square)](#legendformatter) | Function | Function that returns formatted value  |   |
 | **[`animation`](#animation)** | String | "default \| rs \| loop \| reverse \| bounce [duration delay]" | "default 1000 400"|
 | **[`loading`](#loading)** | Boolean |  |false|
 | **[`determinate`](#determinate)** | Boolean |  |false|
@@ -150,7 +152,9 @@ this.myProgress = 55.5;
 this.myProgress = this.tasksDone * 100 / maxTasks; // the percentage of done tasks
 ```
 
->:heavy_exclamation_mark: The `progress` is always used to fill the progress circle line. So you cannot customize this value, it should be always in the range [-100, 100] and not valid Numbers lead to **[`noData`](#noData)** state. For customization purpose please use **[`legendValue`](#legendvalue)**. 
+>:heavy_exclamation_mark: The `progress` is always used to fill the progress circle line. So you cannot customize this 
+>value, it should be always in the range [-100, 100] and not valid Numbers lead to **[`noData`](#noData)** state. 
+>For customization purpose please use **[`legendValue`](#legendvalue)** and take a look at **[`legendFormatter`](#legendformatter)**. 
 
 >If **[`legendValue`](#legendvalue)** is defined the progress will **NOT** be displayed as circle legend.
 
@@ -308,29 +312,75 @@ Is a Boolean. It defines whether the **[`progress`](#progress)** or from you def
 
 ###### Animated: :heavy_check_mark:
 
-Is any number. Use this property if you want to customize the shown progress as the legend of the circle. If defined, `legendValue` will replace **[`progress`](#progress)** as the circle legend!
-
-[![npm](https://img.shields.io/badge/v1.1.1-blue?style=flat-square)](#legendvalue) You can set any precision of the decimal numbers. If the prop is defined as a string, you can specify the `","` as decimals separator (e.g "123,123" for german numbers).
+Is any Number or String. Use this property if you want to show progress value as the legend of the circle that is not in
+the range [-100, 100]. If defined, `legendValue` will replace [`progress`](#progress) as the circle legend!
+You can set any precision of the decimal numbers. If the prop is defined as a string, you can specify the `","` 
+as decimals delimiter (e.g "123,123" for german numbers), apart from this the value must generally be a valid JavaScript Number.
+For more customization possibilities please use [`legendFormatter`](#legendformatter) or [`scoped slot`](#default). 
 
 ###### Example: :scroll:
 
-Let's say you need to display a rating from 0 to 5 of a product with 3.5 stars. Since **[`progress`](#progress)** can take values only from 0 to 100 your need an additional property `legendValue`. You can show the product rating like in the following example:
+Let's say you need to display a rating from 0 to 5 of a product with 3.5 stars. Setting the [`progress`](#progress) to 3.5 will 
+fill the circle to 3.5 percent, and this is not what we need, since we want to display the percentage of 5 as progress. 
+At this point we need an additional property `legendValue`. We can show the product rating like in the following example:
 
 ```js
-<vue-ellipse-progress progress="progress" :legend-value="rating" />
+<vue-ellipse-progress :progress="progress" :legend-value="rating" />
 ...
 this.rating = 3.5;
 this.progress = this.rating * 100 / 5; // the rating percentage
 ```
 Now you can display custom progress value that still animated and circle progress fills properly!
 
-```vuejs
-legend-value="345,12345" // set "," as delimiter defining the value as string
+```vue
+<vue-ellipse-progress legend-value="345,12345" /> // set "," as delimiter defining the value as string
 ```
 
 >:heavy_exclamation_mark: note that `legendValue` replaces **[`progress`](#progress)** as circle legend but not vice versa.
 
 
+<br>
+
+- ### `legendFormatter` 
+
+[![npm](https://img.shields.io/badge/v1.3.0-blue?style=flat-square)](#legendformatter)
+
+Is a Function that must return your custom formatted value. The function takes counter properties object as argument and 
+is called on every tick of the counter. Here the formatting of [legendValue](#legendvalue) or [progress](#progress) 
+is completely up to you and you have full freedom to adjust the presentation to your needs. The function can return any 
+value, even HTML.   
+
+>:grey_exclamation: alternatively you can use **[`scoped slot`](#default)** for custom formatting.
+
+###### Example: :scroll:
+
+Let's see how it works. The function takes counter properties object as argument that you can use to define custom formatting.
+`currentValue` is the most relevant value, as it is the actual value at specific counter tick. The return value will be 
+displayed as the legend of the circle.
+
+```js
+const myFormatter = ({ currentValue, currentRawValue, duration, previousCountStepValue, start, end, difference, oneStepDifference, startTime, elapsed }) => {
+  return new Intl.NumberFormat("de-DE", { style: "currency", currency: "EUR" }).format(currentValue); 
+}
+```
+You can also return HTML:
+```js
+const myFormatter = ({ currentValue }) => {
+     return `
+        <span style="font-weight: bold; font-size: 1.6rem">${new Intl.NumberFormat("de-DE").format(currentValue)}</span>
+        <span>€</span>
+      `;
+    }
+```
+
+Finally, set your formatter as prop:
+
+```vue
+<vue-ellipse-progress :legend-formatter="myFormatter"/>
+<!-- shorter version if you wish-->
+<vue-ellipse-progress :legend-formatter="({ currentValue }) => `My Format ${currentValue}`"/>
+````
+
 <br>
 
 - ### `animation`
@@ -517,6 +567,23 @@ data: [
 
 ### Slot options
 
+- #### `default`
+
+Use this slot, if you want to customize the presentation of the circle legend and make a use of the animated counter, 
+so your formatting still animated. This works similar to the [`legendFormatter`](#legendformatter) and is just 
+an alternative way to provide a custom format. You can access animated counter properties through the scoped slot 
+props and adjust the presentation of the legend to your needs. 
+
+```vue
+<vue-ellipse-progress :progress="50">
+  <template v-slot:default="{ counterTick }">
+    <span style="font-weight: bold; font-size: 1.6rem; color: green;">
+      {{ myFormatter(counterTick.currentValue) }}
+    </span>
+  </template>
+</vue-ellipse-progress>
+```
+
 - #### `legend-value`
 
 In this slot you can put an additional element that you want to display beside the progress
@@ -530,8 +597,12 @@ This code ...
 ```html
 <vue-ellipse-progress ....>
 
-    <span slot="legend-value">/200</span>
-    <p slot="legend-caption">TASKS DONE</p>
+<template v-slot:legend-value>
+  <span slot="legend-value">/200</span>
+</template>
+<template v-slot:legend-caption>
+  <p slot="legend-caption">TASKS DONE</p>
+</template>
 
 </vue-ellipse-progress>
 ```