Extension:Semantic Forms/zh-hant

From MediaWiki.org

Manual on MediaWiki Extensions
List of MediaWiki Extensions

Semantic Forms Release status: stable
Implementation	Special page
Description	一個建基於Semantic MediaWiki的外掛套件, 以使得用戶可用以新增及編輯配合樣板(templates模板)使用的頁面。Forms are defined using editable text files, written in a custom markup language, that are then parsed on-the-fly when a form is needed.
Author(s)	Yaron Koren <yaron57@gmail.com>, and others
Last Version	1.0 (March 2008)
MediaWiki	1.8.* or greater download = 下載
License	No license specified
Download	no link
Example	An auto-generated form allowing the user to edit an opinion item
Hooks used SkinTemplateTabs LanguageGetMagic

[edit] 說明

Semantic Forms是MediaWiki的外掛,用戶可用以新增及編輯配合樣板(templates模板)使用的頁面. 其相當仰賴Semantic MediaWiki ；且適用於使用語意標記(semantic markup)的結構性資料，使用本外掛之前，先行安裝語意維基(Semantic MediaWiki)是必要的。 「原文：Semantic Forms is an extension to MediaWiki that allows users to add and edit data using forms. It is heavily tied in with the Semantic MediaWiki extension, and is meant to be used for structured data that has semantic markup. Having Semantic MediaWiki installed is a precondition for the Semantic Forms extension; the code will not fully work without it.」

Very simply, Semantic Forms allows you to have forms for adding and editing data on your wiki, without any programming. Forms can be created and edited not just by administrators, but by users themselves.

The main components of Semantic Forms functionality are form definition pages, which exist in a new namespace, 'Form:'. These are pages consisting of markup code which gets parsed when a user goes to add or edit data. Since forms are defined strictly through these definition pages, users can themselves create and edit forms, without the need for any actual programming.

The Semantic Forms extension enforces the use of templates in creating semantic data. It does not support direct semantic markup in data pages; instead, all the semantic markup is meant to be stored indirectly through templates. A form allows a user to populate a pre-defined set of templates for a page (behind the scenes, that data is turned into semantic properties once the page is saved).

表單可用於編輯已存在於某面上的資料，您可使「以表單進行編輯」標籤顯現於任何頁面上，參見「以表單進行編輯」標籤 「原文：Forms can also be used to edit the data in an existing page, and you can enable an 'edit with form' tab to show up on any page; see The 'edit with form' tab.」

Semantic Forms 亦支援「自動填入欄位」，所以用戶可輕易看見欄位的前次某輸入值。 「原文：Semantic Forms also supports autocompletion of fields, so users can easily see what the previously-entered values were for a given field. This greatly helps to avoid issues of naming ambiguity, spelling, etc.」

當您頁面的內容不符合表單內的欄位設定，則那些內容將會送入隨意文字區(Free text)，而不會遺失不見。

 「原文：Data in a page that doesn't fit into the form, like a free-form text description of the page's subject, doesn't get ignored when the page is edited with a form; instead, it gets placed into a separate input box, called "Free text".」

Semantic Forms also provides hooks to let outside code easily define new input types; this is useful for, among other things, new extensions to define input types that use code that they provide.

語意表單(Semantic Forms)亦提供了其他工具：

• 「新增語意性質/屬性/關連」工具
• 「新增樣板(模板)」工具
• 「新增表單」工具

此一文件將一一說明，特別是參見特殊頁面該節。

 「原文：Semantic Forms also provides other features: a form to create semantic properties, a form to create templates, a form to create user forms, pages that list all the templates and all the user forms on the site, and others. This documentation covers all the features, but see especially the Special pages section.」

[edit] 下載程式碼

• 參見Semantic Forms

[edit] 安裝

再度提醒您安裝本套件前須先行完成安裝 Semantic MediaWiki套件。

• 安裝本外掛套件的步驟：
  1. 下載本套件且置於wiki/extensions/SemanticForms/目錄內
  2. 於'LocalSettings.php'檔案內加入以下的設定(注意以下的設定須置於語意維基(Semantic Mediawik)相關的設定及自訂名字空間相關的設定之後。)

//以下為自訂名字空間相關的設定，可以不設定
$wgExtraNamespaces =
	array(
	100 =>	"TEST",
	101 =>	"TEST_talk",
);
 
//以下為語意維基(Semantic Mediawik)相關部分的設定僅供參考
$smwgEnableTemplateSupport = true;   //設定Semantic Mediawik可使用樣板(template)頁面內容的設定。
$smwgNamespaceIndex = 102;           //此設定將使Semantic Mediawik使用102~107等名字空間
include_once('extensions/SemanticMediaWiki/includes/SMW_Settings.php');
enableSemantics('127.0.0.1');       //請依您的網站的URL或IP的設定酌予修改此行。
 
/*
 以下為Semantic Forms的相關設定
 第一行將表單的名字空間(Namespace)設定為150
 若您不想將表單的名字空間(Namespace)設定為150時您可不設定此行；
 內定的名字空間值為106；
 設定時須避開Semantic Mediawik所佔用的6個名字空間。
*/
$sfgNamespaceIndex = 150; 
include_once('extensions/SemanticForms/includes/SF_Settings.php');

After you've obtained a 'SemanticForms' directory (either by extracting a compressed file or downloading via SVN), place this directory within the main MediaWiki 'extensions' directory. Then, in the file 'LocalSettings.php' in the main MediaWiki directory, add the following line below the calls for the Semantic MediaWiki extension (both the main 'include_once' line and the 'enableSemantics' line):

include_once('extensions/SemanticForms/includes/SF_Settings.php');

You may also wish to change the number value for the new "Form" namespace, defined in SF_Settings.php; by default it is set to 106.

Also, if you have any custom namespaces declared, you should add the following declaration before the 'include_once' call in the file 'LocalSettings.php':

$sfgNamespaceIndex = 150;

(Or, instead of 150, whatever number you want the "Form" namespace set to.)

NOTE: The definition of $sfgNamespaceIndex and the call to SF_Settings.php must be placed after the initialization of any custom namespace definitions in LocalSettings.php. Otherwise, the Form namespace will not initialize.

[edit] 語言支援

參Extension:Semantic_Forms#Languages_supported

[edit] 作者

