system.xml リファレンス
- トピック:
- 設定
作成対象:
- 経験者
- 管理者
- 開発者
system.xml
ファイルを使用すると、Commerce システム設定を管理できます。 このトピックは、system.xml
ファイルの一般的なリファレンスとして使用します。 system.xml
ファイルは、特定のCommerce 2 拡張子の etc/adminhtml/system.xml
の下にあります。
次のコードスニペットは、ファイルのむき出しのスケルトンを示しています。
<?xml version="1.0" ?>
<config xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="urn:magento:module:Magento_Config:etc/system_file.xsd">
<system>
<!-- PLACE YOUR MODULE SPECIFIC CONFIGURATION HERE -->
</system>
</config>
bin/magento dev:urn-catalog:generate [--ide IDE] [--] <path>
を実行できます。タブ // セクション // グループ // フィールド
system.xml
ファイルでは、互いに関連する 4 つの異なるタイプのエンティティを定義できます。 次の節では、タブ、セクション、グループ、フィールドの関係について説明します。 次のスクリーンショットは、Admin バックエンドのCommerce 2 システム設定を示しています。
赤い四角形は、system.xml
ファイルで定義されている様々なタイプを示しています。
タブは、様々な設定領域を意味的に分割するために使用されます。 各タブには 1 つ以上のセクションを含めることができ、サブメニューとして参照することもできます。 セクションには 1 つ以上のグループが含まれます。
各グループには、1 つ以上のフィールドが一覧表示されます。 グループを使用して、次のフィールドの一般的な説明を追加することもできます。 前述のように、各グループには 1 つ以上のフィールドを含めることができます。 フィールドは最小のエンティティです
システム設定コンテキストで上書きできます。
タブ
<tab>
タグは、システム設定の既存または新しいタブを参照します。
タブ属性リファレンス
<tab>
タグには、次の属性を含めることができます。
属性 | 説明 | タイプ | 必須 |
---|---|---|---|
id | セクションを参照するために使用する識別子を定義します。 | typeId | 必須 |
translate | 翻訳可能にするフィールドを定義します。 ラベルを翻訳可能にする label を指定します。 | string | optional |
sortOrder | セクションの並べ替え順を定義します。 数値が大きい場合はセクションがページの下部にプッシュされ、数値が小さい場合はセクションが上部にプッシュされます。 | float | optional |
class | 定義済みの CSS クラスを、レンダリングされたタブHTML要素に追加します。 | string | optional |
タブノードのリファレンス
<tab>
-Tag は次の子を持つことができます。
ノード | 説明 | タイプ |
---|---|---|
label | フロントエンドに表示されるラベルを定義します。 | string |
例:タブの作成
次のコードスニペットは、サンプルデータを使用して新しいタブを作成する方法を示しています。
<?xml version="1.0" ?>
<config xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="urn:magento:module:Magento_Config:etc/system_file.xsd">
<system>
<tab id="A_UNIQUE_ID" translate="label" class="a-custom-css-class-to-style-this-tab" sortOrder="10">
<label>A meaningful label</label>
</tab>
</system>
</config>
上記のスニペットは、識別子が A_UNIQUE_ID
の新しいタブを作成します。 translate
属性が定義され、ラベルを参照すると、label
ノードが翻訳可能になります。 レンダリングプロセス中に、CSS クラス a-custom-css-class-to-style-this-tab
がこのタブ用に作成されたHTML要素に適用されます。
値が 10
の sortOrder
属性は、レンダリング時のすべてのタブのリスト内のタブの位置を定義します。
セクション
<section>
タグは、システム設定の既存または新しいセクションを参照します。
セクション属性リファレンス
<section>
タグには、次の属性を含めることができます。
id
typeId
translate
label
を指定します。string
type
text
です。string
sortOrder
float
showInDefault
1
を指定してセクションを表示し、0
を指定してセクションを非表示にします。int
showInStore
1
を指定してセクションを表示し、0
を指定してセクションを非表示にします。int
showInWebsite
1
を指定してセクションを表示し、0
を指定してセクションを非表示にします。int
canRestore
int
advanced
bool
extends
string
断面ノード リファレンス
<section>
タグには、次の子を含めることができます。
label
string
class
string
tab
typeTabId
header_css
string
resource
typeAclResourceId
group
typeGroup
frontend_model
typeModel
include
system_include.xsd
互換ファイルを含めるために使用されます。 通常、大きな system.xml
ファイルを構造化するために使用します。includeType
例:セクションを作成してタブに割り当てる
次のコードスニペットは、新しいセクションを作成する際の基本的な使用方法を示しています。
<?xml version="1.0" ?>
<config xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="urn:magento:module:Magento_Config:etc/system_file.xsd">
<system>
<tab id="A_UNIQUE_ID" translate="label" class="a-custom-css-class-to-style-this-tab" sortOrder="10">
<label>A meaningful label</label>
</tab>
<section id="A_UNIQUE_SECTION_ID" showInDefault="1" showInWebsite="0" showInStore="1" sortOrder="10" translate="label">
<label>A meaningful section label</label>
<tab>A_UNIQUE_ID</tab>
<resource>VENDOR_MODULE::path_to_the_acl_resource</resource>
</section>
</system>
</config>
上記の節では、ID A_UNIQUE_SECTION_ID
を定義します。この ID は、デフォルトの設定表示およびストアコンテキストに表示されます。 label
ノードは翻訳可能です。 セクションは、ID が A_UNIQUE_ID
のタブに関連付けられています。 セクションは、ACL VENDOR_MODULE::path_to_the_acl_resource
で権限が定義されているユーザーのみがアクセスできます。
グループ
<group>
-Tag は、フィールドをグループ化するために使用されます。
グループ属性参照
<group>
タグには、次の属性を含めることができます。
id
typeId
translate
label
を指定します。 複数のフィールドはスペースで区切る必要があります。string
type
text
です。string
sortOrder
float
showInDefault
1
を指定し、グループを非表示にする場合は 0
を指定します。int
showInStore
1
を指定し、グループを非表示にする場合は 0
を指定します。int
showInWebsite
1
を指定し、グループを非表示にする場合は 0
を指定します。int
canRestore
int
advanced
bool
extends
string
グループノード参照
<group>
タグには、次の子を含めることができます。
label
string
fieldset_css
string
frontend_model
typeModel
clone_model
typeModel
clone_fields
int
help_url
typeUrl
more_url
typeUrl
demo_link
typeUrl
comment
<![CDATA[//]]>
て適用することができます。string
hide_in_single_store_mode
1
はグループを非表示にし、0
はグループを表示します。int
field
field
group
unbounded
depends
1
の場合にのみ特定のフィールドやグループを表示するために使用されます。 このノードには section/group/field
文字列が必要です。depends
attribute
attribute
include
system_include.xsd
互換ファイルを含めるために使用されます。 通常、大きな system.xml
ファイルを構造化するために使用します。includeType
more_url
、demo_url
、help_url
は、1 回だけ使用される PayPal フロントエンドモデルによって定義されます。 これらのノードは再利用できません。例:特定のセクションのグループを作成する
次のコードスニペットは、新しいグループを作成する際の基本的な使用方法を示しています。
<config xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="urn:magento:module:Magento_Config:etc/system_file.xsd">
<system>
<tab id="A_UNIQUE_ID" translate="label" class="a-custom-css-class-to-style-this-tab" sortOrder="10">
<label>A meaningful label</label>
</tab>
<section id="A_UNIQUE_SECTION_ID" showInDefault="1" showInWebsite="0" showInStore="1" sortOrder="10" translate="label">
<label>A meaningful section label</label>
<tab>A_UNIQUE_ID</tab>
<resource>VENDOR_MODULE::path_to_the_acl_resource</resource>
<group id="A_UNIQUE_GROUP_ID" translate="label comment" sortOrder="10" showInDefault="1" showInWebsite="0" showInStore="1">
<label>A meaningful group label</label>
<comment>An additional comment helping users to understand the effect when configuring the fields defined in this group.</comment>
<!-- Add your fields here. -->
</group>
</section>
</system>
</config>
上記のグループは ID A_UNIQUE_GROUP_ID
を定義し、デフォルトの設定ビューおよびストアコンテキストに表示されます。 label
と comment
の両方が翻訳可能としてマークされます。
フィールド
<field>
-Tag は、特定の設定値を定義するために <group>
-Tags 内で使用されます。
フィールド属性リファレンス
<field>
タグには、次の属性を含めることができます。
id
typeId
translate
label
を指定します。 複数のフィールドはスペースで区切る必要があります。string
type
text
です。string
sortOrder
float
showInDefault
1
を指定してフィールドを表示し、0
を指定してフィールドを非表示にします。int
showInStore
1
を指定してフィールドを表示し、0
を指定してフィールドを非表示にします。int
showInWebsite
1
を指定してフィールドを表示し、0
を指定してフィールドを非表示にします。int
canRestore
int
advanced
bool
extends
string
フィールドタイプの参照
<field>
-Tag は、type=""
属性に対して次の値を持つことができます。
text
textarea
select
source_model
が必要になる場合があります。 Yes/No
選択にも使用されます。 例については、Magento\Search\Model\Adminhtml\System\Config\Source\Engine
を参照してください。multiselect
select
に似ていますが、複数のオプションが有効です。button
Magento\ScheduledImportExport\Block\Adminhtml\System\Config\Clean
を参照してください。obscure
**​**
として表示されるテキストフィールド。 ブラウザーで「Inspect Element」を使用してタイプを変更しても、値は表示されません。password
obscure
と同様に、非表示の値は暗号化されず、ブラウザーで「Inspect Element」を使用して型を強制的に変更すると、値が表示される点が異なります。file
label
time
allowspecific
Magento\Shipping\Model\Config\Source\Allspecificcountries
などの source_model
が必要ですimage
note
frontend_model
が必要です。カスタムフィールドタイプを作成することもできます。 これは、アクションを含む特別なボタンが必要な場合によく行われます。 それには、次の 2 つの主な要素が必要です。
adminhtml
領域にブロックを作成するtype=""
をこのブロックへのパスに設定しています
ブロック自体には、少なくとも __construct
メソッドと getElementHtml()
メソッドが必要です。 OfflineShipping は、カスタムMagentoの簡単な例です。
例えば、OfflineShipping モジュールでは、「書き出し」ボタンは Magento\OfflineShipping\Block\Adminhtml\Form\Field\Export
で定義され、フィールドは次のように定義されます。
<field id="export" translate="label" type="Magento\OfflineShipping\Block\Adminhtml\Form\Field\Export" sortOrder="5" showInDefault="0" showInWebsite="1" showInStore="0">
<label>Export</label>
</field>
フィールドノードの参照
<field>
タグには、次の子を含めることができます。
label
string
comment
<![CDATA[//]]>
て適用することができます。string
tooltip
string
hint
frontend_model
でのみ使用可能です。string
frontend_class
string
frontend_model
typeModel
backend_model
typeModel
source_model
typeModel
config_path
typeConfigPath
validate
string
can_be_empty
type
が multiselect
の場合、フィールドを空にできるように指定するために使用します。int
if_module_enabled
typeModule
base_url
upload_dir
と組み合わせて使用します。typeUrl
upload_dir
typeUploadDir
button_url
button_url
と button_label
が指定されている場合にボタンを表示します。 通常、カスタムフロントエンドモデルと組み合わせて使用します。typeUrl
button_label
button_label
と button_url
が指定されている場合にボタンを表示します。 通常、カスタムフロントエンドモデルと組み合わせて使用します。string
more_url
typeUrl
demo_url
typeUrl
hide_in_single_store_mode
1
はグループを非表示にし、0
はグループを表示します。int
options
complexType
depends
1
の場合に、特定のフィールドやグループのみを表示するために使用されます。 このノードには section/group/field
文字列が必要です。complexType
attribute
complexType
requires
complexType
more_url
、demo_url
、requires
、options
は、別のコア支払いモデルで定義されており、1 回のみ使用されます。 これらのノードは再利用できません。例:特定のグループに 2 つのフィールドを作成する
<config xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="urn:magento:module:Magento_Config:etc/system_file.xsd">
<system>
<tab id="A_UNIQUE_ID" translate="label" class="a-custom-css-class-to-style-this-tab" sortOrder="10">
<label>A meaningful label</label>
</tab>
<section id="A_UNIQUE_SECTION_ID" showInDefault="1" showInWebsite="0" showInStore="1" sortOrder="10" translate="label">
<label>A meaningful section label</label>
<tab>A_UNIQUE_ID</tab>
<resource>VENDOR_MODULE::path_to_the_acl_resource</resource>
<group id="A_UNIQUE_GROUP_ID" translate="label" sortOrder="10" showInDefault="1" showInWebsite="0" showInStore="1">
<label>A meaningful group label</label>
<comment>An additional comment helping users to understand the effect when configuring the fields defined in this group.</comment>
<field id="A_UNIQUE_FIELD_ID" translate="label" sortOrder="10" showInDefault="0" showInWebsite="0" showInStore="1" type="select">
<label>Feature Flag Example</label>
<comment>This field is an example for a basic yes or no select.</comment>
<tooltip>Usually these kinds of fields are used to enable or disable a given feature. Other fields might be dependent to this and will only appear if this field is set to yes.</tooltip>
<source_model>Magento\Config\Model\Config\Source\Yesno</source_model>
</field>
<field id="ANOTHER_UNIQUE_FIELD_ID" translate="label" sortOrder="10" showInDefault="0" showInWebsite="0" showInStore="1" type="text">
<label>A meaningful field label</label>
<comment>A descriptive text explaining this configuration field.</comment>
<tooltip>Another possible frontend element that also can be used to describe the meaning of this field. Will be displayed as a small icon beside the field.</tooltip>
<validate>required-entry no-whitespace</validate> <!-- Field is required and must not contain any whitespace. -->
<if_module_enabled>VENDOR_MODULE</if_module_enabled>
<depends> <!-- This field will only be visible if the field with the id A_UNIQUE_FIELD_ID is set to value 1 -->
<field id="A_UNIQUE_FIELD_ID">1</field>
</depends>
</field>
</group>
</section>
</system>
</config>
上記の例では、デフォルト表示とストア表示の両方で表示可能/設定可能な 2 つのフィールドを作成します。 両方のフィールドには、ユーザーに目的を説明するためのコメントとツールチップがあります。 label
ノードは翻訳可能です。
識別子が ANOTHER_UNIQUE_FIELD_ID
のフィールドは、フ if_module_enabled
ールド内の特定のモジュールがグローバルに有効になっている場合に表示されます。 また、このフィールドでは、ルール required-entry
および no-whitespace
に対して値を検証します。
識別子 A_UNIQUE_FIELD_ID
のフィールドは、Yes
と No
の値を提供する別のソースモデルを定義します。
共通ソースモデル
次のソースモデルは、Commerce 2 コアが提供します。 一般に、さらに多くのソースモデルがあります。以下に、最も一般的なソースモデルを示します。 これらのソースモデルが正しく機能するには、フィールド属性 type
を select
に設定する必要があります。
Magento\Config\Model\Config\Source\Yesnocustom
Yes
、No
、Specified
を指定します。Magento\Config\Model\Config\Source\Enabledisable
Enable
、Disable
を指定します。 値を 0
および 1
としてデータベースに保存します。Magento\AdminNotification\Model\Config\Source\Frequency
1 Hour
、2 Hours
、6 Hours
、12 Hours
および 24 Hours
を指定します。 値は整数として保存されます。Magento\Catalog\Model\Config\Source\TimeFormat
Magento\Cron\Model\Config\Source\Frequency
Daily
、Weekly
、Monthly
を指定します。 値は、D
、W
、M
としてデータベースに保存されます。Magento\GoogleAdwords\Model\Config\Source\Language
Magento\Config\Model\Config\Source\Locale
フィールドの検証
フィールドには 1 つ以上のバリデータクラスを割り当てて、ユーザーの入力が拡張機能の要件を満たしていることを確認できます。 検証ルールは <validate>
-Tag で適用できます。
次の例では、フィールドを検証し、いくつかの異なる検証ルールを追加します。
<field id="A_CUSTOM_IDENTIFIER" showInDefault="1" showInWebsite="0" showInStore="1">
<validate>required-entry validate-clean-url no-whitespace</validate>
</field>
次の検証ルールを使用できます。
alphanumeric
integer
ipv4
ipv6
letters-only
abcABC
。letters-with-basic-punc
次の式を渡す必要があります:
/^[a-z\-.,()\u0027\u0022\s]+$/i
。mobileUK
no-marginal-whitespace
no-whitespace
phoneUK
phoneUS
required-entry
validate-no-empty
と同等の検証)。検証エラーメッセージ:「これは必須フィールドです。」
time
15
、15:05
または 15:05:48
です。time12h
3 am
、11:30 pm
、02:15:00 pm
です。validate-admin-password
validate-alphanum-with-spaces
validate-clean-url
https://www.example.com
や www.example.com
です。validate-currency-dollar
validate-data
最初の文字は文字である必要があります。
(Must match expression:
/^[A-Za-z]+[A-Za-z0-9_]+$/
)検証エラーメッセージ:「このフィールドでは文字(a ~ z または A ~ Z)、数字(0 ~ 9)またはアンダースコア(_)のみを使用してください。最初の文字は文字にする必要があります。」
validate-date-au
validate-email
validate-emailSender
validate-fax
validate-no-empty
requried-entry
と同等の検証)。検証エラーメッセージ:「空の値。」
validate-no-html-tags
validate-password
validate-phoneLax
validate-phoneStrict
validate-select
null
値、文字列値 none
、または文字列長 0 が含まれていないことを強制します。validate-ssn
validate-street
validate-url
validate-xml-identifier
validate-zip-us
vinUS
デフォルト値
フィールドのデフォルト値は、section/group/field_ID
ノードでデフォルト値を指定することで、モジュールの etc/config.xml
ファイルで設定することができます。
例:ANOTHER_UNIQUE_FIELD_ID
のデフォルト値の設定(デフォルトの範囲)
<config xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="urn:magento:module:Magento_Store:etc/config.xsd">
<default>
<A_UNIQUE_SECTION_ID>
<A_UNIQUE_GROUP_ID>
<ANOTHER_UNIQUE_FIELD_ID>This is the default value</ANOTHER_UNIQUE_FIELD_ID>
</A_UNIQUE_GROUP_ID>
</A_UNIQUE_SECTION_ID>
</default>
</config>
例:ANOTHER_UNIQUE_FIELD_ID
のデフォルト値の設定(Web サイトの範囲)
websites
タグを使用して、特定の web サイトのデフォルト値を指定します。
<config xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="urn:magento:module:Magento_Store:etc/config.xsd">
<websites>
<WEBSITE_CODE>
<A_UNIQUE_SECTION_ID>
<A_UNIQUE_GROUP_ID>
<ANOTHER_UNIQUE_FIELD_ID>This is the default value</ANOTHER_UNIQUE_FIELD_ID>
</A_UNIQUE_GROUP_ID>
</A_UNIQUE_SECTION_ID>
</WEBSITE_CODE>
</websites>
</config>