Zen レポートでのコールバック・グラフの使用法

Zen レポートのコールバック・グラフでは、Zen レポート内に Zen グラフの機能を再現します。また、Zen レポートのコールバック・グラフでは、Zen で使用可能なすべてのグラフ・タイプと大部分のグラフ・プロパティがサポートされます。Zen グラフの詳細は、このドキュメント Zen コンポーネントの使用法の “Zen のグラフ” の章を参照してください。特に、“グラフのタイプ” のセクションでは、Zen および Zen レポートでサポートされるすべてのグラフ・タイプが説明されています。XPath グラフという名前の、前述のグラフ実装のドキュメントは、このドキュメントの “Zen レポートでの XPath グラフの使用法” のセクションで利用できます。

項目は以下のとおりです。

Zen レポートのグラフ・プロパティ

Zen ページと Zen レポートで別々に処理されるプロパティは少数しかありません。通常、Zen レポートはインタラクティブではないため、コールバック・グラフでは、Zen アプリケーションのインタラクティブな性質を利用する Zen グラフ・プロパティをサポートしていません。

以下のテーブルには、Zen レポートに対して一意であるか、またはその Zen ページに相当するものとは別に動作するプロパティがリストされています。

属性	説明
bandLeft	10 進数値。定義すると、グラフには、この値よりも低い範囲のプロット領域に色付きの縦帯が表示されます。bandLeftStyle は、この帯のスタイルを定義します。bandLeft および bandRight は、<xyChart> など、値軸に x 軸を指定するグラフに対してのみ適用されます。
bandLeftStyle	bandLeft で定義した帯に適用する SVG CSS スタイル定義。
bandRight	10 進数値。定義すると、グラフには、この値よりも高い範囲のプロット領域に色付きの縦帯が表示されます。bandRightStyle は、この帯のスタイルを定義します。bandLeft および bandRight は、<xyChart> など、値軸に x 軸を指定するグラフに対してのみ適用されます。
bandRightStyle	bandRight で定義した帯に適用する SVG CSS スタイル定義。
ongetData	Zen レポート・コールバック・グラフのデータ指定用コールバック・メソッドを指定します。Zen ページでも ongetData をサポートしていますが、指定するメソッドが Zen レポートとは異なります。このテーブルの後の “Zen レポートのグラフの値の指定” を参照してください。
ongetLabelX	x 軸のラベル指定用コールバック・メソッドを指定します。Zen ページでも ongetLabelX をサポートしていますが、指定するメソッドが Zen レポートとは異なります。このテーブルの後の “Zen レポート・コールバック・メソッド” を参照してください。
ongetLabelY	y 軸のラベル指定用コールバック・メソッドを指定します。Zen ページでも ongetLabelY をサポートしていますが、指定するメソッドが Zen レポートとは異なります。このテーブルの後の “Zen レポート・コールバック・メソッド” を参照してください。
ongetSeriesName	データ系列の名前を取得するためにグラフが呼び出すコールバック・メソッドを指定します。このグラフでは、系列の順序数 (先頭番号は 0) が設定された引数をメソッドに渡します。このテーブルの後の “Zen レポート・コールバック・メソッド” を参照してください。
passChartObject	グラフでグラフ・オブジェクトを ongetData コールバック・メソッドに渡すかどうかを制御します。グラフ・オブジェクトを渡さない初期バージョン用に記述されたコードとの下位互換性を与えるためにのみ使用する必要があります。この属性で基本となるデータ型は %ZEN.Datatype.booleanOpens in a new tab です。 “Zen レポート属性のデータ型” を参照してください。
seriesCount	Zen ページ内で、グラフのデータをデータ・コントローラから取得しない場合は、seriesCount プロパティに値を指定する必要があります。Zen レポートでは、データ・コントローラを使用しないほか、seriesCount の処理が異なります。このパラメータを指定しない場合は、コールバック・メソッド ongetData によって指定されたデータから計算されます。値を指定する場合は、グラフによってその値が使用され、グラフ内で使用可能なデータの量が割り出されます。
seriesSize	Zen ページ内で、グラフのデータをデータ・コントローラから取得しない場合は、seriesSize プロパティに値を指定する必要があります。Zen レポートでは、データ・コントローラを使用しないほか、seriesSize の処理が異なります。このパラメータを指定しない場合は、コールバック・メソッド ongetData によって指定されたデータから計算されます。値を指定する場合は、グラフによってその値が使用され、グラフ内で使用可能なデータの量が割り出されます。

