README

此Silverstripe模块使得将一组Silverstripe DataObjects导出到

• Excel 2007 (XLSX)
• Excel 5 (XLS)
• CSV

此模块通过扩展标准 SilverStripe DataFormatter 构建。

需求

• silverstripe/cms >=3.1
• phpoffice/phpexcel >=1.8

建议

• silverstripe/restfulserver >=3.1

安装

通过 composer 安装模块

composer require firebrandhq/silverstripe-excel-export

导出DataObjects

您可以通过以下三种方式将数据导出到电子表格。

通过直接调用DataFormatter

提供了3个DataFormatter

• ExcelDataFormatter用于XLSX
• OldExcelDataFormatter用于XLS
• CsvDataFormatter用于CSV

您可以直接实例化它们以将数据对象列表或单个数据对象转换为Excel格式。

$formatter = new ExcelDataFormatter();

// Will return an Excel Spreadsheet as a string for a single user
$filedata = $formatter->convertDataObject($user);

// Will return an Excel Spreadsheet as a string for a list of user
$filedata = $formatter->convertDataObjectSet(Member::get());

convertDataObjectSet() 和 convertDataObject() 将自动设置适当的Mime类型HTTP头。

您还可以获取底层的 PHPExcel 对象，并将数据对象集导出为 PHPExcel 支持的任何格式。

// Get your Data
$formatter = new ExcelDataFormatter();
$excel = $formatter->getPhpExcelObject(SiteTree::get());

// Set up a writer
$writer = PHPExcel_IOFactory::createWriter($excel, 'HTML');

// Save the file somewhere on the server
$writer->save('/tmp/sitetree_list.html');

// Output the results back to the browser
$writer->save('php://output');

// Output the file to a variable
ob_start();
$writer->save('php://output');
$fileData = ob_get_clean();

将GridFieldExcelExportButton添加到GridField

GridFieldExcelExportButton允许CMS用户轻松地将GridField中的数据导出到电子表格。

$rowEntryConfig = GridFieldConfig_RecordEditor::create();
$rowEntryConfig->addComponent(new GridFieldExcelExportButton());
$rowEntryDataGridField = new GridField(
    "ContentRow",
    "Content Row Entry",
    $this->ContentRow(),
    $rowEntryConfig
);
$fields->addFieldToTab('Root.Main', $rowEntryDataGridField);

上面的代码片段将显示一个分割按钮，允许用户将GridField列表导出为他们选择的格式。

与SilverStripe GridFieldExportButton不同，GridFieldExcelExportButton将导出提供的数据对象的全部字段...而不仅仅是摘要字段。

您还可以使用GridFieldExcelExportAction组件。此按钮添加到每行，允许您一次导出一个记录。默认情况下，GridFieldExcelExportAction将导出为xlsx格式，但您可以将它设置为导出为xls或csv（例如：new GridFieldExcelExportAction('csv')）。

GridFieldExcelExportAction和GridFieldExcelExportButton可以结合使用，如果您想为用户提供这两种选项。

通过SilverStripe RestfulServer模块调用

SilverStripe RestfulServer模块 允许您将任何Silverstripe网站转换为RESTFul服务器。

如果您将SilverStripe RestfulServer模块与Silverstripe Excel Export模块结合使用，您只需在浏览器中输入正确的URL即可动态导出任何DataObject集。

访问控制

显然，您不希望每个人都能从您的网站上下载任何数据。SilverStripe RestfulServer模块将只为设置了$api_access属性的数据对象返回结果。

private static $api_access = true;

此外，对单个数据对象的访问由canView函数控制。

配置SilverStripe RestfulServer模块

获取数据

导出数据就像输入一个URL一样简单。

• 获取所有页面的列表（Excel 2007）: https://127.0.0.1/api/v1/Page.xlsx
• 获取所有页面的列表（Excel 5）: https://127.0.0.1/api/v1/Page.xls
• 获取所有页面的CSV列表：https://127.0.0.1/api/v1/Page.csv
• 限制列表为10个结果：https://127.0.0.1/api/v1/Page.csv?limit=10
• 返回单个记录：https://127.0.0.1/api/v1/Page/37.xlsx
• 钻入关系：https://127.0.0.1/api/v1/Tag/127/Articles.xlsx

SilverStripe RestfulServer模块支持的操作

自定义输出

您有2种方式可以控制输出

• 选择要输出的字段；
• 选择在标题中使用字段标签而不是字段名称。

选择要输出的字段

因为 ExcelDataFormatter 扩展了 DataFormatter，您可以使用诸如 setCustomFields()、setCustomAddFields() 或 setRemoveFields() 等方法来控制哪些字段将出现在电子表格中。

$formatter = new ExcelDataFormatter();

// This formatter instead of returning every field of a DataObject, will only return 3 fields.
$formatter->setCustomFields(['ID', 'Title', 'LastEdited']);

// If youe DataObject has dynamic properties, you can reference them using setCustomAddFields().
$formatter->setCustomAddFields(['ChildrenCount']);

定义默认列集

您可以通过在您的DataObject类中定义一个 getExcelExportFields() 方法来自定义特定DataObject类返回的默认列集。

此 getExcelExportFields() 方法应返回一个字段数组，其格式与 DataObject::inheritedDatabaseFields() 使用的格式相同

return [
    'ID' => 'Int',
    'Name' => 'Varchar',
    'Address' => 'Text'
];

您还可以在此数组中引用关系或动态属性

return [
    'Owner.Name' => 'Varchar',
    'Category.Title' => 'Varchar',
    'ChildrenCount' => 'Int',
];

这还将允许您控制字段在电子表格中的顺序。请注意，ID始终是第一个字段，不能删除。

您可以通过调用 setCustomFields() 方法来覆盖特定实例的 ExcelDataFormatter 的此行为。

使用字段标签或字段名称作为列标题

默认情况下，将使用实际的字段名称作为列标题。（例如：FirstName 而不是 First Name）。

您可以自定义此行为，并使用DataObject类中定义的字段标签。在生成标题行时，ExcelDataFormatter 将在您的Data Object上调用 fieldLabel() 方法以决定每个标题中使用的字符串。

更改所有 ExcelDataFormatter 的默认值

在您的YML配置中，您可以使用以下语法来更改默认标题。

ExcelDataFormatter:
  UseLabelsAsHeaders: true

覆盖特定实例的默认值

您可能需要更改特定实例的默认行为。

$formatter->setUseLabelsAsHeaders(true);