cfhtmltopdf使用時の注意事項について

ColdFusion 11から追加された<cfhtmltopdf>は、PDFG(PDF Generator)と呼ばれるJettyサーバー(Add-onサービス)内で実行される HTML→PDFの変換エンジンを使用します。

cfhtmltopdf タグ

cfhtmltopdfタグ サンプル

従来の<cfdocument>に比べてHTMLの再現度が高く、CSSによるデザインもある程度(一部のCSS2やCSS3レベルには対応できていませんが)PDFに変換することができるなどの利点がありますが、<cfdocument>はColdFusion内で処理がすべて行われていたのに対して、<cfhtmltopdf>はColdFusion内部でHTMLを生成して、それをJettyサーバー(Add-onサービス)内で動く PDFg サービスに処理を渡して変換を行うため処理が複雑になるとともに、大量のHTML→PDF変換などを行うと、処理に時間が掛かりPDFG側でタイムアウトなどの障害が発生する場合があります。

ここでは<cfhtmltopdf>でいくつか確認されているトラブルや制限事項などについて紹介します。

  • <cfdocument>と同様、Standard版ではcfhtmltopdfのPDF変換はシングル動作となります。多重で処理は行われないため、前の変換処理が終わらないと次の処理が始まらないため処理のボトルネックが生じないように、リクエストを調整してください。
    • https://www.adobe.com/jp/products/coldfusion-family/buying-guide.html
      ※HTMLからのPDFファイルの生成が「機能制限あり」となり、
       ページ下部に”ColdFusion Standard Editionの機能制限:Enterpriseの
       各機能は、Enterprise Feature Router(EFR)を介して実行されます。
       Standard Editionで実行されます。ただし、EFRを介して実行される
       機能は、いずれも一度のリクエストにつき1つずつ処理されます。”
       の説明があります
       
  • UCS-2に含まれない文字は使用することができません
    • ColdFusionはUCS-2エンコードの対応となるため、それに含まれない文字(サロゲートペア文字)などは対応していません。また、<cfdocument>で使用するライブラリ、および、<cfhtmltopdf>で使用するPDFGも対応していません。ですので、UCS-2に含まれない文字を使用すると、その部分は文字化けを起こすかまたは空白になります。
    • (参考)About character encodings
       
  • ベクターグラフィックイメージは使用することができません
    • <cfdocument>、<cfhtmltopdf>では、ベクターグラフィックを使用することができません
  • <cfhtmltopdfitem type="pagebreak" />はLinux OSでは動作しません。また、Windows 環境の場合も下記の不具合に該当する場合はpagebreakが想定外の動作となります。これは変換エンジンの制限からくるため、制限となっています。
    • cfhtmltopdfitem (adobe.com)で「<cfhtmltopdf> がサービスとして使用される場合は、pagebreak は機能しません。」とありますが、これはLinux版で確認された不具合の情報から内容が抜粋されたもので、Linux版でpagebreakが機能しないことを示しています
    • Windows版についても、こちらで登録された不具合に該当する場合は正しくpagebreakが行えません
       
  • Linux版のcfhtmltopdfは、Windows版と比較すると変換エンジンの制限が多いため、以下の点に注意してください。
    • 変換エンジンが使用するライブラリ・フォントをインストールする必要があります。
    • デフォルトのフォントでは日本語が表示できません。そのため、CSS等で日本語フォントを明示的に指定してください。
    • 上記にも記載しましたが、pagebreakは機能しないため、複数ファイルに分割してpdfを作成し、処理の後にcfpdfでマージするなどでの対応を行ってください
    • 多重に処理が途切れることがなくcfhtmltopdfが実行された場合、変換エンジンの処理が止まってしまう場合がある模様です。断続的に大量のcfhtmltopdfを実行しないよう、実行間隔を調整して変換処理を行ってください
       
  • 変換エンジンは、Windows版は ColdFusion 2021|2018 Add-on Services、Linux版は cfjetty([cf_root]/{インスタンス(cfusion等)}/jetty 内の cfjetty スクリプト)を起動することで動作します。ColdFusionのサービスが先に起動しているとAdd-on Services(cfjetty)への接続が行えず変換エンジンが動作しないため、先に Add-on Services(cfjetty)を起動するようにしてください。
    • 発生するエラー: Error occurred while generating PDF.Reason: Error occurred while handling request.
       
  • サービス運用中にAdd-on Services(cfjetty)を停止・再起動すると、以後の変換エンジンの処理でエラーが発生します。
    • 発生するエラー: Error occurred while generating PDF.Reason: SERVER ERROR
       
  • 複雑なHTMLの構文・一つのTABLE内に大量の入れ子のTABLEタグやレコードが含まれる・HTMLの構文が不十分などの場合、変換エンジンの処理に時間が掛かったり、変換が正しく行えずにタイムアウト(既定:120秒)を起こす場合があります。変換するHTMLについては、以下の点を考慮してください
    • 変換するHTMLサイズをなるべく少なくする
    • 複数ページにまたがったTABLEタグなどを使用せず、シンプルなHTML構文(<html>~</html>を含めた)で記述する
       
  • PDFに変換するHTMLに、外部ファイル(画像ファイルやCSSファイル)などを相対パスで指定している場合、ColdFusionサーバー内から外部ファイルを取得しにいく必要があります。その際のURLは、リクエストを行った時のドメインやIPアドレスでアクセスしますので、ColdFusionサーバーからドメインやIPアドレスで到達できる必要があります
    • 例:https://cftest.samuraiz.co.jp/xxx/yyy/pdf.cfm をリクエスト
      <img src="abc.jpg" />
       ↓
      ※ColdFusionサーバー内から下記のリクエストが行われます
      <img src="https://cftest.samuraiz.co.jp/xxx/yyy/abc.jpg" />
       
    • ColdFusionサーバーからドメインの名前解決ができない場合は、外部ファイルに到達できずに変換処理のタイムアウト(既定120秒)を起こしますので、呼び出し方法を変更してください
      • リクエストを行った時ドメイン(上記の例だとcftest.samuraiz.co.jp)に対して 127.0.0.1を参照するようにhostsファイルに記載す
      • CSSファイルなどのテキストファイルは、外部ファイルの参照を止め、<cfinculde>でCSSファイルの内容を任意の場所(ヘッダ内等)にインクルードするようにコードを変更する
          <head>
           <style type="text/css">
           < !--
           <cfinclude template="sample.css">
           -- >
           </style>
          </head>
      • 相対パスではなくてローカルファイルを参照するようにコードを変更する
         <img src="file:///C:/inetpub/wwwroot/xxx/yyy/abc.jpg" />
         
      • 画像ファイルは、data URI を使用を使用してローカルファイルを参照するようにコードを変更する
         <cfoutput>
            <img src="data:image/jpg;base64,#toBase64(fileReadBinary(ExpandPath("abc.jpg")))#">
         </cfoutput>
         
  • Windows版のColdFusion 2021では、日本語が正しく表示されない不具合が確認されています。


 


