cfspreadsheet

説明

Excel スプレッドシートファイルを管理します。

  • シートファイルからシートを読み取り、ColdFusion スプレッドシートオブジェクト、クエリー、CSV 文字列、または HTML 文字列に保管します。

  • クエリー、ColdFusion スプレッドシートオブジェクト、または CSV 文字列変数から単一のシートを新規 XLS ファイルに書き込みます。

  • 既存の XLS ファイルにシートを追加します。

カテゴリ

拡張タグ

シンタックス

タグのシンタックスは action 属性の値によって異なります。

Read 
<cfspreadsheet  
    action="read" 
    src = "filepath" 
    columns = "range" 
    columnnames = "comma-delimited list" 
    excludeHeaderRow = "true | false" 
    format = "CSV|HTML" 
    headerrow = "row number" 
    name = "text" 
    query = "query name" 
    rows = "range" 
    sheet = "number" 
    sheetname = "text"> 
 
Update 
<cfspreadsheet 
    action="update" 
    filename = "filepath" 
    format = "csv" 
    name = "text" 
    password = "password" 
    query = "query name" 
    sheetname = "text" > 
 
Write 
<cfspreadsheet  
    action="write" 
    filename = "filepath" 
    format = "csv" 
    name = "text" 
    overwrite = "true | false" 
    password = "password" 
    query = "queryname" 
    sheetname = "text" >

関連項目

スプレッドシート関数

履歴

ColdFusion 9.0.1:excludeHeaderRow 属性が追加されました。

ColdFusion 9: このタグが追加されました。

属性

属性

アクション

必須 / オプション

デフォルト

説明

action

すべて

必須

次のいずれかです。

  • read: XLS 形式のファイルの内容を読み取ります。

  • update: 既存の XLS ファイルに新しいシートを追加します。uppdate アクションを使用して、ファイル内の既存のシートを変更することはできません。詳細については、「使用方法」を参照してください。

  • write: 新しい XLS 形式のファイルを書き込むか、または既存のファイルを上書きします。

filename

update、writer

必須

書き込まれるファイルのパス名です。

excludeHeaderRow

read

オプション

false

true に設定すると、クエリ結果にヘッダー行が含まれなくなります。この属性は、Excel をクエリとして読み込む場合に役立ちます。headerrow 属性を指定すると、列名はヘッダー行から取得されます。ですが、列名は、クエリーの最初の行にも含まれてしまいます。ヘッダ行が含まれないようにするには、前述の属性値を true に設定します。

name

すべて

name または query が必須です。

  • read アクション : スプレッドシートファイルデータを保管する変数です。name または query を指定します。

  • write および update アクション : 書き込むデータが含まれている CSV フォーマットデータまたは ColdFusion スプレッドシートオブジェクトを含む変数です。name または query を指定します。

query

すべて

name または query が必須です。

  • read アクション : 変換されたスプレッドシートファイルを保管するクエリーです。formatname、または query を指定します。

  • write および update アクション : 書き込むデータが含まれているクエリー変数です。name または query を指定します。

src

read

必須

読み取るファイルのパス名です。

columns

read

オプション

列番号または列の範囲です。単一の番号、ハイフン区切りの列範囲、カンマ区切りリスト、またはこれらの任意の組み合わせ (1,3-6,9 など) を指定します。

columnnames

read

オプション

カンマ区切りの列名です。

format

すべて

オプション

read: スプレッドシートオブジェクトとして保存します。

update および write: スプレッドシートオブジェクトを保存します。

name 変数で表されるデータの形式です。

  • すべて : csv: 読み取り時に、XLS ファイルを CSV 変数に変換します。

  • update または write の際、CSV 変数を XLS ファイルに保存します。

  • 読み取り専用 : html: XLS ファイルを HTML 変数に変換します。

cfspreadsheet タグは、常に、スプレッドシートデータを XLS ファイルとして書き込みます。HTML 変数または CSV 変数を HTML ファイルまたは CSV ファイルとして書き込むには、cffile タグを使用します。

headerrow

read

オプション

列名を含む行番号です。

overwrite

write

オプション

false

既存のファイルを上書きするかどうかを指定するブール値です。

password

update

write

オプション

シートを変更するためのパスワードを設定します。

メモ : 空白文字列のパスワードを設定しても、パスワードの保護が完全に設定解除されるわけではありません。シートを変更しようとすると、パスワードの入力を求められます。

rows

read

オプション

読み取る行の範囲です。単一の番号、ハイフン区切りの行範囲、カンマ区切りリスト、またはこれらの任意の組み合わせ (1,3-6,9 など) を指定します。

sheet

read

オプション

シートの番号です。read アクションの場合、sheet または sheetname を指定できます。

sheetname

すべて

オプション