參Extension:Semantic_Forms#Authors

[edit] 版本

Semantic Forms is currently at version 1.0 See the entire version history.

[edit] 特殊頁面

此一外掛建立如下的特殊頁面，相信您必能望文生義的了解它們(並請有緣者能補充此一翻譯)： 「原文：he extension defines eight "special" MediaWiki pages:」

• 新增資料 - lets a user add a page using a user-defined form. (See example of page)
• 新增頁面 - lets a user specify a page name, to be either added or edited depending on whether it already exists. (See example of page))This page is somewhat deprecated.
• 新增表單 - lets a user create a new form for adding/editing data. (See example of page)
• 新增樣板 - lets a user create a new template. (See example of page)
• 新增語意(semantic)性質 - lets a user create a new property. (See example of page)
• 新增分類(Category) - lets a user create a new category. (See example of page)
• 編輯資料 - lets a user edit an existing page using a user-defined form. (See example of page) This page is somewhat deprecated.
• 表單 - lists all form pages on the site. (See example of page)
• 樣板'Special:Templates' - lists all templates on the site. (See example of page)

[edit] 程式碼結構

以下為此套件所使用的資料夾及檔案： 「原文：The following are the directories and files in the Semantic Forms extension:」

/includes

• SF_FormClasses.inc - defines three classes - SFForm, SFTemplateInForm and SFFormTemplateField - that represent the components of a user-defined form, and handle the creation of a form definition file.
• SF_FormEditTab.php - a tab that shows up on data pages to let the user edit them with a form, if a default form for this page's category or namespace has been specified.
• SF_FormPrinter.inc - defines a class, SFFormPrinter, that handles the display and running of a user-created form.
• SF_GlobalFunctions.php - functions and constants used by the rest of the Semantic Forms code.
• SF_ParserFunctions.php - defines parser functions (currently two - 'forminput' and 'arraymap')
• SF_Settings.php - various settings for Semantic Forms.
• SF_TemplateField.inc - defines a class, SFTemplateField, used in both creating templates and displaying user-created forms.

/languages

• SF_Language.php - parent class for all language files
• SF_LanguageDe.php - German-language text
• SF_LanguageEn.php - English-language text
• SF_LanguageFa.php - Persian-language text
• SF_LanguageFr.php - French-language text
• SF_LanguageHe.php - Hebrew-language text
• SF_LanguageNl.php - Dutch-language text
• SF_LanguagePt_br.php - Brazilian-Portuguese-language text
• SF_LanguageZh_cn.php - Mainland-Chinese-language text
• SF_LanguageZh_tw.php - Taiwanese-Chinese-language text
• SF_Messages.php - Display messages for all languages

/libs

• SF_yui_autocompletion.js - helper functions for auto-completion with the Yahoo! User Interface (YUI) library

/skins

• SF_main.css - main CSS file for Semantic Forms
• SF_yui_autocompletion.css - CSS file for YUI auto-completion

/specials

• SF_AddData.php - defines the 'AddData' special page
• SF_AddPage.php - defines the 'AddPage' special page
• SF_CreateCategory.php - defines the 'CreateCategory' special page
• SF_CreateForm.php - defines the 'CreateForm' special page
• SF_CreateTemplate.php - defines the 'CreateTemplate' special page
• SF_CreateProperty.php - defines the 'CreateProperty' special page
• SF_EditData.php - defines the 'EditData' special page
• SF_Forms.php - defines the 'Forms' special page
• SF_Templates.php - defines the 'Templates' special page

[edit] 起步

當您安裝好本套件之後，即可依下列的數個步驟來進行您的工作： 「原文：So, you've set up all the software on your site. Now what? Now it's time to create the structures to hold, display and enable adding and editing of your data; thankfully all of this can be done simply by creating various wiki pages. You should take the following steps:」

• 規劃您的資料結構。您的資料是屬何種「型態」，您雖可於稍後改變它們，但建議您及早規劃較好。 「原文：Figure out your data structure. What types of pages will the site have? What data will be contained on each one? You can change all of this around later, but it's good to have a starting plan.」

• 新增「性質」(SMW 0.7或更早以前則使用「關聯」及「屬性」)，這是任何語意網站必備的。您可輕易的以新增性質完成此一工作。 「原文： Create properties. The basic building blocks of any semantic site are the connections between data, which in Semantic MediaWiki are known as properties. A property is used to specify a single piece of information about the topic of this page; the value of a property can either be a standalone value, or the name of a page on the wiki. Every property should be defined on your wiki, with a page in the "Property:" namespace. The easiest way to do that is using the 'CreateProperty' special page (see above).」

• 新增樣板：樣板具備了許多功能，如處理某項多值的「性質」舉例來說像是「[[承辦人員:=張三,李四,王二]]」(參見於某欄位內輸入多重數值一節)，以及指定所有含有特定性質的值(如「[[承辦人員:=張三]]」)的頁面名稱給聚集起來並展示於該頁面，建立樣板最方便的途徑應算是使用新增樣板此一工具。 「原文： Create templates. A template sets the display of the data on a page, holds the markup to turn the data into actual semantic information, and (often) defines the page as being of a certain category, and thus of a certain page type. There will generally be one template per page type, although sometimes a single page type will contain more than one template. A template can also be used for aggregation, by displaying a list of all other pages that have a certain relationship to this page (see the inline queries documentation for much more information on this). The easiest way to create templates is using the 'CreateTemplate' special page (see above).」

• 新增表單請記得新增表單之前須先建立對應的樣板，而新增語意(semantic)性質、新增樣板、新增表單僅限用於新增所對應的項目，而不能用於編輯已有的項目。 「原文： Create forms. Now you can create forms to allow users to easily add and edit pages of various types. There should be one form per page type; a form should populate the template or templates that this page type contains. As before, there's a special page to create new forms: 'CreateForm' (see above). See below for documentation on the special markup language used to define forms. One common request is for these three special pages ('CreateProperty', 'CreateTemplate' and 'CreateForm') to be able to edit existing property/template/form pages, and not just create new ones. However, this is programatically much harder to implement than creating new pages, because it requires parsing. For the foreseeable future, modifying existing properties, templates and forms will have to be done by hand.」