Zen レポート・グラフのコールバック・メソッド

Zen レポート・グラフには、グラフへの情報提供に使用されるコールバック・メソッドを指定する属性がいくつかあります。ongetData、ongetLabelX、および ongetLabelY は Zen ページでもサポートされていますが、ongetSeriesName は Zen レポート独自のものです。Zen ページの ongetLabelX および ongetLabelY の詳細は、“プロット領域” を参照してください。“Zen レポートのグラフの値の指定” では、ongetData の詳細を説明しています。

Zen ページのコールバック・メソッドは JavaScript で記述され、クライアントにて実行されます。Zen レポートのコールバック・メソッドは、ObjectScript または他の適切な言語で記述され、サーバ上で実行されます。また、それらのメソッドはすべて、グラフ・オブジェクトを 2 つ目のパラメータとして受け入れます。これにより、コールバック・メソッドでグラフの情報を使用することが可能になります。passChartObject="false" の設定により、グラフ・オブジェクトを渡さない初期バージョン用に記述されたコードとの下位互換性を与えることができます。

以下のコードの例は、コールバック・メソッドのすべてを示しています。ongetLabelX および ongetLabelY のメソッドでは、グラフ・オブジェクトを使うことにより、グラフがピボット処理されているかどうか判断して、適正な軸にラベルを付けます。

/// This XML defines the logical contents of this report.
XData ReportDefinition [ XMLNamespace = "http://www.intersystems.com/zen/report/definition" ]
{
<report xmlns="http://www.intersystems.com/zen/report/definition"
 name="test" runonce="true">
</report>
}

/// This XML defines the display for this report. 
/// This is used to generate the XSLT stylesheets for both HTML and XSL-FO. 
XData ReportDisplay [ XMLNamespace = "http://www.intersystems.com/zen/report/display" ]
{
<report xmlns="http://www.intersystems.com/zen/report/display" 
 name="test"> 
 <document width="8.5in" height="11in" 
  marginLeft="1.25in" marginRight="1.25in" 
  marginTop="1.0in" marginBottom="1.0in" 
  headerHeight="1in" > 
  </document> 

<body> 
<cpercentbarChart 
    id="chart1b" 
    appearance="2D" 
    chartPivot="false" 
    ongetSeriesName ="getSeriesName" 
    valueLabelsVisible="true" 
    ongetLabelX="getSeriesNameX"
    ongetLabelY="getSeriesNameY"
    width="500" height="400" 
    seriesCount="4" seriesSize="3" 
    ongetData="getChartData" > 
    <yAxis majorGridLines="true"></yAxis> 
    </cpercentbarChart> 
</body> 
</report>
}

/// Get chart data 
Method getChartData(ByRef data, chartObject)
{
    for i=1:1:3 Set data(1-1,i-1) = $LI($LB( 34, 18, 27),i) 
    for i=1:1:3 Set data(2-1,i-1) = $LI($LB( 43, 14, 24),i) 
    for i=1:1:3 Set data(3-1,i-1) = $LI($LB( 43, 16, 27),i) 
    for i=1:1:3 Set data(4-1,i-1) = $LI($LB( 45, 13, 34),i)
}

/// Get X axis label name 
Method getSeriesNameX(value, chartObject)
{
    if chartObject.chartPivot {
        quit value 
    }
    else { 
        quit $LI($LB(1991,1992,1993,1994),value+1) 
    }
}

/// Get Y axis label name 
Method getSeriesNameY(value, yAxisNo, chartObject)
{
    if chartObject.chartPivot {
        quit $LI($LB(1991,1992,1993,1994),value+1) 
    }
    else { 
        quit value 
    }
}

/// Get series name 
Method getSeriesName(sno, chartObject)
{
    quit $LI($LB("Oats","Barley","Wheat"),sno+1)
}

Zen レポートのグラフの値の指定

Zen レポートと Zen ページのグラフ間で主に異なるのは、グラフへのデータの指定方法です。どちらも、ongetData 属性を使用して、データを提供するコールバック・メソッドを指定します。Zen ページによって、JavaScript で記述されたコールバック・メソッドが指定され、クライアント上で実行されます。これにより、配列が返されます。詳細は、このドキュメント "Zen コンポーネントの使用法" の “Zen ページのグラフの値の指定” セクションを参照してください。Zen レポートによって、ObjectScript または他の適切な言語で記述されたコールバック・メソッドが指定され、サーバ上で実行されます。ObjectScript ではメソッドで配列を返せないため、ゼロ・ベースの 2 次元配列は参照渡しされ、メソッドで入力されます。配列参照のほかに、グラフ・オブジェクトが ongetData コールバック・メソッドに渡されます。メソッド・シグニチャにグラフ・オブジェクトがない場合は、エラーとなります。passChartObject="false" の設定により、グラフ・オブジェクトを渡さない初期バージョン用に記述されたコードとの下位互換性を与えることができます。

Zen ページでは、ongetData 属性の値は完全な JavaScript 文になります。例えば、ongetData="return zenPage.getChartData(series);" のようになります。これにより、グラフ内からコールバック・メソッドへの引数を指定することができます。 Zen レポートでは、この属性の値は、単にメソッドの名前になります。例えば、ongetData="getChartData" のようになります。メソッドのパラメータに引数を指定することはできません。パラメータは内部コードで自動的に入力されます。Zen レポートのメソッド・シグニチャの要件が、より厳格になる理由がここにあります。

グラフのデータ取得および処理はすべて ongetData コールバック・メソッドで行われることに注意してください。このため、グラフの内容はレポートの XData ReportDefinition または XData ReportDisplay セクションで表示される構造またはデータ構成を反映していません。

以下のコード・サンプルでは、Zen レポートのコールバック・グラフの作成に対して異なるアプローチが示されています。どちらも、出力として同じ棒グラフが作成されます。

コールバック棒グラフ

SQL からのデータの取得

最初の例では、XData ReportDefinition は基本的にプレース・ホルダです。実際の作業は、<cbarChart> を定義する XData ReportDisplay と、データベースからのデータの取得に SQL を使用するコールバック・メソッド ongetData の getchartdata で行われます。その後に、コールバックでは、結果セットを使用して、参照によって渡された配列を入力します。

Class MyApp.getchartdata Extends %ZEN.Report.reportPage {
Parameter APPLICATION;
Parameter DEFAULTMODE = "html";
XData ReportDefinition [ XMLNamespace = "http://www.intersystems.com/zen/report/definition" ]
{
  <report xmlns="http://www.intersystems.com/zen/report/definition"
   name="test" runonce="true">
  </report>
}
XData ReportDisplay [ XMLNamespace = "http://www.intersystems.com/zen/report/display" ]
{
  <report xmlns="http://www.intersystems.com/zen/report/display"
     name="test">
    <document width="8.5in" height="11in" marginLeft="1.25in" marginRight="1.25in" 
     marginTop="1.0in" marginBottom="1.0in" headerHeight="1in">
    </document>
    <body>
      <cbarChart 
        plotAreaStyle="fill: #eeeeee;"
        ongetData="getchartdata" 
        title="Callback Chart Example" 
        height="400px" width="400px" 
        seriesColorScheme="solid"
        ongetLabelX="getName" >
        <yAxis majorGridLines="true" minValue="4" />
        <xAxis majorGridLines="true" />
      </cbarChart>  
    </body> 
  </report>
}
Method getName(val, yseries)
{
  quit $LG($LB("Adult Price","Child Price"),(val+1))
}
Method getchartdata(ByRef var, chart)
{
  SET myquery = 
    "SELECT TheaterName,AdultPrice,ChildPrice FROM Cinema.Theater ORDER BY TheaterName"
  SET tStatement = ##class(%SQL.Statement).%New()
  SET tStatement.%ObjectSelectMode=1
  SET tStatus = tStatement.%Prepare(myquery)
  SET rset = tStatement.%Execute()
  Set Count=0
  WHILE rset.%Next()
  {
    Set var(Count,0)=rset.AdultPrice
    Set var(Count,1)=rset.ChildPrice
    Set Count=Count+1
  } 
  quit $$$OK
}
}