記事公開日:2022年06月16日
最終更新日:2022年06月17日


x

Sample Modal Window

This is just a sample…

Lorem ipsum dolor sit amet, consectetur adipiscing elit. Praesent suscipit iaculis libero sed tristique. Quisque mollis dolor non tellus placerat vitae sodales lectus porta. Curabitur ut suscipit tellus. Maecenas rhoncus, ante vitae vehicula vestibulum, metus sapien dapibus tellus, et mattis dolor neque vitae nisl. Nullam eleifend ultrices ipsum eget pretium. Curabitur semper metus ut ante adipiscing nec volutpat sem rutrum. Nullam a nisi lacus, non interdum ante. Vivamus ante augue, commodo vel egestas sed, pharetra nec dui. Quisque sed tellus felis. Donec ipsum mauris, sagittis eu accumsan in, aliquam non ipsum.

Vestibulum tempor nunc nec felis scelerisque eget elementum erat dignissim. Ut vel ipsum mollis orci venenatis luctus. Aenean vehicula quam vel quam porttitor ac iaculis elit pulvinar. Proin consequat, ipsum eu venenatis semper, justo turpis posuere tortor, ac placerat metus nisl et lectus. Nulla cursus dui id nunc ullamcorper sed semper nisl lobortis. Aliquam erat volutpat. Phasellus arcu ante, imperdiet in ornare sed, laoreet eu massa.