OpenFlashChart2之恶心文档

N久没有做界面相关的项目了，最近一个核心项目中正好有用到几个图形报表的界面，原本一直使用jfreechar，但是这种服务器生成图片，然后浏览器再请求图片，并显示，这种做法一是加大服务器压力，而是加大网络传输的带宽，降低了用户体验，比较好的方式是服务器提供元数据，客户端根据元数据生成对应的图形报表。显然，后一种模式既能有效利用客户机的资源，也减少了带宽，降低了服务器压力。提高了用户体验，唯一的不足是需要客户端安装一些插件，比如使用OpenFlashChart时需要用户按照flashplayer，不过还好，flashplayer在普通的pc机上的按照率高达95%，所以使用Flash在客户端动态生成图形报表是一个非常不错的选择。

于是去下载了OpenFlashChart，现在的最新版本是2.0，原来的1.x版本原作者将不会再维护了。从ahuaxuan短短的几小时接触中发现2.0版本更容易使用，也更容易理解。

在我看来开发任何报表无非是将自己的业务数据组装成报表需要的格式，然后调用对应的API，所以要熟悉一个报表的使用，只需要掌握常用的API和报表的数据结构就完全可以了。

下面我们分两部分来介绍，先介绍OpenFlashChart2.0所需要的常用数据结构。在OpenFlashChart2.0的包中提供了一系列的例子，根据这些例子可以将OpenFlashChart2.0所需要的常用数据结构总结如下(下面这个图是俺用powerdesigner反向工程出来的)：


从这个域模型可以看出OpenFlashChart2所使用的大体的数据结构。

Xaxis表示横坐标族上的属性
Yaxis表示纵坐标族上的熟悉
Title表示图形的一些描述信息
Element表示图形中的数据
Attribute表示数据项的特点

但是很遗憾的是，OpenFlashChart的例子中有多处错误，导致代码不能正常运行，比如说在Attribute中，有很多例子中数据值用value属性，但是很遗憾，2.0中没有这个属性，应该使用的是top属性。再比如在Xaxis中的labels属性，例子中是

"x_axis":{
    "stroke":1,
    "tick_height":10,
    "colour":"#d000d0",
    "grid_colour":"#00ff00",
    "labels": ["January","February","March","April","May","June","July","August","Spetember"]
   },

但是这个是不正确的，因为labels应该这样写：

  "labels": {
   "labels": ["January","February","March","April","May","June","July","August","Spetember"]
}

由于这些不正确的文档描述，会延误使用者很多时间。

那么我们再来看看API的问题。
OpenFlashChart2的例子之一：

<script type="text/javascript">

swfobject.embedSWF(
"open-flash-chart.swf", "my_chart",
"550", "200", "9.0.0", "expressInstall.swf",
{"data-file":"gallery/bar-chart.php"} );

</script>

但是很多情况下，我们打开报表页面并不需要再次请求服务器以得到数据，而是在打开页面的时候就把数据带到页面上来，这个时候，"data-file":"gallery/bar-chart.php"的用法就不正确的了。经查，文档上有data-get这个属性，比如打开页面，我要把一个服务器传过来的数据交给swf处理，那我可以这样写：

<script type="text/javascript">

swfobject.embedSWF(
"open-flash-chart.swf", "my_chart",
"550", "200", "9.0.0", "expressInstall.swf",
{"data-get":"getData"} );

Function getData() {return xx}
</script>

但是很遗憾，虽然文档上告诉我们需要这样做，但是实际上这样做是行不通的，我们必须这样做：

swfobject.embedSWF("${request.contextPath}/media/open-flash-chart.swf", 
		"my_chart", "900", "300", "9.0.0");

        function open_flash_chart_data(){
           // return JSON.stringify(dd);
		   return dd;
        }

看上去，获取数据的方法名是有默认名字的，这些细节在OpenFlashChart上都没有得到体现。
就在这一个图形的报表的问题上文档上已经出现了多处错误，我不得不说对它的文档我真的感到很头疼

虽然用了半天的时间终于达到了ahuaxuan需要的效果：


再看看这张报表呢：


但是事实上这个过程完全可以缩短，缩短的一个重要因素就是OpenFlashChart2需要一份比较好的文档。开源的个人项目确实是不容易的，需要消耗作者大量的业余时间，但是一份好的开源项目不只是该组件的功能强大或者免费，它也需要一份好的文档，可以让使用者迅速上手。

在这一点上，django的文档是我见过的非常好的开源项目文档，目录层次清晰，索引明确，大大降低了使用django开发软件的门槛，学习django的人也可以快速上手。
好的文档对于开源软件来说太重要了，以后在做选型的时候，文档的正确和完善程度应该是我的一种重要衡量标准。

评论

10 楼 kmy_白衣 2015-04-02  

生成的area图有时候 标签的数值和图标上看上去的数值不一致。不知道为什么会出现这种情况

9 楼 zst861205 2012-04-16  

不知道有没有试过在一个页面出两个图呢，，

8 楼 peterchao_asch 2012-02-01  

不知博主还关注ofc不？小弟有一事不明：
        function open_flash_chart_data(){ 
           return JSON.stringify(dd);  
        } 
我发现很多网上的文章都用这种形式，dd是后台传递的json类型字符串，我很矛盾，因为
JSON.stringify这个方法应该是将一个对象序列化为json格式的字符串，而dd已经是json字符串了，为什么还要stringify呢？
还有，我很认同您的观点，这个开源项目文档真的有失水准，不过ofc2这种绘图的方式还是值得推崇的！
最后感谢博主。

7 楼 ahuaxuan 2009-05-11  

chaoqun2003 写道

知道如何设置Y轴Label的颜色吗？搞了好久没弄明白...

我没有仔细看，不过未必有这个功能

6 楼 ahuaxuan 2009-05-11  

我是通过不停的尝试才找到的，　它们有的能跑，有的不能跑，需要仔细观察

5 楼 tanzek 2009-05-09  

我想请问你的这些错误是如何找到的呢？
我也遇到了类似的错误，使用网站所提供的数据示例，都没有办法成功显示图表。
想请教一下。

4 楼 chaoqun2003 2009-04-23  

知道如何设置Y轴Label的颜色吗？
搞了好久没弄明白...

3 楼 ahuaxuan 2009-04-06  

青鸟折翼 写道

用open_flash_chart_data()传递数据，第一次加载页面时可以显示，但是刷新之后数据就传递不了，请教楼主这是怎么回事

我这里没有这种情况，我修改数据库之后，刷新页面，图就变了，你的问题可能是缓存等原因造成的，看看你的数据有没有被缓存住了

2 楼 青鸟折翼 2009-04-03  

用open_flash_chart_data()传递数据，第一次加载页面时可以显示，但是刷新之后数据就传递不了，请教楼主这是怎么回事

1 楼 duker 2009-03-29  

顶你, hibernate 的成功一样是因为有质量很高的文档这个因素..
但开源软件的作者也要赚钱,有些可能是考虑靠咨询和服务收费,这种情况下,文档
不好是可以理解的..