xp-framework/rfc — Issue #54: Custom labels in Chart API
Author: thekid
Created: 2011-10-17 15:46:17+00:00
State: open
Labels: draft, framework

Scope of Change
====
The Chart class will be added a way to define custom labels for each value.

Rationale
====
Until now there is no possibility to label the parts of a graph with custom
values. One can only choose to print the values itself.
It would be nice to be able to print something else, e.g.
24.950000 should be printed as 24:57 hours.
Being able to add custom Labels for each value and choose to print out these
instead of the values itself would solve that problem.

Functionality
====
adding custom labels works like that:

```php
add(new Series('Pie', $values, $vlabels));
$chart->setDisplayValues(TRUE);
$chart->setDisplayCustomValues(TRUE);
?>
```

Existing code should not be affected, because the parameter $vlabels is
optional and default is _not_ to display custom values.

the ImageRenderer Class does the following in the renderPieChart method
to print out the label for each value if requested:

```php
series[0]->values[$i]);
?>
```

Better would be

```php
displayValueOf(0, $i)
?>
```

which does following:

```php
dispcustomvalues
? $this->series[$j]->labels[$i]
: $this->series[$j]->values[$i]
);
?>
```

$labels is an array as a property of the Series class.

It's better to retrieve values from the Chart class via method calls
rather then directly accessing it, and the suggested implementation
should return exactly the same, as the previous direct access.

Security considerations
====
n/a

Speed impact
====
Slightly slower

Dependencies
====
n/a

Related documents
====
- http://sperber.info/xp/img.chart.diff
Patch implementing this RFC

- http://xp-framework.net/downloads/rfc0054.diff
Revised patch implementing custom labels for all chart types.