Extension:Cargo/Storing data/zh

在Cargo中，数据结构的创建及数据的存储完全靠模板完成. 任何使用Cargo的模板都需要包含对解析器函数 和 的调用，或者较罕见的是调用 和. 定义了数据表的字段， 将数据存入数据表，而 指定将模板数据存入事先在其他地方定义过了的数据表.

声明一个表
需要将数据存储在表中的模板，要么声明该表，要么将自身附着在其他地方声明过的表. 由于通常情况下表和模板是一一对应的，大多数使用Cargo的模板都会定义自己的表. 声明通过解析函数 完成.

这个函数通过如下语法调用：

表名和字段名都不能包含空格或破折号，但你可以使用下划线、CamelCase式大小写等. 下划线不能用于表和字段名称的开头或结尾.

字段描述必须以字段的类型开头（在许多情况下描述部分只会出现字段类型）. Cargo中预定义了以下类型：

Any other type specified will be treated as type "String". Fields of types that are unindexed are significantly slower to query on or join on.

字段也可以存储以上类型的列表. 要定义一个这样的列表，类型值应该是这样子：“List (分隔符) of 类型”. 例如，如果要有称为“Authors”的域，存储由逗号隔开的字符串值，你可以在$cargo_declare调用中使用以下参数：

|Authors=List of String

字段参数
描述字符串也可以有额外的参数，这些都包含在类型标识符后的括号中，用分号隔开. 当前允许的参数有：


 * For example, to define a field called "Color" that has three allowed values, you could have the following declaration:

|Color=String (size=10;allowed values=Red,Blue,Yellow)


 * Meanwhile, to define a field called "Main ingredient" that is a hierarchy, you could have the following declaration:


 * Main_ingredient = String (hierarchy;allowed values=*Fruits
 * Mangoes
 * Apples
 * Vegetables
 * Root vegetables
 * Carrots
 * Turnips
 * Peppers)

其他的#cargo_declare参数
除了表的名称和字段之外，以下参数也可以添加到#cargo_declare中：


 * - for setting one or more other Cargo tables as the "parent tables" of this table. This is used within Special:Drilldown, to let the user filter on fields from additional Cargo tables that are tied in some way to this one. It takes the following syntax:
 * _parentTables= tableName1(_localField=localFieldName, _remoteField=remoteFieldName, _alias=tableAlias); tableName2(...); ...
 * Here, 'tableName1' is the name of the table you want to declare as the parent table. '_localField' and '_remoteField' specify the fields in the two tables that need to be joined on (the default values for both are "_pageName"). If '_alias' is defined, then that will be displayed in the drilldown instead of the parent table's name.


 * Example: This drilldown display shows additional drilldown fields from a parent table, "Items" (listed as "Item) (template here)


 * - for setting custom drilldown tabs in Special:Drilldown page. It can be declared like this:
 * _drilldownTabs= Tab1(format=list;delimiter=\;;fields=A,B,C), Tab2(format=table; fields=A,C,D)
 * where 'Tab1' is the display name of the tab, 'format' parameter takes the desired format name and after that you can add all the parameters needed for that format and then 'fields' holds the set of fields to be displayed.


 * Example: This drilldown display also shows custom tabs (template here)


 * 1) cargo_declare also displays a link to the Special:CargoTables page for viewing the contents of this database table.

附着于另一个表
In some cases, you may want more than one template to store their data to the same Cargo table. In that case, only one of the templates should declare the table, while the others should simply "attach" themselves to that table, using the parser function.

This function is called with the following syntax:

A template should have no more than one call to #cargo_attach (and no more than one call to #cargo_declare, for that matter). Any template that contains a call to #cargo_store should also call either #cargo_declare or #cargo_attach.

在一个表中存储数据
A template that declares a table or attaches itself to one should also store data in that table. This is done with the parser function. Unlike  and , which apply to the template page itself and thus should go into the template's &lt;noinclude&gt; section,   applies to each page that calls that template, and thus should go into the template's &lt;includeonly&gt; section.

