cfchart: carta dan graf dalam CFML

cfchart ialah tag CFML yang menjana carta dan graf di sisi pelayan. Dalam Lucee 7 tag ini tidak tersedia secara teras: ia memerlukan sambungan Chart (Chart Extension for Jakarta EE), dan tanpa sambungan itu Lucee membalas undefined tag [cfchart]. Langkah pertama yang wajib ialah memasang sambungan itu. Artikel ini menunjukkan cara memasangnya, membina carta daripada data statik dan daripada query, menyimpan carta ke fail, dan penilaian jujur tentang bila cfchart sesuai dan bila ia tidak.

Pasang sambungan Chart dahulu

Dalam Lucee 7, tag cfchart, cfchartseries dan cfchartdata hidup dalam sambungan berasingan bernama Chart Extension for Jakarta EE. Sambungan ini berasaskan JFreeChart dan tidak dibundel bersama enjin teras. Tanpanya, sebarang halaman yang mengandungi cfchart gagal dikompil dengan ralat undefined tag [cfchart], dan ralat ini yang anda akan lihat jika cuba menjalankan contoh di bawah sebelum pemasangan.

Cara paling mudah ialah melalui pentadbir Lucee: buka halaman pentadbir, pergi ke bahagian Extensions, cari "Chart", kemudian pasang. Sebagai alternatif, sambungan itu boleh dimuat turun sebagai fail .lex daripada repositori Maven dan diletakkan dalam folder deploy pelayan Lucee, atau dipasang melalui pengurus sambungan baris arahan. Selepas pemasangan, mulakan semula Lucee dan sahkan tag itu sudah dikenali.

Carta pertama dengan cfchartdata

Bentuk paling asas cfchart ialah carta bar dengan data statik yang ditulis secara langsung menggunakan cfchartdata. Setiap titik data ialah satu pasangan item dan value. Atribut chartwidth dan chartheight menetapkan saiz dalam piksel, title memberi tajuk, dan format memilih format imej keluaran sama ada png atau jpg.

<cfchart format="png" chartwidth="480" chartheight="280" showlegend="yes" title="Jualan Bulanan">
    <cfchartseries type="bar">
        <cfchartdata item="Jan" value="120">
        <cfchartdata item="Feb" value="150">
        <cfchartdata item="Mac" value="90">
    </cfchartseries>
</cfchart>

Apabila dijalankan, cfchart secara lalai menulis tag <img> bersama peta imej ke dalam respons, dan imej sebenar dihidangkan melalui URL dalaman Lucee. Ini bermakna carta muncul terus dalam halaman tanpa anda perlu menguruskan fail imej sendiri. showlegend hanya berkesan apabila carta mengandungi lebih daripada satu siri, dan setiap siri boleh diberi label melalui atribut serieslabel.

Membina carta daripada query

Dalam aplikasi sebenar, data carta jarang ditulis tangan. cfchartseries menerima atribut query, itemcolumn dan valuecolumn untuk membina carta terus daripada hasil cfquery. Contoh di bawah membaca jadual produk daripada datasource kedai dan memplot harga setiap produk sebagai carta bar.

<cfquery name="qProduk" datasource="kedai">
    SELECT nama, harga FROM produk ORDER BY harga DESC
</cfquery>
<cfchart format="png" chartwidth="480" chartheight="280" showlegend="yes" title="Harga Produk">
    <cfchartseries type="bar" query="qProduk" itemcolumn="nama" valuecolumn="harga">
</cfchart>

itemcolumn menamakan lajur yang menjadi label paksi X, manakala valuecolumn menamakan lajur nilai berangka. Ini corak yang sama seperti mana-mana gelung paparan data lain, jadi anda boleh menukar carta dengan hanya menukar SQL tanpa menyentuh logik carta. Kalau anda mahu carta berubah mengikut tarikh atau penapis, ubah sahaja WHERE dalam query.

Atribut utama cfchart

Atribut yang paling kerap digunakan ialah format, chartwidth, chartheight, showlegend, tipstyle dan url.

• format memilih format keluaran. Nilai png dan jpg kedua-duanya disokong. png lebih sesuai untuk garis dan teks tajam, manakala jpg menghasilkan fail lebih kecil untuk carta berfoto tetapi boleh mengaburkan garisan.
• chartwidth dan chartheight menetapkan dimensi dalam piksel. Tiada saiz lalai yang berguna untuk semua konteks, jadi sentiasa tetapkan kedua-duanya.
• showlegend memaparkan legenda apabila terdapat lebih daripada satu siri. Nilai yes atau no.
• tipstyle pada asalnya mengawal tooltip dalam carta Flash, tetapi Flash tidak lagi disokong. Dalam sambungan Chart Lucee atribut ini ditanda sebagai tidak dilaksanakan, jadi ia tidak memberi kesan. Jangan harapkan tooltip interaktif daripadanya.
• url menjadikan setiap elemen carta boleh diklik untuk drill-down. Lucee menambah parameter series, category dan value secara automatik pada pautan sasaran.

Jadual jenis carta

Atribut type pada cfchartseries menentukan bentuk carta. Sambungan Chart Lucee menyokong jenis ini, semuanya disahkan dalam Lucee 7.1:

Jenis curve dan step juga tersedia dalam Lucee, tetapi pyramid, cylinder dan cone yang wujud dalam Adobe ColdFusion tidak ada. Cuba gunakan pyramid dalam Lucee akan membalas ralat type pyramid is not supported, jadi jangan salin contoh Adobe yang memakai jenis ini secara terus.

Simpan carta ke fail atau hantar terus

Terdapat dua cara untuk menggunakan hasil cfchart. Cara lalai ialah membiarkannya menulis tag <img> ke dalam halaman. Cara kedua ialah menangkap data imej ke dalam pemboleh ubah menggunakan atribut name, yang menyekat paparan dan memberikan anda data binari untuk diproses sendiri.

<cfchart format="png" name="cartaKedai" chartwidth="480" chartheight="280" title="Harga Produk">
    <cfchartseries type="pie">
        <cfchartdata item="Kopi" value="12.50">
        <cfchartdata item="Teh" value="8.00">
        <cfchartdata item="Roti" value="5.50">
    </cfchartseries>
</cfchart>
<cffile action="write" file="/tmp/carta-kedai.png" output="#cartaKedai#">
<cfset infoCarta = getFileInfo("/tmp/carta-kedai.png")>
<cfoutput>disimpan=#fileExists("/tmp/carta-kedai.png")#; saiz=#infoCarta.size# bait</cfoutput>

Atribut name menjadikan cfchart memulangkan binari imej dan bukannya menulis tag <img>. Anda kemudian menulisnya ke fail dengan cffile action="write", dan contoh di atas membuktikan fail itu wujud serta memaparkan saiznya dalam bait. Ini cara yang betul untuk menjana carta dalam kerja kelompok, contohnya carta harian yang disimpan ke folder laporan.

Untuk menghantar imej terus kepada pelayar sebagai binari, guna cfcontent dengan atribut variable:

cfchart(format = "png", name = "carta", chartwidth = 480, chartheight = 280, title = "Carta Terus") {
    cfchartseries(type = "bar") {
        cfchartdata(item = "Jan", value = 120);
        cfchartdata(item = "Feb", value = 150);
        cfchartdata(item = "Mac", value = 90);
    }
}
cfcontent(type = "image/png", variable = carta);

Blok ini berguna apabila carta perlu dihidangkan sebagai fail imej sebenar, contohnya melalui titik akhir yang memulangkan PNG terus dan bukannya halaman HTML. Format skrip cfchart menyokong sintaks sama seperti bentuk tag, dan kedua-duanya boleh dicampur dalam satu projek.

cfchart untuk laporan pelayan dan PDF

Kekuatan sebenar cfchart ialah penjanaan imej di sisi pelayan tanpa bergantung kepada JavaScript di pelayar. Ia sesuai untuk laporan yang dihantar sebagai imej statik, e-mel dengan carta tertanam, dan dokumen PDF. Carta yang dijana cfchart boleh ditulis ke fail kemudian dirujuk dalam cfdocument, jadi laporan PDF anda boleh mengandungi carta yang terhasil daripada query yang sama yang menjana jadual laporan. Rujuk menggabungkan teks dan PDF dengan cfpdf untuk aliran penuh penjanaan PDF, dan imej dalam CFML untuk memanipulasi carta selepas ia dijana.

Namun, untuk papan pemuka web moden, cfchart bukan pilihan yang baik. Ia menjana imej statik yang tidak interaktif, setiap permintaan menjana imej baharu di pelayan, dan kualitinya bergantung pada JFreeChart yang terhad berbanding pustaka JavaScript. Chart.js dan ApexCharts lebih baik untuk papan pemuka kerana ia interaktif, lebih ringan, dan dirender pada klien tanpa pusingan ke pelayan. Baca caching untuk prestasi kalau anda tetap mahu cfchart tetapi perlu mengurangkan beban penjanaan berulang, dan Excel dengan cfspreadsheet kalau keperluan sebenar ialah eksport data berjadual dan bukan visualisasi.

Soalan Lazim

Adakah cfchart tersedia secara teras dalam Lucee 7?

Tidak. Tag cfchart, cfchartseries dan cfchartdata hidup dalam sambungan Chart Extension for Jakarta EE dan bukan dalam enjin teras Lucee 7. Tanpa sambungan itu, Lucee membalas undefined tag [cfchart].

Format imej apa yang disokong oleh cfchart dalam Lucee?

png dan jpg. PNG lebih tajam untuk garisan dan teks, manakala JPG menghasilkan fail lebih kecil tetapi boleh mengaburkan garisan halus.

Bagaimana hendak menyimpan carta ke fail dan bukannya memaparkannya?

Guna atribut name pada cfchart untuk menangkap data binari, kemudian tulis dengan cffile action="write" atau hantar dengan cfcontent type="image/png".

Jenis carta apa yang disokong dalam Lucee?

Bar, line, pie, area, scatter, curve dan step. Jenis pyramid, cylinder dan cone daripada Adobe ColdFusion tidak disokong dan akan membalas type pyramid is not supported.

Bilakah cfchart patut digunakan berbanding Chart.js atau ApexCharts?

Gunakan cfchart untuk laporan pelayan, e-mel dan PDF yang memerlukan imej statik. Untuk papan pemuka web interaktif, Chart.js atau ApexCharts lebih baik kerana ia interaktif, lebih ringan dan dirender pada klien.

Sumber

• Dokumentasi cfchart di docs.lucee.org
• Repositori Lucee Chart Extension di GitHub
• Chart Extension di Maven Central
• Chart.js
• ApexCharts