シートの名前 : read アクションの場合、sheet または sheetname を指定できます。

write および update アクションの場合は、sheetname で指定した値に従って、指定されたシートの名前が変更されます。

使用方法

各 ColdFusion スプレッドシートオブジェクトは、Excel シートを表しています。

  • 複数のシートを持つ Excel ファイルを読み取るには、read オプションで複数の cfspreadsheet タグを使用し、シートごとに異なる name および sheet または sheetname 属性を指定します。

  • 単一ファイルに複数のシートを書き込むには、write アクションを使用してファイルを作成し、最初のシートを保存します。update アクションを使用して、各追加シートを追加します。

  • 既存のファイルを更新するには、ファイルのすべてのシートを読み取り、複数のシートを変更して、その内容を使用します。write アクションおよび Update アクション (複数のシートファイルの場合) を使用して、ファイル全体を再度書き込みます。

cfspreadsheet タグは、XLS 形式のファイルのみを書き込みます。CSV ファイルを書き込むには、データを CSV 形式の文字列変数に配置し、cffile タグを使用して、ファイルにこの変数の内容を書き込みます。

SpreadsheetNewSpreadsheetAddColumn などの ColdFusion Spreadsheet* 関数を使用して、新しい ColdFusion スプレッドシートオブジェクトを作成し、スプレッドシートの内容を変更します。

次の例では、cfspreadsheet タグを使用して、さまざまな形式を使用した Excel スプレッドシートの読み取りおよび書き込みを行います。また、ColdFusion Spreadsheet 関数を使用してシートを変更する簡単な方法も示します。

<!--- Read data from two datasource tables. ---> 
<cfquery 
       name="courses" datasource="cfdocexamples" 
       cachedwithin="#CreateTimeSpan(0, 6, 0, 0)#"> 
       SELECT CORNUMBER,DEPT_ID,COURSE_ID,CORNAME 
       FROM COURSELIST 
</cfquery> 
 
<cfquery 
       name="centers" datasource="cfdocexamples" 
       cachedwithin="#CreateTimeSpan(0, 6, 0, 0)#"> 
       SELECT * 
       FROM CENTERS 
</cfquery> 
     
<cfscript> 
    //Use an absolute path for the files. ---> 
       theDir=GetDirectoryFromPath(GetCurrentTemplatePath()); 
    theFile=theDir & "courses.xls"; 
    //Create two empty ColdFusion spreadsheet objects. ---> 
    theSheet = SpreadsheetNew("CourseData"); 
    theSecondSheet = SpreadsheetNew("CentersData"); 
    //Populate each object with a query. ---> 
    SpreadsheetAddRows(theSheet,courses); 
    SpreadsheetAddRows(theSecondSheet,centers); 
</cfscript> 
 
<!--- Write the two sheets to a single file ---> 
<cfspreadsheet action="write" filename="#theFile#" name="theSheet"  
    sheetname="courses" overwrite=true> 
<cfspreadsheet action="update" filename="#theFile#" name="theSecondSheet" 
    sheetname="centers"> 
 
<!--- Read all or part of the file into a spreadsheet object, CSV string, 
      HTML string, and query. ---> 
<cfspreadsheet action="read" src="#theFile#" sheetname="courses" name="spreadsheetData"> 
<cfspreadsheet action="read" src="#theFile#" sheet=1 rows="3,4" format="csv" name="csvData"> 
<cfspreadsheet action="read" src="#theFile#" format="html" rows="5-10" name="htmlData"> 
<cfspreadsheet action="read" src="#theFile#" sheetname="centers" query="queryData"> 
 
<h3>First sheet row 3 read as a CSV variable</h3> 
<cfdump var="#csvData#"> 
 
<h3>Second sheet rows 5-10 read as an HTML variable</h3> 
<cfdump var="#htmlData#"> 
 
<h3>Second sheet read as a query variable</h3> 
<cfdump var="#queryData#"> 
 
<!--- Modify the courses sheet. ---> 
<cfscript> 
    SpreadsheetAddRow(spreadsheetData,"03,ENGL,230,Poetry 1",8,1); 
    SpreadsheetAddColumn(spreadsheetData, 
    "Basic,Intermediate,Advanced,Basic,Intermediate,Advanced,Basic,Intermediate,Advanced", 
    3,2,true); 
</cfscript> 
 
<!--- Write the updated Courses sheet to a new XLS file ---> 
<cfspreadsheet action="write" filename="#theDir#updatedFile.xls" name="spreadsheetData"  
    sheetname="courses" overwrite=true> 
<!--- Write an XLS file containing the data in the CSV variable. --->     
<cfspreadsheet action="write" filename="#theDir#dataFromCSV.xls" name="CSVData"  
    format="csv" sheetname="courses" overwrite=true>