This function is called with the following syntax:

The field names must match those in the  call elsewhere in the template.

The values will usually, but not always, be template parameters; but in theory they could hold anything.

For fields whose value is a template parameter, and where the name of the template parameter is the same as the name of the Cargo field (other than the presence of underscores instead of spaces), the field can be left out of the #cargo_store call; so, in many cases, the call could instead simply look like:

In fact, not even the table name really needs to specified; so in many cases the call could even look like:

However, this is slightly less efficient (and maybe more confusing to readers) than specifying the table name.

存储循环事件
Special handling exists for storing recurring events, which are events that happen regularly, like birthdays or weekly meetings. For these, the parser function  exists. It takes in a set of parameters for a recurring event (representing the start date, frequency etc.), and simply prints out a string holding a list of the dates for that event. It is meant to be called within  (for a field defined as holding a list of dates), and   will then store the data appropriately. is called with the following syntax:

Of these parameters, only "start=" and "unit=" are required.

By default, if no end date is set, or if the end date is too far in the future,  stores 50 instances of the event. To change this, you can add a setting for  in LocalSettings.php, under the inclusion of Cargo. For instance, to set the number to 100, you would add the following:

If working with recurring events, declare the type of the field of the field to be.

示例
You can see two templates that make use of #cargo_declare and #cargo_store here and here.

创建或重新创建一个表
No data is actually generated or modified when a template page containing a #cargo_declare call is saved. Instead, the data must be created or recreated in a separate process. There are two ways to do this:

通过网页
From the template page, select the tab action called either "Create data" or "Recreate data". This will bring up an interface that may contain a checkbox reading "Recreate data into a replacement table, keeping the old one for querying". (That checkbox will only appear if the Cargo table in question already exists.)

Once you hit "OK", one of the following will happen:

In all three cases, MediaWiki jobs are used to cycle through all the relevant pages and recreate the data - a separate job is created for each page. This can be a lengthy process for large tables, which is why using the "replacement table" approach is recommended for large tables - it avoids a "down time" period when the table is mostly empty.
 * 1) If the checkbox was selected, a "replacement table" will be created, while the current table remains unaffected. This replacement table can be viewed by anyone, but its data will not be used in queries. (In the database, the actual table will have a name like "cargo__tableName__NEXT".) If/when you think this replacement table is ready to be used, you can click on the "Switch in table" link at Special:CargoTables. This link will delete the current Cargo table and rename the replacement table so that it becomes the official table. Conversely, if you don't want to use the replacement table, you can click on the "Delete" link for it.
 * 2) If the checkbox was not selected, the current table will be deleted immediately, and a new version will get created.
 * 3) If the checkbox was not there, it means that this is a new table. In that case, the table will be created.

Depending on the MediaWiki configuration, a call to MediaWiki's script may be useful or even necessary for these jobs to actually start.

If any templates contain #cargo_attach, they too will get a "Create data" or "Recreate data" tab. If this tab is selected and activated, it will not drop and recreate the database table itself; instead, it will only recreate those rows in the table that came from pages that call that template.

权限
The ability to create/recreate data is available to users with the 'recreatecargodata' permission, which by default is given to sysops. You can give this permission to other users; for instance, to have a new user group, 'cargoadmin', with this ability, you would just need to add the following to LocalSettings.php:

Once a table exists for a template, any page that contains one or more calls to that template will have its data in that table refreshed whenever it is resaved; and new pages that contain call(s) to that template will get their data added in when the pages are created.

命令行脚本
If you have access to the command line, you can also recreate the data by calling the script cargoRecreateData.php, located in Cargo's  directory. It can be called in one of two ways:

In addition, the script can be called with the  flag, which turns off all printouts. For full usage information, call it with.

存储页面数据
You can create an additional Cargo table that holds "page data": data specific to each page in the wiki, not related to infobox data. This data can then be queried either on its own or joined with one or more "regular" Cargo tables. The table is named "_pageData", and it holds one row for every page in the wiki. You must specify the set of fields you want the table to store; by default it will only hold the five standard Cargo fields (_pageName, _pageTitle, _pageNamespace, _pageID and _ID: see Database storage details). To include additional fields, add to the array $wgCargoPageDataColumns in LocalSettings.php, below the line that installs Cargo.