XML からのデータの取得

次の例では、XData ReportDisplay ブロックおよび getName メソッドはこの前の例と同じであるため、削除されています。この例では、以前に使用されたものと同じ方法、つまり XPath グラフが採用されています。XData ReportDefinition では、SQL を使用してデータベースからデータを取得し、その結果セットを使用して中間 XSLT ドキュメントを作成します。コールバック・メソッドによってそのドキュメントにアクセスし、配列内のそのドキュメントからデータを格納します。詳細は、"Caché XML ツールの使用法" のドキュメントの “XPath 式の評価” を参照してください。

Include (%occSAX, %occXSLT)
Class MyApp.CBarChartXSLT Extends %ZEN.Report.reportPage
{
Parameter APPLICATION;
Parameter DEFAULTMODE = "html";
XData ReportDefinition [ XMLNamespace = "http://www.intersystems.com/zen/report/definition" ]
{
<report xmlns="http://www.intersystems.com/zen/report/definition"
 name="test" sql="SELECT ID,TheaterName,AdultPrice,ChildPrice
  FROM Cinema.Theater ORDER BY TheaterName" > 
  <group name="Theater" breakOnField="TheaterName">
  <attribute name="TheaterName" field="TheaterName" />
  <attribute name="TheaterID" field="ID" />
  <element name="Adult" field="AdultPrice" />
  <element name="Child" field="ChildPrice" />  
  </group>
</report>
}
///
/// XData ReportDisplay and Method getName deleted
///
Method getchartdata(ByRef var, chart)
{
  Set tSC=$$$OK
    do
    {
      Set tSC=##class(%XML.XPATH.Document).CreateFromFile(..xmlfile,.tDoc)
      if $$$ISERR(tSC) {Do $System.OBJ.DisplayError(tSC) Quit}
      Set tSC=tDoc.EvaluateExpression("/test","Theater",.tResults)
      if $$$ISERR(tSC) {Do $System.OBJ.DisplayError(tSC) Quit}
      For tI=1:1:tResults.Count()
      {
        Set tResult=tResults.GetAt(tI)
        Set index=$i(var(0))
        while (tResult.Read())
        {
        if (tResult.Name="Adult") 
        {
          do tResult.Read()
          Set var(index-1,0)=tResult.Value 
        }
        if (tResult.Name="Child")
        {
          do tResult.Read()
          Set var(index-1,1)=tResult.Value 
          Set index=$i(var(0))
        }
      }
    }
  } while(0)
}
}

Xmlfile

xmlfile は、文字列を格納する Zen レポートのプロパティであり、XML を含んでいる生成されたファイルの完全修飾名です。ユーザによる設定は必要ありません。XML XPATH と XSLT プロセッサで操作可能なデータのソースとしてコールバック・グラフで使用できます。xmlfile は、処理がサーバ上で行われる場合に定義されます。処理がブラウザ上で行われる場合は定義されません。"URI による Zen レポート・クラスのプロパティの設定" のセクションには、ブラウザまたはサーバで処理が発生した場合の概要が記載されています。

"XML からのデータの取得" のセクション内のコード・サンプルには、データ・ソースとして xmlfile を使用する方法が示されています。