• 新增分類(Category)，此一分類與「是否能以語意表單新增頁面」乙事有所關連。您能以新增分類(Category)此一工具，一舉完成所需之相關設定。 「原文：Create categories. One template in each form should define each article that the form creates as being part of a certain category. You should create a page for each such category, and specify a default form for it so that every article is automatically editable with the same form that created it. The easiest way to do that is using the 'CreateCategory' special page (see above).」

• 製作使用表單的連結一旦您完成了您的表單，別忘了貼心的為其他使用者製作使用此表單的連結。 「原文：Enable links to forms.Besides creating categories that have a default form, there are other steps you should take to enable users to access the forms that you have created. These include adding links to add data in the sidebar and elsewhere, and setting default forms and alternate forms on properties, to have red-links to nonexistent pages point to a form for creating them. These actions are all explained further below.」

• 新增資料：使用您建立好的表單新增資料。 「原文：Add data. You should also add data to the site, using your new forms, to make sure that forms, templates and categories are working the way you want them to.」

• 製作導航列上(或其他)的連結：請參考修改MediaWiki:Sidebar此頁。 「原文：Add links on sidebar and elsewhere. The sidebar (which, for English-language wikis, can be edited at the page "MediaWiki:Sidebar") should hold links to add each of the data types, and to the categories for each of these data types as well. You can also include such links on the main page and elsewhere.」

• 客製化：依您的喜好去修整於上述步驟中所產出樣板及表單。 「原文：Customize. Once the structure is in place, you can customize all you want - changing the look-and-feel of the entire wiki, of the various templates, and of the forms, adding and changing fields and adding and changing inline queries for queries.」

如您想獲取更多的參考資訊，請參見example此頁。

 「原文：To see this process in action, see the example of how these steps would be followed for an actual wiki.」

[edit] 表單標記語言

表單係以一組指定樣板及表單的標記(tags)，而維基語法及部份的HTML語法亦可隨意的置入上述的標記外部；而允許使用的標記如下： 「原文：Forms are defined using a set of tags that specify templates and fields within those templates. Wiki-text, and some HTML, can be freely embedded anywhere outside of the tags. The allowed tags are:」

• info - 放置有關此表單的說明文字的地方，惟使用時須注意，須將此說明資訊置於表單上方，而適用的性質如下： 「原文：Holds special information about the form. This tag is optional, but should be placed at the top of the form if it is present. Allowed parameters of this tag are:」
  • partial form - 宣告此表單為局部表單(或部分欄位表單)，詳見 "局部表單"。 「原文：Indicates that this form is a partial form; see "Partial forms", below.」
  • add title=title - 設定該表單在新增頁面頁面中的名稱。 「原文：Sets the title for the 'AddData' page that uses this form definition」
  • edit title=title - 設定此表單在編輯資料頁面中的名稱。 「原文：Sets the title for the 'EditData' page that uses this form definition」

• • page name=formula - 設定公式以作為新增頁面時的頁面名稱設定，請參見下方的#單一步驟程序一節。 「原文：Sets a formula for automatic setting of the name of the page being added; see "The one-step process", below.」

• for template - 指定此一表單所對應的樣板為何。可應用於此標記的相關配套標記如下： 「原文：Specifies a template name, and declares that all of the following fields (until end template is reached) will be those of this template. The name immediately following the for template declaration is the name of the template. Allowed parameters of this tag are:」
  • label=標籤文字 - 用以標示此組表單外圍的標籤。 「原文：Specifies a label to be placed in a square around the entire set of this template's fields in the form.」
  • multiple - 此一標記可使該組表單可多次使用於指定的頁面上。「原文：Specifies that the user can change the number of instances of this template in the form, allowing multiple (or zero) occurrences; see "Multiple values for the same field", below.」
  • chooser=下拉選單名稱 - 類似multiple的功能，但是卻是使用下拉式選單來引用表單。 「原文：Similar to multiple, but allows for a single dropdown input in the form to add instances of each template labelled as chooser, instead of each such template requiring its own 'Add' button.」
  • chooser caption - 您可以此一標記在上述的下拉式選單中來描述介紹此表單中的欄位集合。 「原文：Sets the caption in the form's dropdown for adding instances of this template; must be set in conjunction with chooser option.」
  • strict - 此項目用以指定表單中的欄位，只有在與樣板中的欄位相符合時，才可轉換為表單元件。 「原文：Specifies that only fields in the form that correspond to fields used by the template should get turned into form elements.」

• end template - 說明該項對應樣板的範圍到此結束。 「原文：Ends the range of a template. There are no properties for this tag.」

• field - 指定某欄位置於該表單中，其可以是樣板內的欄位、頁面名稱或是隨意文字區(Free text)，該欄位名稱須緊緊跟著field適用於此標記的相關標記如下： 「原文： Specifies a field to be placed in a form. It can be either a template field or, if it's the page title or free text field, standalone. The name immediately following the field declaration is the name of the field. Allowed parameters of this tag are:」
  • input type=輸入型態 - 用以指定像是text, textarea, date, datetime, datetime with timezone, radiobutton, checkbox, listbox and checkboxes等等的型態。預設值與該欄位對應的語意性質所用的型態為何。 「原文：Specifies the type of input this field will have in the form: allowed values are text, textarea, date, datetime, datetime with timezone, radiobutton, checkbox, listbox and checkboxes. If a field corresponds to a semantic property, the form will usually have the correct input type by default; otherwise the default is text.」
  • size=尺寸 - 用以指定(文字)欄位寬度。 「原文：Used for text entries. Specifies the width of the text entry.」
  • rows=欄位行數(高度) - 使用於文字區塊(多行文字)欄位。 「原文：Used for textarea entries. Specifies the number of rows.」
  • cols=欄位寬度 - 使用於文字區塊(多行文字)欄位。 「原文：Used for textarea entries. Specifies the number of columns.」
  • mandatory - 指定某一欄位不得為空白(必填之欄位)，依譯者的經驗，指定太多了會使整個表單提交時失效。 「原文：Specifies that this field must be filled in by the user.」
  • hidden - 指定此欄位為隱藏欄位。 「原文：Specifies that this field will be hidden in the form: used to preserve values in edited pages.」
  • restricted - 此項目用以指定某欄位內資料僅有系統管理員(admins/sysops)擁有修改權。 「原文：Specifies that this field will be editable only by admins/sysops and disabled for all other users.」
  • autocomplete - 設定此欄位的內容可自動填入前人曾輸入過的值的，此參數僅可用於"String"型態的資料欄位。 「原文：Specifies that this field will be autocompleted based on previous values entered for the semantic property that it covers. This declaration is not necessary for fields that handle properties of type "Page", since this kind of autocompletion happens for them by default. In practice, this parameter only makes sense for fields of type "String".」
  • autocomplete on=分類名稱(category name) - 用以指定文字欄位，此欄將會將某些頁面名稱自動填入該欄位，那些頁面名稱皆屬所指定的分類(及子分類)項下的頁面， Autocompletion 預設值為欄位對應之性質為頁面型態的欄位，若無指定分類名稱，則autocomplete on 的設定將無效。 「原文：Used for text entries. Specifies that there should be Javascript "autocompletion" on this input, using a list of the pages within the specified category (and all its subcategories). Autocompletion is on by default for fields that correspond to "Page" properties; if autocomplete on is included but category name is left blank, autocompletion is disabled.」
  • autocomplete on namespace=namespace name - 有點相似autocomplete on=，但自動填入值，預設為該名字空間項下的頁面名稱。 「原文：Similar to autocomplete on=, but gets all the pages that belong to a certain namespace.」
  • default=預設值 - 為某欄位指定預設值，當欄位為日期屬性時，設定default=now，可使該欄自動填入今天日期。 「原文：Specifies a default value for this field. For date-related fields, default=now will set the value to the current date and possibly time.」
  • preload=頁面名稱 - 將一指定的頁面中 的值載入到隨意文字區(Free text)欄位。 「原文：Specifies a page whose contents should be preloaded into this field (used only for free text field).」
  • list - Specifies that this field contains a list of values; used for autocompletion.
  • delimiter=分隔符號 - 指定使用某一符號做為多值欄位的分隔符號，預設值為半型的逗號「,」。 「原文：Specifies the delimiter character or string this field should use, if it represents a list of values; the default is ", ".」
  • class=樣式名稱 - 指定某CSS樣式應用於此欄位。 「原文：Specifies a CSS class that the input for this field should have.」

另有兩個較為特別的欄位可置於任何的表單內，而與任何的樣板無關。 「原文：There are two special fields a form can contain that are not part of any templates:」

• page title - 非表單元件。Not a form element, but is translated into a text string of the title of the page being created or edited.
• free text - 此為文字區塊欄位，頁面中凡有不屬於任何樣板可對應到的欄位資料，皆將送至此欄位中，此欄位適用的標記如下：rows, cols, hidden, restricted and preload。 「原文：textarea that holds all the text on the page that does not fit into any of the templates specified in the form. Allowed properties for this field are rows, cols, hidden, restricted and preload.」

• choosers - Specifies the input for selecting the 'chooser' fields (see above), if any, for this form. This tag should appear no more than once, if at all, in a form.

• standard input - 略。 「原文：One of seven inputs that, by default, appear at the bottom of every form. The text immediately after "standard input|" is the name of this input - the six allowed values are "save" (for the "Save page" button"), "preview" (for the "Show preview" button), "changes" (for the "Show changes" button), "summary" (for the "Summary" text field), "minor edit" (for the "This is a minor edit" checkbox), "watch" (for the "Watch this page" checkbox) and "cancel" (for the "Cancel" link). Additional parameters that can be set for this tag are:」
  • label=標籤名稱 - 作為輸入欄位的標籤 「原文：Specifies the text associated with this input on the form.」

So, for example, the button for "Save page(保存本頁)" would be specified with "{{{standard input|save}}}". If no standard input tags are included in the form definition, all six will appear at the bottom of the form, just as they do for regular "Edit" pages. However, if even one such tag is included, then only those inputs which have been included will be displayed, in the order, and with the wiki-text, that they appear in in the form definition.

[edit] 各種資料型態與其適用的輸入型態

各種語意維基資料(Semantic MediaWiki data)皆有其預設的輸入型態。在某些情之下亦有其預設之輸入框的尺寸，此外有些「多值輸入欄位」使用以某項分隔符號(如半型逗號「,」)以輸入多值，而非接受單一輸入值。(Each defined Semantic MediaWiki data type has a default input type, and in some cases a default input size as well. Additionally, some data types have special handling if the field holds a delimited list of values, instead of just a single value.)

以下是各種資料型態的預設及其他可接受的輸入型態(僅適用於單一輸入值)：Here are the defaults and the other allowed input types for each data type, for single values:

另有針對「分隔符號」的預設及其他適用的輸入型態，這是用於「多值輸入欄位」"#arraymap"上的功能。And here are the default and other allowed input types for delimited lists of a certain data type, enabled by the use of the "#arraymap" function:

[edit] 範例

以以為在Discourse DB'Item' form definition page 頁面內的原始程式碼： 「原文：Here is the source code for the 'Item' form definition page at Discourse DB:」

{{{info|add title=Add an opinion item|edit title=Edit an opinion item}}}
{{{for template|Item}}}
{| class="formtable"
! Author:
| {{{field|author|mandatory}}}
|-
! Source:
| {{{field|source|mandatory}}}
|-
! Date:
| {{{field|date}}}
|-
! URL:
| {{{field|url}}}
|-
! Quote:
| {{{field|quote|input type=textarea|}}}
|}
{{{end template}}}

{{{for template|Opinion|label=Opinions for this item|multiple}}}
'''Topic:''' {{{field|1}}}

'''Position:''' {{{field|2|size=55}}}

'''Stance:''' {{{field|3|size=10}}}
{{{end template}}}

{{{for template|Reference|label=Previous opinion items this item refers to|multiple}}}
'''Item name:''' {{{field|1|autocomplete on=Items}}}
{{{end template}}}

'''Free text:'''
{{{field|free text}}}


{{{standard input|summary}}}

{{{standard input|minor edit}}} {{{standard input|watch}}}

{{{standard input|save}}} {{{standard input|preview}}} {{{standard input|changes}}} {{{standard input|cancel}}}

注意：以上的程式碼皆是利用特殊頁面新增表單所產生的，其依據的是Item、 Opinion 及 Reference等樣板頁面。 「原文：Note the presence of wiki-text within the code. This markup was created using the Create Form page, and based around the templates Item, Opinion and Reference. You can see the working form at this add data page; the form itself is created on-the-fly from the form definition file. In the 'Items' category page, if you click on any of the pages, you can see the 'edit with form' tab on the top right-hand side. If you click on that tab, you can see this same form, this time populated with the data contained in that page.」

[edit] 新增資料

若用戶欲以表單隨意的新增頁面則須以下的方式，採二階段的步驟來完成，以防覆蓋了原來同名的既存頁面。 「原文：Adding data is usually structured as a two-step process: first the user inputs a page title, and then he/she is sent to a form for either adding or editing that page, depending on whether or not the page already exists; this ensures that users don't accidentally overwrite existing pages. However, it's also possible to skip the first step, if the form contains a formula for setting the page title based on the user input.」

[edit] 二階段步驟

此二階段步驟如下：

• 使用「forminput」的語法(parser)功能-其範例如下：Use the 'forminput' parser function - adding this tag to any page will make an input that will let the user specify a title for adding or editing. By default, this input is included in every from created by the 'CreateForm' page. Here is the generic call for the tag:

{{#forminput:表單名稱|尺寸|預設頁面名稱|按鈕標籤|查詢字串}}

例： {{#forminput:工作|20|test page|新增|namespace=任務}}

上例將以「工作」表單新增名字空間為「任務」的頁面，其預設新增頁面名稱為test page，餘略。

請參看上例 「原文：All arguments are optional. form_name is the name of the SF form to be used; if it is left empty, a dropdown will appear, letting the user choose among all existing forms. size represents the size of the text input (default is 25), and value is the starting value of the input (default is blank). button_text is the text that will appear on the "submit" button, and query_string is the set of values that you want passed in through the query string to the form.」

• 使用新增頁面-前往Special:AddPage ，則可於該頁面中輸入欲新增的頁面名稱再選擇適用的表單，即可進行該作業。 「原文：Use 'AddPage' - the user can go to /Special:AddPage; a form name can optionally be specified in the URL, so it looks like /Special:AddPage/form-name. If no form name is specified, a dropdown of all available forms in the wiki will appear next to the input for the page name, letting the user choose. (This approach is no longer recommended.)」

[edit] 新增特定名字空間項下的頁面

請參上面的例子(已包含新增特定名字空間頁面的介紹)。 「原文：You can have a page-input form create pages within a specific namespace (like 'User:') by default, without forcing users to type in that namespace every time. If you're using the 'forminput' tag, the "query_string" value should include 'namespace=namespace-name'. If you're using 'AddPage', you can do so by setting the URL to something like 」"http://mywiki.com/Special:AddPage/form-name/Namespace:namespace-name".

[edit] 新增子頁面

例： {{#forminput:工作|20|籌備會議|新增|super_page=王小明的任務}}

上例將以「工作」表單新增頁面名稱為「王小明的任務/籌備會議」的頁面，餘略。In MediaWiki, you can create sub-pages by including a slash in the page name. To have the page that's added automatically be a sub-page, you can add a value for "super_page=" in the query string. To make it a sub-page of the current page, you can set this value to "super_page=Semantic Forms/zh-hant". This will prepend a "current-page-name/" onto the beginning of the page name that the user types in.

[edit] 單一步驟程序

您可用設定「預設頁面名稱」的方式，指定表單所新增頁面的頁面名稱， 其在表單中以"info"標籤標示，其共有如下的兩種變數可以於此欄位： 「原文：You can have the name of the page created by the form be created automatically, by adding a "page name" parameter within the form definition's "info" tag. There are two types of "variables" one can include in the value for this field:」

• '<樣板名稱[欄位名稱]>' - 為特定的樣板的欄位設定特定的值。「原文：'<TemplateName[FieldName]>' gets replaced with the value for the specified field in the specified template」
• '<unique number>' - 可為該頁面標題產生最小號數的獨一編號(啟始值為1)。 「原文：'<unique number>' - gets replaced by the lowest number (starting at 1) for which the page title that's generated is unique.」

舉例來說，上面的說明可以是"page name=Opinion item by <Item[Author]> #<unique number>"這樣的設定，此舉將使每次儲存新增頁面的同時將「Author」此一欄位的內容作為該新增頁面名稱的一部份。假如「Author」此一欄位的值為"「Ernest Hemingway」則當按下「儲存頁面」按鈕時，該新增的頁面的名稱就會成為「Ernest Hemingway opinion item 1」。

 「原文：For example, the form described above could have a declaration of "page name=<Item[Author]> opinion item <unique number>". This would include the author's name in the name of every opinion item, as well as a number to guarantee the uniqueness of every opinion-item page added. A user could then go to the URL "http://discoursedb.org/wiki/Special:AddData/Item" and fill out the form; if they set the author to be "Ernest Hemingway", and no other opinion items in the wiki had him as an author, then hitting the "Save page" button would result in a new page called "Ernest Hemingway opinion item 1".」

注意：以上的作法的前提是需將新增頁面提交至"Special:AddData/form-name"，如果是提交至一般表單頁面或"Special:AddPage"，則會要求您輸出頁面名稱。餘略。 「原文：Note that users must be sent to the page "Special:AddData/form-name" for this automatic page-setting to work; if they go instead to the regular form page, or to "Special:AddPage", they will be prompted for a page name, which will override whatever the automatic page name would be. (Though it should be noted that you can also change the form page to link to "Special:AddData/form-name", in place of having the #forminput input, which might eliminate some confusion for users.)」

[edit] 預載資料

您可以如下的方式來設定表單預載特定的內容至特定欄位。 「原文：You may want a form to already contain some data when the user goes to it. (Note that this only applies to adding new data; for editing an existing page, there is no way to set the contents of the form to anything other than the current contents of that page.) There are various ways to do this:」

• 為某欄位指定"default"(預設)值。 「原文：Specify a "default" value for whatever fields you want to have a value for in the form.」
• 查詢字串項目若設"preload"項目時，其效力僅及於「隨意文字區(free text)」欄位的內容。 「原文：Specify a "preload" page for the "free text" field, which will preload the free text field with the contents of that page.」
• 增加preload=預載頁面名稱至表單內的查詢字串值 「原文：

Add preload=preload-page-name to the 'query_string' value in the 'forminput' call; this will preload the entire form with the contents of that page.」

• Similarly, you can add a "preload=..." value to the query string for an 'AddPage' or 'AddData' URL.
• 將查詢字串項目設定為"樣板名稱[欄位名稱]=欄位值"時，可將指定的值填入指定的欄位。

Add "template-name[field-name]=field-value" to the 'query_string' value in the 'forminput' call, to set the value for a specific field.

• Similarly, you can add a value for a specific field to the URL query string for 'AddPage' or 'AddData'.

[edit] 於某欄位內輸入多重數值

There may be fields for which you want the user to be able to enter multiple values. There are two ways to do this:

• The standard way - you can allow users to put all the values in one field, separated by commas or some other string. To do this, the template should contain the Semantic Forms parser function '#arraymap', which applies a mapping on each section of a delimited string. If you have a form that populates the field 'author', and you want the values for that field to be separated by commas and to each get the semantic property 'Has author', you could add the following to the template code, in place of a regular semantic tag:

{{#arraymap:{{{author}}}|,|x|[[Has author::x]]}}

Essentially this function 'maps' the relation tag onto each comma-delimited value in the field. The user can thus enter all the values on the same line, with or without spaces around the commas. Note, by the way, that the "x" is used here as an internal variable: if the attribute/relation/property name itself contains the letter "x", that will lead to problems, and you should replace the letter "x" with some character or string that does not appear in it.

If you use the 'CreateTemplate' page to create a template, an option exists to let you automatically enter this parser function in the template for any field that can take more than one value.

If each of these values is part of an enumerated list, then by default the form will display a set of checkboxes for this field, letting the user select which combination of the allowed values the field should take. If there is no set of allowed values, the form will display a text entry that lets the user add values through multiple-value autocompletion.

• A multiple-instance template - create a template for just that field, and then include the new template in the form, with a 'multiple' property. The example above, for the 'Item' form, contains two such templates (although only one is for a single field). If you look at the form that this definition generates, you can see that there are two buttons labelled 'Add another'. Clicking on either of these will create a new instance of that template and its field(s). The user can add and remove such instances to match the number of values they want to have for each field.

The 'standard' way is the recommended one. You can use a multiple-instance template instead if you wish to separate out this field from the main template for the page.

[edit] 「以表單進行編輯」標籤

有兩個方法可以在特定的頁面產生「以表單進行編輯」的標籤 (Tab)。第一個，也是建議的方式，使用 categories。要讓頁面有這個標籤，你必須先定義該頁面是屬於某個特定的分類 (category) - categories are the standard Semantic MediaWiki approach to defining a page's type. The best way to match pages with a category is to place a 'Category' tag inside the main template that defines this page type; that way, every page that uses this template will become part of this category.

Once you have done that, you should place the semantic property 'Has default form' in the page for that category; the tag should look like [[Has default form::Form:form-name]]. You can do this automatically if you create the category using the 'CreateCategory' page.

As an example of this approach, see the "Magazine" template source code on Discourse DB, which defines any page that includes it to be of category "Magazines"; then the "Magazines" category source code, which specifies the "Magazine" form as the default form for this category. Then, see the page for Newsweek magazine, which uses the "Magazine" template, and thus belongs to category "Magazines", and thus gets an "edit with form" tab at the top; this tab then links to editing with the "Magazine" form. And there you have it.

The second possible way is to match the pages' namespace to a form. You can do that by placing a 'Has default form' property in the page defining that namespace. If, for instance, your wiki is called 'MyWiki', and the namespace you want to associate with a form is 'User', the page in which you need to add the property will probably be called 'MyWiki:User' (you may need to create this page). If the namespace you want a default form for is the main one (i.e., the one with no name, you will need to create and add this property to the page called 'MyWiki:Main', or whatever the main namespace is called in the language of this wiki. Once you've added this property, every page within that namespace will have that form associated with it, unless it already belongs to a category that has an associated form (categories take precedence over namespaces).

[edit] 設定編輯標籤

For pages that have an "edit with form" tab, you may want the regular "edit" tab to be renamed or even removed altogether. There are flags you can set in "SF_Settings.php" to change the appearance of the editing tabs:

• $sfgRenameEditTabs - renames the "edit with form" tab to "edit", and the "edit" tab to "edit source" (in whatever language the wiki is being viewed in)
• $wgGroupPermissions[...]['viewedittab'] - can be set, for different types of viewers, to toggle whether each type will see the regular edit tab. One common modification is to set it to false normally (i.e. for viewer type '*'), and to true for 'sysop' viewers.

[edit] 以「新增資料」表單來處理紅色連結

在MediaWiki 中一個尚未存在的頁面稱為「紅色連結」，因為它們的連結常以紅色來顯示，只要這些連結頁面為語意維基的某項「性質」的資料，則您就可以指定以「新增資料」表單來進行新增頁面的資料編輯作業。 「原文：On MediaWiki, links to nonexistent pages are called 'red links', because they are usually colored red. By default, these links go to a page for adding this article to the wiki using the standard edit form. However, if such an article is the object of a semantic property, it's possible to get such a link to point to the correct Semantic Forms 'add data' form instead.」

所需的一至三項配套作法：This is done in one to three parts:

• 如果您的MediaWiki版本早於1.13，您必須小幅修改MediaWiki 的程式碼，您可以在這裡 找到所需變更的程式碼。 「原文：if your version of MediaWiki is older than 1.13, you must make a small modification to a file in the main MediaWiki code - the code change can be found here.」

• 您可於某關聯/性質(property)頁面新增「預設表單」(參見 「以表單進行編輯」標籤)，以使得爾後得以使用指定的表單來編輯因關聯/性質項目而新增的頁面。 「原文：you can add the semantic property 'Has default form' (see "The 'edit with form' tab") to the page for the property that such an article is the object of.」

• 如果該關聯/性質(property)頁面使用不只一種表單(例如某些頁面可使用不同的表單來新增頁面)，您可以另增「代用表單」至該頁面，則用戶可於新增頁面時多了些選擇。 「原文：if it's possible for a property to point to more than one kind of page (i.e., pages that should be created with different forms), you can also add one or more 'Has alternate form' properties to that page, so that the user gets other possibilities when they click on the red link.」

您可為關聯/性質(property)設定「預設表單」或「代用表單」其中一項(或兩者兼用)。 「原文：You can set either a default form, or alternate forms, or both, for a property.」

範例介紹(略) As an example, see this page. Both the author and the source are red-linked, but the links take you to forms for adding these two pages (please do not actually fill out and submit these forms, because that would ruin the example). When you get to the forms for each page, you can see, at the top, that there are alternative forms that you can select for adding each page. That is enabled by 'Has default form' and 'Has alternate form' properties in the pages for both the properties 'Was written by' and 'Was published by' (they are referred to here as "relations" instead of properties, because Discourse DB still uses an old version of Semantic MediaWiki, but the concept is the same).

如果您已修改了MediaWiki的程式碼，且您已定義了某名字空間指定使用某表單，則即可使用指定的表單以新增該名字空間項下的頁面。 「原文：Note also that, if you've made that MediaWiki code change, and you've defined a namespace as having a default form, red-links that go to a page within that namespace will also go to the right 'add data' form, without any extra work needed.」

如果以上的設定仍無法使您順利的使用指定的表單來新增頁面，則不妨清除快取。參見此處。 「原文：Sometimes, when a page with red links is first created, the red links will point (incorrectly) to the standard edit URL, and not to the form URL; the correct URL will only appear at some point later. That happens because of caching on the wiki. You can very easily disable caching, if you want to get around this problem; see the instructions here.」

[edit] 將表單改的頁籤片段

如果您認為使用表單過於冗長時，您可改用頁籤(tab)界面以導航於其中(此作法須另使用Header Tabs套件)。使用時只要在欲呈現頁籤處新增一上層片段(section)例如"=第一段="，並在表單的底部增加"<headertabs/>" 標籤即可，此方法不可用於將單一的樣板拆為兩段。但您可將單一的大型樣板，事先改為兩個以上的小型樣板的方式來達成同樣目的。您可參考此範例; 「原文：If you think a form is too long for users to fill out comfortably, you can turn into sections, with a tab interface to navigate between them, using the Header Tabs extension. If you install this extension, it is very easy to add tabs to a form: just add a top-level section wherever you want a tab to appear, of the form "=Tab 1="; and then add the tag "<headertabs/>" near the bottom of the form, right above the "standard input" declarations. Note that you can't split up a single template between two tabs; if you think a single template is too long to be filled out in one screen, consider splitting up that template into two or more templates; each template can then be put into a different tab. You can see a simple example of a form in tabbed sections here; the form definition used to create it is here.

Such tabs can also be used, in a similar way, to display data pages themselves.」

[edit] 定義新輸入項目

You can use hooks to define inputs, for either a new input type and a new semantic type; see Defining new inputs.

[edit] 局部表單

您可以在某個表單的{{{info}}} 參數內部增加"partial form"的方式，來指定該表單為局部表單(partial form)。此舉將使得該表單的編輯範圍僅能涵蓋其所包含單一或多重樣板內容，而無法編輯在前述樣板之前及之後的樣板。我們不建議您將局部表單應用在指定分類(category)及名字空間(namespace)的用途上，其宜應用於已存在頁面之編輯作業上。您能查看局部表單內容的範例內容的範例, 及使用範例 使用範例(須點選"Add or change this opinion item's references"的超連結) 「原文：You can specify a form to be a partial form by adding the property "partial form" to its {{{info}}} tag. This will make the form cover only the single or multiple templates that it contains, and not modify any part of the page before or after these templates. A partial form is not recommended as a default form for a category or namespace, but rather as a tool to modify parts of pages after they have already been created. You can see an example of a partial form here, and you can see it in action here, by clicking on the link reading "Add or change this opinion item's references".」

[edit] 建立行事曆

您也可以使用本套件配合DPL Calendar來製作您所需的行事曆。 「原文：If you want to set up a calendar in which users can add and edit events using Semantic Forms, you can do that fairly easily using the DPL Calendar extension in conjunction with SF; see Creating calendars using DPL Calendar.」

[edit] 常見問題

[edit] MediaWiki相關問題

• If you've just set up your wiki and you want the URL of every page to look shorter and more like Wikipedia's, this short URL page explains how.

• If a template contains section headings (like "==Section 1=="), when the template is displayed on a page each section heading will have its own "Edit" link. Such links are not desirable, since they will take the user to editing the template, rather than the actual page in question. The easiest way to avoid this problem is to place the string "__NOEDITSECTION__" anywhere within that template; this will remove all section-edit links from any page that contains that template.

[edit] Semantic MediaWiki相關問題

• If you get an error on any page reading something like "Table 'smw_relations' doesn't exist" or "Table 'smw_attributes' doesn't exist", it means you haven't installed, or haven't finished installing, the Semantic MediaWiki extension. If you've set up the SMW code and added the right lines to LocalSettings.php, probably all you need to do is create the new semantic database tables - go to 'Special:SMWAdmin' and press the button.

• To get rid of the semantic "factbox" that appears at the bottom of most pages, add the following line to your 'LocalSettings.php' file: "$smwgShowFactbox = SMW_FACTBOX_HIDDEN;"

• To get rid of the "error" image that appears for property values that are supposedly incorrect, add the following line to your 'LocalSettings.php' file: "$smwgInlineErrors = false;"

• There is currently a bug in SMW, in which properties of type "Page" that are enumerations have only their first value recognized, generating strange-looking error messages like "'Blue' is not in the list of possible values (Red, Blue, Yellow) for this property." Until this is fixed, you can easily fix it yourself in the code: add the line "$this->m_dbkeyform = NULL;" to the file "/includes/SMW_DV_WikiPage.php" in SMW's directory, right under the line which reads "$this->m_title = NULL;" (which should be line 28).

[edit] Semantic Forms相關問題

• You can change the way dates are outputted by the forms by adding the line "$wgAmericanDates = true;" to the main MediaWiki LocalSettings.php file. By default, dates are printed out as "2007/06/20"; making this change will set dates to instead be printed out as "June 20, 2007" (with the month name dependent on the language of the wiki).

• If a page (which we'll call Page A) gets transcluded in another page (which we'll call Page B), and Page A belongs to a category that's associated with a form, it can have the unfortunate side effect of making Page B a member of that category as well, thus giving Page B an "edit with form" tab at the top, even if such a tab is not appropriate. You can solve this problem by putting the category declaration in Page A within a "<noinclude>" block, which will make Page A a member of that category but not Page B.

• 如果您的網站係由SMW 0.7 (或更早的版本) 昇級至 SMW 1.0，則別忘了在「性質:預設表單」、「性質:設有表單」及「property:Has default form」頁面設定[[設有型態::頁面]]或[[Has type::Page]]。 「原文：If you are upgrading your site from SMW 0.7 (or an earlier version) to SMW 1.0, and you have the property "Has default form" defined, make sure that you add to it the type declaration "[[Has type::Page]]".」

• 本套件已自0.9版起由原先的使用HTML語法，改為使用維基語法，故當您把本套件自舊版升級至0.9版(含以後)時，表單會出現問題。

If you upgraded your copy of Semantic Forms from one before 0.9 to any afterwards, you may see strange formatting in some or all of your forms; that is because wiki-text parsing was added in version 0.9. You should be able to get rid of the formatting problems in two steps: remove the spaces from the beginning of every line in the form definition, and replace the line that looks like "<fieldset><legend>Description of magazine</legend>", plus the closing "</fieldset>" tag (and any other lines that look like that) with something like "'''Free text:'''"; for some reason, the MediaWiki parser does not like the "fieldset" and "legend" HTML tags. You can also disable wiki-text parsing instead; see the next item.

• If you click on the "edit with form" tab for a page and you get a message reading "Error: No form page was found at..", but the form does in fact exist, that is due to a bug in old versions of SMW 1.0. You should upgrade to the latest version of SMW, then re-save the page of any category that has a "Has default form" call linking to such a form; make sure that you make a small change to the category page first, or else it won't really be re-saved.

• There is currently no way to allow users to upload images through a form. If you want to make an image one of the elements in the page that the form creates, the easiest way is to have the form tell users to upload the image separately (you can even have the form link directly to the "Special:Upload" page), then to place the image name in the appropriate field in the form. See here for an example (in the "Logo:" field). You can also add "autocomplete on namespace=Image" as a parameter to that field in the form definition, so that users don't have to type in the full file name.

• Semantic Forms only handles forms for adding and editing data in wiki pages. You may want forms for other purposes: fortunately, there are other form extensions you can use. EmailForm allows you to create forms for emailing data, and Simple Forms allows you to create generic forms for a variety of purposes. See also the MediaWiki forms manual for other such extensions.

[edit] 資料設計相關問題

• 如果某頁面設有相關的兩個語意性質(semantic property)且連結至兩項分類（categories)，且此兩分類有父子關係結構，舉例來說像是您可在「紐約」的頁面內設定[[所在國家::美國]]或在「美國」頁面內設定[[包含城市::紐約]]，則建議該頁面僅需在「紐約」的頁面內設定[[Category:美國的城市]]的分類即可，這樣的做法有兩個主要理由：
  1. 此舉確保每個父子相關係結構分類的子分類歸類於為某父分類項下。
  2. 其使得autocomplete on=分類名稱的設定更為可靠實用。 「原文：When creating a semantic property connecting any two "classes", or pages represented by different categories, you may be unsure about which way to point the property. Usually such relationships will be of the one-to-many variety, also known as parent-child relationships, in which each page of type A has a relationship to any number of pages of type B, while each page of type B always has a relationship to exactly one page of type A. An example is countries and cities: a country can have many cities, but a city always belongs to exactly one country. In such a case, you may not know whether it should be country pages that have a "Has city" property, or city pages that have a "Belongs to country" property, or even whether both properties should exist. In this kind of situation, it is recommended that you specify the relationship only from the child to the parent, i.e. use a "Belongs to country" property for cities and not the other way around. This is for two reasons: first, it lets you guarantee the rule that every child has exactly one parent, by setting this property through a field within the child's main template; and second, it makes page-name autocompletion more reliable, since parent pages are usually created before their children's pages are.」

• You may not be sure about whether to create one form or many for a set of related page types. For instance, in a wiki about restaurants, should you have a separate form/template/category set for regular restaurants, fast-food restaurants, diners etc., or a single form called "Restaurant", with a corresponding single template and category, that just uses a field to indicate the type of restaurant it is? A good rule of thumb is to look at the set of data that you want to be entered and displayed for each type of page. If it's the same across all the types, then you could probably use a single form/template/category set for all of them. However, if there's even one difference in the set of fields being displayed for any page type, then it probably makes sense to give such a page type its own form, template and category.

[edit] 使用本套件的網站

請參考這裡

[edit] Mailing list

The mailing list for Semantic Forms is on Google Groups, at http://groups.google.com/group/semantic-forms. The list is intended for announcements, discussions about the functionality, ideas for new features, and bug reports. You must be a member to post.

[edit] Contributing to the project

[edit] Bugs and feature requests

You can submit bug reports and requests for new features at MediaWiki's Bugzilla, here.

The current list of known bugs and requested features for Semantic Forms can be found here.

[edit] Contributing patches to the project

If you found some bug and fixed it, or if you wrote code for a new feature, please create a patch by going to the main "SemanticForms" directory, and typing:

svn diff >descriptivename.patch

Then go to the relevant bug report in Bugzilla, or create one if one doesn't exist (note, again, that Bugzilla is used for both bugs and feature requests), and attach this patch file to it.

If, for any reason, you don't wish to use Bugzilla, feel free to simply send this patch, with a description, to the Semantic Forms mailing list.

[edit] 翻譯

Translation of Semantic Forms is done through Betawiki. The translation for this extension can be found here. To add language values or change existing ones, you should create an account on Betawiki, then request permission from the administrators to translate a certain language or languages on this page (this is a very simple process). Once you have permission for a given language, you can log in and add or edit whatever messages you want to in that language.

[edit] 捐獻

Semantic Forms was created and is developed on a strictly volunteer basis, with no funding whatsoever; all donations are welcome. You can also use donations to "fund" the development of a specific feature you would like to see added to Semantic Forms; to do that, please contact Yaron or the mailing list about it first. You can donate to the project here.

[edit] 參見

[edit] See also

• Simple Forms
• Semantic MediaWiki

Languages:

English  • ‪中文(繁體)‬