Currently there are seven more fields that can be added to the _pageData table; here are the fields, and the call to add each one:

Once you have specified which fields you want the table to hold, go to the Cargo /maintenance directory, and make the following call to create, or recreate, the _pageData table:

To recreate with replacement, add a  flag:

The replacement table can then be switched in normally using the  interface.

If you want to get rid of this table, call the following instead:

You do not need to call the "--delete" option if you are planning to recreate the table; simply calling setCargoPageData.php will delete the previous version.

存储文件数据
Similarly to page data, you can also automatically store data for each uploaded file. This data gets put in a table called "_fileData", which holds one row for each file. This table again has its own settings array, to specify which columns should be stored, called $wgCargoFileDataColumns.

There are currently five columns that can be set:

To store the full text of PDF files, you need to have the  utility installed on the server, and then add the following to LocalSettings.php:

pdftotext is available as part of several different packages. if you have the PdfHandler extension installed (and working), you may have pdftotext installed already.

To store the number of pages, you need to have the  utility installed on the server, and then add the following to LocalSettings.php:

Once you have specified which fields you want the table to hold, go to the Cargo /maintenance directory, and make the following call to create, or recreate, the _fileData table:

数据库存储细节
When the data for a template is created or recreated, a database table is created in the Cargo database that (usually) has one column for each specified field. This table will additionally hold the following columns:

存储列表
For fields that have lists of values, the handling is more complex: a whole separate database table is created to hold all the individual values for this field. This table will get the name "MainTableName__FieldName" (e.g. "Books__Authors"), and it will have the following fields:

So if an "Authors" field contained three values, the "Books__Authors" table would have three rows corresponding to that one page.

There's one more complication for list fields: the corresponding field for a list field in the database table will not actually be given that name, but will rather be called "FieldName__full", e.g. "Authors__full". This is to enable the "true" field name to serve as a "virtual" field within the #cargo_query call, to make querying on the field values table easier (see 'The "HOLDS" command').

存储层次结构
For fields that have a set of allowed values that is defined as being a hierarchy, a separate database table is created to store the whole set of allowed values. This table will get the name "MainTableName__FieldName__hierarchy" (e.g. "Books__Genre__hierarchy"), and it will have the following fields:

For an explanation of this method of storage, see the Wikipedia article "Nested set model".

存储文件名称
If a table has one or more fields of type "File", an additional table is created - for use in searching on files within Special:Drilldown - with the name "MainTableName__files" (e.g. "Books__files"), with the following fields:

存储坐标
For fields of type 'Coordinates', like for fields that hold a list of values, no database field is created with the actual specified field name. Instead, the following three fields are created:

If the coordinates cannot be parsed, the "__full" field still gets the value, but the "__lat" and "__lon" fields are set to null.

存储日期
For fields of type 'Date' or 'Datetime', an extra field is created that is named "fieldName__precision". It holds an integer value representing the "precision" of each date value, i.e. whether it holds a full date, only a year, etc. The possible values are:

Storing Flex Diagrams data
The Flex Diagrams extension lets users define (and display) diagrams within wiki pages. If both Cargo and Flex Diagrams are installed on a wiki, you can store some of the data from those diagrams within special Cargo tables, so that the data can be browsed and queried. Two diagram types can have their data stored: BPMN diagrams and Gantt charts. Unlike with Cargo's standard special tables, _pageData and _fileData, you cannot dictate which columns get set - they all are.

BPMN diagrams
Data about BPMN diagrams is stored in the table _bpmnData. This table can be generated by calling the following in the Cargo /maintenance directory:

This table holds the following columns:

Gantt charts
Data about Gantt charts is stored in the table _ganttData. This table can be generated by calling the following in the Cargo /maintenance directory:

This table holds the following columns: