From 553d7aad4df70371508c18f8f568d8bb4a88615a Mon Sep 17 00:00:00 2001 From: Brad Bell Date: Fri, 12 Jun 2020 17:31:24 -0700 Subject: [PATCH 001/245] New translations user-profile-form.md (French) --- fr/dev/examples/user-profile-form.md | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/fr/dev/examples/user-profile-form.md b/fr/dev/examples/user-profile-form.md index a57f7c41b07..cec187ec415 100644 --- a/fr/dev/examples/user-profile-form.md +++ b/fr/dev/examples/user-profile-form.md @@ -1,6 +1,6 @@ # User Profile Form -You can create a front-end form to let users edit their profiles without granting them access to the Control Panel. To do this, you can point your form to the same controller that the Control Panel uses for its profile form. (Jump down to [Form Action](#form-action) for more about forms and controllers.) +You can create a front-end form to let users edit their profiles without granting them access to the control panel. To do this, you can point your form to the same controller that the Control Panel uses for its profile form. (Jump down to [Form Action](#form-action) for more about forms and controllers.) We’ll provide two examples: The simplest possible profile form and a full-featured profile form. @@ -224,7 +224,7 @@ Make sure the user is logged in or else the template will throw errors doing any The `
` tag does not have an `action=""` parameter on purpose. The hidden `name="action"` input tells Craft which controller and controller method to use. :::tip -The Control Panel profile form uses Craft’s [UserController::actionSaveUser()](api:craft\controllers\UsersController#method-actionsaveuser) controller and you’re free to use it on the front end too if it suits your needs. Otherwise, you can use it as inspiration to build your own controller in a custom module or plugin. +The control panel profile form uses Craft’s [UserController::actionSaveUser()](api:craft\controllers\UsersController#method-actionsaveuser) controller and you’re free to use it on the front end too if it suits your needs. Otherwise, you can use it as inspiration to build your own controller in a custom module or plugin. ::: #### Notice @@ -349,7 +349,7 @@ You’ll find styles in the [Extras](#extras) section to show and hide HTML elem ``` -That is like the Username field except for showing a message that the user should expect to verify a new email address if you’ve ticked the checkbox for “Verify email addresses?” in the Control Panel under Settings → Users → Settings. The [Current Password](#current-password) field will be required to change an email address. +That is like the Username field except for showing a message that the user should expect to verify a new email address if you’ve ticked the checkbox for “Verify email addresses?” in the control panel under Settings → Users → Settings. The [Current Password](#current-password) field will be required to change an email address. #### Password @@ -395,7 +395,7 @@ This field is required when the email address or password has changed. Otherwise Let’s say you added a custom field named “Bio” with a handle of `bio` to the user profile field layout under Settings → Users → Fields. Let’s also say it’s a required field. The difference here is that custom fields belong in a `fields` array with names like `field[]`. :::tip -Handling complex custom fields, like Matrix or third-party plugin fields, can seem complicated. You might want to view the source code of a user profile form in the Control Panel to see how to handle those types of fields. +Handling complex custom fields, like Matrix or third-party plugin fields, can seem complicated. You might want to view the source code of a user profile form in the control panel to see how to handle those types of fields. ::: #### Form Submission From 884eb733bff515359d88c16d62676e69ed8e5035 Mon Sep 17 00:00:00 2001 From: Brad Bell Date: Fri, 12 Jun 2020 17:31:26 -0700 Subject: [PATCH 002/245] New translations user-profile-form.md (Japanese) --- ja/dev/examples/user-profile-form.md | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/ja/dev/examples/user-profile-form.md b/ja/dev/examples/user-profile-form.md index e4caac62b33..8e81b2284ee 100644 --- a/ja/dev/examples/user-profile-form.md +++ b/ja/dev/examples/user-profile-form.md @@ -1,6 +1,6 @@ # ユーザープロフィールの編集フォーム -コントロールパネルへのアクセスを許可することなく、ユーザーが自身のプロフィールを編集できるようにするためのフロントエンドフォームを作成できます。これをするために、プロフィールフォームのためにコントロールパネルが使用するのと同じコントローラーにフォームを向かわせます。（フォームやコントローラーの詳細については、[フォームアクション](#form-action)に移動してください。） +You can create a front-end form to let users edit their profiles without granting them access to the control panel. To do this, you can point your form to the same controller that the Control Panel uses for its profile form. (Jump down to [Form Action](#form-action) for more about forms and controllers.) 可能な限りシンプルなプロフィールフォームとフル機能のプロフィールフォームの2つの例を紹介します。 @@ -224,7 +224,7 @@ `` タグは、意図的に `action=""` パラメータを持ちません。不可視要素の `name="action"` 項目が、どのコントローラーやコントローラーメソッドを使用するか Craft に伝えます。 :::tip -コントロールパネルのプロフィールフォームは、Craft の [UserController::actionSaveUser()](api:craft\controllers\UsersController#method-actionsaveuser) コントローラーを使用しています。あなたのニーズに適している場合、フロントエンドでも自由に使うことができます。そうでなければ、独自のモジュールやプラグインで自身のコントローラーを実装するためのインスピレーションとして使用できます。 +The control panel profile form uses Craft’s [UserController::actionSaveUser()](api:craft\controllers\UsersController#method-actionsaveuser) controller and you’re free to use it on the front end too if it suits your needs. Otherwise, you can use it as inspiration to build your own controller in a custom module or plugin. ::: #### 通知 @@ -349,7 +349,7 @@ class 名に基づく HTML 要素を表示・非表示にするためのスタ ``` -コントロールパネルの「設定 > ユーザー > 設定」で「メールアドレスを確認しますか？」のチェックボックスを ON にしている場合、ユーザーが新しいメールアドレスを確認することを期待するメッセージを表示することを除けば、ユーザー名フィールドと同様です。[現在のパスワード](#current-password)フィールドは、メールアドレスを変更するために必須です。 +That is like the Username field except for showing a message that the user should expect to verify a new email address if you’ve ticked the checkbox for “Verify email addresses?” in the control panel under Settings → Users → Settings. The [Current Password](#current-password) field will be required to change an email address. #### パスワード @@ -395,7 +395,7 @@ class 名に基づく HTML 要素を表示・非表示にするためのスタ 「設定 > ユーザー > フィールド」にあるユーザープロフィールのフィールドレイアウトで `bio` というハンドルのカスタムフィールド名 “Bio” を追加したとします。それはまた、必須のフィールドだとします。ここでの違いは、カスタムフィールドが `field[]` のような名前の配列 `fields` に属していることです。 :::tip -行列やサードパーティプラグインのような複雑なカスタムフィールドの操作は、理解しにくいと思うでしょう。それらの種類のフィールドを処理する方法を知るために、コントロールパネルでユーザープロフィールフォームのソースコードを見てください。 +Handling complex custom fields, like Matrix or third-party plugin fields, can seem complicated. You might want to view the source code of a user profile form in the control panel to see how to handle those types of fields. ::: #### フォームの送信 From 28d9288072ad0e075a80bc4024a0f8918fcfc0f5 Mon Sep 17 00:00:00 2001 From: Brad Bell Date: Fri, 12 Jun 2020 17:31:31 -0700 Subject: [PATCH 003/245] New translations eager-loading-elements.md (French) --- fr/dev/eager-loading-elements.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/fr/dev/eager-loading-elements.md b/fr/dev/eager-loading-elements.md index 405db1e9773..a0005880bd7 100644 --- a/fr/dev/eager-loading-elements.md +++ b/fr/dev/eager-loading-elements.md @@ -117,7 +117,7 @@ It’s also possible to load *nested* sets of elements, using this syntax: ### Defining Custom Parameters on Eager-Loaded Elements -You can define custom criteria parameters that will get applied as elements are being eager-loaded, by replacing its key with an array that has two values: the key, and an object that defines the criteria parameters that should be applied. +You can define custom criteria parameters that will get applied as elements are being eager-loaded, by replacing its key with an array that has two values: the key, and a [hash](twig-primer.md#hashes) that defines the criteria parameters that should be applied. ```twig {% set entries = craft.entries() @@ -176,7 +176,7 @@ This problem can be solved with the `withTransforms` asset criteria parameter: .all() %} ``` -Note that each transform definition you want to eager-load can either be a string (the handle of a transform defined in Settings → Assets → Image Transforms) or an object that defines the transform properties. +Note that each transform definition you want to eager-load can either be a string (the handle of a transform defined in Settings → Assets → Image Transforms) or a [hash](twig-primer.md#hashes) that defines the transform properties. Using the `withTransforms` param has no effect on how you’d access image transforms further down in the template. From 4ebfe7cb6b779d30153e476401bb8257696398e5 Mon Sep 17 00:00:00 2001 From: Brad Bell Date: Fri, 12 Jun 2020 17:31:33 -0700 Subject: [PATCH 004/245] New translations eager-loading-elements.md (Japanese) --- ja/dev/eager-loading-elements.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/ja/dev/eager-loading-elements.md b/ja/dev/eager-loading-elements.md index fe2c0d2a164..c0e4745477e 100644 --- a/ja/dev/eager-loading-elements.md +++ b/ja/dev/eager-loading-elements.md @@ -117,7 +117,7 @@ eager-loaded エレメントへのアクセスは、lazy-loaded エレメント ### Eager-Loaded エレメントのカスタムパラメータを定義する -そのキーを（キー、および、適用されるべき基準パラメータを定義するオブジェクトを含む）2つの値を持つ配列に置き換えることによって、eager-loaded するときにエレメントへ適用されるカスタムの基準パラメータを定義できます。 +You can define custom criteria parameters that will get applied as elements are being eager-loaded, by replacing its key with an array that has two values: the key, and a [hash](twig-primer.md#hashes) that defines the criteria parameters that should be applied. ```twig {% set entries = craft.entries() @@ -176,7 +176,7 @@ eager-loaded エレメントへのアクセスは、lazy-loaded エレメント .all() %} ``` -eager-load したいそれぞれのトランスフォームの定義は、文字列（「設定 > アセット > 画像の変形」で定義されたトランスフォームのハンドル)、 または、トランスフォームプロパティを定義したオブジェクトのいずれかです。 +Note that each transform definition you want to eager-load can either be a string (the handle of a transform defined in Settings → Assets → Image Transforms) or a [hash](twig-primer.md#hashes) that defines the transform properties. `withTransforms` パラメータを使っても、テンプレート内の変換された画像にアクセスする方法には影響を与えません。 From 33fada33ff655e299311809ad85f6b44ff2ea073 Mon Sep 17 00:00:00 2001 From: Brad Bell Date: Fri, 12 Jun 2020 17:31:37 -0700 Subject: [PATCH 005/245] New translations user-queries.md (Japanese) --- ja/dev/element-queries/user-queries.md | 718 +++++++++---------------- 1 file changed, 254 insertions(+), 464 deletions(-) diff --git a/ja/dev/element-queries/user-queries.md b/ja/dev/element-queries/user-queries.md index 38a5800e622..4d979bd791b 100644 --- a/ja/dev/element-queries/user-queries.md +++ b/ja/dev/element-queries/user-queries.md @@ -50,6 +50,37 @@ $myUserQuery = \craft\elements\User::find(); +| Param | Description | +| ----------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| [admin](#admin) | Narrows the query results to only users that have admin accounts. | +| [anyStatus](#anystatus) | Clears out the [status](#status) and [enabledForSite()](https://docs.craftcms.com/api/v3/craft-elements-db-elementquery.html#method-enabledforsite) parameters. | +| [asArray](#asarray) | Causes the query to return matching users as arrays of data, rather than [User](api:craft\elements\User) objects. | +| [can](#can) | Narrows the query results to only users that have a certain user permission, either directly on the user account or through one of their user groups. | +| [clearCachedResult](#clearcachedresult) | Clears the cached result. | +| [dateCreated](#datecreated) | Narrows the query results based on the users’ creation dates. | +| [dateUpdated](#dateupdated) | Narrows the query results based on the users’ last-updated dates. | +| [email](#email) | Narrows the query results based on the users’ email addresses. | +| [firstName](#firstname) | Narrows the query results based on the users’ first names. | +| [fixedOrder](#fixedorder) | Causes the query results to be returned in the order specified by [id](#id). | +| [group](#group) | Narrows the query results based on the user group the users belong to. | +| [groupId](#groupid) | Narrows the query results based on the user group the users belong to, per the groups’ IDs. | +| [id](#id) | Narrows the query results based on the users’ IDs. | +| [ignorePlaceholders](#ignoreplaceholders) | Causes the query to return matching users as they are stored in the database, ignoring matching placeholder elements that were set by [craft\services\Elements::setPlaceholderElement()](https://docs.craftcms.com/api/v3/craft-services-elements.html#method-setplaceholderelement). | +| [inReverse](#inreverse) | Causes the query results to be returned in reverse order. | +| [lastLoginDate](#lastlogindate) | Narrows the query results based on the users’ last login dates. | +| [lastName](#lastname) | Narrows the query results based on the users’ last names. | +| [limit](#limit) | Determines the number of users that should be returned. | +| [offset](#offset) | Determines how many users should be skipped in the results. | +| [orderBy](#orderby) | Determines the order that the users should be returned in. (If empty, defaults to `username ASC`.) | +| [preferSites](#prefersites) | If [unique()](https://docs.craftcms.com/api/v3/craft-elements-db-elementquery.html#method-unique) is set, this determines which site should be selected when querying multi-site elements. | +| [relatedTo](#relatedto) | Narrows the query results to only users that are related to certain other elements. | +| [search](#search) | Narrows the query results to only users that match a search query. | +| [status](#status) | Narrows the query results based on the users’ statuses. | +| [trashed](#trashed) | Narrows the query results to only users that have been soft-deleted. | +| [uid](#uid) | Narrows the query results based on the users’ UIDs. | +| [username](#username) | Narrows the query results based on the users’ usernames. | +| [with](#with) | Causes the query to return matching users eager-loaded with related elements. | + ### `admin` 「管理」権限を持つユーザーだけに、クエリの結果を絞り込みます。 @@ -59,14 +90,14 @@ $myUserQuery = \craft\elements\User::find(); ::: code ```twig {# Fetch admins #} -{% set elements = {twig-function} +{% set users = craft.users() .admin() .all() %} ``` ```php // Fetch admins -$elements = ElementClass::find() +$users = \craft\elements\User::find() ->admin() ->all(); ``` @@ -83,15 +114,15 @@ $elements = ElementClass::find() ::: code ```twig -{# Fetch all elements, regardless of status #} -{% set elements = craft.queryFunction() +{# Fetch all users, regardless of status #} +{% set users = craft.users() .anyStatus() .all() %} ``` ```php -// Fetch all elements, regardless of status -$elements = ElementClass::find() +// Fetch all users, regardless of status +$users = \craft\elements\User::find() ->anyStatus() ->all(); ``` @@ -100,7 +131,7 @@ $elements = ElementClass::find() ### `asArray` -ElementClass オブジェクトではなく、データの配列として、マッチしたエレメントをクエリが返します。 +Causes the query to return matching users as arrays of data, rather than [User](api:craft\elements\User) objects. @@ -108,15 +139,15 @@ ElementClass オブジェクトではなく、データの配列として、マ ::: code ```twig -{# Fetch elements as arrays #} -{% set elements = craft.queryFunction() +{# Fetch users as arrays #} +{% set users = craft.users() .asArray() .all() %} ``` ```php -// Fetch elements as arrays -$elements = ElementClass::find() +// Fetch users as arrays +$users = \craft\elements\User::find() ->asArray() ->all(); ``` @@ -133,54 +164,63 @@ Craft によって定義された利用可能なユーザー権限のリスト ::: code ```twig -{# Fetch users that can access the Control Panel #} -{% set elements = {twig-function} +{# Fetch users that can access the control panel #} +{% set users = craft.users() .can('accessCp') .all() %} ``` ```php -// Fetch users that can access the Control Panel -$elements = ElementClass::find() +// Fetch users that can access the control panel +$users = \craft\elements\User::find() ->can('accessCp') ->all(); ``` ::: +### `clearCachedResult` + +Clears the cached result. + + + + + + ### `dateCreated` -エレメントの作成日に基づいて、クエリの結果を絞り込みます。 +Narrows the query results based on the users’ creation dates. -利用可能な値には、次のものが含まれます。 +Possible values include: -| 値 | 取得するエレメント | -| ------------------------------------------------ | ------------------------------------ | -| `'>= 2018-04-01'` | 2018-04-01 以降に作成されたもの。 | -| `'< 2018-05-01'` | 2018-05-01 より前に作成されたもの。 | -| `['and', '>= 2018-04-04', '< 2018-05-01']` | 2018-04-01 から 2018-05-01 の間に作成されたもの。 | +| 値 | Fetches users… | +| ------------------------------------------------ | ---------------------------------------------------- | +| `'>= 2018-04-01'` | that were created on or after 2018-04-01. | +| `'< 2018-05-01'` | that were created before 2018-05-01 | +| `['and', '>= 2018-04-04', '< 2018-05-01']` | that were created between 2018-04-01 and 2018-05-01. | ::: code ```twig -{# Fetch elements created last month #} +{# Fetch users created last month #} {% set start = date('first day of last month')|atom %} {% set end = date('first day of this month')|atom %} -{% set elements = craft.queryFunction() +{% set users = craft.users() .dateCreated(['and', ">= #{start}", "< #{end}"]) .all() %} ``` ```php -// Fetch elements created last month +// Fetch users created last month $start = (new \DateTime('first day of last month'))->format(\DateTime::ATOM); $end = (new \DateTime('first day of this month'))->format(\DateTime::ATOM); -$elements = ElementClass::find() +$users = \craft\elements\User::find() ->dateCreated(['and', ">= {$start}", "< {$end}"]) ->all(); ``` @@ -189,35 +229,35 @@ $elements = ElementClass::find() ### `dateUpdated` -エレメントの最終アップデート日に基づいて、クエリの結果が絞り込まれます。 +Narrows the query results based on the users’ last-updated dates. -利用可能な値には、次のものが含まれます。 +Possible values include: -| 値 | 取得するエレメント | -| ------------------------------------------------ | ---------------------------------------- | -| `'>= 2018-04-01'` | 2018-04-01 以降にアップデートされたもの。 | -| `'< 2018-05-01'` | 2018-05-01 より前にアップデートされたもの。 | -| `['and', '>= 2018-04-04', '< 2018-05-01']` | 2018-04-01 から 2018-05-01 の間にアップデートされたもの。 | +| 値 | Fetches users… | +| ------------------------------------------------ | ---------------------------------------------------- | +| `'>= 2018-04-01'` | that were updated on or after 2018-04-01. | +| `'< 2018-05-01'` | that were updated before 2018-05-01 | +| `['and', '>= 2018-04-04', '< 2018-05-01']` | that were updated between 2018-04-01 and 2018-05-01. | ::: code ```twig -{# Fetch elements updated in the last week #} +{# Fetch users updated in the last week #} {% set lastWeek = date('1 week ago')|atom %} -{% set elements = craft.queryFunction() +{% set users = craft.users() .dateUpdated(">= #{lastWeek}") .all() %} ``` ```php -// Fetch elements updated in the last week +// Fetch users updated in the last week $lastWeek = (new \DateTime('1 week ago'))->format(\DateTime::ATOM); -$elements = ElementClass::find() +$users = \craft\elements\User::find() ->dateUpdated(">= {$lastWeek}") ->all(); ``` @@ -226,30 +266,29 @@ $elements = ElementClass::find() ### `email` -ユーザーのメールアドレスに基づいて、クエリの結果を絞り込みます。 - - +Narrows the query results based on the users’ email addresses. -利用可能な値には、次のものが含まれます。 +Possible values include: -| 値 | 取得するエレメント | -| --------------------------------------------------------------------------- | ---------------------------- | -| `r.baz'3d'foo@bar.baz'6c'foo@bar.baz'2f3.95654'foo@bar.baz'64'foo@bar.baz'` | メールアドレスが `foo@bar.baz`。 | -| a [craft\elements\User](api:craft\elements\User) object | メールアドレスが `foo@bar.baz` ではない。 | +| 値 | Fetches users… | +| ------------------- | ---------------------------------------- | +| `'foo@bar.baz'` | with an email of `foo@bar.baz`. | +| `'not foo@bar.baz'` | not with an email of `foo@bar.baz`. | +| `'*@bar.baz'` | with an email that ends with `@bar.baz`. | ::: code ```twig {# Fetch users with a .co.uk domain on their email address #} -{% set elements = craft.queryFunction() +{% set users = craft.users() .email('*.co.uk') .all() %} ``` ```php // Fetch users with a .co.uk domain on their email address -$elements = ElementClass::find() +$users = \craft\elements\User::find() ->email('*.co.uk') ->all(); ``` @@ -258,29 +297,28 @@ $elements = ElementClass::find() ### `firstName` -ユーザーのファーストネーム（名）に基づいて、クエリの結果を絞り込みます。 - +Narrows the query results based on the users’ first names. +Possible values include: -利用可能な値には、次のものが含まれます。 - -| 値 | 取得するエレメント | -| ---------------------------- | ----------------- | -| `6fc090.362772'Jane'4'Jane'` | ファーストネームが `Jane`。 | +| 値 | Fetches users… | +| ------------ | -------------------------------- | +| `'Jane'` | with a first name of `Jane`. | +| `'not Jane'` | not with a first name of `Jane`. | ::: code ```twig {# Fetch all the Jane's #} -{% set elements = craft.queryFunction() +{% set users = craft.users() .firstName('Jane') .all() %} ``` ```php // Fetch all the Jane's -$elements = ElementClass::find() +$users = \craft\elements\User::find() ->firstName('Jane') ->one(); ``` @@ -289,31 +327,24 @@ $elements = ElementClass::find() ### `fixedOrder` -クエリの結果を [id](#id) で指定された順序で返します。 +Causes the query results to be returned in the order specified by [id](#id). -::: code - -| 値 | 取得するエレメント | -| ----------------------- | ----------------------- | -| `284.0886'foo'053'foo'` | ハンドルが `foo` のグループ内。 | -| a ElementClass object | ハンドルが `foo` のグループ内ではない。 | - -::: +::: code ```twig -{# Fetch elements in a specific order #} -{% set elements = craft.queryFunction() +{# Fetch users in a specific order #} +{% set users = craft.users() .id([1, 2, 3, 4, 5]) .fixedOrder() .all() %} ``` ```php -// Fetch elements in a specific order -$elements = ElementClass::find() +// Fetch users in a specific order +$users = \craft\elements\User::find() ->id([1, 2, 3, 4, 5]) ->fixedOrder() ->all(); @@ -323,23 +354,31 @@ $elements = ElementClass::find() ### `group` -利用可能な値には、次のものが含まれます。 +Narrows the query results based on the user group the users belong to. +Possible values include: +| 値 | Fetches users… | +| -------------------------------------------------- | ----------------------------------------------- | +| `'foo'` | in a group with a handle of `foo`. | +| `'not foo'` | not in a group with a handle of `foo`. | +| `['foo', 'bar']` | in a group with a handle of `foo` or `bar`. | +| `['not', 'foo', 'bar']` | not in a group with a handle of `foo` or `bar`. | +| a [UserGroup](api:craft\models\UserGroup) object | in a group represented by the object. | ::: code ```twig -{# Fetch elements in the Foo user group #} -{% set elements = craft.queryFunction() +{# Fetch users in the Foo user group #} +{% set users = craft.users() .group('foo') .all() %} ``` ```php -// Fetch elements in the Foo user group -$elements = ElementClass::find() +// Fetch users in the Foo user group +$users = \craft\elements\User::find() ->group('foo') ->all(); ``` @@ -348,29 +387,30 @@ $elements = ElementClass::find() ### `groupId` -グループ ID ごとに、ユーザーが属するユーザーグループに基づいて、クエリの結果を絞り込みます。 +Narrows the query results based on the user group the users belong to, per the groups’ IDs. -利用可能な値には、次のものが含まれます。 +Possible values include: -| 値 | 取得するエレメント | -| --------- | -------------------- | -| `1` | ID が 1 のグループ内。 | -| `'not 1'` | ID が 1 のグループ内ではない。 | -| `[1, 2]` | ID が 1 または 2 のグループ内。 | +| 値 | Fetches users… | +| --------------- | ------------------------------------ | +| `1` | in a group with an ID of 1. | +| `'not 1'` | not in a group with an ID of 1. | +| `[1, 2]` | in a group with an ID of 1 or 2. | +| `['not', 1, 2]` | not in a group with an ID of 1 or 2. | ::: code ```twig -{# Fetch elements in a group with an ID of 1 #} -{% set elements = craft.queryFunction() +{# Fetch users in a group with an ID of 1 #} +{% set users = craft.users() .groupId(1) .all() %} ``` ```php -// Fetch elements in a group with an ID of 1 -$elements = ElementClass::find() +// Fetch users in a group with an ID of 1 +$users = \craft\elements\User::find() ->groupId(1) ->all(); ``` @@ -379,55 +419,76 @@ $elements = ElementClass::find() ### `id` -エレメントの ID に基づいて、クエリの結果を絞り込みます。 +Narrows the query results based on the users’ IDs. -利用可能な値には、次のものが含まれます。 -| 値 | 取得するエレメント | -| --------- | ----------- | -| `1` | ID が 1。 | -| `'not 1'` | ID が 1ではない。 | + +Possible values include: + +| 値 | Fetches users… | +| --------------- | ------------------------- | +| `1` | with an ID of 1. | +| `'not 1'` | not with an ID of 1. | +| `[1, 2]` | with an ID of 1 or 2. | +| `['not', 1, 2]` | not with an ID of 1 or 2. | ::: code ```twig -{# Fetch the element by its ID #} -{% set element = craft.queryFunction() +{# Fetch the user by its ID #} +{% set user = craft.users() .id(1) .one() %} ``` ```php -// Fetch the element by its ID -$element = ElementClass::find() +// Fetch the user by its ID +$user = \craft\elements\User::find() ->id(1) ->one(); ``` ::: -### `inReverse` ::: tip -特定の順序で結果を返したい場合、[fixedOrder](#fixedorder) と組み合わせることができます。 +This can be combined with [fixedOrder](#fixedorder) if you want the results to be returned in a specific order. ::: +### `ignorePlaceholders` + +Causes the query to return matching users as they are stored in the database, ignoring matching placeholder elements that were set by [craft\services\Elements::setPlaceholderElement()](https://docs.craftcms.com/api/v3/craft-services-elements.html#method-setplaceholderelement). + + + + -クエリの結果を逆順で返します。 + + + +### `inReverse` + +Causes the query results to be returned in reverse order. + + + + + +::: code ```twig -{# Fetch elements in reverse #} -{% set elements = craft.queryFunction() +{# Fetch users in reverse #} +{% set users = craft.users() .inReverse() .all() %} ``` ```php -// Fetch elements in reverse -$elements = ElementClass::find() +// Fetch users in reverse +$users = \craft\elements\User::find() ->inReverse() ->all(); ``` @@ -436,35 +497,33 @@ $elements = ElementClass::find() ### `lastLoginDate` -::: +Narrows the query results based on the users’ last login dates. -ユーサーの最終ログイン日に基づいて、クエリの結果を絞り込みます。 +Possible values include: -| 値 | 取得するエレメント | -| -------------------------------------------------- | ----------------------------------------------- | -| `'>= 2018-04-01'` | 2018-04-01 以降に最終ログインされたもの。 | -| `'< 2018-05-01'` | 2018-05-01 より前に最終ログインされたもの。 | -| `['and', '>= 2018-04-04', '< 2018-05-01']` | 2018-04-01 から 2018-05-01 の間に最終ログインされたもの。 | -| `['not', 'foo', 'bar']` | not in a group with a handle of `foo` or `bar`. | -| a [UserGroup](api:craft\models\UserGroup) object | in a group represented by the object. | +| 値 | Fetches users… | +| ------------------------------------------------ | ------------------------------------------------------ | +| `'>= 2018-04-01'` | that last logged-in on or after 2018-04-01. | +| `'< 2018-05-01'` | that last logged-in before 2018-05-01 | +| `['and', '>= 2018-04-04', '< 2018-05-01']` | that last logged-in between 2018-04-01 and 2018-05-01. | -利用可能な値には、次のものが含まれます。 +::: code ```twig -{# Fetch elements that logged in recently #} +{# Fetch users that logged in recently #} {% set aWeekAgo = date('7 days ago')|atom %} -{% set elements = craft.queryFunction() +{% set users = craft.users() .lastLoginDate(">= #{aWeekAgo}") .all() %} ``` ```php -// Fetch elements that logged in recently +// Fetch users that logged in recently $aWeekAgo = (new \DateTime('7 days ago'))->format(\DateTime::ATOM); -$elements = ElementClass::find() +$users = \craft\elements\User::find() ->lastLoginDate(">= {$aWeekAgo}") ->all(); ``` @@ -473,30 +532,28 @@ $elements = ElementClass::find() ### `lastName` -::: +Narrows the query results based on the users’ last names. -ユーザーのラストネーム（姓）に基づいて、クエリの結果を絞り込みます。 +Possible values include: -| 値 | 取得するエレメント | -| ----------------------- | ------------------------------------ | -| `Doe'b44.50395768'Doe'` | ラストネームが `Doe`。 | -| `'not Doe'` | ラストネームが `Doe` ではない。 | -| `[1, 2]` | in a group with an ID of 1 or 2. | -| `['not', 1, 2]` | not in a group with an ID of 1 or 2. | +| 値 | Fetches users… | +| ----------- | ------------------------------ | +| `'Doe'` | with a last name of `Doe`. | +| `'not Doe'` | not with a last name of `Doe`. | -利用可能な値には、次のものが含まれます。 +::: code ```twig {# Fetch all the Doe's #} -{% set elements = craft.queryFunction() +{% set users = craft.users() .lastName('Doe') .all() %} ``` ```php // Fetch all the Doe's -$elements = ElementClass::find() +$users = \craft\elements\User::find() ->lastName('Doe') ->one(); ``` @@ -505,403 +562,136 @@ $elements = ElementClass::find() ### `limit` -::: - - - -返されるエレメントの数を決定します。 - -| 値 | 取得するエレメント | -| ------------- | ----------------------------------- | -| `1` | 有効なアカウント。 | -| `'suspended'` | 停止されているアカウント。 | -| `'pending'` | アクティベーションが保留されているアカウント。 | -| `'locked'` | （それが有効か停止されているかに関わらず）ロックされているアカウント。 | +Determines the number of users that should be returned. ::: code ```twig -{# Fetch up to 10 elements #} -{% set elements = craft.queryFunction() +{# Fetch up to 10 users #} +{% set users = craft.users() .limit(10) .all() %} ``` ```php -// Fetch up to 10 elements -$elements = ElementClass::find() +// Fetch up to 10 users +$users = \craft\elements\User::find() ->limit(10) ->all(); ``` ::: - -結果からスキップされるエレメントの数を決定します。 - - ### `offset` -::: code - - - - - - - - - - -### `orderBy` - -::: - +Determines how many users should be skipped in the results. - -返されるエレメントの順序を決定します。 +::: code ```twig -{# Fetch all elements except for the first 3 #} -{% set elements = craft.queryFunction() +{# Fetch all users except for the first 3 #} +{% set users = craft.users() .offset(3) .all() %} ``` ```php -// Fetch all elements except for the first 3 -$elements = ElementClass::find() +// Fetch all users except for the first 3 +$users = \craft\elements\User::find() ->offset(3) ->all(); ``` ::: -### `relatedTo` - -::: - -特定の他のエレメントと関連付けられたエレメントだけに、クエリの結果を絞り込みます。 +### `orderBy` -| 値 | 取得するエレメント | -| ------------------------------------------------ | ------------------------------------------------------ | -| `'foo'` | ユーザー名が `foo`。 | -| `'not foo'` | ユーザー名が `foo` ではない。 | -| `['and', '>= 2018-04-04', '< 2018-05-01']` | that last logged-in between 2018-04-01 and 2018-05-01. | +Determines the order that the users should be returned in. (If empty, defaults to `username ASC`.) -このパラメーターがどのように機能するかの詳細については、[リレーション](https://docs.craftcms.com/v3/relations.html)を参照してください。 +::: code ```twig -{# Fetch all elements in order of date created #} -{% set elements = craft.queryFunction() +{# Fetch all users in order of date created #} +{% set users = craft.users() .orderBy('dateCreated asc') .all() %} ``` ```php -// Fetch all elements in order of date created -$elements = ElementClass::find() +// Fetch all users in order of date created +$users = \craft\elements\User::find() ->orderBy('dateCreated asc') ->all(); ``` ::: -### `search` - -::: - -検索結果にマッチするエレメントだけに、クエリの結果を絞り込みます。 - -| Value | Fetches elements… | -| ----------- | ------------------------------ | -| `'Doe'` | with a last name of `Doe`. | -| `'not Doe'` | not with a last name of `Doe`. | - - - -このパラメーターがどのように機能するかの詳細については、[検索](https://docs.craftcms.com/v3/searching.html)を参照してください。 -```twig -{# Fetch all elements that are related to myCategory #} -{% set elements = craft.queryFunction() - .relatedTo(myCategory) - .all() %} -``` - -```php -// Fetch all elements that are related to $myCategory -$elements = ElementClass::find() - ->relatedTo($myCategory) - ->all(); -``` -::: - - -### `status` - -::: - - - -エレメントのステータスに基づいて、クエリの結果を絞り込みます。 -```twig -{# Get the search query from the 'q' query string param #} -{% set searchQuery = craft.app.request.getQueryParam('q') %} - -{# Fetch all elements that match the search query #} -{% set elements = craft.queryFunction() - .search(searchQuery) - .all() %} -``` - -```php -// Get the search query from the 'q' query string param -$searchQuery = \Craft::$app->request->getQueryParam('q'); - -// Fetch all elements that match the search query -$elements = ElementClass::find() - ->search($searchQuery) - ->all(); -``` -::: - - -### `trashed` - -::: code - - - -::: -```twig -{# Fetch active and locked elements #} -{% set elements = {twig-function} - .status(['active', 'locked']) - .all() %} -``` - -```php -// Fetch active and locked elements -$elements = ElementClass::find() - ->status(['active', 'locked']) - ->all(); -``` -::: - - -### `uid` - -::: code - - - -::: -```twig -{# Fetch trashed elements #} -{% set elements = {twig-function} - .trashed() - .all() %} -``` - -```php -// Fetch trashed elements -$elements = ElementClass::find() - ->trashed() - ->all(); -``` -::: - - -### `username` - -::: code - - - -::: - -ユーザーのユーザー名に基づいて、クエリの結果を絞り込みます。 - - - -利用可能な値には、次のものが含まれます。 -```twig -{# Fetch the element by its UID #} -{% set element = craft.queryFunction() - .uid('xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx') - .one() %} -``` - -```php -// Fetch the element by its UID -$element = ElementClass::find() - ->uid('xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx') - ->one(); -``` -::: - - -### `with` - -::: - - - -関連付けられたエレメントを eager-loaded した状態で、マッチしたエレメントをクエリが返します。 - - - -このパラメーターがどのように機能するかの詳細については、[エレメントのEager-Loading](https://docs.craftcms.com/v3/dev/eager-loading-elements.html)を参照してください。 -```twig -{# Get the requested username #} -{% set requestedUsername = craft.app.request.getSegment(2) %} - -{# Fetch that user #} -{% set element = craft.queryFunction() - .username(requestedUsername|literal) - .one() %} -``` - -```php -// Get the requested username -$requestedUsername = \Craft::$app->request->getSegment(2); - -// Fetch that user -$element = ElementClass::find() - ->username(\craft\helpers\Db::escapeParam($requestedUsername)) - ->one(); -``` -::: - - -### `revisionCreator` - -::: - - - -Possible values include: - -| Value | Fetches revisions… | -| ----------------------------------------------------------- | -------------------------------------- | -| `1` | created by the user with an ID of 1. | -| a [craft\elements\User](api:craft\elements\User) object | by the user represented by the object. | - - - -::: code -```twig -{# Fetch elements eager-loaded with the "Related" field’s relations #} -{% set elements = craft.queryFunction() - .with(['related']) - .all() %} -``` - -```php -// Fetch elements eager-loaded with the "Related" field’s relations -$elements = ElementClass::find() - ->with(['related']) - ->all(); -``` -::: - - -### `revisionId` +### `preferSites` -Narrows the query results based on the elements’ revision’s ID (from the `revisions` table). +If [unique()](https://docs.craftcms.com/api/v3/craft-elements-db-elementquery.html#method-unique) is set, this determines which site should be selected when querying multi-site elements. -Possible values include: +For example, if element “Foo” exists in Site A and Site B, and element “Bar” exists in Site B and Site C, and this is set to `['c', 'b', 'a']`, then Foo will be returned for Site C, and Bar will be returned for Site B. -| Value | Fetches revisions… | -| ----- | --------------------------------- | -| `1` | for the revision with an ID of 1. | +If this isn’t set, then preference goes to the current site. ::: code ```twig -{# Fetch a revision #} -{% set elements = craft.queryFunction() - .revisionId(10) +{# Fetch unique users from Site A, or Site B if they don’t exist in Site A #} +{% set users = craft.users() + .site('*') + .unique() + .preferSites(['a', 'b']) .all() %} ``` ```php -// Fetch a revision -$elements = ElementClass::find() - ->revisionIf(10) +// Fetch unique users from Site A, or Site B if they don’t exist in Site A +$users = \craft\elements\User::find() + ->site('*') + ->unique() + ->preferSites(['a', 'b']) ->all(); ``` ::: -### `revisionOf` - -Narrows the query results to only revisions of a given element. +### `relatedTo` +Narrows the query results to only users that are related to certain other elements. -Possible values include: -| Value | Fetches revisions… | -| --------------------- | ------------------------------------------ | -| `1` | for the element with an ID of 1. | -| a ElementClass object | for the element represented by the object. | +See [Relations](https://docs.craftcms.com/v3/relations.html) for a full explanation of how to work with this parameter. ::: code ```twig -{# Fetch revisions of the element #} -{% set elements = craft.queryFunction() - .revisionOf(myElement) +{# Fetch all users that are related to myCategory #} +{% set users = craft.users() + .relatedTo(myCategory) .all() %} ``` ```php -// Fetch revisions of the element -$elements = ElementClass::find() - ->revisionOf($myElement) +// Fetch all users that are related to $myCategory +$users = \craft\elements\User::find() + ->relatedTo($myCategory) ->all(); ``` ::: -### `revisions` - -Narrows the query results to only revision elements. - - - - - -::: code -```twig -{# Fetch a revision element #} -{% set elements = {twig-function} - .revisions() - .id(123) - .one() %} -``` - -```php -// Fetch a revision element -$elements = ElementClass::find() - ->revisions() - ->id(123) - ->one(); -``` -::: - - ### `search` -Narrows the query results to only elements that match a search query. +Narrows the query results to only users that match a search query. @@ -914,8 +704,8 @@ See [Searching](https://docs.craftcms.com/v3/searching.html) for a full explanat {# Get the search query from the 'q' query string param #} {% set searchQuery = craft.app.request.getQueryParam('q') %} -{# Fetch all elements that match the search query #} -{% set elements = craft.queryFunction() +{# Fetch all users that match the search query #} +{% set users = craft.users() .search(searchQuery) .all() %} ``` @@ -924,8 +714,8 @@ See [Searching](https://docs.craftcms.com/v3/searching.html) for a full explanat // Get the search query from the 'q' query string param $searchQuery = \Craft::$app->request->getQueryParam('q'); -// Fetch all elements that match the search query -$elements = ElementClass::find() +// Fetch all users that match the search query +$users = \craft\elements\User::find() ->search($searchQuery) ->all(); ``` @@ -934,11 +724,11 @@ $elements = ElementClass::find() ### `status` -Narrows the query results based on the elements’ statuses. +Narrows the query results based on the users’ statuses. Possible values include: -| Value | Fetches elements… | +| 値 | Fetches users… | | ------------------------- | ------------------------------------------------------------------------- | | `'active'` _(default)_ | with active accounts. | | `'suspended'` | with suspended accounts. | @@ -950,15 +740,15 @@ Possible values include: ::: code ```twig -{# Fetch active and locked elements #} -{% set elements = craft.queryFunction() +{# Fetch active and locked users #} +{% set users = craft.users() .status(['active', 'locked']) .all() %} ``` ```php -// Fetch active and locked elements -$elements = ElementClass::find() +// Fetch active and locked users +$users = \craft\elements\User::find() ->status(['active', 'locked']) ->all(); ``` @@ -967,7 +757,7 @@ $elements = ElementClass::find() ### `trashed` -Narrows the query results to only elements that have been soft-deleted. +Narrows the query results to only users that have been soft-deleted. @@ -975,15 +765,15 @@ Narrows the query results to only elements that have been soft-deleted. ::: code ```twig -{# Fetch trashed elements #} -{% set elements = craft.queryFunction() +{# Fetch trashed users #} +{% set users = craft.users() .trashed() .all() %} ``` ```php -// Fetch trashed elements -$elements = ElementClass::find() +// Fetch trashed users +$users = \craft\elements\User::find() ->trashed() ->all(); ``` @@ -992,7 +782,7 @@ $elements = ElementClass::find() ### `uid` -Narrows the query results based on the elements’ UIDs. +Narrows the query results based on the users’ UIDs. @@ -1000,15 +790,15 @@ Narrows the query results based on the elements’ UIDs. ::: code ```twig -{# Fetch the element by its UID #} -{% set element = craft.queryFunction() +{# Fetch the user by its UID #} +{% set user = craft.users() .uid('xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx') .one() %} ``` ```php -// Fetch the element by its UID -$element = ElementClass::find() +// Fetch the user by its UID +$user = \craft\elements\User::find() ->uid('xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx') ->one(); ``` @@ -1021,7 +811,7 @@ Narrows the query results based on the users’ usernames. Possible values include: -| Value | Fetches elements… | +| Value | Fetches users… | | ----------- | ----------------------------- | | `'foo'` | with a username of `foo`. | | `'not foo'` | not with a username of `foo`. | @@ -1034,7 +824,7 @@ Possible values include: {% set requestedUsername = craft.app.request.getSegment(2) %} {# Fetch that user #} -{% set element = craft.queryFunction() +{% set user = craft.users() .username(requestedUsername|literal) .one() %} ``` @@ -1044,7 +834,7 @@ Possible values include: $requestedUsername = \Craft::$app->request->getSegment(2); // Fetch that user -$element = ElementClass::find() +$user = \craft\elements\User::find() ->username(\craft\helpers\Db::escapeParam($requestedUsername)) ->one(); ``` @@ -1053,7 +843,7 @@ $element = ElementClass::find() ### `with` -Causes the query to return matching elements eager-loaded with related elements. +Causes the query to return matching users eager-loaded with related elements. @@ -1063,15 +853,15 @@ See [Eager-Loading Elements](https://docs.craftcms.com/v3/dev/eager-loading-elem ::: code ```twig -{# Fetch elements eager-loaded with the "Related" field’s relations #} -{% set elements = craft.queryFunction() +{# Fetch users eager-loaded with the "Related" field’s relations #} +{% set users = craft.users() .with(['related']) .all() %} ``` ```php -// Fetch elements eager-loaded with the "Related" field’s relations -$elements = ElementClass::find() +// Fetch users eager-loaded with the "Related" field’s relations +$users = \craft\elements\User::find() ->with(['related']) ->all(); ``` From 2832bcd58da7f5cc2e7523547869bc8521b48e88 Mon Sep 17 00:00:00 2001 From: Brad Bell Date: Fri, 12 Jun 2020 17:31:39 -0700 Subject: [PATCH 006/245] New translations user-queries.md (French) --- fr/dev/element-queries/user-queries.md | 524 ++++++++----------------- 1 file changed, 160 insertions(+), 364 deletions(-) diff --git a/fr/dev/element-queries/user-queries.md b/fr/dev/element-queries/user-queries.md index 3873feebf2e..3499e566c11 100644 --- a/fr/dev/element-queries/user-queries.md +++ b/fr/dev/element-queries/user-queries.md @@ -50,6 +50,37 @@ User queries support the following parameters: +| Param | Description | +| ----------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| [admin](#admin) | Narrows the query results to only users that have admin accounts. | +| [anyStatus](#anystatus) | Clears out the [status](#status) and [enabledForSite()](https://docs.craftcms.com/api/v3/craft-elements-db-elementquery.html#method-enabledforsite) parameters. | +| [asArray](#asarray) | Causes the query to return matching users as arrays of data, rather than [User](api:craft\elements\User) objects. | +| [can](#can) | Narrows the query results to only users that have a certain user permission, either directly on the user account or through one of their user groups. | +| [clearCachedResult](#clearcachedresult) | Clears the cached result. | +| [dateCreated](#datecreated) | Narrows the query results based on the users’ creation dates. | +| [dateUpdated](#dateupdated) | Narrows the query results based on the users’ last-updated dates. | +| [email](#email) | Narrows the query results based on the users’ email addresses. | +| [firstName](#firstname) | Narrows the query results based on the users’ first names. | +| [fixedOrder](#fixedorder) | Causes the query results to be returned in the order specified by [id](#id). | +| [group](#group) | Narrows the query results based on the user group the users belong to. | +| [groupId](#groupid) | Narrows the query results based on the user group the users belong to, per the groups’ IDs. | +| [id](#id) | Narrows the query results based on the users’ IDs. | +| [ignorePlaceholders](#ignoreplaceholders) | Causes the query to return matching users as they are stored in the database, ignoring matching placeholder elements that were set by [craft\services\Elements::setPlaceholderElement()](https://docs.craftcms.com/api/v3/craft-services-elements.html#method-setplaceholderelement). | +| [inReverse](#inreverse) | Causes the query results to be returned in reverse order. | +| [lastLoginDate](#lastlogindate) | Narrows the query results based on the users’ last login dates. | +| [lastName](#lastname) | Narrows the query results based on the users’ last names. | +| [limit](#limit) | Determines the number of users that should be returned. | +| [offset](#offset) | Determines how many users should be skipped in the results. | +| [orderBy](#orderby) | Determines the order that the users should be returned in. (If empty, defaults to `username ASC`.) | +| [preferSites](#prefersites) | If [unique()](https://docs.craftcms.com/api/v3/craft-elements-db-elementquery.html#method-unique) is set, this determines which site should be selected when querying multi-site elements. | +| [relatedTo](#relatedto) | Narrows the query results to only users that are related to certain other elements. | +| [search](#search) | Narrows the query results to only users that match a search query. | +| [status](#status) | Narrows the query results based on the users’ statuses. | +| [trashed](#trashed) | Narrows the query results to only users that have been soft-deleted. | +| [uid](#uid) | Narrows the query results based on the users’ UIDs. | +| [username](#username) | Narrows the query results based on the users’ usernames. | +| [with](#with) | Causes the query to return matching users eager-loaded with related elements. | + ### `admin` Narrows the query results to only users that have admin accounts. @@ -59,14 +90,14 @@ Narrows the query results to only users that have admin accounts. ::: code ```twig {# Fetch admins #} -{% set elements = craft.queryFunction() +{% set users = craft.users() .admin() .all() %} ``` ```php // Fetch admins -$elements = ElementClass::find() +$users = \craft\elements\User::find() ->admin() ->all(); ``` @@ -83,15 +114,15 @@ Clears out the [status](#status) and [enabledForSite()](https://docs.craftcms.co ::: code ```twig -{# Fetch all elements, regardless of status #} -{% set elements = craft.queryFunction() +{# Fetch all users, regardless of status #} +{% set users = craft.users() .anyStatus() .all() %} ``` ```php -// Fetch all elements, regardless of status -$elements = ElementClass::find() +// Fetch all users, regardless of status +$users = \craft\elements\User::find() ->anyStatus() ->all(); ``` @@ -100,7 +131,7 @@ $elements = ElementClass::find() ### `asArray` -Causes the query to return matching elements as arrays of data, rather than ElementClass objects. +Causes the query to return matching users as arrays of data, rather than [User](api:craft\elements\User) objects. @@ -108,15 +139,15 @@ Causes the query to return matching elements as arrays of data, rather than Elem ::: code ```twig -{# Fetch elements as arrays #} -{% set elements = craft.queryFunction() +{# Fetch users as arrays #} +{% set users = craft.users() .asArray() .all() %} ``` ```php -// Fetch elements as arrays -$elements = ElementClass::find() +// Fetch users as arrays +$users = \craft\elements\User::find() ->asArray() ->all(); ``` @@ -133,30 +164,39 @@ See [Users](https://docs.craftcms.com/v3/users.html) for a full list of availabl ::: code ```twig -{# Fetch users that can access the Control Panel #} -{% set elements = craft.queryFunction() +{# Fetch users that can access the control panel #} +{% set users = craft.users() .can('accessCp') .all() %} ``` ```php -// Fetch users that can access the Control Panel -$elements = ElementClass::find() +// Fetch users that can access the control panel +$users = \craft\elements\User::find() ->can('accessCp') ->all(); ``` ::: +### `clearCachedResult` + +Clears the cached result. + + + + + + ### `dateCreated` -Narrows the query results based on the elements’ creation dates. +Narrows the query results based on the users’ creation dates. Possible values include: -| Value | Fetches elements… | +| Value | Fetches users… | | ------------------------------------------------ | ---------------------------------------------------- | | `'>= 2018-04-01'` | that were created on or after 2018-04-01. | | `'< 2018-05-01'` | that were created before 2018-05-01 | @@ -166,21 +206,21 @@ Possible values include: ::: code ```twig -{# Fetch elements created last month #} +{# Fetch users created last month #} {% set start = date('first day of last month')|atom %} {% set end = date('first day of this month')|atom %} -{% set elements = craft.queryFunction() +{% set users = craft.users() .dateCreated(['and', ">= #{start}", "< #{end}"]) .all() %} ``` ```php -// Fetch elements created last month +// Fetch users created last month $start = (new \DateTime('first day of last month'))->format(\DateTime::ATOM); $end = (new \DateTime('first day of this month'))->format(\DateTime::ATOM); -$elements = ElementClass::find() +$users = \craft\elements\User::find() ->dateCreated(['and', ">= {$start}", "< {$end}"]) ->all(); ``` @@ -189,13 +229,13 @@ $elements = ElementClass::find() ### `dateUpdated` -Narrows the query results based on the elements’ last-updated dates. +Narrows the query results based on the users’ last-updated dates. Possible values include: -| Value | Fetches elements… | +| Value | Fetches users… | | ------------------------------------------------ | ---------------------------------------------------- | | `'>= 2018-04-01'` | that were updated on or after 2018-04-01. | | `'< 2018-05-01'` | that were updated before 2018-05-01 | @@ -205,154 +245,32 @@ Possible values include: ::: code ```twig -{# Fetch elements updated in the last week #} +{# Fetch users updated in the last week #} {% set lastWeek = date('1 week ago')|atom %} -{% set elements = craft.queryFunction() +{% set users = craft.users() .dateUpdated(">= #{lastWeek}") .all() %} ``` ```php -// Fetch elements updated in the last week +// Fetch users updated in the last week $lastWeek = (new \DateTime('1 week ago'))->format(\DateTime::ATOM); -$elements = ElementClass::find() +$users = \craft\elements\User::find() ->dateUpdated(">= {$lastWeek}") ->all(); ``` ::: -### `draftCreator` - -Narrows the query results to only drafts created by a given user. - - - -Possible values include: - -| Value | Fetches drafts… | -| ----------------------------------------------------------- | -------------------------------------- | -| `1` | created by the user with an ID of 1. | -| a [craft\elements\User](api:craft\elements\User) object | by the user represented by the object. | - - - -::: code -```twig -{# Fetch drafts by the current user #} -{% set elements = craft.queryFunction() - .draftCreator(currentUser) - .all() %} -``` - -```php -// Fetch drafts by the current user -$elements = ElementClass::find() - ->draftCreator(Craft::$app->user->identity) - ->all(); -``` -::: - - -### `draftId` - -Narrows the query results based on the elements’ draft’s ID (from the `drafts` table). - - - -Possible values include: - -| Value | Fetches drafts… | -| ----- | ------------------------------ | -| `1` | for the draft with an ID of 1. | - - - -::: code -```twig -{# Fetch a draft #} -{% set elements = craft.queryFunction() - .draftId(10) - .all() %} -``` - -```php -// Fetch a draft -$elements = ElementClass::find() - ->draftIf(10) - ->all(); -``` -::: - - -### `draftOf` - -Narrows the query results to only drafts of a given element. - - - -Possible values include: - -| Value | Fetches drafts… | -| --------------------- | ------------------------------------------ | -| `1` | for the element with an ID of 1. | -| a ElementClass object | for the element represented by the object. | - - - -::: code -```twig -{# Fetch drafts of the element #} -{% set elements = craft.queryFunction() - .draftOf(myElement) - .all() %} -``` - -```php -// Fetch drafts of the element -$elements = ElementClass::find() - ->draftOf($myElement) - ->all(); -``` -::: - - -### `drafts` - -Narrows the query results to only drafts elements. - - - - - -::: code -```twig -{# Fetch a draft element #} -{% set elements = {twig-function} - .drafts() - .id(123) - .one() %} -``` - -```php -// Fetch a draft element -$elements = ElementClass::find() - ->drafts() - ->id(123) - ->one(); -``` -::: - - ### `email` Narrows the query results based on the users’ email addresses. Possible values include: -| Value | Fetches elements… | +| Value | Fetches users… | | ------------------- | ---------------------------------------- | | `'foo@bar.baz'` | with an email of `foo@bar.baz`. | | `'not foo@bar.baz'` | not with an email of `foo@bar.baz`. | @@ -363,14 +281,14 @@ Possible values include: ::: code ```twig {# Fetch users with a .co.uk domain on their email address #} -{% set elements = craft.queryFunction() +{% set users = craft.users() .email('*.co.uk') .all() %} ``` ```php // Fetch users with a .co.uk domain on their email address -$elements = ElementClass::find() +$users = \craft\elements\User::find() ->email('*.co.uk') ->all(); ``` @@ -383,7 +301,7 @@ Narrows the query results based on the users’ first names. Possible values include: -| Value | Fetches elements… | +| Value | Fetches users… | | ------------ | -------------------------------- | | `'Jane'` | with a first name of `Jane`. | | `'not Jane'` | not with a first name of `Jane`. | @@ -393,14 +311,14 @@ Possible values include: ::: code ```twig {# Fetch all the Jane's #} -{% set elements = craft.queryFunction() +{% set users = craft.users() .firstName('Jane') .all() %} ``` ```php // Fetch all the Jane's -$elements = ElementClass::find() +$users = \craft\elements\User::find() ->firstName('Jane') ->one(); ``` @@ -417,16 +335,16 @@ Causes the query results to be returned in the order specified by [id](#id). ::: code ```twig -{# Fetch elements in a specific order #} -{% set elements = craft.queryFunction() +{# Fetch users in a specific order #} +{% set users = craft.users() .id([1, 2, 3, 4, 5]) .fixedOrder() .all() %} ``` ```php -// Fetch elements in a specific order -$elements = ElementClass::find() +// Fetch users in a specific order +$users = \craft\elements\User::find() ->id([1, 2, 3, 4, 5]) ->fixedOrder() ->all(); @@ -440,7 +358,7 @@ Narrows the query results based on the user group the users belong to. Possible values include: -| Value | Fetches elements… | +| Value | Fetches users… | | -------------------------------------------------- | ----------------------------------------------- | | `'foo'` | in a group with a handle of `foo`. | | `'not foo'` | not in a group with a handle of `foo`. | @@ -452,15 +370,15 @@ Possible values include: ::: code ```twig -{# Fetch elements in the Foo user group #} -{% set elements = craft.queryFunction() +{# Fetch users in the Foo user group #} +{% set users = craft.users() .group('foo') .all() %} ``` ```php -// Fetch elements in the Foo user group -$elements = ElementClass::find() +// Fetch users in the Foo user group +$users = \craft\elements\User::find() ->group('foo') ->all(); ``` @@ -473,7 +391,7 @@ Narrows the query results based on the user group the users belong to, per the g Possible values include: -| Value | Fetches elements… | +| Value | Fetches users… | | --------------- | ------------------------------------ | | `1` | in a group with an ID of 1. | | `'not 1'` | not in a group with an ID of 1. | @@ -484,15 +402,15 @@ Possible values include: ::: code ```twig -{# Fetch elements in a group with an ID of 1 #} -{% set elements = craft.queryFunction() +{# Fetch users in a group with an ID of 1 #} +{% set users = craft.users() .groupId(1) .all() %} ``` ```php -// Fetch elements in a group with an ID of 1 -$elements = ElementClass::find() +// Fetch users in a group with an ID of 1 +$users = \craft\elements\User::find() ->groupId(1) ->all(); ``` @@ -501,13 +419,13 @@ $elements = ElementClass::find() ### `id` -Narrows the query results based on the elements’ IDs. +Narrows the query results based on the users’ IDs. Possible values include: -| Value | Fetches elements… | +| Value | Fetches users… | | --------------- | ------------------------- | | `1` | with an ID of 1. | | `'not 1'` | not with an ID of 1. | @@ -518,15 +436,15 @@ Possible values include: ::: code ```twig -{# Fetch the element by its ID #} -{% set element = craft.queryFunction() +{# Fetch the user by its ID #} +{% set user = craft.users() .id(1) .one() %} ``` ```php -// Fetch the element by its ID -$element = ElementClass::find() +// Fetch the user by its ID +$user = \craft\elements\User::find() ->id(1) ->one(); ``` @@ -541,7 +459,7 @@ This can be combined with [fixedOrder](#fixedorder) if you want the results to b ### `ignorePlaceholders` -Causes the query to return matching elements as they are stored in the database, ignoring matching placeholder elements that were set by [craft\services\Elements::setPlaceholderElement()](https://docs.craftcms.com/api/v3/craft-services-elements.html#method-setplaceholderelement). +Causes the query to return matching users as they are stored in the database, ignoring matching placeholder elements that were set by [craft\services\Elements::setPlaceholderElement()](https://docs.craftcms.com/api/v3/craft-services-elements.html#method-setplaceholderelement). @@ -562,15 +480,15 @@ Causes the query results to be returned in reverse order. ::: code ```twig -{# Fetch elements in reverse #} -{% set elements = craft.queryFunction() +{# Fetch users in reverse #} +{% set users = craft.users() .inReverse() .all() %} ``` ```php -// Fetch elements in reverse -$elements = ElementClass::find() +// Fetch users in reverse +$users = \craft\elements\User::find() ->inReverse() ->all(); ``` @@ -583,7 +501,7 @@ Narrows the query results based on the users’ last login dates. Possible values include: -| Value | Fetches elements… | +| Value | Fetches users… | | ------------------------------------------------ | ------------------------------------------------------ | | `'>= 2018-04-01'` | that last logged-in on or after 2018-04-01. | | `'< 2018-05-01'` | that last logged-in before 2018-05-01 | @@ -593,19 +511,19 @@ Possible values include: ::: code ```twig -{# Fetch elements that logged in recently #} +{# Fetch users that logged in recently #} {% set aWeekAgo = date('7 days ago')|atom %} -{% set elements = craft.queryFunction() +{% set users = craft.users() .lastLoginDate(">= #{aWeekAgo}") .all() %} ``` ```php -// Fetch elements that logged in recently +// Fetch users that logged in recently $aWeekAgo = (new \DateTime('7 days ago'))->format(\DateTime::ATOM); -$elements = ElementClass::find() +$users = \craft\elements\User::find() ->lastLoginDate(">= {$aWeekAgo}") ->all(); ``` @@ -618,7 +536,7 @@ Narrows the query results based on the users’ last names. Possible values include: -| Value | Fetches elements… | +| Value | Fetches users… | | ----------- | ------------------------------ | | `'Doe'` | with a last name of `Doe`. | | `'not Doe'` | not with a last name of `Doe`. | @@ -628,14 +546,14 @@ Possible values include: ::: code ```twig {# Fetch all the Doe's #} -{% set elements = craft.queryFunction() +{% set users = craft.users() .lastName('Doe') .all() %} ``` ```php // Fetch all the Doe's -$elements = ElementClass::find() +$users = \craft\elements\User::find() ->lastName('Doe') ->one(); ``` @@ -644,21 +562,21 @@ $elements = ElementClass::find() ### `limit` -Determines the number of elements that should be returned. +Determines the number of users that should be returned. ::: code ```twig -{# Fetch up to 10 elements #} -{% set elements = craft.queryFunction() +{# Fetch up to 10 users #} +{% set users = craft.users() .limit(10) .all() %} ``` ```php -// Fetch up to 10 elements -$elements = ElementClass::find() +// Fetch up to 10 users +$users = \craft\elements\User::find() ->limit(10) ->all(); ``` @@ -667,21 +585,21 @@ $elements = ElementClass::find() ### `offset` -Determines how many elements should be skipped in the results. +Determines how many users should be skipped in the results. ::: code ```twig -{# Fetch all elements except for the first 3 #} -{% set elements = craft.queryFunction() +{# Fetch all users except for the first 3 #} +{% set users = craft.users() .offset(3) .all() %} ``` ```php -// Fetch all elements except for the first 3 -$elements = ElementClass::find() +// Fetch all users except for the first 3 +$users = \craft\elements\User::find() ->offset(3) ->all(); ``` @@ -690,21 +608,21 @@ $elements = ElementClass::find() ### `orderBy` -Determines the order that the elements should be returned in. +Determines the order that the users should be returned in. (If empty, defaults to `username ASC`.) ::: code ```twig -{# Fetch all elements in order of date created #} -{% set elements = craft.queryFunction() +{# Fetch all users in order of date created #} +{% set users = craft.users() .orderBy('dateCreated asc') .all() %} ``` ```php -// Fetch all elements in order of date created -$elements = ElementClass::find() +// Fetch all users in order of date created +$users = \craft\elements\User::find() ->orderBy('dateCreated asc') ->all(); ``` @@ -725,8 +643,8 @@ If this isn’t set, then preference goes to the current site. ::: code ```twig -{# Fetch unique elements from Site A, or Site B if they don’t exist in Site A #} -{% set elements = craft.queryFunction() +{# Fetch unique users from Site A, or Site B if they don’t exist in Site A #} +{% set users = craft.users() .site('*') .unique() .preferSites(['a', 'b']) @@ -734,8 +652,8 @@ If this isn’t set, then preference goes to the current site. ``` ```php -// Fetch unique elements from Site A, or Site B if they don’t exist in Site A -$elements = ElementClass::find() +// Fetch unique users from Site A, or Site B if they don’t exist in Site A +$users = \craft\elements\User::find() ->site('*') ->unique() ->preferSites(['a', 'b']) @@ -746,7 +664,7 @@ $elements = ElementClass::find() ### `relatedTo` -Narrows the query results to only elements that are related to certain other elements. +Narrows the query results to only users that are related to certain other elements. @@ -756,146 +674,24 @@ See [Relations](https://docs.craftcms.com/v3/relations.html) for a full explanat ::: code ```twig -{# Fetch all elements that are related to myCategory #} -{% set elements = craft.queryFunction() +{# Fetch all users that are related to myCategory #} +{% set users = craft.users() .relatedTo(myCategory) .all() %} ``` ```php -// Fetch all elements that are related to $myCategory -$elements = ElementClass::find() +// Fetch all users that are related to $myCategory +$users = \craft\elements\User::find() ->relatedTo($myCategory) ->all(); ``` ::: -### `revisionCreator` - -Narrows the query results to only revisions created by a given user. - - - -Possible values include: - -| Value | Fetches revisions… | -| ----------------------------------------------------------- | -------------------------------------- | -| `1` | created by the user with an ID of 1. | -| a [craft\elements\User](api:craft\elements\User) object | by the user represented by the object. | - - - -::: code -```twig -{# Fetch revisions by the current user #} -{% set elements = craft.queryFunction() - .revisionCreator(currentUser) - .all() %} -``` - -```php -// Fetch revisions by the current user -$elements = ElementClass::find() - ->revisionCreator(Craft::$app->user->identity) - ->all(); -``` -::: - - -### `revisionId` - -Narrows the query results based on the elements’ revision’s ID (from the `revisions` table). - - - -Possible values include: - -| Value | Fetches revisions… | -| ----- | --------------------------------- | -| `1` | for the revision with an ID of 1. | - - - -::: code -```twig -{# Fetch a revision #} -{% set elements = craft.queryFunction() - .revisionId(10) - .all() %} -``` - -```php -// Fetch a revision -$elements = ElementClass::find() - ->revisionIf(10) - ->all(); -``` -::: - - -### `revisionOf` - -Narrows the query results to only revisions of a given element. - - - -Possible values include: - -| Value | Fetches revisions… | -| --------------------- | ------------------------------------------ | -| `1` | for the element with an ID of 1. | -| a ElementClass object | for the element represented by the object. | - - - -::: code -```twig -{# Fetch revisions of the element #} -{% set elements = craft.queryFunction() - .revisionOf(myElement) - .all() %} -``` - -```php -// Fetch revisions of the element -$elements = ElementClass::find() - ->revisionOf($myElement) - ->all(); -``` -::: - - -### `revisions` - -Narrows the query results to only revision elements. - - - - - -::: code -```twig -{# Fetch a revision element #} -{% set elements = {twig-function} - .revisions() - .id(123) - .one() %} -``` - -```php -// Fetch a revision element -$elements = ElementClass::find() - ->revisions() - ->id(123) - ->one(); -``` -::: - - ### `search` -Narrows the query results to only elements that match a search query. +Narrows the query results to only users that match a search query. @@ -908,8 +704,8 @@ See [Searching](https://docs.craftcms.com/v3/searching.html) for a full explanat {# Get the search query from the 'q' query string param #} {% set searchQuery = craft.app.request.getQueryParam('q') %} -{# Fetch all elements that match the search query #} -{% set elements = craft.queryFunction() +{# Fetch all users that match the search query #} +{% set users = craft.users() .search(searchQuery) .all() %} ``` @@ -918,8 +714,8 @@ See [Searching](https://docs.craftcms.com/v3/searching.html) for a full explanat // Get the search query from the 'q' query string param $searchQuery = \Craft::$app->request->getQueryParam('q'); -// Fetch all elements that match the search query -$elements = ElementClass::find() +// Fetch all users that match the search query +$users = \craft\elements\User::find() ->search($searchQuery) ->all(); ``` @@ -928,13 +724,13 @@ $elements = ElementClass::find() ### `status` -Narrows the query results based on the elements’ statuses. +Narrows the query results based on the users’ statuses. Possible values include: -| Value | Fetches elements… | +| Value | Fetches users… | | ------------------------- | ------------------------------------------------------------------------- | -| `'active'` *(default)* | with active accounts. | +| `'active'` _(default)_ | with active accounts. | | `'suspended'` | with suspended accounts. | | `'pending'` | with accounts that are still pending activation. | | `'locked'` | with locked accounts (regardless of whether they’re active or suspended). | @@ -944,15 +740,15 @@ Possible values include: ::: code ```twig -{# Fetch active and locked elements #} -{% set elements = craft.queryFunction() +{# Fetch active and locked users #} +{% set users = craft.users() .status(['active', 'locked']) .all() %} ``` ```php -// Fetch active and locked elements -$elements = ElementClass::find() +// Fetch active and locked users +$users = \craft\elements\User::find() ->status(['active', 'locked']) ->all(); ``` @@ -961,7 +757,7 @@ $elements = ElementClass::find() ### `trashed` -Narrows the query results to only elements that have been soft-deleted. +Narrows the query results to only users that have been soft-deleted. @@ -969,15 +765,15 @@ Narrows the query results to only elements that have been soft-deleted. ::: code ```twig -{# Fetch trashed elements #} -{% set elements = craft.queryFunction() +{# Fetch trashed users #} +{% set users = craft.users() .trashed() .all() %} ``` ```php -// Fetch trashed elements -$elements = ElementClass::find() +// Fetch trashed users +$users = \craft\elements\User::find() ->trashed() ->all(); ``` @@ -986,7 +782,7 @@ $elements = ElementClass::find() ### `uid` -Narrows the query results based on the elements’ UIDs. +Narrows the query results based on the users’ UIDs. @@ -994,15 +790,15 @@ Narrows the query results based on the elements’ UIDs. ::: code ```twig -{# Fetch the element by its UID #} -{% set element = craft.queryFunction() +{# Fetch the user by its UID #} +{% set user = craft.users() .uid('xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx') .one() %} ``` ```php -// Fetch the element by its UID -$element = ElementClass::find() +// Fetch the user by its UID +$user = \craft\elements\User::find() ->uid('xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx') ->one(); ``` @@ -1015,7 +811,7 @@ Narrows the query results based on the users’ usernames. Possible values include: -| Value | Fetches elements… | +| Value | Fetches users… | | ----------- | ----------------------------- | | `'foo'` | with a username of `foo`. | | `'not foo'` | not with a username of `foo`. | @@ -1028,7 +824,7 @@ Possible values include: {% set requestedUsername = craft.app.request.getSegment(2) %} {# Fetch that user #} -{% set element = craft.queryFunction() +{% set user = craft.users() .username(requestedUsername|literal) .one() %} ``` @@ -1038,7 +834,7 @@ Possible values include: $requestedUsername = \Craft::$app->request->getSegment(2); // Fetch that user -$element = ElementClass::find() +$user = \craft\elements\User::find() ->username(\craft\helpers\Db::escapeParam($requestedUsername)) ->one(); ``` @@ -1047,7 +843,7 @@ $element = ElementClass::find() ### `with` -Causes the query to return matching elements eager-loaded with related elements. +Causes the query to return matching users eager-loaded with related elements. @@ -1057,15 +853,15 @@ See [Eager-Loading Elements](https://docs.craftcms.com/v3/dev/eager-loading-elem ::: code ```twig -{# Fetch elements eager-loaded with the "Related" field’s relations #} -{% set elements = craft.queryFunction() +{# Fetch users eager-loaded with the "Related" field’s relations #} +{% set users = craft.users() .with(['related']) .all() %} ``` ```php -// Fetch elements eager-loaded with the "Related" field’s relations -$elements = ElementClass::find() +// Fetch users eager-loaded with the "Related" field’s relations +$users = \craft\elements\User::find() ->with(['related']) ->all(); ``` From 044067b56e0f45c4a51fa3c4e2cbc6d60820c140 Mon Sep 17 00:00:00 2001 From: Brad Bell Date: Fri, 12 Jun 2020 17:31:41 -0700 Subject: [PATCH 007/245] New translations app.md (Japanese) --- ja/config/app.md | 144 ++++++++++++++++++++++++++++++++++++++++------- 1 file changed, 124 insertions(+), 20 deletions(-) diff --git a/ja/config/app.md b/ja/config/app.md index c43c4715939..62d8990830f 100644 --- a/ja/config/app.md +++ b/ja/config/app.md @@ -14,6 +14,31 @@ Craft のデフォルト設定は [src/config/app.php](https://github.com/craftc デフォルトでは、Craft は `storage/runtime/cache/` フォルダにデータキャッシュを蓄積します。`config/app.php` で `cache` アプリケーションコンポーネントを上書きすることによって、代替の[キャッシュストレージ](https://www.yiiframework.com/doc/guide/2.0/en/caching-data#supported-cache-storage)を使うよう Craft を設定できます。 +#### Database Cache Example + +If you want to store data caches in the database, first you will need to create a `cache` table as specified by . Craft provides a CLI command for convenience: + +```bash +./craft setup/db-cache-table +``` + +Once that’s done, you can set your `cache` application component to use . + +```php + [ + 'cache' => craft\cache\DbCache::class, + ], +]; +``` + +::: tip +If you’ve already configured Craft to use rather than , you can safely switch to the latter if you remove your `cache` table’s `dateCreated`, `dateUpdated`, and `uid` columns. +::: + +#### APC Example + ```php [ 'class' => yii\caching\ApcCache::class, 'useApcu' => true, + 'keyPrefix' => 'a_unique_key', ], ], ]; ``` -#### Memcached の実例 + +#### Memcached Example ```php 1, ], ], + 'keyPrefix' => 'a_unique_key', ], ], ]; ``` -#### Redis の実例 +#### Redis Example -Redis キャッシュストレージを利用するには、あらかじめ [yii2-redis](https://github.com/yiisoft/yii2-redis) ライブラリをインストールする必要があります。次に、Craft の `cache` コンポーネントでそれを利用するよう設定します。 +To use Redis cache storage, you will first need to install the [yii2-redis](https://github.com/yiisoft/yii2-redis) library. Then configure Craft’s `cache` component to use it: ```php [ 'class' => yii\redis\Cache::class, 'defaultDuration' => 86400, + 'keyPrefix' => 'a_unique_key', ], ], ]; ``` -## Session コンポーネント +## Database Component -負荷分散された環境では、デフォルトの `session` コンポーネントを上書きして、PHP セッションデータを一元管理された場所（例：Redis）に保存したいかもしれません。 +If you need to configure the database connection beyond what’s possible with Craft’s [database config settings](db-settings.md), you can do that by overriding the `db` component: + +```php + [ + 'db' => function() { + // Get the default component config + $config = craft\helpers\App::dbConfig(); + + // Use read/write query splitting + // (https://www.yiiframework.com/doc/guide/2.0/en/db-dao#read-write-splitting) + + // Define the default config for replica DB connections + $config['slaveConfig'] = [ + 'username' => getenv('DB_REPLICA_USER'), + 'password' => getenv('DB_REPLICA_PASSWORD'), + 'tablePrefix' => getenv('DB_TABLE_PREFIX'), + 'attributes' => [ + // Use a smaller connection timeout + PDO::ATTR_TIMEOUT => 10, + ], + 'charset' => 'utf8', + ]; + + // Define the replica DB connections + $config['slaves'] = [ + ['dsn' => getenv('DB_REPLICA_DSN_1')], + ['dsn' => getenv('DB_REPLICA_DSN_2')], + ['dsn' => getenv('DB_REPLICA_DSN_3')], + ['dsn' => getenv('DB_REPLICA_DSN_4')], + ]; + + // Instantiate and return it + return Craft::createObject($config); + }, + ], +]; +``` + +## Session Component + +In a load-balanced environment, you may want to override the default `session` component to store PHP session data in a centralized location. + +#### Redis Example ```php 6379, 'password' => getenv('REDIS_PASSWORD'), ], - 'session' => [ - 'class' => yii\redis\Session::class, - 'as session' => craft\behaviors\SessionBehavior::class, - ], + 'session' => function() { + // Get the default component config + $config = craft\helpers\App::sessionConfig(); + + // Override the class to use Redis' session class + $config['class'] = yii\redis\Session::class; + + // Instantiate and return it + return Craft::createObject($config); + }, + ], +]; +``` + +#### Database Example + +First, you must create the database table that will store PHP’s sessions. You can do that by running the `craft setup/php-session-table` console command from your project’s root folder. + +```php + [ + 'session' => function() { + // Get the default component config + $config = craft\helpers\App::sessionConfig(); + + // Override the class to use DB session class + $config['class'] = yii\web\DbSession::class; + + // Set the session table name + $config['sessionTable'] = craft\db\Table::PHPSESSIONS; + + // Instantiate and return it + return Craft::createObject($config); + }, ], ]; ``` ::: tip -`session` コンポーネントは、システムが依存するコンポーネントにメソッドを加える ビヘイビアで設定**しなければなりません**。 +The `session` component **must** be configured with the behavior, which adds methods to the component that the system relies on. ::: -## Mailer コンポーネント +## Mailer Component -（メール送信を担っている）`mailer` コンポーネントの設定を上書きするために、`config/app.php` を調整します。 +To override the `mailer` component config (which is responsible for sending emails), do this in `config/app.php`: ```php メール」からメールの設定をテストする際には反映されません。 +Any changes you make to the Mailer component from `config/app.php` will not be reflected when testing email settings from Settings → Email. ::: -## Queue コンポーネント +## Queue Component -Craft のジョブキューは [Yii2 Queue Extension](https://github.com/yiisoft/yii2-queue) によって動いています。デフォルトでは、Craft はエクステンションの [DB driver](https://github.com/yiisoft/yii2-queue/blob/master/docs/guide/driver-db.md) をベースとする [custom queue driver](api:craft\queue\Queue) を使用しますが、`config/app.php` から Craft の `queue` コンポーネントを上書きすることによって、別のドライバに切り替えることができます。 +Craft’s job queue is powered by the [Yii2 Queue Extension](https://github.com/yiisoft/yii2-queue). By default Craft will use a [custom queue driver](api:craft\queue\Queue) based on the extension’s [DB driver](https://github.com/yiisoft/yii2-queue/blob/master/docs/guide/driver-db.md), but you can switch to a different driver by overriding Craft’s `queue` component from `config/app.php`: ```php を実装しているドライバだけがコントロールパネル内に表示されます。 +Only drivers that implement will be visible within the control panel. ::: ::: tip -キュードライバが独自のワーカーを提供している場合、`config/general.php` の コンフィグ設定を `false` に設定します。 +If your queue driver supplies its own worker, set the config setting to `false` in `config/general.php`. ::: -## モジュール +## Modules -`config/app.php` からカスタム Yii モジュールを登録し bootstrap することもできます。詳細については、[モジュールの構築方法](../extend/module-guide.md)を参照してください。 +You can register and bootstrap custom Yii modules into the application from `config/app.php` as well. See [How to Build a Module](../extend/module-guide.md) for more info. From 3c860f9994ffd91685d59fd0d7e6ad61f576100b Mon Sep 17 00:00:00 2001 From: Brad Bell Date: Fri, 12 Jun 2020 17:31:43 -0700 Subject: [PATCH 008/245] New translations app.md (French) --- fr/config/app.md | 116 ++++++++++++++++++++++++++++++++++++++++++++--- 1 file changed, 110 insertions(+), 6 deletions(-) diff --git a/fr/config/app.md b/fr/config/app.md index e91ea9a65f6..402512ea284 100644 --- a/fr/config/app.md +++ b/fr/config/app.md @@ -14,6 +14,31 @@ Craft’s default configuration is defined by [src/config/app.php](https://githu By default, Craft will store data caches in the `storage/runtime/cache/` folder. You can configure Craft to use alternative [cache storage](https://www.yiiframework.com/doc/guide/2.0/en/caching-data#supported-cache-storage) by overriding the `cache` application component from `config/app.php`. +#### Database Cache Example + +If you want to store data caches in the database, first you will need to create a `cache` table as specified by . Craft provides a CLI command for convenience: + +```bash +./craft setup/db-cache-table +``` + +Once that’s done, you can set your `cache` application component to use . + +```php + [ + 'cache' => craft\cache\DbCache::class, + ], +]; +``` + +::: tip +If you’ve already configured Craft to use rather than , you can safely switch to the latter if you remove your `cache` table’s `dateCreated`, `dateUpdated`, and `uid` columns. +::: + +#### APC Example + ```php [ 'class' => yii\caching\ApcCache::class, 'useApcu' => true, + 'keyPrefix' => 'a_unique_key', ], ], ]; ``` + #### Memcached Example ```php @@ -49,6 +76,7 @@ return [ 'weight' => 1, ], ], + 'keyPrefix' => 'a_unique_key', ], ], ]; @@ -71,14 +99,59 @@ return [ 'cache' => [ 'class' => yii\redis\Cache::class, 'defaultDuration' => 86400, + 'keyPrefix' => 'a_unique_key', ], ], ]; ``` +## Database Component + +If you need to configure the database connection beyond what’s possible with Craft’s [database config settings](db-settings.md), you can do that by overriding the `db` component: + +```php + [ + 'db' => function() { + // Get the default component config + $config = craft\helpers\App::dbConfig(); + + // Use read/write query splitting + // (https://www.yiiframework.com/doc/guide/2.0/en/db-dao#read-write-splitting) + + // Define the default config for replica DB connections + $config['slaveConfig'] = [ + 'username' => getenv('DB_REPLICA_USER'), + 'password' => getenv('DB_REPLICA_PASSWORD'), + 'tablePrefix' => getenv('DB_TABLE_PREFIX'), + 'attributes' => [ + // Use a smaller connection timeout + PDO::ATTR_TIMEOUT => 10, + ], + 'charset' => 'utf8', + ]; + + // Define the replica DB connections + $config['slaves'] = [ + ['dsn' => getenv('DB_REPLICA_DSN_1')], + ['dsn' => getenv('DB_REPLICA_DSN_2')], + ['dsn' => getenv('DB_REPLICA_DSN_3')], + ['dsn' => getenv('DB_REPLICA_DSN_4')], + ]; + + // Instantiate and return it + return Craft::createObject($config); + }, + ], +]; +``` + ## Session Component -In a load-balanced environment, you may want to override the default `session` component to store PHP session data in a centralized location (e.g. Redis): +In a load-balanced environment, you may want to override the default `session` component to store PHP session data in a centralized location. + +#### Redis Example ```php 6379, 'password' => getenv('REDIS_PASSWORD'), ], - 'session' => [ - 'class' => yii\redis\Session::class, - 'as session' => craft\behaviors\SessionBehavior::class, - ], + 'session' => function() { + // Get the default component config + $config = craft\helpers\App::sessionConfig(); + + // Override the class to use Redis' session class + $config['class'] = yii\redis\Session::class; + + // Instantiate and return it + return Craft::createObject($config); + }, + ], +]; +``` + +#### Database Example + +First, you must create the database table that will store PHP’s sessions. You can do that by running the `craft setup/php-session-table` console command from your project’s root folder. + +```php + [ + 'session' => function() { + // Get the default component config + $config = craft\helpers\App::sessionConfig(); + + // Override the class to use DB session class + $config['class'] = yii\web\DbSession::class; + + // Set the session table name + $config['sessionTable'] = craft\db\Table::PHPSESSIONS; + + // Instantiate and return it + return Craft::createObject($config); + }, ], ]; ``` @@ -157,7 +261,7 @@ return [ Available drivers are listed in the [Yii2 Queue Extension documentation](https://github.com/yiisoft/yii2-queue/tree/master/docs/guide). ::: warning -Only drivers that implement will be visible within the Control Panel. +Only drivers that implement will be visible within the control panel. ::: ::: tip From 5ea32d01b11260d0b0c9d4bc499c19da5cf0459f Mon Sep 17 00:00:00 2001 From: Brad Bell Date: Fri, 12 Jun 2020 17:31:45 -0700 Subject: [PATCH 009/245] New translations config-settings.md (Japanese) --- ja/config/config-settings.md | 1409 +++++++++++++++++++--------------- 1 file changed, 805 insertions(+), 604 deletions(-) diff --git a/ja/config/config-settings.md b/ja/config/config-settings.md index 91dc66ba89b..31a5a133fea 100644 --- a/ja/config/config-settings.md +++ b/ja/config/config-settings.md @@ -55,7 +55,7 @@ Craft がサポートするコンフィグ設定の完全なリストは、次 -現在のリクエストを最初にコントローラーアクションにルーティングするかどうかを決定するとき、Craft が探す URI セグメント。 +The URI segment Craft should look for when determining if the current request should be routed to a controller action. @@ -78,7 +78,7 @@ Craft がサポートするコンフィグ設定の完全なリストは、次 -コントロールパネルにアクセスできないユーザーが、アカウントをアクティベートしたときにリダイレクトする URI。 +The URI that users without access to the control panel should be redirected to after activating their account. サポートされる値の種類は、[craft\helpers\ConfigHelper::localizedValue()](https://docs.craftcms.com/api/v3/craft-helpers-confighelper.html#method-localizedvalue) のリストを参照してください。 @@ -147,13 +147,18 @@ Craft がサポートするコンフィグ設定の完全なリストは、次 [GeneralConfig::$allowAdminChanges](api:craft\config\GeneralConfig::$allowAdminChanges) +Since +: + +3.1.0 + 管理者によるシステムへの管理上の変更を許可するかどうか。 これを無効にすると、設定およびプラグインストアのセクションは非表示になり、Craft 本体のエディションとプラグインのバージョンがロックされ、プロジェクトコンフィグは読み取り専用になります。 -そのため、[useProjectConfigFile](https://docs.craftcms.com/api/v3/craft-config-generalconfig.html#useprojectconfigfile) が有効になっている production 環境のみ、これを無効にするべきです。そして、デプロイメントワークフローでデプロイ時に自動的に `composer install` を実行するようにします。 +Therefore you should only disable this in production environments when is enabled, and you have a deployment workflow that runs `composer install` automatically on deploy. ::: warning **すべての**環境が Craft 3.1.0 以降にアップデートされるまで、この設定を無効にしないでください。 @@ -203,9 +208,9 @@ Craft がサポートするコンフィグ設定の完全なリストは、次 -コントロールパネルでのシステムとプラグインのアップデート、および、プラグインストアからのプラグインのインストールを Craft が許可するかどうか。 +Whether Craft should allow system and plugin updates in the control panel, and plugin installation from the Plugin Store. -[allowAdminChanges](https://docs.craftcms.com/api/v3/craft-config-generalconfig.html#allowadminchanges) が無効になっている場合、この設定は自動的に無効になります。 +This setting will automatically be disabled if is disabled. @@ -356,12 +361,12 @@ Craft がサポートするコンフィグ設定の完全なリストは、次 -コントロールパネルの URL を生成する際に、Craft が使用するベース URL。 +The base URL that Craft should use when generating control panel URLs. 空白の場合、自動的に決定されます。 ::: tip -ベース CP URL に [CP トリガーワード](https://docs.craftcms.com/api/v3/craft-config-generalconfig.html#cptrigger)（例：`/admin`）を **含めない** でください。 +The base control panel URL should **not** include the [control panel trigger word](config:cpTrigger) (e.g. `/admin`). ::: @@ -464,6 +469,10 @@ Craft が `{% cache %}` タグ内にエレメントクエリをキャッシュ アップロードされたファイル名に含まれる ASCII 以外の文字を ASCII に変換するかどうか（例： `ñ` → `n`）。 +::: tip +You can run `./craft utils/ascii-filenames` in your terminal to apply ASCII filenames to all existing assets. +::: + ### `cooldownDuration` @@ -485,11 +494,11 @@ Craft が `{% cache %}` タグ内にエレメントクエリをキャッシュ -あまりに多くのログイン試行の失敗によりアカウントがロックされた後、ユーザーが再試行するために待たなければならない時間。 +The amount of time a user must wait before re-attempting to log in after their account is locked due to too many failed login attempts. -`0` をセットするとアカウントは無期限にロックされます。管理者が手動でアカウントのロックを解除する必要があります。 +Set to `0` to keep the account locked indefinitely, requiring an admin to manually unlock the account. -サポートされる値の種類は、[craft\helpers\ConfigHelper::durationInSeconds()](https://docs.craftcms.com/api/v3/craft-helpers-confighelper.html#method-durationinseconds) のリストを参照してください。 +See [craft\helpers\ConfigHelper::durationInSeconds()](https://docs.craftcms.com/api/v3/craft-helpers-confighelper.html#method-durationinseconds) for a list of supported value types. @@ -512,7 +521,7 @@ Craft が `{% cache %}` タグ内にエレメントクエリをキャッシュ -現在のリクエストをフロントエンドのウェブサイトではなくコントロールパネルにルーティングするかどうかを決定するとき、Craft が探す URI セグメント。 +The URI segment Craft should look for when determining if the current request should route to the control panel rather than the front-end website. @@ -535,7 +544,7 @@ Craft が `{% cache %}` タグ内にエレメントクエリをキャッシュ -[enableCsrfProtection](https://docs.craftcms.com/api/v3/craft-config-generalconfig.html#enablecsrfprotection) が `true` にセットされている場合、CSRF の検証に使用される CSRF トークン名。 +The name of CSRF token used for CSRF validation if is set to `true`. @@ -558,7 +567,7 @@ Craft が `{% cache %}` タグ内にエレメントクエリをキャッシュ -Craft によって生成される Cookie が作成されるべきドメイン。空白の場合、使用するドメイン（ほとんどの場合、現在のもの）の決定はブラウザに任されます。すべてのサブドメインで機能する Cookie を望むなら、例えば、これを `'.domain.com'` にセットします。 +The domain that cookies generated by Craft should be created for. If blank, it will be left up to the browser to determine which domain to use (almost always the current). If you want the cookies to work for all subdomains, for example, you could set this to `'.domain.com'`. @@ -581,7 +590,7 @@ Craft によって生成される Cookie が作成されるべきドメイン。 -優先言語をまだセットしてないユーザー向けに、コントロールパネルが使用するデフォルトの言語。 +The default language the control panel should use for users who haven’t set a preferred language yet. @@ -604,9 +613,9 @@ Craft によって生成される Cookie が作成されるべきドメイン。 -新しく生成されたディレクトリにセットされるデフォルトのパーミッション。 +The default permission to be set for newly generated directories. -`null` をセットすると、パーミッションは現在の環境によって決定されます。 +If set to `null`, the permission will be determined by the current environment. @@ -629,9 +638,9 @@ Craft によって生成される Cookie が作成されるべきドメイン。 -新しく生成されたファイルにセットされるデフォルトのパーミッション。 +The default permission to be set for newly generated files. -`null` をセットすると、パーミッションは現在の環境によって決定されます。 +If set to `null`, the permission will be determined by the current environment. @@ -654,7 +663,7 @@ Craft によって生成される Cookie が作成されるべきドメイン。 -JPG と PNG ファイルを保存する際に、Craft が使用する品質レベル。0（最低品質、最小ファイルサイズ）から100（最高品質、最大ファイルサイズ）までの範囲。 +The quality level Craft will use when saving JPG and PNG files. Ranges from 0 (worst quality, smallest file) to 100 (best quality, biggest file). @@ -677,9 +686,9 @@ JPG と PNG ファイルを保存する際に、Craft が使用する品質レ -それぞれの検索用語に適用されるデフォルトのオプション。 +The default options that should be applied to each search term. -オプションは次のものを含みます。 +Options include: - `attribute` – （もしある場合）用語が適用される属性（例：'title'）。（デフォルトは `null`） - `exact` – 用語が完全一致でなければならないかどうか（`attribute` がセットされている場合のみ、適用されます）。（デフォルトは `false`） @@ -708,7 +717,7 @@ JPG と PNG ファイルを保存する際に、Craft が使用する品質レ -フロントエンドでテンプレートパスとファイルの照合をする際に、Craft が探すテンプレートファイルの拡張子。 +The template file extensions Craft will look for when matching a template path to a file on the front end. @@ -731,9 +740,9 @@ JPG と PNG ファイルを保存する際に、Craft が使用する品質レ -トークンが期限切れになる前に使用できるデフォルトの時間。 +The default amount of time tokens can be used before expiring. -サポートされる値の種類は、[craft\helpers\ConfigHelper::durationInSeconds()](https://docs.craftcms.com/api/v3/craft-helpers-confighelper.html#method-durationinseconds) のリストを参照してください。 +See [craft\helpers\ConfigHelper::durationInSeconds()](https://docs.craftcms.com/api/v3/craft-helpers-confighelper.html#method-durationinseconds) for a list of supported value types. @@ -756,9 +765,9 @@ JPG と PNG ファイルを保存する際に、Craft が使用する品質レ -新しいユーザーが「週の開始日」としてセットする必要があるデフォルトの曜日。 +The default day that new users should have set as their Week Start Day. -これは、次の整数の1つをセットしてください。 +This should be set to one of the following integers: - `0` – 日曜日 - `1` – 月曜日 @@ -789,9 +798,9 @@ JPG と PNG ファイルを保存する際に、Craft が使用する品質レ -デフォルトでは、フロントエンドの一般ユーザー登録で「パスワード」フィールドを送信する必要があります。`true` をセットすると、最初の登録フォームでパスワードを必要としなくなります。 +By default, Craft will require a 'password' field to be submitted on front-end, public user registrations. Setting this to `true` will no longer require it on the initial registration form. -メールアドレスの確認が有効になっている場合、新しいユーザーは通知メールに記載されたリンクをクリックしてパスワードを設定できます。そうでなければ、「パスワードを忘れた」際のワークフローを経由することがパスワードをセットできる唯一の方法となります。 +If you have email verification enabled, new users will set their password once they've clicked on the verification link in the email. If you don't, the only way they can set their password is to go through your "forgot password" workflow. @@ -814,7 +823,7 @@ JPG と PNG ファイルを保存する際に、Craft が使用する品質レ -システムを [Dev Mode](https://craftcms.com/support/dev-mode) で実行するかどうか。 +Whether the system should run in [Dev Mode](https://craftcms.com/support/dev-mode). @@ -835,9 +844,14 @@ JPG と PNG ファイルを保存する際に、Craft が使用する品質レ [GeneralConfig::$disabledPlugins](api:craft\config\GeneralConfig::$disabledPlugins) +Since +: + +3.1.9 -プロジェクトコンフィグの内容に関わらず無効にする、プラグインハンドルの配列。 + +Array of plugin handles that should be disabled, regardless of what the project config says. ```php 'dev' => [ @@ -864,11 +878,11 @@ JPG と PNG ファイルを保存する際に、Craft が使用する品質レ -機密性の高い操作（例：ユーザーのグループや権限の割り当てなど）に必要な、ユーザーの昇格されたセッションの時間。 +The amount of time a user’s elevated session will last, which is required for some sensitive actions (e.g. user group/permission assignment). -昇格されたセッションのサポートを無効化するには、`0` をセットしてください。 +Set to `0` to disable elevated session support. -サポートされる値の種類は、[craft\helpers\ConfigHelper::durationInSeconds()](https://docs.craftcms.com/api/v3/craft-helpers-confighelper.html#method-durationinseconds) のリストを参照してください。 +See [craft\helpers\ConfigHelper::durationInSeconds()](https://docs.craftcms.com/api/v3/craft-helpers-confighelper.html#method-durationinseconds) for a list of supported value types. @@ -891,7 +905,7 @@ JPG と PNG ファイルを保存する際に、Craft が使用する品質レ -[enableCsrfProtection](https://docs.craftcms.com/api/v3/craft-config-generalconfig.html#enablecsrfprotection) が有効な場合、CSRF トークンを保持するために Cookie を使用するかどうか。false の場合、CSRF トークンはコンフィグ設定名 `csrfTokenName` 配下のセッション内に保管されます。セッションの CSRF トークンを保存することでセキュリティが向上している間は、CSRF トークンをすべてのページでセッションを開始する必要があるため、サイトのパフォーマンスが低下する可能性がある点に注意してください。 +Whether to use a cookie to persist the CSRF token if is enabled. If false, the CSRF token will be stored in session under the `csrfTokenName` config setting name. Note that while storing CSRF tokens in session increases security, it requires starting a session for every page that a CSRF token is needed, which may degrade site performance. @@ -914,7 +928,7 @@ JPG と PNG ファイルを保存する際に、Craft が使用する品質レ -Craft 経由で送信されるすべてのフォームで、不可視項目による CSRF 保護を有効にするかどうか。 +Whether to enable CSRF protection via hidden form inputs for all forms submitted via Craft. @@ -935,15 +949,20 @@ Craft 経由で送信されるすべてのフォームで、不可視項目に [GeneralConfig::$enableTemplateCaching](api:craft\config\GeneralConfig::$enableGql) +Since +: +3.3.1 -グローバル基準で Craft テンプレートの `{% cache %}` タグを有効にするかどうか。 -エラーテンプレートを探すためのパスを決定するときに、HTTP エラーステータスコードの前につける接頭辞。 +Whether the GraphQL API should be enabled. +Note that the GraphQL API is only available for Craft Pro. -### `errorTemplatePrefix` + + +### `enableGraphQlCaching` 許可される型 : @@ -958,15 +977,47 @@ Craft 経由で送信されるすべてのフォームで、不可視項目に 定義元 : -[GeneralConfig::$errorTemplatePrefix](api:craft\config\GeneralConfig::$enableTemplateCaching) +[GeneralConfig::$enableGraphQlCaching](api:craft\config\GeneralConfig::$enableGraphQlCaching) + +Since +: + +3.3.12 -例えば `'_'` がセットされている場合、サイトの 404 テンプレートは`templates/_404.html` となります。 +Whether Craft should cache GraphQL queries. +If set to `true`, Craft will cache the results for unique GraphQL queries per access token. The cache is automatically invalidated any time an element is saved, the site structure is updated, or a GraphQL schema is saved. +This setting will have no effect if a plugin is using the [craft\services\Gql::EVENT_BEFORE_EXECUTE_GQL_QUERY](https://docs.craftcms.com/api/v3/craft-services-gql.html#event-before-execute-gql-query) event to provide its own caching logic and setting the `result` property. + + + +### `enableTemplateCaching` + +許可される型 +: + +[boolean](http://php.net/language.types.boolean) + +デフォルト値 +: + +`true` + +定義元 +: + +[GeneralConfig::$enableTemplateCaching](api:craft\config\GeneralConfig::$enableTemplateCaching) + + + +Whether to enable Craft's template `{% cache %}` tag on a global basis. -### `extraAllowedFileExtensions` + + +### `errorTemplatePrefix` 許可される型 : @@ -981,17 +1032,17 @@ Craft 経由で送信されるすべてのフォームで、不可視項目に 定義元 : -[GeneralConfig::$extraAllowedFileExtensions](api:craft\config\GeneralConfig::$errorTemplatePrefix) +[GeneralConfig::$errorTemplatePrefix](api:craft\config\GeneralConfig::$errorTemplatePrefix) -コンフィグ設定 [allowedFileExtensions](https://docs.craftcms.com/api/v3/craft-config-generalconfig.html#allowedfileextensions) にマージされるファイル拡張子のリスト。 +The prefix that should be prepended to HTTP error status codes when determining the path to look for an error’s template. -アプリケーションがサポートすべき追加のロケール ID のリストで、ユーザーが優先言語として選択できる必要があります。 +If set to `'_'`, then your site’s 404 template would live at `templates/_404.html`, for example. -### `extraAppLocales` +### `extraAllowedFileExtensions` 許可される型 : @@ -1001,20 +1052,20 @@ Craft 経由で送信されるすべてのフォームで、不可視項目に デフォルト値 : -`null` +`[]` 定義元 : -[GeneralConfig::$extraAppLocales](api:craft\config\GeneralConfig::$extraAllowedFileExtensions) +[GeneralConfig::$extraAllowedFileExtensions](api:craft\config\GeneralConfig::$extraAllowedFileExtensions) -サーバーに Intl PHP エクステンションがあるか、対応する[ロケールデータ](https://github.com/craftcms/locales)を `config/locales/` フォルダに保存している場合のみ、この設定を使用してください。 +List of file extensions that will be merged into the config setting. -### `extraFileKinds` +### `extraAppLocales` 許可される型 : @@ -1024,24 +1075,27 @@ Craft 経由で送信されるすべてのフォームで、不可視項目に デフォルト値 : -`[]` +`null` 定義元 : -[GeneralConfig::$extraFileKinds](api:craft\config\GeneralConfig::$extraAppLocales) +[GeneralConfig::$extraAppLocales](api:craft\config\GeneralConfig::$extraAppLocales) +Since +: +3.0.24 -Craft がサポートすべき追加のファイル種類のリスト。この配列は `\craft\config\craft\helpers\Assets::_buildFileKinds()` 内で定義されたものとマージされます。 -::: tip -ここにリストされたファイル拡張子が、即座にアップロードを許可されるわけではありません。コンフィグ設定 [extraAllowedFileExtensions](https://docs.craftcms.com/api/v3/craft-config-generalconfig.html#extraallowedfileextensions) でそれらをリストする必要もあります。 -::: +List of extra locale IDs that the application should support, and users should be able to select as their Preferred Language. +Only use this setting if your server has the Intl PHP extension, or if you’ve saved the corresponding [locale data](https://github.com/craftcms/locales) into your `config/locales/` folder. -### `filenameWordSeparator` + + +### `extraFileKinds` 許可される型 : @@ -1051,16 +1105,21 @@ Craft がサポートすべき追加のファイル種類のリスト。この デフォルト値 : -`'-'` +`[]` 定義元 : -[GeneralConfig::$filenameWordSeparator](api:craft\config\GeneralConfig::$extraFileKinds) +[GeneralConfig::$extraFileKinds](api:craft\config\GeneralConfig::$extraFileKinds) + +Since +: + +3.0.37 -アセットをアップロードする際に、単語を区切るために使用する文字列。`false` の場合、空白だけが残ります。 +List of additional file kinds Craft should support. This array will get merged with the one defined in `\craft\helpers\Assets::_buildFileKinds()`. ```php 'extraFileKinds' => [ @@ -1076,11 +1135,13 @@ Craft がサポートすべき追加のファイル種類のリスト。この ], ``` -ページの読み込み前に画像の変形によるサムネイルの生成をするかどうか。 +::: tip +File extensions listed here won’t immediately be allowed to be uploaded. You will also need to list them with the config setting. +::: -### `generateTransformsBeforePageLoad` +### `filenameWordSeparator` 許可される型 : @@ -1090,20 +1151,20 @@ Craft がサポートすべき追加のファイル種類のリスト。この デフォルト値 : -`false` +`'-'` 定義元 : -[GeneralConfig::$generateTransformsBeforePageLoad](api:craft\config\GeneralConfig::$filenameWordSeparator) +[GeneralConfig::$filenameWordSeparator](api:craft\config\GeneralConfig::$filenameWordSeparator) -Craft が画像の削除や変形で使用するイメージドライバ。デフォルトでは、Craft はインストールされている ImageMagick を自動検出し、そうでない場合は GD をフォールバックします。明示的に `'imagick'` または `'gd'` をセットして、その振る舞いを上書きすることができます。 +The string to use to separate words when uploading Assets. If set to `false`, spaces will be left alone. -### `imageDriver` +### `generateTransformsBeforePageLoad` 許可される型 : @@ -1113,20 +1174,20 @@ Craft が画像の削除や変形で使用するイメージドライバ。デ デフォルト値 : -`self::IMAGE_DRIVER_AUTO` +`['index']` 定義元 : -[GeneralConfig::$imageDriver](api:craft\config\GeneralConfig::$generateTransformsBeforePageLoad) +[GeneralConfig::$generateTransformsBeforePageLoad](api:craft\config\GeneralConfig::$generateTransformsBeforePageLoad) -フロントエンドでテンプレートパスとファイルの照合をする際に、Craft がディレクトリ内で探すディレクトリの「インデックス」テンプレートに相当するテンプレートファイル名。 +Whether images transforms should be generated before page load. -### `indexTemplateFilenames` +### `headlessMode` 許可される型 : @@ -1136,395 +1197,429 @@ Craft が画像の削除や変形で使用するイメージドライバ。デ デフォルト値 : -`['index']` +`false` 定義元 : -[GeneralConfig::$indexTemplateFilenames](api:craft\config\GeneralConfig::$headlessMode) +[GeneralConfig::$headlessMode](api:craft\config\GeneralConfig::$headlessMode) + +Since +: + +3.3.0 -Craft がアカウントをロックするかを決定するために、ユーザーの無効なログイン試行を追跡する時間。 +Bool Whether the system should run in Headless Mode, which optimizes the system and control panel for headless CMS implementations. -サポートされる値の種類は、[craft\helpers\ConfigHelper::durationInSeconds()](https://docs.craftcms.com/api/v3/craft-helpers-confighelper.html#method-durationinseconds) のリストを参照してください。 +When this is enabled, the following changes will take place: -- `{path}` - バックアップファイルのパス +- Template settings for sections and category groups will be hidden. - `{port}` -現在のデータベースポート - `{server}` - 現在のデータベースホスト名 - `{user}` -データベースのに接続するユーザー - `{database}` - 現在のデータベース名 +- The , , , and settings will be ignored. -### `invalidLoginWindowDuration` +### `imageDriver` -許可される型 +Allowed types : `mixed` -デフォルト値 +Default value : -`3600` +`self::IMAGE_DRIVER_AUTO` -定義元 +Defined by : -[GeneralConfig::$invalidLoginWindowDuration](api:craft\config\GeneralConfig::$imageDriver) +[GeneralConfig::$imageDriver](api:craft\config\GeneralConfig::$imageDriver) -ユーザートークンの検証が失敗した際に、Craft がリダイレクトする URI。トークンは、ユーザーアカウントのパスワードの設定やリセットで利用されます。フロントエンドサイトのリクエストのみに影響することに注意してください。 +The image driver Craft should use to cleanse and transform images. By default Craft will auto-detect if ImageMagick is installed and fallback to GD if not. You can explicitly set either `'imagick'` or `'gd'` here to override that behavior. -### `invalidUserTokenPath` +### `indexTemplateFilenames` -許可される型 +Allowed types : [string](http://php.net/language.types.string)[] -デフォルト値 +Default value : -`''` +`['index']` -定義元 +Defined by : -[GeneralConfig::$invalidUserTokenPath](api:craft\config\GeneralConfig::$indexTemplateFilenames) +[GeneralConfig::$indexTemplateFilenames](api:craft\config\GeneralConfig::$indexTemplateFilenames) -サポートされる値の種類は、[craft\helpers\ConfigHelper::localizedValue()](https://docs.craftcms.com/api/v3/craft-helpers-confighelper.html#method-localizedvalue) のリストを参照してください。 +The template filenames Craft will look for within a directory to represent the directory’s “index” template when matching a template path to a file on the front end. -### `ipHeaders` +### `invalidLoginWindowDuration` -許可される型 +Allowed types : `mixed` -デフォルト値 +Default value : -`null` +`3600` -定義元 +Defined by : -[GeneralConfig::$ipHeaders](api:craft\config\GeneralConfig::$invalidLoginWindowDuration) +[GeneralConfig::$invalidLoginWindowDuration](api:craft\config\GeneralConfig::$invalidLoginWindowDuration) -プロキシが実際のクライアント IP を保管するヘッダーのリスト。 +The amount of time to track invalid login attempts for a user, for determining if Craft should lock an account. -詳細については、[yii\web\Request::$ipHeaders](https://www.yiiframework.com/doc/api/2.0/yii-web-request#$ipHeaders-detail) を参照してください。 +See [craft\helpers\ConfigHelper::durationInSeconds()](https://docs.craftcms.com/api/v3/craft-helpers-confighelper.html#method-durationinseconds) for a list of supported value types. -### `isSystemLive` +### `invalidUserTokenPath` -許可される型 +Allowed types : `mixed` -デフォルト値 +Default value : `''` -定義元 +Defined by : -[GeneralConfig::$isSystemLive](api:craft\config\GeneralConfig::$invalidUserTokenPath) +[GeneralConfig::$invalidUserTokenPath](api:craft\config\GeneralConfig::$invalidUserTokenPath) -設定されていない場合、デフォルトで [craft\web\Request::$ipHeaders](https://docs.craftcms.com/api/v3/craft-web-request.html#ipheaders) 値が使用されます。 +The URI Craft should redirect to when user token validation fails. A token is used on things like setting and resetting user account passwords. Note that this only affects front-end site requests. -サイトが現在稼働しているかどうか。`true` または `false` をセットしている場合、「設定 > 一般」のシステムのステータス設定よりも優先されます。 +See [craft\helpers\ConfigHelper::localizedValue()](https://docs.craftcms.com/api/v3/craft-helpers-confighelper.html#method-localizedvalue) for a list of supported value types. -### `limitAutoSlugsToAscii` +### `ipHeaders` -許可される型 +Allowed types : [string](http://php.net/language.types.string)[], [null](http://php.net/language.types.null) -デフォルト値 +Default value : -`false` +`null` -定義元 +Defined by : -[GeneralConfig::$limitAutoSlugsToAscii](api:craft\config\GeneralConfig::$ipHeaders) +[GeneralConfig::$ipHeaders](api:craft\config\GeneralConfig::$ipHeaders) -自動生成されたスラグの ASCII 以外の文字を ASCII に変換するかどうか（例： ñ → n）。 +List of headers where proxies store the real client IP. -::: tip -これは JavaScript によって自動生成されるスラグのみ影響します。手動で入力した場合、ASCII 以外の文字をスラグに使用できます。 -::: +See [yii\web\Request::$ipHeaders](https://www.yiiframework.com/doc/api/2.0/yii-web-request#$ipHeaders-detail) for more details. -Craft がフロントエンドのユーザーログインに使用する URI。 +If not set, the default [craft\web\Request::$ipHeaders](https://docs.craftcms.com/api/v3/craft-web-request.html#ipheaders) value will be used. -### `loginPath` +### `isSystemLive` -許可される型 +Allowed types : [boolean](http://php.net/language.types.boolean), [null](http://php.net/language.types.null) -デフォルト値 +Default value : -`'login'` +`null` -定義元 +Defined by : -[GeneralConfig::$loginPath](api:craft\config\GeneralConfig::$isSystemLive) +[GeneralConfig::$isSystemLive](api:craft\config\GeneralConfig::$isSystemLive) -サポートされる値の種類は、[craft\helpers\ConfigHelper::localizedValue()](https://docs.craftcms.com/api/v3/craft-helpers-confighelper.html#method-localizedvalue) のリストを参照してください。 +Whether the site is currently live. If set to `true` or `false`, it will take precedence over the System Status setting in Settings → General. -### `logoutPath` +### `limitAutoSlugsToAscii` -許可される型 +Allowed types : [boolean](http://php.net/language.types.boolean) -デフォルト値 +Default value : -`'logout'` +`false` -定義元 +Defined by : -[GeneralConfig::$logoutPath](api:craft\config\GeneralConfig::$limitAutoSlugsToAscii) +[GeneralConfig::$limitAutoSlugsToAscii](api:craft\config\GeneralConfig::$limitAutoSlugsToAscii) -Craft がフロントエンドのユーザーログアウトに使用する URI。 +Whether non-ASCII characters in auto-generated slugs should be converted to ASCII (i.e. ñ → n). -サポートされる値の種類は、[craft\helpers\ConfigHelper::localizedValue()](https://docs.craftcms.com/api/v3/craft-helpers-confighelper.html#method-localizedvalue) のリストを参照してください。 +::: tip +This only affects the JavaScript auto-generated slugs. Non-ASCII characters can still be used in slugs if entered manually. +::: -### `maxCachedCloudImageSize` +### `loginPath` -許可される型 +Allowed types : `mixed` -デフォルト値 +Default value : -`2000` +`'login'` -定義元 +Defined by : -[GeneralConfig::$maxCachedCloudImageSize](api:craft\config\GeneralConfig::$loginPath) +[GeneralConfig::$loginPath](api:craft\config\GeneralConfig::$loginPath) -変換で使用する外部ソースから画像をキャッシュする際に使用する最大の寸法サイズ。キャッシュを無効化するには、`0` をセットしてください。 +The URI Craft should use for user login on the front-end. -ロックされる前のアカウントが指定期間内で Craft に許可される、無効なログイン試行の回数。 +This can be set to `false` to disable front-end login. +See [craft\helpers\ConfigHelper::localizedValue()](https://docs.craftcms.com/api/v3/craft-helpers-confighelper.html#method-localizedvalue) for a list of supported value types. -### `maxInvalidLogins` -許可される型 +### `logoutPath` + +Allowed types : `mixed` -デフォルト値 +Default value : -`5` +`'logout'` -定義元 +Defined by : -[GeneralConfig::$maxInvalidLogins](api:craft\config\GeneralConfig::$logoutPath) +[GeneralConfig::$logoutPath](api:craft\config\GeneralConfig::$logoutPath) -諦めてエラーにする前に、Craft がそれをユニークにするためにスラグへ追加する最高の数。 +The URI Craft should use for user logout on the front-end. -許可される最大のアップロードファイルサイズ。 +This can be set to `false` to disable front-end logout. +See [craft\helpers\ConfigHelper::localizedValue()](https://docs.craftcms.com/api/v3/craft-helpers-confighelper.html#method-localizedvalue) for a list of supported value types. -### `maxSlugIncrement` -許可される型 +### `maxBackups` + +Allowed types : -[integer](http://php.net/language.types.integer) +[integer](http://php.net/language.types.integer), [false](http://php.net/language.types.boolean) -デフォルト値 +Default value : -`100` +`20` -定義元 +Defined by : -[GeneralConfig::$maxSlugIncrement](api:craft\config\GeneralConfig::$maxCachedCloudImageSize) +[GeneralConfig::$maxBackups](api:craft\config\GeneralConfig::$maxBackups) -サポートされる値の種類は、[craft\helpers\ConfigHelper::sizeInBytes()](https://docs.craftcms.com/api/v3/craft-helpers-confighelper.html#method-sizeinbytes) のリストを参照してください。 +The number of backups that Craft should make before it starts deleting the oldest backups. If it is set to `false`, then Craft will not delete any backups. -### `maxUploadFileSize` +### `maxCachedCloudImageSize` -許可される型 +Allowed types : [integer](http://php.net/language.types.integer) -デフォルト値 +Default value : -`661e8.0004774116777216` +`2000` -定義元 +Defined by : -[GeneralConfig::$maxUploadFileSize](api:craft\config\GeneralConfig::$maxInvalidLogins) +[GeneralConfig::$maxCachedCloudImageSize](api:craft\config\GeneralConfig::$maxCachedCloudImageSize) -生成された URL が `index.php` を省略するかどうか（例：`http://domain.com/index.php/path` の代わりに `http://domain.com/path`）。 +The maximum dimension size to use when caching images from external sources to use in transforms. Set to `0` to never cache them. -### `omitScriptNameInUrls` +### `maxInvalidLogins` -許可される型 +Allowed types : -[integer](http://php.net/language.types.integer), [null](http://php.net/language.types.null) +[integer](http://php.net/language.types.integer) -デフォルト値 +Default value : -`false` +`5` -定義元 +Defined by : -[GeneralConfig::$omitScriptNameInUrls](api:craft\config\GeneralConfig::$maxRevisions) +[GeneralConfig::$maxInvalidLogins](api:craft\config\GeneralConfig::$maxInvalidLogins) -これは、例えば Craft に付属している `.htaccess` にリダイレクトが見つかるなど、404 を `index.php` にリダイレクトするようサーバーが設定されている場合のみ可能です。 +The number of invalid login attempts Craft will allow within the specified duration before the account gets locked. -Craft が画質を著しく低下させることなく、画像のファイルサイズを減らす最適化をするかどうか。 （ImageMagick を使用している場合のみ、サポートされます。） +### `maxRevisions` -### `optimizeImageFilesize` +Allowed types +: -許可される型 +[integer](http://php.net/language.types.integer), [null](http://php.net/language.types.null) + +Default value : -[boolean](http://php.net/language.types.integer) +`50` -デフォルト値 +Defined by : -`true` +[GeneralConfig::$maxRevisions](api:craft\config\GeneralConfig::$maxRevisions) -定義元 +Since : -[GeneralConfig::$optimizeImageFilesize](api:craft\config\GeneralConfig::$maxSlugIncrement) +3.2.0 -現在のリクエストがページ分割されたリストに含まれる特定ページのものかどうかを決定する際に、Craft が探す数値の前にある文字列。 +The maximum number of revisions that should be stored for each element. +Set to `0` if you want to store an unlimited number of revisions. -### `pageTrigger` -許可される型 +### `maxSlugIncrement` + +Allowed types : -[integer](http://php.net/language.types.integer), [string](http://php.net/language.types.string) +[integer](http://php.net/language.types.integer) -デフォルト値 +Default value : -`'p'` +`100` -定義元 +Defined by : -[GeneralConfig::$pageTrigger](api:craft\config\GeneralConfig::$maxUploadFileSize) - +[GeneralConfig::$maxSlugIncrement](api:craft\config\GeneralConfig::$maxSlugIncrement) -::: tip -これを `?p`（例：`/news?p=5`）にセットしたい場合、デフォルトで `p` がセットされている [pathParam](https://docs.craftcms.com/api/v3/craft-config-generalconfig.html#pathparam) 設定も変更する必要があります。さらにサーバーが Apache で稼働している場合、新しい `pathParam` 値とマッチするよう `.htaccess` ファイル内のリダイレクトコードをアップデートする必要があります。 -::: -リクエストのパスを決定する際に、Craft がチェックするクエリ文字列のパラメータ。 +The highest number Craft will tack onto a slug in order to make it unique before giving up and throwing an error. -### `pathParam` +### `maxUploadFileSize` -許可される型 +Allowed types : -[string](http://php.net/language.types.boolean) +[integer](http://php.net/language.types.integer), [string](http://php.net/language.types.string) -デフォルト値 +Default value : -`'p'` +`16777216` -定義元 +Defined by : -[GeneralConfig::$pathParam](api:craft\config\GeneralConfig::$omitScriptNameInUrls) +[GeneralConfig::$maxUploadFileSize](api:craft\config\GeneralConfig::$maxUploadFileSize) -::: tip -これを変更し、かつ、サーバーが Apache で稼働している場合、新しい値とマッチするよう `.htaccess` ファイルをアップデートすることを忘れないでください。 -::: +The maximum upload file size allowed. + +See [craft\helpers\ConfigHelper::sizeInBytes()](https://docs.craftcms.com/api/v3/craft-helpers-confighelper.html#method-sizeinbytes) for a list of supported value types. + + + +### `omitScriptNameInUrls` + +Allowed types +: + +[boolean](http://php.net/language.types.boolean) + +Default value +: + +`false` + +Defined by +: + +[GeneralConfig::$omitScriptNameInUrls](api:craft\config\GeneralConfig::$omitScriptNameInUrls) + + + +Whether generated URLs should omit `index.php` (e.g. `http://domain.com/path` instead of `http://domain.com/index.php/path`) -Craft が圧縮、展開、アップデートなどのメモリ集約型の操作中に確保しようと試みるメモリの最大量。デフォルトは空の文字列で、可能な限り多くのメモリを使用することを意味しています。 +This can only be possible if your server is configured to redirect would-be 404's to `index.php`, for example, with the redirect found in the `.htaccess` file that came with Craft: ``` RewriteEngine On @@ -1535,591 +1630,610 @@ RewriteRule (.+) /index.php?p= [QSA,L] -### `phpMaxMemoryLimit` +### `optimizeImageFilesize` -許可される型 +Allowed types : [boolean](http://php.net/language.types.boolean) -デフォルト値 +Default value : -`null` +`true` -定義元 +Defined by : -[GeneralConfig::$phpMaxMemoryLimit](api:craft\config\GeneralConfig::$optimizeImageFilesize) +[GeneralConfig::$optimizeImageFilesize](api:craft\config\GeneralConfig::$optimizeImageFilesize) -受け入れられる値については、 のリストを参照してください。 +Whether Craft should optimize images for reduced file sizes without noticeably reducing image quality. (Only supported when ImageMagick is used.) -### `phpSessionName` +### `pageTrigger` -許可される型 +Allowed types : [string](http://php.net/language.types.string) -デフォルト値 +Default value : -`'CraftSessionId'` +`'p'` -定義元 +Defined by : -[GeneralConfig::$phpSessionName](api:craft\config\GeneralConfig::$pageTrigger) +[GeneralConfig::$pageTrigger](api:craft\config\GeneralConfig::$pageTrigger) -PHP セッション Cookie の名前。 +The string preceding a number which Craft will look for when determining if the current request is for a particular page in a paginated list of pages. -| サンプル値 | サンプル URI | -| ------- | -------------- | -| `p` | `/news/p5` | -| `page` | `/news/page5` | -| `page/` | `/news/page/5` | -| `?page` | `/news?page=5` | +| Example Value | Example URI | +| ------------- | -------------- | +| `p` | `/news/p5` | +| `page` | `/news/page5` | +| `page/` | `/news/page/5` | +| `?page` | `/news?page=5` | -コントロールパネルからログインした後にユーザーをリダイレクトするパス。 +::: tip +If you want to set this to `?p` (e.g. `/news?p=5`), you will need to change your setting as well, which is set to `p` by default, and if your server is running Apache, you will need to update the redirect code in your `.htaccess` file to match your new `pathParam` value. +::: -### `postCpLoginRedirect` +### `pathParam` -許可される型 +Allowed types : [string](http://php.net/language.types.string) -デフォルト値 +Default value : -`'dashboard'` +`'p'` -定義元 +Defined by : -[GeneralConfig::$postCpLoginRedirect](api:craft\config\GeneralConfig::$pathParam) +[GeneralConfig::$pathParam](api:craft\config\GeneralConfig::$pathParam) -すでにログインしているユーザーが CP のログインページ（`/admin/login`）または、CP のルート URL（/admin）にアクセスした場合も、この設定が効力を発揮します。 +The query string param that Craft will check when determining the request's path. -サポートされる値の種類は、[craft\helpers\ConfigHelper::localizedValue()](https://docs.craftcms.com/api/v3/craft-helpers-confighelper.html#method-localizedvalue) のリストを参照してください。 +::: tip +If you change this and your server is running Apache, don’t forget to update the redirect code in your `.htaccess` file to match the new value. +::: -### `postLoginRedirect` +### `phpMaxMemoryLimit` -許可される型 +Allowed types : [string](http://php.net/language.types.string), [null](http://php.net/language.types.null) -デフォルト値 +Default value : -`''` +`null` -定義元 +Defined by : -[GeneralConfig::$postLoginRedirect](api:craft\config\GeneralConfig::$phpMaxMemoryLimit) +[GeneralConfig::$phpMaxMemoryLimit](api:craft\config\GeneralConfig::$phpMaxMemoryLimit) -フロントエンドサイトからログインした後にユーザーをリダイレクトするパス。 +The maximum amount of memory Craft will try to reserve during memory intensive operations such as zipping, unzipping and updating. Defaults to an empty string, which means it will use as much memory as it possibly can. -すでにログインしているユーザーがログインページ（コンフィグ設定の loginPath に明示されているとおり）にアクセスした場合も、効力を発揮します。 +See for a list of acceptable values. -### `postLogoutRedirect` +### `phpSessionName` -許可される型 +Allowed types : [string](http://php.net/language.types.string) -デフォルト値 +Default value : -`''` +`'CraftSessionId'` -定義元 +Defined by : -[GeneralConfig::$postLogoutRedirect](api:craft\config\GeneralConfig::$phpSessionName) +[GeneralConfig::$phpSessionName](api:craft\config\GeneralConfig::$phpSessionName) -サポートされる値の種類は、[craft\helpers\ConfigHelper::localizedValue()](https://docs.craftcms.com/api/v3/craft-helpers-confighelper.html#method-localizedvalue) のリストを参照してください。 +The name of the PHP session cookie. -### `preserveCmykColorspace` +### `postCpLoginRedirect` -許可される型 +Allowed types : `mixed` -デフォルト値 +Default value : -`false` +`'dashboard'` -定義元 +Defined by : -[GeneralConfig::$preserveCmykColorspace](api:craft\config\GeneralConfig::$postCpLoginRedirect) +[GeneralConfig::$postCpLoginRedirect](api:craft\config\GeneralConfig::$postCpLoginRedirect) -フロントエンドサイトからログアウトした後にユーザーをリダイレクトするパス。 +The path that users should be redirected to after logging in from the control panel. -サポートされる値の種類は、[craft\helpers\ConfigHelper::localizedValue()](https://docs.craftcms.com/api/v3/craft-helpers-confighelper.html#method-localizedvalue) のリストを参照してください。 +This setting will also come into effect if a user visits the control panel’s Login page (`/admin/login`) or the control panel’s root URL (/admin) when they are already logged in. -画像を操作するとき、CMYK を色空間として保存するかどうか。 +See [craft\helpers\ConfigHelper::localizedValue()](https://docs.craftcms.com/api/v3/craft-helpers-confighelper.html#method-localizedvalue) for a list of supported value types. -### `preserveExifData` +### `postLoginRedirect` -許可される型 +Allowed types : `mixed` -デフォルト値 +Default value : `''` -定義元 +Defined by : -[GeneralConfig::$preserveExifData](api:craft\config\GeneralConfig::$postLoginRedirect) +[GeneralConfig::$postLoginRedirect](api:craft\config\GeneralConfig::$postLoginRedirect) -`true` をセットすると、Craft は CMYK イメージを sRGB に変換するのを防ぎます。ただし、 ImageMagick のバージョンによっては、イメージに色の歪みを生じることがあります。これは ImageMagick を使用している場合のみ、影響があります。 +The path that users should be redirected to after logging in from the front-end site. -画像を操作するとき、EXIF データを保存するかどうか。 +This setting will also come into effect if the user visits the Login page (as specified by the loginPath config setting) when they are already logged in. -`true` をセットすると、画像ファイルのサイズが大きくなります。 +See [craft\helpers\ConfigHelper::localizedValue()](https://docs.craftcms.com/api/v3/craft-helpers-confighelper.html#method-localizedvalue) for a list of supported value types. -### `preserveImageColorProfiles` +### `postLogoutRedirect` -許可される型 +Allowed types : `mixed` -デフォルト値 +Default value : `''` -定義元 +Defined by : -[GeneralConfig::$preserveImageColorProfiles](api:craft\config\GeneralConfig::$postLogoutRedirect) +[GeneralConfig::$postLogoutRedirect](api:craft\config\GeneralConfig::$postLogoutRedirect) -これは ImageMagick を使用している場合のみ、影響があります。 +The path that users should be redirected to after logging out from the front-end site. -画像を操作するとき、埋め込まれたイメージカラープロファイル（ICC）を保存するかどうか。 +See [craft\helpers\ConfigHelper::localizedValue()](https://docs.craftcms.com/api/v3/craft-helpers-confighelper.html#method-localizedvalue) for a list of supported value types. -### `preventUserEnumeration` +### `preserveCmykColorspace` -許可される型 +Allowed types : [boolean](http://php.net/language.types.boolean) -デフォルト値 +Default value : `false` -定義元 +Defined by : -[GeneralConfig::$preventUserEnumeration](api:craft\config\GeneralConfig::$preserveCmykColorspace) +[GeneralConfig::$preserveCmykColorspace](api:craft\config\GeneralConfig::$preserveCmykColorspace) +Since +: +3.0.8 -`false` に設定すると画像サイズが少し小さくなります。ただし、ImageMagick のバージョンによっては正しくないガンマ値が保存され、とても暗い画像になることがあります。これは ImageMagick を使用している場合のみ、影響があります。 -`false` に設定され、コントロールパネルのログインページの「パスワードを忘れた」ワークフローを通過すると、ユーザー名 / メールアドレスが存在しないのか、または、次の手順のためのメール送信が成功し確認されたのかを示す別個のメッセージが表示されます。これは、レスポンスに基づいてユーザー名 / メールアドレスの列挙を許可します。`true` に設定すると、ユーザーを列挙するのが難しいエラーである場合も、常に正常なレスポンスを受け取るでしょう。 +Whether CMYK should be preserved as the colorspace when manipulating images. +Setting this to `true` will prevent Craft from transforming CMYK images to sRGB, but on some ImageMagick versions it can cause color distortion in the image. This will only have effect if ImageMagick is in use. -### `privateTemplateTrigger` -許可される型 + +### `preserveExifData` + +Allowed types : -[string](http://php.net/language.types.boolean) +[boolean](http://php.net/language.types.boolean) -デフォルト値 +Default value : -`'_'` +`false` -定義元 +Defined by : -[GeneralConfig::$privateTemplateTrigger](api:craft\config\GeneralConfig::$preserveExifData) +[GeneralConfig::$preserveExifData](api:craft\config\GeneralConfig::$preserveExifData) -「プライベート」テンプレート（マッチする URL から直接アクセスできないテンプレート）を識別するために使用するテンプレートパスのセグメントの接頭辞。 +Whether the EXIF data should be preserved when manipulating and uploading images. -公開テンプレートのルーティングを無効化するには、空の値をセットしてください。 +Setting this to `true` will result in larger image file sizes. -有効化されていない保留中のユーザーを Craft がシステムからパージするまでに待機する時間。 +This will only have effect if ImageMagick is in use. -### `purgePendingUsersDuration` +### `preserveImageColorProfiles` -許可される型 +Allowed types : [boolean](http://php.net/language.types.boolean) -デフォルト値 +Default value : -`null` +`true` -定義元 +Defined by : -[GeneralConfig::$purgePendingUsersDuration](api:craft\config\GeneralConfig::$preserveImageColorProfiles) +[GeneralConfig::$preserveImageColorProfiles](api:craft\config\GeneralConfig::$preserveImageColorProfiles) -与えられた時間が経過すると、保留中のユーザーに割り当てられたコンテンツもすべて削除される点に注意してください。 +Whether the embedded Image Color Profile (ICC) should be preserved when manipulating images. -この機能を無効化するには、`0` をセットしてください。 +Setting this to `false` will reduce the image size a little bit, but on some ImageMagick versions can cause images to be saved with an incorrect gamma value, which causes the images to become very dark. This will only have effect if ImageMagick is in use. -### `rememberUsernameDuration` +### `preventUserEnumeration` -許可される型 +Allowed types : [boolean](http://php.net/language.types.boolean) -デフォルト値 +Default value : -`31536000` +`false` -定義元 +Defined by : -[GeneralConfig::$rememberUsernameDuration](api:craft\config\GeneralConfig::$preventUserEnumeration) +[GeneralConfig::$preventUserEnumeration](api:craft\config\GeneralConfig::$preventUserEnumeration) -サポートされる値の種類は、[craft\helpers\ConfigHelper::durationInSeconds()](https://docs.craftcms.com/api/v3/craft-helpers-confighelper.html#method-durationinseconds) のリストを参照してください。 +When set to `false` and you go through the "forgot password" workflow on the control panel login page, for example, you get distinct messages saying if the username/email didn't exist or the email was successfully sent and to check your email for further instructions. This can allow for username/email enumeration based on the response. If set `true`, you will always get a successful response even if there was an error making it difficult to enumerate users. -### `rememberedUserSessionDuration` +### `privateTemplateTrigger` -許可される型 +Allowed types : [string](http://php.net/language.types.string) -デフォルト値 +Default value : -`1209600` +`'_'` -定義元 +Defined by : -[GeneralConfig::$rememberedUserSessionDuration](api:craft\config\GeneralConfig::$privateTemplateTrigger) +[GeneralConfig::$privateTemplateTrigger](api:craft\config\GeneralConfig::$privateTemplateTrigger) -CP ログインページへ自動挿入するために、Craft がユーザー名を記憶しておく時間。 +The template path segment prefix that should be used to identify "private" templates (templates that aren't directly accessible via a matching URL). -この機能を完全に無効化するには、`0` をセットしてください。 +Set to an empty value to disable public template routing. -### `requireMatchingUserAgentForSession` +### `purgePendingUsersDuration` -許可される型 +Allowed types : `mixed` -デフォルト値 +Default value : -`true` +`null` -定義元 +Defined by : -[GeneralConfig::$requireMatchingUserAgentForSession](api:craft\config\GeneralConfig::$purgePendingUsersDuration) +[GeneralConfig::$purgePendingUsersDuration](api:craft\config\GeneralConfig::$purgePendingUsersDuration) -サポートされる値の種類は、[craft\helpers\ConfigHelper::durationInSeconds()](https://docs.craftcms.com/api/v3/craft-helpers-confighelper.html#method-durationinseconds) のリストを参照してください。 +The amount of time to wait before Craft purges pending users from the system that have not activated. -ログインページで「ログイン状態を維持する」がチェックされている場合、ユーザーがログインしたままになる時間。 +Note that any content assigned to a pending user will be deleted as well when the given time interval passes. -「ログイン状態を維持する」機能を完全に無効化するには、`0` をセットしてください。 +Set to `0` to disable this feature. -サポートされる値の種類は、[craft\helpers\ConfigHelper::durationInSeconds()](https://docs.craftcms.com/api/v3/craft-helpers-confighelper.html#method-durationinseconds) のリストを参照してください。 +See [craft\helpers\ConfigHelper::durationInSeconds()](https://docs.craftcms.com/api/v3/craft-helpers-confighelper.html#method-durationinseconds) for a list of supported value types. -### `requireUserAgentAndIpForSession` +### `purgeStaleUserSessionDuration` -許可される型 +Allowed types : `mixed` -デフォルト値 +Default value : -`true` +`7776000` -定義元 +Defined by : -[GeneralConfig::$requireUserAgentAndIpForSession](api:craft\config\GeneralConfig::$purgeStaleUserSessionDuration) +[GeneralConfig::$purgeStaleUserSessionDuration](api:craft\config\GeneralConfig::$purgeStaleUserSessionDuration) +Since +: +3.3.0 -Cookie からユーザーセッションを復元する際に、一致するユーザーエージェントの文字列を Craft が必要とするかどうか。 -新しいユーザーセッションを作成する際に、ユーザーエージェントの文字列と IP アドレスの存在を Craft が必要とするかどうか。 -公開された CP リソースを保管するルートディレクトリのパス。 +The amount of time to wait before Craft purges stale user sessions from the sessions table in the database. +Set to `0` to disable this feature. +See [craft\helpers\ConfigHelper::durationInSeconds()](https://docs.craftcms.com/api/v3/craft-helpers-confighelper.html#method-durationinseconds) for a list of supported value types. -### `resourceBasePath` -許可される型 + +### `purgeUnsavedDraftsDuration` + +Allowed types : `mixed` -デフォルト値 +Default value : -`'@webroot/cpresources'` +`2592000` -定義元 +Defined by +: + +[GeneralConfig::$purgeUnsavedDraftsDuration](api:craft\config\GeneralConfig::$purgeUnsavedDraftsDuration) + +Since : -[GeneralConfig::$resourceBasePath](api:craft\config\GeneralConfig::$purgeUnsavedDraftsDuration) +3.2.0 -公開された CP リソースを保管するルートディレクトリの URL。 +The amount of time to wait before Craft purges drafts of new elements that were never formally saved. -データベースのバックアップを復元するために Craft が実行するシェルコマンド。 +Set to `0` to disable this feature. -ウェブサーバーを実行しているユーザーの `$PATH` 変数にライブラリが含まれている場合、デフォルトで Craft は `mysql` または `psql` を実行します。 +See [craft\helpers\ConfigHelper::durationInSeconds()](https://docs.craftcms.com/api/v3/craft-helpers-confighelper.html#method-durationinseconds) for a list of supported value types. -### `resourceBaseUrl` +### `rememberUsernameDuration` -許可される型 +Allowed types : `mixed` -デフォルト値 +Default value : -`'@web/cpresources'` +`31536000` -定義元 +Defined by : -[GeneralConfig::$resourceBaseUrl](api:craft\config\GeneralConfig::$rememberUsernameDuration) +[GeneralConfig::$rememberUsernameDuration](api:craft\config\GeneralConfig::$rememberUsernameDuration) -ランタイムで Craft がスワップアウトするために利用できるいくつかのトークンがあります。 +The amount of time Craft will remember a username and pre-populate it on the control panel’s Login page. -データベースの復元を完全に無効化するために、`false` をセットすることもできます。 +Set to `0` to disable this feature altogether. -アップロード時の EXIF データに従って、Craft が画像を回転するかどうか。 +See [craft\helpers\ConfigHelper::durationInSeconds()](https://docs.craftcms.com/api/v3/craft-helpers-confighelper.html#method-durationinseconds) for a list of supported value types. -### `restoreCommand` +### `rememberedUserSessionDuration` -許可される型 +Allowed types : `mixed` -デフォルト値 +Default value : -`null` +`1209600` -定義元 +Defined by : -[GeneralConfig::$restoreCommand](api:craft\config\GeneralConfig::$rememberedUserSessionDuration) +[GeneralConfig::$rememberedUserSessionDuration](api:craft\config\GeneralConfig::$rememberedUserSessionDuration) -HTTP リクエストを通して、Craft が保留中のキュージョブを自動的に実行するかどうか。 +The amount of time a user stays logged if “Remember Me” is checked on the login page. -この設定は、サーバーが Win32 を実行している、または、Apache の mod_deflate/mod_gzip がインストールされている場合は、PHP の [flush()](http://php.net/manual/en/function.flush.php) メソッドが動作しないため、無効にする必要があります。 +Set to `0` to disable the “Remember Me” feature altogether. -無効にした場合、代わりのキューランナーを別途セットアップ*しなければなりません*。 +See [craft\helpers\ConfigHelper::durationInSeconds()](https://docs.craftcms.com/api/v3/craft-helpers-confighelper.html#method-durationinseconds) for a list of supported value types. -### `rotateImagesOnUploadByExifData` +### `requireMatchingUserAgentForSession` -許可される型 +Allowed types : [boolean](http://php.net/language.types.boolean) -デフォルト値 +Default value : `true` -定義元 +Defined by : -[GeneralConfig::$rotateImagesOnUploadByExifData](api:craft\config\GeneralConfig::$requireMatchingUserAgentForSession) +[GeneralConfig::$requireMatchingUserAgentForSession](api:craft\config\GeneralConfig::$requireMatchingUserAgentForSession) -これは、1分ごとに実行される cron ジョブからキューランナーを設定する方法の例です。 +Whether Craft should require a matching user agent string when restoring a user session from a cookie. -### `runQueueAutomatically` +### `requireUserAgentAndIpForSession` -許可される型 +Allowed types : [boolean](http://php.net/language.types.boolean) -デフォルト値 +Default value : `true` -定義元 +Defined by : -[GeneralConfig::$runQueueAutomatically](api:craft\config\GeneralConfig::$requireUserAgentAndIpForSession) +[GeneralConfig::$requireUserAgentAndIpForSession](api:craft\config\GeneralConfig::$requireUserAgentAndIpForSession) -Craft がアップロードされた SVG ファイルをサニタイズし、潜在的な悪意のあるコンテンツを取り除くべきかどうか。 +Whether Craft should require the existence of a user agent string and IP address when creating a new user session. -### `sanitizeSvgUploads` +### `resourceBasePath` -許可される型 +Allowed types : -[boolean](http://php.net/language.types.string) +[string](http://php.net/language.types.string) -デフォルト値 +Default value : -`true` +`'@webroot/cpresources'` -定義元 +Defined by : -[GeneralConfig::$sanitizeSvgUploads](api:craft\config\GeneralConfig::$resourceBasePath) +[GeneralConfig::$resourceBasePath](api:craft\config\GeneralConfig::$resourceBasePath) -信頼できないソースから SVG アップロードを許可する場合は、これを確実に有効にするべきです。 +The path to the root directory that should store published control panel resources. -### `secureHeaders` +### `resourceBaseUrl` -許可される型 +Allowed types : [string](http://php.net/language.types.string) -デフォルト値 +Default value : -`null` +`'@web/cpresources'` -定義元 +Defined by : -[GeneralConfig::$secureHeaders](api:craft\config\GeneralConfig::$resourceBaseUrl) +[GeneralConfig::$resourceBaseUrl](api:craft\config\GeneralConfig::$resourceBaseUrl) -デフォルトで、信頼できるホスト設定の適用を受けるヘッダーのリスト。 +The URL to the root directory that should store published control panel resources. -### `secureProtocolHeaders` +### `restoreCommand` -許可される型 +Allowed types : -[array](http://php.net/language.types.array), [null](http://php.net/language.types.null) +[string](http://php.net/language.types.string), [null](http://php.net/language.types.null) -デフォルト値 +Default value : `null` -定義元 +Defined by : -[GeneralConfig::$secureProtocolHeaders](api:craft\config\GeneralConfig::$restoreCommand) +[GeneralConfig::$restoreCommand](api:craft\config\GeneralConfig::$restoreCommand) -詳細については、[yii\web\Request::$secureHeaders](https://www.yiiframework.com/doc/api/2.0/yii-web-request#$secureHeaders-detail) を参照してください。 +The shell command that Craft should execute to restore a database backup. -設定されていない場合、デフォルトで [yii\web\Request::$secureHeaders](https://www.yiiframework.com/doc/api/2.0/yii-web-request#$secureHeaders-detail) 値が使用されます。 +By default Craft will run `mysql` or `psql`, provided that those libraries are in the `$PATH` variable for the user the web server is running as. -HTTPS 経由で接続されるかどうかを決定するための確認を行うヘッダーのリスト。 +There are several tokens you can use that Craft will swap out at runtime: - `{path}` - the backup file path - `{port}` - the current database port @@ -2128,82 +2242,82 @@ HTTPS 経由で接続されるかどうかを決定するための確認を行 - `{database}` - the current database name - `{schema}` - the current database schema (if any) -詳細については、[yii\web\Request::$secureProtocolHeaders](https://www.yiiframework.com/doc/api/2.0/yii-web-request#$secureProtocolHeaders-detail) を参照してください。 +This can also be set to `false` to disable database restores completely. -### `securityKey` +### `rotateImagesOnUploadByExifData` -許可される型 +Allowed types : -[string](http://php.net/language.types.boolean) +[boolean](http://php.net/language.types.boolean) -デフォルト値 +Default value : -`null` +`true` -定義元 +Defined by : -[GeneralConfig::$securityKey](api:craft\config\GeneralConfig::$rotateImagesOnUploadByExifData) +[GeneralConfig::$rotateImagesOnUploadByExifData](api:craft\config\GeneralConfig::$rotateImagesOnUploadByExifData) -設定されていない場合、デフォルトで [yii\web\Request::$secureProtocolHeaders](https://www.yiiframework.com/doc/api/2.0/yii-web-request#$secureProtocolHeaders-detail) 値が使用されます。 +Whether Craft should rotate images according to their EXIF data on upload. -### `sendPoweredByHeader` +### `runQueueAutomatically` -許可される型 +Allowed types : [boolean](http://php.net/language.types.boolean) -デフォルト値 +Default value : `true` -定義元 +Defined by : -[GeneralConfig::$sendPoweredByHeader](api:craft\config\GeneralConfig::$runQueueAutomatically) - - +[GeneralConfig::$runQueueAutomatically](api:craft\config\GeneralConfig::$runQueueAutomatically) -[craft\services\Security](api:craft\services\Security) のデータのハッシングや暗号化に使われる、非公開でランダムな暗号的に安全な鍵。 -この値は、すべての環境で同じであるべきです。この鍵を変更した場合、暗号化されたいかなるデータにもアクセスできなくなることに注意してください。 -`X-Powered-By: Craft CMS` ヘッダーを送信するかどうか。[BuiltWith](https://builtwith.com/) や [Wappalyzer](https://www.wappalyzer.com/) のようなサービスで、サイトが Craft で動作していると判別するのを手伝います。 +Whether Craft should run pending queue jobs automatically when someone visits the control panel. -パスワードリセットのテンプレートパス。フロントエンドサイトのリクエストのみに影響することに注意してください。 +If disabled, an alternate queue worker *must* be set up separately, either as an [always-running daemon](https://github.com/yiisoft/yii2-queue/blob/master/docs/guide/worker.md), or a cron job that runs the `queue/run` command every minute: -```text -/1 * * * * /path/to/project/root/craft queue/run +```cron +* * * * * /path/to/project/craft queue/run ``` +::: tip +This setting should be disabled for servers running Win32, or with Apache’s mod_deflate/mod_gzip installed, where PHP’s [flush()](http://php.net/manual/en/function.flush.php) method won’t work. +::: -### `setPasswordPath` -許可される型 +### `sameSiteCookieValue` + +Allowed types : [string](http://php.net/language.types.string) -デフォルト値 +Default value : -`'setpassword'` +`null` -定義元 +Defined by : -[GeneralConfig::$setPasswordPath](api:craft\config\GeneralConfig::$sameSiteCookieValue) +[GeneralConfig::$sameSiteCookieValue](api:craft\config\GeneralConfig::$sameSiteCookieValue) Since : @@ -2212,240 +2326,246 @@ Since -サポートされる値の種類は、[craft\helpers\ConfigHelper::localizedValue()](https://docs.craftcms.com/api/v3/craft-helpers-confighelper.html#method-localizedvalue) のリストを参照してください。 +The [SameSite](https://www.owasp.org/index.php/SameSite) value that should be set on Craft cookies, if any. -Craft がフロントエンドからパスワードを設定したユーザーをリダイレクトさせる URI。 +This can be set to `'Lax'`, `'Strict'`, or `null`. -サポートされる値の種類は、[craft\helpers\ConfigHelper::localizedValue()](https://docs.craftcms.com/api/v3/craft-helpers-confighelper.html#method-localizedvalue) のリストを参照してください。 +::: tip +This setting requires PHP 7.3 or later. +::: -### `setPasswordSuccessPath` +### `sanitizeSvgUploads` -許可される型 +Allowed types : [boolean](http://php.net/language.types.boolean) -デフォルト値 +Default value : -`''` +`true` -定義元 +Defined by : -[GeneralConfig::$setPasswordSuccessPath](api:craft\config\GeneralConfig::$sanitizeSvgUploads) +[GeneralConfig::$sanitizeSvgUploads](api:craft\config\GeneralConfig::$sanitizeSvgUploads) -サイト名。セットされている場合、「設定 > サイト > 名前」で設定された名称よりも優先されます。 +Whether Craft should sanitize uploaded SVG files and strip out potential malicious looking content. -プライマリサイトの名前だけを上書きするための文字列、または、サイトのハンドルをキーとして使用する配列をセットできます。 +This should definitely be enabled if you are accepting SVG uploads from untrusted sources. -### `siteName` +### `secureHeaders` -許可される型 +Allowed types : -[string](http://php.net/language.types.string), [string](http://php.net/language.types.string)[] +[array](http://php.net/language.types.array), [null](http://php.net/language.types.null) -デフォルト値 +Default value : `null` -定義元 +Defined by : -[GeneralConfig::$siteName](api:craft\config\GeneralConfig::$secureHeaders) +[GeneralConfig::$secureHeaders](api:craft\config\GeneralConfig::$secureHeaders) -サイトのベース URL。セットされている場合、「設定 > サイト > ベース URL」で設定されたベース URLよりも優先されます。 +Lists of headers that are, by default, subject to the trusted host configuration. -プライマリサイトのベース URL だけを上書きするための文字列、または、サイトのハンドルをキーとして使用する配列をセットできます。 +See [yii\web\Request::$secureHeaders](https://www.yiiframework.com/doc/api/2.0/yii-web-request#$secureHeaders-detail) for more details. -URL は `http://`、`https://`、`//`（プロトコル相対）、または、[エイリアス](https://docs.craftcms.com/api/v3/craft-config-generalconfig.html#aliases)のいずれかではじまる必要があります。 +If not set, the default [yii\web\Request::$secureHeaders](https://www.yiiframework.com/doc/api/2.0/yii-web-request#$secureHeaders-detail) value will be used. -### `siteUrl` +### `secureProtocolHeaders` -許可される型 +Allowed types : -[string](http://php.net/language.types.string), [string](http://php.net/language.types.string)[] +[array](http://php.net/language.types.array), [null](http://php.net/language.types.null) -デフォルト値 +Default value : `null` -定義元 +Defined by : -[GeneralConfig::$siteUrl](api:craft\config\GeneralConfig::$secureProtocolHeaders) +[GeneralConfig::$secureProtocolHeaders](api:craft\config\GeneralConfig::$secureProtocolHeaders) -スラグの単語を区切るために使用する文字。 +List of headers to check for determining whether the connection is made via HTTPS. -ソフトデリートされたアイテムが、ガベージコレクションによって完全に削除されるまでの時間。 +See [yii\web\Request::$secureProtocolHeaders](https://www.yiiframework.com/doc/api/2.0/yii-web-request#$secureProtocolHeaders-detail) for more details. -ソフトデリートされたアイテムを削除したくない場合、`0` をセットしてください。 +If not set, the default [yii\web\Request::$secureProtocolHeaders](https://www.yiiframework.com/doc/api/2.0/yii-web-request#$secureProtocolHeaders-detail) value will be used. -### `slugWordSeparator` +### `securityKey` -許可される型 +Allowed types : [string](http://php.net/language.types.string) -デフォルト値 +Default value : -`'-'` +`null` -定義元 +Defined by : -[GeneralConfig::$slugWordSeparator](api:craft\config\GeneralConfig::$securityKey) +[GeneralConfig::$securityKey](api:craft\config\GeneralConfig::$securityKey) -サポートされる値の種類は、[craft\helpers\ConfigHelper::durationInSeconds()](https://docs.craftcms.com/api/v3/craft-helpers-confighelper.html#method-durationinseconds) のリストを参照してください。 +A private, random, cryptographically-secure key that is used for hashing and encrypting data in [craft\services\Security](api:craft\services\Security). -ユーザーの IP アドレスがシステムによって保存 / 記録されるべきかどうか。 +This value should be the same across all environments. Note that if this key ever changes, any data that was encrypted with it will be inaccessible. -### `softDeleteDuration` +### `sendPoweredByHeader` -許可される型 +Allowed types : [boolean](http://php.net/language.types.boolean) -デフォルト値 +Default value : -`2592000` +`true` -定義元 +Defined by : -[GeneralConfig::$softDeleteDuration](api:craft\config\GeneralConfig::$sendPoweredByHeader) +[GeneralConfig::$sendPoweredByHeader](api:craft\config\GeneralConfig::$sendPoweredByHeader) -Twig のランタイムエラーを抑制するかどうか。 +Whether an `X-Powered-By: Craft CMS` header should be sent, helping services like [BuiltWith](https://builtwith.com/) and [Wappalyzer](https://www.wappalyzer.com/) identify that the site is running on Craft. -### `storeUserIps` +### `setPasswordPath` -許可される型 +Allowed types : `mixed` -デフォルト値 +Default value : -`false` +`'setpassword'` -定義元 +Defined by : -[GeneralConfig::$storeUserIps](api:craft\config\GeneralConfig::$setPasswordPath) +[GeneralConfig::$setPasswordPath](api:craft\config\GeneralConfig::$setPasswordPath) -`true` をセットすると、エラーは Craft のログファイルに記録されます。 +The URI Craft should use for Set Password forms on the front-end. -すべてのシステムメールをテスト目的の単一のメールアドレス、または、メールアドレスの配列へ送信するよう、Craft を設定します。 +See [craft\helpers\ConfigHelper::localizedValue()](https://docs.craftcms.com/api/v3/craft-helpers-confighelper.html#method-localizedvalue) for a list of supported value types. +::: tip +You might also want to set in case a user clicks on an expired password reset link. +::: -### `suppressTemplateErrors` -許可される型 +### `setPasswordSuccessPath` + +Allowed types : `mixed` -デフォルト値 +Default value : `''` -定義元 +Defined by : -[GeneralConfig::$suppressTemplateErrors](api:craft\config\GeneralConfig::$setPasswordSuccessPath) +[GeneralConfig::$setPasswordSuccessPath](api:craft\config\GeneralConfig::$setPasswordSuccessPath) -デフォルトでは受信者名は「テスト受信者」になりますが、`['email@address.com' => 'Name']` の形式で値をカスタマイズできます。 +The URI Craft should redirect users to after setting their password from the front-end. -サイトのタイムゾーン。セットされている場合、「設定 > 一般」で設定されたタイムゾーンよりも優先されます。 +See [craft\helpers\ConfigHelper::localizedValue()](https://docs.craftcms.com/api/v3/craft-helpers-confighelper.html#method-localizedvalue) for a list of supported value types. -### `testToEmailAddress` +### `siteName` -許可される型 +Allowed types : -[string](http://php.net/language.types.string), [array](http://php.net/language.types.array), [false](http://php.net/language.types.boolean), [null](http://php.net/language.types.null) +[string](http://php.net/language.types.string), [string](http://php.net/language.types.string)[] -デフォルト値 +Default value : `null` -定義元 +Defined by : -[GeneralConfig::$testToEmailAddress](api:craft\config\GeneralConfig::$siteName) +[GeneralConfig::$siteName](api:craft\config\GeneralConfig::$siteName) -これは、PHP の [supported timezones](http://php.net/manual/en/timezones.php) の1つをセットできます。 +The site name(s). If set, it will take precedence over the Name settings in Settings → Sites → [Site Name]. -Craft のトークンがセットされるクエリ文字列パラメータ名。 +This can be set to a string, which will override the primary site’s name only, or an array with site handles used as the keys. -### `timezone` +### `siteUrl` -許可される型 +Allowed types : -[string](http://php.net/language.types.string), [null](http://php.net/language.types.null) +[string](http://php.net/language.types.string), [string](http://php.net/language.types.string)[] -デフォルト値 +Default value : `null` -定義元 +Defined by : -[GeneralConfig::$timezone](api:craft\config\GeneralConfig::$siteUrl) +[GeneralConfig::$siteUrl](api:craft\config\GeneralConfig::$siteUrl) -GIF ファイルを綺麗にしたり、変形したりするかどうか。 +The base URL to the site(s). If set, it will take precedence over the Base URL settings in Settings → Sites → [Site Name]. -`Craft::t()` または `|translate` フィルタを通して実行されていない文字列を見つけるために、翻訳されたメッセージを特殊文字で囲むかどうか。 +This can be set to a string, which will override the primary site’s base URL only, or an array with site handles used as the keys. -信頼されるセキュリティ関連のヘッダーの設定。 +The URL(s) must begin with either `http://`, `https://`, `//` (protocol-relative), or an [alias](config:aliases). ```php 'siteUrl' => [ @@ -2456,345 +2576,391 @@ GIF ファイルを綺麗にしたり、変形したりするかどうか。 -### `tokenParam` +### `slugWordSeparator` -許可される型 +Allowed types : [string](http://php.net/language.types.string) -デフォルト値 +Default value : -`'token'` +`'-'` -定義元 +Defined by : -[GeneralConfig::$tokenParam](api:craft\config\GeneralConfig::$slugWordSeparator) +[GeneralConfig::$slugWordSeparator](api:craft\config\GeneralConfig::$slugWordSeparator) -詳細については、[yii\web\Request::$trustedHosts](https://www.yiiframework.com/doc/api/2.0/yii-web-request#$trustedHosts-detail) を参照してください。 +The character(s) that should be used to separate words in slugs. -### `transformGifs` +### `softDeleteDuration` -許可される型 +Allowed types : `mixed` -デフォルト値 +Default value : -`true` +`2592000` -定義元 +Defined by +: + +[GeneralConfig::$softDeleteDuration](api:craft\config\GeneralConfig::$softDeleteDuration) + +Since : -[GeneralConfig::$transformGifs](api:craft\config\GeneralConfig::$softDeleteDuration) +3.1.0 -デフォルトでは、すべてのホストが信頼されます。 +The amount of time before a soft-deleted item will be up for hard-deletion by garbage collection. -可能な場合に、圧縮された JavaScript を Craft が使用するかどうか。 +Set to `0` if you don’t ever want to delete soft-deleted items. -ユーザー自身がユーザー名をセットするのではなく、Craft がユーザー名をメールアドレスに合わせるかどうか。 +See [craft\helpers\ConfigHelper::durationInSeconds()](https://docs.craftcms.com/api/v3/craft-helpers-confighelper.html#method-durationinseconds) for a list of supported value types. -### `translationDebugOutput` +### `storeUserIps` -許可される型 +Allowed types : [boolean](http://php.net/language.types.boolean) -デフォルト値 +Default value : `false` -定義元 +Defined by : -[GeneralConfig::$translationDebugOutput](api:craft\config\GeneralConfig::$storeUserIps) +[GeneralConfig::$storeUserIps](api:craft\config\GeneralConfig::$storeUserIps) +Since +: +3.1.0 -`LOCK_EX` フラグを使用して、書き込む際にファイルを排他ロックするかどうか。 +Whether user IP addresses should be stored/logged by the system. -### `trustedHosts` -許可される型 + +### `testToEmailAddress` + +Allowed types : [string](http://php.net/language.types.string), [array](http://php.net/language.types.array), [false](http://php.net/language.types.boolean), [null](http://php.net/language.types.null) -デフォルト値 +Default value : -`['any']` +`null` -定義元 +Defined by : -[GeneralConfig::$trustedHosts](api:craft\config\GeneralConfig::$testToEmailAddress) +[GeneralConfig::$testToEmailAddress](api:craft\config\GeneralConfig::$testToEmailAddress) -NFS のような一部のファイルシステムでは、排他的なファイルロックをサポートしていません。 +Configures Craft to send all system emails to a single email address, or an array of email addresses for testing purposes. -`true` または `false` をセットしていない場合、Craft は自動的に基礎となるファイルシステムが排他的なファイルロックをサポートしているかを検出し、結果をキャッシュします。 +By default the recipient name(s) will be “Test Recipient”, but you can customize that by setting the value with the format `['email@address.com' => 'Name']`. -### `useCompressedJs` +### `timezone` -許可される型 +Allowed types : [string](http://php.net/language.types.string), [null](http://php.net/language.types.null) -デフォルト値 +Default value : -`true` +`null` -定義元 +Defined by : -[GeneralConfig::$useCompressedJs](api:craft\config\GeneralConfig::$timezone) +[GeneralConfig::$timezone](api:craft\config\GeneralConfig::$timezone) -Craft が URL を生成する際、`PATH_INFO` を使用してパスを指定するか、クエリ文字列パラメータとして指定するかどうか。 +The timezone of the site. If set, it will take precedence over the Timezone setting in Settings → General. -この設定は、[omitScriptNameInUrls](https://docs.craftcms.com/api/v3/craft-config-generalconfig.html#omitscriptnameinurls) が false にセットされている場合のみ影響することに注意してください。 +This can be set to one of PHP’s [supported timezones](http://php.net/manual/en/timezones.php). -### `useEmailAsUsername` +### `tokenParam` -許可される型 +Allowed types : -[boolean](http://php.net/language.types.string) +[string](http://php.net/language.types.string) -デフォルト値 +Default value : -`false` +`'token'` -定義元 +Defined by : -[GeneralConfig::$useEmailAsUsername](api:craft\config\GeneralConfig::$tokenParam) +[GeneralConfig::$tokenParam](api:craft\config\GeneralConfig::$tokenParam) -プロジェクトコンフィグを `config/project.yaml` に保存するかどうか。 +The query string parameter name that Craft tokens should be set to. -### `useFileLocks` +### `transformGifs` -許可される型 +Allowed types : [boolean](http://php.net/language.types.boolean) -デフォルト値 +Default value : -`null` +`true` -定義元 +Defined by : -[GeneralConfig::$useFileLocks](api:craft\config\GeneralConfig::$transformGifs) +[GeneralConfig::$transformGifs](api:craft\config\GeneralConfig::$transformGifs) +Since +: +3.0.7 -`true` をセットすると、システムのプロジェクトコンフィグのハードコピーが `config/project.yaml` に保存され、`config/project.yaml` の変更はシステムに適用されます。それによって、別々のデータベースを持つにも関わらず、マルチ環境で同じプロジェクトコンフィグを共有することが可能になります。 +Whether GIF files should be cleansed/transformed. -### `usePathInfo` -許可される型 + +### `translationDebugOutput` + +Allowed types : [boolean](http://php.net/language.types.boolean) -デフォルト値 +Default value : `false` -定義元 +Defined by : -[GeneralConfig::$usePathInfo](api:craft\config\GeneralConfig::$translationDebugOutput) +[GeneralConfig::$translationDebugOutput](api:craft\config\GeneralConfig::$translationDebugOutput) -::: warning -この設定を有効にする場合、必ず[プロジェクトコンフィグ](../project-config.html)ドキュメント全体を読み、「プロジェクトコンフィグファイルを有効にする」のステップに慎重に従ってください。 -::: +Whether translated messages should be wrapped in special characters, to help find any strings that are not being run through `Craft::t()` or the `|translate` filter. -### `useProjectConfigFile` +### `trustedHosts` -許可される型 +Allowed types : -[boolean](http://php.net/language.types.array) +[array](http://php.net/language.types.array) -デフォルト値 +Default value : -`false` +`['any']` -定義元 +Defined by : -[GeneralConfig::$useProjectConfigFile](api:craft\config\GeneralConfig::$trustedHosts) +[GeneralConfig::$trustedHosts](api:craft\config\GeneralConfig::$trustedHosts) -`Cookie を作成するために Craft::cookieConfig()` を使用した際、Craft が保存する Cookie に "secure" フラグをセットするかどうか。 +The configuration for trusted security-related headers. -有効な値は `true`、`false`、および、`'auto'` です。デフォルトは `'auto'` で、現在のアクセスが `https://` 越しの場合に、secure フラグがセットされます。`true` はプロトコルに関係なく常にフラグをセットし、`false` は自動的にフラグをセットすることはありません。 +See [yii\web\Request::$trustedHosts](https://www.yiiframework.com/doc/api/2.0/yii-web-request#$trustedHosts-detail) for more details. -トークン化された URL を生成する際に、Craft が使用するプロトコル / スキーマを決定します。`'auto'` をセットすると、Craft は現在のリクエストの siteUrl とプロトコルをチェックし、いずれかが https であればトークン化された URL で `https` を使用します。そうでなければ、`http` を使用します。 +By default, all hosts are trusted. -### `useSecureCookies` +### `upscaleImages` -許可される型 +Allowed types : [boolean](http://php.net/language.types.boolean) -デフォルト値 +Default value : -`'auto'` +`true` -定義元 +Defined by : -[GeneralConfig::$useSecureCookies](api:craft\config\GeneralConfig::$useCompressedJs) +[GeneralConfig::$upscaleImages](api:craft\config\GeneralConfig::$upscaleImages) + +Since +: +3.4.0 -`false` をセットすると、Craft は常に `http` を使用します。そして、`true` をセットすると、Craft は常に `https` を使用します。 +Whether images should be upscaled if the provided transform size is larger than the image. -### `useSslOnTokenizedUrls` -許可される型 +### `useCompressedJs` + +Allowed types : [boolean](http://php.net/language.types.boolean) -デフォルト値 +Default value : -`'auto'` +`true` -定義元 +Defined by : -[GeneralConfig::$useSslOnTokenizedUrls](api:craft\config\GeneralConfig::$useEmailAsUsername) +[GeneralConfig::$useCompressedJs](api:craft\config\GeneralConfig::$useCompressedJs) -ユーザーがアクティブではないためにログアウトするまでの時間。 +Whether Craft should include minified JavaScript files whenever possible, and minify JavaScript code passed to `\craft\web\View::includeJs()` or `{% js %}` Twig tags. -### `userSessionDuration` +### `useEmailAsUsername` -許可される型 +Allowed types +: + +[boolean](http://php.net/language.types.boolean) + +Default value +: + +`false` + +Defined by +: + +[GeneralConfig::$useEmailAsUsername](api:craft\config\GeneralConfig::$useEmailAsUsername) + + + +Whether Craft should set users’ usernames to their email addresses, rather than let them set their username separately. + + + +### `useFileLocks` + +Allowed types : [boolean](http://php.net/language.types.boolean), [null](http://php.net/language.types.null) -デフォルト値 +Default value : -`3600` +`null` -定義元 +Defined by : -[GeneralConfig::$userSessionDuration](api:craft\config\GeneralConfig::$useFileLocks) +[GeneralConfig::$useFileLocks](api:craft\config\GeneralConfig::$useFileLocks) -事前に決定した時間ではなく、ユーザーがブラウザを開いている間はログインしたままにしておきたい場合は、`0` をセットします。 +Whether to grab an exclusive lock on a file when writing to it by using the `LOCK_EX` flag. -サポートされる値の種類は、[craft\helpers\ConfigHelper::durationInSeconds()](https://docs.craftcms.com/api/v3/craft-helpers-confighelper.html#method-durationinseconds) のリストを参照してください。 +Some file systems, such as NFS, do not support exclusive file locking. -期限切れになる前に、ユーザー確認コードを使用できる時間。 +If not set to `true` or `false`, Craft will automatically try to detect if the underlying file system supports exclusive file locking and cache the results. -### `verificationCodeDuration` +### `usePathInfo` -許可される型 +Allowed types : [boolean](http://php.net/language.types.boolean) -デフォルト値 +Default value : -`86400` +`false` -定義元 +Defined by : -[GeneralConfig::$verificationCodeDuration](api:craft\config\GeneralConfig::$usePathInfo) +[GeneralConfig::$usePathInfo](api:craft\config\GeneralConfig::$usePathInfo) -サポートされる値の種類は、[craft\helpers\ConfigHelper::durationInSeconds()](https://docs.craftcms.com/api/v3/craft-helpers-confighelper.html#method-durationinseconds) のリストを参照してください。 +Whether Craft should specify the path using `PATH_INFO` or as a query string parameter when generating URLs. -コントロールパネルにアクセスできないユーザーが、新しいメールアドレスを確認したときにリダイレクトする URI。 +Note that this setting only takes effect if is set to false. -### `verifyEmailSuccessPath` +### `useProjectConfigFile` -許可される型 +Allowed types : [boolean](http://php.net/language.types.boolean) -デフォルト値 +Default value : -`''` +`false` -定義元 +Defined by +: + +[GeneralConfig::$useProjectConfigFile](api:craft\config\GeneralConfig::$useProjectConfigFile) + +Since : -[GeneralConfig::$verifyEmailSuccessPath](api:craft\config\GeneralConfig::$useProjectConfigFile) +3.1.0 -サポートされる値の種類は、[craft\helpers\ConfigHelper::localizedValue()](https://docs.craftcms.com/api/v3/craft-helpers-confighelper.html#method-localizedvalue) のリストを参照してください。 +Whether the project config should be saved out to `config/project.yaml`. If set to `true`, a hard copy of your system’s project config will be saved in `config/project.yaml`, and any changes to `config/project.yaml` will be applied back to the system, making it possible for multiple environments to share the same project config despite having separate databases. @@ -2906,6 +3072,36 @@ See [craft\helpers\ConfigHelper::durationInSeconds()](https://docs.craftcms.com/ +### `verifyEmailPath` + +Allowed types +: + +`mixed` + +Default value +: + +`'verifyemail'` + +Defined by +: + +[GeneralConfig::$verifyEmailPath](api:craft\config\GeneralConfig::$verifyEmailPath) + +Since +: + +3.4.0 + + + +The URI Craft should use for email verification links on the front-end. + +See [craft\helpers\ConfigHelper::localizedValue()](https://docs.craftcms.com/api/v3/craft-helpers-confighelper.html#method-localizedvalue) for a list of supported value types. + + + ### `verifyEmailSuccessPath` Allowed types @@ -2923,9 +3119,14 @@ Defined by [GeneralConfig::$verifyEmailSuccessPath](api:craft\config\GeneralConfig::$verifyEmailSuccessPath) +Since +: + +3.1.20 + -The URI that users without access to the Control Panel should be redirected to after verifying a new email address. +The URI that users without access to the control panel should be redirected to after verifying a new email address. See [craft\helpers\ConfigHelper::localizedValue()](https://docs.craftcms.com/api/v3/craft-helpers-confighelper.html#method-localizedvalue) for a list of supported value types. From f47b056d74026b20a05f954797f07bf5dc22a782 Mon Sep 17 00:00:00 2001 From: Brad Bell Date: Fri, 12 Jun 2020 17:31:46 -0700 Subject: [PATCH 010/245] New translations db-settings.md (French) --- fr/config/db-settings.md | 30 ++++++++++++++++++------------ 1 file changed, 18 insertions(+), 12 deletions(-) diff --git a/fr/config/db-settings.md b/fr/config/db-settings.md index cc900dd1e91..dd060578722 100644 --- a/fr/config/db-settings.md +++ b/fr/config/db-settings.md @@ -10,13 +10,13 @@ For example, in a new Craft 3 project, your `.env` file should define these envi ENVIRONMENT="dev" SECURITY_KEY="" DB_DRIVER="mysql" -DB_SERVER="localhost" +DB_SERVER="" +DB_PORT="" +DB_DATABASE="" DB_USER="root" DB_PASSWORD="" -DB_DATABASE="" DB_SCHEMA="public" DB_TABLE_PREFIX="" -DB_PORT="" ``` The variables that start with `DB_` are database connection settings, and they get pulled into `config/db.php` like this: @@ -25,15 +25,19 @@ The variables that start with `DB_` are database connection settings, and they g return [ 'driver' => getenv('DB_DRIVER'), 'server' => getenv('DB_SERVER'), + 'port' => getenv('DB_PORT'), + 'database' => getenv('DB_DATABASE'), 'user' => getenv('DB_USER'), 'password' => getenv('DB_PASSWORD'), - 'database' => getenv('DB_DATABASE'), 'schema' => getenv('DB_SCHEMA'), 'tablePrefix' => getenv('DB_TABLE_PREFIX'), - 'port' => getenv('DB_PORT') ]; ``` +::: tip +NOTE You may also provide a `DB_DSN` environment variable. If defined, Craft will use that. +::: + We recommend this environment variable approach for two reasons: 1. It keeps sensitive information out of your project’s codebase. (`.env` files should never be shared or committed to Git.) @@ -109,7 +113,7 @@ Allowed types Default value : -`''` +`null` Defined by : @@ -132,7 +136,7 @@ Allowed types Default value : -`self::DRIVER_MYSQL` +`null` Defined by : @@ -164,10 +168,12 @@ Defined by -If you want to manually specify your PDO DSN connection string you can do so here. +The Data Source Name (“DSN”) that tells Craft how to connect to the database. -- MySQL: http://php.net/manual/en/ref.pdo-mysql.connection.php -- PostgreSQL: http://php.net/manual/en/ref.pdo-pgsql.connection.php If you set this, then the [server](https://docs.craftcms.com/api/v3/craft-config-dbconfig.html#server), [port](https://docs.craftcms.com/api/v3/craft-config-dbconfig.html#port), [user](https://docs.craftcms.com/api/v3/craft-config-dbconfig.html#user), [password](https://docs.craftcms.com/api/v3/craft-config-dbconfig.html#password), [database](https://docs.craftcms.com/api/v3/craft-config-dbconfig.html#database), [driver](https://docs.craftcms.com/api/v3/craft-config-dbconfig.html#driver) and [unixSocket](https://docs.craftcms.com/api/v3/craft-config-dbconfig.html#unixsocket) config settings will be ignored. +DSNs should begin with a driver prefix (`mysql:` or `pgsql:`), followed by driver-specific parameters. For example, `mysql:host=127.0.0.1;port=3306;dbname=acme_corp`. + +- MySQL parameters: http://php.net/manual/en/ref.pdo-mysql.connection.php +- PostgreSQL parameters: http://php.net/manual/en/ref.pdo-pgsql.connection.php @@ -250,7 +256,7 @@ Allowed types Default value : -`'localhost'` +`null` Defined by : @@ -259,7 +265,7 @@ Defined by -The database server name or IP address. Usually 'localhost' or '127.0.0.1'. +The database server name or IP address. Usually `localhost` or `127.0.0.1`. From 7163425b0a13187af1e1afd3cf58575cfded8cf3 Mon Sep 17 00:00:00 2001 From: Brad Bell Date: Fri, 12 Jun 2020 17:31:48 -0700 Subject: [PATCH 011/245] New translations db-settings.md (Japanese) --- ja/config/db-settings.md | 96 +++++++++++++++++++++------------------- 1 file changed, 51 insertions(+), 45 deletions(-) diff --git a/ja/config/db-settings.md b/ja/config/db-settings.md index cf21e3f079d..0f3becce254 100644 --- a/ja/config/db-settings.md +++ b/ja/config/db-settings.md @@ -10,13 +10,13 @@ Craft は、Craft がどのようにデータベースへ接続するかを制 ENVIRONMENT="dev" SECURITY_KEY="" DB_DRIVER="mysql" -DB_SERVER="localhost" +DB_SERVER="" +DB_PORT="" +DB_DATABASE="" DB_USER="root" DB_PASSWORD="" -DB_DATABASE="" DB_SCHEMA="public" DB_TABLE_PREFIX="" -DB_PORT="" ``` `DB_` ではじまる変数はデータベース接続設定で、`config/db.php` の中から次のように取得します。 @@ -25,21 +25,25 @@ DB_PORT="" return [ 'driver' => getenv('DB_DRIVER'), 'server' => getenv('DB_SERVER'), + 'port' => getenv('DB_PORT'), + 'database' => getenv('DB_DATABASE'), 'user' => getenv('DB_USER'), 'password' => getenv('DB_PASSWORD'), - 'database' => getenv('DB_DATABASE'), 'schema' => getenv('DB_SCHEMA'), 'tablePrefix' => getenv('DB_TABLE_PREFIX'), - 'port' => getenv('DB_PORT') ]; ``` -私たちがこのような環境変数のアプローチを推奨するには、2つの理由があります。 +::: tip +NOTE You may also provide a `DB_DSN` environment variable. If defined, Craft will use that. +::: + +We recommend this environment variable approach for two reasons: 1. 機密情報をプロジェクトのコードベースから守ります。（`.env` ファイルは、共有したり Git にコミットするべきではありません。） 2. それぞれの開発者が他者の設定を上書きすることなく独自の設定を定義できるため、他の開発者とのコラボレーションを容易にします。 -Craft がサポートするデータベース接続設定の完全なリストは、次の通りです。 +Here’s the full list of database connection settings that Craft supports: @@ -62,9 +66,9 @@ Craft がサポートするデータベース接続設定の完全なリスト -PDO コンストラクタに渡す PDO 属性の key => value ペアの配列。 +An array of key => value pairs of PDO attributes to pass into the PDO constructor. -例えば、MySQL PDO ドライバ（http://php.net/manual/en/ref.pdo-mysql.php）を使用する場合、（MySQL で SSL が利用できると仮定する https://dev.mysql.com/doc/refman/5.5/en/using-secure-connections.html）SSL データベース接続で `'user'` が SSL 経由で接続できる場合、次のように設定します。 +For example, when using the MySQL PDO driver (http://php.net/manual/en/ref.pdo-mysql.php), if you wanted to enable a SSL database connection (assuming SSL is enabled in MySQL (https://dev.mysql.com/doc/refman/5.5/en/using-secure-connections.html) and `'user'` can connect via SSL, you'd set these: ```php [ @@ -95,7 +99,7 @@ PDO コンストラクタに渡す PDO 属性の key => value ペアの配列。 -テーブルを作成する際に使用する文字セット。 +The charset to use when creating tables. @@ -109,7 +113,7 @@ PDO コンストラクタに渡す PDO 属性の key => value ペアの配列。 デフォルト値 : -`''` +`null` 定義元 : @@ -118,7 +122,7 @@ PDO コンストラクタに渡す PDO 属性の key => value ペアの配列。 -選択するデータベースの名前。 +The name of the database to select. @@ -132,7 +136,7 @@ PDO コンストラクタに渡す PDO 属性の key => value ペアの配列。 デフォルト値 : -`self::DRIVER_MYSQL` +`null` 定義元 : @@ -141,7 +145,7 @@ PDO コンストラクタに渡す PDO 属性の key => value ペアの配列。 -使用するデータベースのドライバ。MySQL 向けの 'mysql'、または、PostgreSQL 向けの 'pgsql'。 +The database driver to use. Either 'mysql' for MySQL or 'pgsql' for PostgreSQL. @@ -164,10 +168,12 @@ PDO コンストラクタに渡す PDO 属性の key => value ペアの配列。 -手動で PDO DSN 接続文字列を指定する場合は、ここで設定できます。 +The Data Source Name (“DSN”) that tells Craft how to connect to the database. + +DSNs should begin with a driver prefix (`mysql:` or `pgsql:`), followed by driver-specific parameters. For example, `mysql:host=127.0.0.1;port=3306;dbname=acme_corp`. -- MySQL: http://php.net/manual/en/ref.pdo-mysql.connection.php -- PostgreSQL: http://php.net/manual/en/ref.pdo-pgsql.connection.php これを設定すると、コンフィグ設定の [server](https://docs.craftcms.com/api/v3/craft-config-dbconfig.html#server)、[port](https://docs.craftcms.com/api/v3/craft-config-dbconfig.html#port)、[user](https://docs.craftcms.com/api/v3/craft-config-dbconfig.html#user)、[password](https://docs.craftcms.com/api/v3/craft-config-dbconfig.html#password)、[database](https://docs.craftcms.com/api/v3/craft-config-dbconfig.html#database)、[driver](https://docs.craftcms.com/api/v3/craft-config-dbconfig.html#driver)、および、[unixSocket](https://docs.craftcms.com/api/v3/craft-config-dbconfig.html#unixsocket) は無視されます。 +- MySQL parameters: http://php.net/manual/en/ref.pdo-mysql.connection.php +- PostgreSQL parameters: http://php.net/manual/en/ref.pdo-pgsql.connection.php @@ -190,7 +196,7 @@ PDO コンストラクタに渡す PDO 属性の key => value ペアの配列。 -接続するデータベースのパスワード。 +The database password to connect with. @@ -213,147 +219,147 @@ PDO コンストラクタに渡す PDO 属性の key => value ペアの配列。 -データベースサーバーのポート。デフォルトは、MySQL 向けの 3306、および、PostgreSQL 向けの 5432。 +The database server port. Defaults to 3306 for MySQL and 5432 for PostgreSQL. ### `schema` -許可される型 +Allowed types : [string](http://php.net/language.types.string) -デフォルト値 +Default value : `'public'` -定義元 +Defined by : [DbConfig::$schema](api:craft\config\DbConfig::$schema) -使用するデータベースのスキーマ（PostgreSQL のみ）。 +The schema that Postgres is configured to use by default (PostgreSQL only). ### `server` -許可される型 +Allowed types : [string](http://php.net/language.types.string) -デフォルト値 +Default value : -`'localhost'` +`null` -定義元 +Defined by : [DbConfig::$server](api:craft\config\DbConfig::$server) -データベースのサーバー名、または、IP アドレス。通常は 'localhost' または '127.0.0.1' です。 +The database server name or IP address. Usually `localhost` or `127.0.0.1`. ### `tablePrefix` -許可される型 +Allowed types : [string](http://php.net/language.types.string) -デフォルト値 +Default value : `''` -定義元 +Defined by : [DbConfig::$tablePrefix](api:craft\config\DbConfig::$tablePrefix) -共有するCraft のインストールを単一のデータベース（MySQL）、または、単一のデータベースで共有スキーマ（PostgreSQL）を使用する場合、インストールごとにテーブル名の競合を避けるために、テーブル接頭辞をセットできます。これは5文字以内、かつ、すべて小文字でなければなりません。 +If you're sharing Craft installs in a single database (MySQL) or a single database and using a shared schema (PostgreSQL), then you can set a table prefix here to avoid table naming conflicts per install. This can be no more than 5 characters, and must be all lowercase. ### `unixSocket` -許可される型 +Allowed types : [string](http://php.net/language.types.string), [null](http://php.net/language.types.null) -デフォルト値 +Default value : `null` -定義元 +Defined by : [DbConfig::$unixSocket](api:craft\config\DbConfig::$unixSocket) -MySQL のみ。セットされている場合、（yiic で使用される）CLI 接続文字列は、 サーバーやポートの代わりに Unix ソケットに接続します。これを指定すると、'server' と 'port' 設定が無視されます。 +MySQL only. If this is set, then the CLI connection string (used for yiic) will connect to the Unix socket, instead of the server and port. If this is specified, then 'server' and 'port' settings are ignored. ### `url` -許可される型 +Allowed types : [string](http://php.net/language.types.string), [null](http://php.net/language.types.null) -デフォルト値 +Default value : `null` -定義元 +Defined by : [DbConfig::$url](api:craft\config\DbConfig::$url) -ホスティング環境によって提供された場合、データベースの接続 URL。 +The database connection URL, if one was provided by your hosting environment. -これがセットされている場合、[driver](https://docs.craftcms.com/api/v3/craft-config-dbconfig.html#driver)、[user](https://docs.craftcms.com/api/v3/craft-config-dbconfig.html#user)、[database](https://docs.craftcms.com/api/v3/craft-config-dbconfig.html#database)、[server](https://docs.craftcms.com/api/v3/craft-config-dbconfig.html#server)、[port](https://docs.craftcms.com/api/v3/craft-config-dbconfig.html#port)、および、[database](https://docs.craftcms.com/api/v3/craft-config-dbconfig.html#database) の値は、そこから抽出されます。 +If this is set, the values for [driver](https://docs.craftcms.com/api/v3/craft-config-dbconfig.html#driver), [user](https://docs.craftcms.com/api/v3/craft-config-dbconfig.html#user), [database](https://docs.craftcms.com/api/v3/craft-config-dbconfig.html#database), [server](https://docs.craftcms.com/api/v3/craft-config-dbconfig.html#server), [port](https://docs.craftcms.com/api/v3/craft-config-dbconfig.html#port), and [database](https://docs.craftcms.com/api/v3/craft-config-dbconfig.html#database) will be extracted from it. ### `user` -許可される型 +Allowed types : [string](http://php.net/language.types.string) -デフォルト値 +Default value : `'root'` -定義元 +Defined by : [DbConfig::$user](api:craft\config\DbConfig::$user) -接続するデータベースのユーザー名。 +The database username to connect with. From bb8fb2a8d0bebc145839abc56756b7f438157c92 Mon Sep 17 00:00:00 2001 From: Brad Bell Date: Fri, 12 Jun 2020 17:31:50 -0700 Subject: [PATCH 012/245] New translations environments.md (French) --- fr/config/environments.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/fr/config/environments.md b/fr/config/environments.md index 2153bad2d82..44e8fe8c7c6 100644 --- a/fr/config/environments.md +++ b/fr/config/environments.md @@ -4,7 +4,7 @@ Some settings should be defined on a per-environment basis. For example, when de ## Control Panel Settings -Some settings in the Control Panel can be set to environment variables (like the ones defined in your `.env` file): +Some settings in the control panel can be set to environment variables (like the ones defined in your `.env` file): - General Settings - **System Name** From 35b56f8f74c01fcd66127f28b1747743a85348d1 Mon Sep 17 00:00:00 2001 From: Brad Bell Date: Fri, 12 Jun 2020 17:31:51 -0700 Subject: [PATCH 013/245] New translations environments.md (Japanese) --- ja/config/environments.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/ja/config/environments.md b/ja/config/environments.md index 2e51656d368..9617f116664 100644 --- a/ja/config/environments.md +++ b/ja/config/environments.md @@ -4,7 +4,7 @@ ## コントロールパネルの設定 -コントロールパネル内のいくつかの設定は、（`.env` ファイルで定義されているような）環境変数にセットできます。 +Some settings in the control panel can be set to environment variables (like the ones defined in your `.env` file): - 一般 - **システム名** From 783dc4dbc90059add07d5cbf86f3707d00b540e4 Mon Sep 17 00:00:00 2001 From: Brad Bell Date: Fri, 12 Jun 2020 17:31:52 -0700 Subject: [PATCH 014/245] New translations php-constants.md (French) --- fr/config/php-constants.md | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/fr/config/php-constants.md b/fr/config/php-constants.md index 076c26fa83d..e5a9f175a38 100644 --- a/fr/config/php-constants.md +++ b/fr/config/php-constants.md @@ -36,6 +36,10 @@ The environment name that [multi-environment configs](environments.md#multi-envi define('CRAFT_ENVIRONMENT', getenv('ENVIRONMENT') ?: 'production'); ``` +### `CRAFT_EPHEMERAL` + +When defined as `true`, Craft will skip file system permission checks and operations that are not available in an environment with ephemeral or read-only storage. + ### `CRAFT_LICENSE_KEY` Your Craft license key, if for some reason that must be defined by PHP rather than a license key file. (Don’t set this until you have a valid license key.) From b521faff7f24b4f863cc4b429e6bd0e314d38e80 Mon Sep 17 00:00:00 2001 From: Brad Bell Date: Fri, 12 Jun 2020 17:31:54 -0700 Subject: [PATCH 015/245] New translations php-constants.md (Japanese) --- ja/config/php-constants.md | 22 ++++++++++++++-------- 1 file changed, 14 insertions(+), 8 deletions(-) diff --git a/ja/config/php-constants.md b/ja/config/php-constants.md index dfe894f1218..bfb79e41ab1 100644 --- a/ja/config/php-constants.md +++ b/ja/config/php-constants.md @@ -36,17 +36,21 @@ define('CRAFT_COMPOSER_PATH', 'path/to/composer.json'); define('CRAFT_ENVIRONMENT', getenv('ENVIRONMENT') ?: 'production'); ``` +### `CRAFT_EPHEMERAL` + +When defined as `true`, Craft will skip file system permission checks and operations that are not available in an environment with ephemeral or read-only storage. + ### `CRAFT_LICENSE_KEY` -何らかの理由で、ライセンスキーファイルではなく PHP によって定義されなければならい場合の Craft のライセンスキー。（有効なライセンスキーを取得するまで、これをセットしないでください。） +Your Craft license key, if for some reason that must be defined by PHP rather than a license key file. (Don’t set this until you have a valid license key.) ### `CRAFT_LICENSE_KEY_PATH` -ファイル名を含めた Craft がライセンスキーファイルを保存するパス。（デフォルトでは、[config/](../directory-structure.md#config) フォルダ内に `license.key` が保存されます。） +The path that Craft should store its license key file, including its filename. (It will be stored as `license.key` within your [config/](../directory-structure.md#config) folder by default.) ### `CRAFT_LOG_PHP_ERRORS` -Craft が PHP の [log_errors](http://php.net/manual/en/errorfunc.configuration.php#ini.log-errors) 設定をセットすることを抑制し、`php.ini` 内の設定に任せるよう `false` をセットすることもできます。 +Can be set to `false` to prevent Craft from setting PHP’s [log_errors](http://php.net/manual/en/errorfunc.configuration.php#ini.log-errors) setting, leaving it up to whatever’s set in `php.ini`. ```php // Don't send PHP error logs to storage/logs/phperrors.log @@ -55,7 +59,7 @@ define('CRAFT_LOG_PHP_ERRORS', false); ### `CRAFT_SITE` -Craft がこの `index.php` ファイルから提供するべき、サイトハンドル、または、サイト ID。（明確な理由がある場合のみ、これをセットしてください。セットされていなければ、Craft はリクエスト URL を調査することで正しいサイトを自動的に配信します。） +The Site handle or ID that Craft should be serving from this `index.php` file. (Only set this if you have a good reason to. Craft will automatically serve the correct site by inspecting the requested URL, unless this is set.) ```php // Show the German site @@ -64,17 +68,19 @@ define('CRAFT_SITE', 'de'); ### `CRAFT_STORAGE_PATH` -[storage/](../directory-structure.md#storage) フォルダのパス。（デフォルトでは、ベースディレクトリ内に存在するものとします。） +The path to the [storage/](../directory-structure.md#storage) folder. (It is assumed to live within the base directory by default.) -[templates/](../directory-structure.md#templates) フォルダのパス。（デフォルトでは、ベースディレクトリ内に存在するものとします。） +::: tip +Make sure you set this to a valid folder path, otherwise it will be ignored. +::: ### `CRAFT_TEMPLATES_PATH` -`translations/` フォルダのパス。（デフォルトでは、ベースディレクトリ内に存在するものとします。） +The path to the [templates/](../directory-structure.md#templates) folder. (It is assumed to live within the base directory by default.) ### `CRAFT_TRANSLATIONS_PATH` -[vendor/](../directory-structure.md#vendor) フォルダのパス。（デフォルトでは、起動スクリプトによって4つのディレクトリが稼働しているものとします。） +The path to the `translations/` folder. (It is assumed to live within the base directory by default.) ### `CRAFT_VENDOR_PATH` From c8220dbdf722ac0b2212a0db8d158012e37c6a7f Mon Sep 17 00:00:00 2001 From: Brad Bell Date: Fri, 12 Jun 2020 17:31:56 -0700 Subject: [PATCH 016/245] New translations config-settings.md (French) --- fr/config/config-settings.md | 281 ++++++++++++++++++++++++++++++----- 1 file changed, 241 insertions(+), 40 deletions(-) diff --git a/fr/config/config-settings.md b/fr/config/config-settings.md index df9bdf3d254..1889f7b2708 100644 --- a/fr/config/config-settings.md +++ b/fr/config/config-settings.md @@ -55,7 +55,7 @@ Defined by -The URI segment Craft should look for when determining if the current request should first be routed to a controller action. +The URI segment Craft should look for when determining if the current request should be routed to a controller action. @@ -78,7 +78,7 @@ Defined by -The URI that users without access to the Control Panel should be redirected to after activating their account. +The URI that users without access to the control panel should be redirected to after activating their account. See [craft\helpers\ConfigHelper::localizedValue()](https://docs.craftcms.com/api/v3/craft-helpers-confighelper.html#method-localizedvalue) for a list of supported value types. @@ -147,13 +147,18 @@ Defined by [GeneralConfig::$allowAdminChanges](api:craft\config\GeneralConfig::$allowAdminChanges) +Since +: + +3.1.0 + Whether admins should be allowed to make administrative changes to the system. If this is disabled, the Settings and Plugin Store sections will be hidden, the Craft edition and Craft/plugin versions will be locked, and the project config will become read-only. -Therefore you should only disable this in production environments when [useProjectConfigFile](https://docs.craftcms.com/api/v3/craft-config-generalconfig.html#useprojectconfigfile) is enabled, and you have a deployment workflow that runs `composer install` automatically on deploy. +Therefore you should only disable this in production environments when is enabled, and you have a deployment workflow that runs `composer install` automatically on deploy. ::: warning Don’t disable this setting until **all** environments have been updated to Craft 3.1.0 or later. @@ -203,9 +208,9 @@ Defined by -Whether Craft should allow system and plugin updates in the Control Panel, and plugin installation from the Plugin Store. +Whether Craft should allow system and plugin updates in the control panel, and plugin installation from the Plugin Store. -This setting will automatically be disabled if [allowAdminChanges](https://docs.craftcms.com/api/v3/craft-config-generalconfig.html#allowadminchanges) is disabled. +This setting will automatically be disabled if is disabled. @@ -356,12 +361,12 @@ Defined by -The base URL that Craft should use when generating Control Panel URLs. +The base URL that Craft should use when generating control panel URLs. It will be determined automatically if left blank. ::: tip -The base CP URL should **not** include the [CP trigger word](https://docs.craftcms.com/api/v3/craft-config-generalconfig.html#cptrigger) (e.g. `/admin`). +The base control panel URL should **not** include the [control panel trigger word](config:cpTrigger) (e.g. `/admin`). ::: @@ -464,6 +469,10 @@ Defined by Whether uploaded filenames with non-ASCII characters should be converted to ASCII (i.e. `ñ` → `n`). +::: tip +You can run `./craft utils/ascii-filenames` in your terminal to apply ASCII filenames to all existing assets. +::: + ### `cooldownDuration` @@ -512,7 +521,7 @@ Defined by -The URI segment Craft should look for when determining if the current request should route to the Control Panel rather than the front-end website. +The URI segment Craft should look for when determining if the current request should route to the control panel rather than the front-end website. @@ -535,7 +544,7 @@ Defined by -The name of CSRF token used for CSRF validation if [enableCsrfProtection](https://docs.craftcms.com/api/v3/craft-config-generalconfig.html#enablecsrfprotection) is set to `true`. +The name of CSRF token used for CSRF validation if is set to `true`. @@ -581,7 +590,7 @@ Defined by -The default language the Control Panel should use for users who haven’t set a preferred language yet. +The default language the control panel should use for users who haven’t set a preferred language yet. @@ -835,6 +844,11 @@ Defined by [GeneralConfig::$disabledPlugins](api:craft\config\GeneralConfig::$disabledPlugins) +Since +: + +3.1.9 + Array of plugin handles that should be disabled, regardless of what the project config says. @@ -891,7 +905,7 @@ Defined by -Whether to use a cookie to persist the CSRF token if [enableCsrfProtection](https://docs.craftcms.com/api/v3/craft-config-generalconfig.html#enablecsrfprotection) is enabled. If false, the CSRF token will be stored in session under the `csrfTokenName` config setting name. Note that while storing CSRF tokens in session increases security, it requires starting a session for every page that a CSRF token is need, which may degrade site performance. +Whether to use a cookie to persist the CSRF token if is enabled. If false, the CSRF token will be stored in session under the `csrfTokenName` config setting name. Note that while storing CSRF tokens in session increases security, it requires starting a session for every page that a CSRF token is needed, which may degrade site performance. @@ -935,6 +949,11 @@ Defined by [GeneralConfig::$enableGql](api:craft\config\GeneralConfig::$enableGql) +Since +: + +3.3.1 + Whether the GraphQL API should be enabled. @@ -943,6 +962,38 @@ Note that the GraphQL API is only available for Craft Pro. +### `enableGraphQlCaching` + +Allowed types +: + +[boolean](http://php.net/language.types.boolean) + +Default value +: + +`true` + +Defined by +: + +[GeneralConfig::$enableGraphQlCaching](api:craft\config\GeneralConfig::$enableGraphQlCaching) + +Since +: + +3.3.12 + + + +Whether Craft should cache GraphQL queries. + +If set to `true`, Craft will cache the results for unique GraphQL queries per access token. The cache is automatically invalidated any time an element is saved, the site structure is updated, or a GraphQL schema is saved. + +This setting will have no effect if a plugin is using the [craft\services\Gql::EVENT_BEFORE_EXECUTE_GQL_QUERY](https://docs.craftcms.com/api/v3/craft-services-gql.html#event-before-execute-gql-query) event to provide its own caching logic and setting the `result` property. + + + ### `enableTemplateCaching` Allowed types @@ -1010,7 +1061,7 @@ Defined by -List of file extensions that will be merged into the [allowedFileExtensions](https://docs.craftcms.com/api/v3/craft-config-generalconfig.html#allowedfileextensions) config setting. +List of file extensions that will be merged into the config setting. @@ -1031,6 +1082,11 @@ Defined by [GeneralConfig::$extraAppLocales](api:craft\config\GeneralConfig::$extraAppLocales) +Since +: + +3.0.24 + List of extra locale IDs that the application should support, and users should be able to select as their Preferred Language. @@ -1056,9 +1112,14 @@ Defined by [GeneralConfig::$extraFileKinds](api:craft\config\GeneralConfig::$extraFileKinds) +Since +: + +3.0.37 + -List of additional file kinds Craft should support. This array will get merged with the one defined in `\craft\config\craft\helpers\Assets::_buildFileKinds()`. +List of additional file kinds Craft should support. This array will get merged with the one defined in `\craft\helpers\Assets::_buildFileKinds()`. ```php 'extraFileKinds' => [ @@ -1075,7 +1136,7 @@ List of additional file kinds Craft should support. This array will get merged w ``` ::: tip -File extensions listed here won’t immediately be allowed to be uploaded. You will also need to list them with the [extraAllowedFileExtensions](https://docs.craftcms.com/api/v3/craft-config-generalconfig.html#extraallowedfileextensions) config setting. +File extensions listed here won’t immediately be allowed to be uploaded. You will also need to list them with the config setting. ::: @@ -1143,17 +1204,23 @@ Defined by [GeneralConfig::$headlessMode](api:craft\config\GeneralConfig::$headlessMode) +Since +: + +3.3.0 -Bool Whether the system should run in Headless Mode, which optimizes the system and Control Panel for headless CMS implementations. + +Bool Whether the system should run in Headless Mode, which optimizes the system and control panel for headless CMS implementations. When this is enabled, the following changes will take place: -- URI Format settings for sections and category groups will be hidden. +- Template settings for sections and category groups will be hidden. - Template route management will be hidden. - Front-end routing will skip checks for element and template requests. - Front-end responses will be JSON-formatted rather than HTML by default. - Twig will be configured to escape unsafe strings for JavaScript/JSON rather than HTML by default for front-end requests. +- The , , , and settings will be ignored. @@ -1351,6 +1418,8 @@ Defined by The URI Craft should use for user login on the front-end. +This can be set to `false` to disable front-end login. + See [craft\helpers\ConfigHelper::localizedValue()](https://docs.craftcms.com/api/v3/craft-helpers-confighelper.html#method-localizedvalue) for a list of supported value types. @@ -1376,10 +1445,35 @@ Defined by The URI Craft should use for user logout on the front-end. +This can be set to `false` to disable front-end logout. + See [craft\helpers\ConfigHelper::localizedValue()](https://docs.craftcms.com/api/v3/craft-helpers-confighelper.html#method-localizedvalue) for a list of supported value types. +### `maxBackups` + +Allowed types +: + +[integer](http://php.net/language.types.integer), [false](http://php.net/language.types.boolean) + +Default value +: + +`20` + +Defined by +: + +[GeneralConfig::$maxBackups](api:craft\config\GeneralConfig::$maxBackups) + + + +The number of backups that Craft should make before it starts deleting the oldest backups. If it is set to `false`, then Craft will not delete any backups. + + + ### `maxCachedCloudImageSize` Allowed types @@ -1443,6 +1537,11 @@ Defined by [GeneralConfig::$maxRevisions](api:craft\config\GeneralConfig::$maxRevisions) +Since +: + +3.2.0 + The maximum number of revisions that should be stored for each element. @@ -1583,7 +1682,7 @@ The string preceding a number which Craft will look for when determining if the | `?page` | `/news?page=5` | ::: tip -If you want to set this to `?p` (e.g. `/news?p=5`), you will need to change your [pathParam](https://docs.craftcms.com/api/v3/craft-config-generalconfig.html#pathparam) setting as well, which is set to `p` by default, and if your server is running Apache, you will need to update the redirect code in your `.htaccess` file to match your new `pathParam` value. +If you want to set this to `?p` (e.g. `/news?p=5`), you will need to change your setting as well, which is set to `p` by default, and if your server is running Apache, you will need to update the redirect code in your `.htaccess` file to match your new `pathParam` value. ::: @@ -1682,9 +1781,9 @@ Defined by -The path that users should be redirected to after logging in from the Control Panel. +The path that users should be redirected to after logging in from the control panel. -This setting will also come into effect if the user visits the CP’s Login page (`/admin/login`) or the CP’s root URL (/admin) when they are already logged in. +This setting will also come into effect if a user visits the control panel’s Login page (`/admin/login`) or the control panel’s root URL (/admin) when they are already logged in. See [craft\helpers\ConfigHelper::localizedValue()](https://docs.craftcms.com/api/v3/craft-helpers-confighelper.html#method-localizedvalue) for a list of supported value types. @@ -1759,11 +1858,16 @@ Defined by [GeneralConfig::$preserveCmykColorspace](api:craft\config\GeneralConfig::$preserveCmykColorspace) +Since +: + +3.0.8 -Whether CMYK should be preserved as the colorspace when when manipulating images. -Setting this to `true` will prevent Craft from transforming CMYK images to sRGB, but on some ImageMagick versions can cause color distortion in the image. This will only have effect if ImageMagick is in use. +Whether CMYK should be preserved as the colorspace when manipulating images. + +Setting this to `true` will prevent Craft from transforming CMYK images to sRGB, but on some ImageMagick versions it can cause color distortion in the image. This will only have effect if ImageMagick is in use. @@ -1838,7 +1942,7 @@ Defined by -When set to `false` and you go through the "forgot password" workflow on the Control Panel login page, for example, you get distinct messages saying if the username/email didn't exist or the email was successfully sent and to check your email for further instructions. This can allow for username/email enumeration based on the response. If set `true`, you will always get a successful response even if there was an error making it difficult to enumerate users. +When set to `false` and you go through the "forgot password" workflow on the control panel login page, for example, you get distinct messages saying if the username/email didn't exist or the email was successfully sent and to check your email for further instructions. This can allow for username/email enumeration based on the response. If set `true`, you will always get a successful response even if there was an error making it difficult to enumerate users. @@ -1913,6 +2017,11 @@ Defined by [GeneralConfig::$purgeStaleUserSessionDuration](api:craft\config\GeneralConfig::$purgeStaleUserSessionDuration) +Since +: + +3.3.0 + The amount of time to wait before Craft purges stale user sessions from the sessions table in the database. @@ -1940,6 +2049,11 @@ Defined by [GeneralConfig::$purgeUnsavedDraftsDuration](api:craft\config\GeneralConfig::$purgeUnsavedDraftsDuration) +Since +: + +3.2.0 + The amount of time to wait before Craft purges drafts of new elements that were never formally saved. @@ -1969,7 +2083,7 @@ Defined by -The amount of time Craft will remember a username and pre-populate it on the CP login page. +The amount of time Craft will remember a username and pre-populate it on the control panel’s Login page. Set to `0` to disable this feature altogether. @@ -2069,7 +2183,7 @@ Defined by -The path to the root directory that should store published CP resources. +The path to the root directory that should store published control panel resources. @@ -2092,7 +2206,7 @@ Defined by -The URL to the root directory that should store published CP resources. +The URL to the root directory that should store published control panel resources. @@ -2117,7 +2231,7 @@ Defined by The shell command that Craft should execute to restore a database backup. -By default Craft will run `mysql` or `psql`, provided that those libraries are in the `$PATH` variable for the user the web server is running as. +By default Craft will run `mysql` or `psql`, provided that those libraries are in the `$PATH` variable for the user the web server is running as. There are several tokens you can use that Craft will swap out at runtime: @@ -2174,18 +2288,18 @@ Defined by -Whether Craft should run pending queue jobs automatically over HTTP requests. - -This setting should be disabled for servers running Win32, or with Apache’s mod_deflate/mod_gzip installed, where PHP’s [flush()](http://php.net/manual/en/function.flush.php) method won’t work. +Whether Craft should run pending queue jobs automatically when someone visits the control panel. -If disabled, an alternate queue runner *must* be set up separately. +If disabled, an alternate queue worker *must* be set up separately, either as an [always-running daemon](https://github.com/yiisoft/yii2-queue/blob/master/docs/guide/worker.md), or a cron job that runs the `queue/run` command every minute: -Here is an example of how you would setup a queue runner from a cron job that ran every minute: - -```text -/1 * * * * /path/to/project/root/craft queue/run +```cron +* * * * * /path/to/project/craft queue/run ``` +::: tip +This setting should be disabled for servers running Win32, or with Apache’s mod_deflate/mod_gzip installed, where PHP’s [flush()](http://php.net/manual/en/function.flush.php) method won’t work. +::: + ### `sameSiteCookieValue` @@ -2216,7 +2330,7 @@ The [SameSite](https://www.owasp.org/index.php/SameSite) value that should be se This can be set to `'Lax'`, `'Strict'`, or `null`. -::: note +::: tip This setting requires PHP 7.3 or later. ::: @@ -2368,10 +2482,14 @@ Defined by -The password-reset template path. Note that this only affects front-end site requests. +The URI Craft should use for Set Password forms on the front-end. See [craft\helpers\ConfigHelper::localizedValue()](https://docs.craftcms.com/api/v3/craft-helpers-confighelper.html#method-localizedvalue) for a list of supported value types. +::: tip +You might also want to set in case a user clicks on an expired password reset link. +::: + ### `setPasswordSuccessPath` @@ -2447,7 +2565,7 @@ The base URL to the site(s). If set, it will take precedence over the Base URL s This can be set to a string, which will override the primary site’s base URL only, or an array with site handles used as the keys. -The URL(s) must begin with either `http://`, `https://`, `//` (protocol-relative), or an [alias](https://docs.craftcms.com/api/v3/craft-config-generalconfig.html#aliases). +The URL(s) must begin with either `http://`, `https://`, `//` (protocol-relative), or an [alias](config:aliases). ```php 'siteUrl' => [ @@ -2498,6 +2616,11 @@ Defined by [GeneralConfig::$softDeleteDuration](api:craft\config\GeneralConfig::$softDeleteDuration) +Since +: + +3.1.0 + The amount of time before a soft-deleted item will be up for hard-deletion by garbage collection. @@ -2525,6 +2648,11 @@ Defined by [GeneralConfig::$storeUserIps](api:craft\config\GeneralConfig::$storeUserIps) +Since +: + +3.1.0 + Whether user IP addresses should be stored/logged by the system. @@ -2621,6 +2749,11 @@ Defined by [GeneralConfig::$transformGifs](api:craft\config\GeneralConfig::$transformGifs) +Since +: + +3.0.7 + Whether GIF files should be cleansed/transformed. @@ -2677,6 +2810,34 @@ By default, all hosts are trusted. +### `upscaleImages` + +Allowed types +: + +[boolean](http://php.net/language.types.boolean) + +Default value +: + +`true` + +Defined by +: + +[GeneralConfig::$upscaleImages](api:craft\config\GeneralConfig::$upscaleImages) + +Since +: + +3.4.0 + + + +Whether images should be upscaled if the provided transform size is larger than the image. + + + ### `useCompressedJs` Allowed types @@ -2696,7 +2857,7 @@ Defined by -Whether Craft should use compressed JavaScript files whenever possible. +Whether Craft should include minified JavaScript files whenever possible, and minify JavaScript code passed to `\craft\web\View::includeJs()` or `{% js %}` Twig tags. @@ -2771,7 +2932,7 @@ Defined by Whether Craft should specify the path using `PATH_INFO` or as a query string parameter when generating URLs. -Note that this setting only takes effect if [omitScriptNameInUrls](https://docs.craftcms.com/api/v3/craft-config-generalconfig.html#omitscriptnameinurls) is set to false. +Note that this setting only takes effect if is set to false. @@ -2792,6 +2953,11 @@ Defined by [GeneralConfig::$useProjectConfigFile](api:craft\config\GeneralConfig::$useProjectConfigFile) +Since +: + +3.1.0 + Whether the project config should be saved out to `config/project.yaml`. @@ -2906,6 +3072,36 @@ See [craft\helpers\ConfigHelper::durationInSeconds()](https://docs.craftcms.com/ +### `verifyEmailPath` + +Allowed types +: + +`mixed` + +Default value +: + +`'verifyemail'` + +Defined by +: + +[GeneralConfig::$verifyEmailPath](api:craft\config\GeneralConfig::$verifyEmailPath) + +Since +: + +3.4.0 + + + +The URI Craft should use for email verification links on the front-end. + +See [craft\helpers\ConfigHelper::localizedValue()](https://docs.craftcms.com/api/v3/craft-helpers-confighelper.html#method-localizedvalue) for a list of supported value types. + + + ### `verifyEmailSuccessPath` Allowed types @@ -2923,9 +3119,14 @@ Defined by [GeneralConfig::$verifyEmailSuccessPath](api:craft\config\GeneralConfig::$verifyEmailSuccessPath) +Since +: + +3.1.20 + -The URI that users without access to the Control Panel should be redirected to after verifying a new email address. +The URI that users without access to the control panel should be redirected to after verifying a new email address. See [craft\helpers\ConfigHelper::localizedValue()](https://docs.craftcms.com/api/v3/craft-helpers-confighelper.html#method-localizedvalue) for a list of supported value types. From 2952a3358cb7971ff7d51484ad556e379202b2c8 Mon Sep 17 00:00:00 2001 From: Brad Bell Date: Fri, 12 Jun 2020 17:31:58 -0700 Subject: [PATCH 017/245] New translations asset-queries.md (French) --- fr/dev/element-queries/asset-queries.md | 352 +++++++----------------- 1 file changed, 94 insertions(+), 258 deletions(-) diff --git a/fr/dev/element-queries/asset-queries.md b/fr/dev/element-queries/asset-queries.md index a8c7546a04e..9457e146282 100644 --- a/fr/dev/element-queries/asset-queries.md +++ b/fr/dev/element-queries/asset-queries.md @@ -45,12 +45,53 @@ We can display a list of thumbnails for images in a “Photos” volume by doing ``` +::: warning +When using `asset.url` or `asset.getUrl()`, the asset’s source volume must have “Assets in this volume have public URLs” enabled and a “Base URL” setting. Otherwise, the result will always be empty. +::: + ## Parameters Asset queries support the following parameters: +| Param | Description | +| ----------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| [anyStatus](#anystatus) | Clears out the [status()](https://docs.craftcms.com/api/v3/craft-elements-db-elementquery.html#method-status) and [enabledForSite()](https://docs.craftcms.com/api/v3/craft-elements-db-elementquery.html#method-enabledforsite) parameters. | +| [asArray](#asarray) | Causes the query to return matching assets as arrays of data, rather than [Asset](api:craft\elements\Asset) objects. | +| [clearCachedResult](#clearcachedresult) | Clears the cached result. | +| [dateCreated](#datecreated) | Narrows the query results based on the assets’ creation dates. | +| [dateModified](#datemodified) | Narrows the query results based on the assets’ files’ last-modified dates. | +| [dateUpdated](#dateupdated) | Narrows the query results based on the assets’ last-updated dates. | +| [filename](#filename) | Narrows the query results based on the assets’ filenames. | +| [fixedOrder](#fixedorder) | Causes the query results to be returned in the order specified by [id](#id). | +| [folderId](#folderid) | Narrows the query results based on the folders the assets belong to, per the folders’ IDs. | +| [height](#height) | Narrows the query results based on the assets’ image heights. | +| [id](#id) | Narrows the query results based on the assets’ IDs. | +| [ignorePlaceholders](#ignoreplaceholders) | Causes the query to return matching assets as they are stored in the database, ignoring matching placeholder elements that were set by [craft\services\Elements::setPlaceholderElement()](https://docs.craftcms.com/api/v3/craft-services-elements.html#method-setplaceholderelement). | +| [inReverse](#inreverse) | Causes the query results to be returned in reverse order. | +| [includeSubfolders](#includesubfolders) | Broadens the query results to include assets from any of the subfolders of the folder specified by [folderId](#folderid). | +| [kind](#kind) | Narrows the query results based on the assets’ file kinds. | +| [limit](#limit) | Determines the number of assets that should be returned. | +| [offset](#offset) | Determines how many assets should be skipped in the results. | +| [orderBy](#orderby) | Determines the order that the assets should be returned in. (If empty, defaults to `dateCreated DESC`.) | +| [preferSites](#prefersites) | If [unique](#unique) is set, this determines which site should be selected when querying multi-site elements. | +| [relatedTo](#relatedto) | Narrows the query results to only assets that are related to certain other elements. | +| [search](#search) | Narrows the query results to only assets that match a search query. | +| [site](#site) | Determines which site(s) the assets should be queried in. | +| [siteId](#siteid) | Determines which site(s) the assets should be queried in, per the site’s ID. | +| [size](#size) | Narrows the query results based on the assets’ file sizes (in bytes). | +| [title](#title) | Narrows the query results based on the assets’ titles. | +| [trashed](#trashed) | Narrows the query results to only assets that have been soft-deleted. | +| [uid](#uid) | Narrows the query results based on the assets’ UIDs. | +| [unique](#unique) | Determines whether only elements with unique IDs should be returned by the query. | +| [uploader](#uploader) | Narrows the query results based on the user the assets were uploaded by, per the user’s IDs. | +| [volume](#volume) | Narrows the query results based on the volume the assets belong to. | +| [volumeId](#volumeid) | Narrows the query results based on the volumes the assets belong to, per the volumes’ IDs. | +| [width](#width) | Narrows the query results based on the assets’ image widths. | +| [with](#with) | Causes the query to return matching assets eager-loaded with related elements. | +| [withTransforms](#withtransforms) | Causes the query to return matching assets eager-loaded with image transform indexes. | + ### `anyStatus` Clears out the [status()](https://docs.craftcms.com/api/v3/craft-elements-db-elementquery.html#method-status) and [enabledForSite()](https://docs.craftcms.com/api/v3/craft-elements-db-elementquery.html#method-enabledforsite) parameters. @@ -101,6 +142,15 @@ $assets = \craft\elements\Asset::find() ::: +### `clearCachedResult` + +Clears the cached result. + + + + + + ### `dateCreated` Narrows the query results based on the assets’ creation dates. @@ -212,128 +262,6 @@ $assets = \craft\elements\Asset::find() ::: -### `draftCreator` - -Narrows the query results to only drafts created by a given user. - - - -Possible values include: - -| Value | Fetches drafts… | -| -------------------------------------- | -------------------------------------- | -| `1` | created by the user with an ID of 1. | -| a `\craft\elements\db\User` object | by the user represented by the object. | - - - -::: code -```twig -{# Fetch drafts by the current user #} -{% set assets = craft.assets() - .draftCreator(currentUser) - .all() %} -``` - -```php -// Fetch drafts by the current user -$assets = \craft\elements\Asset::find() - ->draftCreator(Craft::$app->user->identity) - ->all(); -``` -::: - - -### `draftId` - -Narrows the query results based on the assets’ draft’s ID (from the `drafts` table). - - - -Possible values include: - -| Value | Fetches drafts… | -| ----- | ------------------------------ | -| `1` | for the draft with an ID of 1. | - - - -::: code -```twig -{# Fetch a draft #} -{% set assets = craft.assets() - .draftId(10) - .all() %} -``` - -```php -// Fetch a draft -$assets = \craft\elements\Asset::find() - ->draftIf(10) - ->all(); -``` -::: - - -### `draftOf` - -Narrows the query results to only drafts of a given asset. - - - -Possible values include: - -| Value | Fetches drafts… | -| -------------------------------------------- | ---------------------------------------- | -| `1` | for the asset with an ID of 1. | -| a [Asset](api:craft\elements\Asset) object | for the asset represented by the object. | - - - -::: code -```twig -{# Fetch drafts of the asset #} -{% set assets = craft.assets() - .draftOf(myAsset) - .all() %} -``` - -```php -// Fetch drafts of the asset -$assets = \craft\elements\Asset::find() - ->draftOf($myAsset) - ->all(); -``` -::: - - -### `drafts` - -Narrows the query results to only drafts assets. - - - - - -::: code -```twig -{# Fetch a draft asset #} -{% set assets = {twig-function} - .drafts() - .id(123) - .one() %} -``` - -```php -// Fetch a draft asset -$assets = \craft\elements\Asset::find() - ->drafts() - ->id(123) - ->one(); -``` -::: - - ### `filename` Narrows the query results based on the assets’ filenames. @@ -402,7 +330,7 @@ Narrows the query results based on the folders the assets belong to, per the fol Possible values include: -| Value | Fetches categories… | +| Value | Fetches assets… | | --------------- | ------------------------------------- | | `1` | in a folder with an ID of 1. | | `'not 1'` | not in a folder with an ID of 1. | @@ -420,7 +348,7 @@ Possible values include: ``` ```php -// Fetch categories in the folder with an ID of 1 +// Fetch assets in the folder with an ID of 1 $assets = \craft\elements\Asset::find() ->folderId(1) ->all(); @@ -559,7 +487,7 @@ Broadens the query results to include assets from any of the subfolders of the f ``` ```php -// Fetch categories in the folder with an ID of 1 (including its subfolders) +// Fetch assets in the folder with an ID of 1 (including its subfolders) $assets = \craft\elements\Asset::find() ->folderId(1) ->includeSubfolders() @@ -673,7 +601,7 @@ $assets = \craft\elements\Asset::find() ### `orderBy` -Determines the order that the assets should be returned in. +Determines the order that the assets should be returned in. (If empty, defaults to `dateCreated DESC`.) @@ -754,128 +682,6 @@ $assets = \craft\elements\Asset::find() ::: -### `revisionCreator` - -Narrows the query results to only revisions created by a given user. - - - -Possible values include: - -| Value | Fetches revisions… | -| -------------------------------------- | -------------------------------------- | -| `1` | created by the user with an ID of 1. | -| a `\craft\elements\db\User` object | by the user represented by the object. | - - - -::: code -```twig -{# Fetch revisions by the current user #} -{% set assets = craft.assets() - .revisionCreator(currentUser) - .all() %} -``` - -```php -// Fetch revisions by the current user -$assets = \craft\elements\Asset::find() - ->revisionCreator(Craft::$app->user->identity) - ->all(); -``` -::: - - -### `revisionId` - -Narrows the query results based on the assets’ revision’s ID (from the `revisions` table). - - - -Possible values include: - -| Value | Fetches revisions… | -| ----- | --------------------------------- | -| `1` | for the revision with an ID of 1. | - - - -::: code -```twig -{# Fetch a revision #} -{% set assets = craft.assets() - .revisionId(10) - .all() %} -``` - -```php -// Fetch a revision -$assets = \craft\elements\Asset::find() - ->revisionIf(10) - ->all(); -``` -::: - - -### `revisionOf` - -Narrows the query results to only revisions of a given asset. - - - -Possible values include: - -| Value | Fetches revisions… | -| -------------------------------------------- | ---------------------------------------- | -| `1` | for the asset with an ID of 1. | -| a [Asset](api:craft\elements\Asset) object | for the asset represented by the object. | - - - -::: code -```twig -{# Fetch revisions of the asset #} -{% set assets = craft.assets() - .revisionOf(myAsset) - .all() %} -``` - -```php -// Fetch revisions of the asset -$assets = \craft\elements\Asset::find() - ->revisionOf($myAsset) - ->all(); -``` -::: - - -### `revisions` - -Narrows the query results to only revision assets. - - - - - -::: code -```twig -{# Fetch a revision asset #} -{% set assets = {twig-function} - .revisions() - .id(123) - .one() %} -``` - -```php -// Fetch a revision asset -$assets = \craft\elements\Asset::find() - ->revisions() - ->id(123) - ->one(); -``` -::: - - ### `search` Narrows the query results to only assets that match a search query. @@ -919,13 +725,13 @@ The current site will be used by default. Possible values include: -| Value | Fetches assets… | -| -------------------------------------- | ---------------------------------------------- | -| `'foo'` | from the site with a handle of `foo`. | -| `['foo', 'bar']` | from a site with a handle of `foo` or `bar`. | -| `['not', 'foo', 'bar']` | not in a site with a handle of `foo` or `bar`. | -| a `\craft\elements\db\Site` object | from the site represented by the object. | -| `'*'` | from any site. | +| Value | Fetches assets… | +| ------------------------------------------------------- | ---------------------------------------------- | +| `'foo'` | from the site with a handle of `foo`. | +| `['foo', 'bar']` | from a site with a handle of `foo` or `bar`. | +| `['not', 'foo', 'bar']` | not in a site with a handle of `foo` or `bar`. | +| a [craft\models\Site](api:craft\models\Site) object | from the site represented by the object. | +| `'*'` | from any site. | ::: tip If multiple sites are specified, elements that belong to multiple sites will be returned multiple times. If you only want unique elements to be returned, use [unique](#unique) in conjunction with this. @@ -1124,13 +930,43 @@ $assets = \craft\elements\Asset::find() ::: +### `uploader` + +Narrows the query results based on the user the assets were uploaded by, per the user’s IDs. + +Possible values include: + +| Value | Fetches assets… | +| ----------------------------------------------------------- | ----------------------------------------------- | +| `1` | uploaded by the user with an ID of 1. | +| a [craft\elements\User](api:craft\elements\User) object | uploaded by the user represented by the object. | + + + +::: code +```twig +{# Fetch assets uploaded by the user with an ID of 1 #} +{% set assets = craft.assets() + .uploader(1) + .all() %} +``` + +```php +// Fetch assets uploaded by the user with an ID of 1 +$assets = \craft\elements\Asset::find() + ->uploader(1) + ->all(); +``` +::: + + ### `volume` Narrows the query results based on the volume the assets belong to. Possible values include: -| Value | Fetches categories… | +| Value | Fetches assets… | | ------------------------------------------ | ------------------------------------------------ | | `'foo'` | in a volume with a handle of `foo`. | | `'not foo'` | not in a volume with a handle of `foo`. | @@ -1163,7 +999,7 @@ Narrows the query results based on the volumes the assets belong to, per the vol Possible values include: -| Value | Fetches categories… | +| Value | Fetches assets… | | --------------- | ------------------------------------- | | `1` | in a volume with an ID of 1. | | `'not 1'` | not in a volume with an ID of 1. | @@ -1181,7 +1017,7 @@ Possible values include: ``` ```php -// Fetch categories in the volume with an ID of 1 +// Fetch assets in the volume with an ID of 1 $assets = \craft\elements\Asset::find() ->volumeId(1) ->all(); From 28faece602d8eb7b9c3b6ee7d165c10090a970b7 Mon Sep 17 00:00:00 2001 From: Brad Bell Date: Fri, 12 Jun 2020 17:32:00 -0700 Subject: [PATCH 018/245] New translations global-set-queries.md (Japanese) --- ja/dev/element-queries/global-set-queries.md | 446 +++++-------------- 1 file changed, 119 insertions(+), 327 deletions(-) diff --git a/ja/dev/element-queries/global-set-queries.md b/ja/dev/element-queries/global-set-queries.md index b3af9863d4c..875d606fe87 100644 --- a/ja/dev/element-queries/global-set-queries.md +++ b/ja/dev/element-queries/global-set-queries.md @@ -51,6 +51,31 @@ $myGlobalSetQuery = \craft\elements\GlobalSet::find(); +| Param | Description | +| ----------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| [anyStatus](#anystatus) | Clears out the [status()](https://docs.craftcms.com/api/v3/craft-elements-db-elementquery.html#method-status) and [enabledForSite()](https://docs.craftcms.com/api/v3/craft-elements-db-elementquery.html#method-enabledforsite) parameters. | +| [asArray](#asarray) | Causes the query to return matching global sets as arrays of data, rather than [GlobalSet](api:craft\elements\GlobalSet) objects. | +| [clearCachedResult](#clearcachedresult) | Clears the cached result. | +| [dateCreated](#datecreated) | Narrows the query results based on the global sets’ creation dates. | +| [dateUpdated](#dateupdated) | Narrows the query results based on the global sets’ last-updated dates. | +| [fixedOrder](#fixedorder) | Causes the query results to be returned in the order specified by [id](#id). | +| [handle](#handle) | Narrows the query results based on the global sets’ handles. | +| [id](#id) | Narrows the query results based on the global sets’ IDs. | +| [ignorePlaceholders](#ignoreplaceholders) | Causes the query to return matching global sets as they are stored in the database, ignoring matching placeholder elements that were set by [craft\services\Elements::setPlaceholderElement()](https://docs.craftcms.com/api/v3/craft-services-elements.html#method-setplaceholderelement). | +| [inReverse](#inreverse) | Causes the query results to be returned in reverse order. | +| [limit](#limit) | Determines the number of global sets that should be returned. | +| [offset](#offset) | Determines how many global sets should be skipped in the results. | +| [orderBy](#orderby) | Determines the order that the global sets should be returned in. (If empty, defaults to `name ASC`.) | +| [preferSites](#prefersites) | If [unique](#unique) is set, this determines which site should be selected when querying multi-site elements. | +| [relatedTo](#relatedto) | Narrows the query results to only global sets that are related to certain other elements. | +| [search](#search) | Narrows the query results to only global sets that match a search query. | +| [site](#site) | Determines which site(s) the global sets should be queried in. | +| [siteId](#siteid) | Determines which site(s) the global sets should be queried in, per the site’s ID. | +| [trashed](#trashed) | Narrows the query results to only global sets that have been soft-deleted. | +| [uid](#uid) | Narrows the query results based on the global sets’ UIDs. | +| [unique](#unique) | Determines whether only elements with unique IDs should be returned by the query. | +| [with](#with) | Causes the query to return matching global sets eager-loaded with related elements. | + ### `anyStatus` [status()](https://docs.craftcms.com/api/v3/craft-elements-db-elementquery.html#method-status) および [enabledForSite()](https://docs.craftcms.com/api/v3/craft-elements-db-elementquery.html#method-enabledforsite) パラメータをクリアします。 @@ -101,19 +126,28 @@ $globalSets = \craft\elements\GlobalSet::find() ::: +### `clearCachedResult` + +Clears the cached result. + + + + + + ### `dateCreated` -グローバル設定の作成日に基づいて、クエリの結果を絞り込みます。 +Narrows the query results based on the global sets’ creation dates. -利用可能な値には、次のものが含まれます。 +Possible values include: -| 値 | 取得するグローバル設定 | -| ------------------------------------------------ | ------------------------------------ | -| `'>= 2018-04-01'` | 2018-04-01 以降に作成されたもの。 | -| `'< 2018-05-01'` | 2018-05-01 より前に作成されたもの。 | -| `['and', '>= 2018-04-04', '< 2018-05-01']` | 2018-04-01 から 2018-05-01 の間に作成されたもの。 | +| 値 | 取得するグローバル設定 | +| ------------------------------------------------ | ---------------------------------------------------- | +| `'>= 2018-04-01'` | that were created on or after 2018-04-01. | +| `'< 2018-05-01'` | that were created before 2018-05-01 | +| `['and', '>= 2018-04-04', '< 2018-05-01']` | that were created between 2018-04-01 and 2018-05-01. | @@ -142,17 +176,17 @@ $globalSets = \craft\elements\GlobalSet::find() ### `dateUpdated` -グローバル設定の最終アップデート日に基づいて、クエリの結果を絞り込みます。 +Narrows the query results based on the global sets’ last-updated dates. -利用可能な値には、次のものが含まれます。 +Possible values include: -| 値 | 取得するグローバル設定 | -| ------------------------------------------------ | ---------------------------------------- | -| `'>= 2018-04-01'` | 2018-04-01 以降にアップデートされたもの。 | -| `'< 2018-05-01'` | 2018-05-01 より前にアップデートされたもの。 | -| `['and', '>= 2018-04-04', '< 2018-05-01']` | 2018-04-01 から 2018-05-01 の間にアップデートされたもの。 | +| 値 | Fetches global sets… | +| ------------------------------------------------ | ---------------------------------------------------- | +| `'>= 2018-04-01'` | that were updated on or after 2018-04-01. | +| `'< 2018-05-01'` | that were updated before 2018-05-01 | +| `['and', '>= 2018-04-04', '< 2018-05-01']` | that were updated between 2018-04-01 and 2018-05-01. | @@ -179,20 +213,13 @@ $globalSets = \craft\elements\GlobalSet::find() ### `fixedOrder` -クエリの結果を [id](#id) で指定された順序で返します。 +Causes the query results to be returned in the order specified by [id](#id). -::: code - -| 値 | 取得するグローバル設定 | -| -------------------------------------- | ----------------- | -| `08975709'foo'` | ハンドルが `foo`。 | -| a `\craft\elements\db\User` object | ハンドルが `foo` ではない。 | - -::: +::: code ```twig {# Fetch global sets in a specific order #} {% set globalSets = craft.globalSets() @@ -213,19 +240,20 @@ $globalSets = \craft\elements\GlobalSet::find() ### `handle` -利用可能な値には、次のものが含まれます。 +Narrows the query results based on the global sets’ handles. +Possible values include: - -::: code - -| 値 | 取得するグローバル設定 | -| --- | ----------- | -| `1` | ID が 1。 | +| 値 | Fetches global sets… | +| ----------------------- | ------------------------------------ | +| `'foo'` | with a handle of `foo`. | +| `'not foo'` | not with a handle of `foo`. | +| `['foo', 'bar']` | with a handle of `foo` or `bar`. | +| `['not', 'foo', 'bar']` | not with a handle of `foo` or `bar`. | -::: +::: code ```twig {# Fetch the global set with a handle of 'foo' #} {% set globalSet = craft.globalSets() @@ -244,20 +272,22 @@ $globalSet = \craft\elements\GlobalSet::find() ### `id` -利用可能な値には、次のものが含まれます。 +Narrows the query results based on the global sets’ IDs. -::: code +Possible values include: -| 値 | 取得するグローバル設定 | -| ------------------------------------ | ------------------- | -| `45784548'foo'` | ハンドルが `foo` のサイトから。 | -| `\craft\elements\db\Site` オブジェクト | オブジェクトで表されるサイトから。 | +| 値 | Fetches global sets… | +| --------------- | ------------------------- | +| `1` | with an ID of 1. | +| `'not 1'` | not with an ID of 1. | +| `[1, 2]` | with an ID of 1 or 2. | +| `['not', 1, 2]` | not with an ID of 1 or 2. | -::: +::: code ```twig {# Fetch the global set by its ID #} {% set globalSet = craft.globalSets() @@ -274,9 +304,28 @@ $globalSet = \craft\elements\GlobalSet::find() ::: + +::: tip +This can be combined with [fixedOrder](#fixedorder) if you want the results to be returned in a specific order. +::: + + +### `ignorePlaceholders` + +Causes the query to return matching global sets as they are stored in the database, ignoring matching placeholder elements that were set by [craft\services\Elements::setPlaceholderElement()](https://docs.craftcms.com/api/v3/craft-services-elements.html#method-setplaceholderelement). + + + + + + + + + + ### `inReverse` -クエリの結果を逆順で返します。 +Causes the query results to be returned in reverse order. @@ -301,9 +350,7 @@ $globalSets = \craft\elements\GlobalSet::find() ### `limit` -返されるグローバル設定の数を決定します。 - - +Determines the number of global sets that should be returned. @@ -326,20 +373,11 @@ $globalSets = \craft\elements\GlobalSet::find() ### `offset` -結果からスキップされるグローバル設定の数を決定します。 - -::: code - -| Value | Fetches global sets… | -| ----------------------- | ------------------------------------ | -| `'foo'` | with a handle of `foo`. | -| `'not foo'` | not with a handle of `foo`. | -| `['foo', 'bar']` | with a handle of `foo` or `bar`. | -| `['not', 'foo', 'bar']` | not with a handle of `foo` or `bar`. | +Determines how many global sets should be skipped in the results. -::: +::: code ```twig {# Fetch all global sets except for the first 3 #} {% set globalSets = craft.globalSets() @@ -358,22 +396,11 @@ $globalSets = \craft\elements\GlobalSet::find() ### `orderBy` -::: code - - - -::: - -| Value | Fetches global sets… | -| --------------- | ------------------------- | -| `1` | with an ID of 1. | -| `'not 1'` | not with an ID of 1. | -| `[1, 2]` | with an ID of 1 or 2. | -| `['not', 1, 2]` | not with an ID of 1 or 2. | +Determines the order that the global sets should be returned in. (If empty, defaults to `name ASC`.) -特定の他のエレメントと関連付けられたグローバル設定だけに、クエリの結果を絞り込みます。 +::: code ```twig {# Fetch all global sets in order of date created #} {% set globalSets = craft.globalSets() @@ -390,301 +417,66 @@ $globalSets = \craft\elements\GlobalSet::find() ::: +### `preferSites` -::: code - - -### `relatedTo` - -::: - - - - - - - - - - -### `search` - -検索クエリにマッチするグローバル設定だけに、クエリの結果を絞り込みます。 - - - - - -このパラメーターがどのように機能するかの詳細については、[検索](https://docs.craftcms.com/v3/searching.html)を参照してください。 -```twig -{# Fetch all global sets that are related to myCategory #} -{% set globalSets = craft.globalSets() - .relatedTo(myCategory) - .all() %} -``` - -```php -// Fetch all global sets that are related to $myCategory -$globalSets = \craft\elements\GlobalSet::find() - ->relatedTo($myCategory) - ->all(); -``` -::: - - -### `site` - -::: - - - -グローバル設定を照会するサイトを決定します。 -```twig -{# Get the search query from the 'q' query string param #} -{% set searchQuery = craft.app.request.getQueryParam('q') %} - -{# Fetch all global sets that match the search query #} -{% set globalSets = craft.globalSets() - .search(searchQuery) - .all() %} -``` - -```php -// Get the search query from the 'q' query string param -$searchQuery = \Craft::$app->request->getQueryParam('q'); - -// Fetch all global sets that match the search query -$globalSets = \craft\elements\GlobalSet::find() - ->search($searchQuery) - ->all(); -``` -::: - - -### `siteId` - -利用可能な値には、次のものが含まれます。 - - - -::: code -```twig -{# Fetch global sets from the Foo site #} -{% set globalSets = craft.globalSets() - .site('foo') - .all() %} -``` - -```php -// Fetch global sets from the Foo site -$globalSets = \craft\elements\GlobalSet::find() - ->site('foo') - ->all(); -``` -::: - - -### `trashed` - -サイトの ID ごとに、グローバル設定を照会するサイトを決定します。 - - - -デフォルトでは、現在のサイトが使用されます。 -```twig -{# Fetch global sets from the site with an ID of 1 #} -{% set globalSets = craft.globalSets() - .siteId(1) - .all() %} -``` - -```php -// Fetch global sets from the site with an ID of 1 -$globalSets = \craft\elements\GlobalSet::find() - ->siteId(1) - ->all(); -``` -::: - - -### `uid` - -::: - - - -ソフトデリートされたグローバル設定だけに、クエリの結果を絞り込みます。 - -::: code - - - -::: -```twig -{# Fetch trashed global sets #} -{% set globalSets = {twig-function} - .trashed() - .all() %} -``` - -```php -// Fetch trashed global sets -$globalSets = \craft\elements\GlobalSet::find() - ->trashed() - ->all(); -``` -::: - - -### `with` - -::: code - - - -::: - - - -関連付けられたエレメントを eager-loaded した状態で、マッチしたグローバル設定をクエリが返します。 -```twig -{# Fetch the global set by its UID #} -{% set globalSet = craft.globalSets() - .uid('xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx') - .one() %} -``` - -```php -// Fetch the global set by its UID -$globalSet = \craft\elements\GlobalSet::find() - ->uid('xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx') - ->one(); -``` -::: - - -### `revisionCreator` - -::: code - - - -::: - -| Value | Fetches revisions… | -| -------------------------------------- | -------------------------------------- | -| `1` | created by the user with an ID of 1. | -| a `\craft\elements\db\User` object | by the user represented by the object. | - - - -::: code -```twig -{# Fetch global sets eager-loaded with the "Related" field’s relations #} -{% set globalSets = craft.globalSets() - .with(['related']) - .all() %} -``` - -```php -// Fetch global sets eager-loaded with the "Related" field’s relations -$globalSets = \craft\elements\GlobalSet::find() - ->with(['related']) - ->all(); -``` -::: - - -### `revisionId` - -Narrows the query results based on the global sets’ revision’s ID (from the `revisions` table). +If [unique](#unique) is set, this determines which site should be selected when querying multi-site elements. -Possible values include: +For example, if element “Foo” exists in Site A and Site B, and element “Bar” exists in Site B and Site C, and this is set to `['c', 'b', 'a']`, then Foo will be returned for Site C, and Bar will be returned for Site B. -| Value | Fetches revisions… | -| ----- | --------------------------------- | -| `1` | for the revision with an ID of 1. | +If this isn’t set, then preference goes to the current site. ::: code ```twig -{# Fetch a revision #} +{# Fetch unique global sets from Site A, or Site B if they don’t exist in Site A #} {% set globalSets = craft.globalSets() - .revisionId(10) + .site('*') + .unique() + .preferSites(['a', 'b']) .all() %} ``` ```php -// Fetch a revision +// Fetch unique global sets from Site A, or Site B if they don’t exist in Site A $globalSets = \craft\elements\GlobalSet::find() - ->revisionIf(10) + ->site('*') + ->unique() + ->preferSites(['a', 'b']) ->all(); ``` ::: -### `revisionOf` - -Narrows the query results to only revisions of a given global set. +### `relatedTo` +Narrows the query results to only global sets that are related to certain other elements. -Possible values include: -| Value | Fetches revisions… | -| ---------------------------------------------------- | --------------------------------------------- | -| `1` | for the global set with an ID of 1. | -| a [GlobalSet](api:craft\elements\GlobalSet) object | for the global set represented by the object. | +See [Relations](https://docs.craftcms.com/v3/relations.html) for a full explanation of how to work with this parameter. ::: code ```twig -{# Fetch revisions of the global set #} +{# Fetch all global sets that are related to myCategory #} {% set globalSets = craft.globalSets() - .revisionOf(myGlobalSet) + .relatedTo(myCategory) .all() %} ``` ```php -// Fetch revisions of the global set +// Fetch all global sets that are related to $myCategory $globalSets = \craft\elements\GlobalSet::find() - ->revisionOf($myGlobalSet) + ->relatedTo($myCategory) ->all(); ``` ::: -### `revisions` - -Narrows the query results to only revision global sets. - - - - - -::: code -```twig -{# Fetch a revision global set #} -{% set globalSets = {twig-function} - .revisions() - .id(123) - .one() %} -``` - -```php -// Fetch a revision global set -$globalSets = \craft\elements\GlobalSet::find() - ->revisions() - ->id(123) - ->one(); -``` -::: - - ### `search` Narrows the query results to only global sets that match a search query. @@ -728,13 +520,13 @@ The current site will be used by default. Possible values include: -| Value | Fetches global sets… | -| -------------------------------------- | ---------------------------------------------- | -| `'foo'` | from the site with a handle of `foo`. | -| `['foo', 'bar']` | from a site with a handle of `foo` or `bar`. | -| `['not', 'foo', 'bar']` | not in a site with a handle of `foo` or `bar`. | -| a `\craft\elements\db\Site` object | from the site represented by the object. | -| `'*'` | from any site. | +| Value | Fetches global sets… | +| ------------------------------------------------------- | ---------------------------------------------- | +| `'foo'` | from the site with a handle of `foo`. | +| `['foo', 'bar']` | from a site with a handle of `foo` or `bar`. | +| `['not', 'foo', 'bar']` | not in a site with a handle of `foo` or `bar`. | +| a [craft\models\Site](api:craft\models\Site) object | from the site represented by the object. | +| `'*'` | from any site. | ::: tip If multiple sites are specified, elements that belong to multiple sites will be returned multiple times. If you only want unique elements to be returned, use [unique](#unique) in conjunction with this. From cec79a9c8f35f57662398bb7e740710d829c1161 Mon Sep 17 00:00:00 2001 From: Brad Bell Date: Fri, 12 Jun 2020 17:32:02 -0700 Subject: [PATCH 019/245] New translations asset-queries.md (Japanese) --- ja/dev/element-queries/asset-queries.md | 678 +++++++++--------------- 1 file changed, 261 insertions(+), 417 deletions(-) diff --git a/ja/dev/element-queries/asset-queries.md b/ja/dev/element-queries/asset-queries.md index 43ad700549d..ee932a41775 100644 --- a/ja/dev/element-queries/asset-queries.md +++ b/ja/dev/element-queries/asset-queries.md @@ -45,15 +45,56 @@ $myAssetQuery = \craft\elements\Asset::find(); ``` +::: warning +When using `asset.url` or `asset.getUrl()`, the asset’s source volume must have “Assets in this volume have public URLs” enabled and a “Base URL” setting. Otherwise, the result will always be empty. +::: + ## パラメータ -アセットクエリは、次のパラメータをサポートしています。 +Asset queries support the following parameters: +| Param | Description | +| ----------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| [anyStatus](#anystatus) | Clears out the [status()](https://docs.craftcms.com/api/v3/craft-elements-db-elementquery.html#method-status) and [enabledForSite()](https://docs.craftcms.com/api/v3/craft-elements-db-elementquery.html#method-enabledforsite) parameters. | +| [asArray](#asarray) | Causes the query to return matching assets as arrays of data, rather than [Asset](api:craft\elements\Asset) objects. | +| [clearCachedResult](#clearcachedresult) | Clears the cached result. | +| [dateCreated](#datecreated) | Narrows the query results based on the assets’ creation dates. | +| [dateModified](#datemodified) | Narrows the query results based on the assets’ files’ last-modified dates. | +| [dateUpdated](#dateupdated) | Narrows the query results based on the assets’ last-updated dates. | +| [filename](#filename) | Narrows the query results based on the assets’ filenames. | +| [fixedOrder](#fixedorder) | Causes the query results to be returned in the order specified by [id](#id). | +| [folderId](#folderid) | Narrows the query results based on the folders the assets belong to, per the folders’ IDs. | +| [height](#height) | Narrows the query results based on the assets’ image heights. | +| [id](#id) | Narrows the query results based on the assets’ IDs. | +| [ignorePlaceholders](#ignoreplaceholders) | Causes the query to return matching assets as they are stored in the database, ignoring matching placeholder elements that were set by [craft\services\Elements::setPlaceholderElement()](https://docs.craftcms.com/api/v3/craft-services-elements.html#method-setplaceholderelement). | +| [inReverse](#inreverse) | Causes the query results to be returned in reverse order. | +| [includeSubfolders](#includesubfolders) | Broadens the query results to include assets from any of the subfolders of the folder specified by [folderId](#folderid). | +| [kind](#kind) | Narrows the query results based on the assets’ file kinds. | +| [limit](#limit) | Determines the number of assets that should be returned. | +| [offset](#offset) | Determines how many assets should be skipped in the results. | +| [orderBy](#orderby) | Determines the order that the assets should be returned in. (If empty, defaults to `dateCreated DESC`.) | +| [preferSites](#prefersites) | If [unique](#unique) is set, this determines which site should be selected when querying multi-site elements. | +| [relatedTo](#relatedto) | Narrows the query results to only assets that are related to certain other elements. | +| [search](#search) | Narrows the query results to only assets that match a search query. | +| [site](#site) | Determines which site(s) the assets should be queried in. | +| [siteId](#siteid) | Determines which site(s) the assets should be queried in, per the site’s ID. | +| [size](#size) | Narrows the query results based on the assets’ file sizes (in bytes). | +| [title](#title) | Narrows the query results based on the assets’ titles. | +| [trashed](#trashed) | Narrows the query results to only assets that have been soft-deleted. | +| [uid](#uid) | Narrows the query results based on the assets’ UIDs. | +| [unique](#unique) | Determines whether only elements with unique IDs should be returned by the query. | +| [uploader](#uploader) | Narrows the query results based on the user the assets were uploaded by, per the user’s IDs. | +| [volume](#volume) | Narrows the query results based on the volume the assets belong to. | +| [volumeId](#volumeid) | Narrows the query results based on the volumes the assets belong to, per the volumes’ IDs. | +| [width](#width) | Narrows the query results based on the assets’ image widths. | +| [with](#with) | Causes the query to return matching assets eager-loaded with related elements. | +| [withTransforms](#withtransforms) | Causes the query to return matching assets eager-loaded with image transform indexes. | + ### `anyStatus` -[status()](https://docs.craftcms.com/api/v3/craft-elements-db-elementquery.html#method-status) および [enabledForSite()](https://docs.craftcms.com/api/v3/craft-elements-db-elementquery.html#method-enabledforsite) パラメータをクリアします。 +Clears out the [status()](https://docs.craftcms.com/api/v3/craft-elements-db-elementquery.html#method-status) and [enabledForSite()](https://docs.craftcms.com/api/v3/craft-elements-db-elementquery.html#method-enabledforsite) parameters. @@ -78,7 +119,7 @@ $assets = \craft\elements\Asset::find() ### `asArray` -[Asset](api:craft\elements\Asset) オブジェクトではなく、データの配列として、マッチしたアセットをクエリが返します。 +Causes the query to return matching assets as arrays of data, rather than [Asset](api:craft\elements\Asset) objects. @@ -101,19 +142,28 @@ $assets = \craft\elements\Asset::find() ::: +### `clearCachedResult` + +Clears the cached result. + + + + + + ### `dateCreated` -アセットの作成日に基づいて、クエリの結果を絞り込みます。 +Narrows the query results based on the assets’ creation dates. -利用可能な値には、次のものが含まれます。 +Possible values include: -| 値 | 取得するアセット | -| ------------------------------------------------ | ------------------------------------ | -| `'>= 2018-04-01'` | 2018-04-01 以降に作成されたもの。 | -| `'< 2018-05-01'` | 2018-05-01 より前に作成されたもの。 | -| `['and', '>= 2018-04-04', '< 2018-05-01']` | 2018-04-01 から 2018-05-01 の間に作成されたもの。 | +| 値 | 取得するアセット | +| ------------------------------------------------ | ---------------------------------------------------- | +| `'>= 2018-04-01'` | that were created on or after 2018-04-01. | +| `'< 2018-05-01'` | that were created before 2018-05-01 | +| `['and', '>= 2018-04-04', '< 2018-05-01']` | that were created between 2018-04-01 and 2018-05-01. | @@ -142,15 +192,15 @@ $assets = \craft\elements\Asset::find() ### `dateModified` -アセットファイルの最終更新日に基づいて、クエリの結果を絞り込みます。 +Narrows the query results based on the assets’ files’ last-modified dates. -利用可能な値には、次のものが含まれます。 +Possible values include: -| 値 | 取得するアセット | -| ------------------------------------------------ | ------------------------------------ | -| `'>= 2018-04-01'` | 2018-04-01 以降に更新されたもの。 | -| `'< 2018-05-01'` | 2018-05-01 より前に更新されたもの。 | -| `['and', '>= 2018-04-04', '< 2018-05-01']` | 2018-04-01 から 2018-05-01 の間に更新されたもの。 | +| 値 | 取得するアセット | +| ------------------------------------------------ | ----------------------------------------------------- | +| `'>= 2018-04-01'` | that were modified on or after 2018-04-01. | +| `'< 2018-05-01'` | that were modified before 2018-05-01 | +| `['and', '>= 2018-04-04', '< 2018-05-01']` | that were modified between 2018-04-01 and 2018-05-01. | @@ -177,17 +227,17 @@ $assets = \craft\elements\Asset::find() ### `dateUpdated` -アセットの最終アップデート日に基づいて、クエリの結果を絞り込みます。 +Narrows the query results based on the assets’ last-updated dates. -利用可能な値には、次のものが含まれます。 +Possible values include: -| 値 | 取得するアセット | -| ------------------------------------------------ | ---------------------------------------- | -| `'>= 2018-04-01'` | 2018-04-01 以降にアップデートされたもの。 | -| `'< 2018-05-01'` | 2018-05-01 より前にアップデートされたもの。 | -| `['and', '>= 2018-04-04', '< 2018-05-01']` | 2018-04-01 から 2018-05-01 の間にアップデートされたもの。 | +| 値 | Fetches assets… | +| ------------------------------------------------ | ---------------------------------------------------- | +| `'>= 2018-04-01'` | that were updated on or after 2018-04-01. | +| `'< 2018-05-01'` | that were updated before 2018-05-01 | +| `['and', '>= 2018-04-04', '< 2018-05-01']` | that were updated between 2018-04-01 and 2018-05-01. | @@ -214,16 +264,19 @@ $assets = \craft\elements\Asset::find() ### `filename` -アセットのファイル名に基づいて、クエリの結果を絞り込みます。 +Narrows the query results based on the assets’ filenames. +Possible values include: - -利用可能な値には、次のものが含まれます。 - -| 値 | 取得するアセット | -| -------------------------------------- | ------------------- | -| `f4890a6.83992027'foo.jpg'` | ファイル名が `foo.jpg`。 | -| a `\craft\elements\db\User` object | ファイル名が `foo` ではじまる。 | +| 値 | Fetches assets… | +| --------------------------- | ---------------------------------------------------- | +| `'foo.jpg'` | with a filename of `foo.jpg`. | +| `'foo*'` | with a filename that begins with `foo`. | +| `'*.jpg'` | with a filename that ends with `.jpg`. | +| `'*foo*'` | with a filename that contains `foo`. | +| `'not *foo*'` | with a filename that doesn’t contain `foo`. | +| `['*foo*', '*bar*']` | with a filename that contains `foo` or `bar`. | +| `['not', '*foo*', '*bar*']` | with a filename that doesn’t contain `foo` or `bar`. | @@ -246,19 +299,13 @@ $assets = \craft\elements\Asset::find() ### `fixedOrder` -クエリの結果を [id](#id) で指定された順序で返します。 +Causes the query results to be returned in the order specified by [id](#id). -::: code - -| 値 | 取得するアセット | -| --- | -------------- | -| `1` | ID が 1 のフォルダ内。 | - -::: +::: code ```twig {# Fetch assets in a specific order #} {% set assets = craft.assets() @@ -279,20 +326,20 @@ $assets = \craft\elements\Asset::find() ### `folderId` -利用可能な値には、次のものが含まれます。 - +Narrows the query results based on the folders the assets belong to, per the folders’ IDs. +Possible values include: -::: code - -| 値 | 取得するアセット | -| -------------------------------------------- | --------------- | -| `00100669100` | 高さ 100px。 | -| a [Asset](api:craft\elements\Asset) object | 少なくとも、高さ 100px。 | +| 値 | Fetches assets… | +| --------------- | ------------------------------------- | +| `1` | in a folder with an ID of 1. | +| `'not 1'` | not in a folder with an ID of 1. | +| `[1, 2]` | in a folder with an ID of 1 or 2. | +| `['not', 1, 2]` | not in a folder with an ID of 1 or 2. | -::: +::: code ```twig {# Fetch assets in the folder with an ID of 1 #} {% set assets = craft.assets() @@ -301,7 +348,7 @@ $assets = \craft\elements\Asset::find() ``` ```php -// Fetch categories in the folder with an ID of 1 +// Fetch assets in the folder with an ID of 1 $assets = \craft\elements\Asset::find() ->folderId(1) ->all(); @@ -309,15 +356,25 @@ $assets = \craft\elements\Asset::find() ::: + +::: tip +This can be combined with [includeSubfolders](#includesubfolders) if you want to include assets in all the subfolders of a certain folder. +::: ### `height` -アセットの画像の高さに基づいて、クエリの結果を絞り込みます。 +Narrows the query results based on the assets’ image heights. +Possible values include: +| 値 | 取得するアセット | +| ----------------------------- | ------------------------------------ | +| `100` | with a height of 100. | +| `'>= 100'` | with a height of at least 100. | +| `['>= 100', '<= 1000']` | with a height between 100 and 1,000. | -利用可能な値には、次のものが含まれます。 +::: code ```twig {# Fetch XL images #} {% set assets = craft.assets() @@ -338,23 +395,22 @@ $assets = \craft\elements\Asset::find() ### `id` -::: +Narrows the query results based on the assets’ IDs. -アセットの ID に基づいて、クエリの結果を絞り込みます。 -| 値 | 取得するアセット | -| --------------------------- | ---------------------------------------------------- | -| `1` | ID が 1。 | -| `'not 1'` | ID が 1ではない。 | -| `[1, 2]` | ID が 1 または 2。 | -| `['not', 1, 2]` | ID が 1 または 2 ではない。 | -| `'not *foo*'` | with a filename that doesn’t contain `foo`. | -| `['*foo*', '*bar*']` | with a filename that contains `foo` or `bar`. | -| `['not', '*foo*', '*bar*']` | with a filename that doesn’t contain `foo` or `bar`. | +Possible values include: +| 値 | Fetches assets… | +| --------------- | ------------------------- | +| `1` | with an ID of 1. | +| `'not 1'` | not with an ID of 1. | +| `[1, 2]` | with an ID of 1 or 2. | +| `['not', 1, 2]` | not with an ID of 1 or 2. | -利用可能な値には、次のものが含まれます。 + + +::: code ```twig {# Fetch the asset by its ID #} {% set asset = craft.assets() @@ -371,208 +427,84 @@ $asset = \craft\elements\Asset::find() ::: -### `inReverse` - -::: - - - - ::: tip -特定の順序で結果を返したい場合、[fixedOrder](#fixedorder) と組み合わせることができます。 -::: -```twig -{# Fetch assets in reverse #} -{% set assets = craft.assets() - .inReverse() - .all() %} -``` - -```php -// Fetch assets in reverse -$assets = \craft\elements\Asset::find() - ->inReverse() - ->all(); -``` +This can be combined with [fixedOrder](#fixedorder) if you want the results to be returned in a specific order. ::: -### `includeSubfolders` +### `ignorePlaceholders` -::: code +Causes the query to return matching assets as they are stored in the database, ignoring matching placeholder elements that were set by [craft\services\Elements::setPlaceholderElement()](https://docs.craftcms.com/api/v3/craft-services-elements.html#method-setplaceholderelement). -::: -| 値 | 取得するアセット | -| ------------------------- | -------------------------------- | -| `d86.57052653'image'` | ファイルの種類が `image`。 | -| `'not image'` | ファイルの種類が `image` ではない。 | -| `['image', 'pdf']` | ファイルの種類が `image` または `pdf`。 | -| `['not', 'image', 'pdf']` | ファイルの種類が `image` または `pdf` ではない。 | -[folderId](#folderid) で指定されたフォルダのすべてのサブフォルダにあるアセットを含むよう、クエリの結果を拡張します。 -```twig -{# Fetch assets in the folder with an ID of 1 (including its subfolders) #} -{% set assets = craft.assets() - .folderId(1) - .includeSubfolders() - .all() %} -``` -```php -// Fetch categories in the folder with an ID of 1 (including its subfolders) -$assets = \craft\elements\Asset::find() - ->folderId(1) - ->includeSubfolders() - ->all(); -``` -::: -::: -### `kind` -::: warning -これは [folderId](#folderid) に単一のフォルダ ID がセットされているときだけ、動作します。 -::: +### `inReverse` -アセットのファイルの種類に基づいて、クエリの結果を絞り込みます。 +Causes the query results to be returned in reverse order. -| 値 | 取得するアセット | -| ----------------------------- | ------------------------------------ | -| `'foo'` | ハンドルが `foo` のサイトから。 | -| `'>= 100'` | オブジェクトで表されるサイトから。 | -| `['>= 100', '<= 1000']` | with a height between 100 and 1,000. | -サポートされるファイルの種類： -```twig -{# Fetch all the images #} -{% set assets = craft.assets() - .kind('image') - .all() %} -``` - -```php -// Fetch all the images -$assets = \craft\elements\Asset::find() - ->kind('image') - ->all(); -``` -::: - - -### `limit` ::: code - - - -::: - -| 値 | 取得するアセット | -| -------------------------------- | -------------------------------- | -| `6100023771000` | サイズが 1,000 bytes（1KB）。 | -| `'< 1000000'` | サイズが 1,000,000 bytes（1MB）よりも小さい。 | -| `['>= 1000', '< 1000000']` | サイズが 1KB から 1MB の間。 | -| `['not', 1, 2]` | not with an ID of 1 or 2. | - - - -返されるアセットの数を決定します。 ```twig -{# Fetch up to 10 assets #} +{# Fetch assets in reverse #} {% set assets = craft.assets() - .limit(10) + .inReverse() .all() %} ``` ```php -// Fetch up to 10 assets +// Fetch assets in reverse $assets = \craft\elements\Asset::find() - ->limit(10) + ->inReverse() ->all(); ``` ::: +### `includeSubfolders` -::: - - -### `offset` - -結果からスキップされるアセットの数を決定します。 - - - - - - - - +Broadens the query results to include assets from any of the subfolders of the folder specified by [folderId](#folderid). -### `orderBy` ::: code - - - - - -::: ```twig -{# Fetch all assets except for the first 3 #} +{# Fetch assets in the folder with an ID of 1 (including its subfolders) #} {% set assets = craft.assets() - .offset(3) + .folderId(1) + .includeSubfolders() .all() %} ``` ```php -// Fetch all assets except for the first 3 +// Fetch assets in the folder with an ID of 1 (including its subfolders) $assets = \craft\elements\Asset::find() - ->offset(3) + ->folderId(1) + ->includeSubfolders() ->all(); ``` ::: -### `relatedTo` - -::: code - - - -::: -```twig -{# Fetch all assets in order of date created #} -{% set assets = craft.assets() - .orderBy('dateCreated asc') - .all() %} -``` -```php -// Fetch all assets in order of date created -$assets = \craft\elements\Asset::find() - ->orderBy('dateCreated asc') - ->all(); -``` +::: warning +This will only work if [folderId](#folderid) was set to a single folder ID. ::: +### `kind` +Narrows the query results based on the assets’ file kinds. - -このパラメーターがどのように機能するかの詳細については、[リレーション](https://docs.craftcms.com/v3/relations.html)を参照してください。 -### `search` - -::: code - -::: +Supported file kinds: - `access` - `audio` - `compressed` @@ -593,348 +525,232 @@ $assets = \craft\elements\Asset::find() - `xml` - `unknown` -検索クエリにマッチするアセットだけに、クエリの結果を絞り込みます。 +Possible values include: -| 値 | 取得するアセット | -| --------- | ------------------ | -| `'Foo'` | タイトルが `Foo`。 | -| `'Foo*'` | タイトルが `Foo` ではじまる。 | -| `'*Foo'` | タイトルが `Foo` で終わる。 | -| `'*Foo*'` | タイトルが `Foo` を含む。 | +| 値 | 取得するアセット | +| ------------------------- | ----------------------------------------- | +| `'image'` | with a file kind of `image`. | +| `'not image'` | not with a file kind of `image`.. | +| `['image', 'pdf']` | with a file kind of `image` or `pdf`. | +| `['not', 'image', 'pdf']` | not with a file kind of `image` or `pdf`. | -このパラメーターがどのように機能するかの詳細については、[検索](https://docs.craftcms.com/v3/searching.html)を参照してください。 +::: code ```twig -{# Fetch all assets that are related to myCategory #} +{# Fetch all the images #} {% set assets = craft.assets() - .relatedTo(myCategory) + .kind('image') .all() %} ``` ```php -// Fetch all assets that are related to $myCategory +// Fetch all the images $assets = \craft\elements\Asset::find() - ->relatedTo($myCategory) + ->kind('image') ->all(); ``` ::: -### `site` +### `limit` -::: +Determines the number of assets that should be returned. -アセットを照会するサイトを決定します。 +::: code ```twig -{# Get the search query from the 'q' query string param #} -{% set searchQuery = craft.app.request.getQueryParam('q') %} - -{# Fetch all assets that match the search query #} +{# Fetch up to 10 assets #} {% set assets = craft.assets() - .search(searchQuery) + .limit(10) .all() %} ``` ```php -// Get the search query from the 'q' query string param -$searchQuery = \Craft::$app->request->getQueryParam('q'); - -// Fetch all assets that match the search query +// Fetch up to 10 assets $assets = \craft\elements\Asset::find() - ->search($searchQuery) + ->limit(10) ->all(); ``` ::: -### `siteId` +### `offset` -利用可能な値には、次のものが含まれます。 +Determines how many assets should be skipped in the results. ::: code ```twig -{# Fetch assets from the Foo site #} +{# Fetch all assets except for the first 3 #} {% set assets = craft.assets() - .site('foo') + .offset(3) .all() %} ``` ```php -// Fetch assets from the Foo site +// Fetch all assets except for the first 3 $assets = \craft\elements\Asset::find() - ->site('foo') + ->offset(3) ->all(); ``` ::: -### `size` +### `orderBy` -サイトの ID ごとに、アセットを照会するサイトを決定します。 +Determines the order that the assets should be returned in. (If empty, defaults to `dateCreated DESC`.) -デフォルトでは、現在のサイトが使用されます。 +::: code ```twig -{# Fetch assets from the site with an ID of 1 #} +{# Fetch all assets in order of date created #} {% set assets = craft.assets() - .siteId(1) + .orderBy('dateCreated asc') .all() %} ``` ```php -// Fetch assets from the site with an ID of 1 +// Fetch all assets in order of date created $assets = \craft\elements\Asset::find() - ->siteId(1) + ->orderBy('dateCreated asc') ->all(); ``` ::: -### `title` +### `preferSites` -::: +If [unique](#unique) is set, this determines which site should be selected when querying multi-site elements. -アセットのファイルサイズ（バイト単位）に基づいて、クエリの結果を絞り込みます。 +For example, if element “Foo” exists in Site A and Site B, and element “Bar” exists in Site B and Site C, and this is set to `['c', 'b', 'a']`, then Foo will be returned for Site C, and Bar will be returned for Site B. -利用可能な値には、次のものが含まれます。 +If this isn’t set, then preference goes to the current site. ::: code ```twig -{# Fetch assets that are smaller than 1KB #} +{# Fetch unique assets from Site A, or Site B if they don’t exist in Site A #} {% set assets = craft.assets() - .size('< 1000') + .site('*') + .unique() + .preferSites(['a', 'b']) .all() %} ``` ```php -// Fetch assets that are smaller than 1KB +// Fetch unique assets from Site A, or Site B if they don’t exist in Site A $assets = \craft\elements\Asset::find() - ->size('< 1000') + ->site('*') + ->unique() + ->preferSites(['a', 'b']) ->all(); ``` ::: -### `trashed` +### `relatedTo` -アセットのタイトルに基づいて、クエリの結果を絞り込みます。 +Narrows the query results to only assets that are related to certain other elements. -利用可能な値には、次のものが含まれます。 +See [Relations](https://docs.craftcms.com/v3/relations.html) for a full explanation of how to work with this parameter. ::: code ```twig -{# Fetch assets with a title that contains "Foo" #} +{# Fetch all assets that are related to myCategory #} {% set assets = craft.assets() - .title('*Foo*') + .relatedTo(myCategory) .all() %} ``` ```php -// Fetch assets with a title that contains "Foo" +// Fetch all assets that are related to $myCategory $assets = \craft\elements\Asset::find() - ->title('*Foo*') + ->relatedTo($myCategory) ->all(); ``` ::: -### `uid` - -ソフトデリートされたアセットだけに、クエリの結果を絞り込みます。 - - - -::: code - -| 値 | 取得するアセット | -| -------------------------------------- | ------------------------ | -| `09247074'foo'` | ハンドルが `foo` のボリューム内。 | -| a `\craft\elements\db\User` object | ハンドルが `foo` のボリューム内ではない。 | +### `search` +Narrows the query results to only assets that match a search query. -::: -```twig -{# Fetch trashed assets #} -{% set assets = {twig-function} - .trashed() - .all() %} -``` -```php -// Fetch trashed assets -$assets = \craft\elements\Asset::find() - ->trashed() - ->all(); -``` -::: +See [Searching](https://docs.craftcms.com/v3/searching.html) for a full explanation of how to work with this parameter. -### `volume` ::: code - - - -::: - -| 値 | 取得するアセット | -| --- | --------------- | -| `1` | ID が 1 のボリューム内。 | - - - -アセットが属するボリュームに基づいて、クエリの結果を絞り込みます。 ```twig -{# Fetch the asset by its UID #} -{% set asset = craft.assets() - .uid('xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx') - .one() %} -``` - -```php -// Fetch the asset by its UID -$asset = \craft\elements\Asset::find() - ->uid('xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx') - ->one(); -``` -::: - - -### `volumeId` - -::: code - - - -::: - -| 値 | 取得するアセット | -| -------------------------------------------- | -------------- | -| `587390100` | 幅 100px。 | -| a [Asset](api:craft\elements\Asset) object | 少なくとも、幅 100px。 | - - +{# Get the search query from the 'q' query string param #} +{% set searchQuery = craft.app.request.getQueryParam('q') %} -ボリュームの ID ごとに、アセットが属するボリュームに基づいて、クエリの結果を絞り込みます。 -```twig -{# Fetch assets in the Foo volume #} +{# Fetch all assets that match the search query #} {% set assets = craft.assets() - .volume('foo') + .search(searchQuery) .all() %} ``` ```php -// Fetch assets in the Foo group -$assets = \craft\elements\Asset::find() - ->volume('foo') - ->all(); -``` -::: - - -### `width` - -::: code - - - - - -::: -```twig -{# Fetch assets in the volume with an ID of 1 #} -{% set assets = craft.assets() - .volumeId(1) - .all() %} -``` +// Get the search query from the 'q' query string param +$searchQuery = \Craft::$app->request->getQueryParam('q'); -```php -// Fetch categories in the volume with an ID of 1 +// Fetch all assets that match the search query $assets = \craft\elements\Asset::find() - ->volumeId(1) + ->search($searchQuery) ->all(); ``` ::: -### `with` - -利用可能な値には、次のものが含まれます。 +### `site` +Determines which site(s) the assets should be queried in. -::: code +The current site will be used by default. +Possible values include: -::: -```twig -{# Fetch XL images #} -{% set assets = craft.assets() - .kind('image') - .width('>= 1000') - .all() %} -``` +| 値 | 取得するアセット | +| ------------------------------------------------------- | ---------------------------------------------- | +| `'foo'` | from the site with a handle of `foo`. | +| `['foo', 'bar']` | from a site with a handle of `foo` or `bar`. | +| `['not', 'foo', 'bar']` | not in a site with a handle of `foo` or `bar`. | +| a [craft\models\Site](api:craft\models\Site) object | from the site represented by the object. | +| `'*'` | from any site. | -```php -// Fetch XL images -$assets = \craft\elements\Asset::find() - ->kind('image') - ->width('>= 1000') - ->all(); -``` +::: tip +If multiple sites are specified, elements that belong to multiple sites will be returned multiple times. If you only want unique elements to be returned, use [unique](#unique) in conjunction with this. ::: -### `withTransforms` - -このパラメーターがどのように機能するかの詳細については、[エレメントのEager-Loading](https://docs.craftcms.com/v3/dev/eager-loading-elements.html)を参照してください。 - - ::: code - -::: - -| Value | Fetches assets… | -| -------------------------------------- | ---------------------------------------------- | -| `'foo'` | from the site with a handle of `foo`. | -| `['foo', 'bar']` | from a site with a handle of `foo` or `bar`. | -| `['not', 'foo', 'bar']` | not in a site with a handle of `foo` or `bar`. | -| a `\craft\elements\db\Site` object | from the site represented by the object. | -| `'*'` | from any site. | - -イメージ変換インデックスを eager-loaded した状態で、マッチしたアセットをクエリが返します。 - - - -トランスフォームがすでに生成されている場合、一度に複数の変換された画像を表示する際のパフォーマンスが向上します。 ```twig -{# Fetch assets eager-loaded with the "Related" field’s relations #} +{# Fetch assets from the Foo site #} {% set assets = craft.assets() - .with(['related']) + .site('foo') .all() %} ``` ```php -// Fetch assets eager-loaded with the "Related" field’s relations +// Fetch assets from the Foo site $assets = \craft\elements\Asset::find() - ->with(['related']) + ->site('foo') ->all(); ``` ::: @@ -942,7 +758,7 @@ $assets = \craft\elements\Asset::find() ### `siteId` -::: +Determines which site(s) the assets should be queried in, per the site’s ID. @@ -952,18 +768,16 @@ The current site will be used by default. ::: code ```twig -{# Fetch assets with the 'thumbnail' and 'hiResThumbnail' transform data preloaded #} +{# Fetch assets from the site with an ID of 1 #} {% set assets = craft.assets() - .kind('image') - .withTransforms(['thumbnail', 'hiResThumbnail']) + .siteId(1) .all() %} ``` ```php -// Fetch assets with the 'thumbnail' and 'hiResThumbnail' transform data preloaded +// Fetch assets from the site with an ID of 1 $assets = \craft\elements\Asset::find() - ->kind('image') - ->withTransforms(['thumbnail', 'hiResThumbnail']) + ->siteId(1) ->all(); ``` ::: @@ -975,7 +789,7 @@ Narrows the query results based on the assets’ file sizes (in bytes). Possible values include: -| Value | Fetches assets… | +| 値 | 取得するアセット | | -------------------------------- | ----------------------------------------------- | | `1000` | with a size of 1,000 bytes (1KB). | | `'< 1000000'` | with a size of less than 1,000,000 bytes (1MB). | @@ -1008,7 +822,7 @@ Narrows the query results based on the assets’ titles. Possible values include: -| Value | Fetches assets… | +| 値 | Fetches assets… | | --------------------------- | ------------------------------------------------- | | `'Foo'` | with a title of `Foo`. | | `'Foo*'` | with a title that begins with `Foo`. | @@ -1116,13 +930,43 @@ $assets = \craft\elements\Asset::find() ::: +### `uploader` + +Narrows the query results based on the user the assets were uploaded by, per the user’s IDs. + +Possible values include: + +| 値 | Fetches assets… | +| ----------------------------------------------------------- | ----------------------------------------------- | +| `1` | uploaded by the user with an ID of 1. | +| a [craft\elements\User](api:craft\elements\User) object | uploaded by the user represented by the object. | + + + +::: code +```twig +{# Fetch assets uploaded by the user with an ID of 1 #} +{% set assets = craft.assets() + .uploader(1) + .all() %} +``` + +```php +// Fetch assets uploaded by the user with an ID of 1 +$assets = \craft\elements\Asset::find() + ->uploader(1) + ->all(); +``` +::: + + ### `volume` Narrows the query results based on the volume the assets belong to. Possible values include: -| Value | Fetches categories… | +| 値 | Fetches assets… | | ------------------------------------------ | ------------------------------------------------ | | `'foo'` | in a volume with a handle of `foo`. | | `'not foo'` | not in a volume with a handle of `foo`. | @@ -1155,7 +999,7 @@ Narrows the query results based on the volumes the assets belong to, per the vol Possible values include: -| Value | Fetches categories… | +| Value | Fetches assets… | | --------------- | ------------------------------------- | | `1` | in a volume with an ID of 1. | | `'not 1'` | not in a volume with an ID of 1. | @@ -1173,7 +1017,7 @@ Possible values include: ``` ```php -// Fetch categories in the volume with an ID of 1 +// Fetch assets in the volume with an ID of 1 $assets = \craft\elements\Asset::find() ->volumeId(1) ->all(); From 7f55d1075c4c5770a623d1d23eec24db48067de2 Mon Sep 17 00:00:00 2001 From: Brad Bell Date: Fri, 12 Jun 2020 17:32:04 -0700 Subject: [PATCH 020/245] New translations tag-queries.md (Japanese) --- ja/dev/element-queries/tag-queries.md | 481 +++++++------------------- 1 file changed, 134 insertions(+), 347 deletions(-) diff --git a/ja/dev/element-queries/tag-queries.md b/ja/dev/element-queries/tag-queries.md index e2a118dc0ea..48e8e0bd058 100644 --- a/ja/dev/element-queries/tag-queries.md +++ b/ja/dev/element-queries/tag-queries.md @@ -50,6 +50,34 @@ $myTagQuery = \craft\elements\Tag::find(); +| Param | Description | +| ----------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| [anyStatus](#anystatus) | Clears out the [status()](https://docs.craftcms.com/api/v3/craft-elements-db-elementquery.html#method-status) and [enabledForSite()](https://docs.craftcms.com/api/v3/craft-elements-db-elementquery.html#method-enabledforsite) parameters. | +| [asArray](#asarray) | Causes the query to return matching tags as arrays of data, rather than [Tag](api:craft\elements\Tag) objects. | +| [clearCachedResult](#clearcachedresult) | Clears the cached result. | +| [dateCreated](#datecreated) | Narrows the query results based on the tags’ creation dates. | +| [dateUpdated](#dateupdated) | Narrows the query results based on the tags’ last-updated dates. | +| [fixedOrder](#fixedorder) | Causes the query results to be returned in the order specified by [id](#id). | +| [group](#group) | Narrows the query results based on the tag groups the tags belong to. | +| [groupId](#groupid) | Narrows the query results based on the tag groups the tags belong to, per the groups’ IDs. | +| [id](#id) | Narrows the query results based on the tags’ IDs. | +| [ignorePlaceholders](#ignoreplaceholders) | Causes the query to return matching tags as they are stored in the database, ignoring matching placeholder elements that were set by [craft\services\Elements::setPlaceholderElement()](https://docs.craftcms.com/api/v3/craft-services-elements.html#method-setplaceholderelement). | +| [inReverse](#inreverse) | Causes the query results to be returned in reverse order. | +| [limit](#limit) | Determines the number of tags that should be returned. | +| [offset](#offset) | Determines how many tags should be skipped in the results. | +| [orderBy](#orderby) | Determines the order that the tags should be returned in. (If empty, defaults to `title ASC`.) | +| [preferSites](#prefersites) | If [unique](#unique) is set, this determines which site should be selected when querying multi-site elements. | +| [relatedTo](#relatedto) | Narrows the query results to only tags that are related to certain other elements. | +| [search](#search) | Narrows the query results to only tags that match a search query. | +| [site](#site) | Determines which site(s) the tags should be queried in. | +| [siteId](#siteid) | Determines which site(s) the tags should be queried in, per the site’s ID. | +| [title](#title) | Narrows the query results based on the tags’ titles. | +| [trashed](#trashed) | Narrows the query results to only tags that have been soft-deleted. | +| [uid](#uid) | Narrows the query results based on the tags’ UIDs. | +| [unique](#unique) | Determines whether only elements with unique IDs should be returned by the query. | +| [uri](#uri) | Narrows the query results based on the tags’ URIs. | +| [with](#with) | Causes the query to return matching tags eager-loaded with related elements. | + ### `anyStatus` [status()](https://docs.craftcms.com/api/v3/craft-elements-db-elementquery.html#method-status) および [enabledForSite()](https://docs.craftcms.com/api/v3/craft-elements-db-elementquery.html#method-enabledforsite) パラメータをクリアします。 @@ -100,19 +128,28 @@ $tags = \craft\elements\Tag::find() ::: +### `clearCachedResult` + +Clears the cached result. + + + + + + ### `dateCreated` -タグの作成日に基づいて、クエリの結果を絞り込みます。 +Narrows the query results based on the tags’ creation dates. -利用可能な値には、次のものが含まれます。 +Possible values include: -| 値 | 取得するタグ | -| ------------------------------------------------ | ------------------------------------ | -| `'>= 2018-04-01'` | 2018-04-01 以降に作成されたもの。 | -| `'< 2018-05-01'` | 2018-05-01 より前に作成されたもの。 | -| `['and', '>= 2018-04-04', '< 2018-05-01']` | 2018-04-01 から 2018-05-01 の間に作成されたもの。 | +| 値 | 取得するタグ | +| ------------------------------------------------ | ---------------------------------------------------- | +| `'>= 2018-04-01'` | that were created on or after 2018-04-01. | +| `'< 2018-05-01'` | that were created before 2018-05-01 | +| `['and', '>= 2018-04-04', '< 2018-05-01']` | that were created between 2018-04-01 and 2018-05-01. | @@ -141,17 +178,17 @@ $tags = \craft\elements\Tag::find() ### `dateUpdated` -タグの最終アップデート日に基づいて、クエリの結果を絞り込みます。 +Narrows the query results based on the tags’ last-updated dates. -利用可能な値には、次のものが含まれます。 +Possible values include: -| 値 | 取得するタグ | -| ------------------------------------------------ | ---------------------------------------- | -| `'>= 2018-04-01'` | 2018-04-01 以降にアップデートされたもの。 | -| `'< 2018-05-01'` | 2018-05-01 より前にアップデートされたもの。 | -| `['and', '>= 2018-04-04', '< 2018-05-01']` | 2018-04-01 から 2018-05-01 の間にアップデートされたもの。 | +| 値 | Fetches tags… | +| ------------------------------------------------ | ---------------------------------------------------- | +| `'>= 2018-04-01'` | that were updated on or after 2018-04-01. | +| `'< 2018-05-01'` | that were updated before 2018-05-01 | +| `['and', '>= 2018-04-04', '< 2018-05-01']` | that were updated between 2018-04-01 and 2018-05-01. | @@ -178,20 +215,13 @@ $tags = \craft\elements\Tag::find() ### `fixedOrder` -クエリの結果を [id](#id) で指定された順序で返します。 +Causes the query results to be returned in the order specified by [id](#id). -::: code - -| 値 | 取得するタグ | -| -------------------------------------- | ----------------------- | -| `oo'.09'foo'34733'foo'` | ハンドルが `foo` のグループ内。 | -| a `\craft\elements\db\User` object | ハンドルが `foo` のグループ内ではない。 | - -::: +::: code ```twig {# Fetch tags in a specific order #} {% set tags = craft.tags() @@ -212,19 +242,21 @@ $tags = \craft\elements\Tag::find() ### `group` -利用可能な値には、次のものが含まれます。 +Narrows the query results based on the tag groups the tags belong to. +Possible values include: - -::: code - -| 値 | 取得するタグ | -| --- | -------------- | -| `1` | ID が 1 のグループ内。 | +| 値 | Fetches tags… | +| ------------------------------------------------ | ----------------------------------------------- | +| `'foo'` | in a group with a handle of `foo`. | +| `'not foo'` | not in a group with a handle of `foo`. | +| `['foo', 'bar']` | in a group with a handle of `foo` or `bar`. | +| `['not', 'foo', 'bar']` | not in a group with a handle of `foo` or `bar`. | +| a [TagGroup](api:craft\models\TagGroup) object | in a group represented by the object. | -::: +::: code ```twig {# Fetch tags in the Foo group #} {% set tags = craft.tags() @@ -243,20 +275,20 @@ $tags = \craft\elements\Tag::find() ### `groupId` -利用可能な値には、次のものが含まれます。 +Narrows the query results based on the tag groups the tags belong to, per the groups’ IDs. +Possible values include: - -::: code - -| 値 | 取得するタグ | -| ---------------------------------------- | ----------- | -| `1` | ID が 1。 | -| a [Tag](api:craft\elements\Tag) object | ID が 1ではない。 | +| 値 | Fetches tags… | +| --------------- | ------------------------------------ | +| `1` | in a group with an ID of 1. | +| `'not 1'` | not in a group with an ID of 1. | +| `[1, 2]` | in a group with an ID of 1 or 2. | +| `['not', 1, 2]` | not in a group with an ID of 1 or 2. | -::: +::: code ```twig {# Fetch tags in the group with an ID of 1 #} {% set tags = craft.tags() @@ -275,9 +307,18 @@ $tags = \craft\elements\Tag::find() ### `id` -利用可能な値には、次のものが含まれます。 +Narrows the query results based on the tags’ IDs. + +Possible values include: + +| 値 | 取得するタグ | +| --------------- | ------------------------- | +| `1` | with an ID of 1. | +| `'not 1'` | not with an ID of 1. | +| `[1, 2]` | with an ID of 1 or 2. | +| `['not', 1, 2]` | not with an ID of 1 or 2. | @@ -298,17 +339,34 @@ $tag = \craft\elements\Tag::find() ::: -### `inReverse` ::: tip -特定の順序で結果を返したい場合、[fixedOrder](#fixedorder) と組み合わせることができます。 +This can be combined with [fixedOrder](#fixedorder) if you want the results to be returned in a specific order. ::: +### `ignorePlaceholders` + +Causes the query to return matching tags as they are stored in the database, ignoring matching placeholder elements that were set by [craft\services\Elements::setPlaceholderElement()](https://docs.craftcms.com/api/v3/craft-services-elements.html#method-setplaceholderelement). + + + -クエリの結果を逆順で返します。 + + + + +### `inReverse` + +Causes the query results to be returned in reverse order. + + + + + +::: code ```twig {# Fetch tags in reverse #} {% set tags = craft.tags() @@ -327,17 +385,7 @@ $tags = \craft\elements\Tag::find() ### `limit` -::: - -返されるタグの数を決定します。 - -| 値 | 取得するタグ | -| ------------------------------------------------ | ----------------------------------------------- | -| `'foo'` | ハンドルが `foo` のサイトから。 | -| `'not foo'` | オブジェクトで表されるサイトから。 | -| `['foo', 'bar']` | in a group with a handle of `foo` or `bar`. | -| `['not', 'foo', 'bar']` | not in a group with a handle of `foo` or `bar`. | -| a [TagGroup](api:craft\models\TagGroup) object | in a group represented by the object. | +Determines the number of tags that should be returned. @@ -360,20 +408,11 @@ $tags = \craft\elements\Tag::find() ### `offset` -結果からスキップされるタグの数を決定します。 - -::: code - -| 値 | 取得するタグ | -| --------------- | ------------------ | -| `32584556'Foo'` | タイトルが `Foo`。 | -| `'Foo*'` | タイトルが `Foo` ではじまる。 | -| `'*Foo'` | タイトルが `Foo` で終わる。 | -| `'*Foo*'` | タイトルが `Foo` を含む。 | +Determines how many tags should be skipped in the results. -::: +::: code ```twig {# Fetch all tags except for the first 3 #} {% set tags = craft.tags() @@ -392,22 +431,11 @@ $tags = \craft\elements\Tag::find() ### `orderBy` -::: code - - - -::: +Determines the order that the tags should be returned in. (If empty, defaults to `title ASC`.) -| 値 | 取得するタグ | -| ------------------- | ------------------ | -| `748040'foo'9'foo'` | URI が `foo`。 | -| `'foo*'` | URI が `foo` ではじまる。 | -| `'*foo'` | URI が `foo` で終わる。 | -| `'*foo*'` | URI が `foo` を含む。 | - -特定の他のエレメントと関連付けられたタグだけに、クエリの結果を絞り込みます。 +::: code ```twig {# Fetch all tags in order of date created #} {% set tags = craft.tags() @@ -424,307 +452,66 @@ $tags = \craft\elements\Tag::find() ::: +### `preferSites` -::: code - - -### `relatedTo` - -::: - - - - - - - - - - -### `search` - -検索クエリにマッチするタグだけに、クエリの結果を絞り込みます。 - - - - - -このパラメーターがどのように機能するかの詳細については、[検索](https://docs.craftcms.com/v3/searching.html)を参照してください。 -```twig -{# Fetch all tags that are related to myCategory #} -{% set tags = craft.tags() - .relatedTo(myCategory) - .all() %} -``` - -```php -// Fetch all tags that are related to $myCategory -$tags = \craft\elements\Tag::find() - ->relatedTo($myCategory) - ->all(); -``` -::: - - -### `site` - -::: - - - -タグを照会するサイトを決定します。 -```twig -{# Get the search query from the 'q' query string param #} -{% set searchQuery = craft.app.request.getQueryParam('q') %} - -{# Fetch all tags that match the search query #} -{% set tags = craft.tags() - .search(searchQuery) - .all() %} -``` - -```php -// Get the search query from the 'q' query string param -$searchQuery = \Craft::$app->request->getQueryParam('q'); - -// Fetch all tags that match the search query -$tags = \craft\elements\Tag::find() - ->search($searchQuery) - ->all(); -``` -::: - - -### `siteId` - -利用可能な値には、次のものが含まれます。 - - - -::: code -```twig -{# Fetch tags from the Foo site #} -{% set tags = craft.tags() - .site('foo') - .all() %} -``` - -```php -// Fetch tags from the Foo site -$tags = \craft\elements\Tag::find() - ->site('foo') - ->all(); -``` -::: - - -### `title` - -サイトの ID ごとに、タグを照会するサイトを決定します。 +If [unique](#unique) is set, this determines which site should be selected when querying multi-site elements. -デフォルトでは、現在のサイトが使用されます。 -```twig -{# Fetch tags from the site with an ID of 1 #} -{% set tags = craft.tags() - .siteId(1) - .all() %} -``` +For example, if element “Foo” exists in Site A and Site B, and element “Bar” exists in Site B and Site C, and this is set to `['c', 'b', 'a']`, then Foo will be returned for Site C, and Bar will be returned for Site B. -```php -// Fetch tags from the site with an ID of 1 -$tags = \craft\elements\Tag::find() - ->siteId(1) - ->all(); -``` -::: - - -### `trashed` - -::: - - - -タグのタイトルに基づいて、クエリの結果を絞り込みます。 - -利用可能な値には、次のものが含まれます。 +If this isn’t set, then preference goes to the current site. ::: code ```twig -{# Fetch tags with a title that contains "Foo" #} +{# Fetch unique tags from Site A, or Site B if they don’t exist in Site A #} {% set tags = craft.tags() - .title('*Foo*') - .all() %} -``` - -```php -// Fetch tags with a title that contains "Foo" -$tags = \craft\elements\Tag::find() - ->title('*Foo*') - ->all(); -``` -::: - - -### `uid` - -ソフトデリートされたタグだけに、クエリの結果を絞り込みます。 - - - -::: code - - - -::: -```twig -{# Fetch trashed tags #} -{% set tags = {twig-function} - .trashed() + .site('*') + .unique() + .preferSites(['a', 'b']) .all() %} ``` ```php -// Fetch trashed tags +// Fetch unique tags from Site A, or Site B if they don’t exist in Site A $tags = \craft\elements\Tag::find() - ->trashed() + ->site('*') + ->unique() + ->preferSites(['a', 'b']) ->all(); ``` ::: -### `uri` - -::: code - - - -::: - -| Value | Fetches revisions… | -| -------------------------------------- | -------------------------------------- | -| `1` | created by the user with an ID of 1. | -| a `\craft\elements\db\User` object | by the user represented by the object. | - - - -タグの URI に基づいて、クエリの結果を絞り込みます。 -```twig -{# Fetch the tag by its UID #} -{% set tag = craft.tags() - .uid('xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx') - .one() %} -``` - -```php -// Fetch the tag by its UID -$tag = \craft\elements\Tag::find() - ->uid('xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx') - ->one(); -``` -::: - - -### `with` - -::: code - - - -::: - -| Value | Fetches revisions… | -| ----- | --------------------------------- | -| `1` | for the revision with an ID of 1. | - - - -関連付けられたエレメントを eager-loaded した状態で、マッチしたタグをクエリが返します。 -```twig -{# Get the requested URI #} -{% set requestedUri = craft.app.request.getPathInfo() %} - -{# Fetch the tag with that URI #} -{% set tag = craft.tags() - .uri(requestedUri|literal) - .one() %} -``` - -```php -// Get the requested URI -$requestedUri = \Craft::$app->request->getPathInfo(); - -// Fetch the tag with that URI -$tag = \craft\elements\Tag::find() - ->uri(\craft\helpers\Db::escapeParam($requestedUri)) - ->one(); -``` -::: - - -### `revisionOf` - -::: code +### `relatedTo` +Narrows the query results to only tags that are related to certain other elements. -::: -| Value | Fetches revisions… | -| ---------------------------------------- | -------------------------------------- | -| `1` | for the tag with an ID of 1. | -| a [Tag](api:craft\elements\Tag) object | for the tag represented by the object. | +See [Relations](https://docs.craftcms.com/v3/relations.html) for a full explanation of how to work with this parameter. ::: code ```twig -{# Fetch tags eager-loaded with the "Related" field’s relations #} +{# Fetch all tags that are related to myCategory #} {% set tags = craft.tags() - .with(['related']) + .relatedTo(myCategory) .all() %} ``` ```php -// Fetch tags eager-loaded with the "Related" field’s relations +// Fetch all tags that are related to $myCategory $tags = \craft\elements\Tag::find() - ->with(['related']) + ->relatedTo($myCategory) ->all(); ``` ::: -### `revisions` - -Narrows the query results to only revision tags. - - - - - -::: code -```twig -{# Fetch a revision tag #} -{% set tags = {twig-function} - .revisions() - .id(123) - .one() %} -``` - -```php -// Fetch a revision tag -$tags = \craft\elements\Tag::find() - ->revisions() - ->id(123) - ->one(); -``` -::: - - ### `search` Narrows the query results to only tags that match a search query. @@ -768,13 +555,13 @@ The current site will be used by default. Possible values include: -| Value | Fetches tags… | -| -------------------------------------- | ---------------------------------------------- | -| `'foo'` | from the site with a handle of `foo`. | -| `['foo', 'bar']` | from a site with a handle of `foo` or `bar`. | -| `['not', 'foo', 'bar']` | not in a site with a handle of `foo` or `bar`. | -| a `\craft\elements\db\Site` object | from the site represented by the object. | -| `'*'` | from any site. | +| 値 | 取得するタグ | +| ------------------------------------------------------- | ---------------------------------------------- | +| `'foo'` | from the site with a handle of `foo`. | +| `['foo', 'bar']` | from a site with a handle of `foo` or `bar`. | +| `['not', 'foo', 'bar']` | not in a site with a handle of `foo` or `bar`. | +| a [craft\models\Site](api:craft\models\Site) object | from the site represented by the object. | +| `'*'` | from any site. | ::: tip If multiple sites are specified, elements that belong to multiple sites will be returned multiple times. If you only want unique elements to be returned, use [unique](#unique) in conjunction with this. @@ -834,7 +621,7 @@ Narrows the query results based on the tags’ titles. Possible values include: -| Value | Fetches tags… | +| 値 | 取得するタグ | | --------------------------- | ------------------------------------------------- | | `'Foo'` | with a title of `Foo`. | | `'Foo*'` | with a title that begins with `Foo`. | From c1004f9e67f7f52a920f910d7fcd8c381578ad70 Mon Sep 17 00:00:00 2001 From: Brad Bell Date: Fri, 12 Jun 2020 17:32:06 -0700 Subject: [PATCH 021/245] New translations matrix-block-queries.md (Japanese) --- .../element-queries/matrix-block-queries.md | 541 +++++++----------- 1 file changed, 202 insertions(+), 339 deletions(-) diff --git a/ja/dev/element-queries/matrix-block-queries.md b/ja/dev/element-queries/matrix-block-queries.md index cd5cbdebb1b..451df3d41bd 100644 --- a/ja/dev/element-queries/matrix-block-queries.md +++ b/ja/dev/element-queries/matrix-block-queries.md @@ -54,9 +54,70 @@ $myMatrixBlockQuery = \craft\elements\MatrixBlock::find(); +| Param | Description | +| ------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| [allowOwnerDrafts](#allowownerdrafts) | Narrows the query results based on whether the Matrix blocks’ owners are drafts. | +| [allowOwnerRevisions](#allowownerrevisions) | Narrows the query results based on whether the Matrix blocks’ owners are revisions. | +| [anyStatus](#anystatus) | Clears out the [status](#status) and [enabledForSite()](https://docs.craftcms.com/api/v3/craft-elements-db-elementquery.html#method-enabledforsite) parameters. | +| [asArray](#asarray) | Causes the query to return matching Matrix blocks as arrays of data, rather than [MatrixBlock](api:craft\elements\MatrixBlock) objects. | +| [clearCachedResult](#clearcachedresult) | Clears the cached result. | +| [dateCreated](#datecreated) | Narrows the query results based on the Matrix blocks’ creation dates. | +| [dateUpdated](#dateupdated) | Narrows the query results based on the Matrix blocks’ last-updated dates. | +| [field](#field) | Narrows the query results based on the field the Matrix blocks belong to. | +| [fieldId](#fieldid) | Narrows the query results based on the field the Matrix blocks belong to, per the fields’ IDs. | +| [fixedOrder](#fixedorder) | Causes the query results to be returned in the order specified by [id](#id). | +| [id](#id) | Narrows the query results based on the Matrix blocks’ IDs. | +| [ignorePlaceholders](#ignoreplaceholders) | Causes the query to return matching Matrix blocks as they are stored in the database, ignoring matching placeholder elements that were set by [craft\services\Elements::setPlaceholderElement()](https://docs.craftcms.com/api/v3/craft-services-elements.html#method-setplaceholderelement). | +| [inReverse](#inreverse) | Causes the query results to be returned in reverse order. | +| [limit](#limit) | Determines the number of Matrix blocks that should be returned. | +| [offset](#offset) | Determines how many Matrix blocks should be skipped in the results. | +| [orderBy](#orderby) | Determines the order that the Matrix blocks should be returned in. (If empty, defaults to `sortOrder ASC`.) | +| [owner](#owner) | Sets the [ownerId](#ownerid) and [siteId](#siteid) parameters based on a given element. | +| [ownerId](#ownerid) | Narrows the query results based on the owner element of the Matrix blocks, per the owners’ IDs. | +| [preferSites](#prefersites) | If [unique](#unique) is set, this determines which site should be selected when querying multi-site elements. | +| [relatedTo](#relatedto) | Narrows the query results to only Matrix blocks that are related to certain other elements. | +| [search](#search) | Narrows the query results to only Matrix blocks that match a search query. | +| [site](#site) | Determines which site(s) the Matrix blocks should be queried in. | +| [siteId](#siteid) | Determines which site(s) the Matrix blocks should be queried in, per the site’s ID. | +| [status](#status) | Narrows the query results based on the Matrix blocks’ statuses. | +| [trashed](#trashed) | Narrows the query results to only Matrix blocks that have been soft-deleted. | +| [type](#type) | Narrows the query results based on the Matrix blocks’ block types. | +| [typeId](#typeid) | Narrows the query results based on the Matrix blocks’ block types, per the types’ IDs. | +| [uid](#uid) | Narrows the query results based on the Matrix blocks’ UIDs. | +| [unique](#unique) | Determines whether only elements with unique IDs should be returned by the query. | +| [with](#with) | Causes the query to return matching Matrix blocks eager-loaded with related elements. | + +### `allowOwnerDrafts` + +Narrows the query results based on whether the Matrix blocks’ owners are drafts. + +Possible values include: + +| 値 | 取得する行列ブロック | +| ------- | ------------------------------- | +| `true` | which can belong to a draft. | +| `false` | which cannot belong to a draft. | + + + + +### `allowOwnerRevisions` + +Narrows the query results based on whether the Matrix blocks’ owners are revisions. + +Possible values include: + +| 値 | Fetches Matrix blocks… | +| ------- | ---------------------------------- | +| `true` | which can belong to a revision. | +| `false` | which cannot belong to a revision. | + + + + ### `anyStatus` -[status](#status) および [enabledForSite()](https://docs.craftcms.com/api/v3/craft-elements-db-elementquery.html#method-enabledforsite) パラメータをクリアします。 +Clears out the [status](#status) and [enabledForSite()](https://docs.craftcms.com/api/v3/craft-elements-db-elementquery.html#method-enabledforsite) parameters. @@ -81,7 +142,7 @@ $MatrixBlocks = \craft\elements\MatrixBlock::find() ### `asArray` -[MatrixBlock](api:craft\elements\MatrixBlock) オブジェクトではなく、データの配列として、マッチした行列ブロックをクエリが返します。 +Causes the query to return matching Matrix blocks as arrays of data, rather than [MatrixBlock](api:craft\elements\MatrixBlock) objects. @@ -104,19 +165,28 @@ $MatrixBlocks = \craft\elements\MatrixBlock::find() ::: +### `clearCachedResult` + +Clears the cached result. + + + + + + ### `dateCreated` -行列ブロックの作成日に基づいて、クエリの結果を絞り込みます。 +Narrows the query results based on the Matrix blocks’ creation dates. -利用可能な値には、次のものが含まれます。 +Possible values include: -| 値 | 取得する行列ブロック | -| ------------------------------------------------ | ------------------------------------ | -| `'>= 2018-04-01'` | 2018-04-01 以降に作成されたもの。 | -| `'< 2018-05-01'` | 2018-05-01 より前に作成されたもの。 | -| `['and', '>= 2018-04-04', '< 2018-05-01']` | 2018-04-01 から 2018-05-01 の間に作成されたもの。 | +| 値 | Fetches Matrix blocks… | +| ------------------------------------------------ | ---------------------------------------------------- | +| `'>= 2018-04-01'` | that were created on or after 2018-04-01. | +| `'< 2018-05-01'` | that were created before 2018-05-01 | +| `['and', '>= 2018-04-04', '< 2018-05-01']` | that were created between 2018-04-01 and 2018-05-01. | @@ -145,17 +215,17 @@ $MatrixBlocks = \craft\elements\MatrixBlock::find() ### `dateUpdated` -行列ブロックの最終アップデート日に基づいて、クエリの結果を絞り込みます。 +Narrows the query results based on the Matrix blocks’ last-updated dates. -利用可能な値には、次のものが含まれます。 +Possible values include: -| 値 | 取得する行列ブロック | -| ------------------------------------------------ | ---------------------------------------- | -| `'>= 2018-04-01'` | 2018-04-01 以降にアップデートされたもの。 | -| `'< 2018-05-01'` | 2018-05-01 より前にアップデートされたもの。 | -| `['and', '>= 2018-04-04', '< 2018-05-01']` | 2018-04-01 から 2018-05-01 の間にアップデートされたもの。 | +| 値 | Fetches Matrix blocks… | +| ------------------------------------------------ | ---------------------------------------------------- | +| `'>= 2018-04-01'` | that were updated on or after 2018-04-01. | +| `'< 2018-05-01'` | that were updated before 2018-05-01 | +| `['and', '>= 2018-04-04', '< 2018-05-01']` | that were updated between 2018-04-01 and 2018-05-01. | @@ -180,18 +250,51 @@ $MatrixBlocks = \craft\elements\MatrixBlock::find() ::: -### `fieldId` +### `field` -フィールドの ID ごとに、行列ブロックが属するフィールドに基づいて、クエリの結果を絞り込みます。 +Narrows the query results based on the field the Matrix blocks belong to. +Possible values include: +| 値 | Fetches Matrix blocks… | +| ----------------------------------------------------------- | ----------------------------------------------- | +| `'foo'` | in a field with a handle of `foo`. | +| `'not foo'` | not in a field with a handle of `foo`. | +| `['foo', 'bar']` | in a field with a handle of `foo` or `bar`. | +| `['not', 'foo', 'bar']` | not in a field with a handle of `foo` or `bar`. | +| a [craft\fields\Matrix](api:craft\fields\Matrix) object | in a field represented by the object. | -利用可能な値には、次のものが含まれます。 -| 値 | 取得する行列ブロック | -| -------------------------------------- | ------------------- | -| `1` | ID が 1 のフィールド内。 | -| a `\craft\elements\db\User` object | ID が 1 のフィールド内ではない。 | + +::: code +```twig +{# Fetch Matrix blocks in the Foo field #} +{% set MatrixBlocks = craft.matrixBlocks() + .field('foo') + .all() %} +``` + +```php +// Fetch Matrix blocks in the Foo field +$MatrixBlocks = \craft\elements\MatrixBlock::find() + ->field('foo') + ->all(); +``` +::: + + +### `fieldId` + +Narrows the query results based on the field the Matrix blocks belong to, per the fields’ IDs. + +Possible values include: + +| 値 | Fetches Matrix blocks… | +| --------------- | ------------------------------------ | +| `1` | in a field with an ID of 1. | +| `'not 1'` | not in a field with an ID of 1. | +| `[1, 2]` | in a field with an ID of 1 or 2. | +| `['not', 1, 2]` | not in a field with an ID of 1 or 2. | @@ -214,19 +317,13 @@ $MatrixBlocks = \craft\elements\MatrixBlock::find() ### `fixedOrder` -クエリの結果を [id](#id) で指定された順序で返します。 - +Causes the query results to be returned in the order specified by [id](#id). -::: code - -| 値 | 取得する行列ブロック | -| --- | ---------- | -| `1` | ID が 1。 | -::: +::: code ```twig {# Fetch Matrix blocks in a specific order #} {% set MatrixBlocks = craft.matrixBlocks() @@ -247,20 +344,22 @@ $MatrixBlocks = \craft\elements\MatrixBlock::find() ### `id` -利用可能な値には、次のものが含まれます。 +Narrows the query results based on the Matrix blocks’ IDs. -::: code +Possible values include: -| 値 | 取得する行列ブロック | -| -------------------------------------------------------- | ----------------------------- | -| `1` | ID が 1 のエレメントによって作成されたもの。 | -| a [MatrixBlock](api:craft\elements\MatrixBlock) object | ID が 1 のエレメントによって作成されたものではない。 | +| 値 | 取得する行列ブロック | +| --------------- | ------------------------- | +| `1` | with an ID of 1. | +| `'not 1'` | not with an ID of 1. | +| `[1, 2]` | with an ID of 1 or 2. | +| `['not', 1, 2]` | not with an ID of 1 or 2. | -::: +::: code ```twig {# Fetch the Matrix block by its ID #} {% set MatrixBlock = craft.matrixBlocks() @@ -277,9 +376,28 @@ $MatrixBlock = \craft\elements\MatrixBlock::find() ::: + +::: tip +This can be combined with [fixedOrder](#fixedorder) if you want the results to be returned in a specific order. +::: + + +### `ignorePlaceholders` + +Causes the query to return matching Matrix blocks as they are stored in the database, ignoring matching placeholder elements that were set by [craft\services\Elements::setPlaceholderElement()](https://docs.craftcms.com/api/v3/craft-services-elements.html#method-setplaceholderelement). + + + + + + + + + + ### `inReverse` -クエリの結果を逆順で返します。 +Causes the query results to be returned in reverse order. @@ -304,20 +422,11 @@ $MatrixBlocks = \craft\elements\MatrixBlock::find() ### `limit` -返される行列ブロックの数を決定します。 +Determines the number of Matrix blocks that should be returned. -::: code -| 値 | 取得される行列ブロック | -| ------------------- | ------------------------------------ | -| `oo'.29678489'foo'` | ハンドルが `foo` のサイトから。 | -| `'not 1'` | オブジェクトで表されるサイトから。 | -| `[1, 2]` | in a field with an ID of 1 or 2. | -| `['not', 1, 2]` | not in a field with an ID of 1 or 2. | - - -::: +::: code ```twig {# Fetch up to 10 Matrix blocks #} {% set MatrixBlocks = craft.matrixBlocks() @@ -336,13 +445,11 @@ $MatrixBlocks = \craft\elements\MatrixBlock::find() ### `offset` -::: code - - +Determines how many Matrix blocks should be skipped in the results. -::: +::: code ```twig {# Fetch all Matrix blocks except for the first 3 #} {% set MatrixBlocks = craft.matrixBlocks() @@ -361,22 +468,11 @@ $MatrixBlocks = \craft\elements\MatrixBlock::find() ### `orderBy` -::: code - +Determines the order that the Matrix blocks should be returned in. (If empty, defaults to `sortOrder ASC`.) -::: -| 値 | 取得する行列ブロック | -| --------------- | ------------------------- | -| `1` | 有効になっているもの。 | -| `'disabled'` | 無効になっているもの。 | -| `[1, 2]` | with an ID of 1 or 2. | -| `['not', 1, 2]` | not with an ID of 1 or 2. | - - - -指定されたエレメントに基づいて、[ownerId](#ownerid) および [siteId](#siteid) パラメータをセットします。 +::: code ```twig {# Fetch all Matrix blocks in order of date created #} {% set MatrixBlocks = craft.matrixBlocks() @@ -393,28 +489,9 @@ $MatrixBlocks = \craft\elements\MatrixBlock::find() ::: - -::: - - ### `owner` -オーナーの ID ごとに、行列ブロックのオーナーエレメントに基づいて、クエリの結果を絞り込みます。 - - - - - - - - - - -### `ownerId` - -利用可能な値には、次のものが含まれます。 - - +Sets the [ownerId](#ownerid) and [siteId](#siteid) parameters based on a given element. @@ -435,13 +512,22 @@ $MatrixBlocks = \craft\elements\MatrixBlock::find() ::: -### `relatedTo` +### `ownerId` + +Narrows the query results based on the owner element of the Matrix blocks, per the owners’ IDs. + +Possible values include: -特定の他のエレメントと関連付けられた行列ブロックだけに、クエリの結果を絞り込みます。 +| 値 | Fetches Matrix blocks… | +| --------------- | ------------------------------------------------ | +| `1` | created for an element with an ID of 1. | +| `'not 1'` | not created for an element with an ID of 1. | +| `[1, 2]` | created for an element with an ID of 1 or 2. | +| `['not', 1, 2]` | not created for an element with an ID of 1 or 2. | -このパラメーターがどのように機能するかの詳細については、[リレーション](https://docs.craftcms.com/v3/relations.html)を参照してください。 +::: code ```twig {# Fetch Matrix blocks created for an element with an ID of 1 #} {% set MatrixBlocks = craft.matrixBlocks() @@ -458,284 +544,61 @@ $MatrixBlocks = \craft\elements\MatrixBlock::find() ::: -### `search` - -::: - - - -検索クエリにマッチする行列ブロックだけに、クエリの結果を絞り込みます。 -```twig -{# Fetch all Matrix blocks that are related to myCategory #} -{% set MatrixBlocks = craft.matrixBlocks() - .relatedTo(myCategory) - .all() %} -``` - -```php -// Fetch all Matrix blocks that are related to $myCategory -$MatrixBlocks = \craft\elements\MatrixBlock::find() - ->relatedTo($myCategory) - ->all(); -``` -::: - - -### `site` - -::: code - - - -::: -```twig -{# Get the search query from the 'q' query string param #} -{% set searchQuery = craft.app.request.getQueryParam('q') %} - -{# Fetch all Matrix blocks that match the search query #} -{% set MatrixBlocks = craft.matrixBlocks() - .search(searchQuery) - .all() %} -``` - -```php -// Get the search query from the 'q' query string param -$searchQuery = \Craft::$app->request->getQueryParam('q'); - -// Fetch all Matrix blocks that match the search query -$MatrixBlocks = \craft\elements\MatrixBlock::find() - ->search($searchQuery) - ->all(); -``` -::: - - -### `siteId` - -デフォルトでは、現在のサイトが使用されます。 - - - -利用可能な値には、次のものが含まれます。 -```twig -{# Fetch Matrix blocks from the Foo site #} -{% set MatrixBlocks = craft.matrixBlocks() - .site('foo') - .all() %} -``` - -```php -// Fetch Matrix blocks from the Foo site -$MatrixBlocks = \craft\elements\MatrixBlock::find() - ->site('foo') - ->all(); -``` -::: +### `preferSites` +If [unique](#unique) is set, this determines which site should be selected when querying multi-site elements. -### `status` - -::: -サイトの ID ごとに、行列ブロックを照会するサイトを決定します。 -| 値 | 取得する行列ブロック | -| ----------------------- | ------------------------------- | -| `65'foo''foo'0766'foo'` | ハンドルが `foo` のタイプ。 | -| `'not foo'` | ハンドルが `foo` のタイプではない。 | -| `['foo', 'bar']` | ハンドルが `foo` または `bar` のタイプ。 | -| `['not', 'foo', 'bar']` | ハンドルが `foo` または `bar` のタイプではない。 | +For example, if element “Foo” exists in Site A and Site B, and element “Bar” exists in Site B and Site C, and this is set to `['c', 'b', 'a']`, then Foo will be returned for Site C, and Bar will be returned for Site B. - - -デフォルトでは、現在のサイトが使用されます。 -```twig -{# Fetch Matrix blocks from the site with an ID of 1 #} -{% set MatrixBlocks = craft.matrixBlocks() - .siteId(1) - .all() %} -``` - -```php -// Fetch Matrix blocks from the site with an ID of 1 -$MatrixBlocks = \craft\elements\MatrixBlock::find() - ->siteId(1) - ->all(); -``` -::: - - -### `trashed` - -::: - - - -行列ブロックのステータスに基づいて、クエリの結果を絞り込みます。 - -利用可能な値には、次のものが含まれます。 +If this isn’t set, then preference goes to the current site. ::: code ```twig -{# Fetch disabled Matrix blocks #} +{# Fetch unique Matrix blocks from Site A, or Site B if they don’t exist in Site A #} {% set MatrixBlocks = craft.matrixBlocks() - .status('disabled') - .all() %} -``` - -```php -// Fetch disabled Matrix blocks -$MatrixBlocks = \craft\elements\MatrixBlock::find() - ->status('disabled') - ->all(); -``` -::: - - -### `type` - -ソフトデリートされた行列ブロックだけに、クエリの結果を絞り込みます。 - - - -::: code - - - -::: -```twig -{# Fetch trashed Matrix blocks #} -{% set MatrixBlocks = {twig-function} - .trashed() + .site('*') + .unique() + .preferSites(['a', 'b']) .all() %} ``` ```php -// Fetch trashed Matrix blocks +// Fetch unique Matrix blocks from Site A, or Site B if they don’t exist in Site A $MatrixBlocks = \craft\elements\MatrixBlock::find() - ->trashed() - ->all(); -``` -::: - - -### `typeId` - -利用可能な値には、次のものが含まれます。 - - - -::: code - -| 値 | 取得する行列ブロック | -| -------------------------------------- | ---------------- | -| `1` | ID が 1 のタイプ。 | -| a `\craft\elements\db\User` object | ID が 1 のタイプではない。 | - - - -::: -```twig -{# Fetch Matrix blocks with a Foo block type #} -{% set MatrixBlocks = myEntry.myMatrixField - .type('foo') - .all() %} -``` - -```php -// Fetch Matrix blocks with a Foo block type -$MatrixBlocks = $myEntry->myMatrixField - ->type('foo') - ->all(); -``` -::: - - -### `uid` - -利用可能な値には、次のものが含まれます。 - - - -::: code - -| Value | Fetches revisions… | -| ----- | --------------------------------- | -| `1` | for the revision with an ID of 1. | - - - -::: -```twig -{# Fetch Matrix blocks of the block type with an ID of 1 #} -{% set MatrixBlocks = myEntry.myMatrixField - .typeId(1) - .all() %} -``` - -```php -// Fetch Matrix blocks of the block type with an ID of 1 -$MatrixBlocks = $myEntry->myMatrixField - ->typeId(1) + ->site('*') + ->unique() + ->preferSites(['a', 'b']) ->all(); ``` ::: -### `with` - -::: code - - - -::: - -| Value | Fetches revisions… | -| -------------------------------------------------------- | ----------------------------------------------- | -| `1` | for the Matrix block with an ID of 1. | -| a [MatrixBlock](api:craft\elements\MatrixBlock) object | for the Matrix block represented by the object. | +### `relatedTo` +Narrows the query results to only Matrix blocks that are related to certain other elements. -関連付けられたエレメントを eager-loaded した状態で、マッチした行列ブロックをクエリが返します。 -```twig -{# Fetch the Matrix block by its UID #} -{% set MatrixBlock = craft.matrixBlocks() - .uid('xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx') - .one() %} -``` -```php -// Fetch the Matrix block by its UID -$MatrixBlock = \craft\elements\MatrixBlock::find() - ->uid('xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx') - ->one(); -``` -::: +See [Relations](https://docs.craftcms.com/v3/relations.html) for a full explanation of how to work with this parameter. -### `revisions` ::: code - - - - - -::: ```twig -{# Fetch Matrix blocks eager-loaded with the "Related" field’s relations #} +{# Fetch all Matrix blocks that are related to myCategory #} {% set MatrixBlocks = craft.matrixBlocks() - .with(['related']) + .relatedTo(myCategory) .all() %} ``` ```php -// Fetch Matrix blocks eager-loaded with the "Related" field’s relations +// Fetch all Matrix blocks that are related to $myCategory $MatrixBlocks = \craft\elements\MatrixBlock::find() - ->with(['related']) + ->relatedTo($myCategory) ->all(); ``` ::: @@ -784,13 +647,13 @@ The current site will be used by default. Possible values include: -| Value | Fetches Matrix blocks… | -| -------------------------------------- | ---------------------------------------------- | -| `'foo'` | from the site with a handle of `foo`. | -| `['foo', 'bar']` | from a site with a handle of `foo` or `bar`. | -| `['not', 'foo', 'bar']` | not in a site with a handle of `foo` or `bar`. | -| a `\craft\elements\db\Site` object | from the site represented by the object. | -| `'*'` | from any site. | +| Value | Fetches Matrix blocks… | +| ------------------------------------------------------- | ---------------------------------------------- | +| `'foo'` | from the site with a handle of `foo`. | +| `['foo', 'bar']` | from a site with a handle of `foo` or `bar`. | +| `['not', 'foo', 'bar']` | not in a site with a handle of `foo` or `bar`. | +| a [craft\models\Site](api:craft\models\Site) object | from the site represented by the object. | +| `'*'` | from any site. | ::: tip If multiple sites are specified, elements that belong to multiple sites will be returned multiple times. If you only want unique elements to be returned, use [unique](#unique) in conjunction with this. From ccc667caa70d61d9fc10569aebc73ea78b5013d3 Mon Sep 17 00:00:00 2001 From: Brad Bell Date: Fri, 12 Jun 2020 17:32:07 -0700 Subject: [PATCH 022/245] New translations matrix-block-queries.md (French) --- .../element-queries/matrix-block-queries.md | 331 +++++------------- 1 file changed, 95 insertions(+), 236 deletions(-) diff --git a/fr/dev/element-queries/matrix-block-queries.md b/fr/dev/element-queries/matrix-block-queries.md index 709ce881e43..a66d788b14e 100644 --- a/fr/dev/element-queries/matrix-block-queries.md +++ b/fr/dev/element-queries/matrix-block-queries.md @@ -54,6 +54,67 @@ Matrix block queries support the following parameters: +| Param | Description | +| ------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| [allowOwnerDrafts](#allowownerdrafts) | Narrows the query results based on whether the Matrix blocks’ owners are drafts. | +| [allowOwnerRevisions](#allowownerrevisions) | Narrows the query results based on whether the Matrix blocks’ owners are revisions. | +| [anyStatus](#anystatus) | Clears out the [status](#status) and [enabledForSite()](https://docs.craftcms.com/api/v3/craft-elements-db-elementquery.html#method-enabledforsite) parameters. | +| [asArray](#asarray) | Causes the query to return matching Matrix blocks as arrays of data, rather than [MatrixBlock](api:craft\elements\MatrixBlock) objects. | +| [clearCachedResult](#clearcachedresult) | Clears the cached result. | +| [dateCreated](#datecreated) | Narrows the query results based on the Matrix blocks’ creation dates. | +| [dateUpdated](#dateupdated) | Narrows the query results based on the Matrix blocks’ last-updated dates. | +| [field](#field) | Narrows the query results based on the field the Matrix blocks belong to. | +| [fieldId](#fieldid) | Narrows the query results based on the field the Matrix blocks belong to, per the fields’ IDs. | +| [fixedOrder](#fixedorder) | Causes the query results to be returned in the order specified by [id](#id). | +| [id](#id) | Narrows the query results based on the Matrix blocks’ IDs. | +| [ignorePlaceholders](#ignoreplaceholders) | Causes the query to return matching Matrix blocks as they are stored in the database, ignoring matching placeholder elements that were set by [craft\services\Elements::setPlaceholderElement()](https://docs.craftcms.com/api/v3/craft-services-elements.html#method-setplaceholderelement). | +| [inReverse](#inreverse) | Causes the query results to be returned in reverse order. | +| [limit](#limit) | Determines the number of Matrix blocks that should be returned. | +| [offset](#offset) | Determines how many Matrix blocks should be skipped in the results. | +| [orderBy](#orderby) | Determines the order that the Matrix blocks should be returned in. (If empty, defaults to `sortOrder ASC`.) | +| [owner](#owner) | Sets the [ownerId](#ownerid) and [siteId](#siteid) parameters based on a given element. | +| [ownerId](#ownerid) | Narrows the query results based on the owner element of the Matrix blocks, per the owners’ IDs. | +| [preferSites](#prefersites) | If [unique](#unique) is set, this determines which site should be selected when querying multi-site elements. | +| [relatedTo](#relatedto) | Narrows the query results to only Matrix blocks that are related to certain other elements. | +| [search](#search) | Narrows the query results to only Matrix blocks that match a search query. | +| [site](#site) | Determines which site(s) the Matrix blocks should be queried in. | +| [siteId](#siteid) | Determines which site(s) the Matrix blocks should be queried in, per the site’s ID. | +| [status](#status) | Narrows the query results based on the Matrix blocks’ statuses. | +| [trashed](#trashed) | Narrows the query results to only Matrix blocks that have been soft-deleted. | +| [type](#type) | Narrows the query results based on the Matrix blocks’ block types. | +| [typeId](#typeid) | Narrows the query results based on the Matrix blocks’ block types, per the types’ IDs. | +| [uid](#uid) | Narrows the query results based on the Matrix blocks’ UIDs. | +| [unique](#unique) | Determines whether only elements with unique IDs should be returned by the query. | +| [with](#with) | Causes the query to return matching Matrix blocks eager-loaded with related elements. | + +### `allowOwnerDrafts` + +Narrows the query results based on whether the Matrix blocks’ owners are drafts. + +Possible values include: + +| Value | Fetches Matrix blocks… | +| ------- | ------------------------------- | +| `true` | which can belong to a draft. | +| `false` | which cannot belong to a draft. | + + + + +### `allowOwnerRevisions` + +Narrows the query results based on whether the Matrix blocks’ owners are revisions. + +Possible values include: + +| Value | Fetches Matrix blocks… | +| ------- | ---------------------------------- | +| `true` | which can belong to a revision. | +| `false` | which cannot belong to a revision. | + + + + ### `anyStatus` Clears out the [status](#status) and [enabledForSite()](https://docs.craftcms.com/api/v3/craft-elements-db-elementquery.html#method-enabledforsite) parameters. @@ -104,6 +165,15 @@ $MatrixBlocks = \craft\elements\MatrixBlock::find() ::: +### `clearCachedResult` + +Clears the cached result. + + + + + + ### `dateCreated` Narrows the query results based on the Matrix blocks’ creation dates. @@ -180,128 +250,39 @@ $MatrixBlocks = \craft\elements\MatrixBlock::find() ::: -### `draftCreator` - -Narrows the query results to only drafts created by a given user. - +### `field` +Narrows the query results based on the field the Matrix blocks belong to. Possible values include: -| Value | Fetches drafts… | -| -------------------------------------- | -------------------------------------- | -| `1` | created by the user with an ID of 1. | -| a `\craft\elements\db\User` object | by the user represented by the object. | +| Value | Fetches Matrix blocks… | +| ----------------------------------------------------------- | ----------------------------------------------- | +| `'foo'` | in a field with a handle of `foo`. | +| `'not foo'` | not in a field with a handle of `foo`. | +| `['foo', 'bar']` | in a field with a handle of `foo` or `bar`. | +| `['not', 'foo', 'bar']` | not in a field with a handle of `foo` or `bar`. | +| a [craft\fields\Matrix](api:craft\fields\Matrix) object | in a field represented by the object. | ::: code ```twig -{# Fetch drafts by the current user #} +{# Fetch Matrix blocks in the Foo field #} {% set MatrixBlocks = craft.matrixBlocks() - .draftCreator(currentUser) + .field('foo') .all() %} ``` ```php -// Fetch drafts by the current user +// Fetch Matrix blocks in the Foo field $MatrixBlocks = \craft\elements\MatrixBlock::find() - ->draftCreator(Craft::$app->user->identity) + ->field('foo') ->all(); ``` ::: -### `draftId` - -Narrows the query results based on the Matrix blocks’ draft’s ID (from the `drafts` table). - - - -Possible values include: - -| Value | Fetches drafts… | -| ----- | ------------------------------ | -| `1` | for the draft with an ID of 1. | - - - -::: code -```twig -{# Fetch a draft #} -{% set MatrixBlocks = craft.matrixBlocks() - .draftId(10) - .all() %} -``` - -```php -// Fetch a draft -$MatrixBlocks = \craft\elements\MatrixBlock::find() - ->draftIf(10) - ->all(); -``` -::: - - -### `draftOf` - -Narrows the query results to only drafts of a given Matrix block. - - - -Possible values include: - -| Value | Fetches drafts… | -| -------------------------------------------------------- | ----------------------------------------------- | -| `1` | for the Matrix block with an ID of 1. | -| a [MatrixBlock](api:craft\elements\MatrixBlock) object | for the Matrix block represented by the object. | - - - -::: code -```twig -{# Fetch drafts of the Matrix block #} -{% set MatrixBlocks = craft.matrixBlocks() - .draftOf(myBlock) - .all() %} -``` - -```php -// Fetch drafts of the Matrix block -$MatrixBlocks = \craft\elements\MatrixBlock::find() - ->draftOf($myBlock) - ->all(); -``` -::: - - -### `drafts` - -Narrows the query results to only drafts Matrix blocks. - - - - - -::: code -```twig -{# Fetch a draft Matrix block #} -{% set MatrixBlocks = {twig-function} - .drafts() - .id(123) - .one() %} -``` - -```php -// Fetch a draft Matrix block -$MatrixBlocks = \craft\elements\MatrixBlock::find() - ->drafts() - ->id(123) - ->one(); -``` -::: - - ### `fieldId` Narrows the query results based on the field the Matrix blocks belong to, per the fields’ IDs. @@ -487,7 +468,7 @@ $MatrixBlocks = \craft\elements\MatrixBlock::find() ### `orderBy` -Determines the order that the Matrix blocks should be returned in. +Determines the order that the Matrix blocks should be returned in. (If empty, defaults to `sortOrder ASC`.) @@ -623,128 +604,6 @@ $MatrixBlocks = \craft\elements\MatrixBlock::find() ::: -### `revisionCreator` - -Narrows the query results to only revisions created by a given user. - - - -Possible values include: - -| Value | Fetches revisions… | -| -------------------------------------- | -------------------------------------- | -| `1` | created by the user with an ID of 1. | -| a `\craft\elements\db\User` object | by the user represented by the object. | - - - -::: code -```twig -{# Fetch revisions by the current user #} -{% set MatrixBlocks = craft.matrixBlocks() - .revisionCreator(currentUser) - .all() %} -``` - -```php -// Fetch revisions by the current user -$MatrixBlocks = \craft\elements\MatrixBlock::find() - ->revisionCreator(Craft::$app->user->identity) - ->all(); -``` -::: - - -### `revisionId` - -Narrows the query results based on the Matrix blocks’ revision’s ID (from the `revisions` table). - - - -Possible values include: - -| Value | Fetches revisions… | -| ----- | --------------------------------- | -| `1` | for the revision with an ID of 1. | - - - -::: code -```twig -{# Fetch a revision #} -{% set MatrixBlocks = craft.matrixBlocks() - .revisionId(10) - .all() %} -``` - -```php -// Fetch a revision -$MatrixBlocks = \craft\elements\MatrixBlock::find() - ->revisionIf(10) - ->all(); -``` -::: - - -### `revisionOf` - -Narrows the query results to only revisions of a given Matrix block. - - - -Possible values include: - -| Value | Fetches revisions… | -| -------------------------------------------------------- | ----------------------------------------------- | -| `1` | for the Matrix block with an ID of 1. | -| a [MatrixBlock](api:craft\elements\MatrixBlock) object | for the Matrix block represented by the object. | - - - -::: code -```twig -{# Fetch revisions of the Matrix block #} -{% set MatrixBlocks = craft.matrixBlocks() - .revisionOf(myBlock) - .all() %} -``` - -```php -// Fetch revisions of the Matrix block -$MatrixBlocks = \craft\elements\MatrixBlock::find() - ->revisionOf($myBlock) - ->all(); -``` -::: - - -### `revisions` - -Narrows the query results to only revision Matrix blocks. - - - - - -::: code -```twig -{# Fetch a revision Matrix block #} -{% set MatrixBlocks = {twig-function} - .revisions() - .id(123) - .one() %} -``` - -```php -// Fetch a revision Matrix block -$MatrixBlocks = \craft\elements\MatrixBlock::find() - ->revisions() - ->id(123) - ->one(); -``` -::: - - ### `search` Narrows the query results to only Matrix blocks that match a search query. @@ -788,13 +647,13 @@ The current site will be used by default. Possible values include: -| Value | Fetches Matrix blocks… | -| -------------------------------------- | ---------------------------------------------- | -| `'foo'` | from the site with a handle of `foo`. | -| `['foo', 'bar']` | from a site with a handle of `foo` or `bar`. | -| `['not', 'foo', 'bar']` | not in a site with a handle of `foo` or `bar`. | -| a `\craft\elements\db\Site` object | from the site represented by the object. | -| `'*'` | from any site. | +| Value | Fetches Matrix blocks… | +| ------------------------------------------------------- | ---------------------------------------------- | +| `'foo'` | from the site with a handle of `foo`. | +| `['foo', 'bar']` | from a site with a handle of `foo` or `bar`. | +| `['not', 'foo', 'bar']` | not in a site with a handle of `foo` or `bar`. | +| a [craft\models\Site](api:craft\models\Site) object | from the site represented by the object. | +| `'*'` | from any site. | ::: tip If multiple sites are specified, elements that belong to multiple sites will be returned multiple times. If you only want unique elements to be returned, use [unique](#unique) in conjunction with this. @@ -854,10 +713,10 @@ Narrows the query results based on the Matrix blocks’ statuses. Possible values include: -| Value | Fetches Matrix blocks… | -| ----------------------- | ---------------------- | -| `'enabled'` *(default)* | that are enabled. | -| `'disabled'` | that are disabled. | +| Value | Fetches Matrix blocks… | +| ------------------------ | ---------------------- | +| `'enabled'` _(default)_ | that are enabled. | +| `'disabled'` | that are disabled. | From 1f754bc9413dbcb5e9625ccfed3efe72a1260d1b Mon Sep 17 00:00:00 2001 From: Brad Bell Date: Fri, 12 Jun 2020 17:32:09 -0700 Subject: [PATCH 023/245] New translations tag-queries.md (French) --- fr/dev/element-queries/tag-queries.md | 297 ++++---------------------- 1 file changed, 45 insertions(+), 252 deletions(-) diff --git a/fr/dev/element-queries/tag-queries.md b/fr/dev/element-queries/tag-queries.md index 5c12b2cf2ef..823999f269d 100644 --- a/fr/dev/element-queries/tag-queries.md +++ b/fr/dev/element-queries/tag-queries.md @@ -50,6 +50,34 @@ Tag queries support the following parameters: +| Param | Description | +| ----------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| [anyStatus](#anystatus) | Clears out the [status()](https://docs.craftcms.com/api/v3/craft-elements-db-elementquery.html#method-status) and [enabledForSite()](https://docs.craftcms.com/api/v3/craft-elements-db-elementquery.html#method-enabledforsite) parameters. | +| [asArray](#asarray) | Causes the query to return matching tags as arrays of data, rather than [Tag](api:craft\elements\Tag) objects. | +| [clearCachedResult](#clearcachedresult) | Clears the cached result. | +| [dateCreated](#datecreated) | Narrows the query results based on the tags’ creation dates. | +| [dateUpdated](#dateupdated) | Narrows the query results based on the tags’ last-updated dates. | +| [fixedOrder](#fixedorder) | Causes the query results to be returned in the order specified by [id](#id). | +| [group](#group) | Narrows the query results based on the tag groups the tags belong to. | +| [groupId](#groupid) | Narrows the query results based on the tag groups the tags belong to, per the groups’ IDs. | +| [id](#id) | Narrows the query results based on the tags’ IDs. | +| [ignorePlaceholders](#ignoreplaceholders) | Causes the query to return matching tags as they are stored in the database, ignoring matching placeholder elements that were set by [craft\services\Elements::setPlaceholderElement()](https://docs.craftcms.com/api/v3/craft-services-elements.html#method-setplaceholderelement). | +| [inReverse](#inreverse) | Causes the query results to be returned in reverse order. | +| [limit](#limit) | Determines the number of tags that should be returned. | +| [offset](#offset) | Determines how many tags should be skipped in the results. | +| [orderBy](#orderby) | Determines the order that the tags should be returned in. (If empty, defaults to `title ASC`.) | +| [preferSites](#prefersites) | If [unique](#unique) is set, this determines which site should be selected when querying multi-site elements. | +| [relatedTo](#relatedto) | Narrows the query results to only tags that are related to certain other elements. | +| [search](#search) | Narrows the query results to only tags that match a search query. | +| [site](#site) | Determines which site(s) the tags should be queried in. | +| [siteId](#siteid) | Determines which site(s) the tags should be queried in, per the site’s ID. | +| [title](#title) | Narrows the query results based on the tags’ titles. | +| [trashed](#trashed) | Narrows the query results to only tags that have been soft-deleted. | +| [uid](#uid) | Narrows the query results based on the tags’ UIDs. | +| [unique](#unique) | Determines whether only elements with unique IDs should be returned by the query. | +| [uri](#uri) | Narrows the query results based on the tags’ URIs. | +| [with](#with) | Causes the query to return matching tags eager-loaded with related elements. | + ### `anyStatus` Clears out the [status()](https://docs.craftcms.com/api/v3/craft-elements-db-elementquery.html#method-status) and [enabledForSite()](https://docs.craftcms.com/api/v3/craft-elements-db-elementquery.html#method-enabledforsite) parameters. @@ -100,6 +128,15 @@ $tags = \craft\elements\Tag::find() ::: +### `clearCachedResult` + +Clears the cached result. + + + + + + ### `dateCreated` Narrows the query results based on the tags’ creation dates. @@ -176,128 +213,6 @@ $tags = \craft\elements\Tag::find() ::: -### `draftCreator` - -Narrows the query results to only drafts created by a given user. - - - -Possible values include: - -| Value | Fetches drafts… | -| -------------------------------------- | -------------------------------------- | -| `1` | created by the user with an ID of 1. | -| a `\craft\elements\db\User` object | by the user represented by the object. | - - - -::: code -```twig -{# Fetch drafts by the current user #} -{% set tags = craft.tags() - .draftCreator(currentUser) - .all() %} -``` - -```php -// Fetch drafts by the current user -$tags = \craft\elements\Tag::find() - ->draftCreator(Craft::$app->user->identity) - ->all(); -``` -::: - - -### `draftId` - -Narrows the query results based on the tags’ draft’s ID (from the `drafts` table). - - - -Possible values include: - -| Value | Fetches drafts… | -| ----- | ------------------------------ | -| `1` | for the draft with an ID of 1. | - - - -::: code -```twig -{# Fetch a draft #} -{% set tags = craft.tags() - .draftId(10) - .all() %} -``` - -```php -// Fetch a draft -$tags = \craft\elements\Tag::find() - ->draftIf(10) - ->all(); -``` -::: - - -### `draftOf` - -Narrows the query results to only drafts of a given tag. - - - -Possible values include: - -| Value | Fetches drafts… | -| ---------------------------------------- | -------------------------------------- | -| `1` | for the tag with an ID of 1. | -| a [Tag](api:craft\elements\Tag) object | for the tag represented by the object. | - - - -::: code -```twig -{# Fetch drafts of the tag #} -{% set tags = craft.tags() - .draftOf(myTag) - .all() %} -``` - -```php -// Fetch drafts of the tag -$tags = \craft\elements\Tag::find() - ->draftOf($myTag) - ->all(); -``` -::: - - -### `drafts` - -Narrows the query results to only drafts tags. - - - - - -::: code -```twig -{# Fetch a draft tag #} -{% set tags = {twig-function} - .drafts() - .id(123) - .one() %} -``` - -```php -// Fetch a draft tag -$tags = \craft\elements\Tag::find() - ->drafts() - ->id(123) - ->one(); -``` -::: - - ### `fixedOrder` Causes the query results to be returned in the order specified by [id](#id). @@ -516,7 +431,7 @@ $tags = \craft\elements\Tag::find() ### `orderBy` -Determines the order that the tags should be returned in. +Determines the order that the tags should be returned in. (If empty, defaults to `title ASC`.) @@ -597,128 +512,6 @@ $tags = \craft\elements\Tag::find() ::: -### `revisionCreator` - -Narrows the query results to only revisions created by a given user. - - - -Possible values include: - -| Value | Fetches revisions… | -| -------------------------------------- | -------------------------------------- | -| `1` | created by the user with an ID of 1. | -| a `\craft\elements\db\User` object | by the user represented by the object. | - - - -::: code -```twig -{# Fetch revisions by the current user #} -{% set tags = craft.tags() - .revisionCreator(currentUser) - .all() %} -``` - -```php -// Fetch revisions by the current user -$tags = \craft\elements\Tag::find() - ->revisionCreator(Craft::$app->user->identity) - ->all(); -``` -::: - - -### `revisionId` - -Narrows the query results based on the tags’ revision’s ID (from the `revisions` table). - - - -Possible values include: - -| Value | Fetches revisions… | -| ----- | --------------------------------- | -| `1` | for the revision with an ID of 1. | - - - -::: code -```twig -{# Fetch a revision #} -{% set tags = craft.tags() - .revisionId(10) - .all() %} -``` - -```php -// Fetch a revision -$tags = \craft\elements\Tag::find() - ->revisionIf(10) - ->all(); -``` -::: - - -### `revisionOf` - -Narrows the query results to only revisions of a given tag. - - - -Possible values include: - -| Value | Fetches revisions… | -| ---------------------------------------- | -------------------------------------- | -| `1` | for the tag with an ID of 1. | -| a [Tag](api:craft\elements\Tag) object | for the tag represented by the object. | - - - -::: code -```twig -{# Fetch revisions of the tag #} -{% set tags = craft.tags() - .revisionOf(myTag) - .all() %} -``` - -```php -// Fetch revisions of the tag -$tags = \craft\elements\Tag::find() - ->revisionOf($myTag) - ->all(); -``` -::: - - -### `revisions` - -Narrows the query results to only revision tags. - - - - - -::: code -```twig -{# Fetch a revision tag #} -{% set tags = {twig-function} - .revisions() - .id(123) - .one() %} -``` - -```php -// Fetch a revision tag -$tags = \craft\elements\Tag::find() - ->revisions() - ->id(123) - ->one(); -``` -::: - - ### `search` Narrows the query results to only tags that match a search query. @@ -762,13 +555,13 @@ The current site will be used by default. Possible values include: -| Value | Fetches tags… | -| -------------------------------------- | ---------------------------------------------- | -| `'foo'` | from the site with a handle of `foo`. | -| `['foo', 'bar']` | from a site with a handle of `foo` or `bar`. | -| `['not', 'foo', 'bar']` | not in a site with a handle of `foo` or `bar`. | -| a `\craft\elements\db\Site` object | from the site represented by the object. | -| `'*'` | from any site. | +| Value | Fetches tags… | +| ------------------------------------------------------- | ---------------------------------------------- | +| `'foo'` | from the site with a handle of `foo`. | +| `['foo', 'bar']` | from a site with a handle of `foo` or `bar`. | +| `['not', 'foo', 'bar']` | not in a site with a handle of `foo` or `bar`. | +| a [craft\models\Site](api:craft\models\Site) object | from the site represented by the object. | +| `'*'` | from any site. | ::: tip If multiple sites are specified, elements that belong to multiple sites will be returned multiple times. If you only want unique elements to be returned, use [unique](#unique) in conjunction with this. From 97c17de4c75ced9bc5d114e0eaa0efe8b852fe20 Mon Sep 17 00:00:00 2001 From: Brad Bell Date: Fri, 12 Jun 2020 17:32:10 -0700 Subject: [PATCH 024/245] New translations global-set-queries.md (French) --- fr/dev/element-queries/global-set-queries.md | 294 +++---------------- 1 file changed, 42 insertions(+), 252 deletions(-) diff --git a/fr/dev/element-queries/global-set-queries.md b/fr/dev/element-queries/global-set-queries.md index 147c133d095..a64e1467878 100644 --- a/fr/dev/element-queries/global-set-queries.md +++ b/fr/dev/element-queries/global-set-queries.md @@ -51,6 +51,31 @@ Global set queries support the following parameters: +| Param | Description | +| ----------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| [anyStatus](#anystatus) | Clears out the [status()](https://docs.craftcms.com/api/v3/craft-elements-db-elementquery.html#method-status) and [enabledForSite()](https://docs.craftcms.com/api/v3/craft-elements-db-elementquery.html#method-enabledforsite) parameters. | +| [asArray](#asarray) | Causes the query to return matching global sets as arrays of data, rather than [GlobalSet](api:craft\elements\GlobalSet) objects. | +| [clearCachedResult](#clearcachedresult) | Clears the cached result. | +| [dateCreated](#datecreated) | Narrows the query results based on the global sets’ creation dates. | +| [dateUpdated](#dateupdated) | Narrows the query results based on the global sets’ last-updated dates. | +| [fixedOrder](#fixedorder) | Causes the query results to be returned in the order specified by [id](#id). | +| [handle](#handle) | Narrows the query results based on the global sets’ handles. | +| [id](#id) | Narrows the query results based on the global sets’ IDs. | +| [ignorePlaceholders](#ignoreplaceholders) | Causes the query to return matching global sets as they are stored in the database, ignoring matching placeholder elements that were set by [craft\services\Elements::setPlaceholderElement()](https://docs.craftcms.com/api/v3/craft-services-elements.html#method-setplaceholderelement). | +| [inReverse](#inreverse) | Causes the query results to be returned in reverse order. | +| [limit](#limit) | Determines the number of global sets that should be returned. | +| [offset](#offset) | Determines how many global sets should be skipped in the results. | +| [orderBy](#orderby) | Determines the order that the global sets should be returned in. (If empty, defaults to `name ASC`.) | +| [preferSites](#prefersites) | If [unique](#unique) is set, this determines which site should be selected when querying multi-site elements. | +| [relatedTo](#relatedto) | Narrows the query results to only global sets that are related to certain other elements. | +| [search](#search) | Narrows the query results to only global sets that match a search query. | +| [site](#site) | Determines which site(s) the global sets should be queried in. | +| [siteId](#siteid) | Determines which site(s) the global sets should be queried in, per the site’s ID. | +| [trashed](#trashed) | Narrows the query results to only global sets that have been soft-deleted. | +| [uid](#uid) | Narrows the query results based on the global sets’ UIDs. | +| [unique](#unique) | Determines whether only elements with unique IDs should be returned by the query. | +| [with](#with) | Causes the query to return matching global sets eager-loaded with related elements. | + ### `anyStatus` Clears out the [status()](https://docs.craftcms.com/api/v3/craft-elements-db-elementquery.html#method-status) and [enabledForSite()](https://docs.craftcms.com/api/v3/craft-elements-db-elementquery.html#method-enabledforsite) parameters. @@ -101,6 +126,15 @@ $globalSets = \craft\elements\GlobalSet::find() ::: +### `clearCachedResult` + +Clears the cached result. + + + + + + ### `dateCreated` Narrows the query results based on the global sets’ creation dates. @@ -177,128 +211,6 @@ $globalSets = \craft\elements\GlobalSet::find() ::: -### `draftCreator` - -Narrows the query results to only drafts created by a given user. - - - -Possible values include: - -| Value | Fetches drafts… | -| -------------------------------------- | -------------------------------------- | -| `1` | created by the user with an ID of 1. | -| a `\craft\elements\db\User` object | by the user represented by the object. | - - - -::: code -```twig -{# Fetch drafts by the current user #} -{% set globalSets = craft.globalSets() - .draftCreator(currentUser) - .all() %} -``` - -```php -// Fetch drafts by the current user -$globalSets = \craft\elements\GlobalSet::find() - ->draftCreator(Craft::$app->user->identity) - ->all(); -``` -::: - - -### `draftId` - -Narrows the query results based on the global sets’ draft’s ID (from the `drafts` table). - - - -Possible values include: - -| Value | Fetches drafts… | -| ----- | ------------------------------ | -| `1` | for the draft with an ID of 1. | - - - -::: code -```twig -{# Fetch a draft #} -{% set globalSets = craft.globalSets() - .draftId(10) - .all() %} -``` - -```php -// Fetch a draft -$globalSets = \craft\elements\GlobalSet::find() - ->draftIf(10) - ->all(); -``` -::: - - -### `draftOf` - -Narrows the query results to only drafts of a given global set. - - - -Possible values include: - -| Value | Fetches drafts… | -| ---------------------------------------------------- | --------------------------------------------- | -| `1` | for the global set with an ID of 1. | -| a [GlobalSet](api:craft\elements\GlobalSet) object | for the global set represented by the object. | - - - -::: code -```twig -{# Fetch drafts of the global set #} -{% set globalSets = craft.globalSets() - .draftOf(myGlobalSet) - .all() %} -``` - -```php -// Fetch drafts of the global set -$globalSets = \craft\elements\GlobalSet::find() - ->draftOf($myGlobalSet) - ->all(); -``` -::: - - -### `drafts` - -Narrows the query results to only drafts global sets. - - - - - -::: code -```twig -{# Fetch a draft global set #} -{% set globalSets = {twig-function} - .drafts() - .id(123) - .one() %} -``` - -```php -// Fetch a draft global set -$globalSets = \craft\elements\GlobalSet::find() - ->drafts() - ->id(123) - ->one(); -``` -::: - - ### `fixedOrder` Causes the query results to be returned in the order specified by [id](#id). @@ -484,7 +396,7 @@ $globalSets = \craft\elements\GlobalSet::find() ### `orderBy` -Determines the order that the global sets should be returned in. +Determines the order that the global sets should be returned in. (If empty, defaults to `name ASC`.) @@ -565,128 +477,6 @@ $globalSets = \craft\elements\GlobalSet::find() ::: -### `revisionCreator` - -Narrows the query results to only revisions created by a given user. - - - -Possible values include: - -| Value | Fetches revisions… | -| -------------------------------------- | -------------------------------------- | -| `1` | created by the user with an ID of 1. | -| a `\craft\elements\db\User` object | by the user represented by the object. | - - - -::: code -```twig -{# Fetch revisions by the current user #} -{% set globalSets = craft.globalSets() - .revisionCreator(currentUser) - .all() %} -``` - -```php -// Fetch revisions by the current user -$globalSets = \craft\elements\GlobalSet::find() - ->revisionCreator(Craft::$app->user->identity) - ->all(); -``` -::: - - -### `revisionId` - -Narrows the query results based on the global sets’ revision’s ID (from the `revisions` table). - - - -Possible values include: - -| Value | Fetches revisions… | -| ----- | --------------------------------- | -| `1` | for the revision with an ID of 1. | - - - -::: code -```twig -{# Fetch a revision #} -{% set globalSets = craft.globalSets() - .revisionId(10) - .all() %} -``` - -```php -// Fetch a revision -$globalSets = \craft\elements\GlobalSet::find() - ->revisionIf(10) - ->all(); -``` -::: - - -### `revisionOf` - -Narrows the query results to only revisions of a given global set. - - - -Possible values include: - -| Value | Fetches revisions… | -| ---------------------------------------------------- | --------------------------------------------- | -| `1` | for the global set with an ID of 1. | -| a [GlobalSet](api:craft\elements\GlobalSet) object | for the global set represented by the object. | - - - -::: code -```twig -{# Fetch revisions of the global set #} -{% set globalSets = craft.globalSets() - .revisionOf(myGlobalSet) - .all() %} -``` - -```php -// Fetch revisions of the global set -$globalSets = \craft\elements\GlobalSet::find() - ->revisionOf($myGlobalSet) - ->all(); -``` -::: - - -### `revisions` - -Narrows the query results to only revision global sets. - - - - - -::: code -```twig -{# Fetch a revision global set #} -{% set globalSets = {twig-function} - .revisions() - .id(123) - .one() %} -``` - -```php -// Fetch a revision global set -$globalSets = \craft\elements\GlobalSet::find() - ->revisions() - ->id(123) - ->one(); -``` -::: - - ### `search` Narrows the query results to only global sets that match a search query. @@ -730,13 +520,13 @@ The current site will be used by default. Possible values include: -| Value | Fetches global sets… | -| -------------------------------------- | ---------------------------------------------- | -| `'foo'` | from the site with a handle of `foo`. | -| `['foo', 'bar']` | from a site with a handle of `foo` or `bar`. | -| `['not', 'foo', 'bar']` | not in a site with a handle of `foo` or `bar`. | -| a `\craft\elements\db\Site` object | from the site represented by the object. | -| `'*'` | from any site. | +| Value | Fetches global sets… | +| ------------------------------------------------------- | ---------------------------------------------- | +| `'foo'` | from the site with a handle of `foo`. | +| `['foo', 'bar']` | from a site with a handle of `foo` or `bar`. | +| `['not', 'foo', 'bar']` | not in a site with a handle of `foo` or `bar`. | +| a [craft\models\Site](api:craft\models\Site) object | from the site represented by the object. | +| `'*'` | from any site. | ::: tip If multiple sites are specified, elements that belong to multiple sites will be returned multiple times. If you only want unique elements to be returned, use [unique](#unique) in conjunction with this. From e55a620b4281248c885300c5866101296721ed06 Mon Sep 17 00:00:00 2001 From: Brad Bell Date: Fri, 12 Jun 2020 17:32:12 -0700 Subject: [PATCH 025/245] New translations entry-queries.md (Japanese) --- ja/dev/element-queries/entry-queries.md | 565 +++++++++++++----------- 1 file changed, 317 insertions(+), 248 deletions(-) diff --git a/ja/dev/element-queries/entry-queries.md b/ja/dev/element-queries/entry-queries.md index cab7f2ced46..6b5edc2a7af 100644 --- a/ja/dev/element-queries/entry-queries.md +++ b/ja/dev/element-queries/entry-queries.md @@ -53,16 +53,76 @@ $myEntryQuery = \craft\elements\Entry::find(); +| Param | Description | +| ----------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| [after](#after) | Narrows the query results to only entries that were posted on or after a certain date. | +| [ancestorDist](#ancestordist) | Narrows the query results to only entries that are up to a certain distance away from the entry specified by [ancestorOf](#ancestorof). | +| [ancestorOf](#ancestorof) | Narrows the query results to only entries that are ancestors of another entry. | +| [anyStatus](#anystatus) | Clears out the [status](#status) and [enabledForSite](#enabledforsite) parameters. | +| [asArray](#asarray) | Causes the query to return matching entries as arrays of data, rather than [Entry](api:craft\elements\Entry) objects. | +| [authorGroup](#authorgroup) | Narrows the query results based on the user group the entries’ authors belong to. | +| [authorGroupId](#authorgroupid) | Narrows the query results based on the user group the entries’ authors belong to, per the groups’ IDs. | +| [authorId](#authorid) | Narrows the query results based on the entries’ authors. | +| [before](#before) | Narrows the query results to only entries that were posted before a certain date. | +| [clearCachedResult](#clearcachedresult) | Clears the cached result. | +| [dateCreated](#datecreated) | Narrows the query results based on the entries’ creation dates. | +| [dateUpdated](#dateupdated) | Narrows the query results based on the entries’ last-updated dates. | +| [descendantDist](#descendantdist) | Narrows the query results to only entries that are up to a certain distance away from the entry specified by [descendantOf](#descendantof). | +| [descendantOf](#descendantof) | Narrows the query results to only entries that are descendants of another entry. | +| [draftCreator](#draftcreator) | Narrows the query results to only drafts created by a given user. | +| [draftId](#draftid) | Narrows the query results based on the entries’ draft’s ID (from the `drafts` table). | +| [draftOf](#draftof) | Narrows the query results to only drafts of a given entry. | +| [drafts](#drafts) | Narrows the query results to only drafts entries. | +| [enabledForSite](#enabledforsite) | Narrows the query results based on whether the entries are enabled in the site they’re being queried in, per the [site](#site) parameter. | +| [expiryDate](#expirydate) | Narrows the query results based on the entries’ expiry dates. | +| [fixedOrder](#fixedorder) | Causes the query results to be returned in the order specified by [id](#id). | +| [hasDescendants](#hasdescendants) | Narrows the query results based on whether the entries have any descendants. | +| [id](#id) | Narrows the query results based on the entries’ IDs. | +| [ignorePlaceholders](#ignoreplaceholders) | Causes the query to return matching entries as they are stored in the database, ignoring matching placeholder elements that were set by [craft\services\Elements::setPlaceholderElement()](https://docs.craftcms.com/api/v3/craft-services-elements.html#method-setplaceholderelement). | +| [inReverse](#inreverse) | Causes the query results to be returned in reverse order. | +| [leaves](#leaves) | Narrows the query results based on whether the entries are “leaves” (entries with no descendants). | +| [level](#level) | Narrows the query results based on the entries’ level within the structure. | +| [limit](#limit) | Determines the number of entries that should be returned. | +| [nextSiblingOf](#nextsiblingof) | Narrows the query results to only the entry that comes immediately after another entry. | +| [offset](#offset) | Determines how many entries should be skipped in the results. | +| [orderBy](#orderby) | Determines the order that the entries should be returned in. (If empty, defaults to `postDate DESC`.) | +| [positionedAfter](#positionedafter) | Narrows the query results to only entries that are positioned after another entry. | +| [positionedBefore](#positionedbefore) | Narrows the query results to only entries that are positioned before another entry. | +| [postDate](#postdate) | Narrows the query results based on the entries’ post dates. | +| [preferSites](#prefersites) | If [unique](#unique) is set, this determines which site should be selected when querying multi-site elements. | +| [prevSiblingOf](#prevsiblingof) | Narrows the query results to only the entry that comes immediately before another entry. | +| [relatedTo](#relatedto) | Narrows the query results to only entries that are related to certain other elements. | +| [revisionCreator](#revisioncreator) | Narrows the query results to only revisions created by a given user. | +| [revisionId](#revisionid) | Narrows the query results based on the entries’ revision’s ID (from the `revisions` table). | +| [revisionOf](#revisionof) | Narrows the query results to only revisions of a given entry. | +| [revisions](#revisions) | Narrows the query results to only revision entries. | +| [search](#search) | Narrows the query results to only entries that match a search query. | +| [section](#section) | Narrows the query results based on the sections the entries belong to. | +| [sectionId](#sectionid) | Narrows the query results based on the sections the entries belong to, per the sections’ IDs. | +| [siblingOf](#siblingof) | Narrows the query results to only entries that are siblings of another entry. | +| [site](#site) | Determines which site(s) the entries should be queried in. | +| [siteId](#siteid) | Determines which site(s) the entries should be queried in, per the site’s ID. | +| [slug](#slug) | Narrows the query results based on the entries’ slugs. | +| [status](#status) | Narrows the query results based on the entries’ statuses. | +| [title](#title) | Narrows the query results based on the entries’ titles. | +| [trashed](#trashed) | Narrows the query results to only entries that have been soft-deleted. | +| [type](#type) | Narrows the query results based on the entries’ entry types. | +| [typeId](#typeid) | Narrows the query results based on the entries’ entry types, per the types’ IDs. | +| [uid](#uid) | Narrows the query results based on the entries’ UIDs. | +| [unique](#unique) | Determines whether only elements with unique IDs should be returned by the query. | +| [uri](#uri) | Narrows the query results based on the entries’ URIs. | +| [with](#with) | Causes the query to return matching entries eager-loaded with related elements. | + ### `after` 特定の日付以降に投稿されたエントリだけに、クエリの結果を絞り込みます。 利用可能な値には、次のものが含まれます。 -| 値 | 取得するエントリ | -| ------------------------------------------------ | -------------------------- | -| `'2018-04-01'` | 2018-04-01 以降に投稿されたもの。 | -| [DateTime](http://php.net/class.datetime) オブジェクト | オブジェクトとして表される日付以降に投稿されたもの。 | +| 値 | 取得するエントリ | +| -------------------------------------------------- | ---------------------------------------------------------- | +| `'2018-04-01'` | that were posted after 2018-04-01. | +| a [DateTime](http://php.net/class.datetime) object | that were posted after the date represented by the object. | @@ -122,10 +182,10 @@ $entries = \craft\elements\Entry::find() 利用可能な値には、次のものが含まれます。 -| 値 | 取得するエントリ | -| ------------------------------------------ | ------------------- | -| `1` | ID が 1 のエントリの上層。 | -| [Entry](api:craft\elements\Entry) オブジェクト | オブジェクトで表されるエントリの上層。 | +| 値 | 取得するエントリ | +| -------------------------------------------- | ------------------------------------------ | +| `1` | above the entry with an ID of 1. | +| a [Entry](api:craft\elements\Entry) object | above the entry represented by the object. | @@ -208,13 +268,13 @@ $entries = \craft\elements\Entry::find() 利用可能な値には、次のものが含まれます。 -| 値 | 取得するエントリ | -| ------------------------------------------------ | ------------------------------------- | -| `'foo'` | ハンドルが `foo` のグループ内の投稿者。 | -| `'not foo'` | ハンドルが `foo` のグループ内の投稿者ではない。 | -| `['foo', 'bar']` | ハンドルが `foo` または `bar` のグループ内の投稿者。 | -| `['not', 'foo', 'bar']` | ハンドルが `foo` または `bar` のグループ内の投稿者ではない。 | -| [UserGroup](api:craft\models\UserGroup) オブジェクト | オブジェクトで表されるグループ内の投稿者。 | +| 値 | 取得するエントリ | +| -------------------------------------------------- | -------------------------------------------------------------- | +| `'foo'` | with an author in a group with a handle of `foo`. | +| `'not foo'` | not with an author in a group with a handle of `foo`. | +| `['foo', 'bar']` | with an author in a group with a handle of `foo` or `bar`. | +| `['not', 'foo', 'bar']` | not with an author in a group with a handle of `foo` or `bar`. | +| a [UserGroup](api:craft\models\UserGroup) object | with an author in a group represented by the object. | @@ -241,12 +301,12 @@ $entries = \craft\elements\Entry::find() 利用可能な値には、次のものが含まれます。 -| 値 | 取得するエントリ | -| --------------- | ---------------------------- | -| `1` | ID が 1 のグループ内の投稿者。 | -| `'not 1'` | ID が 1 のグループ内の投稿者ではない。 | -| `[1, 2]` | ID が 1 または 2 のグループ内の投稿者。 | -| `['not', 1, 2]` | ID が 1 または 2 のグループ内の投稿者ではない。 | +| 値 | 取得するエントリ | +| --------------- | --------------------------------------------------- | +| `1` | with an author in a group with an ID of 1. | +| `'not 1'` | not with an author in a group with an ID of 1. | +| `[1, 2]` | with an author in a group with an ID of 1 or 2. | +| `['not', 1, 2]` | not with an author in a group with an ID of 1 or 2. | @@ -273,12 +333,12 @@ $entries = \craft\elements\Entry::find() 利用可能な値には、次のものが含まれます。 -| 値 | 取得するエントリ | -| --------------- | ---------------------- | -| `1` | ID が 1 の投稿者。 | -| `'not 1'` | ID が 1 の投稿者ではない。 | -| `[1, 2]` | ID が 1 または 2 の投稿者。 | -| `['not', 1, 2]` | ID が 1 または 2 の投稿者ではない。 | +| 値 | 取得するエントリ | +| --------------- | ---------------------------------------- | +| `1` | with an author with an ID of 1. | +| `'not 1'` | not with an author with an ID of 1. | +| `[1, 2]` | with an author with an ID of 1 or 2. | +| `['not', 1, 2]` | not with an author with an ID of 1 or 2. | @@ -305,10 +365,10 @@ $entries = \craft\elements\Entry::find() 利用可能な値には、次のものが含まれます。 -| 値 | 取得するエントリ | -| ------------------------------------------------ | ------------------------- | -| `'2018-04-01'` | 2018-04-01 より前に投稿されたもの。 | -| [DateTime](http://php.net/class.datetime) オブジェクト | オブジェクトで表される日付より前に投稿されたもの。 | +| 値 | 取得するエントリ | +| -------------------------------------------------- | ----------------------------------------------------------- | +| `'2018-04-01'` | that were posted before 2018-04-01. | +| a [DateTime](http://php.net/class.datetime) object | that were posted before the date represented by the object. | @@ -333,19 +393,28 @@ $entries = \craft\elements\Entry::find() ::: +### `clearCachedResult` + +Clears the cached result. + + + + + + ### `dateCreated` -エントリの作成日に基づいて、クエリの結果を絞り込みます。 +Narrows the query results based on the entries’ creation dates. -利用可能な値には、次のものが含まれます。 +Possible values include: -| 値 | 取得するエントリ | -| ------------------------------------------------ | ------------------------------------ | -| `'>= 2018-04-01'` | 2018-04-01 以降に作成されたもの。 | -| `'< 2018-05-01'` | 2018-05-01 より前に作成されたもの。 | -| `['and', '>= 2018-04-04', '< 2018-05-01']` | 2018-04-01 から 2018-05-01 の間に作成されたもの。 | +| 値 | 取得するエントリ | +| ------------------------------------------------ | ---------------------------------------------------- | +| `'>= 2018-04-01'` | that were created on or after 2018-04-01. | +| `'< 2018-05-01'` | that were created before 2018-05-01 | +| `['and', '>= 2018-04-04', '< 2018-05-01']` | that were created between 2018-04-01 and 2018-05-01. | @@ -374,17 +443,17 @@ $entries = \craft\elements\Entry::find() ### `dateUpdated` -エントリの最終アップデート日に基づいて、クエリの結果が絞り込まれます。 +Narrows the query results based on the entries’ last-updated dates. -利用可能な値には、次のものが含まれます。 +Possible values include: -| 値 | 取得するエントリ | -| ------------------------------------------------ | ---------------------------------------- | -| `'>= 2018-04-01'` | 2018-04-01 以降にアップデートされたもの。 | -| `'< 2018-05-01'` | 2018-05-01 より前にアップデートされたもの。 | -| `['and', '>= 2018-04-04', '< 2018-05-01']` | 2018-04-01 から 2018-05-01 の間にアップデートされたもの。 | +| 値 | 取得するエントリ | +| ------------------------------------------------ | ---------------------------------------------------- | +| `'>= 2018-04-01'` | that were updated on or after 2018-04-01. | +| `'< 2018-05-01'` | that were updated before 2018-05-01 | +| `['and', '>= 2018-04-04', '< 2018-05-01']` | that were updated between 2018-04-01 and 2018-05-01. | @@ -411,7 +480,7 @@ $entries = \craft\elements\Entry::find() ### `descendantDist` -[descendantOf](#descendantof) で指定されたエントリから特定の距離だけ離れているエントリのみに、クエリの結果を絞り込みます。 +Narrows the query results to only entries that are up to a certain distance away from the entry specified by [descendantOf](#descendantof). @@ -438,16 +507,16 @@ $entries = \craft\elements\Entry::find() ### `descendantOf` -指定したエントリの子孫であるエントリだけに、クエリの結果を絞り込みます。 +Narrows the query results to only entries that are descendants of another entry. -利用可能な値には、次のものが含まれます。 +Possible values include: -| 値 | 取得するエントリ | -| ------------------------------------------ | ------------------- | -| `1` | ID が 1 のカテゴリの下層。 | -| [Entry](api:craft\elements\Entry) オブジェクト | オブジェクトで表されるエントリの下層。 | +| 値 | Fetches entries… | +| -------------------------------------------- | ------------------------------------------ | +| `1` | below the entry with an ID of 1. | +| a [Entry](api:craft\elements\Entry) object | below the entry represented by the object. | @@ -470,22 +539,22 @@ $entries = \craft\elements\Entry::find() ::: tip -どれだけ離れた子孫エントリを対象にするか制限したい場合、[descendantDist](#descendantdist) と組み合わせることができます。 +This can be combined with [descendantDist](#descendantdist) if you want to limit how far away the descendant entries can be. ::: -### `enabledForSite` +### `draftCreator` -[site](#site) パラメータごとに、照会されているサイトでエントリが有効になっているかどうかに基づいて、クエリの結果を絞り込みます。 +Narrows the query results to only drafts created by a given user. -利用可能な値には、次のものが含まれます。 +Possible values include: -| 値 | 取得するエントリ | -| -------------------------------------- | ----------------- | -| `1` | サイト内で有効になっているもの。 | -| a `\craft\elements\db\User` object | サイト内で有効かどうかに関係なく。 | +| 値 | 取得するエントリ | +| ----------------------------------------------------------- | ---------------------------------------------- | +| `':empty:'` | created by the user with an ID of 1. | +| a [craft\elements\User](api:craft\elements\User) object | created by the user represented by the object. | @@ -506,17 +575,17 @@ $entries = \craft\elements\Entry::find() ::: -### `expiryDate` +### `draftId` -エントリの有効期限日に基づいて、クエリの結果を絞り込みます。 +Narrows the query results based on the entries’ draft’s ID (from the `drafts` table). -利用可能な値には、次のものが含まれます。 +Possible values include: -| 値 | 取得するエントリ | -| ----------------------------------- | ----------- | -| `b7c56':empty:'6.79477389':empty:'` | 有効期限日を持たない。 | +| 値 | 取得するエントリ | +| --- | ------------------------------ | +| `1` | for the draft with an ID of 1. | @@ -531,32 +600,30 @@ $entries = \craft\elements\Entry::find() ``` ```php -// Fetch entries expiring this month -$nextMonth = (new \DateTime('first day of next month'))->format(\DateTime::ATOM); - +// Fetch a draft $entries = \craft\elements\Entry::find() - ->expiryDate("< {$nextMonth}") + ->draftId(10) ->all(); ``` ::: -### `fixedOrder` +### `draftOf` -クエリの結果を [id](#id) で指定された順序で返します。 +Narrows the query results to only drafts of a given entry. -::: code +Possible values include: -| 値 | 取得するエントリ | -| -------------------------------------------- | ----------- | -| `1` | ID が 1。 | -| a [Entry](api:craft\elements\Entry) object | ID が 1ではない。 | +| 値 | Fetches drafts… | +| -------------------------------------------- | ---------------------------------------- | +| `1` | for the entry with an ID of 1. | +| a [Entry](api:craft\elements\Entry) object | for the entry represented by the object. | -::: +::: code ```twig {# Fetch entries in a specific order #} {% set entries = craft.entries() @@ -575,9 +642,9 @@ $entries = \craft\elements\Entry::find() ::: -### `hasDescendants` +### `drafts` -（これは [leaves](#leaves) の呼び出しと反対の効果を持っています。） +Narrows the query results to only drafts entries. @@ -600,18 +667,18 @@ $entries = \craft\elements\Entry::find() ::: -### `id` +### `enabledForSite` -エントリの ID に基づいて、クエリの結果を絞り込みます。 +Narrows the query results based on whether the entries are enabled in the site they’re being queried in, per the [site](#site) parameter. -利用可能な値には、次のものが含まれます。 +Possible values include: -| 値 | 取得するエントリ | -| ------------------ | ------------ | -| `true` _(default)_ | レベルが 1。 | -| `'not 1'` | レベルが 1 ではない。 | +| 値 | 取得するエントリ | +| ------------------ | -------------------------------------------- | +| `true` _(default)_ | that are enabled in the site. | +| `false` | whether they are enabled or not in the site. | @@ -632,18 +699,16 @@ $entry = \craft\elements\Entry::find() ::: -### `inReverse` +### `expiryDate` -::: tip -特定の順序で結果を返したい場合、[fixedOrder](#fixedorder) と組み合わせることができます。 -::: +Narrows the query results based on the entries’ expiry dates. -クエリの結果を逆順で返します。 +Possible values include: | 値 | 取得するエントリ | | ------------------------------------------------ | --------------------------------------------------- | -| `1` | ID が 1 のエントリの後。 | -| `':notempty:'` | オブジェクトで表されるエントリの後。 | +| `':empty:'` | that don’t have an expiry date. | +| `':notempty:'` | that have an expiry date. | | `'>= 2020-04-01'` | that will expire on or after 2020-04-01. | | `'< 2020-05-01'` | that will expire before 2020-05-01 | | `['and', '>= 2020-04-04', '< 2020-05-01']` | that will expire between 2020-04-01 and 2020-05-01. | @@ -667,15 +732,15 @@ $entries = \craft\elements\Entry::find() ::: -### `leaves` +### `fixedOrder` -エントリが「leaves」（子孫のないエントリ）であるかどうかに基づいて、クエリの結果を絞り込みます。 +Causes the query results to be returned in the order specified by [id](#id). -（これは [hasDescendants](#hasdescendants) の呼び出しと反対の効果を持っています。） +::: code ```twig {# Fetch entries that have no descendants #} {% set entries = craft.entries() @@ -692,17 +757,17 @@ $entries = \craft\elements\Entry::find() ::: -### `level` +### `hasDescendants` -::: +Narrows the query results based on whether the entries have any descendants. -構造内のエントリのレベルに基づいて、クエリの結果を絞り込みます。 +(This has the opposite effect of calling [leaves](#leaves).) -利用可能な値には、次のものが含まれます。 +::: code ```twig {# Fetch entries positioned at level 3 or above #} {% set entries = craft.entries() @@ -719,18 +784,18 @@ $entries = \craft\elements\Entry::find() ::: -### `limit` +### `id` -::: +Narrows the query results based on the entries’ IDs. -返されるエントリの数を決定します。 +Possible values include: | 値 | 取得するエントリ | | --------------- | ------------------------- | -| `1` | ID が 1 のエントリの後。 | -| `'not 1'` | オブジェクトで表されるエントリの後。 | +| `1` | with an ID of 1. | +| `'not 1'` | not with an ID of 1. | | `[1, 2]` | with an ID of 1 or 2. | | `['not', 1, 2]` | not with an ID of 1 or 2. | @@ -754,12 +819,14 @@ $entries = \craft\elements\Entry::find() -指定したエントリの直後にあるエントリだけに、クエリの結果を絞り込みます。 +::: tip +This can be combined with [fixedOrder](#fixedorder) if you want the results to be returned in a specific order. +::: -### `nextSiblingOf` +### `ignorePlaceholders` -利用可能な値には、次のものが含まれます。 +Causes the query to return matching entries as they are stored in the database, ignoring matching placeholder elements that were set by [craft\services\Elements::setPlaceholderElement()](https://docs.craftcms.com/api/v3/craft-services-elements.html#method-setplaceholderelement). @@ -770,15 +837,15 @@ $entries = \craft\elements\Entry::find() -### `offset` +### `inReverse` -::: code +Causes the query results to be returned in reverse order. -::: +::: code ```twig {# Fetch the next entry #} {% set entry = craft.entries() @@ -795,17 +862,17 @@ $entry = \craft\elements\Entry::find() ::: -### `orderBy` +### `leaves` -::: code +Narrows the query results based on whether the entries are “leaves” (entries with no descendants). -::: +(This has the opposite effect of calling [hasDescendants](#hasdescendants).) -返されるエントリの順序を決定します。 +::: code ```twig {# Fetch all entries except for the first 3 #} {% set entries = craft.entries() @@ -822,25 +889,25 @@ $entries = \craft\elements\Entry::find() ::: -### `positionedAfter` +### `level` -::: +Narrows the query results based on the entries’ level within the structure. -指定したエントリの後に位置するエントリだけに、クエリの結果を絞り込みます。 +Possible values include: -| 値 | 取得するエントリ | -| --------------- | ---------------------------------------- | -| `1` | ID が 1 のエントリの前。 | -| `'not 1'` | オブジェクトで表されるエントリの前。 | -| `'>= 3'` | with a level greater than or equal to 3. | -| `[1, 2]` | with a level of 1 or 2 | -| `['not', 1, 2]` | not with level of 1 or 2. | +| 値 | Fetches entries… | +| -------------------- | ---------------------------------------- | +| `'>= 2018-04-01'` | with a level of 1. | +| `'not 1'` | not with a level of 1. | +| `'>= 3'` | with a level greater than or equal to 3. | +| `[1, 2]` | with a level of 1 or 2 | +| `['not', 1, 2]` | not with level of 1 or 2. | -利用可能な値には、次のものが含まれます。 +::: code ```twig {# Fetch all entries in order of date created #} {% set entries = craft.entries() @@ -857,13 +924,13 @@ $entries = \craft\elements\Entry::find() ::: -### `positionedBefore` +### `limit` -::: +Determines the number of entries that should be returned. -指定したエントリの前に位置するエントリだけに、クエリの結果を絞り込みます。 +::: code ```twig {# Fetch entries after this one #} {% set entries = craft.entries() @@ -880,22 +947,22 @@ $entries = \craft\elements\Entry::find() ::: -### `postDate` +### `nextSiblingOf` -::: code +Narrows the query results to only the entry that comes immediately after another entry. -::: +Possible values include: -| 値 | 取得するエントリ | -| ------------------------------------------------------ | ----------------------- | -| `gt;= 2018-04-01'43bb36c30.80274976'>= 2018-04-01'` | 2018-04-01 以降に投稿されたもの。 | -| a [Entry](api:craft\elements\Entry) object | 2018-05-01 より前に投稿されたもの。 | +| 値 | Fetches the entry… | +| ------------------------------------------ | ------------------ | +| `1` | ID が 1 のエントリの前。 | +| [Entry](api:craft\elements\Entry) オブジェクト | オブジェクトで表されるエントリの前。 | -エントリの投稿日に基づいて、クエリの結果を絞り込みます。 +::: code ```twig {# Fetch entries before this one #} {% set entries = craft.entries() @@ -912,13 +979,13 @@ $entries = \craft\elements\Entry::find() ::: -### `prevSiblingOf` +### `offset` -::: code +Determines how many entries should be skipped in the results. -::: +::: code ```twig {# Fetch entries posted last month #} {% set start = date('first day of last month')|atom %} @@ -941,9 +1008,9 @@ $entries = \craft\elements\Entry::find() ::: -### `relatedTo` +### `orderBy` -利用可能な値には、次のものが含まれます。 +Determines the order that the entries should be returned in. (If empty, defaults to `postDate DESC`.) @@ -964,18 +1031,18 @@ $entry = \craft\elements\Entry::find() ::: -### `search` +### `positionedAfter` -特定の他のエレメントと関連付けられたエントリだけに、クエリの結果を絞り込みます。 +Narrows the query results to only entries that are positioned after another entry. -このパラメーターがどのように機能するかの詳細については、[リレーション](https://docs.craftcms.com/v3/relations.html)を参照してください。 +Possible values include: -| 値 | 取得するエントリ | -| ------------------------------------------ | ------------------ | -| `1` | ID が 1 のエントリの前。 | -| [Entry](api:craft\elements\Entry) オブジェクト | オブジェクトで表されるエントリの前。 | +| 値 | 取得するエントリ | +| -------------------------------------------- | ------------------------------------------ | +| `'foo'` | after the entry with an ID of 1. | +| a [Entry](api:craft\elements\Entry) object | after the entry represented by the object. | @@ -996,18 +1063,18 @@ $entries = \craft\elements\Entry::find() ::: -### `section` +### `positionedBefore` -検索クエリにマッチするエントリだけに、クエリの結果を絞り込みます。 +Narrows the query results to only entries that are positioned before another entry. -このパラメーターがどのように機能するかの詳細については、[検索](https://docs.craftcms.com/v3/searching.html)を参照してください。 +Possible values include: -| 値 | 取得するエントリ | -| -------------------------------------------- | ------------------------ | -| `'94.78950570'foo'` | ハンドルが `foo` のセクション内。 | -| a [Entry](api:craft\elements\Entry) object | ハンドルが `foo` のセクション内ではない。 | +| 値 | 取得するエントリ | +| -------------------------------------------- | ------------------------------------------- | +| `1` | before the entry with an ID of 1. | +| a [Entry](api:craft\elements\Entry) object | before the entry represented by the object. | @@ -1034,17 +1101,17 @@ $entries = \craft\elements\Entry::find() ::: -### `sectionId` +### `postDate` -エントリが属するセクションに基づいて、クエリの結果を絞り込みます。 +Narrows the query results based on the entries’ post dates. -利用可能な値には、次のものが含まれます。 +Possible values include: -| 値 | 取得するエントリ | -| --------- | --------------------- | -| `1` | ID が 1 のセクション内。 | -| `'not 1'` | ID が 1 のセクション内ではない。 | -| `[1, 2]` | ID が 1 または 2 のセクション内。 | +| 値 | Fetches entries… | +| ------------------------------------------------ | --------------------------------------------------- | +| `'>= 2018-04-01'` | that were posted on or after 2018-04-01. | +| `'< 2018-05-01'` | that were posted before 2018-05-01 | +| `['and', '>= 2018-04-04', '< 2018-05-01']` | that were posted between 2018-04-01 and 2018-05-01. | @@ -1065,19 +1132,19 @@ $entries = \craft\elements\Entry::find() ::: -### `siblingOf` +### `preferSites` -セクションの ID ごとに、エントリが属するセクションに基づいて、クエリの結果を絞り込みます。 +If [unique](#unique) is set, this determines which site should be selected when querying multi-site elements. -利用可能な値には、次のものが含まれます。 +For example, if element “Foo” exists in Site A and Site B, and element “Bar” exists in Site B and Site C, and this is set to `['c', 'b', 'a']`, then Foo will be returned for Site C, and Bar will be returned for Site B. -::: code +If this isn’t set, then preference goes to the current site. -::: +::: code ```twig {# Fetch entries in the section with an ID of 1 #} {% set entries = craft.entries() @@ -1094,22 +1161,22 @@ $entries = \craft\elements\Entry::find() ::: -### `site` +### `prevSiblingOf` -利用可能な値には、次のものが含まれます。 +Narrows the query results to only the entry that comes immediately before another entry. -::: code +Possible values include: -| 値 | 取得するエントリ | -| ------------------------------------------ | ------------------ | -| `1` | ID が 1 のエントリの横。 | -| [Entry](api:craft\elements\Entry) オブジェクト | オブジェクトで表されるエントリの横。 | +| 値 | Fetches the entry… | +| -------------------------------------------- | ------------------------------------------- | +| `'foo'` | before the entry with an ID of 1. | +| a [Entry](api:craft\elements\Entry) object | before the entry represented by the object. | -::: +::: code ```twig {# Fetch entries beside this one #} {% set entries = craft.entries() @@ -1126,13 +1193,13 @@ $entries = \craft\elements\Entry::find() ::: -### `siteId` +### `relatedTo` -デフォルトでは、現在のサイトが使用されます。 +Narrows the query results to only entries that are related to certain other elements. -利用可能な値には、次のものが含まれます。 +See [Relations](https://docs.craftcms.com/v3/relations.html) for a full explanation of how to work with this parameter. @@ -1153,18 +1220,18 @@ $entries = \craft\elements\Entry::find() ::: -### `slug` +### `revisionCreator` -サイトの ID ごとに、エントリを照会するサイトを決定します。 +Narrows the query results to only revisions created by a given user. -デフォルトでは、現在のサイトが使用されます。 +Possible values include: -| 値 | 取得するエントリ | -| ------------------------------------ | ------------------- | -| `3676'foo'4'foo'7'foo'` | ハンドルが `foo` のサイトから。 | -| `\craft\elements\db\Site` オブジェクト | オブジェクトで表されるサイトから。 | +| 値 | 取得するエントリ | +| ----------------------------------------------------------- | ---------------------------------------------- | +| `'foo'` | created by the user with an ID of 1. | +| a [craft\elements\User](api:craft\elements\User) object | created by the user represented by the object. | @@ -1185,17 +1252,17 @@ $entries = \craft\elements\Entry::find() ::: -### `status` +### `revisionId` -エントリのスラグに基づいて、クエリの結果を絞り込みます。 +Narrows the query results based on the entries’ revision’s ID (from the `revisions` table). -利用可能な値には、次のものが含まれます。 +Possible values include: -| 値 | 取得するエントリ | -| ----------------------- | ----------- | -| `e'foo'7.76569554'foo'` | スラグが `foo`。 | +| 値 | 取得するエントリ | +| --- | --------------------------------- | +| `1` | for the revision with an ID of 1. | @@ -1222,18 +1289,18 @@ $entry = \craft\elements\Entry::find() ::: -### `title` +### `revisionOf` -エントリのステータスに基づいて、クエリの結果を絞り込みます。 +Narrows the query results to only revisions of a given entry. -利用可能な値には、次のものが含まれます。 +Possible values include: -| 値 | 取得するエントリ | -| -------------------------------------------- | ----------------------------- | -| `1` | 公開しているもの。 | -| a [Entry](api:craft\elements\Entry) object | 保留しているもの（未来の投稿日がセットされた有効なもの）。 | +| 値 | Fetches revisions… | +| -------------------------------------------- | ---------------------------------------- | +| `1` | for the entry with an ID of 1. | +| a [Entry](api:craft\elements\Entry) object | for the entry represented by the object. | @@ -1254,15 +1321,15 @@ $entries = \craft\elements\Entry::find() ::: -### `trashed` +### `revisions` -エントリのタイトルに基づいて、クエリの結果を絞り込みます。 +Narrows the query results to only revision entries. -利用可能な値には、次のものが含まれます。 +::: code ```twig {# Fetch entries with a title that contains "Foo" #} {% set entries = craft.entries() @@ -1279,13 +1346,13 @@ $entries = \craft\elements\Entry::find() ::: -### `type` +### `search` -::: +Narrows the query results to only entries that match a search query. -ソフトデリートされたエントリだけに、クエリの結果を絞り込みます。 +See [Searching](https://docs.craftcms.com/v3/searching.html) for a full explanation of how to work with this parameter. @@ -1306,19 +1373,19 @@ $entries = \craft\elements\Entry::find() ::: -### `typeId` +### `section` -エントリの入力タイプに基づいて、クエリの結果を絞り込みます。 +Narrows the query results based on the sections the entries belong to. -利用可能な値には、次のものが含まれます。 +Possible values include: -| 値 | 取得するエントリ | -| ---------------------------------------------- | ------------------ | -| `'Foo'` | タイトルが `Foo`。 | -| `'Foo*'` | タイトルが `Foo` ではじまる。 | -| `'*Foo'` | タイトルが `Foo` で終わる。 | -| `'*Foo*'` | タイトルが `Foo` を含む。 | -| a [Section](api:craft\models\Section) object | タイトルが `Foo` を含まない。 | +| 値 | 取得するエントリ | +| ---------------------------------------------- | ------------------------------------------------- | +| `'foo'` | in a section with a handle of `foo`. | +| `'not foo'` | not in a section with a handle of `foo`. | +| `['foo', 'bar']` | in a section with a handle of `foo` or `bar`. | +| `['not', 'foo', 'bar']` | not in a section with a handle of `foo` or `bar`. | +| a [Section](api:craft\models\Section) object | in a section represented by the object. | @@ -1341,18 +1408,18 @@ $entries = \craft\elements\Entry::find() ::: -### `uid` +### `sectionId` -タイプの ID ごとに、エントリの入力タイプに基づいて、クエリの結果を絞り込みます。 +Narrows the query results based on the sections the entries belong to, per the sections’ IDs. -利用可能な値には、次のものが含まれます。 +Possible values include: -| 値 | 取得するエントリ | -| ------------------------------- | ------------------------------- | -| `365.3830'foo''foo''foo'0'foo'` | ハンドルが `foo` のタイプ。 | -| `'not foo'` | ハンドルが `foo` のタイプではない。 | -| `['foo', 'bar']` | ハンドルが `foo` または `bar` のタイプ。 | -| `['not', 'foo', 'bar']` | ハンドルが `foo` または `bar` のタイプではない。 | +| 値 | 取得するエントリ | +| --------------- | -------------------------------------- | +| `1` | in a section with an ID of 1. | +| `'not 1'` | not in a section with an ID of 1. | +| `[1, 2]` | in a section with an ID of 1 or 2. | +| `['not', 1, 2]` | not in a section with an ID of 1 or 2. | @@ -1373,22 +1440,22 @@ $entries = \craft\elements\Entry::find() ::: -### `uri` +### `siblingOf` -エントリの UID に基づいて、クエリの結果を絞り込みます。 +Narrows the query results to only entries that are siblings of another entry. -::: code +Possible values include: -| 値 | 取得するエントリ | -| -------------------------------------------- | ---------------- | -| `1` | ID が 1 のタイプ。 | -| a [Entry](api:craft\elements\Entry) object | ID が 1 のタイプではない。 | +| 値 | 取得するエントリ | +| -------------------------------------------- | ------------------------------------------- | +| `1` | beside the entry with an ID of 1. | +| a [Entry](api:craft\elements\Entry) object | beside the entry represented by the object. | -::: +::: code ```twig {# Fetch the entry by its UID #} {% set entry = craft.entries() @@ -1405,29 +1472,31 @@ $entry = \craft\elements\Entry::find() ::: -### `with` +### `site` -利用可能な値には、次のものが含まれます。 +Determines which site(s) the entries should be queried in. -::: code +The current site will be used by default. -::: +Possible values include: -| 値 | 取得するエントリ | -| -------------------------------------- | ------------------ | -| `'foo'` | URI が `foo`。 | -| `'foo*'` | URI が `foo` ではじまる。 | -| `'*foo'` | URI が `foo` で終わる。 | -| a `\craft\elements\db\Site` object | URI が `foo` を含む。 | -| `'not *foo*'` | URI が `foo` を含まない。 | +| Value | Fetches entries… | +| ------------------------------------------------------- | ---------------------------------------------- | +| `'foo'` | from the site with a handle of `foo`. | +| `['foo', 'bar']` | from a site with a handle of `foo` or `bar`. | +| `['not', 'foo', 'bar']` | not in a site with a handle of `foo` or `bar`. | +| a [craft\models\Site](api:craft\models\Site) object | from the site represented by the object. | +| `'*'` | from any site. | -関連付けられたエレメントを eager-loaded した状態で、マッチしたエントリをクエリが返します。 +::: tip +If multiple sites are specified, elements that belong to multiple sites will be returned multiple times. If you only want unique elements to be returned, use [unique](#unique) in conjunction with this. +::: -このパラメーターがどのように機能するかの詳細については、[エレメントのEager-Loading](https://docs.craftcms.com/v3/dev/eager-loading-elements.html)を参照してください。 +::: code ```twig {# Get the requested URI #} {% set requestedUri = craft.app.request.getPathInfo() %} @@ -1452,7 +1521,7 @@ $entry = \craft\elements\Entry::find() ### `siteId` -::: +Determines which site(s) the entries should be queried in, per the site’s ID. From 03cf9aa83830d5b3fdd5a61e4877d7d3e20d7098 Mon Sep 17 00:00:00 2001 From: Brad Bell Date: Fri, 12 Jun 2020 17:32:14 -0700 Subject: [PATCH 026/245] New translations entry-queries.md (French) --- fr/dev/element-queries/entry-queries.md | 107 +++++++++++++++++++----- 1 file changed, 88 insertions(+), 19 deletions(-) diff --git a/fr/dev/element-queries/entry-queries.md b/fr/dev/element-queries/entry-queries.md index 63649b9764e..61c0f983a5c 100644 --- a/fr/dev/element-queries/entry-queries.md +++ b/fr/dev/element-queries/entry-queries.md @@ -53,6 +53,66 @@ Entry queries support the following parameters: +| Param | Description | +| ----------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| [after](#after) | Narrows the query results to only entries that were posted on or after a certain date. | +| [ancestorDist](#ancestordist) | Narrows the query results to only entries that are up to a certain distance away from the entry specified by [ancestorOf](#ancestorof). | +| [ancestorOf](#ancestorof) | Narrows the query results to only entries that are ancestors of another entry. | +| [anyStatus](#anystatus) | Clears out the [status](#status) and [enabledForSite](#enabledforsite) parameters. | +| [asArray](#asarray) | Causes the query to return matching entries as arrays of data, rather than [Entry](api:craft\elements\Entry) objects. | +| [authorGroup](#authorgroup) | Narrows the query results based on the user group the entries’ authors belong to. | +| [authorGroupId](#authorgroupid) | Narrows the query results based on the user group the entries’ authors belong to, per the groups’ IDs. | +| [authorId](#authorid) | Narrows the query results based on the entries’ authors. | +| [before](#before) | Narrows the query results to only entries that were posted before a certain date. | +| [clearCachedResult](#clearcachedresult) | Clears the cached result. | +| [dateCreated](#datecreated) | Narrows the query results based on the entries’ creation dates. | +| [dateUpdated](#dateupdated) | Narrows the query results based on the entries’ last-updated dates. | +| [descendantDist](#descendantdist) | Narrows the query results to only entries that are up to a certain distance away from the entry specified by [descendantOf](#descendantof). | +| [descendantOf](#descendantof) | Narrows the query results to only entries that are descendants of another entry. | +| [draftCreator](#draftcreator) | Narrows the query results to only drafts created by a given user. | +| [draftId](#draftid) | Narrows the query results based on the entries’ draft’s ID (from the `drafts` table). | +| [draftOf](#draftof) | Narrows the query results to only drafts of a given entry. | +| [drafts](#drafts) | Narrows the query results to only drafts entries. | +| [enabledForSite](#enabledforsite) | Narrows the query results based on whether the entries are enabled in the site they’re being queried in, per the [site](#site) parameter. | +| [expiryDate](#expirydate) | Narrows the query results based on the entries’ expiry dates. | +| [fixedOrder](#fixedorder) | Causes the query results to be returned in the order specified by [id](#id). | +| [hasDescendants](#hasdescendants) | Narrows the query results based on whether the entries have any descendants. | +| [id](#id) | Narrows the query results based on the entries’ IDs. | +| [ignorePlaceholders](#ignoreplaceholders) | Causes the query to return matching entries as they are stored in the database, ignoring matching placeholder elements that were set by [craft\services\Elements::setPlaceholderElement()](https://docs.craftcms.com/api/v3/craft-services-elements.html#method-setplaceholderelement). | +| [inReverse](#inreverse) | Causes the query results to be returned in reverse order. | +| [leaves](#leaves) | Narrows the query results based on whether the entries are “leaves” (entries with no descendants). | +| [level](#level) | Narrows the query results based on the entries’ level within the structure. | +| [limit](#limit) | Determines the number of entries that should be returned. | +| [nextSiblingOf](#nextsiblingof) | Narrows the query results to only the entry that comes immediately after another entry. | +| [offset](#offset) | Determines how many entries should be skipped in the results. | +| [orderBy](#orderby) | Determines the order that the entries should be returned in. (If empty, defaults to `postDate DESC`.) | +| [positionedAfter](#positionedafter) | Narrows the query results to only entries that are positioned after another entry. | +| [positionedBefore](#positionedbefore) | Narrows the query results to only entries that are positioned before another entry. | +| [postDate](#postdate) | Narrows the query results based on the entries’ post dates. | +| [preferSites](#prefersites) | If [unique](#unique) is set, this determines which site should be selected when querying multi-site elements. | +| [prevSiblingOf](#prevsiblingof) | Narrows the query results to only the entry that comes immediately before another entry. | +| [relatedTo](#relatedto) | Narrows the query results to only entries that are related to certain other elements. | +| [revisionCreator](#revisioncreator) | Narrows the query results to only revisions created by a given user. | +| [revisionId](#revisionid) | Narrows the query results based on the entries’ revision’s ID (from the `revisions` table). | +| [revisionOf](#revisionof) | Narrows the query results to only revisions of a given entry. | +| [revisions](#revisions) | Narrows the query results to only revision entries. | +| [search](#search) | Narrows the query results to only entries that match a search query. | +| [section](#section) | Narrows the query results based on the sections the entries belong to. | +| [sectionId](#sectionid) | Narrows the query results based on the sections the entries belong to, per the sections’ IDs. | +| [siblingOf](#siblingof) | Narrows the query results to only entries that are siblings of another entry. | +| [site](#site) | Determines which site(s) the entries should be queried in. | +| [siteId](#siteid) | Determines which site(s) the entries should be queried in, per the site’s ID. | +| [slug](#slug) | Narrows the query results based on the entries’ slugs. | +| [status](#status) | Narrows the query results based on the entries’ statuses. | +| [title](#title) | Narrows the query results based on the entries’ titles. | +| [trashed](#trashed) | Narrows the query results to only entries that have been soft-deleted. | +| [type](#type) | Narrows the query results based on the entries’ entry types. | +| [typeId](#typeid) | Narrows the query results based on the entries’ entry types, per the types’ IDs. | +| [uid](#uid) | Narrows the query results based on the entries’ UIDs. | +| [unique](#unique) | Determines whether only elements with unique IDs should be returned by the query. | +| [uri](#uri) | Narrows the query results based on the entries’ URIs. | +| [with](#with) | Causes the query to return matching entries eager-loaded with related elements. | + ### `after` Narrows the query results to only entries that were posted on or after a certain date. @@ -333,6 +393,15 @@ $entries = \craft\elements\Entry::find() ::: +### `clearCachedResult` + +Clears the cached result. + + + + + + ### `dateCreated` Narrows the query results based on the entries’ creation dates. @@ -482,10 +551,10 @@ Narrows the query results to only drafts created by a given user. Possible values include: -| Value | Fetches drafts… | -| -------------------------------------- | -------------------------------------- | -| `1` | created by the user with an ID of 1. | -| a `\craft\elements\db\User` object | by the user represented by the object. | +| Value | Fetches drafts… | +| ----------------------------------------------------------- | ---------------------------------------------- | +| `1` | created by the user with an ID of 1. | +| a [craft\elements\User](api:craft\elements\User) object | created by the user represented by the object. | @@ -531,7 +600,7 @@ Possible values include: ```php // Fetch a draft $entries = \craft\elements\Entry::find() - ->draftIf(10) + ->draftId(10) ->all(); ``` ::: @@ -606,7 +675,7 @@ Possible values include: | Value | Fetches entries… | | ------------------ | -------------------------------------------- | -| `true` *(default)* | that are enabled in the site. | +| `true` _(default)_ | that are enabled in the site. | | `false` | whether they are enabled or not in the site. | @@ -939,7 +1008,7 @@ $entries = \craft\elements\Entry::find() ### `orderBy` -Determines the order that the entries should be returned in. +Determines the order that the entries should be returned in. (If empty, defaults to `postDate DESC`.) @@ -1161,10 +1230,10 @@ Narrows the query results to only revisions created by a given user. Possible values include: -| Value | Fetches revisions… | -| -------------------------------------- | -------------------------------------- | -| `1` | created by the user with an ID of 1. | -| a `\craft\elements\db\User` object | by the user represented by the object. | +| Value | Fetches revisions… | +| ----------------------------------------------------------- | ---------------------------------------------- | +| `1` | created by the user with an ID of 1. | +| a [craft\elements\User](api:craft\elements\User) object | created by the user represented by the object. | @@ -1415,13 +1484,13 @@ The current site will be used by default. Possible values include: -| Value | Fetches entries… | -| -------------------------------------- | ---------------------------------------------- | -| `'foo'` | from the site with a handle of `foo`. | -| `['foo', 'bar']` | from a site with a handle of `foo` or `bar`. | -| `['not', 'foo', 'bar']` | not in a site with a handle of `foo` or `bar`. | -| a `\craft\elements\db\Site` object | from the site represented by the object. | -| `'*'` | from any site. | +| Value | Fetches entries… | +| ------------------------------------------------------- | ---------------------------------------------- | +| `'foo'` | from the site with a handle of `foo`. | +| `['foo', 'bar']` | from a site with a handle of `foo` or `bar`. | +| `['not', 'foo', 'bar']` | not in a site with a handle of `foo` or `bar`. | +| a [craft\models\Site](api:craft\models\Site) object | from the site represented by the object. | +| `'*'` | from any site. | ::: tip If multiple sites are specified, elements that belong to multiple sites will be returned multiple times. If you only want unique elements to be returned, use [unique](#unique) in conjunction with this. @@ -1524,7 +1593,7 @@ Possible values include: | Value | Fetches entries… | | --------------------- | ----------------------------------------------------------- | -| `'live'` *(default)* | that are live. | +| `'live'` _(default)_ | that are live. | | `'pending'` | that are pending (enabled with a Post Date in the future). | | `'expired'` | that are expired (enabled with an Expiry Date in the past). | | `'disabled'` | that are disabled. | From 473124e395e1f6ef19af7554e734434e84252246 Mon Sep 17 00:00:00 2001 From: Brad Bell Date: Fri, 12 Jun 2020 17:32:16 -0700 Subject: [PATCH 027/245] New translations category-queries.md (Japanese) --- ja/dev/element-queries/category-queries.md | 688 ++++++++------------- 1 file changed, 246 insertions(+), 442 deletions(-) diff --git a/ja/dev/element-queries/category-queries.md b/ja/dev/element-queries/category-queries.md index 3af4e961ed2..1cf1be8e518 100644 --- a/ja/dev/element-queries/category-queries.md +++ b/ja/dev/element-queries/category-queries.md @@ -57,6 +57,49 @@ $myCategoryQuery = \craft\elements\Category::find(); +| Param | Description | +| ----------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| [ancestorDist](#ancestordist) | Narrows the query results to only categories that are up to a certain distance away from the category specified by [ancestorOf](#ancestorof). | +| [ancestorOf](#ancestorof) | Narrows the query results to only categories that are ancestors of another category. | +| [anyStatus](#anystatus) | Clears out the [status](#status) and [enabledForSite](#enabledforsite) parameters. | +| [asArray](#asarray) | Causes the query to return matching categories as arrays of data, rather than [Category](api:craft\elements\Category) objects. | +| [clearCachedResult](#clearcachedresult) | Clears the cached result. | +| [dateCreated](#datecreated) | Narrows the query results based on the categories’ creation dates. | +| [dateUpdated](#dateupdated) | Narrows the query results based on the categories’ last-updated dates. | +| [descendantDist](#descendantdist) | Narrows the query results to only categories that are up to a certain distance away from the category specified by [descendantOf](#descendantof). | +| [descendantOf](#descendantof) | Narrows the query results to only categories that are descendants of another category. | +| [enabledForSite](#enabledforsite) | Narrows the query results based on whether the categories are enabled in the site they’re being queried in, per the [site](#site) parameter. | +| [fixedOrder](#fixedorder) | Causes the query results to be returned in the order specified by [id](#id). | +| [group](#group) | Narrows the query results based on the category groups the categories belong to. | +| [groupId](#groupid) | Narrows the query results based on the category groups the categories belong to, per the groups’ IDs. | +| [hasDescendants](#hasdescendants) | Narrows the query results based on whether the categories have any descendants. | +| [id](#id) | Narrows the query results based on the categories’ IDs. | +| [ignorePlaceholders](#ignoreplaceholders) | Causes the query to return matching categories as they are stored in the database, ignoring matching placeholder elements that were set by [craft\services\Elements::setPlaceholderElement()](https://docs.craftcms.com/api/v3/craft-services-elements.html#method-setplaceholderelement). | +| [inReverse](#inreverse) | Causes the query results to be returned in reverse order. | +| [leaves](#leaves) | Narrows the query results based on whether the categories are “leaves” (categories with no descendants). | +| [level](#level) | Narrows the query results based on the categories’ level within the structure. | +| [limit](#limit) | Determines the number of categories that should be returned. | +| [nextSiblingOf](#nextsiblingof) | Narrows the query results to only the category that comes immediately after another category. | +| [offset](#offset) | Determines how many categories should be skipped in the results. | +| [orderBy](#orderby) | Determines the order that the categories should be returned in. (If empty, defaults to `dateCreated DESC`.) | +| [positionedAfter](#positionedafter) | Narrows the query results to only categories that are positioned after another category. | +| [positionedBefore](#positionedbefore) | Narrows the query results to only categories that are positioned before another category. | +| [preferSites](#prefersites) | If [unique](#unique) is set, this determines which site should be selected when querying multi-site elements. | +| [prevSiblingOf](#prevsiblingof) | Narrows the query results to only the category that comes immediately before another category. | +| [relatedTo](#relatedto) | Narrows the query results to only categories that are related to certain other elements. | +| [search](#search) | Narrows the query results to only categories that match a search query. | +| [siblingOf](#siblingof) | Narrows the query results to only categories that are siblings of another category. | +| [site](#site) | Determines which site(s) the categories should be queried in. | +| [siteId](#siteid) | Determines which site(s) the categories should be queried in, per the site’s ID. | +| [slug](#slug) | Narrows the query results based on the categories’ slugs. | +| [status](#status) | Narrows the query results based on the categories’ statuses. | +| [title](#title) | Narrows the query results based on the categories’ titles. | +| [trashed](#trashed) | Narrows the query results to only categories that have been soft-deleted. | +| [uid](#uid) | Narrows the query results based on the categories’ UIDs. | +| [unique](#unique) | Determines whether only elements with unique IDs should be returned by the query. | +| [uri](#uri) | Narrows the query results based on the categories’ URIs. | +| [with](#with) | Causes the query to return matching categories eager-loaded with related elements. | + ### `ancestorDist` [ancestorOf](#ancestorof) で指定されたカテゴリから特定の距離だけ離れているカテゴリのみに、クエリの結果を絞り込みます。 @@ -92,10 +135,10 @@ $categories = \craft\elements\Category::find() 利用可能な値には、次のものが含まれます。 -| 値 | 取得するカテゴリ | -| ------------------------------------------------ | ------------------- | -| `1` | ID が 1 のカテゴリの上層。 | -| [Category](api:craft\elements\Category) オブジェクト | オブジェクトで表されるカテゴリの上層。 | +| 値 | 取得するカテゴリ | +| -------------------------------------------------- | --------------------------------------------- | +| `1` | above the category with an ID of 1. | +| a [Category](api:craft\elements\Category) object | above the category represented by the object. | @@ -172,19 +215,28 @@ $categories = \craft\elements\Category::find() ::: +### `clearCachedResult` + +Clears the cached result. + + + + + + ### `dateCreated` -カテゴリの作成日に基づいて、クエリの結果を絞り込みます。 +Narrows the query results based on the categories’ creation dates. -利用可能な値には、次のものが含まれます。 +Possible values include: -| 値 | 取得するカテゴリ | -| ------------------------------------------------ | ------------------------------------ | -| `'>= 2018-04-01'` | 2018-04-01 以降に作成されたもの。 | -| `'< 2018-05-01'` | 2018-05-01 より前に作成されたもの。 | -| `['and', '>= 2018-04-04', '< 2018-05-01']` | 2018-04-01 から 2018-05-01 の間に作成されたもの。 | +| 値 | 取得するカテゴリ | +| ------------------------------------------------ | ---------------------------------------------------- | +| `'>= 2018-04-01'` | that were created on or after 2018-04-01. | +| `'< 2018-05-01'` | that were created before 2018-05-01 | +| `['and', '>= 2018-04-04', '< 2018-05-01']` | that were created between 2018-04-01 and 2018-05-01. | @@ -213,17 +265,17 @@ $categories = \craft\elements\Category::find() ### `dateUpdated` -カテゴリの最終アップデート日に基づいて、クエリの結果を絞り込みます。 +Narrows the query results based on the categories’ last-updated dates. -利用可能な値には、次のものが含まれます。 +Possible values include: -| 値 | 取得するカテゴリ | -| ------------------------------------------------ | ---------------------------------------- | -| `'>= 2018-04-01'` | 2018-04-01 以降にアップデートされたもの。 | -| `'< 2018-05-01'` | 2018-05-01 より前にアップデートされたもの。 | -| `['and', '>= 2018-04-04', '< 2018-05-01']` | 2018-04-01 から 2018-05-01 の間にアップデートされたもの。 | +| 値 | 取得するカテゴリ | +| ------------------------------------------------ | ---------------------------------------------------- | +| `'>= 2018-04-01'` | that were updated on or after 2018-04-01. | +| `'< 2018-05-01'` | that were updated before 2018-05-01 | +| `['and', '>= 2018-04-04', '< 2018-05-01']` | that were updated between 2018-04-01 and 2018-05-01. | @@ -250,7 +302,7 @@ $categories = \craft\elements\Category::find() ### `descendantDist` -[descendantOf](#descendantof) で指定されたカテゴリから特定の距離だけ離れているカテゴリのみに、クエリの結果を絞り込みます。 +Narrows the query results to only categories that are up to a certain distance away from the category specified by [descendantOf](#descendantof). @@ -277,16 +329,16 @@ $categories = \craft\elements\Category::find() ### `descendantOf` -指定したカテゴリの子孫であるカテゴリだけに、クエリの結果を絞り込みます。 +Narrows the query results to only categories that are descendants of another category. -利用可能な値には、次のものが含まれます。 +Possible values include: -| 値 | 取得するカテゴリ | -| ------------------------------------------------ | ------------------- | -| `1` | ID が 1 のカテゴリの下層。 | -| [Category](api:craft\elements\Category) オブジェクト | オブジェクトで表されるカテゴリの下層。 | +| 値 | Fetches categories… | +| -------------------------------------------------- | --------------------------------------------- | +| `1` | below the category with an ID of 1. | +| a [Category](api:craft\elements\Category) object | below the category represented by the object. | @@ -309,22 +361,22 @@ $categories = \craft\elements\Category::find() ::: tip -どれだけ離れた子孫カテゴリを対象にするか制限したい場合、[descendantDist](#descendantdist) と組み合わせることができます。 +This can be combined with [descendantDist](#descendantdist) if you want to limit how far away the descendant categories can be. ::: ### `enabledForSite` -[site](#site) パラメータごとに、照会されているサイトでカテゴリが有効になっているかどうかに基づいて、クエリの結果を絞り込みます。 +Narrows the query results based on whether the categories are enabled in the site they’re being queried in, per the [site](#site) parameter. -利用可能な値には、次のものが含まれます。 +Possible values include: -| 値 | 取得するカテゴリ | -| -------------------------------------- | ----------------- | -| `1` | サイト内で有効になっているもの。 | -| a `\craft\elements\db\User` object | サイト内で有効かどうかに関係なく。 | +| 値 | Fetches categories… | +| ------------------ | -------------------------------------------- | +| `true` _(default)_ | that are enabled in the site. | +| `false` | whether they are enabled or not in the site. | @@ -347,19 +399,13 @@ $categories = \craft\elements\Category::find() ### `fixedOrder` -クエリの結果を [id](#id) で指定された順序で返します。 +Causes the query results to be returned in the order specified by [id](#id). -::: code - -| 値 | 取得するカテゴリ | -| ----------------------- | ------------------- | -| `643.240068'foo'4'foo'` | ハンドルが `foo` のグループ内。 | - -::: +::: code ```twig {# Fetch categories in a specific order #} {% set categories = craft.categories() @@ -380,20 +426,21 @@ $categories = \craft\elements\Category::find() ### `group` -利用可能な値には、次のものが含まれます。 - - +Narrows the query results based on the category groups the categories belong to. -::: code +Possible values include: -| 値 | 取得するカテゴリ | -| -------------------------------------------------- | ------------------ | -| `1` | ID が 1 のグループ内。 | -| a [Category](api:craft\elements\Category) object | ID が 1 のグループ内ではない。 | +| 値 | Fetches categories… | +| ---------------------------------------------------------- | ----------------------------------------------- | +| `'foo'` | in a group with a handle of `foo`. | +| `'not foo'` | not in a group with a handle of `foo`. | +| `['foo', 'bar']` | in a group with a handle of `foo` or `bar`. | +| `['not', 'foo', 'bar']` | not in a group with a handle of `foo` or `bar`. | +| a [CategoryGroup](api:craft\models\CategoryGroup) object | in a group represented by the object. | -::: +::: code ```twig {# Fetch categories in the Foo group #} {% set categories = craft.categories() @@ -412,9 +459,16 @@ $categories = \craft\elements\Category::find() ### `groupId` -利用可能な値には、次のものが含まれます。 +Narrows the query results based on the category groups the categories belong to, per the groups’ IDs. +Possible values include: +| 値 | 取得するカテゴリ | +| --------------- | ------------------------------------ | +| `1` | in a group with an ID of 1. | +| `'not 1'` | not in a group with an ID of 1. | +| `[1, 2]` | in a group with an ID of 1 or 2. | +| `['not', 1, 2]` | not in a group with an ID of 1 or 2. | @@ -437,16 +491,11 @@ $categories = \craft\elements\Category::find() ### `hasDescendants` -カテゴリが子孫を持つかどうかに基づいて、クエリの結果を絞り込みます。 +Narrows the query results based on whether the categories have any descendants. -（これは [leaves](#leaves) の呼び出しと反対の効果を持っています。） - -| 値 | 取得するカテゴリ | -| ------------------ | ----------- | -| `true` _(default)_ | ID が 1。 | -| `'not 1'` | ID が 1ではない。 | +(This has the opposite effect of calling [leaves](#leaves).) @@ -469,13 +518,22 @@ $categories = \craft\elements\Category::find() ### `id` -カテゴリの ID に基づいて、クエリの結果を絞り込みます。 +Narrows the query results based on the categories’ IDs. + + +Possible values include: +| 値 | 取得するカテゴリ | +| --------------- | ------------------------- | +| `1` | with an ID of 1. | +| `'not 1'` | not with an ID of 1. | +| `[1, 2]` | with an ID of 1 or 2. | +| `['not', 1, 2]` | not with an ID of 1 or 2. | -利用可能な値には、次のものが含まれます。 +::: code ```twig {# Fetch the category by its ID #} {% set category = craft.categories() @@ -492,25 +550,34 @@ $category = \craft\elements\Category::find() ::: -### `inReverse` - -::: ::: tip -特定の順序で結果を返したい場合、[fixedOrder](#fixedorder) と組み合わせることができます。 +This can be combined with [fixedOrder](#fixedorder) if you want the results to be returned in a specific order. ::: -| 値 | 取得するカテゴリ | -| ---------------------------------------------------------- | ------------------ | -| `1` | レベルが 1。 | -| `'not 1'` | レベルが 1 ではない。 | -| `'>= 3'` | レベルが 3 以上。 | -| `[1, 2]` | レベルが 1 または 2。 | -| a [CategoryGroup](api:craft\models\CategoryGroup) object | レベルが 1 または 2 ではない。 | + +### `ignorePlaceholders` + +Causes the query to return matching categories as they are stored in the database, ignoring matching placeholder elements that were set by [craft\services\Elements::setPlaceholderElement()](https://docs.craftcms.com/api/v3/craft-services-elements.html#method-setplaceholderelement). + + + + -クエリの結果を逆順で返します。 + + + +### `inReverse` + +Causes the query results to be returned in reverse order. + + + + + +::: code ```twig {# Fetch categories in reverse #} {% set categories = craft.categories() @@ -529,20 +596,15 @@ $categories = \craft\elements\Category::find() ### `leaves` -::: +Narrows the query results based on whether the categories are “leaves” (categories with no descendants). -カテゴリが「leaves」（子孫のないカテゴリ）であるかどうかに基づいて、クエリの結果を絞り込みます。 -| 値 | 取得するカテゴリ | -| --------------- | ------------------------------------ | -| `1` | ID が 1 のカテゴリの後。 | -| `'not 1'` | オブジェクトで表されるカテゴリの後。 | -| `[1, 2]` | in a group with an ID of 1 or 2. | -| `['not', 1, 2]` | not in a group with an ID of 1 or 2. | +(This has the opposite effect of calling [hasDescendants](#hasdescendants).) -（これは [hasDescendants](#hasdescendants) の呼び出しと反対の効果を持っています。） + +::: code ```twig {# Fetch categories that have no descendants #} {% set categories = craft.categories() @@ -561,15 +623,23 @@ $categories = \craft\elements\Category::find() ### `level` -::: +Narrows the query results based on the categories’ level within the structure. -構造内のカテゴリのレベルに基づいて、クエリの結果を絞り込みます。 +Possible values include: +| 値 | Fetches categories… | +| --------------- | ---------------------------------------- | +| `1` | with a level of 1. | +| `'not 1'` | not with a level of 1. | +| `'>= 3'` | with a level greater than or equal to 3. | +| `[1, 2]` | with a level of 1 or 2 | +| `['not', 1, 2]` | not with level of 1 or 2. | -利用可能な値には、次のものが含まれます。 + +::: code ```twig {# Fetch categories positioned at level 3 or above #} {% set categories = craft.categories() @@ -588,18 +658,7 @@ $categories = \craft\elements\Category::find() ### `limit` -::: - - - -返されるカテゴリの数を決定します。 - -| 値 | 取得するカテゴリ | -| --------------- | ------------------------- | -| `1` | ID が 1 のカテゴリの後。 | -| `'not 1'` | オブジェクトで表されるカテゴリの後。 | -| `[1, 2]` | with an ID of 1 or 2. | -| `['not', 1, 2]` | not with an ID of 1 or 2. | +Determines the number of categories that should be returned. @@ -620,32 +679,22 @@ $categories = \craft\elements\Category::find() ::: - -指定したカテゴリの直後にあるカテゴリだけに、クエリの結果を絞り込みます。 - - ### `nextSiblingOf` -利用可能な値には、次のものが含まれます。 - - - - +Narrows the query results to only the category that comes immediately after another category. +Possible values include: +| 値 | Fetches the category… | +| -------------------------------------------------- | --------------------------------------------- | +| `1` | after the category with an ID of 1. | +| a [Category](api:craft\elements\Category) object | after the category represented by the object. | -### `offset` ::: code - - - - - -::: ```twig {# Fetch the next category #} {% set category = craft.categories() @@ -662,17 +711,13 @@ $category = \craft\elements\Category::find() ::: -### `orderBy` - -::: code - - +### `offset` -::: +Determines how many categories should be skipped in the results. -返されるカテゴリの順序を決定します。 +::: code ```twig {# Fetch all categories except for the first 3 #} {% set categories = craft.categories() @@ -689,25 +734,13 @@ $categories = \craft\elements\Category::find() ::: -### `positionedAfter` - -::: +### `orderBy` +Determines the order that the categories should be returned in. (If empty, defaults to `dateCreated DESC`.) -指定したカテゴリの後に位置するカテゴリだけに、クエリの結果を絞り込みます。 -| Value | Fetches categories… | -| --------------- | ---------------------------------------- | -| `1` | before the category with an ID of 1. | -| `'not 1'` | オブジェクトで表されるカテゴリの前。 | -| `'>= 3'` | with a level greater than or equal to 3. | -| `[1, 2]` | with a level of 1 or 2 | -| `['not', 1, 2]` | not with level of 1 or 2. | - - - -利用可能な値には、次のものが含まれます。 +::: code ```twig {# Fetch all categories in order of date created #} {% set categories = craft.categories() @@ -724,13 +757,22 @@ $categories = \craft\elements\Category::find() ::: -### `positionedBefore` +### `positionedAfter` -::: +Narrows the query results to only categories that are positioned after another category. + + + +Possible values include: +| Value | Fetches categories… | +| -------------------------------------------------- | --------------------------------------------- | +| `1` | after the category with an ID of 1. | +| a [Category](api:craft\elements\Category) object | after the category represented by the object. | -指定したカテゴリの前に位置するカテゴリだけに、クエリの結果を絞り込みます。 + +::: code ```twig {# Fetch categories after this one #} {% set categories = craft.categories() @@ -747,22 +789,22 @@ $categories = \craft\elements\Category::find() ::: -### `prevSiblingOf` +### `positionedBefore` -::: code +Narrows the query results to only categories that are positioned before another category. -::: +Possible values include: -| 値 | 取得するカテゴリ | -| ------------------------------------------------ | ------------------ | -| `1` | ID が 1 のカテゴリの前。 | -| [Category](api:craft\elements\Category) オブジェクト | オブジェクトで表されるカテゴリの前。 | +| 値 | Fetches categories… | +| ------------------------------------------------ | ---------------------------------------------- | +| `1` | before the category with an ID of 1. | +| [Category](api:craft\elements\Category) オブジェクト | before the category represented by the object. | -指定したカテゴリの直前にあるカテゴリだけに、クエリの結果を絞り込みます。 +::: code ```twig {# Fetch categories before this one #} {% set categories = craft.categories() @@ -779,396 +821,158 @@ $categories = \craft\elements\Category::find() ::: -### `relatedTo` - -::: code - - - -::: -```twig -{# Fetch the previous category #} -{% set category = craft.categories() - .prevSiblingOf(myCategory) - .one() %} -``` - -```php -// Fetch the previous category -$category = \craft\elements\Category::find() - ->prevSiblingOf($myCategory) - ->one(); -``` -::: - - -### `search` - -このパラメーターがどのように機能するかの詳細については、[リレーション](https://docs.craftcms.com/v3/relations.html)を参照してください。 - - - -::: code -```twig -{# Fetch all categories that are related to myCategory #} -{% set categories = craft.categories() - .relatedTo(myCategory) - .all() %} -``` - -```php -// Fetch all categories that are related to $myCategory -$categories = \craft\elements\Category::find() - ->relatedTo($myCategory) - ->all(); -``` -::: - - -### `siblingOf` - -検索クエリにマッチするカテゴリだけに、クエリの結果を絞り込みます。 - - - -このパラメーターがどのように機能するかの詳細については、[検索](https://docs.craftcms.com/v3/searching.html)を参照してください。 - -| 値 | 取得するカテゴリ | -| ------------------------------------------------ | ------------------ | -| `1` | ID が 1 のカテゴリの横。 | -| [Category](api:craft\elements\Category) オブジェクト | オブジェクトで表されるカテゴリの横。 | - - - -::: code -```twig -{# Get the search query from the 'q' query string param #} -{% set searchQuery = craft.app.request.getQueryParam('q') %} - -{# Fetch all categories that match the search query #} -{% set categories = craft.categories() - .search(searchQuery) - .all() %} -``` - -```php -// Get the search query from the 'q' query string param -$searchQuery = \Craft::$app->request->getQueryParam('q'); - -// Fetch all categories that match the search query -$categories = \craft\elements\Category::find() - ->search($searchQuery) - ->all(); -``` -::: - - -### `site` +### `preferSites` -指定したカテゴリの兄弟であるカテゴリだけに、クエリの結果を絞り込みます。 +If [unique](#unique) is set, this determines which site should be selected when querying multi-site elements. -利用可能な値には、次のものが含まれます。 +For example, if element “Foo” exists in Site A and Site B, and element “Bar” exists in Site B and Site C, and this is set to `['c', 'b', 'a']`, then Foo will be returned for Site C, and Bar will be returned for Site B. -| 値 | 取得するカテゴリ | -| ------------------------------------ | ------------------- | -| `foo'852.'foo'2303752'foo'` | ハンドルが `foo` のサイトから。 | -| `\craft\elements\db\Site` オブジェクト | オブジェクトで表されるサイトから。 | +If this isn’t set, then preference goes to the current site. ::: code ```twig -{# Fetch categories beside this one #} +{# Fetch unique categories from Site A, or Site B if they don’t exist in Site A #} {% set categories = craft.categories() - .siblingOf(myCategory) - .all() %} -``` - -```php -// Fetch categories beside this one -$categories = \craft\elements\Category::find() - ->siblingOf($myCategory) - ->all(); -``` -::: - - -### `siteId` - -カテゴリを照会するサイトを決定します。 - - - -デフォルトでは、現在のサイトが使用されます。 - -利用可能な値には、次のものが含まれます。 - - - -::: code -```twig -{# Fetch categories from the Foo site #} -{% set categories = craft.categories() - .site('foo') + .site('*') + .unique() + .preferSites(['a', 'b']) .all() %} ``` ```php -// Fetch categories from the Foo site +// Fetch unique categories from Site A, or Site B if they don’t exist in Site A $categories = \craft\elements\Category::find() - ->site('foo') + ->site('*') + ->unique() + ->preferSites(['a', 'b']) ->all(); ``` ::: -### `slug` - -サイトの ID ごとに、カテゴリを照会するサイトを決定します。 - - - -デフォルトでは、現在のサイトが使用されます。 - -| 値 | 取得するカテゴリ | -| -------------------------------------------------- | ----------------- | -| `oo'e7c'foo'.277707'foo'7'foo'` | スラグが `foo`。 | -| a [Category](api:craft\elements\Category) object | スラグが `foo` ではじまる。 | - - - -::: code -```twig -{# Fetch categories from the site with an ID of 1 #} -{% set categories = craft.categories() - .siteId(1) - .all() %} -``` - -```php -// Fetch categories from the site with an ID of 1 -$categories = \craft\elements\Category::find() - ->siteId(1) - ->all(); -``` -::: - +### `prevSiblingOf` -### `status` +Narrows the query results to only the category that comes immediately before another category. -カテゴリのスラグに基づいて、クエリの結果を絞り込みます。 +Possible values include: -利用可能な値には、次のものが含まれます。 +| 値 | Fetches the category… | +| ------------------------------------------------ | ---------------------------------------------- | +| `1` | before the category with an ID of 1. | +| [Category](api:craft\elements\Category) オブジェクト | before the category represented by the object. | ::: code ```twig -{# Get the requested category slug from the URL #} -{% set requestedSlug = craft.app.request.getSegment(3) %} - -{# Fetch the category with that slug #} +{# Fetch the previous category #} {% set category = craft.categories() - .slug(requestedSlug|literal) + .prevSiblingOf(myCategory) .one() %} ``` ```php -// Get the requested category slug from the URL -$requestedSlug = \Craft::$app->request->getSegment(3); - -// Fetch the category with that slug +// Fetch the previous category $category = \craft\elements\Category::find() - ->slug(\craft\helpers\Db::escapeParam($requestedSlug)) + ->prevSiblingOf($myCategory) ->one(); ``` ::: -### `title` - -カテゴリのステータスに基づいて、クエリの結果を絞り込みます。 +### `relatedTo` +Narrows the query results to only categories that are related to certain other elements. -利用可能な値には、次のものが含まれます。 -| 値 | 取得するカテゴリ | -| -------------------------------------- | ----------- | -| `1` | 有効になっているもの。 | -| a `\craft\elements\db\User` object | 無効になっているもの。 | +See [Relations](https://docs.craftcms.com/v3/relations.html) for a full explanation of how to work with this parameter. ::: code ```twig -{# Fetch disabled categories #} +{# Fetch all categories that are related to myCategory #} {% set categories = craft.categories() - .status('disabled') + .relatedTo(myCategory) .all() %} ``` ```php -// Fetch disabled categories +// Fetch all categories that are related to $myCategory $categories = \craft\elements\Category::find() - ->status('disabled') + ->relatedTo($myCategory) ->all(); ``` ::: -### `trashed` - -カテゴリのタイトルに基づいて、クエリの結果を絞り込みます。 +### `search` +Narrows the query results to only categories that match a search query. -利用可能な値には、次のものが含まれます。 -| 値 | 取得するカテゴリ | -| ----------------------- | ------------ | -| `o'f7bd4.72649324'Foo'` | タイトルが `Foo`。 | +See [Searching](https://docs.craftcms.com/v3/searching.html) for a full explanation of how to work with this parameter. ::: code ```twig -{# Fetch categories with a title that contains "Foo" #} +{# Get the search query from the 'q' query string param #} +{% set searchQuery = craft.app.request.getQueryParam('q') %} + +{# Fetch all categories that match the search query #} {% set categories = craft.categories() - .title('*Foo*') + .search(searchQuery) .all() %} ``` ```php -// Fetch categories with a title that contains "Foo" -$categories = \craft\elements\Category::find() - ->title('*Foo*') - ->all(); -``` -::: - - -### `uid` - -ソフトデリートされたカテゴリだけに、クエリの結果を絞り込みます。 - - - -::: code - -| 値 | 取得するカテゴリ | -| -------------------------------------------------- | ------------------ | -| `843.68'foo'07527'foo'` | URI が `foo`。 | -| a [Category](api:craft\elements\Category) object | URI が `foo` ではじまる。 | - - - -::: -```twig -{# Fetch trashed categories #} -{% set categories = {twig-function} - .trashed() - .all() %} -``` +// Get the search query from the 'q' query string param +$searchQuery = \Craft::$app->request->getQueryParam('q'); -```php -// Fetch trashed categories +// Fetch all categories that match the search query $categories = \craft\elements\Category::find() - ->trashed() + ->search($searchQuery) ->all(); ``` ::: -### `uri` - -::: code - - - - - -::: -```twig -{# Fetch the category by its UID #} -{% set category = craft.categories() - .uid('xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx') - .one() %} -``` - -```php -// Fetch the category by its UID -$category = \craft\elements\Category::find() - ->uid('xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx') - ->one(); -``` -::: - - -### `with` - -利用可能な値には、次のものが含まれます。 - - - -::: code - - - -::: -```twig -{# Get the requested URI #} -{% set requestedUri = craft.app.request.getPathInfo() %} - -{# Fetch the category with that URI #} -{% set category = craft.categories() - .uri(requestedUri|literal) - .one() %} -``` - -```php -// Get the requested URI -$requestedUri = \Craft::$app->request->getPathInfo(); - -// Fetch the category with that URI -$category = \craft\elements\Category::find() - ->uri(\craft\helpers\Db::escapeParam($requestedUri)) - ->one(); -``` -::: - - ### `siblingOf` -このパラメーターがどのように機能するかの詳細については、[エレメントのEager-Loading](https://docs.craftcms.com/v3/dev/eager-loading-elements.html)を参照してください。 +Narrows the query results to only categories that are siblings of another category. -::: code +Possible values include: -| Value | Fetches categories… | +| 値 | 取得するカテゴリ | | -------------------------------------------------- | ---------------------------------------------- | | `1` | beside the category with an ID of 1. | | a [Category](api:craft\elements\Category) object | beside the category represented by the object. | -::: +::: code ```twig -{# Fetch categories eager-loaded with the "Related" field’s relations #} +{# Fetch categories beside this one #} {% set categories = craft.categories() - .with(['related']) + .siblingOf(myCategory) .all() %} ``` ```php -// Fetch categories eager-loaded with the "Related" field’s relations +// Fetch categories beside this one $categories = \craft\elements\Category::find() - ->with(['related']) + ->siblingOf($myCategory) ->all(); ``` ::: @@ -1184,13 +988,13 @@ The current site will be used by default. Possible values include: -| Value | Fetches categories… | -| -------------------------------------- | ---------------------------------------------- | -| `'foo'` | from the site with a handle of `foo`. | -| `['foo', 'bar']` | from a site with a handle of `foo` or `bar`. | -| `['not', 'foo', 'bar']` | not in a site with a handle of `foo` or `bar`. | -| a `\craft\elements\db\Site` object | from the site represented by the object. | -| `'*'` | from any site. | +| 値 | Fetches categories… | +| ------------------------------------------------------- | ---------------------------------------------- | +| `'foo'` | from the site with a handle of `foo`. | +| `['foo', 'bar']` | from a site with a handle of `foo` or `bar`. | +| `['not', 'foo', 'bar']` | not in a site with a handle of `foo` or `bar`. | +| a [craft\models\Site](api:craft\models\Site) object | from the site represented by the object. | +| `'*'` | from any site. | ::: tip If multiple sites are specified, elements that belong to multiple sites will be returned multiple times. If you only want unique elements to be returned, use [unique](#unique) in conjunction with this. @@ -1250,7 +1054,7 @@ Narrows the query results based on the categories’ slugs. Possible values include: -| Value | Fetches categories… | +| 値 | Fetches categories… | | --------------------------- | ------------------------------------------------ | | `'foo'` | with a slug of `foo`. | | `'foo*'` | with a slug that begins with `foo`. | @@ -1293,7 +1097,7 @@ Narrows the query results based on the categories’ statuses. Possible values include: -| Value | Fetches categories… | +| 値 | Fetches categories… | | ------------------------ | ------------------- | | `'enabled'` _(default)_ | that are enabled. | | `'disabled'` | that are disabled. | @@ -1325,7 +1129,7 @@ Narrows the query results based on the categories’ titles. Possible values include: -| Value | Fetches categories… | +| 値 | Fetches categories… | | --------------------------- | ------------------------------------------------- | | `'Foo'` | with a title of `Foo`. | | `'Foo*'` | with a title that begins with `Foo`. | From 89764a99414420dd7f442ba631b108b0b9684d69 Mon Sep 17 00:00:00 2001 From: Brad Bell Date: Fri, 12 Jun 2020 17:32:19 -0700 Subject: [PATCH 028/245] New translations category-queries.md (French) --- fr/dev/element-queries/category-queries.md | 322 +++++---------------- 1 file changed, 65 insertions(+), 257 deletions(-) diff --git a/fr/dev/element-queries/category-queries.md b/fr/dev/element-queries/category-queries.md index 2f566e1dd7b..5c569862c86 100644 --- a/fr/dev/element-queries/category-queries.md +++ b/fr/dev/element-queries/category-queries.md @@ -57,6 +57,49 @@ Category queries support the following parameters: +| Param | Description | +| ----------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| [ancestorDist](#ancestordist) | Narrows the query results to only categories that are up to a certain distance away from the category specified by [ancestorOf](#ancestorof). | +| [ancestorOf](#ancestorof) | Narrows the query results to only categories that are ancestors of another category. | +| [anyStatus](#anystatus) | Clears out the [status](#status) and [enabledForSite](#enabledforsite) parameters. | +| [asArray](#asarray) | Causes the query to return matching categories as arrays of data, rather than [Category](api:craft\elements\Category) objects. | +| [clearCachedResult](#clearcachedresult) | Clears the cached result. | +| [dateCreated](#datecreated) | Narrows the query results based on the categories’ creation dates. | +| [dateUpdated](#dateupdated) | Narrows the query results based on the categories’ last-updated dates. | +| [descendantDist](#descendantdist) | Narrows the query results to only categories that are up to a certain distance away from the category specified by [descendantOf](#descendantof). | +| [descendantOf](#descendantof) | Narrows the query results to only categories that are descendants of another category. | +| [enabledForSite](#enabledforsite) | Narrows the query results based on whether the categories are enabled in the site they’re being queried in, per the [site](#site) parameter. | +| [fixedOrder](#fixedorder) | Causes the query results to be returned in the order specified by [id](#id). | +| [group](#group) | Narrows the query results based on the category groups the categories belong to. | +| [groupId](#groupid) | Narrows the query results based on the category groups the categories belong to, per the groups’ IDs. | +| [hasDescendants](#hasdescendants) | Narrows the query results based on whether the categories have any descendants. | +| [id](#id) | Narrows the query results based on the categories’ IDs. | +| [ignorePlaceholders](#ignoreplaceholders) | Causes the query to return matching categories as they are stored in the database, ignoring matching placeholder elements that were set by [craft\services\Elements::setPlaceholderElement()](https://docs.craftcms.com/api/v3/craft-services-elements.html#method-setplaceholderelement). | +| [inReverse](#inreverse) | Causes the query results to be returned in reverse order. | +| [leaves](#leaves) | Narrows the query results based on whether the categories are “leaves” (categories with no descendants). | +| [level](#level) | Narrows the query results based on the categories’ level within the structure. | +| [limit](#limit) | Determines the number of categories that should be returned. | +| [nextSiblingOf](#nextsiblingof) | Narrows the query results to only the category that comes immediately after another category. | +| [offset](#offset) | Determines how many categories should be skipped in the results. | +| [orderBy](#orderby) | Determines the order that the categories should be returned in. (If empty, defaults to `dateCreated DESC`.) | +| [positionedAfter](#positionedafter) | Narrows the query results to only categories that are positioned after another category. | +| [positionedBefore](#positionedbefore) | Narrows the query results to only categories that are positioned before another category. | +| [preferSites](#prefersites) | If [unique](#unique) is set, this determines which site should be selected when querying multi-site elements. | +| [prevSiblingOf](#prevsiblingof) | Narrows the query results to only the category that comes immediately before another category. | +| [relatedTo](#relatedto) | Narrows the query results to only categories that are related to certain other elements. | +| [search](#search) | Narrows the query results to only categories that match a search query. | +| [siblingOf](#siblingof) | Narrows the query results to only categories that are siblings of another category. | +| [site](#site) | Determines which site(s) the categories should be queried in. | +| [siteId](#siteid) | Determines which site(s) the categories should be queried in, per the site’s ID. | +| [slug](#slug) | Narrows the query results based on the categories’ slugs. | +| [status](#status) | Narrows the query results based on the categories’ statuses. | +| [title](#title) | Narrows the query results based on the categories’ titles. | +| [trashed](#trashed) | Narrows the query results to only categories that have been soft-deleted. | +| [uid](#uid) | Narrows the query results based on the categories’ UIDs. | +| [unique](#unique) | Determines whether only elements with unique IDs should be returned by the query. | +| [uri](#uri) | Narrows the query results based on the categories’ URIs. | +| [with](#with) | Causes the query to return matching categories eager-loaded with related elements. | + ### `ancestorDist` Narrows the query results to only categories that are up to a certain distance away from the category specified by [ancestorOf](#ancestorof). @@ -172,6 +215,15 @@ $categories = \craft\elements\Category::find() ::: +### `clearCachedResult` + +Clears the cached result. + + + + + + ### `dateCreated` Narrows the query results based on the categories’ creation dates. @@ -313,128 +365,6 @@ This can be combined with [descendantDist](#descendantdist) if you want to limit ::: -### `draftCreator` - -Narrows the query results to only drafts created by a given user. - - - -Possible values include: - -| Value | Fetches drafts… | -| -------------------------------------- | -------------------------------------- | -| `1` | created by the user with an ID of 1. | -| a `\craft\elements\db\User` object | by the user represented by the object. | - - - -::: code -```twig -{# Fetch drafts by the current user #} -{% set categories = craft.categories() - .draftCreator(currentUser) - .all() %} -``` - -```php -// Fetch drafts by the current user -$categories = \craft\elements\Category::find() - ->draftCreator(Craft::$app->user->identity) - ->all(); -``` -::: - - -### `draftId` - -Narrows the query results based on the categories’ draft’s ID (from the `drafts` table). - - - -Possible values include: - -| Value | Fetches drafts… | -| ----- | ------------------------------ | -| `1` | for the draft with an ID of 1. | - - - -::: code -```twig -{# Fetch a draft #} -{% set categories = craft.categories() - .draftId(10) - .all() %} -``` - -```php -// Fetch a draft -$categories = \craft\elements\Category::find() - ->draftIf(10) - ->all(); -``` -::: - - -### `draftOf` - -Narrows the query results to only drafts of a given category. - - - -Possible values include: - -| Value | Fetches drafts… | -| -------------------------------------------------- | ------------------------------------------- | -| `1` | for the category with an ID of 1. | -| a [Category](api:craft\elements\Category) object | for the category represented by the object. | - - - -::: code -```twig -{# Fetch drafts of the category #} -{% set categories = craft.categories() - .draftOf(myCategory) - .all() %} -``` - -```php -// Fetch drafts of the category -$categories = \craft\elements\Category::find() - ->draftOf($myCategory) - ->all(); -``` -::: - - -### `drafts` - -Narrows the query results to only drafts categories. - - - - - -::: code -```twig -{# Fetch a draft category #} -{% set categories = {twig-function} - .drafts() - .id(123) - .one() %} -``` - -```php -// Fetch a draft category -$categories = \craft\elements\Category::find() - ->drafts() - ->id(123) - ->one(); -``` -::: - - ### `enabledForSite` Narrows the query results based on whether the categories are enabled in the site they’re being queried in, per the [site](#site) parameter. @@ -445,7 +375,7 @@ Possible values include: | Value | Fetches categories… | | ------------------ | -------------------------------------------- | -| `true` *(default)* | that are enabled in the site. | +| `true` _(default)_ | that are enabled in the site. | | `false` | whether they are enabled or not in the site. | @@ -806,7 +736,7 @@ $categories = \craft\elements\Category::find() ### `orderBy` -Determines the order that the categories should be returned in. +Determines the order that the categories should be returned in. (If empty, defaults to `dateCreated DESC`.) @@ -983,128 +913,6 @@ $categories = \craft\elements\Category::find() ::: -### `revisionCreator` - -Narrows the query results to only revisions created by a given user. - - - -Possible values include: - -| Value | Fetches revisions… | -| -------------------------------------- | -------------------------------------- | -| `1` | created by the user with an ID of 1. | -| a `\craft\elements\db\User` object | by the user represented by the object. | - - - -::: code -```twig -{# Fetch revisions by the current user #} -{% set categories = craft.categories() - .revisionCreator(currentUser) - .all() %} -``` - -```php -// Fetch revisions by the current user -$categories = \craft\elements\Category::find() - ->revisionCreator(Craft::$app->user->identity) - ->all(); -``` -::: - - -### `revisionId` - -Narrows the query results based on the categories’ revision’s ID (from the `revisions` table). - - - -Possible values include: - -| Value | Fetches revisions… | -| ----- | --------------------------------- | -| `1` | for the revision with an ID of 1. | - - - -::: code -```twig -{# Fetch a revision #} -{% set categories = craft.categories() - .revisionId(10) - .all() %} -``` - -```php -// Fetch a revision -$categories = \craft\elements\Category::find() - ->revisionIf(10) - ->all(); -``` -::: - - -### `revisionOf` - -Narrows the query results to only revisions of a given category. - - - -Possible values include: - -| Value | Fetches revisions… | -| -------------------------------------------------- | ------------------------------------------- | -| `1` | for the category with an ID of 1. | -| a [Category](api:craft\elements\Category) object | for the category represented by the object. | - - - -::: code -```twig -{# Fetch revisions of the category #} -{% set categories = craft.categories() - .revisionOf(myCategory) - .all() %} -``` - -```php -// Fetch revisions of the category -$categories = \craft\elements\Category::find() - ->revisionOf($myCategory) - ->all(); -``` -::: - - -### `revisions` - -Narrows the query results to only revision categories. - - - - - -::: code -```twig -{# Fetch a revision category #} -{% set categories = {twig-function} - .revisions() - .id(123) - .one() %} -``` - -```php -// Fetch a revision category -$categories = \craft\elements\Category::find() - ->revisions() - ->id(123) - ->one(); -``` -::: - - ### `search` Narrows the query results to only categories that match a search query. @@ -1180,13 +988,13 @@ The current site will be used by default. Possible values include: -| Value | Fetches categories… | -| -------------------------------------- | ---------------------------------------------- | -| `'foo'` | from the site with a handle of `foo`. | -| `['foo', 'bar']` | from a site with a handle of `foo` or `bar`. | -| `['not', 'foo', 'bar']` | not in a site with a handle of `foo` or `bar`. | -| a `\craft\elements\db\Site` object | from the site represented by the object. | -| `'*'` | from any site. | +| Value | Fetches categories… | +| ------------------------------------------------------- | ---------------------------------------------- | +| `'foo'` | from the site with a handle of `foo`. | +| `['foo', 'bar']` | from a site with a handle of `foo` or `bar`. | +| `['not', 'foo', 'bar']` | not in a site with a handle of `foo` or `bar`. | +| a [craft\models\Site](api:craft\models\Site) object | from the site represented by the object. | +| `'*'` | from any site. | ::: tip If multiple sites are specified, elements that belong to multiple sites will be returned multiple times. If you only want unique elements to be returned, use [unique](#unique) in conjunction with this. @@ -1289,10 +1097,10 @@ Narrows the query results based on the categories’ statuses. Possible values include: -| Value | Fetches categories… | -| ----------------------- | ------------------- | -| `'enabled'` *(default)* | that are enabled. | -| `'disabled'` | that are disabled. | +| Value | Fetches categories… | +| ------------------------ | ------------------- | +| `'enabled'` _(default)_ | that are enabled. | +| `'disabled'` | that are disabled. | From da0361f87777d97a6470c15096f561de12b86678 Mon Sep 17 00:00:00 2001 From: Brad Bell Date: Fri, 12 Jun 2020 17:32:22 -0700 Subject: [PATCH 029/245] New translations date-time-fields.md (French) --- fr/date-time-fields.md | 15 ++++++++++----- 1 file changed, 10 insertions(+), 5 deletions(-) diff --git a/fr/date-time-fields.md b/fr/date-time-fields.md index ceb5a50108a..86c51120da8 100644 --- a/fr/date-time-fields.md +++ b/fr/date-time-fields.md @@ -29,7 +29,7 @@ Possible values include: {% set end = now|date_modify('+1 month')|atom %} {% set entries = craft.entries() - .('and', ">= #{start}", "< #{end}") + .(['and', ">= #{start}", "< #{end}"]) .all() %} ``` @@ -93,16 +93,21 @@ The [HTML5Forms.js](https://github.com/zoltan-dulac/html5Forms.js) polyfill can #### Customizing the Timezone -By default, Craft will assume the date is posted in UTC. As of Craft 3.1.6 you you can post dates in a different timezone by changing the input name to `fields[][datetime]` and adding a hidden input named `fields[][timezone]`, set to a [valid PHP timezone](http://php.net/manual/en/timezones.php): +By default, Craft will assume the date is posted in UTC. As of Craft 3.1.6 you can post dates in a different timezone by changing the input name to `fields[][datetime]` and adding a hidden input named `fields[][timezone]`, set to a [valid PHP timezone](http://php.net/manual/en/timezones.php): ```twig -{% set pt = 'America/Los_Angeles' %} +{# Use the timezone selected under Settings → General Settings → Time Zone #} +{% set tz = craft.app.getTimezone() %} + +{# Or set a specific timezone #} +{% set tz = 'America/Los_Angeles' %} + {% set currentValue = entry is defined and entry. - ? entry.|date('Y-m-d\\TH:i', timezone=pt) + ? entry.|date('Y-m-d\\TH:i', tz) : '' %} -{{ hiddenInput('fields[][timezone]', pt) }} +{{ hiddenInput('fields[][timezone]', tz) }} ``` Or you can let users decide which timezone the date should be posted in: From b88d21577a49c7edf44be7f6f262759228de912b Mon Sep 17 00:00:00 2001 From: Brad Bell Date: Fri, 12 Jun 2020 17:32:24 -0700 Subject: [PATCH 030/245] New translations date-time-fields.md (Japanese) --- ja/date-time-fields.md | 17 +++++++++++------ 1 file changed, 11 insertions(+), 6 deletions(-) diff --git a/ja/date-time-fields.md b/ja/date-time-fields.md index acdc16c53b1..8346e13360c 100644 --- a/ja/date-time-fields.md +++ b/ja/date-time-fields.md @@ -8,7 +8,7 @@ ## テンプレート記法 -### 日/時フィールドによるエレメントの照会 +### Querying Elements with Date/Time Fields 日/時フィールドを持つ[エレメントを照会](dev/element-queries/README.md)する場合、フィールドのハンドルにちなんで名付けられたクエリパラメータを使用して、日/時フィールドのデータに基づいた結果をフィルタできます。 @@ -29,7 +29,7 @@ {% set end = now|date_modify('+1 month')|atom %} {% set entries = craft.entries() - .('and', ">= #{start}", "< #{end}") + .(['and', ">= #{start}", "< #{end}"]) .all() %} ``` @@ -93,16 +93,21 @@ Craft と Twig は、必要に応じて使用できる日付を操作するた #### タイムゾーンのカスタマイズ -デフォルトでは、Craft は日付が UTC で投稿されていると想定します。Craft 3.1.6 から、入力欄の name を `fields[][datetime]`、不可視項目の name を `fields[][timezone]` とし、[有効な PHP タイムゾーン](http://php.net/manual/en/timezones.php)をセットすることによって、異なるタイムゾーンの日付を投稿できます。 +By default, Craft will assume the date is posted in UTC. As of Craft 3.1.6 you can post dates in a different timezone by changing the input name to `fields[][datetime]` and adding a hidden input named `fields[][timezone]`, set to a [valid PHP timezone](http://php.net/manual/en/timezones.php): ```twig -{% set pt = 'America/Los_Angeles' %} +{# Use the timezone selected under Settings → General Settings → Time Zone #} +{% set tz = craft.app.getTimezone() %} + +{# Or set a specific timezone #} +{% set tz = 'America/Los_Angeles' %} + {% set currentValue = entry is defined and entry. - ? entry.|date('Y-m-d\\TH:i', timezone=pt) + ? entry.|date('Y-m-d\\TH:i', tz) : '' %} -{{ hiddenInput('fields[][timezone]', pt) }} +{{ hiddenInput('fields[][timezone]', tz) }} ``` または、どのタイムゾーンで日付を投稿するかをユーザーに決定させることもできます。 From afb76b5cefe84d9917b0c380a583ff0884885340 Mon Sep 17 00:00:00 2001 From: Brad Bell Date: Fri, 12 Jun 2020 17:32:29 -0700 Subject: [PATCH 031/245] New translations entries-fields.md (French) --- fr/entries-fields.md | 58 ++++++++++++++++++++++++++++++++++++++------ 1 file changed, 51 insertions(+), 7 deletions(-) diff --git a/fr/entries-fields.md b/fr/entries-fields.md index 90677eeb0d5..7baa5d265b4 100644 --- a/fr/entries-fields.md +++ b/fr/entries-fields.md @@ -40,15 +40,21 @@ When [querying for elements](dev/element-queries/README.md) that have an Entries Possible values include: -| Value | Fetches elements… -| - | - -| `':empty:'` | that don’t have any related entries. -| `':notempty:'` | that have at least one related entry. +| Value | Fetches elements… | +| ----------------------------------------------------------- | -------------------------------------------------------- | +| `':empty:'` | that don’t have any related entries. | +| `':notempty:'` | that have at least one related entry. | +| `100` | that are related to the entry with an ID of 100. | +| `[100, 200]` | that are related to an entry with an ID of 100 or 200. | +| `['and', 100, 200]` | that are related to the entries with IDs of 100 and 200. | +| an [Entry](api:craft\elements\Entry) object | that are related to the entry. | +| an [EntryQuery](api:craft\elements\db\EntryQuery) object | that are related to any of the resulting entries. | ```twig -{# Fetch entries with a related entry #} -{% set entries = craft.entries() - .(':notempty:') +{# Fetch artwork entries that are related to `artist` #} +{% set works = craft.entries() + .section('artwork') + .(artist) .all() %} ``` @@ -104,6 +110,44 @@ You can set [parameters](dev/element-queries/entry-queries.md#parameters) on the It’s always a good idea to clone the entry query using the [clone()](./dev/functions.md#clone) function before adjusting its parameters, so the parameters don’t have unexpected consequences later on in your template. ::: +### Saving Entries Fields in Entry Forms + +If you have an [entry form](dev/examples/entry-form.md) that needs to contain an Entries field, you will need to submit your field value as a list of entry IDs, in the order you want them to be related. + +For example, you could create a list of checkboxes for each of the possible relations: + +```twig +{# Include a hidden input first so Craft knows to update the + existing value, if no checkboxes are checked. #} +{{ hiddenInput('fields[]', '') }} + +{# Get all of the possible entry options #} +{% set possibleEntries = craft.entries() + .section('galleries') + .orderBy('title ASC') + .all() %} + +{# Get the currently related entry IDs #} +{% set relatedEntryIds = entry is defined + ? entry..ids() + : [] %} + +
    + {% for possibleEntry in possibleEntries %} +
  • + +
    • + {% endfor %} +
+``` + +You could then make the checkbox list sortable, so users have control over the order of related entries. + ## See Also * [Entry Queries](dev/element-queries/entry-queries.md) From 5df28a671761b5b36eb7bb5aa51801cadce01da7 Mon Sep 17 00:00:00 2001 From: Brad Bell Date: Fri, 12 Jun 2020 17:32:32 -0700 Subject: [PATCH 032/245] New translations globals.md (French) --- fr/globals.md | 21 ++++++++++++++++++--- 1 file changed, 18 insertions(+), 3 deletions(-) diff --git a/fr/globals.md b/fr/globals.md index aa9fab5423a..40883a2f7eb 100644 --- a/fr/globals.md +++ b/fr/globals.md @@ -1,12 +1,12 @@ # Globals -Globals store content that is available globally throughout your templates. They're a convenient way to make non-Entry content easily editable via the Control Panel. +Globals store content that is available globally throughout your templates. They're a convenient way to make non-Entry content easily editable via the control panel. Craft organizes Globals into Global Sets. Each Global Set has its own [field layout](fields.md#field-layouts) using any of the existing fields or new fields. To create a Global Set, go to Settings → Globals. -If you have at least one Global Set, Craft will add a new “Globals” item added to the Control Panel primary navigation. Clicking on this will take you to a page that lists all of your Global Sets in a sidebar, as well as all of the fields associated with the selected Global Set in the main content area. +If you have at least one Global Set, Craft will add a new “Globals” item added to the control panel primary navigation. Clicking on this will take you to a page that lists all of your Global Sets in a sidebar, as well as all of the fields associated with the selected Global Set in the main content area. ::: tip Unlike [entries](sections-and-entries.md#entries), Global Sets don’t have the Live Preview feature, since they aren’t associated with any one particular URL. @@ -24,12 +24,27 @@ If you have a Global Set with the handle `companyInfo` and it has a field with t For additional Global Set properties you can use besides your custom fields see for a full reference. +### Manually Loading Global Sets + +In some special situations, like within email templates, Global Sets won’t be available by default. Any Global Set may still be loaded manually. The above example could be loaded with `getSetByHandle()`: + +::: code +```twig +{% set companyInfo = craft.globals().getSetByHandle('companyInfo') %} +``` +```php +$companyInfo = \Craft::$app->getGlobals()->getSetByHandle('companyInfo'); +``` +::: + +More details are available in the [Globals service class documentation](api:craft\services\Globals). + ## Global Sets with Multiple Sites If you run multiple sites with Craft, Global Sets are available in all sites. However, you can set the values in those sets on a per site basis, even leaving some fields blank, if desired. To do that, edit the global set’s fields, and make sure that their “Translation Method” settings are set to “Translate for each site”. -To toggle between sites while viewing Global Sets, use the drop-down menu at the top left of the Global Sets page in the Control Panel. +To toggle between sites while viewing Global Sets, use the drop-down menu at the top left of the Global Sets page in the control panel. ![Toggling between sites in Globals](./images/globals-multisite-nav.png) From d4fc82032a0e755863d65428acf88940088d6ec6 Mon Sep 17 00:00:00 2001 From: Brad Bell Date: Fri, 12 Jun 2020 17:32:33 -0700 Subject: [PATCH 033/245] New translations entries-fields.md (Japanese) --- ja/entries-fields.md | 62 +++++++++++++++++++++++++++++++++++++++----- 1 file changed, 55 insertions(+), 7 deletions(-) diff --git a/ja/entries-fields.md b/ja/entries-fields.md index f7fa916b1b7..a9edf0e9c70 100644 --- a/ja/entries-fields.md +++ b/ja/entries-fields.md @@ -40,15 +40,21 @@ 利用可能な値には、次のものが含まれます。 -| 値 | 取得するエレメント | -| -------------- | ----------------------- | -| `':empty:'` | 関連付けられたエントリを持たない。 | -| `':notempty:'` | 少なくとも1つの関連付けられたエントリを持つ。 | +| 値 | 取得するエレメント | +| ----------------------------------------------------------- | -------------------------------------------------------- | +| `':empty:'` | 関連付けられたエントリを持たない。 | +| `':notempty:'` | 少なくとも1つの関連付けられたエントリを持つ。 | +| `100` | that are related to the entry with an ID of 100. | +| `[100, 200]` | that are related to an entry with an ID of 100 or 200. | +| `['and', 100, 200]` | that are related to the entries with IDs of 100 and 200. | +| an [Entry](api:craft\elements\Entry) object | that are related to the entry. | +| an [EntryQuery](api:craft\elements\db\EntryQuery) object | that are related to any of the resulting entries. | ```twig -{# Fetch entries with a related entry #} -{% set entries = craft.entries() - .(':notempty:') +{# Fetch artwork entries that are related to `artist` #} +{% set works = craft.entries() + .section('artwork') + .(artist) .all() %} ``` @@ -100,6 +106,48 @@ .all() %} ``` +::: tip +It’s always a good idea to clone the entry query using the [clone()](./dev/functions.md#clone) function before adjusting its parameters, so the parameters don’t have unexpected consequences later on in your template. +::: + +### Saving Entries Fields in Entry Forms + +If you have an [entry form](dev/examples/entry-form.md) that needs to contain an Entries field, you will need to submit your field value as a list of entry IDs, in the order you want them to be related. + +For example, you could create a list of checkboxes for each of the possible relations: + +```twig +{# Include a hidden input first so Craft knows to update the + existing value, if no checkboxes are checked. #} +{{ hiddenInput('fields[]', '') }} + +{# Get all of the possible entry options #} +{% set possibleEntries = craft.entries() + .section('galleries') + .orderBy('title ASC') + .all() %} + +{# Get the currently related entry IDs #} +{% set relatedEntryIds = entry is defined + ? entry..ids() + : [] %} + +
    + {% for possibleEntry in possibleEntries %} +
  • + +
    • + {% endfor %} +
+``` + +You could then make the checkbox list sortable, so users have control over the order of related entries. + ## 関連項目 * [エントリクエリ](dev/element-queries/entry-queries.md) From 9ede6172d7c34c60d2ae8abe6202d8c20092a2dd Mon Sep 17 00:00:00 2001 From: Brad Bell Date: Fri, 12 Jun 2020 17:32:35 -0700 Subject: [PATCH 034/245] New translations fields.md (French) --- fr/fields.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/fr/fields.md b/fr/fields.md index 3359633d16d..da52f76b8db 100644 --- a/fr/fields.md +++ b/fr/fields.md @@ -7,7 +7,7 @@ Fields are defined globally from Settings → Fields. They are organized into Fi All fields share a few common settings: - **Group** – The field group that the field should be shown in -- **Name** – How the field will be referenced throughout the Control Panel +- **Name** – How the field will be referenced throughout the control panel - **Handle** – How the field will be referenced from your templates - **Instructions** – Instruction text to guide the authors - **Field Type** – What type of field it is From 4d6cbd1144cc12a6ba3882f3db349be137e30056 Mon Sep 17 00:00:00 2001 From: Brad Bell Date: Fri, 12 Jun 2020 17:32:37 -0700 Subject: [PATCH 035/245] New translations fields.md (Japanese) --- ja/fields.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/ja/fields.md b/ja/fields.md index bc0919604ce..8e32037228d 100644 --- a/ja/fields.md +++ b/ja/fields.md @@ -7,7 +7,7 @@ すべてのフィールドはいくつかの共通の設定があります。 - 所属するフィールドグループ -- 名前 +- **Name** – How the field will be referenced throughout the control panel - ハンドル - 説明 - **Field Type** – What type of field it is From e6dcf894e015cc5e9cb94fe7fca13fa3517aae87 Mon Sep 17 00:00:00 2001 From: Brad Bell Date: Fri, 12 Jun 2020 17:32:38 -0700 Subject: [PATCH 036/245] New translations gc.md (French) --- fr/gc.md | 3 +++ 1 file changed, 3 insertions(+) diff --git a/fr/gc.md b/fr/gc.md index 218c6070f9a..4f8e5f4a9dc 100644 --- a/fr/gc.md +++ b/fr/gc.md @@ -2,9 +2,12 @@ Craft occasionally runs a few garbage collection routines to remove stale data, including: +- Purge unsaved drafts (per the config setting). +- Delete expired template caches. - Purge any expired pending user accounts (per the config setting). - Hard delete expired soft-deleted rows (per the config setting). - Delete stale user session data. +- Delete orphaned search indexes (any indexes belonging to elements that don’t exist anymore). By default, each web request has a 1 in 100,000 chance of triggering garbage collection. That can be configured from `config/app.php` by overriding . From 254d7957b9f35ca716216905f0114124a9e9516a Mon Sep 17 00:00:00 2001 From: Brad Bell Date: Fri, 12 Jun 2020 17:32:40 -0700 Subject: [PATCH 037/245] New translations gc.md (Japanese) --- ja/gc.md | 9 ++++++--- 1 file changed, 6 insertions(+), 3 deletions(-) diff --git a/ja/gc.md b/ja/gc.md index 976c9cb76cd..7c1dde0836a 100644 --- a/ja/gc.md +++ b/ja/gc.md @@ -2,9 +2,12 @@ Craft は古いデータを削除するためにいくつかのガベージコレクションルーチンを実行することがあります。 -- （コンフィグ設定の ごとに）期限切れの保留中のユーザーアカウントを削除します。 -- （コンフィグ設定の ごとに）期限切れのソフトデリート行を完全に削除します。 -- 古いユーザーセッションデータを削除します。 +- Purge unsaved drafts (per the config setting). +- Delete expired template caches. +- Purge any expired pending user accounts (per the config setting). +- Hard delete expired soft-deleted rows (per the config setting). +- Delete stale user session data. +- Delete orphaned search indexes (any indexes belonging to elements that don’t exist anymore). デフォルトでは、すべてのウェブリクエストがガベージコレクションを発動する 100,000 分の 1 のチャンスを持っています。それは を上書きすることによって `config/app.php` から設定できます。 From a043ab8660e315be4de3107fa5f8fc2162cafebe Mon Sep 17 00:00:00 2001 From: Brad Bell Date: Fri, 12 Jun 2020 17:32:41 -0700 Subject: [PATCH 038/245] New translations globals.md (Japanese) --- ja/globals.md | 27 +++++++++++++++++++++------ 1 file changed, 21 insertions(+), 6 deletions(-) diff --git a/ja/globals.md b/ja/globals.md index 7c4fe37a5d9..8dbebe30189 100644 --- a/ja/globals.md +++ b/ja/globals.md @@ -1,12 +1,12 @@ # グローバル -グローバルは、テンプレート全体で包括的に利用可能なコンテンツを保存できます。これは、コントロールパネル経由でエントリではないコンテンツを簡単に編集できるようにする便利な方法です。 +Globals store content that is available globally throughout your templates. They're a convenient way to make non-Entry content easily editable via the control panel. Craft はグローバル設定内でグローバルを整理します。それぞれのグローバル設定は、存在するすべてのフィールドや新しいフィールドを利用する独自の[フィールドレイアウト](fields.md#field-layouts)を持ちます。 グローバル設定を作るには、「設定 > グローバル」に移動します。 -少なくとも1つのグローバル設定があれば、Craft はコントロールパネルのメインナビゲーションに「グローバル」項目を追加します。これをクリックすると、サイドバーにすべてのグローバル設定のリスト、メインコンテンツエリアに選択されたグローバル設定に関連するすべてのフィールドが表示されたページに移動します。 +If you have at least one Global Set, Craft will add a new “Globals” item added to the control panel primary navigation. Clicking on this will take you to a page that lists all of your Global Sets in a sidebar, as well as all of the fields associated with the selected Global Set in the main content area. ::: tip [エントリ](sections-and-entries.md#entries)とは異なり、特定の URL と関連付けられていないグローバル設定では、ライブプレビュー機能がありません。 @@ -24,12 +24,27 @@ Craft はグローバル設定内でグローバルを整理します。それ カスタムフィールド以外で利用できる追加のグローバル設定のプロパティについては、リファレンスの を参照してください。 +### Manually Loading Global Sets + +In some special situations, like within email templates, Global Sets won’t be available by default. Any Global Set may still be loaded manually. The above example could be loaded with `getSetByHandle()`: + +::: code +```twig +{% set companyInfo = craft.globals().getSetByHandle('companyInfo') %} +``` +```php +$companyInfo = \Craft::$app->getGlobals()->getSetByHandle('companyInfo'); +``` +::: + +More details are available in the [Globals service class documentation](api:craft\services\Globals). + ## マルチサイトでのグローバル設定 -Craft でマルチサイトを運用している場合、グローバル設定はすべてのサイトで利用可能です。しかしながら、必要に応じていくつかのフィールドを空のままにするなど、それぞれの設定値をサイトごとにセットできます。 +If you run multiple sites with Craft, Global Sets are available in all sites. However, you can set the values in those sets on a per site basis, even leaving some fields blank, if desired. -そのためには、グローバルセットのフィールドを編集し、それぞれの「翻訳方法」設定で「各サイトに対して翻訳」をセットします。 +To do that, edit the global set’s fields, and make sure that their “Translation Method” settings are set to “Translate for each site”. -グローバル設定を表示中にサイトを切り替えるには、コントロールパネルのグローバル設定ページの左上にあるドロップダウンメニューを使用します。 +To toggle between sites while viewing Global Sets, use the drop-down menu at the top left of the Global Sets page in the control panel. -![グローバル内のサイトの切り替え](./images/globals-multisite-nav.png) +![Toggling between sites in Globals](./images/globals-multisite-nav.png) From bfce78944b9e8634e52066d596049237970fe0da Mon Sep 17 00:00:00 2001 From: Brad Bell Date: Fri, 12 Jun 2020 17:32:44 -0700 Subject: [PATCH 039/245] New translations graphql.md (French) --- fr/graphql.md | 1768 ++++++++++++++++++++----------------------------- 1 file changed, 722 insertions(+), 1046 deletions(-) diff --git a/fr/graphql.md b/fr/graphql.md index 44876f6a59f..7197987fee6 100644 --- a/fr/graphql.md +++ b/fr/graphql.md @@ -2,6 +2,66 @@ Craft Pro provides an autogenerated [GraphQL](https://graphql.org) API for your content, which you can query to pull your content into separate applications, such as single-page apps (SPAs) or static site generators. +[[toc]] + +## An example query and response + +### Query payload + +```graphql +{ + entries (section: "news", limit: 2, orderBy: "dateCreated DESC") { + dateCreated @formatDateTime (format: "Y-m-d") + title + children { + title + } + ... on news_article_Entry { + shortDescription + featuredImage { + url @transform (width: 300, immediately: true) + } + } + } +} +``` + +### The response + +```json +{ + "data": { + "entries": [ + { + "dateCreated": "2019-08-21", + "title": "An important news item", + "children": [], + "shortDescription": "

This is how we roll these days.

", + "featuredImage": [ + { + "url": "/assets/site/_300xAUTO_crop_center-center_none/glasses.jpg" + } + ] + }, + { + "dateCreated": "2019-07-02", + "title": "Dolorem ea eveniet alias", + "children": [ + { + "title": "Child entry" + }, + { + "title": "This is also a child entry" + } + ], + "shortDescription": "Et omnis explicabo iusto eum nobis. Consequatur debitis architecto est exercitationem vitae velit repellendus. Aut consequatur maiores error ducimus ea et. Rem ipsa asperiores eius quas et omnis. Veniam quasi qui repellendus dignissimos et necessitatibus. Aut a illo tempora.", + "featuredImage": [] + } + ] + } +} +``` + ## Getting Started Before you begin, make sure that you are running Craft 3.3 or later, and you’ve got the Pro edition installed. @@ -42,7 +102,7 @@ Craft has two types of schemas: - The **Public Schema** defines which content should be available publicly. - You can also define multiple private schemas, which each have their own secret **Access Token**. -You can manage your schemas from the Control Panel, at GraphQL → Schemas. In addition to defining the scope of each schema, you can also give them expiration dates, or disable them. +You can manage your schemas from the control panel, at GraphQL → Schemas. In addition to defining the scope of each schema, you can also give them expiration dates, or disable them. ::: tip When performing a GraphQL API request, the schema will be determined automatically based on the token that is supplied (if any). See [below](#querying-a-private-schema) to learn how to do that. @@ -50,9 +110,9 @@ When performing a GraphQL API request, the schema will be determined automatical ## Sending API Requests -### Using GraphiQL +### Using the GraphiQL IDE -The easiest way to start exploring your GraphQL API is with the built-in [GraphiQL](https://github.com/graphql/graphiql) IDE, which is available in the Control Panel from GraphQL → Explore. +The easiest way to start exploring your GraphQL API is with the built-in [GraphiQL](https://github.com/graphql/graphiql) IDE, which is available in the control panel from GraphQL → Explore. ![The built-in GraphiQL IDE](./images/graphiql.png) @@ -99,18 +159,6 @@ The GraphQL API can be queried in three ways: If you need to specify any [variables](https://graphql.org/learn/queries/#variables) along with your query, then you must send request as a `POST` request with an `application/json` content type, and include a `variables` key in the JSON body alongside `query`. -```bash -curl \ - --data-urlencode "query={ping}" \ - http://craft32.test/api - # or - curl http://craft32.test/api?query=%7Bping%7D -``` - -#### Querying a Private Schema - -The Public Schema will be used by default. To query against a different [schema](#define-your-schemas), pass its Access Token using an `Authorization` header. - ```bash curl \ -H "Content-Type: application/json" \ @@ -121,1106 +169,734 @@ curl \ http://my-project.test/api ``` -## Query Reference - -::: tip -The actual API features will depend on what your schema allows. -::: - -### The `assets` query -This query is used to query for assets. - -#### The `id` argument -Narrows the query results based on the elements’ IDs. - -#### The `uid` argument -Narrows the query results based on the elements’ UIDs. - -#### The `status` argument -Narrows the query results based on the elements’ statuses. - -#### The `archived` argument -Narrows the query results to only elements that have been archived. - -#### The `trashed` argument -Narrows the query results to only elements that have been soft-deleted. - -#### The `site` argument -Determines which site(s) the elements should be queried in. Defaults to the primary site. - -#### The `siteId` argument -Determines which site(s) the elements should be queried in. Defaults to the primary site. - -#### The `unique` argument -Determines whether only elements with unique IDs should be returned by the query. - -#### The `enabledForSite` argument -Narrows the query results based on whether the elements are enabled in the site they’re being queried in, per the `site` argument. - -#### The `title` argument -Narrows the query results based on the elements’ titles. - -#### The `slug` argument -Narrows the query results based on the elements’ slugs. - -#### The `uri` argument -Narrows the query results based on the elements’ URIs. - -#### The `search` argument -Narrows the query results to only elements that match a search query. - -#### The `ref` argument -Narrows the query results based on a reference string. - -#### The `fixedOrder` argument -Causes the query results to be returned in the order specified by the `id` argument. - -#### The `inReverse` argument -Causes the query results to be returned in reverse order. - -#### The `dateCreated` argument -Narrows the query results based on the elements’ creation dates. - -#### The `dateUpdated` argument -Narrows the query results based on the elements’ last-updated dates. - -#### The `offset` argument -Sets the offset for paginated results. - -#### The `limit` argument -Sets the limit for paginated results. +#### Querying a Private Schema -#### The `orderBy` argument -Sets the field the returned elements should be ordered by +The Public Schema will be used by default. To query against a different [schema](#define-your-schemas), pass its Access Token using an `Authorization` header. -#### The `volumeId` argument -Narrows the query results based on the volumes the assets belong to, per the volumes’ IDs. +```bash +curl \ + -H "Authorization: Bearer xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" \ + -H "Content-Type: application/graphql" \ + -d '{entries{id}}' \ + http://my-project.test/api +``` -#### The `volume` argument -Narrows the query results based on the volumes the assets belong to, per the volumes’ handles. +## Caching -#### The `folderId` argument -Narrows the query results based on the folders the assets belong to, per the folders’ IDs. +All query results are cached, so that repeated queries can yield results faster. The GraphQL result cache does not have a sophisticated ruleset on invalidating the cache - if the site's content or structure changes, the entire cache is invalidated. -#### The `filename` argument -Narrows the query results based on the assets’ filenames. +Craft has GraphQL result caching enabled by default, but it can be disabled with the [enableGraphQlCaching](https://docs.craftcms.com/api/v3/craft-config-generalconfig.html#enablegraphqlcaching) config setting. -#### The `kind` argument -Narrows the query results based on the assets’ file kinds. +## Interface Implementation -#### The `height` argument -Narrows the query results based on the assets’ image heights. +A defined type exists for each specific interface implementation. For example, if a “News” section has “Article” and “Editorial” entry types, in addition to the `EntryInterface` interface type, two additional types would be defined the GraphQL schema, if the token used allows it: `news_article_Entry` and `news_editorial_Entry` types. -#### The `width` argument -Narrows the query results based on the assets’ image widths. +## Query Reference -#### The `size` argument -Narrows the query results based on the assets’ file sizes (in bytes). +::: tip +The actual API features will depend on what your schema allows. +::: -#### The `dateModified` argument -Narrows the query results based on the assets’ files’ last-modified dates. + -#### The `includeSubfolders` argument -Broadens the query results to include assets from any of the subfolders of the folder specified by `folderId`. +### The `assets` query +This query is used to query for assets. +| Argument | Type | Description | +| ------------------- | ----------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `id` | `[QueryArgument]` | Narrows the query results based on the elements’ IDs. | +| `uid` | `[String]` | Narrows the query results based on the elements’ UIDs. | +| `status` | `[String]` | Narrows the query results based on the elements’ statuses. | +| `archived` | `Boolean` | Narrows the query results to only elements that have been archived. | +| `trashed` | `Boolean` | Narrows the query results to only elements that have been soft-deleted. | +| `site` | `[String]` | Determines which site(s) the elements should be queried in. Defaults to the current (requested) site. | +| `siteId` | `String` | Determines which site(s) the elements should be queried in. Defaults to the current (requested) site. | +| `unique` | `Boolean` | Determines whether only elements with unique IDs should be returned by the query. | +| `enabledForSite` | `Boolean` | Narrows the query results based on whether the elements are enabled in the site they’re being queried in, per the `site` argument. | +| `title` | `[String]` | Narrows the query results based on the elements’ titles. | +| `slug` | `[String]` | Narrows the query results based on the elements’ slugs. | +| `uri` | `[String]` | Narrows the query results based on the elements’ URIs. | +| `search` | `String` | Narrows the query results to only elements that match a search query. | +| `relatedTo` | `[Int]` | Narrows the query results to elements that relate to *any* of the provided element IDs. This argument is ignored, if `relatedToAll` is also used. | +| `relatedToAll` | `[Int]` | Narrows the query results to elements that relate to *all* of the provided element IDs. Using this argument will cause `relatedTo` argument to be ignored. | +| `ref` | `[String]` | Narrows the query results based on a reference string. | +| `fixedOrder` | `Boolean` | Causes the query results to be returned in the order specified by the `id` argument. | +| `inReverse` | `Boolean` | Causes the query results to be returned in reverse order. | +| `dateCreated` | `[String]` | Narrows the query results based on the elements’ creation dates. | +| `dateUpdated` | `[String]` | Narrows the query results based on the elements’ last-updated dates. | +| `offset` | `Int` | Sets the offset for paginated results. | +| `limit` | `Int` | Sets the limit for paginated results. | +| `orderBy` | `String` | Sets the field the returned elements should be ordered by | +| `volumeId` | `[QueryArgument]` | Narrows the query results based on the volumes the assets belong to, per the volumes’ IDs. | +| `volume` | `[String]` | Narrows the query results based on the volumes the assets belong to, per the volumes’ handles. | +| `folderId` | `[QueryArgument]` | Narrows the query results based on the folders the assets belong to, per the folders’ IDs. | +| `filename` | `[String]` | Narrows the query results based on the assets’ filenames. | +| `kind` | `[String]` | Narrows the query results based on the assets’ file kinds. | +| `height` | `[String]` | Narrows the query results based on the assets’ image heights. | +| `width` | `[String]` | Narrows the query results based on the assets’ image widths. | +| `size` | `[String]` | Narrows the query results based on the assets’ file sizes (in bytes). | +| `dateModified` | `String` | Narrows the query results based on the assets’ files’ last-modified dates. | +| `includeSubfolders` | `Boolean` | Broadens the query results to include assets from any of the subfolders of the folder specified by `folderId`. | +| `withTransforms` | `[String]` | A list of transform handles to preload. | + +### The `asset` query +This query is used to query for a single asset. +| Argument | Type | Description | +| ------------------- | ----------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `id` | `[QueryArgument]` | Narrows the query results based on the elements’ IDs. | +| `uid` | `[String]` | Narrows the query results based on the elements’ UIDs. | +| `status` | `[String]` | Narrows the query results based on the elements’ statuses. | +| `archived` | `Boolean` | Narrows the query results to only elements that have been archived. | +| `trashed` | `Boolean` | Narrows the query results to only elements that have been soft-deleted. | +| `site` | `[String]` | Determines which site(s) the elements should be queried in. Defaults to the current (requested) site. | +| `siteId` | `String` | Determines which site(s) the elements should be queried in. Defaults to the current (requested) site. | +| `unique` | `Boolean` | Determines whether only elements with unique IDs should be returned by the query. | +| `enabledForSite` | `Boolean` | Narrows the query results based on whether the elements are enabled in the site they’re being queried in, per the `site` argument. | +| `title` | `[String]` | Narrows the query results based on the elements’ titles. | +| `slug` | `[String]` | Narrows the query results based on the elements’ slugs. | +| `uri` | `[String]` | Narrows the query results based on the elements’ URIs. | +| `search` | `String` | Narrows the query results to only elements that match a search query. | +| `relatedTo` | `[Int]` | Narrows the query results to elements that relate to *any* of the provided element IDs. This argument is ignored, if `relatedToAll` is also used. | +| `relatedToAll` | `[Int]` | Narrows the query results to elements that relate to *all* of the provided element IDs. Using this argument will cause `relatedTo` argument to be ignored. | +| `ref` | `[String]` | Narrows the query results based on a reference string. | +| `fixedOrder` | `Boolean` | Causes the query results to be returned in the order specified by the `id` argument. | +| `inReverse` | `Boolean` | Causes the query results to be returned in reverse order. | +| `dateCreated` | `[String]` | Narrows the query results based on the elements’ creation dates. | +| `dateUpdated` | `[String]` | Narrows the query results based on the elements’ last-updated dates. | +| `offset` | `Int` | Sets the offset for paginated results. | +| `limit` | `Int` | Sets the limit for paginated results. | +| `orderBy` | `String` | Sets the field the returned elements should be ordered by | +| `volumeId` | `[QueryArgument]` | Narrows the query results based on the volumes the assets belong to, per the volumes’ IDs. | +| `volume` | `[String]` | Narrows the query results based on the volumes the assets belong to, per the volumes’ handles. | +| `folderId` | `[QueryArgument]` | Narrows the query results based on the folders the assets belong to, per the folders’ IDs. | +| `filename` | `[String]` | Narrows the query results based on the assets’ filenames. | +| `kind` | `[String]` | Narrows the query results based on the assets’ file kinds. | +| `height` | `[String]` | Narrows the query results based on the assets’ image heights. | +| `width` | `[String]` | Narrows the query results based on the assets’ image widths. | +| `size` | `[String]` | Narrows the query results based on the assets’ file sizes (in bytes). | +| `dateModified` | `String` | Narrows the query results based on the assets’ files’ last-modified dates. | +| `includeSubfolders` | `Boolean` | Broadens the query results to include assets from any of the subfolders of the folder specified by `folderId`. | +| `withTransforms` | `[String]` | A list of transform handles to preload. | ### The `entries` query This query is used to query for entries. - -#### The `id` argument -Narrows the query results based on the elements’ IDs. - -#### The `uid` argument -Narrows the query results based on the elements’ UIDs. - -#### The `status` argument -Narrows the query results based on the elements’ statuses. - -#### The `archived` argument -Narrows the query results to only elements that have been archived. - -#### The `trashed` argument -Narrows the query results to only elements that have been soft-deleted. - -#### The `site` argument -Determines which site(s) the elements should be queried in. Defaults to the primary site. - -#### The `siteId` argument -Determines which site(s) the elements should be queried in. Defaults to the primary site. - -#### The `unique` argument -Determines whether only elements with unique IDs should be returned by the query. - -#### The `enabledForSite` argument -Narrows the query results based on whether the elements are enabled in the site they’re being queried in, per the `site` argument. - -#### The `title` argument -Narrows the query results based on the elements’ titles. - -#### The `slug` argument -Narrows the query results based on the elements’ slugs. - -#### The `uri` argument -Narrows the query results based on the elements’ URIs. - -#### The `search` argument -Narrows the query results to only elements that match a search query. - -#### The `ref` argument -Narrows the query results based on a reference string. - -#### The `fixedOrder` argument -Causes the query results to be returned in the order specified by the `id` argument. - -#### The `inReverse` argument -Causes the query results to be returned in reverse order. - -#### The `dateCreated` argument -Narrows the query results based on the elements’ creation dates. - -#### The `dateUpdated` argument -Narrows the query results based on the elements’ last-updated dates. - -#### The `offset` argument -Sets the offset for paginated results. - -#### The `limit` argument -Sets the limit for paginated results. - -#### The `orderBy` argument -Sets the field the returned elements should be ordered by - -#### The `withStructure` argument -Explicitly determines whether the query should join in the structure data. - -#### The `structureId` argument -Determines which structure data should be joined into the query. - -#### The `level` argument -Narrows the query results based on the elements’ level within the structure. - -#### The `hasDescendants` argument -Narrows the query results based on whether the elements have any descendants. - -#### The `ancestorOf` argument -Narrows the query results to only elements that are ancestors of another element. - -#### The `ancestorDist` argument -Narrows the query results to only elements that are up to a certain distance away from the element specified by `ancestorOf`. - -#### The `descendantOf` argument -Narrows the query results to only elements that are descendants of another element. - -#### The `descendantDist` argument -Narrows the query results to only elements that are up to a certain distance away from the element specified by `descendantOf`. - -#### The `leaves` argument -Narrows the query results based on whether the elements are “leaves” (element with no descendants). - -#### The `editable` argument -Whether to only return entries that the user has permission to edit. - -#### The `section` argument -Narrows the query results based on the section handles the entries belong to. - -#### The `sectionId` argument -Narrows the query results based on the sections the entries belong to, per the sections’ IDs. - -#### The `type` argument -Narrows the query results based on the entries’ entry type handles. - -#### The `typeId` argument -Narrows the query results based on the entries’ entry types, per the types’ IDs. - -#### The `authorId` argument -Narrows the query results based on the entries’ authors. - -#### The `authorGroup` argument -Narrows the query results based on the user group the entries’ authors belong to. - -#### The `postDate` argument -Narrows the query results based on the entries’ post dates. - -#### The `before` argument -Narrows the query results to only entries that were posted before a certain date. - -#### The `after` argument -Narrows the query results to only entries that were posted on or after a certain date. - -#### The `expiryDate` argument -Narrows the query results based on the entries’ expiry dates. +| Argument | Type | Description | +| ------------------ | ----------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `id` | `[QueryArgument]` | Narrows the query results based on the elements’ IDs. | +| `uid` | `[String]` | Narrows the query results based on the elements’ UIDs. | +| `status` | `[String]` | Narrows the query results based on the elements’ statuses. | +| `archived` | `Boolean` | Narrows the query results to only elements that have been archived. | +| `trashed` | `Boolean` | Narrows the query results to only elements that have been soft-deleted. | +| `site` | `[String]` | Determines which site(s) the elements should be queried in. Defaults to the current (requested) site. | +| `siteId` | `String` | Determines which site(s) the elements should be queried in. Defaults to the current (requested) site. | +| `unique` | `Boolean` | Determines whether only elements with unique IDs should be returned by the query. | +| `enabledForSite` | `Boolean` | Narrows the query results based on whether the elements are enabled in the site they’re being queried in, per the `site` argument. | +| `title` | `[String]` | Narrows the query results based on the elements’ titles. | +| `slug` | `[String]` | Narrows the query results based on the elements’ slugs. | +| `uri` | `[String]` | Narrows the query results based on the elements’ URIs. | +| `search` | `String` | Narrows the query results to only elements that match a search query. | +| `relatedTo` | `[Int]` | Narrows the query results to elements that relate to *any* of the provided element IDs. This argument is ignored, if `relatedToAll` is also used. | +| `relatedToAll` | `[Int]` | Narrows the query results to elements that relate to *all* of the provided element IDs. Using this argument will cause `relatedTo` argument to be ignored. | +| `ref` | `[String]` | Narrows the query results based on a reference string. | +| `fixedOrder` | `Boolean` | Causes the query results to be returned in the order specified by the `id` argument. | +| `inReverse` | `Boolean` | Causes the query results to be returned in reverse order. | +| `dateCreated` | `[String]` | Narrows the query results based on the elements’ creation dates. | +| `dateUpdated` | `[String]` | Narrows the query results based on the elements’ last-updated dates. | +| `offset` | `Int` | Sets the offset for paginated results. | +| `limit` | `Int` | Sets the limit for paginated results. | +| `orderBy` | `String` | Sets the field the returned elements should be ordered by | +| `withStructure` | `Boolean` | Explicitly determines whether the query should join in the structure data. | +| `structureId` | `Int` | Determines which structure data should be joined into the query. | +| `level` | `Int` | Narrows the query results based on the elements’ level within the structure. | +| `hasDescendants` | `Boolean` | Narrows the query results based on whether the elements have any descendants. | +| `ancestorOf` | `Int` | Narrows the query results to only elements that are ancestors of another element. | +| `ancestorDist` | `Int` | Narrows the query results to only elements that are up to a certain distance away from the element specified by `ancestorOf`. | +| `descendantOf` | `Int` | Narrows the query results to only elements that are descendants of another element. | +| `descendantDist` | `Int` | Narrows the query results to only elements that are up to a certain distance away from the element specified by `descendantOf`. | +| `leaves` | `Boolean` | Narrows the query results based on whether the elements are “leaves” (element with no descendants). | +| `nextSiblingOf` | `Int` | Narrows the query results to only the entry that comes immediately after another element. | +| `prevSiblingOf` | `Int` | Narrows the query results to only the entry that comes immediately before another element. | +| `positionedAfter` | `Int` | Narrows the query results to only entries that are positioned after another element. | +| `positionedBefore` | `Int` | Narrows the query results to only entries that are positioned before another element. | +| `editable` | `Boolean` | Whether to only return entries that the user has permission to edit. | +| `section` | `[String]` | Narrows the query results based on the section handles the entries belong to. | +| `sectionId` | `[QueryArgument]` | Narrows the query results based on the sections the entries belong to, per the sections’ IDs. | +| `type` | `[String]` | Narrows the query results based on the entries’ entry type handles. | +| `typeId` | `[QueryArgument]` | Narrows the query results based on the entries’ entry types, per the types’ IDs. | +| `authorId` | `[QueryArgument]` | Narrows the query results based on the entries’ authors. | +| `authorGroup` | `[String]` | Narrows the query results based on the user group the entries’ authors belong to. | +| `authorGroupId` | `[QueryArgument]` | Narrows the query results based on the user group the entries’ authors belong to, per the groups’ IDs. | +| `postDate` | `[String]` | Narrows the query results based on the entries’ post dates. | +| `before` | `String` | Narrows the query results to only entries that were posted before a certain date. | +| `after` | `String` | Narrows the query results to only entries that were posted on or after a certain date. | +| `expiryDate` | `[String]` | Narrows the query results based on the entries’ expiry dates. | + +### The `entry` query +This query is used to query for a single entry. +| Argument | Type | Description | +| ------------------ | ----------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `id` | `[QueryArgument]` | Narrows the query results based on the elements’ IDs. | +| `uid` | `[String]` | Narrows the query results based on the elements’ UIDs. | +| `status` | `[String]` | Narrows the query results based on the elements’ statuses. | +| `archived` | `Boolean` | Narrows the query results to only elements that have been archived. | +| `trashed` | `Boolean` | Narrows the query results to only elements that have been soft-deleted. | +| `site` | `[String]` | Determines which site(s) the elements should be queried in. Defaults to the current (requested) site. | +| `siteId` | `String` | Determines which site(s) the elements should be queried in. Defaults to the current (requested) site. | +| `unique` | `Boolean` | Determines whether only elements with unique IDs should be returned by the query. | +| `enabledForSite` | `Boolean` | Narrows the query results based on whether the elements are enabled in the site they’re being queried in, per the `site` argument. | +| `title` | `[String]` | Narrows the query results based on the elements’ titles. | +| `slug` | `[String]` | Narrows the query results based on the elements’ slugs. | +| `uri` | `[String]` | Narrows the query results based on the elements’ URIs. | +| `search` | `String` | Narrows the query results to only elements that match a search query. | +| `relatedTo` | `[Int]` | Narrows the query results to elements that relate to *any* of the provided element IDs. This argument is ignored, if `relatedToAll` is also used. | +| `relatedToAll` | `[Int]` | Narrows the query results to elements that relate to *all* of the provided element IDs. Using this argument will cause `relatedTo` argument to be ignored. | +| `ref` | `[String]` | Narrows the query results based on a reference string. | +| `fixedOrder` | `Boolean` | Causes the query results to be returned in the order specified by the `id` argument. | +| `inReverse` | `Boolean` | Causes the query results to be returned in reverse order. | +| `dateCreated` | `[String]` | Narrows the query results based on the elements’ creation dates. | +| `dateUpdated` | `[String]` | Narrows the query results based on the elements’ last-updated dates. | +| `offset` | `Int` | Sets the offset for paginated results. | +| `limit` | `Int` | Sets the limit for paginated results. | +| `orderBy` | `String` | Sets the field the returned elements should be ordered by | +| `withStructure` | `Boolean` | Explicitly determines whether the query should join in the structure data. | +| `structureId` | `Int` | Determines which structure data should be joined into the query. | +| `level` | `Int` | Narrows the query results based on the elements’ level within the structure. | +| `hasDescendants` | `Boolean` | Narrows the query results based on whether the elements have any descendants. | +| `ancestorOf` | `Int` | Narrows the query results to only elements that are ancestors of another element. | +| `ancestorDist` | `Int` | Narrows the query results to only elements that are up to a certain distance away from the element specified by `ancestorOf`. | +| `descendantOf` | `Int` | Narrows the query results to only elements that are descendants of another element. | +| `descendantDist` | `Int` | Narrows the query results to only elements that are up to a certain distance away from the element specified by `descendantOf`. | +| `leaves` | `Boolean` | Narrows the query results based on whether the elements are “leaves” (element with no descendants). | +| `nextSiblingOf` | `Int` | Narrows the query results to only the entry that comes immediately after another element. | +| `prevSiblingOf` | `Int` | Narrows the query results to only the entry that comes immediately before another element. | +| `positionedAfter` | `Int` | Narrows the query results to only entries that are positioned after another element. | +| `positionedBefore` | `Int` | Narrows the query results to only entries that are positioned before another element. | +| `editable` | `Boolean` | Whether to only return entries that the user has permission to edit. | +| `section` | `[String]` | Narrows the query results based on the section handles the entries belong to. | +| `sectionId` | `[QueryArgument]` | Narrows the query results based on the sections the entries belong to, per the sections’ IDs. | +| `type` | `[String]` | Narrows the query results based on the entries’ entry type handles. | +| `typeId` | `[QueryArgument]` | Narrows the query results based on the entries’ entry types, per the types’ IDs. | +| `authorId` | `[QueryArgument]` | Narrows the query results based on the entries’ authors. | +| `authorGroup` | `[String]` | Narrows the query results based on the user group the entries’ authors belong to. | +| `authorGroupId` | `[QueryArgument]` | Narrows the query results based on the user group the entries’ authors belong to, per the groups’ IDs. | +| `postDate` | `[String]` | Narrows the query results based on the entries’ post dates. | +| `before` | `String` | Narrows the query results to only entries that were posted before a certain date. | +| `after` | `String` | Narrows the query results to only entries that were posted on or after a certain date. | +| `expiryDate` | `[String]` | Narrows the query results based on the entries’ expiry dates. | ### The `globalSets` query This query is used to query for global sets. - -#### The `id` argument -Narrows the query results based on the elements’ IDs. - -#### The `uid` argument -Narrows the query results based on the elements’ UIDs. - -#### The `status` argument -Narrows the query results based on the elements’ statuses. - -#### The `archived` argument -Narrows the query results to only elements that have been archived. - -#### The `trashed` argument -Narrows the query results to only elements that have been soft-deleted. - -#### The `site` argument -Determines which site(s) the elements should be queried in. Defaults to the primary site. - -#### The `siteId` argument -Determines which site(s) the elements should be queried in. Defaults to the primary site. - -#### The `unique` argument -Determines whether only elements with unique IDs should be returned by the query. - -#### The `enabledForSite` argument -Narrows the query results based on whether the elements are enabled in the site they’re being queried in, per the `site` argument. - -#### The `title` argument -Narrows the query results based on the elements’ titles. - -#### The `slug` argument -Narrows the query results based on the elements’ slugs. - -#### The `uri` argument -Narrows the query results based on the elements’ URIs. - -#### The `search` argument -Narrows the query results to only elements that match a search query. - -#### The `ref` argument -Narrows the query results based on a reference string. - -#### The `fixedOrder` argument -Causes the query results to be returned in the order specified by the `id` argument. - -#### The `inReverse` argument -Causes the query results to be returned in reverse order. - -#### The `dateCreated` argument -Narrows the query results based on the elements’ creation dates. - -#### The `dateUpdated` argument -Narrows the query results based on the elements’ last-updated dates. - -#### The `offset` argument -Sets the offset for paginated results. - -#### The `limit` argument -Sets the limit for paginated results. - -#### The `orderBy` argument -Sets the field the returned elements should be ordered by - -#### The `handle` argument -Narrows the query results based on the global sets’ handles. +| Argument | Type | Description | +| ---------------- | ----------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `id` | `[QueryArgument]` | Narrows the query results based on the elements’ IDs. | +| `uid` | `[String]` | Narrows the query results based on the elements’ UIDs. | +| `status` | `[String]` | Narrows the query results based on the elements’ statuses. | +| `archived` | `Boolean` | Narrows the query results to only elements that have been archived. | +| `trashed` | `Boolean` | Narrows the query results to only elements that have been soft-deleted. | +| `site` | `[String]` | Determines which site(s) the elements should be queried in. Defaults to the current (requested) site. | +| `siteId` | `String` | Determines which site(s) the elements should be queried in. Defaults to the current (requested) site. | +| `unique` | `Boolean` | Determines whether only elements with unique IDs should be returned by the query. | +| `enabledForSite` | `Boolean` | Narrows the query results based on whether the elements are enabled in the site they’re being queried in, per the `site` argument. | +| `title` | `[String]` | Narrows the query results based on the elements’ titles. | +| `slug` | `[String]` | Narrows the query results based on the elements’ slugs. | +| `uri` | `[String]` | Narrows the query results based on the elements’ URIs. | +| `search` | `String` | Narrows the query results to only elements that match a search query. | +| `relatedTo` | `[Int]` | Narrows the query results to elements that relate to *any* of the provided element IDs. This argument is ignored, if `relatedToAll` is also used. | +| `relatedToAll` | `[Int]` | Narrows the query results to elements that relate to *all* of the provided element IDs. Using this argument will cause `relatedTo` argument to be ignored. | +| `ref` | `[String]` | Narrows the query results based on a reference string. | +| `fixedOrder` | `Boolean` | Causes the query results to be returned in the order specified by the `id` argument. | +| `inReverse` | `Boolean` | Causes the query results to be returned in reverse order. | +| `dateCreated` | `[String]` | Narrows the query results based on the elements’ creation dates. | +| `dateUpdated` | `[String]` | Narrows the query results based on the elements’ last-updated dates. | +| `offset` | `Int` | Sets the offset for paginated results. | +| `limit` | `Int` | Sets the limit for paginated results. | +| `orderBy` | `String` | Sets the field the returned elements should be ordered by | +| `handle` | `[String]` | Narrows the query results based on the global sets’ handles. | + +### The `globalSet` query +This query is used to query for a single global set. +| Argument | Type | Description | +| ---------------- | ----------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `id` | `[QueryArgument]` | Narrows the query results based on the elements’ IDs. | +| `uid` | `[String]` | Narrows the query results based on the elements’ UIDs. | +| `status` | `[String]` | Narrows the query results based on the elements’ statuses. | +| `archived` | `Boolean` | Narrows the query results to only elements that have been archived. | +| `trashed` | `Boolean` | Narrows the query results to only elements that have been soft-deleted. | +| `site` | `[String]` | Determines which site(s) the elements should be queried in. Defaults to the current (requested) site. | +| `siteId` | `String` | Determines which site(s) the elements should be queried in. Defaults to the current (requested) site. | +| `unique` | `Boolean` | Determines whether only elements with unique IDs should be returned by the query. | +| `enabledForSite` | `Boolean` | Narrows the query results based on whether the elements are enabled in the site they’re being queried in, per the `site` argument. | +| `title` | `[String]` | Narrows the query results based on the elements’ titles. | +| `slug` | `[String]` | Narrows the query results based on the elements’ slugs. | +| `uri` | `[String]` | Narrows the query results based on the elements’ URIs. | +| `search` | `String` | Narrows the query results to only elements that match a search query. | +| `relatedTo` | `[Int]` | Narrows the query results to elements that relate to *any* of the provided element IDs. This argument is ignored, if `relatedToAll` is also used. | +| `relatedToAll` | `[Int]` | Narrows the query results to elements that relate to *all* of the provided element IDs. Using this argument will cause `relatedTo` argument to be ignored. | +| `ref` | `[String]` | Narrows the query results based on a reference string. | +| `fixedOrder` | `Boolean` | Causes the query results to be returned in the order specified by the `id` argument. | +| `inReverse` | `Boolean` | Causes the query results to be returned in reverse order. | +| `dateCreated` | `[String]` | Narrows the query results based on the elements’ creation dates. | +| `dateUpdated` | `[String]` | Narrows the query results based on the elements’ last-updated dates. | +| `offset` | `Int` | Sets the offset for paginated results. | +| `limit` | `Int` | Sets the limit for paginated results. | +| `orderBy` | `String` | Sets the field the returned elements should be ordered by | +| `handle` | `[String]` | Narrows the query results based on the global sets’ handles. | ### The `users` query This query is used to query for users. - -#### The `id` argument -Narrows the query results based on the elements’ IDs. - -#### The `uid` argument -Narrows the query results based on the elements’ UIDs. - -#### The `status` argument -Narrows the query results based on the elements’ statuses. - -#### The `archived` argument -Narrows the query results to only elements that have been archived. - -#### The `trashed` argument -Narrows the query results to only elements that have been soft-deleted. - -#### The `site` argument -Determines which site(s) the elements should be queried in. Defaults to the primary site. - -#### The `siteId` argument -Determines which site(s) the elements should be queried in. Defaults to the primary site. - -#### The `unique` argument -Determines whether only elements with unique IDs should be returned by the query. - -#### The `enabledForSite` argument -Narrows the query results based on whether the elements are enabled in the site they’re being queried in, per the `site` argument. - -#### The `title` argument -Narrows the query results based on the elements’ titles. - -#### The `slug` argument -Narrows the query results based on the elements’ slugs. - -#### The `uri` argument -Narrows the query results based on the elements’ URIs. - -#### The `search` argument -Narrows the query results to only elements that match a search query. - -#### The `ref` argument -Narrows the query results based on a reference string. - -#### The `fixedOrder` argument -Causes the query results to be returned in the order specified by the `id` argument. - -#### The `inReverse` argument -Causes the query results to be returned in reverse order. - -#### The `dateCreated` argument -Narrows the query results based on the elements’ creation dates. - -#### The `dateUpdated` argument -Narrows the query results based on the elements’ last-updated dates. - -#### The `offset` argument -Sets the offset for paginated results. - -#### The `limit` argument -Sets the limit for paginated results. - -#### The `orderBy` argument -Sets the field the returned elements should be ordered by - -#### The `email` argument -Narrows the query results based on the users’ email addresses. - -#### The `username` argument -Narrows the query results based on the users’ usernames. - -#### The `firstName` argument -Narrows the query results based on the users’ first names. - -#### The `lastName` argument -Narrows the query results based on the users’ last names. +| Argument | Type | Description | +| ---------------- | ----------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `id` | `[QueryArgument]` | Narrows the query results based on the elements’ IDs. | +| `uid` | `[String]` | Narrows the query results based on the elements’ UIDs. | +| `status` | `[String]` | Narrows the query results based on the elements’ statuses. | +| `archived` | `Boolean` | Narrows the query results to only elements that have been archived. | +| `trashed` | `Boolean` | Narrows the query results to only elements that have been soft-deleted. | +| `site` | `[String]` | Determines which site(s) the elements should be queried in. Defaults to the current (requested) site. | +| `siteId` | `String` | Determines which site(s) the elements should be queried in. Defaults to the current (requested) site. | +| `unique` | `Boolean` | Determines whether only elements with unique IDs should be returned by the query. | +| `enabledForSite` | `Boolean` | Narrows the query results based on whether the elements are enabled in the site they’re being queried in, per the `site` argument. | +| `title` | `[String]` | Narrows the query results based on the elements’ titles. | +| `slug` | `[String]` | Narrows the query results based on the elements’ slugs. | +| `uri` | `[String]` | Narrows the query results based on the elements’ URIs. | +| `search` | `String` | Narrows the query results to only elements that match a search query. | +| `relatedTo` | `[Int]` | Narrows the query results to elements that relate to *any* of the provided element IDs. This argument is ignored, if `relatedToAll` is also used. | +| `relatedToAll` | `[Int]` | Narrows the query results to elements that relate to *all* of the provided element IDs. Using this argument will cause `relatedTo` argument to be ignored. | +| `ref` | `[String]` | Narrows the query results based on a reference string. | +| `fixedOrder` | `Boolean` | Causes the query results to be returned in the order specified by the `id` argument. | +| `inReverse` | `Boolean` | Causes the query results to be returned in reverse order. | +| `dateCreated` | `[String]` | Narrows the query results based on the elements’ creation dates. | +| `dateUpdated` | `[String]` | Narrows the query results based on the elements’ last-updated dates. | +| `offset` | `Int` | Sets the offset for paginated results. | +| `limit` | `Int` | Sets the limit for paginated results. | +| `orderBy` | `String` | Sets the field the returned elements should be ordered by | +| `email` | `[String]` | Narrows the query results based on the users’ email addresses. | +| `username` | `[String]` | Narrows the query results based on the users’ usernames. | +| `firstName` | `[String]` | Narrows the query results based on the users’ first names. | +| `lastName` | `[String]` | Narrows the query results based on the users’ last names. | +| `groupId` | `[QueryArgument]` | Narrows the query results based on the user group the users belong to, per the groups’ IDs. | +| `group` | `[QueryArgument]` | Narrows the query results based on the user group the users belong to. | + +### The `user` query +This query is used to query for a single user. +| Argument | Type | Description | +| ---------------- | ----------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `id` | `[QueryArgument]` | Narrows the query results based on the elements’ IDs. | +| `uid` | `[String]` | Narrows the query results based on the elements’ UIDs. | +| `status` | `[String]` | Narrows the query results based on the elements’ statuses. | +| `archived` | `Boolean` | Narrows the query results to only elements that have been archived. | +| `trashed` | `Boolean` | Narrows the query results to only elements that have been soft-deleted. | +| `site` | `[String]` | Determines which site(s) the elements should be queried in. Defaults to the current (requested) site. | +| `siteId` | `String` | Determines which site(s) the elements should be queried in. Defaults to the current (requested) site. | +| `unique` | `Boolean` | Determines whether only elements with unique IDs should be returned by the query. | +| `enabledForSite` | `Boolean` | Narrows the query results based on whether the elements are enabled in the site they’re being queried in, per the `site` argument. | +| `title` | `[String]` | Narrows the query results based on the elements’ titles. | +| `slug` | `[String]` | Narrows the query results based on the elements’ slugs. | +| `uri` | `[String]` | Narrows the query results based on the elements’ URIs. | +| `search` | `String` | Narrows the query results to only elements that match a search query. | +| `relatedTo` | `[Int]` | Narrows the query results to elements that relate to *any* of the provided element IDs. This argument is ignored, if `relatedToAll` is also used. | +| `relatedToAll` | `[Int]` | Narrows the query results to elements that relate to *all* of the provided element IDs. Using this argument will cause `relatedTo` argument to be ignored. | +| `ref` | `[String]` | Narrows the query results based on a reference string. | +| `fixedOrder` | `Boolean` | Causes the query results to be returned in the order specified by the `id` argument. | +| `inReverse` | `Boolean` | Causes the query results to be returned in reverse order. | +| `dateCreated` | `[String]` | Narrows the query results based on the elements’ creation dates. | +| `dateUpdated` | `[String]` | Narrows the query results based on the elements’ last-updated dates. | +| `offset` | `Int` | Sets the offset for paginated results. | +| `limit` | `Int` | Sets the limit for paginated results. | +| `orderBy` | `String` | Sets the field the returned elements should be ordered by | +| `email` | `[String]` | Narrows the query results based on the users’ email addresses. | +| `username` | `[String]` | Narrows the query results based on the users’ usernames. | +| `firstName` | `[String]` | Narrows the query results based on the users’ first names. | +| `lastName` | `[String]` | Narrows the query results based on the users’ last names. | +| `groupId` | `[QueryArgument]` | Narrows the query results based on the user group the users belong to, per the groups’ IDs. | +| `group` | `[QueryArgument]` | Narrows the query results based on the user group the users belong to. | ### The `tags` query This query is used to query for tags. - -#### The `id` argument -Narrows the query results based on the elements’ IDs. - -#### The `uid` argument -Narrows the query results based on the elements’ UIDs. - -#### The `status` argument -Narrows the query results based on the elements’ statuses. - -#### The `archived` argument -Narrows the query results to only elements that have been archived. - -#### The `trashed` argument -Narrows the query results to only elements that have been soft-deleted. - -#### The `site` argument -Determines which site(s) the elements should be queried in. Defaults to the primary site. - -#### The `siteId` argument -Determines which site(s) the elements should be queried in. Defaults to the primary site. - -#### The `unique` argument -Determines whether only elements with unique IDs should be returned by the query. - -#### The `enabledForSite` argument -Narrows the query results based on whether the elements are enabled in the site they’re being queried in, per the `site` argument. - -#### The `title` argument -Narrows the query results based on the elements’ titles. - -#### The `slug` argument -Narrows the query results based on the elements’ slugs. - -#### The `uri` argument -Narrows the query results based on the elements’ URIs. - -#### The `search` argument -Narrows the query results to only elements that match a search query. - -#### The `ref` argument -Narrows the query results based on a reference string. - -#### The `fixedOrder` argument -Causes the query results to be returned in the order specified by the `id` argument. - -#### The `inReverse` argument -Causes the query results to be returned in reverse order. - -#### The `dateCreated` argument -Narrows the query results based on the elements’ creation dates. - -#### The `dateUpdated` argument -Narrows the query results based on the elements’ last-updated dates. - -#### The `offset` argument -Sets the offset for paginated results. - -#### The `limit` argument -Sets the limit for paginated results. - -#### The `orderBy` argument -Sets the field the returned elements should be ordered by - -#### The `group` argument -Narrows the query results based on the tag groups the tags belong to per the group’s handles. - -#### The `groupId` argument -Narrows the query results based on the tag groups the tags belong to, per the groups’ IDs. +| Argument | Type | Description | +| ---------------- | ----------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `id` | `[QueryArgument]` | Narrows the query results based on the elements’ IDs. | +| `uid` | `[String]` | Narrows the query results based on the elements’ UIDs. | +| `status` | `[String]` | Narrows the query results based on the elements’ statuses. | +| `archived` | `Boolean` | Narrows the query results to only elements that have been archived. | +| `trashed` | `Boolean` | Narrows the query results to only elements that have been soft-deleted. | +| `site` | `[String]` | Determines which site(s) the elements should be queried in. Defaults to the current (requested) site. | +| `siteId` | `String` | Determines which site(s) the elements should be queried in. Defaults to the current (requested) site. | +| `unique` | `Boolean` | Determines whether only elements with unique IDs should be returned by the query. | +| `enabledForSite` | `Boolean` | Narrows the query results based on whether the elements are enabled in the site they’re being queried in, per the `site` argument. | +| `title` | `[String]` | Narrows the query results based on the elements’ titles. | +| `slug` | `[String]` | Narrows the query results based on the elements’ slugs. | +| `uri` | `[String]` | Narrows the query results based on the elements’ URIs. | +| `search` | `String` | Narrows the query results to only elements that match a search query. | +| `relatedTo` | `[Int]` | Narrows the query results to elements that relate to *any* of the provided element IDs. This argument is ignored, if `relatedToAll` is also used. | +| `relatedToAll` | `[Int]` | Narrows the query results to elements that relate to *all* of the provided element IDs. Using this argument will cause `relatedTo` argument to be ignored. | +| `ref` | `[String]` | Narrows the query results based on a reference string. | +| `fixedOrder` | `Boolean` | Causes the query results to be returned in the order specified by the `id` argument. | +| `inReverse` | `Boolean` | Causes the query results to be returned in reverse order. | +| `dateCreated` | `[String]` | Narrows the query results based on the elements’ creation dates. | +| `dateUpdated` | `[String]` | Narrows the query results based on the elements’ last-updated dates. | +| `offset` | `Int` | Sets the offset for paginated results. | +| `limit` | `Int` | Sets the limit for paginated results. | +| `orderBy` | `String` | Sets the field the returned elements should be ordered by | +| `group` | `[String]` | Narrows the query results based on the tag groups the tags belong to per the group’s handles. | +| `groupId` | `[QueryArgument]` | Narrows the query results based on the tag groups the tags belong to, per the groups’ IDs. | + +### The `tag` query +This query is used to query for a single tag. +| Argument | Type | Description | +| ---------------- | ----------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `id` | `[QueryArgument]` | Narrows the query results based on the elements’ IDs. | +| `uid` | `[String]` | Narrows the query results based on the elements’ UIDs. | +| `status` | `[String]` | Narrows the query results based on the elements’ statuses. | +| `archived` | `Boolean` | Narrows the query results to only elements that have been archived. | +| `trashed` | `Boolean` | Narrows the query results to only elements that have been soft-deleted. | +| `site` | `[String]` | Determines which site(s) the elements should be queried in. Defaults to the current (requested) site. | +| `siteId` | `String` | Determines which site(s) the elements should be queried in. Defaults to the current (requested) site. | +| `unique` | `Boolean` | Determines whether only elements with unique IDs should be returned by the query. | +| `enabledForSite` | `Boolean` | Narrows the query results based on whether the elements are enabled in the site they’re being queried in, per the `site` argument. | +| `title` | `[String]` | Narrows the query results based on the elements’ titles. | +| `slug` | `[String]` | Narrows the query results based on the elements’ slugs. | +| `uri` | `[String]` | Narrows the query results based on the elements’ URIs. | +| `search` | `String` | Narrows the query results to only elements that match a search query. | +| `relatedTo` | `[Int]` | Narrows the query results to elements that relate to *any* of the provided element IDs. This argument is ignored, if `relatedToAll` is also used. | +| `relatedToAll` | `[Int]` | Narrows the query results to elements that relate to *all* of the provided element IDs. Using this argument will cause `relatedTo` argument to be ignored. | +| `ref` | `[String]` | Narrows the query results based on a reference string. | +| `fixedOrder` | `Boolean` | Causes the query results to be returned in the order specified by the `id` argument. | +| `inReverse` | `Boolean` | Causes the query results to be returned in reverse order. | +| `dateCreated` | `[String]` | Narrows the query results based on the elements’ creation dates. | +| `dateUpdated` | `[String]` | Narrows the query results based on the elements’ last-updated dates. | +| `offset` | `Int` | Sets the offset for paginated results. | +| `limit` | `Int` | Sets the limit for paginated results. | +| `orderBy` | `String` | Sets the field the returned elements should be ordered by | +| `group` | `[String]` | Narrows the query results based on the tag groups the tags belong to per the group’s handles. | +| `groupId` | `[QueryArgument]` | Narrows the query results based on the tag groups the tags belong to, per the groups’ IDs. | ### The `categories` query This query is used to query for categories. - -#### The `id` argument -Narrows the query results based on the elements’ IDs. - -#### The `uid` argument -Narrows the query results based on the elements’ UIDs. - -#### The `status` argument -Narrows the query results based on the elements’ statuses. - -#### The `archived` argument -Narrows the query results to only elements that have been archived. - -#### The `trashed` argument -Narrows the query results to only elements that have been soft-deleted. - -#### The `site` argument -Determines which site(s) the elements should be queried in. Defaults to the primary site. - -#### The `siteId` argument -Determines which site(s) the elements should be queried in. Defaults to the primary site. - -#### The `unique` argument -Determines whether only elements with unique IDs should be returned by the query. - -#### The `enabledForSite` argument -Narrows the query results based on whether the elements are enabled in the site they’re being queried in, per the `site` argument. - -#### The `title` argument -Narrows the query results based on the elements’ titles. - -#### The `slug` argument -Narrows the query results based on the elements’ slugs. - -#### The `uri` argument -Narrows the query results based on the elements’ URIs. - -#### The `search` argument -Narrows the query results to only elements that match a search query. - -#### The `ref` argument -Narrows the query results based on a reference string. - -#### The `fixedOrder` argument -Causes the query results to be returned in the order specified by the `id` argument. - -#### The `inReverse` argument -Causes the query results to be returned in reverse order. - -#### The `dateCreated` argument -Narrows the query results based on the elements’ creation dates. - -#### The `dateUpdated` argument -Narrows the query results based on the elements’ last-updated dates. - -#### The `offset` argument -Sets the offset for paginated results. - -#### The `limit` argument -Sets the limit for paginated results. - -#### The `orderBy` argument -Sets the field the returned elements should be ordered by - -#### The `withStructure` argument -Explicitly determines whether the query should join in the structure data. - -#### The `structureId` argument -Determines which structure data should be joined into the query. - -#### The `level` argument -Narrows the query results based on the elements’ level within the structure. - -#### The `hasDescendants` argument -Narrows the query results based on whether the elements have any descendants. - -#### The `ancestorOf` argument -Narrows the query results to only elements that are ancestors of another element. - -#### The `ancestorDist` argument -Narrows the query results to only elements that are up to a certain distance away from the element specified by `ancestorOf`. - -#### The `descendantOf` argument -Narrows the query results to only elements that are descendants of another element. - -#### The `descendantDist` argument -Narrows the query results to only elements that are up to a certain distance away from the element specified by `descendantOf`. - -#### The `leaves` argument -Narrows the query results based on whether the elements are “leaves” (element with no descendants). - -#### The `editable` argument -Whether to only return categories that the user has permission to edit. - -#### The `group` argument -Narrows the query results based on the category groups the categories belong to per the group’s handles. - -#### The `groupId` argument -Narrows the query results based on the category groups the categories belong to, per the groups’ IDs. +| Argument | Type | Description | +| ------------------ | ----------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `id` | `[QueryArgument]` | Narrows the query results based on the elements’ IDs. | +| `uid` | `[String]` | Narrows the query results based on the elements’ UIDs. | +| `status` | `[String]` | Narrows the query results based on the elements’ statuses. | +| `archived` | `Boolean` | Narrows the query results to only elements that have been archived. | +| `trashed` | `Boolean` | Narrows the query results to only elements that have been soft-deleted. | +| `site` | `[String]` | Determines which site(s) the elements should be queried in. Defaults to the current (requested) site. | +| `siteId` | `String` | Determines which site(s) the elements should be queried in. Defaults to the current (requested) site. | +| `unique` | `Boolean` | Determines whether only elements with unique IDs should be returned by the query. | +| `enabledForSite` | `Boolean` | Narrows the query results based on whether the elements are enabled in the site they’re being queried in, per the `site` argument. | +| `title` | `[String]` | Narrows the query results based on the elements’ titles. | +| `slug` | `[String]` | Narrows the query results based on the elements’ slugs. | +| `uri` | `[String]` | Narrows the query results based on the elements’ URIs. | +| `search` | `String` | Narrows the query results to only elements that match a search query. | +| `relatedTo` | `[Int]` | Narrows the query results to elements that relate to *any* of the provided element IDs. This argument is ignored, if `relatedToAll` is also used. | +| `relatedToAll` | `[Int]` | Narrows the query results to elements that relate to *all* of the provided element IDs. Using this argument will cause `relatedTo` argument to be ignored. | +| `ref` | `[String]` | Narrows the query results based on a reference string. | +| `fixedOrder` | `Boolean` | Causes the query results to be returned in the order specified by the `id` argument. | +| `inReverse` | `Boolean` | Causes the query results to be returned in reverse order. | +| `dateCreated` | `[String]` | Narrows the query results based on the elements’ creation dates. | +| `dateUpdated` | `[String]` | Narrows the query results based on the elements’ last-updated dates. | +| `offset` | `Int` | Sets the offset for paginated results. | +| `limit` | `Int` | Sets the limit for paginated results. | +| `orderBy` | `String` | Sets the field the returned elements should be ordered by | +| `withStructure` | `Boolean` | Explicitly determines whether the query should join in the structure data. | +| `structureId` | `Int` | Determines which structure data should be joined into the query. | +| `level` | `Int` | Narrows the query results based on the elements’ level within the structure. | +| `hasDescendants` | `Boolean` | Narrows the query results based on whether the elements have any descendants. | +| `ancestorOf` | `Int` | Narrows the query results to only elements that are ancestors of another element. | +| `ancestorDist` | `Int` | Narrows the query results to only elements that are up to a certain distance away from the element specified by `ancestorOf`. | +| `descendantOf` | `Int` | Narrows the query results to only elements that are descendants of another element. | +| `descendantDist` | `Int` | Narrows the query results to only elements that are up to a certain distance away from the element specified by `descendantOf`. | +| `leaves` | `Boolean` | Narrows the query results based on whether the elements are “leaves” (element with no descendants). | +| `nextSiblingOf` | `Int` | Narrows the query results to only the entry that comes immediately after another element. | +| `prevSiblingOf` | `Int` | Narrows the query results to only the entry that comes immediately before another element. | +| `positionedAfter` | `Int` | Narrows the query results to only entries that are positioned after another element. | +| `positionedBefore` | `Int` | Narrows the query results to only entries that are positioned before another element. | +| `editable` | `Boolean` | Whether to only return categories that the user has permission to edit. | +| `group` | `[String]` | Narrows the query results based on the category groups the categories belong to per the group’s handles. | +| `groupId` | `[QueryArgument]` | Narrows the query results based on the category groups the categories belong to, per the groups’ IDs. | + +### The `category` query +This query is used to query for a single category. +| Argument | Type | Description | +| ------------------ | ----------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `id` | `[QueryArgument]` | Narrows the query results based on the elements’ IDs. | +| `uid` | `[String]` | Narrows the query results based on the elements’ UIDs. | +| `status` | `[String]` | Narrows the query results based on the elements’ statuses. | +| `archived` | `Boolean` | Narrows the query results to only elements that have been archived. | +| `trashed` | `Boolean` | Narrows the query results to only elements that have been soft-deleted. | +| `site` | `[String]` | Determines which site(s) the elements should be queried in. Defaults to the current (requested) site. | +| `siteId` | `String` | Determines which site(s) the elements should be queried in. Defaults to the current (requested) site. | +| `unique` | `Boolean` | Determines whether only elements with unique IDs should be returned by the query. | +| `enabledForSite` | `Boolean` | Narrows the query results based on whether the elements are enabled in the site they’re being queried in, per the `site` argument. | +| `title` | `[String]` | Narrows the query results based on the elements’ titles. | +| `slug` | `[String]` | Narrows the query results based on the elements’ slugs. | +| `uri` | `[String]` | Narrows the query results based on the elements’ URIs. | +| `search` | `String` | Narrows the query results to only elements that match a search query. | +| `relatedTo` | `[Int]` | Narrows the query results to elements that relate to *any* of the provided element IDs. This argument is ignored, if `relatedToAll` is also used. | +| `relatedToAll` | `[Int]` | Narrows the query results to elements that relate to *all* of the provided element IDs. Using this argument will cause `relatedTo` argument to be ignored. | +| `ref` | `[String]` | Narrows the query results based on a reference string. | +| `fixedOrder` | `Boolean` | Causes the query results to be returned in the order specified by the `id` argument. | +| `inReverse` | `Boolean` | Causes the query results to be returned in reverse order. | +| `dateCreated` | `[String]` | Narrows the query results based on the elements’ creation dates. | +| `dateUpdated` | `[String]` | Narrows the query results based on the elements’ last-updated dates. | +| `offset` | `Int` | Sets the offset for paginated results. | +| `limit` | `Int` | Sets the limit for paginated results. | +| `orderBy` | `String` | Sets the field the returned elements should be ordered by | +| `withStructure` | `Boolean` | Explicitly determines whether the query should join in the structure data. | +| `structureId` | `Int` | Determines which structure data should be joined into the query. | +| `level` | `Int` | Narrows the query results based on the elements’ level within the structure. | +| `hasDescendants` | `Boolean` | Narrows the query results based on whether the elements have any descendants. | +| `ancestorOf` | `Int` | Narrows the query results to only elements that are ancestors of another element. | +| `ancestorDist` | `Int` | Narrows the query results to only elements that are up to a certain distance away from the element specified by `ancestorOf`. | +| `descendantOf` | `Int` | Narrows the query results to only elements that are descendants of another element. | +| `descendantDist` | `Int` | Narrows the query results to only elements that are up to a certain distance away from the element specified by `descendantOf`. | +| `leaves` | `Boolean` | Narrows the query results based on whether the elements are “leaves” (element with no descendants). | +| `nextSiblingOf` | `Int` | Narrows the query results to only the entry that comes immediately after another element. | +| `prevSiblingOf` | `Int` | Narrows the query results to only the entry that comes immediately before another element. | +| `positionedAfter` | `Int` | Narrows the query results to only entries that are positioned after another element. | +| `positionedBefore` | `Int` | Narrows the query results to only entries that are positioned before another element. | +| `editable` | `Boolean` | Whether to only return categories that the user has permission to edit. | +| `group` | `[String]` | Narrows the query results based on the category groups the categories belong to per the group’s handles. | +| `groupId` | `[QueryArgument]` | Narrows the query results based on the category groups the categories belong to, per the groups’ IDs. | + + ## List of available directives Directives are not regulated by permissions and they affect how the returned data is displayed. + + ### The `formatDateTime` directive This directive allows for formatting any date to the desired format. It can be applied to all fields, but changes anything only when applied to a DateTime field. +| Argument | Type | Description | +| ---------- | -------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `format` | `String` | This specifies the format to use. It defaults to the [Atom date time format](https://www.php.net/manual/en/class.datetimeinterface.php#datetime.constants.atom]). | +| `timezone` | `String` | The full name of the timezone, defaults to UTC. (E.g., America/New_York) | -#### The `format` argument -This specifies the format to use. It defaults to the [Atom date time format](https://www.php.net/manual/en/class.datetimeinterface.php#datetime.constants.atom]). - -#### The `timezone` argument -The full name of the timezone, defaults to UTC. (E.g., America/New_York) ### The `transform` directive This directive is used to return a URL for an [asset tranform](https://docs.craftcms.com/v3/image-transforms.html). It accepts the same arguments you would use for a transform in Craft and adds the `immediately` argument. +| Argument | Type | Description | +| ------------- | --------- | ---------------------------------------------------------------------------------------------------------------- | +| `handle` | `String` | The handle of the named transform to use. | +| `transform` | `String` | The handle of the named transform to use. | +| `width` | `Int` | Width for the generated transform | +| `height` | `Int` | Height for the generated transform | +| `mode` | `String` | The mode to use for the generated transform. | +| `position` | `String` | The position to use when cropping, if no focal point specified. | +| `interlace` | `String` | The interlace mode to use for the transform | +| `quality` | `Int` | The quality of the transform | +| `format` | `String` | The format to use for the transform | +| `immediately` | `Boolean` | Whether the transform should be generated immediately or only when the image is requested used the generated URL | -#### The `handle` argument -The handle of the named transform to use. - -#### The `width` argument -Width for the generated transform - -#### The `height` argument -Height for the generated transform - -#### The `mode` argument -The mode to use for the generated transform. - -#### The `position` argument -The position to use when cropping, if no focal point specified. - -#### The `interlace` argument -The interlace mode to use for the transform - -#### The `quality` argument -The quality of the transform - -#### The `format` argument -The format to use for the transform - -#### The `immediately` argument -Whether the transform should be generated immediately or only when the image is requested used the generated URL ### The `markdown` directive Parses the passed field value as Markdown. +| Argument | Type | Description | +| -------- | -------- | ------------------------------------------------------------------------------------------------------------------------------- | +| `flavor` | `String` | The “flavor” of Markdown the input should be interpreted with. Accepts the same arguments as yii\helpers\Markdown::process(). | -#### The `flavor` argument -The “flavor” of Markdown the input should be interpreted with. Accepts the same arguments as yii\helpers\Markdown::process(). + ## Pre-defined interfaces Craft defines several interfaces to be implemented by the different GraphQL types. + + ### The `AssetInterface` interface This is the interface implemented by all assets. +| Field | Type | Description | +| --------------- | ---------- | --------------------------------------------------------------------------------------------- | +| `id` | `ID` | The id of the entity | +| `uid` | `String` | The uid of the entity | +| `_count` | `Int` | Return a number of related elements for a field. | +| `title` | `String` | The element’s title. | +| `slug` | `String` | The element’s slug. | +| `uri` | `String` | The element’s URI. | +| `enabled` | `Boolean` | Whether the element is enabled or not. | +| `archived` | `Boolean` | Whether the element is archived or not. | +| `siteId` | `Int` | The ID of the site the element is associated with. | +| `searchScore` | `String` | The element’s search score, if the `search` parameter was used when querying for the element. | +| `trashed` | `Boolean` | Whether the element has been soft-deleted or not. | +| `status` | `String` | The element's status. | +| `dateCreated` | `DateTime` | The date the element was created. | +| `dateUpdated` | `DateTime` | The date the element was last updated. | +| `volumeId` | `Int` | The ID of the volume that the asset belongs to. | +| `folderId` | `Int` | The ID of the folder that the asset belongs to. | +| `filename` | `String` | The filename of the asset file. | +| `extension` | `String` | The file extension for the asset file. | +| `hasFocalPoint` | `Boolean` | Whether a user-defined focal point is set on the asset. | +| `focalPoint` | `[Float]` | The focal point represented as an array with `x` and `y` keys, or null if it's not an image. | +| `kind` | `String` | The file kind. | +| `size` | `String` | The file size in bytes. | +| `height` | `Int` | The height in pixels or null if it's not an image. | +| `width` | `Int` | The width in pixels or null if it's not an image. | +| `img` | `String` | An `` tag based on this asset. | +| `url` | `String` | The full URL of the asset. This field accepts the same fields as the `transform` directive. | +| `mimeType` | `String` | The file’s MIME type, if it can be determined. | +| `path` | `String` | The asset's path in the volume. | +| `dateModified` | `DateTime` | The date the asset file was last modified. | -#### The `id` field -The id of the entity - -#### The `uid` field -The uid of the entity - -#### The `title` field -The element’s title. - -#### The `slug` field -The element’s slug. - -#### The `uri` field -The element’s URI. - -#### The `enabled` field -Whether the element is enabled or not. - -#### The `archived` field -Whether the element is archived or not. - -#### The `siteId` field -The ID of the site the element is associated with. - -#### The `searchScore` field -The element’s search score, if the `search` parameter was used when querying for the element. - -#### The `trashed` field -Whether the element has been soft-deleted or not. - -#### The `status` field -The element's status. - -#### The `dateCreated` field -The date the element was created. - -#### The `dateUpdated` field -The date the element was last updated. - -#### The `volumeId` field -The ID of the volume that the asset belongs to. - -#### The `folderId` field -The ID of the folder that the asset belongs to. - -#### The `filename` field -The filename of the asset file. - -#### The `extension` field -The file extension for the asset file. - -#### The `hasFocalPoint` field -Whether a user-defined focal point is set on the asset. - -#### The `focalPoint` field -The focal point represented as an array with `x` and `y` keys, or null if it's not an image. - -#### The `kind` field -The file kind. - -#### The `size` field -The file size in bytes. - -#### The `height` field -The height in pixels or null if it's not an image. - -#### The `width` field -The width in pixels or null if it's not an image. - -#### The `img` field -An `` tag based on this asset. - -#### The `url` field -The full URL of the asset. This field accepts the same fields as the `transform` directive. - -#### The `mimeType` field -The file’s MIME type, if it can be determined. - -#### The `path` field -The asset's path in the volume. - -#### The `dateModified` field -The date the asset file was last modified. ### The `EntryInterface` interface This is the interface implemented by all entries. +| Field | Type | Description | +| --------------- | ------------------ | ------------------------------------------------------------------------------------------------------- | +| `id` | `ID` | The id of the entity | +| `uid` | `String` | The uid of the entity | +| `_count` | `Int` | Return a number of related elements for a field. | +| `title` | `String` | The element’s title. | +| `slug` | `String` | The element’s slug. | +| `uri` | `String` | The element’s URI. | +| `enabled` | `Boolean` | Whether the element is enabled or not. | +| `archived` | `Boolean` | Whether the element is archived or not. | +| `siteId` | `Int` | The ID of the site the element is associated with. | +| `searchScore` | `String` | The element’s search score, if the `search` parameter was used when querying for the element. | +| `trashed` | `Boolean` | Whether the element has been soft-deleted or not. | +| `status` | `String` | The element's status. | +| `dateCreated` | `DateTime` | The date the element was created. | +| `dateUpdated` | `DateTime` | The date the element was last updated. | +| `lft` | `Int` | The element’s left position within its structure. | +| `rgt` | `Int` | The element’s right position within its structure. | +| `level` | `Int` | The element’s level within its structure | +| `root` | `Int` | The element’s structure’s root ID | +| `structureId` | `Int` | The element’s structure ID. | +| `sectionId` | `Int` | The ID of the section that contains the entry. | +| `sectionHandle` | `String` | The handle of the section that contains the entry. | +| `typeId` | `Int` | The ID of the entry type that contains the entry. | +| `typeHandle` | `String` | The handle of the entry type that contains the entry. | +| `postDate` | `DateTime` | The entry's post date. | +| `expiryDate` | `DateTime` | The expiry date of the entry. | +| `children` | `[EntryInterface]` | The entry’s children, if the section is a structure. Accepts the same arguments as the `entries` query. | +| `parent` | `EntryInterface` | The entry’s parent, if the section is a structure. | +| `url` | `String` | The element’s full URL | -#### The `id` field -The id of the entity - -#### The `uid` field -The uid of the entity - -#### The `title` field -The element’s title. - -#### The `slug` field -The element’s slug. - -#### The `uri` field -The element’s URI. - -#### The `enabled` field -Whether the element is enabled or not. - -#### The `archived` field -Whether the element is archived or not. - -#### The `siteId` field -The ID of the site the element is associated with. - -#### The `searchScore` field -The element’s search score, if the `search` parameter was used when querying for the element. - -#### The `trashed` field -Whether the element has been soft-deleted or not. - -#### The `status` field -The element's status. - -#### The `dateCreated` field -The date the element was created. - -#### The `dateUpdated` field -The date the element was last updated. - -#### The `lft` field -The element’s left position within its structure. - -#### The `rgt` field -The element’s right position within its structure. - -#### The `level` field -The element’s level within its structure - -#### The `root` field -The element’s structure’s root ID - -#### The `structureId` field -The element’s structure ID. - -#### The `sectionId` field -The ID of the section that contains the entry. - -#### The `sectionHandle` field -The handle of the section that contains the entry. - -#### The `typeId` field -The ID of the entry type that contains the entry. - -#### The `typeHandle` field -The handle of the entry type that contains the entry. - -#### The `authorId` field -The ID of the author of this entry. - -#### The `author` field -The entry's author. - -#### The `postDate` field -The entry's post date. - -#### The `expiryDate` field -The expiry date of the entry. - -#### The `children` field -The entry’s children, if the section is a structure. Accepts the same arguments as the `entries` query. - -#### The `parent` field -The entry’s parent, if the section is a structure. ### The `GlobalSetInterface` interface This is the interface implemented by all global sets. +| Field | Type | Description | +| ------------- | ---------- | --------------------------------------------------------------------------------------------- | +| `id` | `ID` | The id of the entity | +| `uid` | `String` | The uid of the entity | +| `_count` | `Int` | Return a number of related elements for a field. | +| `title` | `String` | The element’s title. | +| `slug` | `String` | The element’s slug. | +| `uri` | `String` | The element’s URI. | +| `enabled` | `Boolean` | Whether the element is enabled or not. | +| `archived` | `Boolean` | Whether the element is archived or not. | +| `siteId` | `Int` | The ID of the site the element is associated with. | +| `searchScore` | `String` | The element’s search score, if the `search` parameter was used when querying for the element. | +| `trashed` | `Boolean` | Whether the element has been soft-deleted or not. | +| `status` | `String` | The element's status. | +| `dateCreated` | `DateTime` | The date the element was created. | +| `dateUpdated` | `DateTime` | The date the element was last updated. | +| `name` | `String` | The name of the global set. | +| `handle` | `String` | The handle of the global set. | -#### The `id` field -The id of the entity - -#### The `uid` field -The uid of the entity - -#### The `title` field -The element’s title. - -#### The `slug` field -The element’s slug. - -#### The `uri` field -The element’s URI. - -#### The `enabled` field -Whether the element is enabled or not. - -#### The `archived` field -Whether the element is archived or not. - -#### The `siteId` field -The ID of the site the element is associated with. - -#### The `searchScore` field -The element’s search score, if the `search` parameter was used when querying for the element. - -#### The `trashed` field -Whether the element has been soft-deleted or not. - -#### The `status` field -The element's status. - -#### The `dateCreated` field -The date the element was created. - -#### The `dateUpdated` field -The date the element was last updated. - -#### The `name` field -The name of the global set. - -#### The `handle` field -The handle of the global set. ### The `MatrixBlockInterface` interface This is the interface implemented by all matrix blocks. +| Field | Type | Description | +| ------------- | ---------- | --------------------------------------------------------------------------------------------- | +| `id` | `ID` | The id of the entity | +| `uid` | `String` | The uid of the entity | +| `_count` | `Int` | Return a number of related elements for a field. | +| `title` | `String` | The element’s title. | +| `slug` | `String` | The element’s slug. | +| `uri` | `String` | The element’s URI. | +| `enabled` | `Boolean` | Whether the element is enabled or not. | +| `archived` | `Boolean` | Whether the element is archived or not. | +| `siteId` | `Int` | The ID of the site the element is associated with. | +| `searchScore` | `String` | The element’s search score, if the `search` parameter was used when querying for the element. | +| `trashed` | `Boolean` | Whether the element has been soft-deleted or not. | +| `status` | `String` | The element's status. | +| `dateCreated` | `DateTime` | The date the element was created. | +| `dateUpdated` | `DateTime` | The date the element was last updated. | +| `fieldId` | `Int` | The ID of the field that owns the matrix block. | +| `ownerId` | `Int` | The ID of the element that owns the matrix block. | +| `typeId` | `Int` | The ID of the matrix block's type. | +| `typeHandle` | `String` | The handle of the matrix block's type. | +| `sortOrder` | `Int` | The sort order of the matrix block within the owner element field. | -#### The `id` field -The id of the entity - -#### The `uid` field -The uid of the entity - -#### The `title` field -The element’s title. - -#### The `slug` field -The element’s slug. - -#### The `uri` field -The element’s URI. - -#### The `enabled` field -Whether the element is enabled or not. - -#### The `archived` field -Whether the element is archived or not. - -#### The `siteId` field -The ID of the site the element is associated with. - -#### The `searchScore` field -The element’s search score, if the `search` parameter was used when querying for the element. - -#### The `trashed` field -Whether the element has been soft-deleted or not. - -#### The `status` field -The element's status. - -#### The `dateCreated` field -The date the element was created. - -#### The `dateUpdated` field -The date the element was last updated. - -#### The `fieldId` field -The ID of the field that owns the matrix block. - -#### The `ownerId` field -The ID of the element that owns the matrix block. - -#### The `typeId` field -The ID of the matrix block's type. - -#### The `typeHandle` field -The handle of the matrix block's type. - -#### The `sortOrder` field -The sort order of the matrix block within the owner element field. ### The `UserInterface` interface This is the interface implemented by all users. +| Field | Type | Description | +| ------------------- | ---------------- | --------------------------------------------------------------------------------------------- | +| `id` | `ID` | The id of the entity | +| `uid` | `String` | The uid of the entity | +| `_count` | `Int` | Return a number of related elements for a field. | +| `title` | `String` | The element’s title. | +| `slug` | `String` | The element’s slug. | +| `uri` | `String` | The element’s URI. | +| `enabled` | `Boolean` | Whether the element is enabled or not. | +| `archived` | `Boolean` | Whether the element is archived or not. | +| `siteId` | `Int` | The ID of the site the element is associated with. | +| `searchScore` | `String` | The element’s search score, if the `search` parameter was used when querying for the element. | +| `trashed` | `Boolean` | Whether the element has been soft-deleted or not. | +| `status` | `String` | The element's status. | +| `dateCreated` | `DateTime` | The date the element was created. | +| `dateUpdated` | `DateTime` | The date the element was last updated. | +| `photo` | `AssetInterface` | The user's photo. | +| `friendlyName` | `String` | The user's first name or username. | +| `fullName` | `String` | The user's full name. | +| `name` | `String` | The user's full name or username. | +| `preferences` | `String` | The user’s preferences. | +| `preferredLanguage` | `String` | The user’s preferred language. | +| `username` | `String` | The username. | +| `firstName` | `String` | The user's first name. | +| `lastName` | `String` | The user's last name. | +| `email` | `String` | The user's email. | -#### The `id` field -The id of the entity - -#### The `uid` field -The uid of the entity - -#### The `title` field -The element’s title. - -#### The `slug` field -The element’s slug. - -#### The `uri` field -The element’s URI. - -#### The `enabled` field -Whether the element is enabled or not. - -#### The `archived` field -Whether the element is archived or not. - -#### The `siteId` field -The ID of the site the element is associated with. - -#### The `searchScore` field -The element’s search score, if the `search` parameter was used when querying for the element. - -#### The `trashed` field -Whether the element has been soft-deleted or not. - -#### The `status` field -The element's status. - -#### The `dateCreated` field -The date the element was created. - -#### The `dateUpdated` field -The date the element was last updated. - -#### The `friendlyName` field -The user's first name or username. - -#### The `fullName` field -The user's full name. - -#### The `name` field -The user's full name or username. - -#### The `photo` field -The user's photo. - -#### The `preferences` field -The user’s preferences. - -#### The `preferredLanguage` field -The user’s preferred language. - -#### The `username` field -The username. - -#### The `firstName` field -The user's first name. - -#### The `lastName` field -The user's last name. - -#### The `email` field -The user's email. ### The `CategoryInterface` interface This is the interface implemented by all categories. +| Field | Type | Description | +| ------------- | --------------------- | --------------------------------------------------------------------------------------------- | +| `id` | `ID` | The id of the entity | +| `uid` | `String` | The uid of the entity | +| `_count` | `Int` | Return a number of related elements for a field. | +| `title` | `String` | The element’s title. | +| `slug` | `String` | The element’s slug. | +| `uri` | `String` | The element’s URI. | +| `enabled` | `Boolean` | Whether the element is enabled or not. | +| `archived` | `Boolean` | Whether the element is archived or not. | +| `siteId` | `Int` | The ID of the site the element is associated with. | +| `searchScore` | `String` | The element’s search score, if the `search` parameter was used when querying for the element. | +| `trashed` | `Boolean` | Whether the element has been soft-deleted or not. | +| `status` | `String` | The element's status. | +| `dateCreated` | `DateTime` | The date the element was created. | +| `dateUpdated` | `DateTime` | The date the element was last updated. | +| `lft` | `Int` | The element’s left position within its structure. | +| `rgt` | `Int` | The element’s right position within its structure. | +| `level` | `Int` | The element’s level within its structure | +| `root` | `Int` | The element’s structure’s root ID | +| `structureId` | `Int` | The element’s structure ID. | +| `groupId` | `Int` | The ID of the group that contains the category. | +| `groupHandle` | `String` | The handle of the group that contains the category. | +| `children` | `[CategoryInterface]` | The category’s children. | +| `parent` | `CategoryInterface` | The category’s parent. | +| `url` | `String` | The element’s full URL | -#### The `id` field -The id of the entity - -#### The `uid` field -The uid of the entity - -#### The `title` field -The element’s title. - -#### The `slug` field -The element’s slug. - -#### The `uri` field -The element’s URI. - -#### The `enabled` field -Whether the element is enabled or not. - -#### The `archived` field -Whether the element is archived or not. - -#### The `siteId` field -The ID of the site the element is associated with. - -#### The `searchScore` field -The element’s search score, if the `search` parameter was used when querying for the element. - -#### The `trashed` field -Whether the element has been soft-deleted or not. - -#### The `status` field -The element's status. - -#### The `dateCreated` field -The date the element was created. - -#### The `dateUpdated` field -The date the element was last updated. - -#### The `lft` field -The element’s left position within its structure. - -#### The `rgt` field -The element’s right position within its structure. - -#### The `level` field -The element’s level within its structure - -#### The `root` field -The element’s structure’s root ID - -#### The `structureId` field -The element’s structure ID. - -#### The `groupId` field -The ID of the group that contains the category. - -#### The `groupHandle` field -The handle of the group that contains the category. - -#### The `children` field -The category’s children. - -#### The `parent` field -The category’s parent. ### The `TagInterface` interface This is the interface implemented by all tags. +| Field | Type | Description | +| ------------- | ---------- | --------------------------------------------------------------------------------------------- | +| `id` | `ID` | The id of the entity | +| `uid` | `String` | The uid of the entity | +| `_count` | `Int` | Return a number of related elements for a field. | +| `title` | `String` | The element’s title. | +| `slug` | `String` | The element’s slug. | +| `uri` | `String` | The element’s URI. | +| `enabled` | `Boolean` | Whether the element is enabled or not. | +| `archived` | `Boolean` | Whether the element is archived or not. | +| `siteId` | `Int` | The ID of the site the element is associated with. | +| `searchScore` | `String` | The element’s search score, if the `search` parameter was used when querying for the element. | +| `trashed` | `Boolean` | Whether the element has been soft-deleted or not. | +| `status` | `String` | The element's status. | +| `dateCreated` | `DateTime` | The date the element was created. | +| `dateUpdated` | `DateTime` | The date the element was last updated. | +| `groupId` | `Int` | The ID of the group that contains the tag. | +| `groupHandle` | `String` | The handle of the group that contains the tag. | + + -#### The `id` field -The id of the entity - -#### The `uid` field -The uid of the entity - -#### The `title` field -The element’s title. - -#### The `slug` field -The element’s slug. - -#### The `uri` field -The element’s URI. - -#### The `enabled` field -Whether the element is enabled or not. - -#### The `archived` field -Whether the element is archived or not. - -#### The `siteId` field -The ID of the site the element is associated with. - -#### The `searchScore` field -The element’s search score, if the `search` parameter was used when querying for the element. - -#### The `trashed` field -Whether the element has been soft-deleted or not. - -#### The `status` field -The element's status. - -#### The `dateCreated` field -The date the element was created. - -#### The `dateUpdated` field -The date the element was last updated. - -#### The `groupId` field -The ID of the group that contains the tag. - -#### The `groupHandle` field -The handle of the group that contains the tag. - -## Interface Implementation - -A defined type exists for each specific interface implementation. For example, if a “News” section has “Article” and “Editorial” entry types, in addition to the `EntryInterface` interface type, two additional types would be defined the GraphQL schema, if the token used allows it: `news_article_Entry` and `news_editorial_Entry` types. - -## An example query and response - -### Query payload - -```graphql -curl \ - -H "Authorization: Bearer xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" \ - -H "Content-Type: application/graphql" \ - -d '{entries{id}}' \ - http://my-project.test/api -``` - -### The response - -```json -{ - queryEntries (section: "news", limit: 2, orderBy: "dateCreated DESC"){ - dateCreated @formatDateTime (format: "Y-m-d") - title - children { - title - } - ... on news_article_Entry { - shortDescription - featuredImage { - url @transform (width: 300, immediately: true) - } - } - } -} -``` From 7e1f988e43386ac3bcb9c7185876ddbfb8097704 Mon Sep 17 00:00:00 2001 From: Brad Bell Date: Fri, 12 Jun 2020 17:32:48 -0700 Subject: [PATCH 040/245] New translations graphql.md (Japanese) --- ja/graphql.md | 1770 ++++++++++++++++++++----------------------------- 1 file changed, 723 insertions(+), 1047 deletions(-) diff --git a/ja/graphql.md b/ja/graphql.md index 44876f6a59f..011aa33cc03 100644 --- a/ja/graphql.md +++ b/ja/graphql.md @@ -1,6 +1,66 @@ # GraphQL API -Craft Pro provides an autogenerated [GraphQL](https://graphql.org) API for your content, which you can query to pull your content into separate applications, such as single-page apps (SPAs) or static site generators. +Craft Pro 版では [GraphQL](https://graphql.org) のAPIを使ってコンテンツを扱うことができます。GraphQL APIにより、シングルページアプリケーション (SPA) や Static Site Generator のような別のアプリケーションでコンテンツを利用することができます。 + +[[toc]] + +## An example query and response + +### Query payload + +```graphql +{ + entries (section: "news", limit: 2, orderBy: "dateCreated DESC") { + dateCreated @formatDateTime (format: "Y-m-d") + title + children { + title + } + ... on news_article_Entry { + shortDescription + featuredImage { + url @transform (width: 300, immediately: true) + } + } + } +} +``` + +### The response + +```json +{ + "data": { + "entries": [ + { + "dateCreated": "2019-08-21", + "title": "An important news item", + "children": [], + "shortDescription": "

This is how we roll these days.

", + "featuredImage": [ + { + "url": "/assets/site/_300xAUTO_crop_center-center_none/glasses.jpg" + } + ] + }, + { + "dateCreated": "2019-07-02", + "title": "Dolorem ea eveniet alias", + "children": [ + { + "title": "Child entry" + }, + { + "title": "This is also a child entry" + } + ], + "shortDescription": "Et omnis explicabo iusto eum nobis. Consequatur debitis architecto est exercitationem vitae velit repellendus. Aut consequatur maiores error ducimus ea et. Rem ipsa asperiores eius quas et omnis. Veniam quasi qui repellendus dignissimos et necessitatibus. Aut a illo tempora.", + "featuredImage": [] + } + ] + } +} +``` ## Getting Started @@ -42,7 +102,7 @@ Craft has two types of schemas: - The **Public Schema** defines which content should be available publicly. - You can also define multiple private schemas, which each have their own secret **Access Token**. -You can manage your schemas from the Control Panel, at GraphQL → Schemas. In addition to defining the scope of each schema, you can also give them expiration dates, or disable them. +You can manage your schemas from the control panel, at GraphQL → Schemas. In addition to defining the scope of each schema, you can also give them expiration dates, or disable them. ::: tip When performing a GraphQL API request, the schema will be determined automatically based on the token that is supplied (if any). See [below](#querying-a-private-schema) to learn how to do that. @@ -50,9 +110,9 @@ When performing a GraphQL API request, the schema will be determined automatical ## Sending API Requests -### Using GraphiQL +### Using the GraphiQL IDE -The easiest way to start exploring your GraphQL API is with the built-in [GraphiQL](https://github.com/graphql/graphiql) IDE, which is available in the Control Panel from GraphQL → Explore. +The easiest way to start exploring your GraphQL API is with the built-in [GraphiQL](https://github.com/graphql/graphiql) IDE, which is available in the control panel from GraphQL → Explore. ![The built-in GraphiQL IDE](./images/graphiql.png) @@ -99,18 +159,6 @@ The GraphQL API can be queried in three ways: If you need to specify any [variables](https://graphql.org/learn/queries/#variables) along with your query, then you must send request as a `POST` request with an `application/json` content type, and include a `variables` key in the JSON body alongside `query`. -```bash -curl \ - --data-urlencode "query={ping}" \ - http://craft32.test/api - # or - curl http://craft32.test/api?query=%7Bping%7D -``` - -#### Querying a Private Schema - -The Public Schema will be used by default. To query against a different [schema](#define-your-schemas), pass its Access Token using an `Authorization` header. - ```bash curl \ -H "Content-Type: application/json" \ @@ -121,1106 +169,734 @@ curl \ http://my-project.test/api ``` -## Query Reference - -::: tip -The actual API features will depend on what your schema allows. -::: - -### The `assets` query -This query is used to query for assets. - -#### The `id` argument -Narrows the query results based on the elements’ IDs. - -#### The `uid` argument -Narrows the query results based on the elements’ UIDs. - -#### The `status` argument -Narrows the query results based on the elements’ statuses. - -#### The `archived` argument -Narrows the query results to only elements that have been archived. - -#### The `trashed` argument -Narrows the query results to only elements that have been soft-deleted. - -#### The `site` argument -Determines which site(s) the elements should be queried in. Defaults to the primary site. - -#### The `siteId` argument -Determines which site(s) the elements should be queried in. Defaults to the primary site. - -#### The `unique` argument -Determines whether only elements with unique IDs should be returned by the query. - -#### The `enabledForSite` argument -Narrows the query results based on whether the elements are enabled in the site they’re being queried in, per the `site` argument. - -#### The `title` argument -Narrows the query results based on the elements’ titles. - -#### The `slug` argument -Narrows the query results based on the elements’ slugs. - -#### The `uri` argument -Narrows the query results based on the elements’ URIs. - -#### The `search` argument -Narrows the query results to only elements that match a search query. - -#### The `ref` argument -Narrows the query results based on a reference string. - -#### The `fixedOrder` argument -Causes the query results to be returned in the order specified by the `id` argument. - -#### The `inReverse` argument -Causes the query results to be returned in reverse order. - -#### The `dateCreated` argument -Narrows the query results based on the elements’ creation dates. - -#### The `dateUpdated` argument -Narrows the query results based on the elements’ last-updated dates. - -#### The `offset` argument -Sets the offset for paginated results. - -#### The `limit` argument -Sets the limit for paginated results. +#### Querying a Private Schema -#### The `orderBy` argument -Sets the field the returned elements should be ordered by +The Public Schema will be used by default. To query against a different [schema](#define-your-schemas), pass its Access Token using an `Authorization` header. -#### The `volumeId` argument -Narrows the query results based on the volumes the assets belong to, per the volumes’ IDs. +```bash +curl \ + -H "Authorization: Bearer xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" \ + -H "Content-Type: application/graphql" \ + -d '{entries{id}}' \ + http://my-project.test/api +``` -#### The `volume` argument -Narrows the query results based on the volumes the assets belong to, per the volumes’ handles. +## Caching -#### The `folderId` argument -Narrows the query results based on the folders the assets belong to, per the folders’ IDs. +All query results are cached, so that repeated queries can yield results faster. The GraphQL result cache does not have a sophisticated ruleset on invalidating the cache - if the site's content or structure changes, the entire cache is invalidated. -#### The `filename` argument -Narrows the query results based on the assets’ filenames. +Craft has GraphQL result caching enabled by default, but it can be disabled with the [enableGraphQlCaching](https://docs.craftcms.com/api/v3/craft-config-generalconfig.html#enablegraphqlcaching) config setting. -#### The `kind` argument -Narrows the query results based on the assets’ file kinds. +## Interface Implementation -#### The `height` argument -Narrows the query results based on the assets’ image heights. +A defined type exists for each specific interface implementation. For example, if a “News” section has “Article” and “Editorial” entry types, in addition to the `EntryInterface` interface type, two additional types would be defined the GraphQL schema, if the token used allows it: `news_article_Entry` and `news_editorial_Entry` types. -#### The `width` argument -Narrows the query results based on the assets’ image widths. +## Query Reference -#### The `size` argument -Narrows the query results based on the assets’ file sizes (in bytes). +::: tip +The actual API features will depend on what your schema allows. +::: -#### The `dateModified` argument -Narrows the query results based on the assets’ files’ last-modified dates. + -#### The `includeSubfolders` argument -Broadens the query results to include assets from any of the subfolders of the folder specified by `folderId`. +### The `assets` query +This query is used to query for assets. +| Argument | Type | Description | +| ------------------- | ----------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `id` | `[QueryArgument]` | Narrows the query results based on the elements’ IDs. | +| `uid` | `[String]` | Narrows the query results based on the elements’ UIDs. | +| `status` | `[String]` | Narrows the query results based on the elements’ statuses. | +| `archived` | `Boolean` | Narrows the query results to only elements that have been archived. | +| `trashed` | `Boolean` | Narrows the query results to only elements that have been soft-deleted. | +| `site` | `[String]` | Determines which site(s) the elements should be queried in. Defaults to the current (requested) site. | +| `siteId` | `String` | Determines which site(s) the elements should be queried in. Defaults to the current (requested) site. | +| `unique` | `Boolean` | Determines whether only elements with unique IDs should be returned by the query. | +| `enabledForSite` | `Boolean` | Narrows the query results based on whether the elements are enabled in the site they’re being queried in, per the `site` argument. | +| `title` | `[String]` | Narrows the query results based on the elements’ titles. | +| `slug` | `[String]` | Narrows the query results based on the elements’ slugs. | +| `uri` | `[String]` | Narrows the query results based on the elements’ URIs. | +| `search` | `String` | Narrows the query results to only elements that match a search query. | +| `relatedTo` | `[Int]` | Narrows the query results to elements that relate to *any* of the provided element IDs. This argument is ignored, if `relatedToAll` is also used. | +| `relatedToAll` | `[Int]` | Narrows the query results to elements that relate to *all* of the provided element IDs. Using this argument will cause `relatedTo` argument to be ignored. | +| `ref` | `[String]` | Narrows the query results based on a reference string. | +| `fixedOrder` | `Boolean` | Causes the query results to be returned in the order specified by the `id` argument. | +| `inReverse` | `Boolean` | Causes the query results to be returned in reverse order. | +| `dateCreated` | `[String]` | Narrows the query results based on the elements’ creation dates. | +| `dateUpdated` | `[String]` | Narrows the query results based on the elements’ last-updated dates. | +| `offset` | `Int` | Sets the offset for paginated results. | +| `limit` | `Int` | Sets the limit for paginated results. | +| `orderBy` | `String` | Sets the field the returned elements should be ordered by | +| `volumeId` | `[QueryArgument]` | Narrows the query results based on the volumes the assets belong to, per the volumes’ IDs. | +| `volume` | `[String]` | Narrows the query results based on the volumes the assets belong to, per the volumes’ handles. | +| `folderId` | `[QueryArgument]` | Narrows the query results based on the folders the assets belong to, per the folders’ IDs. | +| `filename` | `[String]` | Narrows the query results based on the assets’ filenames. | +| `kind` | `[String]` | Narrows the query results based on the assets’ file kinds. | +| `height` | `[String]` | Narrows the query results based on the assets’ image heights. | +| `width` | `[String]` | Narrows the query results based on the assets’ image widths. | +| `size` | `[String]` | Narrows the query results based on the assets’ file sizes (in bytes). | +| `dateModified` | `String` | Narrows the query results based on the assets’ files’ last-modified dates. | +| `includeSubfolders` | `Boolean` | Broadens the query results to include assets from any of the subfolders of the folder specified by `folderId`. | +| `withTransforms` | `[String]` | A list of transform handles to preload. | + +### The `asset` query +This query is used to query for a single asset. +| Argument | Type | Description | +| ------------------- | ----------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `id` | `[QueryArgument]` | Narrows the query results based on the elements’ IDs. | +| `uid` | `[String]` | Narrows the query results based on the elements’ UIDs. | +| `status` | `[String]` | Narrows the query results based on the elements’ statuses. | +| `archived` | `Boolean` | Narrows the query results to only elements that have been archived. | +| `trashed` | `Boolean` | Narrows the query results to only elements that have been soft-deleted. | +| `site` | `[String]` | Determines which site(s) the elements should be queried in. Defaults to the current (requested) site. | +| `siteId` | `String` | Determines which site(s) the elements should be queried in. Defaults to the current (requested) site. | +| `unique` | `Boolean` | Determines whether only elements with unique IDs should be returned by the query. | +| `enabledForSite` | `Boolean` | Narrows the query results based on whether the elements are enabled in the site they’re being queried in, per the `site` argument. | +| `title` | `[String]` | Narrows the query results based on the elements’ titles. | +| `slug` | `[String]` | Narrows the query results based on the elements’ slugs. | +| `uri` | `[String]` | Narrows the query results based on the elements’ URIs. | +| `search` | `String` | Narrows the query results to only elements that match a search query. | +| `relatedTo` | `[Int]` | Narrows the query results to elements that relate to *any* of the provided element IDs. This argument is ignored, if `relatedToAll` is also used. | +| `relatedToAll` | `[Int]` | Narrows the query results to elements that relate to *all* of the provided element IDs. Using this argument will cause `relatedTo` argument to be ignored. | +| `ref` | `[String]` | Narrows the query results based on a reference string. | +| `fixedOrder` | `Boolean` | Causes the query results to be returned in the order specified by the `id` argument. | +| `inReverse` | `Boolean` | Causes the query results to be returned in reverse order. | +| `dateCreated` | `[String]` | Narrows the query results based on the elements’ creation dates. | +| `dateUpdated` | `[String]` | Narrows the query results based on the elements’ last-updated dates. | +| `offset` | `Int` | Sets the offset for paginated results. | +| `limit` | `Int` | Sets the limit for paginated results. | +| `orderBy` | `String` | Sets the field the returned elements should be ordered by | +| `volumeId` | `[QueryArgument]` | Narrows the query results based on the volumes the assets belong to, per the volumes’ IDs. | +| `volume` | `[String]` | Narrows the query results based on the volumes the assets belong to, per the volumes’ handles. | +| `folderId` | `[QueryArgument]` | Narrows the query results based on the folders the assets belong to, per the folders’ IDs. | +| `filename` | `[String]` | Narrows the query results based on the assets’ filenames. | +| `kind` | `[String]` | Narrows the query results based on the assets’ file kinds. | +| `height` | `[String]` | Narrows the query results based on the assets’ image heights. | +| `width` | `[String]` | Narrows the query results based on the assets’ image widths. | +| `size` | `[String]` | Narrows the query results based on the assets’ file sizes (in bytes). | +| `dateModified` | `String` | Narrows the query results based on the assets’ files’ last-modified dates. | +| `includeSubfolders` | `Boolean` | Broadens the query results to include assets from any of the subfolders of the folder specified by `folderId`. | +| `withTransforms` | `[String]` | A list of transform handles to preload. | ### The `entries` query This query is used to query for entries. - -#### The `id` argument -Narrows the query results based on the elements’ IDs. - -#### The `uid` argument -Narrows the query results based on the elements’ UIDs. - -#### The `status` argument -Narrows the query results based on the elements’ statuses. - -#### The `archived` argument -Narrows the query results to only elements that have been archived. - -#### The `trashed` argument -Narrows the query results to only elements that have been soft-deleted. - -#### The `site` argument -Determines which site(s) the elements should be queried in. Defaults to the primary site. - -#### The `siteId` argument -Determines which site(s) the elements should be queried in. Defaults to the primary site. - -#### The `unique` argument -Determines whether only elements with unique IDs should be returned by the query. - -#### The `enabledForSite` argument -Narrows the query results based on whether the elements are enabled in the site they’re being queried in, per the `site` argument. - -#### The `title` argument -Narrows the query results based on the elements’ titles. - -#### The `slug` argument -Narrows the query results based on the elements’ slugs. - -#### The `uri` argument -Narrows the query results based on the elements’ URIs. - -#### The `search` argument -Narrows the query results to only elements that match a search query. - -#### The `ref` argument -Narrows the query results based on a reference string. - -#### The `fixedOrder` argument -Causes the query results to be returned in the order specified by the `id` argument. - -#### The `inReverse` argument -Causes the query results to be returned in reverse order. - -#### The `dateCreated` argument -Narrows the query results based on the elements’ creation dates. - -#### The `dateUpdated` argument -Narrows the query results based on the elements’ last-updated dates. - -#### The `offset` argument -Sets the offset for paginated results. - -#### The `limit` argument -Sets the limit for paginated results. - -#### The `orderBy` argument -Sets the field the returned elements should be ordered by - -#### The `withStructure` argument -Explicitly determines whether the query should join in the structure data. - -#### The `structureId` argument -Determines which structure data should be joined into the query. - -#### The `level` argument -Narrows the query results based on the elements’ level within the structure. - -#### The `hasDescendants` argument -Narrows the query results based on whether the elements have any descendants. - -#### The `ancestorOf` argument -Narrows the query results to only elements that are ancestors of another element. - -#### The `ancestorDist` argument -Narrows the query results to only elements that are up to a certain distance away from the element specified by `ancestorOf`. - -#### The `descendantOf` argument -Narrows the query results to only elements that are descendants of another element. - -#### The `descendantDist` argument -Narrows the query results to only elements that are up to a certain distance away from the element specified by `descendantOf`. - -#### The `leaves` argument -Narrows the query results based on whether the elements are “leaves” (element with no descendants). - -#### The `editable` argument -Whether to only return entries that the user has permission to edit. - -#### The `section` argument -Narrows the query results based on the section handles the entries belong to. - -#### The `sectionId` argument -Narrows the query results based on the sections the entries belong to, per the sections’ IDs. - -#### The `type` argument -Narrows the query results based on the entries’ entry type handles. - -#### The `typeId` argument -Narrows the query results based on the entries’ entry types, per the types’ IDs. - -#### The `authorId` argument -Narrows the query results based on the entries’ authors. - -#### The `authorGroup` argument -Narrows the query results based on the user group the entries’ authors belong to. - -#### The `postDate` argument -Narrows the query results based on the entries’ post dates. - -#### The `before` argument -Narrows the query results to only entries that were posted before a certain date. - -#### The `after` argument -Narrows the query results to only entries that were posted on or after a certain date. - -#### The `expiryDate` argument -Narrows the query results based on the entries’ expiry dates. +| Argument | Type | Description | +| ------------------ | ----------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `id` | `[QueryArgument]` | Narrows the query results based on the elements’ IDs. | +| `uid` | `[String]` | Narrows the query results based on the elements’ UIDs. | +| `status` | `[String]` | Narrows the query results based on the elements’ statuses. | +| `archived` | `Boolean` | Narrows the query results to only elements that have been archived. | +| `trashed` | `Boolean` | Narrows the query results to only elements that have been soft-deleted. | +| `site` | `[String]` | Determines which site(s) the elements should be queried in. Defaults to the current (requested) site. | +| `siteId` | `String` | Determines which site(s) the elements should be queried in. Defaults to the current (requested) site. | +| `unique` | `Boolean` | Determines whether only elements with unique IDs should be returned by the query. | +| `enabledForSite` | `Boolean` | Narrows the query results based on whether the elements are enabled in the site they’re being queried in, per the `site` argument. | +| `title` | `[String]` | Narrows the query results based on the elements’ titles. | +| `slug` | `[String]` | Narrows the query results based on the elements’ slugs. | +| `uri` | `[String]` | Narrows the query results based on the elements’ URIs. | +| `search` | `String` | Narrows the query results to only elements that match a search query. | +| `relatedTo` | `[Int]` | Narrows the query results to elements that relate to *any* of the provided element IDs. This argument is ignored, if `relatedToAll` is also used. | +| `relatedToAll` | `[Int]` | Narrows the query results to elements that relate to *all* of the provided element IDs. Using this argument will cause `relatedTo` argument to be ignored. | +| `ref` | `[String]` | Narrows the query results based on a reference string. | +| `fixedOrder` | `Boolean` | Causes the query results to be returned in the order specified by the `id` argument. | +| `inReverse` | `Boolean` | Causes the query results to be returned in reverse order. | +| `dateCreated` | `[String]` | Narrows the query results based on the elements’ creation dates. | +| `dateUpdated` | `[String]` | Narrows the query results based on the elements’ last-updated dates. | +| `offset` | `Int` | Sets the offset for paginated results. | +| `limit` | `Int` | Sets the limit for paginated results. | +| `orderBy` | `String` | Sets the field the returned elements should be ordered by | +| `withStructure` | `Boolean` | Explicitly determines whether the query should join in the structure data. | +| `structureId` | `Int` | Determines which structure data should be joined into the query. | +| `level` | `Int` | Narrows the query results based on the elements’ level within the structure. | +| `hasDescendants` | `Boolean` | Narrows the query results based on whether the elements have any descendants. | +| `ancestorOf` | `Int` | Narrows the query results to only elements that are ancestors of another element. | +| `ancestorDist` | `Int` | Narrows the query results to only elements that are up to a certain distance away from the element specified by `ancestorOf`. | +| `descendantOf` | `Int` | Narrows the query results to only elements that are descendants of another element. | +| `descendantDist` | `Int` | Narrows the query results to only elements that are up to a certain distance away from the element specified by `descendantOf`. | +| `leaves` | `Boolean` | Narrows the query results based on whether the elements are “leaves” (element with no descendants). | +| `nextSiblingOf` | `Int` | Narrows the query results to only the entry that comes immediately after another element. | +| `prevSiblingOf` | `Int` | Narrows the query results to only the entry that comes immediately before another element. | +| `positionedAfter` | `Int` | Narrows the query results to only entries that are positioned after another element. | +| `positionedBefore` | `Int` | Narrows the query results to only entries that are positioned before another element. | +| `editable` | `Boolean` | Whether to only return entries that the user has permission to edit. | +| `section` | `[String]` | Narrows the query results based on the section handles the entries belong to. | +| `sectionId` | `[QueryArgument]` | Narrows the query results based on the sections the entries belong to, per the sections’ IDs. | +| `type` | `[String]` | Narrows the query results based on the entries’ entry type handles. | +| `typeId` | `[QueryArgument]` | Narrows the query results based on the entries’ entry types, per the types’ IDs. | +| `authorId` | `[QueryArgument]` | Narrows the query results based on the entries’ authors. | +| `authorGroup` | `[String]` | Narrows the query results based on the user group the entries’ authors belong to. | +| `authorGroupId` | `[QueryArgument]` | Narrows the query results based on the user group the entries’ authors belong to, per the groups’ IDs. | +| `postDate` | `[String]` | Narrows the query results based on the entries’ post dates. | +| `before` | `String` | Narrows the query results to only entries that were posted before a certain date. | +| `after` | `String` | Narrows the query results to only entries that were posted on or after a certain date. | +| `expiryDate` | `[String]` | Narrows the query results based on the entries’ expiry dates. | + +### The `entry` query +This query is used to query for a single entry. +| Argument | Type | Description | +| ------------------ | ----------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `id` | `[QueryArgument]` | Narrows the query results based on the elements’ IDs. | +| `uid` | `[String]` | Narrows the query results based on the elements’ UIDs. | +| `status` | `[String]` | Narrows the query results based on the elements’ statuses. | +| `archived` | `Boolean` | Narrows the query results to only elements that have been archived. | +| `trashed` | `Boolean` | Narrows the query results to only elements that have been soft-deleted. | +| `site` | `[String]` | Determines which site(s) the elements should be queried in. Defaults to the current (requested) site. | +| `siteId` | `String` | Determines which site(s) the elements should be queried in. Defaults to the current (requested) site. | +| `unique` | `Boolean` | Determines whether only elements with unique IDs should be returned by the query. | +| `enabledForSite` | `Boolean` | Narrows the query results based on whether the elements are enabled in the site they’re being queried in, per the `site` argument. | +| `title` | `[String]` | Narrows the query results based on the elements’ titles. | +| `slug` | `[String]` | Narrows the query results based on the elements’ slugs. | +| `uri` | `[String]` | Narrows the query results based on the elements’ URIs. | +| `search` | `String` | Narrows the query results to only elements that match a search query. | +| `relatedTo` | `[Int]` | Narrows the query results to elements that relate to *any* of the provided element IDs. This argument is ignored, if `relatedToAll` is also used. | +| `relatedToAll` | `[Int]` | Narrows the query results to elements that relate to *all* of the provided element IDs. Using this argument will cause `relatedTo` argument to be ignored. | +| `ref` | `[String]` | Narrows the query results based on a reference string. | +| `fixedOrder` | `Boolean` | Causes the query results to be returned in the order specified by the `id` argument. | +| `inReverse` | `Boolean` | Causes the query results to be returned in reverse order. | +| `dateCreated` | `[String]` | Narrows the query results based on the elements’ creation dates. | +| `dateUpdated` | `[String]` | Narrows the query results based on the elements’ last-updated dates. | +| `offset` | `Int` | Sets the offset for paginated results. | +| `limit` | `Int` | Sets the limit for paginated results. | +| `orderBy` | `String` | Sets the field the returned elements should be ordered by | +| `withStructure` | `Boolean` | Explicitly determines whether the query should join in the structure data. | +| `structureId` | `Int` | Determines which structure data should be joined into the query. | +| `level` | `Int` | Narrows the query results based on the elements’ level within the structure. | +| `hasDescendants` | `Boolean` | Narrows the query results based on whether the elements have any descendants. | +| `ancestorOf` | `Int` | Narrows the query results to only elements that are ancestors of another element. | +| `ancestorDist` | `Int` | Narrows the query results to only elements that are up to a certain distance away from the element specified by `ancestorOf`. | +| `descendantOf` | `Int` | Narrows the query results to only elements that are descendants of another element. | +| `descendantDist` | `Int` | Narrows the query results to only elements that are up to a certain distance away from the element specified by `descendantOf`. | +| `leaves` | `Boolean` | Narrows the query results based on whether the elements are “leaves” (element with no descendants). | +| `nextSiblingOf` | `Int` | Narrows the query results to only the entry that comes immediately after another element. | +| `prevSiblingOf` | `Int` | Narrows the query results to only the entry that comes immediately before another element. | +| `positionedAfter` | `Int` | Narrows the query results to only entries that are positioned after another element. | +| `positionedBefore` | `Int` | Narrows the query results to only entries that are positioned before another element. | +| `editable` | `Boolean` | Whether to only return entries that the user has permission to edit. | +| `section` | `[String]` | Narrows the query results based on the section handles the entries belong to. | +| `sectionId` | `[QueryArgument]` | Narrows the query results based on the sections the entries belong to, per the sections’ IDs. | +| `type` | `[String]` | Narrows the query results based on the entries’ entry type handles. | +| `typeId` | `[QueryArgument]` | Narrows the query results based on the entries’ entry types, per the types’ IDs. | +| `authorId` | `[QueryArgument]` | Narrows the query results based on the entries’ authors. | +| `authorGroup` | `[String]` | Narrows the query results based on the user group the entries’ authors belong to. | +| `authorGroupId` | `[QueryArgument]` | Narrows the query results based on the user group the entries’ authors belong to, per the groups’ IDs. | +| `postDate` | `[String]` | Narrows the query results based on the entries’ post dates. | +| `before` | `String` | Narrows the query results to only entries that were posted before a certain date. | +| `after` | `String` | Narrows the query results to only entries that were posted on or after a certain date. | +| `expiryDate` | `[String]` | Narrows the query results based on the entries’ expiry dates. | ### The `globalSets` query This query is used to query for global sets. - -#### The `id` argument -Narrows the query results based on the elements’ IDs. - -#### The `uid` argument -Narrows the query results based on the elements’ UIDs. - -#### The `status` argument -Narrows the query results based on the elements’ statuses. - -#### The `archived` argument -Narrows the query results to only elements that have been archived. - -#### The `trashed` argument -Narrows the query results to only elements that have been soft-deleted. - -#### The `site` argument -Determines which site(s) the elements should be queried in. Defaults to the primary site. - -#### The `siteId` argument -Determines which site(s) the elements should be queried in. Defaults to the primary site. - -#### The `unique` argument -Determines whether only elements with unique IDs should be returned by the query. - -#### The `enabledForSite` argument -Narrows the query results based on whether the elements are enabled in the site they’re being queried in, per the `site` argument. - -#### The `title` argument -Narrows the query results based on the elements’ titles. - -#### The `slug` argument -Narrows the query results based on the elements’ slugs. - -#### The `uri` argument -Narrows the query results based on the elements’ URIs. - -#### The `search` argument -Narrows the query results to only elements that match a search query. - -#### The `ref` argument -Narrows the query results based on a reference string. - -#### The `fixedOrder` argument -Causes the query results to be returned in the order specified by the `id` argument. - -#### The `inReverse` argument -Causes the query results to be returned in reverse order. - -#### The `dateCreated` argument -Narrows the query results based on the elements’ creation dates. - -#### The `dateUpdated` argument -Narrows the query results based on the elements’ last-updated dates. - -#### The `offset` argument -Sets the offset for paginated results. - -#### The `limit` argument -Sets the limit for paginated results. - -#### The `orderBy` argument -Sets the field the returned elements should be ordered by - -#### The `handle` argument -Narrows the query results based on the global sets’ handles. +| Argument | Type | Description | +| ---------------- | ----------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `id` | `[QueryArgument]` | Narrows the query results based on the elements’ IDs. | +| `uid` | `[String]` | Narrows the query results based on the elements’ UIDs. | +| `status` | `[String]` | Narrows the query results based on the elements’ statuses. | +| `archived` | `Boolean` | Narrows the query results to only elements that have been archived. | +| `trashed` | `Boolean` | Narrows the query results to only elements that have been soft-deleted. | +| `site` | `[String]` | Determines which site(s) the elements should be queried in. Defaults to the current (requested) site. | +| `siteId` | `String` | Determines which site(s) the elements should be queried in. Defaults to the current (requested) site. | +| `unique` | `Boolean` | Determines whether only elements with unique IDs should be returned by the query. | +| `enabledForSite` | `Boolean` | Narrows the query results based on whether the elements are enabled in the site they’re being queried in, per the `site` argument. | +| `title` | `[String]` | Narrows the query results based on the elements’ titles. | +| `slug` | `[String]` | Narrows the query results based on the elements’ slugs. | +| `uri` | `[String]` | Narrows the query results based on the elements’ URIs. | +| `search` | `String` | Narrows the query results to only elements that match a search query. | +| `relatedTo` | `[Int]` | Narrows the query results to elements that relate to *any* of the provided element IDs. This argument is ignored, if `relatedToAll` is also used. | +| `relatedToAll` | `[Int]` | Narrows the query results to elements that relate to *all* of the provided element IDs. Using this argument will cause `relatedTo` argument to be ignored. | +| `ref` | `[String]` | Narrows the query results based on a reference string. | +| `fixedOrder` | `Boolean` | Causes the query results to be returned in the order specified by the `id` argument. | +| `inReverse` | `Boolean` | Causes the query results to be returned in reverse order. | +| `dateCreated` | `[String]` | Narrows the query results based on the elements’ creation dates. | +| `dateUpdated` | `[String]` | Narrows the query results based on the elements’ last-updated dates. | +| `offset` | `Int` | Sets the offset for paginated results. | +| `limit` | `Int` | Sets the limit for paginated results. | +| `orderBy` | `String` | Sets the field the returned elements should be ordered by | +| `handle` | `[String]` | Narrows the query results based on the global sets’ handles. | + +### The `globalSet` query +This query is used to query for a single global set. +| Argument | Type | Description | +| ---------------- | ----------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `id` | `[QueryArgument]` | Narrows the query results based on the elements’ IDs. | +| `uid` | `[String]` | Narrows the query results based on the elements’ UIDs. | +| `status` | `[String]` | Narrows the query results based on the elements’ statuses. | +| `archived` | `Boolean` | Narrows the query results to only elements that have been archived. | +| `trashed` | `Boolean` | Narrows the query results to only elements that have been soft-deleted. | +| `site` | `[String]` | Determines which site(s) the elements should be queried in. Defaults to the current (requested) site. | +| `siteId` | `String` | Determines which site(s) the elements should be queried in. Defaults to the current (requested) site. | +| `unique` | `Boolean` | Determines whether only elements with unique IDs should be returned by the query. | +| `enabledForSite` | `Boolean` | Narrows the query results based on whether the elements are enabled in the site they’re being queried in, per the `site` argument. | +| `title` | `[String]` | Narrows the query results based on the elements’ titles. | +| `slug` | `[String]` | Narrows the query results based on the elements’ slugs. | +| `uri` | `[String]` | Narrows the query results based on the elements’ URIs. | +| `search` | `String` | Narrows the query results to only elements that match a search query. | +| `relatedTo` | `[Int]` | Narrows the query results to elements that relate to *any* of the provided element IDs. This argument is ignored, if `relatedToAll` is also used. | +| `relatedToAll` | `[Int]` | Narrows the query results to elements that relate to *all* of the provided element IDs. Using this argument will cause `relatedTo` argument to be ignored. | +| `ref` | `[String]` | Narrows the query results based on a reference string. | +| `fixedOrder` | `Boolean` | Causes the query results to be returned in the order specified by the `id` argument. | +| `inReverse` | `Boolean` | Causes the query results to be returned in reverse order. | +| `dateCreated` | `[String]` | Narrows the query results based on the elements’ creation dates. | +| `dateUpdated` | `[String]` | Narrows the query results based on the elements’ last-updated dates. | +| `offset` | `Int` | Sets the offset for paginated results. | +| `limit` | `Int` | Sets the limit for paginated results. | +| `orderBy` | `String` | Sets the field the returned elements should be ordered by | +| `handle` | `[String]` | Narrows the query results based on the global sets’ handles. | ### The `users` query This query is used to query for users. - -#### The `id` argument -Narrows the query results based on the elements’ IDs. - -#### The `uid` argument -Narrows the query results based on the elements’ UIDs. - -#### The `status` argument -Narrows the query results based on the elements’ statuses. - -#### The `archived` argument -Narrows the query results to only elements that have been archived. - -#### The `trashed` argument -Narrows the query results to only elements that have been soft-deleted. - -#### The `site` argument -Determines which site(s) the elements should be queried in. Defaults to the primary site. - -#### The `siteId` argument -Determines which site(s) the elements should be queried in. Defaults to the primary site. - -#### The `unique` argument -Determines whether only elements with unique IDs should be returned by the query. - -#### The `enabledForSite` argument -Narrows the query results based on whether the elements are enabled in the site they’re being queried in, per the `site` argument. - -#### The `title` argument -Narrows the query results based on the elements’ titles. - -#### The `slug` argument -Narrows the query results based on the elements’ slugs. - -#### The `uri` argument -Narrows the query results based on the elements’ URIs. - -#### The `search` argument -Narrows the query results to only elements that match a search query. - -#### The `ref` argument -Narrows the query results based on a reference string. - -#### The `fixedOrder` argument -Causes the query results to be returned in the order specified by the `id` argument. - -#### The `inReverse` argument -Causes the query results to be returned in reverse order. - -#### The `dateCreated` argument -Narrows the query results based on the elements’ creation dates. - -#### The `dateUpdated` argument -Narrows the query results based on the elements’ last-updated dates. - -#### The `offset` argument -Sets the offset for paginated results. - -#### The `limit` argument -Sets the limit for paginated results. - -#### The `orderBy` argument -Sets the field the returned elements should be ordered by - -#### The `email` argument -Narrows the query results based on the users’ email addresses. - -#### The `username` argument -Narrows the query results based on the users’ usernames. - -#### The `firstName` argument -Narrows the query results based on the users’ first names. - -#### The `lastName` argument -Narrows the query results based on the users’ last names. +| Argument | Type | Description | +| ---------------- | ----------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `id` | `[QueryArgument]` | Narrows the query results based on the elements’ IDs. | +| `uid` | `[String]` | Narrows the query results based on the elements’ UIDs. | +| `status` | `[String]` | Narrows the query results based on the elements’ statuses. | +| `archived` | `Boolean` | Narrows the query results to only elements that have been archived. | +| `trashed` | `Boolean` | Narrows the query results to only elements that have been soft-deleted. | +| `site` | `[String]` | Determines which site(s) the elements should be queried in. Defaults to the current (requested) site. | +| `siteId` | `String` | Determines which site(s) the elements should be queried in. Defaults to the current (requested) site. | +| `unique` | `Boolean` | Determines whether only elements with unique IDs should be returned by the query. | +| `enabledForSite` | `Boolean` | Narrows the query results based on whether the elements are enabled in the site they’re being queried in, per the `site` argument. | +| `title` | `[String]` | Narrows the query results based on the elements’ titles. | +| `slug` | `[String]` | Narrows the query results based on the elements’ slugs. | +| `uri` | `[String]` | Narrows the query results based on the elements’ URIs. | +| `search` | `String` | Narrows the query results to only elements that match a search query. | +| `relatedTo` | `[Int]` | Narrows the query results to elements that relate to *any* of the provided element IDs. This argument is ignored, if `relatedToAll` is also used. | +| `relatedToAll` | `[Int]` | Narrows the query results to elements that relate to *all* of the provided element IDs. Using this argument will cause `relatedTo` argument to be ignored. | +| `ref` | `[String]` | Narrows the query results based on a reference string. | +| `fixedOrder` | `Boolean` | Causes the query results to be returned in the order specified by the `id` argument. | +| `inReverse` | `Boolean` | Causes the query results to be returned in reverse order. | +| `dateCreated` | `[String]` | Narrows the query results based on the elements’ creation dates. | +| `dateUpdated` | `[String]` | Narrows the query results based on the elements’ last-updated dates. | +| `offset` | `Int` | Sets the offset for paginated results. | +| `limit` | `Int` | Sets the limit for paginated results. | +| `orderBy` | `String` | Sets the field the returned elements should be ordered by | +| `email` | `[String]` | Narrows the query results based on the users’ email addresses. | +| `username` | `[String]` | Narrows the query results based on the users’ usernames. | +| `firstName` | `[String]` | Narrows the query results based on the users’ first names. | +| `lastName` | `[String]` | Narrows the query results based on the users’ last names. | +| `groupId` | `[QueryArgument]` | Narrows the query results based on the user group the users belong to, per the groups’ IDs. | +| `group` | `[QueryArgument]` | Narrows the query results based on the user group the users belong to. | + +### The `user` query +This query is used to query for a single user. +| Argument | Type | Description | +| ---------------- | ----------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `id` | `[QueryArgument]` | Narrows the query results based on the elements’ IDs. | +| `uid` | `[String]` | Narrows the query results based on the elements’ UIDs. | +| `status` | `[String]` | Narrows the query results based on the elements’ statuses. | +| `archived` | `Boolean` | Narrows the query results to only elements that have been archived. | +| `trashed` | `Boolean` | Narrows the query results to only elements that have been soft-deleted. | +| `site` | `[String]` | Determines which site(s) the elements should be queried in. Defaults to the current (requested) site. | +| `siteId` | `String` | Determines which site(s) the elements should be queried in. Defaults to the current (requested) site. | +| `unique` | `Boolean` | Determines whether only elements with unique IDs should be returned by the query. | +| `enabledForSite` | `Boolean` | Narrows the query results based on whether the elements are enabled in the site they’re being queried in, per the `site` argument. | +| `title` | `[String]` | Narrows the query results based on the elements’ titles. | +| `slug` | `[String]` | Narrows the query results based on the elements’ slugs. | +| `uri` | `[String]` | Narrows the query results based on the elements’ URIs. | +| `search` | `String` | Narrows the query results to only elements that match a search query. | +| `relatedTo` | `[Int]` | Narrows the query results to elements that relate to *any* of the provided element IDs. This argument is ignored, if `relatedToAll` is also used. | +| `relatedToAll` | `[Int]` | Narrows the query results to elements that relate to *all* of the provided element IDs. Using this argument will cause `relatedTo` argument to be ignored. | +| `ref` | `[String]` | Narrows the query results based on a reference string. | +| `fixedOrder` | `Boolean` | Causes the query results to be returned in the order specified by the `id` argument. | +| `inReverse` | `Boolean` | Causes the query results to be returned in reverse order. | +| `dateCreated` | `[String]` | Narrows the query results based on the elements’ creation dates. | +| `dateUpdated` | `[String]` | Narrows the query results based on the elements’ last-updated dates. | +| `offset` | `Int` | Sets the offset for paginated results. | +| `limit` | `Int` | Sets the limit for paginated results. | +| `orderBy` | `String` | Sets the field the returned elements should be ordered by | +| `email` | `[String]` | Narrows the query results based on the users’ email addresses. | +| `username` | `[String]` | Narrows the query results based on the users’ usernames. | +| `firstName` | `[String]` | Narrows the query results based on the users’ first names. | +| `lastName` | `[String]` | Narrows the query results based on the users’ last names. | +| `groupId` | `[QueryArgument]` | Narrows the query results based on the user group the users belong to, per the groups’ IDs. | +| `group` | `[QueryArgument]` | Narrows the query results based on the user group the users belong to. | ### The `tags` query This query is used to query for tags. - -#### The `id` argument -Narrows the query results based on the elements’ IDs. - -#### The `uid` argument -Narrows the query results based on the elements’ UIDs. - -#### The `status` argument -Narrows the query results based on the elements’ statuses. - -#### The `archived` argument -Narrows the query results to only elements that have been archived. - -#### The `trashed` argument -Narrows the query results to only elements that have been soft-deleted. - -#### The `site` argument -Determines which site(s) the elements should be queried in. Defaults to the primary site. - -#### The `siteId` argument -Determines which site(s) the elements should be queried in. Defaults to the primary site. - -#### The `unique` argument -Determines whether only elements with unique IDs should be returned by the query. - -#### The `enabledForSite` argument -Narrows the query results based on whether the elements are enabled in the site they’re being queried in, per the `site` argument. - -#### The `title` argument -Narrows the query results based on the elements’ titles. - -#### The `slug` argument -Narrows the query results based on the elements’ slugs. - -#### The `uri` argument -Narrows the query results based on the elements’ URIs. - -#### The `search` argument -Narrows the query results to only elements that match a search query. - -#### The `ref` argument -Narrows the query results based on a reference string. - -#### The `fixedOrder` argument -Causes the query results to be returned in the order specified by the `id` argument. - -#### The `inReverse` argument -Causes the query results to be returned in reverse order. - -#### The `dateCreated` argument -Narrows the query results based on the elements’ creation dates. - -#### The `dateUpdated` argument -Narrows the query results based on the elements’ last-updated dates. - -#### The `offset` argument -Sets the offset for paginated results. - -#### The `limit` argument -Sets the limit for paginated results. - -#### The `orderBy` argument -Sets the field the returned elements should be ordered by - -#### The `group` argument -Narrows the query results based on the tag groups the tags belong to per the group’s handles. - -#### The `groupId` argument -Narrows the query results based on the tag groups the tags belong to, per the groups’ IDs. +| Argument | Type | Description | +| ---------------- | ----------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `id` | `[QueryArgument]` | Narrows the query results based on the elements’ IDs. | +| `uid` | `[String]` | Narrows the query results based on the elements’ UIDs. | +| `status` | `[String]` | Narrows the query results based on the elements’ statuses. | +| `archived` | `Boolean` | Narrows the query results to only elements that have been archived. | +| `trashed` | `Boolean` | Narrows the query results to only elements that have been soft-deleted. | +| `site` | `[String]` | Determines which site(s) the elements should be queried in. Defaults to the current (requested) site. | +| `siteId` | `String` | Determines which site(s) the elements should be queried in. Defaults to the current (requested) site. | +| `unique` | `Boolean` | Determines whether only elements with unique IDs should be returned by the query. | +| `enabledForSite` | `Boolean` | Narrows the query results based on whether the elements are enabled in the site they’re being queried in, per the `site` argument. | +| `title` | `[String]` | Narrows the query results based on the elements’ titles. | +| `slug` | `[String]` | Narrows the query results based on the elements’ slugs. | +| `uri` | `[String]` | Narrows the query results based on the elements’ URIs. | +| `search` | `String` | Narrows the query results to only elements that match a search query. | +| `relatedTo` | `[Int]` | Narrows the query results to elements that relate to *any* of the provided element IDs. This argument is ignored, if `relatedToAll` is also used. | +| `relatedToAll` | `[Int]` | Narrows the query results to elements that relate to *all* of the provided element IDs. Using this argument will cause `relatedTo` argument to be ignored. | +| `ref` | `[String]` | Narrows the query results based on a reference string. | +| `fixedOrder` | `Boolean` | Causes the query results to be returned in the order specified by the `id` argument. | +| `inReverse` | `Boolean` | Causes the query results to be returned in reverse order. | +| `dateCreated` | `[String]` | Narrows the query results based on the elements’ creation dates. | +| `dateUpdated` | `[String]` | Narrows the query results based on the elements’ last-updated dates. | +| `offset` | `Int` | Sets the offset for paginated results. | +| `limit` | `Int` | Sets the limit for paginated results. | +| `orderBy` | `String` | Sets the field the returned elements should be ordered by | +| `group` | `[String]` | Narrows the query results based on the tag groups the tags belong to per the group’s handles. | +| `groupId` | `[QueryArgument]` | Narrows the query results based on the tag groups the tags belong to, per the groups’ IDs. | + +### The `tag` query +This query is used to query for a single tag. +| Argument | Type | Description | +| ---------------- | ----------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `id` | `[QueryArgument]` | Narrows the query results based on the elements’ IDs. | +| `uid` | `[String]` | Narrows the query results based on the elements’ UIDs. | +| `status` | `[String]` | Narrows the query results based on the elements’ statuses. | +| `archived` | `Boolean` | Narrows the query results to only elements that have been archived. | +| `trashed` | `Boolean` | Narrows the query results to only elements that have been soft-deleted. | +| `site` | `[String]` | Determines which site(s) the elements should be queried in. Defaults to the current (requested) site. | +| `siteId` | `String` | Determines which site(s) the elements should be queried in. Defaults to the current (requested) site. | +| `unique` | `Boolean` | Determines whether only elements with unique IDs should be returned by the query. | +| `enabledForSite` | `Boolean` | Narrows the query results based on whether the elements are enabled in the site they’re being queried in, per the `site` argument. | +| `title` | `[String]` | Narrows the query results based on the elements’ titles. | +| `slug` | `[String]` | Narrows the query results based on the elements’ slugs. | +| `uri` | `[String]` | Narrows the query results based on the elements’ URIs. | +| `search` | `String` | Narrows the query results to only elements that match a search query. | +| `relatedTo` | `[Int]` | Narrows the query results to elements that relate to *any* of the provided element IDs. This argument is ignored, if `relatedToAll` is also used. | +| `relatedToAll` | `[Int]` | Narrows the query results to elements that relate to *all* of the provided element IDs. Using this argument will cause `relatedTo` argument to be ignored. | +| `ref` | `[String]` | Narrows the query results based on a reference string. | +| `fixedOrder` | `Boolean` | Causes the query results to be returned in the order specified by the `id` argument. | +| `inReverse` | `Boolean` | Causes the query results to be returned in reverse order. | +| `dateCreated` | `[String]` | Narrows the query results based on the elements’ creation dates. | +| `dateUpdated` | `[String]` | Narrows the query results based on the elements’ last-updated dates. | +| `offset` | `Int` | Sets the offset for paginated results. | +| `limit` | `Int` | Sets the limit for paginated results. | +| `orderBy` | `String` | Sets the field the returned elements should be ordered by | +| `group` | `[String]` | Narrows the query results based on the tag groups the tags belong to per the group’s handles. | +| `groupId` | `[QueryArgument]` | Narrows the query results based on the tag groups the tags belong to, per the groups’ IDs. | ### The `categories` query This query is used to query for categories. - -#### The `id` argument -Narrows the query results based on the elements’ IDs. - -#### The `uid` argument -Narrows the query results based on the elements’ UIDs. - -#### The `status` argument -Narrows the query results based on the elements’ statuses. - -#### The `archived` argument -Narrows the query results to only elements that have been archived. - -#### The `trashed` argument -Narrows the query results to only elements that have been soft-deleted. - -#### The `site` argument -Determines which site(s) the elements should be queried in. Defaults to the primary site. - -#### The `siteId` argument -Determines which site(s) the elements should be queried in. Defaults to the primary site. - -#### The `unique` argument -Determines whether only elements with unique IDs should be returned by the query. - -#### The `enabledForSite` argument -Narrows the query results based on whether the elements are enabled in the site they’re being queried in, per the `site` argument. - -#### The `title` argument -Narrows the query results based on the elements’ titles. - -#### The `slug` argument -Narrows the query results based on the elements’ slugs. - -#### The `uri` argument -Narrows the query results based on the elements’ URIs. - -#### The `search` argument -Narrows the query results to only elements that match a search query. - -#### The `ref` argument -Narrows the query results based on a reference string. - -#### The `fixedOrder` argument -Causes the query results to be returned in the order specified by the `id` argument. - -#### The `inReverse` argument -Causes the query results to be returned in reverse order. - -#### The `dateCreated` argument -Narrows the query results based on the elements’ creation dates. - -#### The `dateUpdated` argument -Narrows the query results based on the elements’ last-updated dates. - -#### The `offset` argument -Sets the offset for paginated results. - -#### The `limit` argument -Sets the limit for paginated results. - -#### The `orderBy` argument -Sets the field the returned elements should be ordered by - -#### The `withStructure` argument -Explicitly determines whether the query should join in the structure data. - -#### The `structureId` argument -Determines which structure data should be joined into the query. - -#### The `level` argument -Narrows the query results based on the elements’ level within the structure. - -#### The `hasDescendants` argument -Narrows the query results based on whether the elements have any descendants. - -#### The `ancestorOf` argument -Narrows the query results to only elements that are ancestors of another element. - -#### The `ancestorDist` argument -Narrows the query results to only elements that are up to a certain distance away from the element specified by `ancestorOf`. - -#### The `descendantOf` argument -Narrows the query results to only elements that are descendants of another element. - -#### The `descendantDist` argument -Narrows the query results to only elements that are up to a certain distance away from the element specified by `descendantOf`. - -#### The `leaves` argument -Narrows the query results based on whether the elements are “leaves” (element with no descendants). - -#### The `editable` argument -Whether to only return categories that the user has permission to edit. - -#### The `group` argument -Narrows the query results based on the category groups the categories belong to per the group’s handles. - -#### The `groupId` argument -Narrows the query results based on the category groups the categories belong to, per the groups’ IDs. +| Argument | Type | Description | +| ------------------ | ----------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `id` | `[QueryArgument]` | Narrows the query results based on the elements’ IDs. | +| `uid` | `[String]` | Narrows the query results based on the elements’ UIDs. | +| `status` | `[String]` | Narrows the query results based on the elements’ statuses. | +| `archived` | `Boolean` | Narrows the query results to only elements that have been archived. | +| `trashed` | `Boolean` | Narrows the query results to only elements that have been soft-deleted. | +| `site` | `[String]` | Determines which site(s) the elements should be queried in. Defaults to the current (requested) site. | +| `siteId` | `String` | Determines which site(s) the elements should be queried in. Defaults to the current (requested) site. | +| `unique` | `Boolean` | Determines whether only elements with unique IDs should be returned by the query. | +| `enabledForSite` | `Boolean` | Narrows the query results based on whether the elements are enabled in the site they’re being queried in, per the `site` argument. | +| `title` | `[String]` | Narrows the query results based on the elements’ titles. | +| `slug` | `[String]` | Narrows the query results based on the elements’ slugs. | +| `uri` | `[String]` | Narrows the query results based on the elements’ URIs. | +| `search` | `String` | Narrows the query results to only elements that match a search query. | +| `relatedTo` | `[Int]` | Narrows the query results to elements that relate to *any* of the provided element IDs. This argument is ignored, if `relatedToAll` is also used. | +| `relatedToAll` | `[Int]` | Narrows the query results to elements that relate to *all* of the provided element IDs. Using this argument will cause `relatedTo` argument to be ignored. | +| `ref` | `[String]` | Narrows the query results based on a reference string. | +| `fixedOrder` | `Boolean` | Causes the query results to be returned in the order specified by the `id` argument. | +| `inReverse` | `Boolean` | Causes the query results to be returned in reverse order. | +| `dateCreated` | `[String]` | Narrows the query results based on the elements’ creation dates. | +| `dateUpdated` | `[String]` | Narrows the query results based on the elements’ last-updated dates. | +| `offset` | `Int` | Sets the offset for paginated results. | +| `limit` | `Int` | Sets the limit for paginated results. | +| `orderBy` | `String` | Sets the field the returned elements should be ordered by | +| `withStructure` | `Boolean` | Explicitly determines whether the query should join in the structure data. | +| `structureId` | `Int` | Determines which structure data should be joined into the query. | +| `level` | `Int` | Narrows the query results based on the elements’ level within the structure. | +| `hasDescendants` | `Boolean` | Narrows the query results based on whether the elements have any descendants. | +| `ancestorOf` | `Int` | Narrows the query results to only elements that are ancestors of another element. | +| `ancestorDist` | `Int` | Narrows the query results to only elements that are up to a certain distance away from the element specified by `ancestorOf`. | +| `descendantOf` | `Int` | Narrows the query results to only elements that are descendants of another element. | +| `descendantDist` | `Int` | Narrows the query results to only elements that are up to a certain distance away from the element specified by `descendantOf`. | +| `leaves` | `Boolean` | Narrows the query results based on whether the elements are “leaves” (element with no descendants). | +| `nextSiblingOf` | `Int` | Narrows the query results to only the entry that comes immediately after another element. | +| `prevSiblingOf` | `Int` | Narrows the query results to only the entry that comes immediately before another element. | +| `positionedAfter` | `Int` | Narrows the query results to only entries that are positioned after another element. | +| `positionedBefore` | `Int` | Narrows the query results to only entries that are positioned before another element. | +| `editable` | `Boolean` | Whether to only return categories that the user has permission to edit. | +| `group` | `[String]` | Narrows the query results based on the category groups the categories belong to per the group’s handles. | +| `groupId` | `[QueryArgument]` | Narrows the query results based on the category groups the categories belong to, per the groups’ IDs. | + +### The `category` query +This query is used to query for a single category. +| Argument | Type | Description | +| ------------------ | ----------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `id` | `[QueryArgument]` | Narrows the query results based on the elements’ IDs. | +| `uid` | `[String]` | Narrows the query results based on the elements’ UIDs. | +| `status` | `[String]` | Narrows the query results based on the elements’ statuses. | +| `archived` | `Boolean` | Narrows the query results to only elements that have been archived. | +| `trashed` | `Boolean` | Narrows the query results to only elements that have been soft-deleted. | +| `site` | `[String]` | Determines which site(s) the elements should be queried in. Defaults to the current (requested) site. | +| `siteId` | `String` | Determines which site(s) the elements should be queried in. Defaults to the current (requested) site. | +| `unique` | `Boolean` | Determines whether only elements with unique IDs should be returned by the query. | +| `enabledForSite` | `Boolean` | Narrows the query results based on whether the elements are enabled in the site they’re being queried in, per the `site` argument. | +| `title` | `[String]` | Narrows the query results based on the elements’ titles. | +| `slug` | `[String]` | Narrows the query results based on the elements’ slugs. | +| `uri` | `[String]` | Narrows the query results based on the elements’ URIs. | +| `search` | `String` | Narrows the query results to only elements that match a search query. | +| `relatedTo` | `[Int]` | Narrows the query results to elements that relate to *any* of the provided element IDs. This argument is ignored, if `relatedToAll` is also used. | +| `relatedToAll` | `[Int]` | Narrows the query results to elements that relate to *all* of the provided element IDs. Using this argument will cause `relatedTo` argument to be ignored. | +| `ref` | `[String]` | Narrows the query results based on a reference string. | +| `fixedOrder` | `Boolean` | Causes the query results to be returned in the order specified by the `id` argument. | +| `inReverse` | `Boolean` | Causes the query results to be returned in reverse order. | +| `dateCreated` | `[String]` | Narrows the query results based on the elements’ creation dates. | +| `dateUpdated` | `[String]` | Narrows the query results based on the elements’ last-updated dates. | +| `offset` | `Int` | Sets the offset for paginated results. | +| `limit` | `Int` | Sets the limit for paginated results. | +| `orderBy` | `String` | Sets the field the returned elements should be ordered by | +| `withStructure` | `Boolean` | Explicitly determines whether the query should join in the structure data. | +| `structureId` | `Int` | Determines which structure data should be joined into the query. | +| `level` | `Int` | Narrows the query results based on the elements’ level within the structure. | +| `hasDescendants` | `Boolean` | Narrows the query results based on whether the elements have any descendants. | +| `ancestorOf` | `Int` | Narrows the query results to only elements that are ancestors of another element. | +| `ancestorDist` | `Int` | Narrows the query results to only elements that are up to a certain distance away from the element specified by `ancestorOf`. | +| `descendantOf` | `Int` | Narrows the query results to only elements that are descendants of another element. | +| `descendantDist` | `Int` | Narrows the query results to only elements that are up to a certain distance away from the element specified by `descendantOf`. | +| `leaves` | `Boolean` | Narrows the query results based on whether the elements are “leaves” (element with no descendants). | +| `nextSiblingOf` | `Int` | Narrows the query results to only the entry that comes immediately after another element. | +| `prevSiblingOf` | `Int` | Narrows the query results to only the entry that comes immediately before another element. | +| `positionedAfter` | `Int` | Narrows the query results to only entries that are positioned after another element. | +| `positionedBefore` | `Int` | Narrows the query results to only entries that are positioned before another element. | +| `editable` | `Boolean` | Whether to only return categories that the user has permission to edit. | +| `group` | `[String]` | Narrows the query results based on the category groups the categories belong to per the group’s handles. | +| `groupId` | `[QueryArgument]` | Narrows the query results based on the category groups the categories belong to, per the groups’ IDs. | + + ## List of available directives Directives are not regulated by permissions and they affect how the returned data is displayed. + + ### The `formatDateTime` directive This directive allows for formatting any date to the desired format. It can be applied to all fields, but changes anything only when applied to a DateTime field. +| Argument | Type | Description | +| ---------- | -------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `format` | `String` | This specifies the format to use. It defaults to the [Atom date time format](https://www.php.net/manual/en/class.datetimeinterface.php#datetime.constants.atom]). | +| `timezone` | `String` | The full name of the timezone, defaults to UTC. (E.g., America/New_York) | -#### The `format` argument -This specifies the format to use. It defaults to the [Atom date time format](https://www.php.net/manual/en/class.datetimeinterface.php#datetime.constants.atom]). - -#### The `timezone` argument -The full name of the timezone, defaults to UTC. (E.g., America/New_York) ### The `transform` directive This directive is used to return a URL for an [asset tranform](https://docs.craftcms.com/v3/image-transforms.html). It accepts the same arguments you would use for a transform in Craft and adds the `immediately` argument. +| Argument | Type | Description | +| ------------- | --------- | ---------------------------------------------------------------------------------------------------------------- | +| `handle` | `String` | The handle of the named transform to use. | +| `transform` | `String` | The handle of the named transform to use. | +| `width` | `Int` | Width for the generated transform | +| `height` | `Int` | Height for the generated transform | +| `mode` | `String` | The mode to use for the generated transform. | +| `position` | `String` | The position to use when cropping, if no focal point specified. | +| `interlace` | `String` | The interlace mode to use for the transform | +| `quality` | `Int` | The quality of the transform | +| `format` | `String` | The format to use for the transform | +| `immediately` | `Boolean` | Whether the transform should be generated immediately or only when the image is requested used the generated URL | -#### The `handle` argument -The handle of the named transform to use. - -#### The `width` argument -Width for the generated transform - -#### The `height` argument -Height for the generated transform - -#### The `mode` argument -The mode to use for the generated transform. - -#### The `position` argument -The position to use when cropping, if no focal point specified. - -#### The `interlace` argument -The interlace mode to use for the transform - -#### The `quality` argument -The quality of the transform - -#### The `format` argument -The format to use for the transform - -#### The `immediately` argument -Whether the transform should be generated immediately or only when the image is requested used the generated URL ### The `markdown` directive Parses the passed field value as Markdown. +| Argument | Type | Description | +| -------- | -------- | ------------------------------------------------------------------------------------------------------------------------------- | +| `flavor` | `String` | The “flavor” of Markdown the input should be interpreted with. Accepts the same arguments as yii\helpers\Markdown::process(). | -#### The `flavor` argument -The “flavor” of Markdown the input should be interpreted with. Accepts the same arguments as yii\helpers\Markdown::process(). + ## Pre-defined interfaces Craft defines several interfaces to be implemented by the different GraphQL types. + + ### The `AssetInterface` interface This is the interface implemented by all assets. +| Field | Type | Description | +| --------------- | ---------- | --------------------------------------------------------------------------------------------- | +| `id` | `ID` | The id of the entity | +| `uid` | `String` | The uid of the entity | +| `_count` | `Int` | Return a number of related elements for a field. | +| `title` | `String` | The element’s title. | +| `slug` | `String` | The element’s slug. | +| `uri` | `String` | The element’s URI. | +| `enabled` | `Boolean` | Whether the element is enabled or not. | +| `archived` | `Boolean` | Whether the element is archived or not. | +| `siteId` | `Int` | The ID of the site the element is associated with. | +| `searchScore` | `String` | The element’s search score, if the `search` parameter was used when querying for the element. | +| `trashed` | `Boolean` | Whether the element has been soft-deleted or not. | +| `status` | `String` | The element's status. | +| `dateCreated` | `DateTime` | The date the element was created. | +| `dateUpdated` | `DateTime` | The date the element was last updated. | +| `volumeId` | `Int` | The ID of the volume that the asset belongs to. | +| `folderId` | `Int` | The ID of the folder that the asset belongs to. | +| `filename` | `String` | The filename of the asset file. | +| `extension` | `String` | The file extension for the asset file. | +| `hasFocalPoint` | `Boolean` | Whether a user-defined focal point is set on the asset. | +| `focalPoint` | `[Float]` | The focal point represented as an array with `x` and `y` keys, or null if it's not an image. | +| `kind` | `String` | The file kind. | +| `size` | `String` | The file size in bytes. | +| `height` | `Int` | The height in pixels or null if it's not an image. | +| `width` | `Int` | The width in pixels or null if it's not an image. | +| `img` | `String` | An `` tag based on this asset. | +| `url` | `String` | The full URL of the asset. This field accepts the same fields as the `transform` directive. | +| `mimeType` | `String` | The file’s MIME type, if it can be determined. | +| `path` | `String` | The asset's path in the volume. | +| `dateModified` | `DateTime` | The date the asset file was last modified. | -#### The `id` field -The id of the entity - -#### The `uid` field -The uid of the entity - -#### The `title` field -The element’s title. - -#### The `slug` field -The element’s slug. - -#### The `uri` field -The element’s URI. - -#### The `enabled` field -Whether the element is enabled or not. - -#### The `archived` field -Whether the element is archived or not. - -#### The `siteId` field -The ID of the site the element is associated with. - -#### The `searchScore` field -The element’s search score, if the `search` parameter was used when querying for the element. - -#### The `trashed` field -Whether the element has been soft-deleted or not. - -#### The `status` field -The element's status. - -#### The `dateCreated` field -The date the element was created. - -#### The `dateUpdated` field -The date the element was last updated. - -#### The `volumeId` field -The ID of the volume that the asset belongs to. - -#### The `folderId` field -The ID of the folder that the asset belongs to. - -#### The `filename` field -The filename of the asset file. - -#### The `extension` field -The file extension for the asset file. - -#### The `hasFocalPoint` field -Whether a user-defined focal point is set on the asset. - -#### The `focalPoint` field -The focal point represented as an array with `x` and `y` keys, or null if it's not an image. - -#### The `kind` field -The file kind. - -#### The `size` field -The file size in bytes. - -#### The `height` field -The height in pixels or null if it's not an image. - -#### The `width` field -The width in pixels or null if it's not an image. - -#### The `img` field -An `` tag based on this asset. - -#### The `url` field -The full URL of the asset. This field accepts the same fields as the `transform` directive. - -#### The `mimeType` field -The file’s MIME type, if it can be determined. - -#### The `path` field -The asset's path in the volume. - -#### The `dateModified` field -The date the asset file was last modified. ### The `EntryInterface` interface This is the interface implemented by all entries. +| Field | Type | Description | +| --------------- | ------------------ | ------------------------------------------------------------------------------------------------------- | +| `id` | `ID` | The id of the entity | +| `uid` | `String` | The uid of the entity | +| `_count` | `Int` | Return a number of related elements for a field. | +| `title` | `String` | The element’s title. | +| `slug` | `String` | The element’s slug. | +| `uri` | `String` | The element’s URI. | +| `enabled` | `Boolean` | Whether the element is enabled or not. | +| `archived` | `Boolean` | Whether the element is archived or not. | +| `siteId` | `Int` | The ID of the site the element is associated with. | +| `searchScore` | `String` | The element’s search score, if the `search` parameter was used when querying for the element. | +| `trashed` | `Boolean` | Whether the element has been soft-deleted or not. | +| `status` | `String` | The element's status. | +| `dateCreated` | `DateTime` | The date the element was created. | +| `dateUpdated` | `DateTime` | The date the element was last updated. | +| `lft` | `Int` | The element’s left position within its structure. | +| `rgt` | `Int` | The element’s right position within its structure. | +| `level` | `Int` | The element’s level within its structure | +| `root` | `Int` | The element’s structure’s root ID | +| `structureId` | `Int` | The element’s structure ID. | +| `sectionId` | `Int` | The ID of the section that contains the entry. | +| `sectionHandle` | `String` | The handle of the section that contains the entry. | +| `typeId` | `Int` | The ID of the entry type that contains the entry. | +| `typeHandle` | `String` | The handle of the entry type that contains the entry. | +| `postDate` | `DateTime` | The entry's post date. | +| `expiryDate` | `DateTime` | The expiry date of the entry. | +| `children` | `[EntryInterface]` | The entry’s children, if the section is a structure. Accepts the same arguments as the `entries` query. | +| `parent` | `EntryInterface` | The entry’s parent, if the section is a structure. | +| `url` | `String` | The element’s full URL | -#### The `id` field -The id of the entity - -#### The `uid` field -The uid of the entity - -#### The `title` field -The element’s title. - -#### The `slug` field -The element’s slug. - -#### The `uri` field -The element’s URI. - -#### The `enabled` field -Whether the element is enabled or not. - -#### The `archived` field -Whether the element is archived or not. - -#### The `siteId` field -The ID of the site the element is associated with. - -#### The `searchScore` field -The element’s search score, if the `search` parameter was used when querying for the element. - -#### The `trashed` field -Whether the element has been soft-deleted or not. - -#### The `status` field -The element's status. - -#### The `dateCreated` field -The date the element was created. - -#### The `dateUpdated` field -The date the element was last updated. - -#### The `lft` field -The element’s left position within its structure. - -#### The `rgt` field -The element’s right position within its structure. - -#### The `level` field -The element’s level within its structure - -#### The `root` field -The element’s structure’s root ID - -#### The `structureId` field -The element’s structure ID. - -#### The `sectionId` field -The ID of the section that contains the entry. - -#### The `sectionHandle` field -The handle of the section that contains the entry. - -#### The `typeId` field -The ID of the entry type that contains the entry. - -#### The `typeHandle` field -The handle of the entry type that contains the entry. - -#### The `authorId` field -The ID of the author of this entry. - -#### The `author` field -The entry's author. - -#### The `postDate` field -The entry's post date. - -#### The `expiryDate` field -The expiry date of the entry. - -#### The `children` field -The entry’s children, if the section is a structure. Accepts the same arguments as the `entries` query. - -#### The `parent` field -The entry’s parent, if the section is a structure. ### The `GlobalSetInterface` interface This is the interface implemented by all global sets. +| Field | Type | Description | +| ------------- | ---------- | --------------------------------------------------------------------------------------------- | +| `id` | `ID` | The id of the entity | +| `uid` | `String` | The uid of the entity | +| `_count` | `Int` | Return a number of related elements for a field. | +| `title` | `String` | The element’s title. | +| `slug` | `String` | The element’s slug. | +| `uri` | `String` | The element’s URI. | +| `enabled` | `Boolean` | Whether the element is enabled or not. | +| `archived` | `Boolean` | Whether the element is archived or not. | +| `siteId` | `Int` | The ID of the site the element is associated with. | +| `searchScore` | `String` | The element’s search score, if the `search` parameter was used when querying for the element. | +| `trashed` | `Boolean` | Whether the element has been soft-deleted or not. | +| `status` | `String` | The element's status. | +| `dateCreated` | `DateTime` | The date the element was created. | +| `dateUpdated` | `DateTime` | The date the element was last updated. | +| `name` | `String` | The name of the global set. | +| `handle` | `String` | The handle of the global set. | -#### The `id` field -The id of the entity - -#### The `uid` field -The uid of the entity - -#### The `title` field -The element’s title. - -#### The `slug` field -The element’s slug. - -#### The `uri` field -The element’s URI. - -#### The `enabled` field -Whether the element is enabled or not. - -#### The `archived` field -Whether the element is archived or not. - -#### The `siteId` field -The ID of the site the element is associated with. - -#### The `searchScore` field -The element’s search score, if the `search` parameter was used when querying for the element. - -#### The `trashed` field -Whether the element has been soft-deleted or not. - -#### The `status` field -The element's status. - -#### The `dateCreated` field -The date the element was created. - -#### The `dateUpdated` field -The date the element was last updated. - -#### The `name` field -The name of the global set. - -#### The `handle` field -The handle of the global set. ### The `MatrixBlockInterface` interface This is the interface implemented by all matrix blocks. +| Field | Type | Description | +| ------------- | ---------- | --------------------------------------------------------------------------------------------- | +| `id` | `ID` | The id of the entity | +| `uid` | `String` | The uid of the entity | +| `_count` | `Int` | Return a number of related elements for a field. | +| `title` | `String` | The element’s title. | +| `slug` | `String` | The element’s slug. | +| `uri` | `String` | The element’s URI. | +| `enabled` | `Boolean` | Whether the element is enabled or not. | +| `archived` | `Boolean` | Whether the element is archived or not. | +| `siteId` | `Int` | The ID of the site the element is associated with. | +| `searchScore` | `String` | The element’s search score, if the `search` parameter was used when querying for the element. | +| `trashed` | `Boolean` | Whether the element has been soft-deleted or not. | +| `status` | `String` | The element's status. | +| `dateCreated` | `DateTime` | The date the element was created. | +| `dateUpdated` | `DateTime` | The date the element was last updated. | +| `fieldId` | `Int` | The ID of the field that owns the matrix block. | +| `ownerId` | `Int` | The ID of the element that owns the matrix block. | +| `typeId` | `Int` | The ID of the matrix block's type. | +| `typeHandle` | `String` | The handle of the matrix block's type. | +| `sortOrder` | `Int` | The sort order of the matrix block within the owner element field. | -#### The `id` field -The id of the entity - -#### The `uid` field -The uid of the entity - -#### The `title` field -The element’s title. - -#### The `slug` field -The element’s slug. - -#### The `uri` field -The element’s URI. - -#### The `enabled` field -Whether the element is enabled or not. - -#### The `archived` field -Whether the element is archived or not. - -#### The `siteId` field -The ID of the site the element is associated with. - -#### The `searchScore` field -The element’s search score, if the `search` parameter was used when querying for the element. - -#### The `trashed` field -Whether the element has been soft-deleted or not. - -#### The `status` field -The element's status. - -#### The `dateCreated` field -The date the element was created. - -#### The `dateUpdated` field -The date the element was last updated. - -#### The `fieldId` field -The ID of the field that owns the matrix block. - -#### The `ownerId` field -The ID of the element that owns the matrix block. - -#### The `typeId` field -The ID of the matrix block's type. - -#### The `typeHandle` field -The handle of the matrix block's type. - -#### The `sortOrder` field -The sort order of the matrix block within the owner element field. ### The `UserInterface` interface This is the interface implemented by all users. +| Field | Type | Description | +| ------------------- | ---------------- | --------------------------------------------------------------------------------------------- | +| `id` | `ID` | The id of the entity | +| `uid` | `String` | The uid of the entity | +| `_count` | `Int` | Return a number of related elements for a field. | +| `title` | `String` | The element’s title. | +| `slug` | `String` | The element’s slug. | +| `uri` | `String` | The element’s URI. | +| `enabled` | `Boolean` | Whether the element is enabled or not. | +| `archived` | `Boolean` | Whether the element is archived or not. | +| `siteId` | `Int` | The ID of the site the element is associated with. | +| `searchScore` | `String` | The element’s search score, if the `search` parameter was used when querying for the element. | +| `trashed` | `Boolean` | Whether the element has been soft-deleted or not. | +| `status` | `String` | The element's status. | +| `dateCreated` | `DateTime` | The date the element was created. | +| `dateUpdated` | `DateTime` | The date the element was last updated. | +| `photo` | `AssetInterface` | The user's photo. | +| `friendlyName` | `String` | The user's first name or username. | +| `fullName` | `String` | The user's full name. | +| `name` | `String` | The user's full name or username. | +| `preferences` | `String` | The user’s preferences. | +| `preferredLanguage` | `String` | The user’s preferred language. | +| `username` | `String` | The username. | +| `firstName` | `String` | The user's first name. | +| `lastName` | `String` | The user's last name. | +| `email` | `String` | The user's email. | -#### The `id` field -The id of the entity - -#### The `uid` field -The uid of the entity - -#### The `title` field -The element’s title. - -#### The `slug` field -The element’s slug. - -#### The `uri` field -The element’s URI. - -#### The `enabled` field -Whether the element is enabled or not. - -#### The `archived` field -Whether the element is archived or not. - -#### The `siteId` field -The ID of the site the element is associated with. - -#### The `searchScore` field -The element’s search score, if the `search` parameter was used when querying for the element. - -#### The `trashed` field -Whether the element has been soft-deleted or not. - -#### The `status` field -The element's status. - -#### The `dateCreated` field -The date the element was created. - -#### The `dateUpdated` field -The date the element was last updated. - -#### The `friendlyName` field -The user's first name or username. - -#### The `fullName` field -The user's full name. - -#### The `name` field -The user's full name or username. - -#### The `photo` field -The user's photo. - -#### The `preferences` field -The user’s preferences. - -#### The `preferredLanguage` field -The user’s preferred language. - -#### The `username` field -The username. - -#### The `firstName` field -The user's first name. - -#### The `lastName` field -The user's last name. - -#### The `email` field -The user's email. ### The `CategoryInterface` interface This is the interface implemented by all categories. +| Field | Type | Description | +| ------------- | --------------------- | --------------------------------------------------------------------------------------------- | +| `id` | `ID` | The id of the entity | +| `uid` | `String` | The uid of the entity | +| `_count` | `Int` | Return a number of related elements for a field. | +| `title` | `String` | The element’s title. | +| `slug` | `String` | The element’s slug. | +| `uri` | `String` | The element’s URI. | +| `enabled` | `Boolean` | Whether the element is enabled or not. | +| `archived` | `Boolean` | Whether the element is archived or not. | +| `siteId` | `Int` | The ID of the site the element is associated with. | +| `searchScore` | `String` | The element’s search score, if the `search` parameter was used when querying for the element. | +| `trashed` | `Boolean` | Whether the element has been soft-deleted or not. | +| `status` | `String` | The element's status. | +| `dateCreated` | `DateTime` | The date the element was created. | +| `dateUpdated` | `DateTime` | The date the element was last updated. | +| `lft` | `Int` | The element’s left position within its structure. | +| `rgt` | `Int` | The element’s right position within its structure. | +| `level` | `Int` | The element’s level within its structure | +| `root` | `Int` | The element’s structure’s root ID | +| `structureId` | `Int` | The element’s structure ID. | +| `groupId` | `Int` | The ID of the group that contains the category. | +| `groupHandle` | `String` | The handle of the group that contains the category. | +| `children` | `[CategoryInterface]` | The category’s children. | +| `parent` | `CategoryInterface` | The category’s parent. | +| `url` | `String` | The element’s full URL | -#### The `id` field -The id of the entity - -#### The `uid` field -The uid of the entity - -#### The `title` field -The element’s title. - -#### The `slug` field -The element’s slug. - -#### The `uri` field -The element’s URI. - -#### The `enabled` field -Whether the element is enabled or not. - -#### The `archived` field -Whether the element is archived or not. - -#### The `siteId` field -The ID of the site the element is associated with. - -#### The `searchScore` field -The element’s search score, if the `search` parameter was used when querying for the element. - -#### The `trashed` field -Whether the element has been soft-deleted or not. - -#### The `status` field -The element's status. - -#### The `dateCreated` field -The date the element was created. - -#### The `dateUpdated` field -The date the element was last updated. - -#### The `lft` field -The element’s left position within its structure. - -#### The `rgt` field -The element’s right position within its structure. - -#### The `level` field -The element’s level within its structure - -#### The `root` field -The element’s structure’s root ID - -#### The `structureId` field -The element’s structure ID. - -#### The `groupId` field -The ID of the group that contains the category. - -#### The `groupHandle` field -The handle of the group that contains the category. - -#### The `children` field -The category’s children. - -#### The `parent` field -The category’s parent. ### The `TagInterface` interface This is the interface implemented by all tags. +| Field | Type | Description | +| ------------- | ---------- | --------------------------------------------------------------------------------------------- | +| `id` | `ID` | The id of the entity | +| `uid` | `String` | The uid of the entity | +| `_count` | `Int` | Return a number of related elements for a field. | +| `title` | `String` | The element’s title. | +| `slug` | `String` | The element’s slug. | +| `uri` | `String` | The element’s URI. | +| `enabled` | `Boolean` | Whether the element is enabled or not. | +| `archived` | `Boolean` | Whether the element is archived or not. | +| `siteId` | `Int` | The ID of the site the element is associated with. | +| `searchScore` | `String` | The element’s search score, if the `search` parameter was used when querying for the element. | +| `trashed` | `Boolean` | Whether the element has been soft-deleted or not. | +| `status` | `String` | The element's status. | +| `dateCreated` | `DateTime` | The date the element was created. | +| `dateUpdated` | `DateTime` | The date the element was last updated. | +| `groupId` | `Int` | The ID of the group that contains the tag. | +| `groupHandle` | `String` | The handle of the group that contains the tag. | + + -#### The `id` field -The id of the entity - -#### The `uid` field -The uid of the entity - -#### The `title` field -The element’s title. - -#### The `slug` field -The element’s slug. - -#### The `uri` field -The element’s URI. - -#### The `enabled` field -Whether the element is enabled or not. - -#### The `archived` field -Whether the element is archived or not. - -#### The `siteId` field -The ID of the site the element is associated with. - -#### The `searchScore` field -The element’s search score, if the `search` parameter was used when querying for the element. - -#### The `trashed` field -Whether the element has been soft-deleted or not. - -#### The `status` field -The element's status. - -#### The `dateCreated` field -The date the element was created. - -#### The `dateUpdated` field -The date the element was last updated. - -#### The `groupId` field -The ID of the group that contains the tag. - -#### The `groupHandle` field -The handle of the group that contains the tag. - -## Interface Implementation - -A defined type exists for each specific interface implementation. For example, if a “News” section has “Article” and “Editorial” entry types, in addition to the `EntryInterface` interface type, two additional types would be defined the GraphQL schema, if the token used allows it: `news_article_Entry` and `news_editorial_Entry` types. - -## An example query and response - -### Query payload - -```graphql -curl \ - -H "Authorization: Bearer xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" \ - -H "Content-Type: application/graphql" \ - -d '{entries{id}}' \ - http://my-project.test/api -``` - -### The response - -```json -{ - queryEntries (section: "news", limit: 2, orderBy: "dateCreated DESC"){ - dateCreated @formatDateTime (format: "Y-m-d") - title - children { - title - } - ... on news_article_Entry { - shortDescription - featuredImage { - url @transform (width: 300, immediately: true) - } - } - } -} -``` From 9c41704f21108cf4bcf909abfe70f2a602e90211 Mon Sep 17 00:00:00 2001 From: Brad Bell Date: Fri, 12 Jun 2020 17:32:49 -0700 Subject: [PATCH 041/245] New translations image-transforms.md (French) --- fr/image-transforms.md | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/fr/image-transforms.md b/fr/image-transforms.md index b8c1d09fb82..38791faba54 100644 --- a/fr/image-transforms.md +++ b/fr/image-transforms.md @@ -4,7 +4,7 @@ Rather than requiring that everyone upload images at a certain size, Craft lets ## Defining Transforms from the Control Panel -You can define transforms from the Control Panel by going to Settings → Assets → Image Transforms and clicking the “New Transform” button. +You can define transforms from the control panel by going to Settings → Assets → Image Transforms and clicking the “New Transform” button. Each transform has the following settings: @@ -58,7 +58,7 @@ To output an image with a transform applied, simply pass your transform’s hand You can also define transforms directly in your templates. -First, you must create an object that defines the transform’s parameters: +First, you must create a [hash](dev/twig-primer.md#hashes) that defines the transform’s parameters: ```twig {% set thumb = { @@ -70,13 +70,13 @@ First, you must create an object that defines the transform’s parameters: } %} ``` -Then you can pass that object into your asset’s `getUrl()`, `getWidth()`, and `getHeight()` functions: +Then you can pass that hash into your asset’s `getUrl()`, `getWidth()`, and `getHeight()` functions: ```twig ``` -Note how in that example there are no quotes around “`thumb`”, like there were in the first one. That’s because in the first one, we were passing a *string* set to a CP-defined transform’s handle, whereas in this example we’re passing a *variable* referencing the ‘thumb’ object we created within the template. +Note how in that example there are no quotes around “`thumb`”, like there were in the first one. That’s because in the first one, we were passing a [string](dev/twig-primer.md#strings) set to a CP-defined transform’s handle, whereas in this example we’re passing a [variable](dev/twig-primer.md#variables) referencing the `thumb` hash we created within the template. ### Possible Values From b456ef3eb3352034bc701af604d8ec09e888d0e5 Mon Sep 17 00:00:00 2001 From: Brad Bell Date: Fri, 12 Jun 2020 17:32:51 -0700 Subject: [PATCH 042/245] New translations image-transforms.md (Japanese) --- ja/image-transforms.md | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/ja/image-transforms.md b/ja/image-transforms.md index 5d2ee6e8754..2b4de6b9730 100644 --- a/ja/image-transforms.md +++ b/ja/image-transforms.md @@ -4,7 +4,7 @@ ## コントロールパネルからトランスフォームの定義 -「設定 > アセット > 画像の変形」に移動し、「新しい画像変換」ボタンをクリックすることで、コントロールパネルからトランスフォームを定義することができます。 +You can define transforms from the control panel by going to Settings → Assets → Image Transforms and clicking the “New Transform” button. トランスフォームには、次の設定があります。 @@ -58,7 +58,7 @@ If you leave **Quality** blank, Craft will use the quality set by your ``` -ここでは、最初の例のように「`thumb`」の周りに引用符がないことに注意してください。最初の例では、CP で定義されたトランスフォームのハンドルを _文字列_ として渡しているのに対して、この例ではテンプレート内で作成した ‘thumb’ オブジェクトを参照するための _変数_ として渡しています。 +Note how in that example there are no quotes around “`thumb`”, like there were in the first one. That’s because in the first one, we were passing a [string](dev/twig-primer.md#strings) set to a CP-defined transform’s handle, whereas in this example we’re passing a [variable](dev/twig-primer.md#variables) referencing the `thumb` hash we created within the template. ### 利用可能な値 From 5d6d8fec11169d3a68f403bf83847bb676d6b1d2 Mon Sep 17 00:00:00 2001 From: Brad Bell Date: Fri, 12 Jun 2020 17:32:53 -0700 Subject: [PATCH 043/245] New translations installation.md (French) --- fr/installation.md | 12 ++++++++---- 1 file changed, 8 insertions(+), 4 deletions(-) diff --git a/fr/installation.md b/fr/installation.md index e735a58de94..54d0fc68fc0 100644 --- a/fr/installation.md +++ b/fr/installation.md @@ -26,8 +26,8 @@ Composer will take a couple minutes to load everything. Once it’s done you wil Download the archive format you prefer to work with: -- **zip**: [3.3.20.1](https://download.craftcdn.com/craft/3.3/Craft-3.3.20.1.zip), [latest](https://craftcms.com/latest-v3.zip) -- **tar.gz**: [3.3.20.1](https://download.craftcdn.com/craft/3.3/Craft-3.3.20.1.tar.gz), [latest](https://craftcms.com/latest-v3.tar.gz) +- [zip](https://craftcms.com/latest-v3.zip) +- [tar.gz](https://craftcms.com/latest-v3.tar.gz) Extract the archive wherever you want your new Craft project to live. @@ -142,6 +142,10 @@ If you’re not using [MAMP](https://mamp.info) or another localhosting tool, yo You can test whether you set everything up correctly by pointing your web browser to `http:///index.php?p=admin/install` (substituting `` with your web server’s host name). If Craft’s Setup Wizard is shown, the host name is correctly resolving to your Craft installation. +::: tip +We recommend using the `.test` TLD for local development, and specifically not `.local` on macOS since [conflicts with Bonjour can lead to performance issues](https://help.rm.com/technicalarticle.asp?cref=tec3015691). +::: + ## Step 6: Run the Setup Wizard Finally, it’s time to run Craft’s Setup Wizard. You can either run that from your [terminal](#terminal-setup) or your [web browser](#web-browser-setup). @@ -174,7 +178,7 @@ If the Setup Wizard skips this step, it’s because Craft is already able to con ![Craft Installation Database Connection Information](./images/installation-step-2.png) -The third step of the installer is to create an admin account. Don’t be one of *those people* and be sure to pick a strong password. +The third step of the installer is to create an admin account. Don’t be one of _those people_ and be sure to pick a strong password. ![Craft Installation Create User Account](./images/installation-step-3.png) @@ -184,7 +188,7 @@ The final step is to define your System Name, Base URL, and Language. Click “Finish up” to complete the setup process. A few seconds later, you should have a working Craft install! -If it was successful, Craft will redirect your browser to the Control Panel. +If it was successful, Craft will redirect your browser to the control panel. ![Craft Installation Complete](./images/installation-step-5.png) From 3ebc6f815663fa160916340f77231ab66c04506c Mon Sep 17 00:00:00 2001 From: Brad Bell Date: Fri, 12 Jun 2020 17:32:55 -0700 Subject: [PATCH 044/245] New translations assets-fields.md (Japanese) --- ja/assets-fields.md | 121 +++++++++++++++++++++++++++++++++----------- 1 file changed, 91 insertions(+), 30 deletions(-) diff --git a/ja/assets-fields.md b/ja/assets-fields.md index eeee0fbaeeb..2d6830526db 100644 --- a/ja/assets-fields.md +++ b/ja/assets-fields.md @@ -41,37 +41,50 @@ ソースエレメント（アセットフィールドを持つエレメント）でサポートされているすべてのプロパティは、ここで使用できます。 ::: tip -[行列フィールド](matrix-fields.md)の中にアセットフィールドを作成する場合、ソースエレメントは作成された行列フィールドのエレメント _ではなく_ 行列ブロックになります。 +If you want to include the entry’s ID or UID in a dynamic subfolder path, use `{sourceId}` or `{sourceUid}` rather than `{id}` or `{uid}`, so the source entry’s ID or UID is used rather than the revision / draft’s. +::: + +::: tip +If you are creating the Assets field within a [Matrix field](matrix-fields.md), the source element is going to be the Matrix block, _not_ the element that the Matrix field is being created on. -そのため、行列フィールドがエントリに紐づけられていて、動的なサブフォルダパスにエントリ ID を出力したい場合、`id` ではなく `owner.id` を使用します。 +So if your Matrix field is attached to an entry, and you want to output the entry ID in your dynamic subfolder path, use `owner.id` rather than `id`. ::: ## フィールド -アセットフィールドには、現在関連付けられているすべてのアセットのリストと、新しいアセットを追加するためのボタンがあります。 +Assets fields list all of the currently-related assets, with a button to select new ones. + +Clicking the “Add an asset” button will bring up a modal window where you can find and select additional assets, as well as upload new ones. -「アセットを追加」ボタンをクリックすると、新しいアセットのアップロードはもちろん、すでに追加されているアセットの検索や選択ができるモーダルウィンドウが表示されます。 +::: tip +You can also upload assets by dragging files directly onto the assets field or modal window. +::: ### インラインのアセット編集 -関連付けられたアセットをダブルクリックすると、アセットのタイトルやカスタムフィールドを編集したり、（画像の場合）イメージエディタを起動できる HUD を表示します。 +When you double-click on a related asset, a HUD will appear where you can edit the asset’s title and custom fields, and launch the Image Editor (if it’s an image). ::: tip -アセットで使用するカスタムフィールドは、「設定 > アセット > [ボリューム名] > フィールドレイアウト」から選択できます。 +You can choose which custom fields should be available for your assets from Settings → Assets → [Volume Name] → Field Layout. ::: ## テンプレート記法 ### アセットフィールドによるエレメントの照会 -アセットフィールドを持つ[エレメントを照会](dev/element-queries/README.md)する場合、フィールドのハンドルにちなんで名付けられたクエリパラメータを使用して、アセットフィールドのデータに基づいた結果をフィルタできます。 +When [querying for elements](dev/element-queries/README.md) that have an Assets field, you can filter the results based on the Assets field data using a query param named after your field’s handle. -利用可能な値には、次のものが含まれます。 +Possible values include: -| 値 | 取得するエレメント | -| -------------- | ----------------------- | -| `':empty:'` | 関連付けられたアセットを持たない。 | -| `':notempty:'` | 少なくとも1つの関連付けられたアセットを持つ。 | +| 値 | 取得するエレメント | +| ----------------------------------------------------------- | ------------------------------------------------------- | +| `':empty:'` | 関連付けられたアセットを持たない。 | +| `':notempty:'` | 少なくとも1つの関連付けられたアセットを持つ。 | +| `100` | that are related to the asset with an ID of 100. | +| `[100, 200]` | that are related to an asset with an ID of 100 or 200. | +| `['and', 100, 200]` | that are related to the assets with IDs of 100 and 200. | +| an [Asset](api:craft\elements\Asset) object | that are related to the asset. | +| an [AssetQuery](api:craft\elements\db\AssetQuery) object | that are related to any of the resulting assets. | ```twig {# Fetch entries with a related asset #} @@ -82,15 +95,15 @@ ### アセットフィールドデータの操作 -テンプレート内でアセットフィールドのエレメントを取得する場合、アセットフィールドのハンドルを利用して関連付けられたアセットにアクセスできます。 +If you have an element with an Assets field in your template, you can access its related assets using your Assets field’s handle: ```twig {% set query = entry. %} ``` -これは、所定のフィールドで関連付けられたすべてのアセットを出力するよう準備された[アセットクエリ](dev/element-queries/asset-queries.md)を提供します。 +That will give you an [asset query](dev/element-queries/asset-queries.md), prepped to output all of the related assets for the given field. -関連付けられたすべてのアセットをループするには、[all()](api:craft\db\Query::all()) を呼び出して、結果をループ処理します。 +To loop through all of the related assets, call [all()](api:craft\db\Query::all()) and then loop over the results: ```twig {% set relatedAssets = entry..all() %} @@ -103,7 +116,11 @@ {% endif %} ``` -関連付けられた最初のアセットだけが欲しい場合、代わりに [one()](api:craft\db\Query::one()) を呼び出して、何かが返されていることを確認します。 +::: warning +When using `asset.url` or `asset.getUrl()`, the asset’s source volume must have “Assets in this volume have public URLs” enabled and a “Base URL” setting. Otherwise, the result will always be empty. +::: + +If you only want the first related asset, call [one()](api:craft\db\Query::one()) instead, and then make sure it returned something: ```twig {% set rel = entry..one() %} @@ -112,7 +129,7 @@ {% endif %} ``` -（取得する必要はなく）いずれかの関連付けられたアセットがあるかを確認したい場合、[exists()](api:craft\db\Query::exists()) を呼び出すことができます。 +If you just need to check if there are any related assets (but don’t need to fetch them), you can call [exists()](api:craft\db\Query::exists()): ```twig {% if entry..exists() %} @@ -120,7 +137,7 @@ {% endif %} ``` -アセットクエリで[パラメータ](dev/element-queries/asset-queries.md#parameters)をセットすることもできます。例えば、画像だけが返されることを保証するために、[kind](dev/element-queries/asset-queries.md#kind) パラメータをセットできます。 +You can set [parameters](dev/element-queries/asset-queries.md#parameters) on the asset query as well. For example, to ensure that only images are returned, you can set the [kind](dev/element-queries/asset-queries.md#kind) param: ```twig {% set relatedAssets = clone(entry.) @@ -128,30 +145,74 @@ .all() %} ``` -### フロントエンドの投稿フォームからのファイルアップロード +::: tip +It’s always a good idea to clone the asset query using the [clone()](./dev/functions.md#clone) function before adjusting its parameters, so the parameters don’t have unexpected consequences later on in your template. +::: -フロントエンドの[投稿フォーム](dev/examples/entry-form.md)から、アセットフィールドへのファイルアップロードをユーザーに許可するには、2つの調整が必要です。 +### Saving Assets Fields in Entry Forms -まず、`` タグに `enctype="multipart/form-data"` 属性があることを確認して、ファイルをアップロードできるようにします。 +If you have an [entry form](dev/examples/entry-form.md) that needs to contain an Assets field, you will need to submit your field value as a list of asset IDs, in the order you want them to be related. -```markup - +For example, you could create a list of checkboxes for each of the possible relations: + +```twig +{# Include a hidden input first so Craft knows to update the + existing value, if no checkboxes are checked. #} +{{ hiddenInput('fields[]', '') }} + +{# Get all of the possible asset options #} +{% set possibleAssets = craft.assets() + .volume('siteAssets') + .kind('image') + .orderBy('filename ASC') + .withTransforms([ + { width: 100, height: 100 } + ]) + .all() %} + +{# Get the currently related asset IDs #} +{% set relatedAssetIds = entry is defined + ? entry..ids() + : [] %} + +
    + {% for possibleAsset in possibleAssets %} +
  • + +
    • + {% endfor %} +
``` -次に、ファイル入力欄をフォームに追加します。 +You could then make the checkbox list sortable, so users have control over the order of related assets. -```markup - +#### Creating New Assets + +Assets fields can handle new file uploads as well: + +```twig +{{ input('file', 'fields[][]', options={ + multiple: true, +}) }} ``` ::: tip -`` を実際のフィールドハンドルに置き換えます。例えば、フィールドハンドルが “heroImage” の場合、input 名は `fields[heroImage]` になります。 +Don’t forget to set `enctype="multipart/form-data"` on your `` tag so your browser knows to submit the form as a multipart request. ::: -複数ファイルをアップロードできるようにする場合、`multiple` 属性を追加し、input 名の末尾に `[]` を追加します。 +Alternatively, you can submit Base64-encoded file data, which the Assets field will decode and treat as an uploaded file: -```markup - +```twig +{{ hiddenInput('fields[][]', 'data:image/jpeg;base64,') }} ``` ## 関連項目 From 52ed83aefff38fcd6e2c24f60cabfb9323224951 Mon Sep 17 00:00:00 2001 From: Brad Bell Date: Fri, 12 Jun 2020 17:32:57 -0700 Subject: [PATCH 045/245] New translations coc.md (Japanese) --- ja/coc.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/ja/coc.md b/ja/coc.md index 20be23ab6be..6f68e7cd20a 100644 --- a/ja/coc.md +++ b/ja/coc.md @@ -6,7 +6,7 @@ これはあなたがしてはいけないことすべてを網羅したリストではありません。むしろ、意図している「わたしたち自身や参加する技術的なコミュニティのすべてをより豊かにするためのガイドである」という精神を取り入れてください。 -Craft のコミュニティがコミュニケーションのために利用するすべての場所で、この行動規範はあてはまります。Craft Slack、Craft CMS Stack Exchange、GitHub、Twitter、Facebook、会合、カンファレンス、その他すべての関連するフォーラムを含みます。Craft チームが管理していない場所でこの行動規範に違反した場合、コミュニティに参加する資格があるかどうかの判断基準に悪影響を及ぼすでしょう。 +This code of conduct applies to all spaces used by the Craft community for communication. This includes Craft Discord, Craft CMS Stack Exchange, GitHub, Twitter, Facebook, meetups, conferences, and any other relevant forums. Violations of this code outside of any spaces managed by the Craft team will still affect a person’s ability to participate within them. もし誰かが行動規範に違反したと確信したなら、[craftcms.com/contact](https://craftcms.com/contact) から連絡してください。わたしたちはすべての報告を真剣に受け止め、かつ、あなたの身元は機密のままであるようにします。 From a7f712a2392eeae96062e029a75e686ca82fe904 Mon Sep 17 00:00:00 2001 From: Brad Bell Date: Fri, 12 Jun 2020 17:32:58 -0700 Subject: [PATCH 046/245] New translations README.md (Japanese) --- ja/README.md | 10 ++++++---- 1 file changed, 6 insertions(+), 4 deletions(-) diff --git a/ja/README.md b/ja/README.md index 2121dbd619c..34e0e8ba87d 100644 --- a/ja/README.md +++ b/ja/README.md @@ -4,7 +4,7 @@ Craft は、ウェブ上でさらなる独自のデジタル体験を創造す 特徴： -- コンテンツ制作や管理業務のための、直感的でユーザーフレンドリーなコントロールパネル。 +- An intuitive, user-friendly control panel for content creation and administrative tasks. - コンテンツやその消費方法については想定されていない、コンテンツのモデリングや[フロントエンド開発](dev/README.md)のための真っ新なアプローチです。 - クリックするだけの、何百という無料、および、商用[プラグイン](https://plugins.craftcms.com/)を備える組み込みのプラグインストア。 - [モジュールおよびプラグイン開発](extend/README.md)のための、強靭なフレームワーク。 @@ -29,8 +29,10 @@ Craft は [Yii 2](https://www.yiiframework.com/) をベースとするセルフ ## 打ち込む -Craft のコンテンツモデリングがどのように機能するのか詳しく知るには、[セクションとエントリ](sections-and-entries.md) および [フィールド](fields.md)を読んでください。 +If you’re new to Craft CMS the best place to start is [the tutorial](https://docs.craftcms.com/tutorial/). -Craft をインストールする準備ができたら、[サーバー要件](requirements.md) および [インストールガイド](installation.md)を読んでください。 +To start getting acquainted with how content modeling works in Craft, read [Sections and Entries](sections-and-entries.md) and [Fields](fields.md). -最後に、 サイトまたはアプリケーションのフロントエンドを構築する準備が整ったら[フロントエンド開発](dev/README.md)セクションを読んでください。 +Before installing, check out the [Server Requirements](requirements.md) and [Installation Instructions](installation.md). + +Finally, read the [Front-End Development](dev/README.md) section when you’re ready to start building out the front-end of your site or application. From 358be08a271ff94d5190778519602bfe618685b9 Mon Sep 17 00:00:00 2001 From: Brad Bell Date: Fri, 12 Jun 2020 17:33:00 -0700 Subject: [PATCH 047/245] New translations lightswitch-fields.md (French) --- fr/lightswitch-fields.md | 49 ++++++++++++++++++++++++++++++++++++---- 1 file changed, 45 insertions(+), 4 deletions(-) diff --git a/fr/lightswitch-fields.md b/fr/lightswitch-fields.md index d08e22dcde6..2b74fbc5422 100644 --- a/fr/lightswitch-fields.md +++ b/fr/lightswitch-fields.md @@ -2,16 +2,57 @@ Lightswitch fields give you a simple toggle input for times when all you need is a “Yes” or “No” answer. -## The Field - ## Templating -This field will either return a `1` or `0` from the database, so you can test if it is in the `on` position from a template like so: +### Querying Elements with Lightswitch Fields + +When [querying for elements](dev/element-queries/README.md) that have a Lightswitch field, you can filter the results based on the Lightswitch field data using a query param named after your field’s handle. + +Possible values include: + +| Value | Fetches elements… | +| ------------------------ | ---------------------------------- | +| `true` or `':notempty:'` | with an enabled Lightswitch value. | +| `false` or `':empty:'` | with a disabled Lightswitch value. | ```twig -{% if entry.lightswitchFieldHandle %} +{# Fetch entries with the Lightswitch field enabled #} +{% set entries = craft.entries() + .(true) + .all() %} +``` + +::: tip +Any elements that don’t have an explicit Lightswitch value set will be treated as if they have the default field value, per the field settings. +::: + +### Working with Lightswitch Field Data + +If you have an element with a Lightswitch field in your template, you can access its data using your Lightswitch field’s handle: + +```twig +{% if entry. %}

I'm on!

{% else %}

I'm off.

{% endif %} ``` + +::: tip +If the element doesn’t have an explicit Lightswitch field value yet, the field’s default value will be returned. +::: + +### Saving Lightswitch Fields in Entry Forms + +If you have an [entry form](dev/examples/entry-form.md) that needs to contain a Lightswitch field, you can use this template as a starting point: + +```twig +{{ hiddenInput('fields[]', '') }} + +{{ tag('input', { + type: 'checkbox', + name: 'fields[]', + value: '1', + checked: (entry. ?? false) ? true : false, +}) }} +``` From c91f0925a13afc33ff06a361bed619aa7e1237b3 Mon Sep 17 00:00:00 2001 From: Brad Bell Date: Fri, 12 Jun 2020 17:33:01 -0700 Subject: [PATCH 048/245] New translations README.md (French) --- fr/testing/README.md | 28 ++++++++-------------------- 1 file changed, 8 insertions(+), 20 deletions(-) diff --git a/fr/testing/README.md b/fr/testing/README.md index 51352eb7c8c..80928e521b7 100644 --- a/fr/testing/README.md +++ b/fr/testing/README.md @@ -1,29 +1,17 @@ # Testing ## Introduction -Testing is a crucial part of ensuring that software continues to work -as the initial design expected. Things often tend to break when changing existing code bases -and often not directly in the places you are working on when errors occur. -This is where automated testing can help. If done correctly critical parts of -your site, module and/or plugin can be tested in such a way that ensures you are -notified when anything stops working as expected and before shipping any code to production. -Reducing bugs before they are discovered by clients in production saved you the time -of debugging the bug and communicating with the client, win-win. +Testing is a crucial part of ensuring that software continues to work as the initial design expected. Things often tend to break when changing existing code bases and often not directly in the places you are working on when errors occur. -## Craft testing framework -As of 3.2, Craft provides a formalized testing framework that is based on [Codeception](https://codeception.com/) -and implements the [Yii 2 codeception module](https://codeception.com/for/yii). +This is where automated testing can help. If done correctly critical parts of your site, module and/or plugin can be tested in such a way that ensures you are notified when anything stops working as expected and before shipping any code to production. Reducing bugs before they are discovered by clients in production saved you the time of debugging the bug and communicating with the client, win-win. -On top of all the tools that Codeception and Yii 2 natively provide for testing. -Craft adds its own layer of support to ensure Craft specific concepts such as Elements -& Project config are supported. +## Craft Testing Framework + +As of 3.2, Craft provides a formalized testing framework that is based on [Codeception](https://codeception.com/) and implements the [Yii 2 codeception module](https://codeception.com/for/yii). + +On top of all the tools that Codeception and Yii 2 natively provide for testing. Craft adds its own layer of support to ensure Craft specific concepts such as Elements & Project config are supported. ::: tip -Ready to rock? Start by reading a description of what testing is -within [Craft](testing.md) as well as how to test using -[Codeception](https://codeception.com/docs/01-Introduction). -Then there is a handy [get started guide](./testing-craft/getting-started.md) -to setup your test suite. +Ready to rock? Start by reading a description of what testing is within [Craft](testing.md) as well as how to test using [Codeception](https://codeception.com/docs/01-Introduction). Then there is a handy [get started guide](./testing-craft/getting-started.md) to setup your test suite. ::: - From a932007dcf47a437e49315bd2f8bedd2982b218e Mon Sep 17 00:00:00 2001 From: Brad Bell Date: Fri, 12 Jun 2020 17:33:03 -0700 Subject: [PATCH 049/245] New translations README.md (Japanese) --- ja/testing/README.md | 28 ++++++++-------------------- 1 file changed, 8 insertions(+), 20 deletions(-) diff --git a/ja/testing/README.md b/ja/testing/README.md index 51352eb7c8c..80928e521b7 100644 --- a/ja/testing/README.md +++ b/ja/testing/README.md @@ -1,29 +1,17 @@ # Testing ## Introduction -Testing is a crucial part of ensuring that software continues to work -as the initial design expected. Things often tend to break when changing existing code bases -and often not directly in the places you are working on when errors occur. -This is where automated testing can help. If done correctly critical parts of -your site, module and/or plugin can be tested in such a way that ensures you are -notified when anything stops working as expected and before shipping any code to production. -Reducing bugs before they are discovered by clients in production saved you the time -of debugging the bug and communicating with the client, win-win. +Testing is a crucial part of ensuring that software continues to work as the initial design expected. Things often tend to break when changing existing code bases and often not directly in the places you are working on when errors occur. -## Craft testing framework -As of 3.2, Craft provides a formalized testing framework that is based on [Codeception](https://codeception.com/) -and implements the [Yii 2 codeception module](https://codeception.com/for/yii). +This is where automated testing can help. If done correctly critical parts of your site, module and/or plugin can be tested in such a way that ensures you are notified when anything stops working as expected and before shipping any code to production. Reducing bugs before they are discovered by clients in production saved you the time of debugging the bug and communicating with the client, win-win. -On top of all the tools that Codeception and Yii 2 natively provide for testing. -Craft adds its own layer of support to ensure Craft specific concepts such as Elements -& Project config are supported. +## Craft Testing Framework + +As of 3.2, Craft provides a formalized testing framework that is based on [Codeception](https://codeception.com/) and implements the [Yii 2 codeception module](https://codeception.com/for/yii). + +On top of all the tools that Codeception and Yii 2 natively provide for testing. Craft adds its own layer of support to ensure Craft specific concepts such as Elements & Project config are supported. ::: tip -Ready to rock? Start by reading a description of what testing is -within [Craft](testing.md) as well as how to test using -[Codeception](https://codeception.com/docs/01-Introduction). -Then there is a handy [get started guide](./testing-craft/getting-started.md) -to setup your test suite. +Ready to rock? Start by reading a description of what testing is within [Craft](testing.md) as well as how to test using [Codeception](https://codeception.com/docs/01-Introduction). Then there is a handy [get started guide](./testing-craft/getting-started.md) to setup your test suite. ::: - From a6e6bea02d23eafee29faf4b6f285187fd50d0b9 Mon Sep 17 00:00:00 2001 From: Brad Bell Date: Fri, 12 Jun 2020 17:33:04 -0700 Subject: [PATCH 050/245] New translations ci.md (French) --- fr/testing/ci.md | 35 ++++++++++------------------------- 1 file changed, 10 insertions(+), 25 deletions(-) diff --git a/fr/testing/ci.md b/fr/testing/ci.md index 5df0c029629..d0ad36beca9 100644 --- a/fr/testing/ci.md +++ b/fr/testing/ci.md @@ -1,14 +1,10 @@ # Continuous Integration (CI) -There are [many](https://en.wikipedia.org/wiki/Comparison_of_continuous_integration_software) -[Continuous Integration](https://en.wikipedia.org/wiki/Continuous_integration) -platforms available to choose from. +There are [many](https://en.wikipedia.org/wiki/Comparison_of_continuous_integration_software) [Continuous Integration](https://en.wikipedia.org/wiki/Continuous_integration) platforms available to choose from. -Craft uses [Travis](https://travis-ci.com/craftcms/cms) for its public repo, but -you're free to use what you're comfortable with and modify things to your workflow. +Craft uses [Travis](https://travis-ci.com/craftcms/cms) for its public repo, but you're free to use what you're comfortable with and modify things to your workflow. -There are [many options](https://docs.travis-ci.com/) for configuring Travis, but -let's examine [Craft's `.travis.yml` file](https://github.com/craftcms/cms/blob/3.2/.travis.yml). +There are [many options](https://docs.travis-ci.com/) for configuring Travis, but let's examine [Craft's `.travis.yml` file](https://github.com/craftcms/cms/blob/3.2/.travis.yml). ```yaml services: @@ -36,13 +32,9 @@ matrix: env: TASK_TESTS_COVERAGE=1 DB=pgsql ``` -The `matrix` is where we explicitly define the different environments we want the -tests to run in. That includes PHP 7.1 - 7.3 and we define an environment variable -called `DB` that sets both `mysql` and `pgsql` we can use later. +The `matrix` is where we explicitly define the different environments we want the tests to run in. That includes PHP 7.1 - 7.3 and we define an environment variable called `DB` that sets both `mysql` and `pgsql` we can use later. -PHP 7.1 also sets an environment variable called `TASK_TESTS_COVERAGE` we'll use later -because that's the only environment we want code coverage reports to generate in (for -performance reasons). +PHP 7.1 also sets an environment variable called `TASK_TESTS_COVERAGE` we'll use later because that's the only environment we want code coverage reports to generate in (for performance reasons). ```yaml install: @@ -56,8 +48,7 @@ install: travis_retry composer install $DEFAULT_COMPOSER_FLAGS ``` -If `TASK_TESTS_COVERAGE` isn't set, we're going to disable xDebug to speed things up. -It's only needed for generated code coverage reports in this context. +If `TASK_TESTS_COVERAGE` isn't set, we're going to disable xDebug to speed things up. It's only needed for generated code coverage reports in this context. Then we `composer install` to pull down all of Craft's dependencies. @@ -80,9 +71,7 @@ before_script: - cp tests/.env.example.$DB tests/.env ``` -Before we run tests, we output some relevant debugging information to the console -and then create a MySQL and PostgreSQL database called `craft-test` that the tests -are going to use. +Before we run tests, we output some relevant debugging information to the console and then create a MySQL and PostgreSQL database called `craft-test` that the tests are going to use. Then we install Imagick on the server as some image specific tests require it to complete. @@ -90,9 +79,7 @@ Then we install Imagick on the server as some image specific tests require it to - cp tests/.env.example.$DB tests/.env ``` -Finally, for each build environment, we take the `.env.example.mysql` and `.env.example.pgsql` -files that are in the root of the `tests` folder and copy them to `tests/.env` so the test -environments know how to connect to each type of database. +Finally, for each build environment, we take the `.env.example.mysql` and `.env.example.pgsql` files that are in the root of the `tests` folder and copy them to `tests/.env` so the test environments know how to connect to each type of database. ```yaml script: @@ -105,8 +92,7 @@ script: fi ``` -If `TASK_TESTS_COVERAGE` is set, then we pass in the flags to Codeception to generate -code coverage reports. If not, we just run the tests. +If `TASK_TESTS_COVERAGE` is set, then we pass in the flags to Codeception to generate code coverage reports. If not, we just run the tests. ```yaml after_script: @@ -116,5 +102,4 @@ after_script: fi ``` -After tests are done executing, if `TASK_TESTS_COVERAGE` is set, we upload the code -coverage reports to a 3rd party service, [https://codecov.io](https://codecov.io/gh/craftcms/cms). +After tests are done executing, if `TASK_TESTS_COVERAGE` is set, we upload the code coverage reports to a 3rd party service, [https://codecov.io](https://codecov.io/gh/craftcms/cms). From 785a0fd268b559e1e84d28b0a33e3970d84645e5 Mon Sep 17 00:00:00 2001 From: Brad Bell Date: Fri, 12 Jun 2020 17:33:06 -0700 Subject: [PATCH 051/245] New translations ci.md (Japanese) --- ja/testing/ci.md | 35 ++++++++++------------------------- 1 file changed, 10 insertions(+), 25 deletions(-) diff --git a/ja/testing/ci.md b/ja/testing/ci.md index 5df0c029629..d0ad36beca9 100644 --- a/ja/testing/ci.md +++ b/ja/testing/ci.md @@ -1,14 +1,10 @@ # Continuous Integration (CI) -There are [many](https://en.wikipedia.org/wiki/Comparison_of_continuous_integration_software) -[Continuous Integration](https://en.wikipedia.org/wiki/Continuous_integration) -platforms available to choose from. +There are [many](https://en.wikipedia.org/wiki/Comparison_of_continuous_integration_software) [Continuous Integration](https://en.wikipedia.org/wiki/Continuous_integration) platforms available to choose from. -Craft uses [Travis](https://travis-ci.com/craftcms/cms) for its public repo, but -you're free to use what you're comfortable with and modify things to your workflow. +Craft uses [Travis](https://travis-ci.com/craftcms/cms) for its public repo, but you're free to use what you're comfortable with and modify things to your workflow. -There are [many options](https://docs.travis-ci.com/) for configuring Travis, but -let's examine [Craft's `.travis.yml` file](https://github.com/craftcms/cms/blob/3.2/.travis.yml). +There are [many options](https://docs.travis-ci.com/) for configuring Travis, but let's examine [Craft's `.travis.yml` file](https://github.com/craftcms/cms/blob/3.2/.travis.yml). ```yaml services: @@ -36,13 +32,9 @@ matrix: env: TASK_TESTS_COVERAGE=1 DB=pgsql ``` -The `matrix` is where we explicitly define the different environments we want the -tests to run in. That includes PHP 7.1 - 7.3 and we define an environment variable -called `DB` that sets both `mysql` and `pgsql` we can use later. +The `matrix` is where we explicitly define the different environments we want the tests to run in. That includes PHP 7.1 - 7.3 and we define an environment variable called `DB` that sets both `mysql` and `pgsql` we can use later. -PHP 7.1 also sets an environment variable called `TASK_TESTS_COVERAGE` we'll use later -because that's the only environment we want code coverage reports to generate in (for -performance reasons). +PHP 7.1 also sets an environment variable called `TASK_TESTS_COVERAGE` we'll use later because that's the only environment we want code coverage reports to generate in (for performance reasons). ```yaml install: @@ -56,8 +48,7 @@ install: travis_retry composer install $DEFAULT_COMPOSER_FLAGS ``` -If `TASK_TESTS_COVERAGE` isn't set, we're going to disable xDebug to speed things up. -It's only needed for generated code coverage reports in this context. +If `TASK_TESTS_COVERAGE` isn't set, we're going to disable xDebug to speed things up. It's only needed for generated code coverage reports in this context. Then we `composer install` to pull down all of Craft's dependencies. @@ -80,9 +71,7 @@ before_script: - cp tests/.env.example.$DB tests/.env ``` -Before we run tests, we output some relevant debugging information to the console -and then create a MySQL and PostgreSQL database called `craft-test` that the tests -are going to use. +Before we run tests, we output some relevant debugging information to the console and then create a MySQL and PostgreSQL database called `craft-test` that the tests are going to use. Then we install Imagick on the server as some image specific tests require it to complete. @@ -90,9 +79,7 @@ Then we install Imagick on the server as some image specific tests require it to - cp tests/.env.example.$DB tests/.env ``` -Finally, for each build environment, we take the `.env.example.mysql` and `.env.example.pgsql` -files that are in the root of the `tests` folder and copy them to `tests/.env` so the test -environments know how to connect to each type of database. +Finally, for each build environment, we take the `.env.example.mysql` and `.env.example.pgsql` files that are in the root of the `tests` folder and copy them to `tests/.env` so the test environments know how to connect to each type of database. ```yaml script: @@ -105,8 +92,7 @@ script: fi ``` -If `TASK_TESTS_COVERAGE` is set, then we pass in the flags to Codeception to generate -code coverage reports. If not, we just run the tests. +If `TASK_TESTS_COVERAGE` is set, then we pass in the flags to Codeception to generate code coverage reports. If not, we just run the tests. ```yaml after_script: @@ -116,5 +102,4 @@ after_script: fi ``` -After tests are done executing, if `TASK_TESTS_COVERAGE` is set, we upload the code -coverage reports to a 3rd party service, [https://codecov.io](https://codecov.io/gh/craftcms/cms). +After tests are done executing, if `TASK_TESTS_COVERAGE` is set, we upload the code coverage reports to a 3rd party service, [https://codecov.io](https://codecov.io/gh/craftcms/cms). From bb5e9ad50aad844d47ed6a5e26709555ad84d6ff Mon Sep 17 00:00:00 2001 From: Brad Bell Date: Fri, 12 Jun 2020 17:33:09 -0700 Subject: [PATCH 052/245] New translations testing.md (French) --- fr/testing/testing.md | 147 +++++++++++++++++++----------------------- 1 file changed, 67 insertions(+), 80 deletions(-) diff --git a/fr/testing/testing.md b/fr/testing/testing.md index b28a8885829..154baff66fe 100644 --- a/fr/testing/testing.md +++ b/fr/testing/testing.md @@ -1,39 +1,34 @@ # Testing -## Types of tests +## Types of Tests There are a variety of tests, each providing pros and cons to specific use cases and functionalities within your application/module/plugin. Craft currently supports the following four test types. -### Manual testing +### Manual Testing -Everyone has and probably does manual testing when developing with Craft. Manual testing can be defined in the following steps: +Everyone that’s worked with Craft has done manual testing. Manual testing consists of the following steps: -- Write some code -- Press `f5` or trigger a controller action -- Verify the result by seeing the result in the browser, IDE or database. +1. Write some code. +2. Refresh a given page or trigger a controller action. +3. Verify the result in the browser, IDE, or database. -Manual testing is the most time consuming but often the most effective way to catch -bugs in the _primary_ implementation of code - it also takes a lot of time and fails in certain key areas. -Most importantly - if you make a change to a codebase in one place - it can very likely fail in other places, -which you are not manually testing. +Manual testing is often the most effective way to catch bugs in the _primary_ implementation of code. However, each test takes a significant amount of time and fails in certain key areas. Most importantly, if you make a change to a codebase in one place it may fail in other places you’re _not_ manually testing. -It would be woefully inefficient to test your **entire** application after each `git push`. This is where **automated** tests can help. +It would be woefully inefficient to test your **entire** application manually after each `git push`. This is where **automated** tests can help. ::: tip -Testing is all about strategy and approaches. Manual testing and automated testing work best -together. You can use your judgement to detect/prevent issues that computers cannot see whilst computers -can execute many tests in short time. +Testing is all about strategy and approaches. Manual testing and automated testing work best together. You can use your judgement to detect/prevent issues that computers cannot see whilst computers can execute many tests in short time. ::: -### Unit testing +### Unit Testing -Many definitions exist regarding unit testing. Fundamentally a unit test is focused on testing -an individual 'unit' of your code. In practice, this will often mean testing the results of a function or in some cases, class. +Many definitions exist regarding unit testing. Fundamentally a unit test is focused on testing an individual “unit” of your code. This often means testing the results of a function or class. -Consider the following class. +Consider the following class: ```php -class SalaryChecker { +class SalaryChecker +{ public function multiply(int $a, int $b) : int { return $a * $b; @@ -46,13 +41,19 @@ class SalaryChecker { } ``` -If you were to unit test this class you would write something like follows: +Your unit test for this class might look like this: ```php use Codeception\Test\Unit; -class MyTest extends Unit { + +class MyTest extends Unit +{ public $salaryChecker; + /** + * This `_before()` hook is run before *every* test. We use it here + * to create a new `SalaryChecker()` instance each test can call. + */ public function _before() { parent::_before(); @@ -60,6 +61,15 @@ class MyTest extends Unit { $this->salaryChecker = new SalaryChecker(); } + /** + * Each `test*` function is executed, and within it we write a test + * that calls one of SalaryChecker’s methods to make an assertion + * about the result that should be returned. + * + * In this test, `multiply()` should multiply the parameters and + * return the result, so we provide `2` and `2` and know the result + * should be `4`. + */ public function testMultiply() { $this->assertSame( @@ -68,6 +78,10 @@ class MyTest extends Unit { ); } + /** + * SalaryChecker’s `add()` method should add the parameters, so we + * can safely assert that `2` and `1` should return `3`. + */ public function testAdd() { $this->assertSame( @@ -78,25 +92,16 @@ class MyTest extends Unit { } ``` -The anatomy of this test can be defined somewhat as follows: +This is a fundamental unit test. -1. In the `_before` hook we create a `new SalaryChecker()` which can be used during the test. - The `_before` method is run before _every_ test. - -2. A test is executed and a method of the `SalaryChecker` class is called. An **assertion** - (checking that when passing 2 twice, 4 is returned - because the 2's are multiplied) - is then made regarding its return result. - -Fundamentally - that is a unit test. -Now imagine a -developer was to change the `add` method of the `SalaryChecker` class to the following: +Now imagine a developer was to change `SalaryChecker` so its `multiply()` method never returned a number lower than `25000`: ```php public function multiply(int $a, int $b) : int { $result = $a * $b; - // Dont return salaries lower than 25000 + // Don’t return salaries lower than 25,000 if ($result < 25000) { return 25000 } @@ -105,81 +110,63 @@ public function multiply(int $a, int $b) : int } ``` -The test would fail. Obviously, this is a basic example but as your codebase expands/changes, new -devs join or old dev's leave and/or project requirements differ from the original spec more -and more code will become dependant on each other. +The test would fail, expecting a result of `4` and getting `25000` instead. -Your unit tests will primarily cover your [service](../extend/services.md) classes. It is not recommended to test -_every_ method that your service class has. -Use your best judgement and try to test methods as high up in the -[call stack/backtrace](https://www.php.net/manual/en/function.debug-backtrace.php) as possible -(excluding your controllers - they are covered by functional and acceptance testing). +Even though this is a basic example, it would automatically confirm expected application behavior and issue a warning signal if the tested behavior changed. This can be increasingly important as a codebase grows, changes hands as developers join or leave the project, or requirements differ from the original spec. -Having good unit tests ensures that your individual functions work correctly, and if they don't, -quickly catch and fix bugs relating this hereto. +Good unit tests ensure your individual functions work correctly, and help you quickly catch and fix bugs if they don’t. -It is recommended to read the Codeception documentation on -[unit tests](https://codeception.com/docs/05-UnitTests) -as well to see more practical examples of unit tests. +Your unit tests will primarily cover your [service](../extend/services.md) classes. It’s probably excessive to test _every_ method of your service class; you’ll need to use your judgement and test methods as high up in the [call stack/backtrace](https://www.php.net/manual/en/function.debug-backtrace.php) as possible. (This excludes your controllers, which are covered by functional and acceptance testing). -### Functional & acceptance testing +::: tip +For more practical examples, see the [Codeception documentation on unit tests](https://codeception.com/docs/05-UnitTests). +::: + +### Functional & Acceptance Testing -Your application isn't just a collection of PHP classes on a server. These -classes work together to create an end product. These methods are often linked via -controllers. The end product will then be shipped to a user via these controllers. The controller actions -are the place where your application functionality is encompassed into a usable package - seems a good place to write tests for? +Your application isn’t just a collection of PHP classes on a server; these classes work together to create an end product. These methods are often linked via controllers. The end product will then be shipped to a user via these controllers. The controller actions are the place where your application functionality is encompassed into a usable package, making them an ideal place to test. Typically a controller will: -- 1. Process a request (authentication, authorization, request types e.t.c.) -- 2. Invoke craft services -- 3. Return a response +1. Process a request (authentication, authorization, request types etc.) +2. Invoke craft services. +3. Return a response. -Point 2 is covered by unit tests - 1 and 3 are covered by -functional and acceptance tests. +Point 2 is covered by unit tests. 1 and 3 are covered by functional and acceptance tests. -What separates functional and acceptance tests from unit tests are that they -are conducted from the **user** perspective. Consider the following -twig template located at route `/pages/bob`: +What separates functional and acceptance tests from unit tests are that they’re conducted from the **user** perspective. Consider the following Twig template located at route `/pages/bob`: ```twig -Hi {{ currentUser.firstName }} +Hi {{ currentUser.firstName }}, -Welcome to this app +Welcome to this app! ``` -For this page/template you would create the following test class -(Assuming you are creating a functional test): +A functional test tor this page/template might look like this: ```php -amLoggedInAs($userWithFirstNameBob); $I->amOnPage('/pages/bob'); - $I->see('Hi Bob'); - $I->see('Welcome to this app'); + $I->see('Hi Bob,'); + $I->see('Welcome to this app!'); } } ``` -Dont worry about `$userWithFirstNameBob`. Just pretend that this variable is an instance of -`craft\elements\User` where `$firstName = "bob"`. +Don’t worry about `$userWithFirstNameBob`. Just pretend that this variable is an instance of `craft\elements\User` where `$firstName = "bob"`. + +Notice how the test reads like instructions that you _could_ give to a human to perform on a production version of your application. -Notice how the test reads very much like instructions that you _could_ give to a -human to perform on a production version of your application. +Underneath, the functional test actually triggers the controller associated with this route. If you have a module or plugin you can also pass in, for example, `?p=actions/my-plugin/my-controller/my-action` which will test your controller actions. -Underneath the functional test actually triggers the controller associated with this route. -If you have a module/plugin you can also pass in for example -`?p=actions/my-plugin/my-controller/my-action` which will test your controller actions. +You can even test control panel functionality by passing a URL that starts with the [cpTrigger](../config/config-settings.md#cptrigger) config (i.e. with a `cpTrigger` of `admin` you could do `$I->amOnRoute('/admin/my-plugin/my-route/my-action)`). -You can even test the CP functionality by passing in a url that starts with the -[cpTrigger](../config/config-settings.md#cptrigger) config (I.E with a `cpTrigger` of `admin` -you could do `$I->amOnRoute('/admin/my-plugin/my-route/my-action)`). ::: tip -Acceptance and functional tests are quite similar with some subtle differences in their -_implementation_. See the [codeception docs](https://codeception.com/docs/01-Introduction) -for an explanation hereto. +Acceptance and functional tests are similar with subtle differences in their _implementation_. See the [Codeception docs](https://codeception.com/docs/01-Introduction) for an explanation. ::: From f5eee34740e34391b9629538f97b4ffd0ae6a722 Mon Sep 17 00:00:00 2001 From: Brad Bell Date: Fri, 12 Jun 2020 17:33:11 -0700 Subject: [PATCH 053/245] New translations testing.md (Japanese) --- ja/testing/testing.md | 147 +++++++++++++++++++----------------------- 1 file changed, 67 insertions(+), 80 deletions(-) diff --git a/ja/testing/testing.md b/ja/testing/testing.md index b28a8885829..154baff66fe 100644 --- a/ja/testing/testing.md +++ b/ja/testing/testing.md @@ -1,39 +1,34 @@ # Testing -## Types of tests +## Types of Tests There are a variety of tests, each providing pros and cons to specific use cases and functionalities within your application/module/plugin. Craft currently supports the following four test types. -### Manual testing +### Manual Testing -Everyone has and probably does manual testing when developing with Craft. Manual testing can be defined in the following steps: +Everyone that’s worked with Craft has done manual testing. Manual testing consists of the following steps: -- Write some code -- Press `f5` or trigger a controller action -- Verify the result by seeing the result in the browser, IDE or database. +1. Write some code. +2. Refresh a given page or trigger a controller action. +3. Verify the result in the browser, IDE, or database. -Manual testing is the most time consuming but often the most effective way to catch -bugs in the _primary_ implementation of code - it also takes a lot of time and fails in certain key areas. -Most importantly - if you make a change to a codebase in one place - it can very likely fail in other places, -which you are not manually testing. +Manual testing is often the most effective way to catch bugs in the _primary_ implementation of code. However, each test takes a significant amount of time and fails in certain key areas. Most importantly, if you make a change to a codebase in one place it may fail in other places you’re _not_ manually testing. -It would be woefully inefficient to test your **entire** application after each `git push`. This is where **automated** tests can help. +It would be woefully inefficient to test your **entire** application manually after each `git push`. This is where **automated** tests can help. ::: tip -Testing is all about strategy and approaches. Manual testing and automated testing work best -together. You can use your judgement to detect/prevent issues that computers cannot see whilst computers -can execute many tests in short time. +Testing is all about strategy and approaches. Manual testing and automated testing work best together. You can use your judgement to detect/prevent issues that computers cannot see whilst computers can execute many tests in short time. ::: -### Unit testing +### Unit Testing -Many definitions exist regarding unit testing. Fundamentally a unit test is focused on testing -an individual 'unit' of your code. In practice, this will often mean testing the results of a function or in some cases, class. +Many definitions exist regarding unit testing. Fundamentally a unit test is focused on testing an individual “unit” of your code. This often means testing the results of a function or class. -Consider the following class. +Consider the following class: ```php -class SalaryChecker { +class SalaryChecker +{ public function multiply(int $a, int $b) : int { return $a * $b; @@ -46,13 +41,19 @@ class SalaryChecker { } ``` -If you were to unit test this class you would write something like follows: +Your unit test for this class might look like this: ```php use Codeception\Test\Unit; -class MyTest extends Unit { + +class MyTest extends Unit +{ public $salaryChecker; + /** + * This `_before()` hook is run before *every* test. We use it here + * to create a new `SalaryChecker()` instance each test can call. + */ public function _before() { parent::_before(); @@ -60,6 +61,15 @@ class MyTest extends Unit { $this->salaryChecker = new SalaryChecker(); } + /** + * Each `test*` function is executed, and within it we write a test + * that calls one of SalaryChecker’s methods to make an assertion + * about the result that should be returned. + * + * In this test, `multiply()` should multiply the parameters and + * return the result, so we provide `2` and `2` and know the result + * should be `4`. + */ public function testMultiply() { $this->assertSame( @@ -68,6 +78,10 @@ class MyTest extends Unit { ); } + /** + * SalaryChecker’s `add()` method should add the parameters, so we + * can safely assert that `2` and `1` should return `3`. + */ public function testAdd() { $this->assertSame( @@ -78,25 +92,16 @@ class MyTest extends Unit { } ``` -The anatomy of this test can be defined somewhat as follows: +This is a fundamental unit test. -1. In the `_before` hook we create a `new SalaryChecker()` which can be used during the test. - The `_before` method is run before _every_ test. - -2. A test is executed and a method of the `SalaryChecker` class is called. An **assertion** - (checking that when passing 2 twice, 4 is returned - because the 2's are multiplied) - is then made regarding its return result. - -Fundamentally - that is a unit test. -Now imagine a -developer was to change the `add` method of the `SalaryChecker` class to the following: +Now imagine a developer was to change `SalaryChecker` so its `multiply()` method never returned a number lower than `25000`: ```php public function multiply(int $a, int $b) : int { $result = $a * $b; - // Dont return salaries lower than 25000 + // Don’t return salaries lower than 25,000 if ($result < 25000) { return 25000 } @@ -105,81 +110,63 @@ public function multiply(int $a, int $b) : int } ``` -The test would fail. Obviously, this is a basic example but as your codebase expands/changes, new -devs join or old dev's leave and/or project requirements differ from the original spec more -and more code will become dependant on each other. +The test would fail, expecting a result of `4` and getting `25000` instead. -Your unit tests will primarily cover your [service](../extend/services.md) classes. It is not recommended to test -_every_ method that your service class has. -Use your best judgement and try to test methods as high up in the -[call stack/backtrace](https://www.php.net/manual/en/function.debug-backtrace.php) as possible -(excluding your controllers - they are covered by functional and acceptance testing). +Even though this is a basic example, it would automatically confirm expected application behavior and issue a warning signal if the tested behavior changed. This can be increasingly important as a codebase grows, changes hands as developers join or leave the project, or requirements differ from the original spec. -Having good unit tests ensures that your individual functions work correctly, and if they don't, -quickly catch and fix bugs relating this hereto. +Good unit tests ensure your individual functions work correctly, and help you quickly catch and fix bugs if they don’t. -It is recommended to read the Codeception documentation on -[unit tests](https://codeception.com/docs/05-UnitTests) -as well to see more practical examples of unit tests. +Your unit tests will primarily cover your [service](../extend/services.md) classes. It’s probably excessive to test _every_ method of your service class; you’ll need to use your judgement and test methods as high up in the [call stack/backtrace](https://www.php.net/manual/en/function.debug-backtrace.php) as possible. (This excludes your controllers, which are covered by functional and acceptance testing). -### Functional & acceptance testing +::: tip +For more practical examples, see the [Codeception documentation on unit tests](https://codeception.com/docs/05-UnitTests). +::: + +### Functional & Acceptance Testing -Your application isn't just a collection of PHP classes on a server. These -classes work together to create an end product. These methods are often linked via -controllers. The end product will then be shipped to a user via these controllers. The controller actions -are the place where your application functionality is encompassed into a usable package - seems a good place to write tests for? +Your application isn’t just a collection of PHP classes on a server; these classes work together to create an end product. These methods are often linked via controllers. The end product will then be shipped to a user via these controllers. The controller actions are the place where your application functionality is encompassed into a usable package, making them an ideal place to test. Typically a controller will: -- 1. Process a request (authentication, authorization, request types e.t.c.) -- 2. Invoke craft services -- 3. Return a response +1. Process a request (authentication, authorization, request types etc.) +2. Invoke craft services. +3. Return a response. -Point 2 is covered by unit tests - 1 and 3 are covered by -functional and acceptance tests. +Point 2 is covered by unit tests. 1 and 3 are covered by functional and acceptance tests. -What separates functional and acceptance tests from unit tests are that they -are conducted from the **user** perspective. Consider the following -twig template located at route `/pages/bob`: +What separates functional and acceptance tests from unit tests are that they’re conducted from the **user** perspective. Consider the following Twig template located at route `/pages/bob`: ```twig -Hi {{ currentUser.firstName }} +Hi {{ currentUser.firstName }}, -Welcome to this app +Welcome to this app! ``` -For this page/template you would create the following test class -(Assuming you are creating a functional test): +A functional test tor this page/template might look like this: ```php -amLoggedInAs($userWithFirstNameBob); $I->amOnPage('/pages/bob'); - $I->see('Hi Bob'); - $I->see('Welcome to this app'); + $I->see('Hi Bob,'); + $I->see('Welcome to this app!'); } } ``` -Dont worry about `$userWithFirstNameBob`. Just pretend that this variable is an instance of -`craft\elements\User` where `$firstName = "bob"`. +Don’t worry about `$userWithFirstNameBob`. Just pretend that this variable is an instance of `craft\elements\User` where `$firstName = "bob"`. + +Notice how the test reads like instructions that you _could_ give to a human to perform on a production version of your application. -Notice how the test reads very much like instructions that you _could_ give to a -human to perform on a production version of your application. +Underneath, the functional test actually triggers the controller associated with this route. If you have a module or plugin you can also pass in, for example, `?p=actions/my-plugin/my-controller/my-action` which will test your controller actions. -Underneath the functional test actually triggers the controller associated with this route. -If you have a module/plugin you can also pass in for example -`?p=actions/my-plugin/my-controller/my-action` which will test your controller actions. +You can even test control panel functionality by passing a URL that starts with the [cpTrigger](../config/config-settings.md#cptrigger) config (i.e. with a `cpTrigger` of `admin` you could do `$I->amOnRoute('/admin/my-plugin/my-route/my-action)`). -You can even test the CP functionality by passing in a url that starts with the -[cpTrigger](../config/config-settings.md#cptrigger) config (I.E with a `cpTrigger` of `admin` -you could do `$I->amOnRoute('/admin/my-plugin/my-route/my-action)`). ::: tip -Acceptance and functional tests are quite similar with some subtle differences in their -_implementation_. See the [codeception docs](https://codeception.com/docs/01-Introduction) -for an explanation hereto. +Acceptance and functional tests are similar with subtle differences in their _implementation_. See the [Codeception docs](https://codeception.com/docs/01-Introduction) for an explanation. ::: From 099794a40004744db797a431c9d870e450a7968e Mon Sep 17 00:00:00 2001 From: Brad Bell Date: Fri, 12 Jun 2020 17:33:12 -0700 Subject: [PATCH 054/245] New translations README.md (French) --- fr/README.md | 6 ++++-- 1 file changed, 4 insertions(+), 2 deletions(-) diff --git a/fr/README.md b/fr/README.md index 9fd2d3495bc..09209e7b903 100644 --- a/fr/README.md +++ b/fr/README.md @@ -4,7 +4,7 @@ Craft is a flexible, user-friendly CMS for creating custom digital experiences o It features: -- An intuitive, user-friendly Control Panel for content creation and administrative tasks. +- An intuitive, user-friendly control panel for content creation and administrative tasks. - A clean-slate approach to content modeling and [front-end development](dev/README.md) that doesn’t make any assumptions about your content or how it should be consumed. - A built-in Plugin Store with hundreds of free and commercial [plugins](https://plugins.craftcms.com/), all just a click away. - A robust framework for [module and plugin development](extend/README.md). @@ -29,8 +29,10 @@ Craft is a self-hosted PHP 7 application, built on [Yii 2](https://www.yiiframew ## Diving In +If you’re new to Craft CMS the best place to start is [the tutorial](https://docs.craftcms.com/tutorial/). + To start getting acquainted with how content modeling works in Craft, read [Sections and Entries](sections-and-entries.md) and [Fields](fields.md). -When you’re ready to install Craft, read [Server Requirements](requirements.md) and [Installation Instructions](installation.md). +Before installing, check out the [Server Requirements](requirements.md) and [Installation Instructions](installation.md). Finally, read the [Front-End Development](dev/README.md) section when you’re ready to start building out the front-end of your site or application. From a1a61f8487dc8ee838adcd37ae58f2262e44bc11 Mon Sep 17 00:00:00 2001 From: Brad Bell Date: Fri, 12 Jun 2020 17:33:14 -0700 Subject: [PATCH 055/245] New translations assets-fields.md (French) --- fr/assets-fields.md | 99 +++++++++++++++++++++++++++++++++------------ 1 file changed, 73 insertions(+), 26 deletions(-) diff --git a/fr/assets-fields.md b/fr/assets-fields.md index 4e8431450d6..a019a6f2ba8 100644 --- a/fr/assets-fields.md +++ b/fr/assets-fields.md @@ -40,6 +40,10 @@ Subfolder paths defined by the “Upload Location” and “Default Upload Locat Any properties supported by the source element (the element that has the Assets field) can be used here. +::: tip +If you want to include the entry’s ID or UID in a dynamic subfolder path, use `{sourceId}` or `{sourceUid}` rather than `{id}` or `{uid}`, so the source entry’s ID or UID is used rather than the revision / draft’s. +::: + ::: tip If you are creating the Assets field within a [Matrix field](matrix-fields.md), the source element is going to be the Matrix block, _not_ the element that the Matrix field is being created on. @@ -52,6 +56,10 @@ Assets fields list all of the currently-related assets, with a button to select Clicking the “Add an asset” button will bring up a modal window where you can find and select additional assets, as well as upload new ones. +::: tip +You can also upload assets by dragging files directly onto the assets field or modal window. +::: + ### Inline Asset Editing When you double-click on a related asset, a HUD will appear where you can edit the asset’s title and custom fields, and launch the Image Editor (if it’s an image). @@ -68,10 +76,15 @@ When [querying for elements](dev/element-queries/README.md) that have an Assets Possible values include: -| Value | Fetches elements… -| - | - -| `':empty:'` | that don’t have any related assets. -| `':notempty:'` | that have at least one related asset. +| Value | Fetches elements… | +| ----------------------------------------------------------- | ------------------------------------------------------- | +| `':empty:'` | that don’t have any related assets. | +| `':notempty:'` | that have at least one related asset. | +| `100` | that are related to the asset with an ID of 100. | +| `[100, 200]` | that are related to an asset with an ID of 100 or 200. | +| `['and', 100, 200]` | that are related to the assets with IDs of 100 and 200. | +| an [Asset](api:craft\elements\Asset) object | that are related to the asset. | +| an [AssetQuery](api:craft\elements\db\AssetQuery) object | that are related to any of the resulting assets. | ```twig {# Fetch entries with a related asset #} @@ -103,6 +116,10 @@ To loop through all of the related assets, call [all()](api:craft\db\Query::all( {% endif %} ``` +::: warning +When using `asset.url` or `asset.getUrl()`, the asset’s source volume must have “Assets in this volume have public URLs” enabled and a “Base URL” setting. Otherwise, the result will always be empty. +::: + If you only want the first related asset, call [one()](api:craft\db\Query::one()) instead, and then make sure it returned something: ```twig @@ -132,40 +149,70 @@ You can set [parameters](dev/element-queries/asset-queries.md#parameters) on the It’s always a good idea to clone the asset query using the [clone()](./dev/functions.md#clone) function before adjusting its parameters, so the parameters don’t have unexpected consequences later on in your template. ::: -### Uploading Files from Front-End Entry Forms +### Saving Assets Fields in Entry Forms -If you want to allow users to upload files to an Assets field from a front-end [entry form](dev/examples/entry-form.md), you just need to do two things. +If you have an [entry form](dev/examples/entry-form.md) that needs to contain an Assets field, you will need to submit your field value as a list of asset IDs, in the order you want them to be related. -First, make sure your `` tag has an `enctype="multipart/form-data"` attribute, so that it is capable of uploading files. +For example, you could create a list of checkboxes for each of the possible relations: -```markup - +```twig +{# Include a hidden input first so Craft knows to update the + existing value, if no checkboxes are checked. #} +{{ hiddenInput('fields[]', '') }} + +{# Get all of the possible asset options #} +{% set possibleAssets = craft.assets() + .volume('siteAssets') + .kind('image') + .orderBy('filename ASC') + .withTransforms([ + { width: 100, height: 100 } + ]) + .all() %} + +{# Get the currently related asset IDs #} +{% set relatedAssetIds = entry is defined + ? entry..ids() + : [] %} + +
    + {% for possibleAsset in possibleAssets %} +
  • + +
    • + {% endfor %} +
``` -Then add a file input to the form: +You could then make the checkbox list sortable, so users have control over the order of related assets. -```markup - -``` +#### Creating New Assets -::: tip -Replace `` with you actual field handle. For example if you field handle is “heroImage”, the input name should be `fields[heroImage]`. -::: +Assets fields can handle new file uploads as well: -If you want to allow multiple file uploads, add the `multiple` attribute and add `[]` to the end of the input name: - -```markup - +```twig +{{ input('file', 'fields[][]', options={ + multiple: true, +}) }} ``` -If you want to add files to a field with existing assets, you will need to first fetch the existing asset ids and add them to a hidden field: +::: tip +Don’t forget to set `enctype="multipart/form-data"` on your `` tag so your browser knows to submit the form as a multipart request. +::: -``` -{% for asset in entry. %} - -{% endfor %} +Alternatively, you can submit Base64-encoded file data, which the Assets field will decode and treat as an uploaded file: - +```twig +{{ hiddenInput('fields[][]', 'data:image/jpeg;base64,') }} ``` ## See Also From 57fb5d920809b5fe1f40726bbf941dff5f9e3071 Mon Sep 17 00:00:00 2001 From: Brad Bell Date: Fri, 12 Jun 2020 17:33:15 -0700 Subject: [PATCH 056/245] New translations coc.md (French) --- fr/coc.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/fr/coc.md b/fr/coc.md index 3eae5b65b2e..72e264a6310 100644 --- a/fr/coc.md +++ b/fr/coc.md @@ -6,7 +6,7 @@ Diversity is one of our strengths. With that, challenges will arise that can lea This isn’t an exhaustive list of things that you can’t do. Rather, take it in the spirit in which it’s intended - a guide to make it easier to enrich all of us and the technical communities in which we participate. -This code of conduct applies to all spaces used by the Craft community for communication. This includes Craft Slack, Craft CMS Stack Exchange, GitHub, Twitter, Facebook, meetups, conferences, and any other relevant forums. Violations of this code outside of any spaces managed by the Craft team will still affect a person’s ability to participate within them. +This code of conduct applies to all spaces used by the Craft community for communication. This includes Craft Discord, Craft CMS Stack Exchange, GitHub, Twitter, Facebook, meetups, conferences, and any other relevant forums. Violations of this code outside of any spaces managed by the Craft team will still affect a person’s ability to participate within them. If you believe someone is violating the code of conduct, we ask that you report it by contacting us from [craftcms.com/contact](https://craftcms.com/contact). We take all reports seriously, and your identity will remain confidential. From 51bf2ed6493dceceb4be9e0b0934963238ae1aea Mon Sep 17 00:00:00 2001 From: Brad Bell Date: Fri, 12 Jun 2020 17:33:17 -0700 Subject: [PATCH 057/245] New translations assets.md (French) --- fr/assets.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/fr/assets.md b/fr/assets.md index 3ac719eb997..328a5781763 100644 --- a/fr/assets.md +++ b/fr/assets.md @@ -44,7 +44,7 @@ Any fields you select here will be visible in the asset editor HUD that opens up ## Assets Page -When you create your first volume, an “Assets” item will be added to the main Control Panel navigation. Clicking on it will take you to the Assets page, which shows a list of all of your volumes in the left sidebar, and the selected volume’s files in the main content area. +When you create your first volume, an “Assets” item will be added to the main control panel navigation. Clicking on it will take you to the Assets page, which shows a list of all of your volumes in the left sidebar, and the selected volume’s files in the main content area. From this page, you can do the following: From a4ec4b2c6d94d3d12c09c6b8660d31cdd4836e8d Mon Sep 17 00:00:00 2001 From: Brad Bell Date: Fri, 12 Jun 2020 17:33:18 -0700 Subject: [PATCH 058/245] New translations assets.md (Japanese) --- ja/assets.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/ja/assets.md b/ja/assets.md index f8f48df7b89..e95b41858c0 100644 --- a/ja/assets.md +++ b/ja/assets.md @@ -44,7 +44,7 @@ Amazon S3 のようなリモートストレージサービスにアセットを ## アセットページ -最初のボリュームを作成すると、コントロールパネルのメインナビゲーションに「アセット」項目が追加されます。これをクリックすると、左サイドバーにすべてのボリュームのリスト、メインコンテンツエリアに選択されたボリュームのファイルが表示されたアセットページに移動します。 +When you create your first volume, an “Assets” item will be added to the main control panel navigation. Clicking on it will take you to the Assets page, which shows a list of all of your volumes in the left sidebar, and the selected volume’s files in the main content area. このページでは、次のことができます。 From 5f34354e360e5494072f30afdc6cbee95ab1b6b0 Mon Sep 17 00:00:00 2001 From: Brad Bell Date: Fri, 12 Jun 2020 17:33:20 -0700 Subject: [PATCH 059/245] New translations categories-fields.md (French) --- fr/categories-fields.md | 29 +++++++++++++++++++++++------ 1 file changed, 23 insertions(+), 6 deletions(-) diff --git a/fr/categories-fields.md b/fr/categories-fields.md index 07638f088b8..2af652739ba 100644 --- a/fr/categories-fields.md +++ b/fr/categories-fields.md @@ -59,10 +59,15 @@ You can set [parameters](dev/element-queries/category-queries.md#parameters) on Possible values include: -| Value | Fetches elements… | -| -------------- | ---------------------------------------- | -| `':empty:'` | that don’t have any related categories. | -| `':notempty:'` | that have at least one related category. | +| Value | Fetches elements… | +| ----------------------------------------------------------------- | ----------------------------------------------------------- | +| `':empty:'` | that don’t have any related categories. | +| `':notempty:'` | that have at least one related category. | +| `100` | that are related to the category with an ID of 100. | +| `[100, 200]` | that are related to a category with an ID of 100 or 200. | +| `['and', 100, 200]` | that are related to the categories with IDs of 100 and 200. | +| an [Category](api:craft\elements\Category) object | that are related to the category. | +| an [CategoryQuery](api:craft\elements\db\CategoryQuery) object | that are related to any of the resulting categories. | ```twig {% set relatedCategories = entry..all() %} @@ -111,8 +116,20 @@ To loop through all of the related categories as a flat list, call [all()](api:c Or you can show them as a hierarchical list with the [nav](dev/tags/nav.md) tag: ```twig -{% if entry..exists() %} -

There are related categories!

+{% set relatedCategories = entry..all() %} +{% if relatedCategories|length %} +
    + {% nav rel in relatedCategories %} +
  • + {{ rel.title }} + {% ifchildren %} +
      + {% children %} +
    + {% endifchildren %} +
    • + {% endnav %} +
{% endif %} ``` From 9bcebd7f214086e5776ec46d8688e31d77c267e5 Mon Sep 17 00:00:00 2001 From: Brad Bell Date: Fri, 12 Jun 2020 17:33:21 -0700 Subject: [PATCH 060/245] New translations categories-fields.md (Japanese) --- ja/categories-fields.md | 15 ++++++++++----- 1 file changed, 10 insertions(+), 5 deletions(-) diff --git a/ja/categories-fields.md b/ja/categories-fields.md index b5d9be2467e..5b88744c1e3 100644 --- a/ja/categories-fields.md +++ b/ja/categories-fields.md @@ -59,10 +59,15 @@ 利用可能な値には、次のものが含まれます。 -| 値 | 取得するエレメント | -| -------------- | ----------------------- | -| `':empty:'` | 関連付けられたカテゴリを持たない。 | -| `':notempty:'` | 少なくとも1つの関連付けられたカテゴリを持つ。 | +| 値 | 取得するエレメント | +| ----------------------------------------------------------------- | ----------------------------------------------------------- | +| `':empty:'` | 関連付けられたカテゴリを持たない。 | +| `':notempty:'` | 少なくとも1つの関連付けられたカテゴリを持つ。 | +| `100` | that are related to the category with an ID of 100. | +| `[100, 200]` | that are related to a category with an ID of 100 or 200. | +| `['and', 100, 200]` | that are related to the categories with IDs of 100 and 200. | +| an [Category](api:craft\elements\Category) object | that are related to the category. | +| an [CategoryQuery](api:craft\elements\db\CategoryQuery) object | that are related to any of the resulting categories. | ```twig {# Fetch entries with a related category #} @@ -97,7 +102,7 @@ または、[nav](dev/tags/nav.md) タグで階層リストとして表示することもできます。 ```twig -{% set relatedCategories = entry..all() %} {% if relatedCategories|length %}
    {% nav rel in relatedCategories %} From 173681166684664fce2e47b1582316faef0affd1 Mon Sep 17 00:00:00 2001 From: Brad Bell Date: Fri, 12 Jun 2020 17:33:24 -0700 Subject: [PATCH 061/245] New translations categories.md (French) --- fr/categories.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/fr/categories.md b/fr/categories.md index 6b3a7dbb4eb..4ca0faf2be6 100644 --- a/fr/categories.md +++ b/fr/categories.md @@ -25,7 +25,7 @@ You can also add additional fields using all of the available field types in Cra ## Creating and Editing Categories -If you have at least one category group, there will be a “Categories” tab in the primary Control Panel navigation. Clicking on it will take you to the category index. From there you can choose a category group from the sidebar, and add/reorder/delete categories within it: +If you have at least one category group, there will be a “Categories” tab in the primary control panel navigation. Clicking on it will take you to the category index. From there you can choose a category group from the sidebar, and add/reorder/delete categories within it: ![Category Index](./images/categories-category-index.png) From 914fdd992a060b4eeb05bbd39d3663ed247a7090 Mon Sep 17 00:00:00 2001 From: Brad Bell Date: Fri, 12 Jun 2020 17:33:26 -0700 Subject: [PATCH 062/245] New translations categories.md (Japanese) --- ja/categories.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/ja/categories.md b/ja/categories.md index d780a12bb25..4e18d45899b 100644 --- a/ja/categories.md +++ b/ja/categories.md @@ -25,7 +25,7 @@ Craft 内で利用可能なすべてのフィールドタイプを使って、 ## カテゴリの作成と編集 -少なくとも1つのカテゴリグループがあれば、コントロールパネルのメインナビゲーションに「カテゴリ」タブが表示されます。クリックすると、カテゴリのインデックスに移動します。サイドバーからカテゴリグループを選択すると、そのグループに含まれるカテゴリを追加 / 並び替え / 削除できます。 +If you have at least one category group, there will be a “Categories” tab in the primary control panel navigation. Clicking on it will take you to the category index. From there you can choose a category group from the sidebar, and add/reorder/delete categories within it: ![カテゴリインデックス](./images/categories-category-index.png) From 5429d35922f671481255e9a17546cdcf3fdaba6a Mon Sep 17 00:00:00 2001 From: Brad Bell Date: Fri, 12 Jun 2020 17:33:28 -0700 Subject: [PATCH 063/245] New translations changes-in-craft-3.md (French) --- fr/changes-in-craft-3.md | 10 +++++++--- 1 file changed, 7 insertions(+), 3 deletions(-) diff --git a/fr/changes-in-craft-3.md b/fr/changes-in-craft-3.md index 42ecd3953ef..4207a5cdd21 100644 --- a/fr/changes-in-craft-3.md +++ b/fr/changes-in-craft-3.md @@ -35,6 +35,10 @@ The “Position Select” field type has been removed from Craft 3. If you had a If you miss Position Select, you can try installing the [Position Fieldtype](https://github.com/Rias500/craft-position-fieldtype) plugin, which brings it back. +## Lightswitch Fields + +Lightswitch field values are now always `true` or `false`. If you’re accessing a Lightswitch field value for an element that doesn’t have an explicit value set yet, the field’s default value will be returned instead. + ## Remote Volumes Support for Amazon S3, Rackspace Cloud Files, and Google Cloud Storage have been moved into plugins. If you have any asset volumes that were using those services in Craft 2, you will need to install the new plugins: @@ -449,14 +453,14 @@ That made it possible to execute variations of an element query, without affecti {% set totalEntries = query.total() %} ``` -Here `.type()` is applying the `type` parameter to a *clone* of `query`, so it had no effect on `query.total()`, which will still return the total number of News entries, regardless of their entry types. +Here `.type()` is applying the `type` parameter to a _clone_ of `query`, so it had no effect on `query.total()`, which will still return the total number of News entries, regardless of their entry types. This behavior has changed in Craft 3, though. Now any time you call a parameter-setter method, the method will: 1. set the parameter value on the current element query 2. return the element query -Which means in the above code example, `totalEntries` will be set to the total *Article* entries, as the `type` parameter will still be applied. +Which means in the above code example, `totalEntries` will be set to the total _Article_ entries, as the `type` parameter will still be applied. If you have any templates that count on the Craft 2 behavior, you can fix them using the [clone()](dev/functions.md#clone-object) function. @@ -571,7 +575,7 @@ Your front-end ``s and JS scripts that submit to a controller action will ### `action` Params -`action` params must be rewritten in in `kebab-case` rather than `camelCase`. +`action` params must be rewritten in `kebab-case` rather than `camelCase`. ```twig Old: From 835abeec73f5b401ede4be34d2e8a686841206a6 Mon Sep 17 00:00:00 2001 From: Brad Bell Date: Fri, 12 Jun 2020 17:33:30 -0700 Subject: [PATCH 064/245] New translations changes-in-craft-3.md (Japanese) --- ja/changes-in-craft-3.md | 156 ++++++++++++++++++++------------------- 1 file changed, 80 insertions(+), 76 deletions(-) diff --git a/ja/changes-in-craft-3.md b/ja/changes-in-craft-3.md index b867d4f970b..e8eb97e8a11 100644 --- a/ja/changes-in-craft-3.md +++ b/ja/changes-in-craft-3.md @@ -35,19 +35,23 @@ Redactor プラグインをインストールする場合、`config/redactor/` 位置選択フィールドが必要な場合、[Position Fieldtype](https://github.com/Rias500/craft-position-fieldtype) プラグインをインストールしてください。 -## リモートボリューム +## Lightswitch Fields -Amazon S3、Rackspace Cloud Files、および、Google Cloud Storage のサポートは、プラグインに移行されました。それらのサービスを Craft 2 で利用していたアセットボリュームがある場合、新しいプラグインをインストールする必要があります。 +Lightswitch field values are now always `true` or `false`. If you’re accessing a Lightswitch field value for an element that doesn’t have an explicit value set yet, the field’s default value will be returned instead. + +## Remote Volumes + +Support for Amazon S3, Rackspace Cloud Files, and Google Cloud Storage have been moved into plugins. If you have any asset volumes that were using those services in Craft 2, you will need to install the new plugins: - [Amazon S3](https://github.com/craftcms/aws-s3) - [Rackspace Cloud Files](https://github.com/craftcms/rackspace) - [Google Cloud Storage](https://github.com/craftcms/google-cloud) -## コンフィギュレーション +## Configuration ### コンフィグ設定 -いくつかの一般設定は Craft 3 でリネームされました。古い設定名は非推奨となりますが、Craft 4 までは動作し続けます。 +Some general config settings have been renamed in Craft 3. The old setting names have been deprecated, but will continue to work until Craft 4. | 旧設定 | 新設定 | | ---------------------------- | ------------------------------------------ | @@ -60,15 +64,15 @@ Amazon S3、Rackspace Cloud Files、および、Google Cloud Storage のサポ | `useWriteFileLock` | `useFileLocks` | | `validationKey` | `securityKey`4 | -*1 `backupOnUpdate` を `false` にすると、PHP によるバックアップの生成が行われないため、パフォーマンスは大きな要因になりえません。* +*1 Performance should no longer be a major factor when setting `backupOnUpdate` to `false`, since backups aren’t generated by PHP anymore.* -*2 `defaultFileMode` はデフォルトで `null` になりました。これは、現在の環境によって決定されることを意味します。* +*2 `defaultFileMode` is now `null` by default, meaning it will be determined by the current environment.* -*3 Craft 2 のコンフィグ設定 `environmentVariables` で定義された値をサポートする設定項目は、Craft 3 のシステム環境設定とエイリアスにセットできるようになりました。（詳細については、[環境設定](config/environments.md)を参照してください。）Craft 3 にアップデートすると、サイト URL やローカルボリュームの設定は新しい `@alias/sub/path` 構文へ自動的に変換されます。 +*3 Settings that supported values defined by your `environmentVariables` config setting in Craft 2 can now be set to system environment variables and aliases in Craft 3. (See [Environmental Configuration](config/environments.md) to learn more about those.) Site URL and Local volume settings will automatically be converted to the new `@alias/sub/path` syntax when updating to Craft 3. -*4 `securityKey` は、もはやオプションではありません。まだ設定していない場合、（ファイルが存在していれば）`storage/runtime/validation.key` に設定します。自動生成された `validation.key` ファイルのバックアップは、Craft 4 で削除されるでしょう。* +*4 `securityKey` is no longer optional. If you haven’t set it yet, set it to the value in `storage/runtime/validation.key` (if the file exists). The auto-generated `validation.key` file fallback will be removed in Craft 4.* -いくつかの設定は完全に削除されました。 +Some config settings have been removed entirely: | ファイル | 設定 | | ------------- | ------------------------------------------------------------------------------------------ | @@ -79,13 +83,13 @@ Amazon S3、Rackspace Cloud Files、および、Google Cloud Storage のサポ ### `omitScriptNameInUrls` と `usePathInfo` -`omitScriptNameInUrls` 設定は、Craft 2 のデフォルトがそうであったように `'auto'` にすることはもはやできません。HTTP リクエストを `index.php` にルーティングするようにサーバーを設定した場合、`config/general.php` で明示的に `true` にする必要があることを意味しています。 +The `omitScriptNameInUrls` setting can no longer be set to `'auto'`, as it was by default in Craft 2. Which means you will need to explicitly set it to `true` in `config/general.php` if you’ve configured your server to route HTTP requests to `index.php`. -同様に、`usePathInfo` 設定も `'auto'` にすることはできません。サーバーが [PATH_INFO](https://craftcms.com/support/enable-path-info) をサポートするよう設定されているならば、ここに `true` をセットできます。ただし、`omitScriptNameInUrls` を `true` にセットできない場合のみ、必要となります。 +Similarly, the `usePathInfo` setting can no longer be set to `'auto'` either. If your server is configured to support [PATH_INFO](https://craftcms.com/support/enable-path-info), you can set this to `true`. This is only necessary if you can’t set `omitScriptNameInUrls` to `true`, though. -## URL ルール +## URL Rules -`config/routes.php` に [URL ルール](config/README.md#url-rules)を保存しているならば、Yii 2 の [pattern-route 構文](https://www.yiiframework.com/doc/guide/2.0/en/runtime-routing#url-rules) にアップデートする必要があります。 +If you have any [URL rules](config/README.md#url-rules) saved in `config/routes.php`, you will need to update them to Yii 2’s [pattern-route syntax](https://www.yiiframework.com/doc/guide/2.0/en/runtime-routing#url-rules). - パターンの名前付けされたパラメータは、正規表現のサブパターン（`(?PRegExp)`）ではなく、フォーマット（``）を使用して定義する必要があります。 - 名前付けされていないパラメータ（例：`([^\/]+)`）は、もはや許可されません。新しい名前付けされたパラメータ構文（``）に変換しなければなりません。 @@ -106,22 +110,22 @@ Amazon S3、Rackspace Cloud Files、および、Google Cloud Storage のサポ 'blog/type/' => ['template' => 'blog/_type'], ``` -## PHP 定数 +## PHP Constants -いくつかの PHP 定数は Craft 3 で非推奨となり、Craft 4 で動作しなくなります +Some PHP constants have been deprecated in Craft 3, and will no longer work in Craft 4: | 旧 PHP 定数 | 代わりにすべきこと | | ---------------- | ------------------------------------------------------------------------------------- | | `CRAFT_LOCALE` | [CRAFT_SITE](config/php-constants.md#craft-site) 定数1 を使用してください | | `CRAFT_SITE_URL` | コンフィグ設定 、または、[環境変数](config/environments.md)を使用してください | -*1 Craft 3 ではそれぞれのサイト / ロケールごとに独自の `index.php` ファイルを用意することが必須ではなくなりました。そのため、不要になったすべてのサイト / ロケールのウェブルート、および、サブフォルダーを削除することもできます。詳細については、新しい [ローカライゼーションガイド](localization.md) を参照してください。* +*1 Craft 3 doesn’t require each site/locale to have its own `index.php` file anymore, so alternatively you can remove all unnecessary site/locale web roots and subfolders. See the new [Localization guide](localization.md) for more info.* -## 静的な翻訳ファイル +## Static Translation Files -Craft 3 でも[静的メッセージの翻訳](static-translations.md)をサポートしていますが、ディレクトリ構造が変わりました。`translations/` フォルダの中にローケルごとのサブディレクトリを作成し、それぞれに**翻訳カテゴリ**ごとの PHP ファイルを作成する必要があります。 +Craft 3 still supports [static message translations](static-translations.md), but the directory structure has changed. Now within your `translations/` folder, you should create subdirectories for each locale, and within them, PHP files for each **translation category**. -受け入れられる翻訳カテゴリは、次の通りです。 +The acceptable translation categories are: | カテゴリ | 説明 | | --------------- | ---------------- | @@ -130,7 +134,7 @@ Craft 3 でも[静的メッセージの翻訳](static-translations.md)をサポ | `site` | サイト固有の翻訳メッセージ | | `plugin-handle` | プラグイン向けの翻訳メッセージ | -Craft 3 の `translations/` フォルダの構成は、次のようになります。 +In Craft 3, your `translations/` folder might look something like this: ``` translations/ @@ -139,11 +143,11 @@ translations/ └── site.php ``` -## ユーザーフォト +## User Photos -ユーザーフォトはアセットとして保存されるようになりました。Craft 3 にアップグレードすると、Craft は（ `/` サブフォルダを除く、Craft が事前にすべてのユーザー画像を保管している） `storage/userphotos/` を「User Photos」と呼ばれる新しいアセットボリュームとして自動的に作成します。しかしながら、このフォルダはウェブルートよりも上位階層にあるため、HTTP リクエストでアクセスできません。 そのため、このボリュームをアクセスできる状態にするまで、ユーサーフォトはフロントエンドで動作しません。 +User photos are stored as assets now. When upgrading to Craft 3, Craft will automatically create a new asset volume called “User Photos” at `storage/userphotos/` (where Craft previously stored all user photos, but without the `/` subfolders). However this folder is above your web root and inaccessible to HTTP requests, so until you make this volume publicly accessible, user photos will not work on the front end. -次の方法で解決してください。 +Here’s how you can resolve this: 1. `storage/userphotos/` フォルダをウェブルート下層のどこかに移動します。（例：`web/userphotos/`） 2. 「設定 > アセット > ボリューム > User Photos」に移動し、新しいフォルダのロケーションに基づいてボリュームを設定します。 @@ -154,11 +158,11 @@ translations/ ## Twig 2 -Craft 3 では、テンプレート向けに独自の変更を加えた Twig 2 を使用しています。 +Craft 3 uses Twig 2, which has its own breaking changes for templates: ### マクロ -Twig 2 では、利用先となる各テンプレートで明示的にマクロをインポートする必要があります。親テンプレートでインクルードしている場合だけでなく、同じテンプレートファイルで定義されているときでさえも、自動的に利用することはできません。 +Twig 2 requires that you explicitly import macros in each template where you are using them. They are no longer automatically available if a parent template is including them, or even if they were defined in the same template file. ```twig Old: @@ -173,7 +177,7 @@ New: ### 未定義のブロック -Twig 1 では、存在しないブロックでさえも `block()` で呼び出すことができます。 +Twig 1 let you call `block()` even for blocks that didn’t exist: ```twig {% if block('foo') is not empty %} @@ -181,7 +185,7 @@ Twig 1 では、存在しないブロックでさえも `block()` で呼び出 {% endif %} ``` -Twig 2 では、`defined` のテストでない限り、エラーを返します。 +Twig 2 will throw an error unless it’s a `defined` test: ```twig {% if block('foo') is defined %} @@ -189,11 +193,11 @@ Twig 2 では、`defined` のテストでない限り、エラーを返します {% endif %} ``` -## テンプレートタグ +## Template Tags -[{% paginate %}](dev/tags/paginate.md) タグは `{% endpaginate %}` 終了タグを持たなくなったため、そのインスタンスをすべて削除します。 +The [{% paginate %}](dev/tags/paginate.md) tag no longer has an `{% endpaginate %}` closing tag, so remove any instances of that. -いくつかの Twig テンプレートタグは Craft 3 で非推奨となり、Craft 4 で完全に削除されます。 +Some Twig template tags have been deprecated in Craft 3, and will be completely removed in Craft 4: | 旧タグ | 代わりにすべきこと | | ------------------------------- | -------------------------------------------------------- | @@ -205,9 +209,9 @@ Twig 2 では、`defined` のテストでない限り、エラーを返します | `{% includeCssResource path %}` | [アセットバンドル](extend/asset-bundles.md)を使用してください | | `{% includeJsResource path %}` | [アセットバンドル](extend/asset-bundles.md)を使用してください | -## テンプレートファンクション +## Template Functions -いくつかのテンプレートファンクションは完全に削除されました。 +Some template functions have been removed completely: | 旧テンプレートファンクション | 代わりにすべきこと | | ------------------------------------------- | ---------------------------------------------------------------- | @@ -222,9 +226,9 @@ Twig 2 では、`defined` のテストでない限り、エラーを返します | `craft.tasks.haveTasksFailed()` | *（該当なし）* | | `craft.tasks.isTaskRunning()` | `craft.app.queue.getHasReservedJobs()`1 | -*1 `queue` コンポーネントが を実装している場合のみ、使用可能です。* +*1 Only available if the `queue` component implements .* -いくつかのテンプレートファンクションは Craft 3 で非推奨となり、Craft 4 で完全に削除されます。 +Some template functions have been deprecated in Craft 3, and will be completely removed in Craft 4: | 旧テンプレートファンクション | 代わりにすべきこと | | ------------------------------------------------------- | ----------------------------------------------------------- | @@ -344,9 +348,9 @@ Twig 2 では、`defined` のテストでない限り、エラーを返します *1 `craft.app.request.isLivePreview` is also deprecated, and only will return `true` when previewing categories or plugin-supplied element types that don’t support the new previewing system. If you were calling this to work around Craft templating bugs in Live Preview requests, you can simply delete the condition now, and treat Live Preview requests the same as any other request type.* -## 日付フォーマット +## Date Formatting -`|currency` フィルタは にマップされるようになりました。従来と同じ動きになりますが、引数 `stripZeroCents` は `stripZeros` にリネームされ、キーと値の両方が必要となっているため、この引数をセットしている場合はテンプレートを更新する必要があります。 +Craft’s extended DateTime class has been removed in Craft 3. Here’s a list of things you used to be able to do in your templates, and what the Craft 3 equivalent is. (The DateTime object is represented by the `d` variable. In reality it could be `entry.postDate`, `now`, etc.) | 旧 | 新 | | ------------------------- | ---------------------------------- | @@ -372,9 +376,9 @@ Twig 2 では、`defined` のテストでない限り、エラーを返します | `{{ d.w3cDate() }}` | `{{ d|date('Y-m-d') }}` | | `{{ d.year() }}` | `{{ d|date('Y') }}` | -## 通貨フォーマット +## Currency Formatting -いくつかのエレメントクエリパラメータは削除されました。 +The `|currency` filter now maps to . It still works the same, but the `stripZeroCents` argument has been renamed to `stripZeros`, and pushed back a couple notches, so you will need to update your templates if you were setting that argument. ```twig Old: @@ -385,11 +389,11 @@ New: {{ num|currency('USD', stripZeros = true) }} ``` -## エレメントクエリ +## Element Queries ### クエリパラメータ -いくつかのエレメントクエリパラメータは Craft 3 でリネームされました。古いパラメータは非推奨となりますが、Craft 4 までは動作し続けます。 +Some element query params have been removed: | エレメントタイプ | 旧パラメータ | 代わりにすべきこと | | -------- | ---------------- | ------------------------------------------------ | @@ -403,7 +407,7 @@ New: | タグ | `set` | `group` パラメータを使用してください | | タグ | `orderBy:"name"` | `orderBy` パラメータに `'title'` をセットしてください | -`limit` パラメータは、100ではなく、デフォルトで `null`（無制限）がセットされるようになりました。 +Some element query params have been renamed in Craft 3. The old params have been deprecated, but will continue to work until Craft 4. | エレメントタイプ | 旧パラメータ | 新パラメータ | | -------- | ------------------------ | ---------------------- | @@ -417,11 +421,11 @@ New: #### `limit` パラメータ -パラメータ値を配列にセットする場合、配列の大括弧を記述**しなければなりません**。 +The `limit` param is now set to `null` (no limit) by default, rather than 100. #### パラメータを配列にセットする -Craft 2 では、パラメータ設定メソッド（例：`.type('article')`）を呼び出すときは、次のような手順になります。 +If you want to set a param value to an array, you now **must** type out the array brackets. ```twig Old: @@ -435,13 +439,13 @@ New: #### エレメントクエリの複製 -これによって、後続のクエリに影響を与えることなく、エレメントクエリのバリエーションを実行できるようにしています。例えば、 +In Craft 2, each time you call a parameter-setter method (e.g. `.type('article')`), the method would: 1. `ElementCriteriaModel` オブジェクトを複製する 2. 複製したオブジェクトのパラメータ値を設定する 3. 複製したオブジェクトを返す -この `.type()` は `type` パラメータを `query` の _clone_ に適用しているため、 `query.total()` には影響を与えません。入力タイプに関わらず、News エントリの総数を返します。 +That made it possible to execute variations of an element query, without affecting subsequent queries. For example: ```twig {% set query = craft.entries.section('news') %} @@ -449,16 +453,16 @@ New: {% set totalEntries = query.total() %} ``` -しかし、この動作は Craft 3 で変更されました。今では、パラメータ設定メソッドを呼び出すときは、次のような手順になります。 +Here `.type()` is applying the `type` parameter to a _clone_ of `query`, so it had no effect on `query.total()`, which will still return the total number of News entries, regardless of their entry types. -つまり、上記のサンプルコードでは `type` パラメータが適用されてしまうため、`totalEntries` には _Article_ エントリの総数がセットされます。 +This behavior has changed in Craft 3, though. Now any time you call a parameter-setter method, the method will: 1. 現在のエレメントクエリにパラメータ値を設定する 2. エレメントクエリを返す -Craft 2 動作に影響を与えるテンプレートがある場合、[clone()](dev/functions.md#clone-object) ファンクションを用いて修正できます。 +Which means in the above code example, `totalEntries` will be set to the total _Article_ entries, as the `type` parameter will still be applied. -`findElementAtOffset()` エレメントクエリメソッドは Craft 3 で削除されました。代わりに、`nth()` を使用してください。 +If you have any templates that count on the Craft 2 behavior, you can fix them using the [clone()](dev/functions.md#clone-object) function. ```twig {% set query = craft.entries.section('news') %} @@ -468,9 +472,9 @@ Craft 2 動作に影響を与えるテンプレートがある場合、[clone()] ### クエリメソッド -いくつかのエレメントクエリメソッドは Craft 3 でリネームされました。古いメソッドは非推奨となりますが、Craft 4 までは動作し続けます。 +The `findElementAtOffset()` element query method has been removed in Craft 3. Use `nth()` instead. -エレメントクエリを配列のように扱うサポートは Craft 3 で非推奨になり、Craft 4 で完全に削除されます。 +Some element query methods have been renamed in Craft 3. The old methods have been deprecated, but will continue to work until Craft 4. | 旧メソッド | 新メソッド | | --------------- | ----------------------------------------------- | @@ -482,9 +486,9 @@ Craft 2 動作に影響を与えるテンプレートがある場合、[clone()] ### クエリを配列として扱う -エレメントクエリをループする必要があるときは、明示的に `.all()` をコールし、データベースクエリを実行して得られる結果の配列を返す必要があります。 +Support for treating element queries as if they’re arrays has been deprecated in Craft 3, and will be completely removed in Craft 4. -エレメントクエリから結果の総数を取得したいときは、`.count()` メソッドを呼び出す必要があります。 +When you need to loop over an element query, you should start explicitly calling `.all()`, which will execute the database query and return the array of results: ```twig Old: @@ -496,7 +500,7 @@ New: {% for asset in entry.myAssetsField.all() %}...{% endfor %} ``` -代替方法として、実際のクエリ結果を事前にフェッチする必要があり、かつ `offset` や `limit` パラメータをセットしていない場合、 [length](https://twig.symfony.com/doc/2.x/filters/length.html) フィルタを使うことで、余分なデータベースクエリを必要とせず、結果の配列の合計サイズを確認できます。 +When you need to get the total number of results from an element query, you should call the `.count()` method: ```twig Old: @@ -506,7 +510,7 @@ New: {% set total = craft.entries.section('news').count() %} ``` -`last()` は Craft 3 で非推奨になりました。なぜなら、（`query.nth(query.count() - 1)` に相当する）2つのデータベースクエリを背後で実行する必要があることが明確ではないからです。 +Alternatively, if you already needed to fetch the actual query results, and you didn’t set the `offset` or `limit` params, you can use the [length](https://twig.symfony.com/doc/2.x/filters/length.html) filter to find the total size of the results array without the need for an extra database query. ```twig {% set entries = craft.entries() @@ -517,9 +521,9 @@ New: ### `last()` -ほとんどのケースでは、`.last()` の呼び出しを `.inReverse().one()` に置き換えることで、余分なデータベースクエリを必要とせず、同じ結果を得ることができます。（`inReverse()` は、生成された SQL のすべての `ORDER BY` カラムのソート方向を反転させます。） +`last()` was deprecated in Craft 3 because it isn’t clear that it needs to run two database queries behind the scenes (the equivalent of `query.nth(query.count() - 1)`). -`inReverse()` が期待した通りに動作しないケースが2つあります。 +In most cases you can replace calls to `.last()` with `.inReverse().one()` and get the same result, without the extra database query. (`inReverse()` will reverse the sort direction of all of the `ORDER BY` columns in the generated SQL.) ```twig {# Channel entries are ordered by `postDate DESC` by default, so this will swap @@ -531,12 +535,12 @@ New: .one() %} ``` -このようなケースでは、 `.last()` の呼び出しを内部的な処理で置き換えることができます。 +There are two cases where `inReverse()` won’t work as expected, though: - SQL に `ORDER BY` 句が存在しない場合、反転できるものがありません - `orderBy` パラメータに オブジェクトが含まれている場合 -タグエレメントは、もはや `name` プロパティを持ちません。代わりに、`title` を使用してください。 +In those cases, you can just replace the `.last()` call with what it’s already doing internally: ```twig {% set query = craft.entries() @@ -545,19 +549,19 @@ New: {% set last = query.nth(total - 1) %} ``` -## エレメント +## Elements -すべてのエレメントの `locale` プロパティは非推奨となり、Craft 4 で完全に削除されます。エレメントのサイト ID が判る場合は `siteId`、ハンドルが判る場合は `site.handle`、サイトの言語が判る場合は `site.language` をそれぞれ使用してください。 +Tag elements no longer have a `name` property. Use `title` instead. -モデルの `getError('attribute')` メソッドは非推奨となり、Craft 4 で完全に削除されます。代わりに、`getFirstError('attribute')` を使用してください。 +All elements’ `locale` properties have been deprecated, and will be completely removed in Craft 4. Use `siteId` if you need to know an element’s site ID, `site.handle` if you need to know its handle, or `site.language` if you need to know its site’s language. -## モデル +## Models -いくつかのロケールメソッドは Craft 3 で非推奨となり、Craft 4 で完全に削除されます。 +Models’ `getError('attribute')` methods have been deprecated, and will be completely removed in Craft 4. Use `getFirstError('attribute')` instead. -## ロケール +## Locales -コントローラーアクションに送信するフロントエンドの ``や JavaScript は、次の変更を加えてアップデートする必要があります。 +Some locale methods have been deprecated in Craft 3, and will be completely removed in Craft 4: | 旧メソッド | 代わりにすべきこと | | ----------------- | ------------------------------------ | @@ -565,13 +569,13 @@ New: | `getName()` | `getDisplayName(craft.app.language)` | | `getNativeName()` | `getDisplayName()` | -## リクエストパラメータ +## Request Params -`action` パラメータは `camelCase` ではなく `kebab-case` に書き換えなければなりません。 +Your front-end ``s and JS scripts that submit to a controller action will need to be updated with the following changes. ### `action` パラメータ -いくつかのコントローラーアクションはリネームされました。 +`action` params must be rewritten in `kebab-case` rather than `camelCase`. ```twig Old: @@ -581,7 +585,7 @@ New: ``` -`redirect` パラメータは、ハッシュ値に変換しなければなりません。 +Some controller actions have been renamed: | 旧コントローラーアクション | 新コントローラーアクション | | ---------------------------- | --------------------------------- | @@ -592,7 +596,7 @@ New: ### `redirect` パラメータ -`redirectInput()` ファンクションは、ショートカットとして提供されています。 +`redirect` params must be hashed now. ```twig Old: @@ -602,13 +606,13 @@ New: ``` -いくつかの `redirect` パラメータトークンはリネームされました。 +The `redirectInput()` function is provided as a shortcut. ```twig {{ redirectInput('foo/bar') }} ``` -CSRF プロテクションは、Craft 3 ではデフォルトで有効になりました。（コンフィグ設定 `enableCsrfProtection` で）有効化していなかった場合、 コントローラーアクションで送信するフロントエンドのすべての `` と JavaScript に新しい CSRF トークンパラメータを追加するアップデートが必要です。 +Some `redirect` param tokens have been renamed: | コントローラーアクション | 旧トークン | 新トークン | | ------------------------------- | ------------- | ------ | @@ -622,7 +626,7 @@ CSRF プロテクションは、Craft 3 ではデフォルトで有効になり ### CSRF トークンパラメータ -`csrfInput()` ファンクションは、ショートカットとして提供されています。 +CSRF protection is enabled by default in Craft 3. If you didn’t already have it enabled (via the `enableCsrfProtection` config setting), each of your front-end ``s and JS scripts that submit to a controller action will need to be updated with a new CSRF token param. ```twig {% set csrfParam = craft.app.request.csrfParam %} @@ -630,12 +634,12 @@ CSRF プロテクションは、Craft 3 ではデフォルトで有効になり ``` -[Craft 3 のためのプラグインアップデート](extend/updating-plugins.md)を参照してください。 +The `csrfInput()` function is provided as a shortcut. ```twig {{ csrfInput() }} ``` -## プラグイン +## Plugins See [Updating Plugins for Craft 3](extend/updating-plugins.md). From 06b2b7ef92f81ced342a6125709873f2f7f1020c Mon Sep 17 00:00:00 2001 From: Brad Bell Date: Fri, 12 Jun 2020 17:33:31 -0700 Subject: [PATCH 065/245] New translations checkboxes-fields.md (French) --- fr/checkboxes-fields.md | 12 ++++++------ 1 file changed, 6 insertions(+), 6 deletions(-) diff --git a/fr/checkboxes-fields.md b/fr/checkboxes-fields.md index 20d9b89adc0..68979d0f899 100644 --- a/fr/checkboxes-fields.md +++ b/fr/checkboxes-fields.md @@ -16,12 +16,12 @@ When [querying for elements](dev/element-queries/README.md) that have a Checkbox Possible values include: -| Value | Fetches elements… -| - | - -| `'foo'` | with a `foo` option checked. -| `'not foo'` | without a `foo` option checked. -| `['foo', 'bar']` | with `foo` or `bar` options selected. -| `['and', 'foo', 'bar']` | with `foo` and `bar` options selected. +| Value | Fetches elements… | +| ----------------------- | -------------------------------------- | +| `'foo'` | with a `foo` option checked. | +| `'not foo'` | without a `foo` option checked. | +| `['foo', 'bar']` | with `foo` or `bar` options selected. | +| `['and', 'foo', 'bar']` | with `foo` and `bar` options selected. | ```twig {# Fetch entries with the 'foo' option checked #} From 3b6b6add274fe34947a0e44f8ea9c6c33043aba3 Mon Sep 17 00:00:00 2001 From: Brad Bell Date: Fri, 12 Jun 2020 17:33:33 -0700 Subject: [PATCH 066/245] New translations checkboxes-fields.md (Japanese) --- ja/checkboxes-fields.md | 12 ++++++------ 1 file changed, 6 insertions(+), 6 deletions(-) diff --git a/ja/checkboxes-fields.md b/ja/checkboxes-fields.md index b3d78cb05d0..67e2c2f0d64 100644 --- a/ja/checkboxes-fields.md +++ b/ja/checkboxes-fields.md @@ -16,12 +16,12 @@ 利用可能な値には、次のものが含まれます。 -| 値 | 取得するエレメント -| - | - -| `'foo'` | `foo` オプションが選択されている。 -| `'not foo'` | `foo` オプションが選択されていない。 -| `['foo', 'bar']` | with `foo` or `bar` options selected. -| `['and', 'foo', 'bar']` | with `foo` and `bar` options selected. +| 値 | 取得するエレメント | +| ----------------------- | -------------------------------------- | +| `'foo'` | `foo` オプションが選択されている。 | +| `'not foo'` | `foo` オプションが選択されていない。 | +| `['foo', 'bar']` | with `foo` or `bar` options selected. | +| `['and', 'foo', 'bar']` | with `foo` and `bar` options selected. | ```twig {# Fetch entries with the 'foo' option checked #} From 805d102a6436ac778ec5260f21b574144cc33378 Mon Sep 17 00:00:00 2001 From: Brad Bell Date: Fri, 12 Jun 2020 17:33:35 -0700 Subject: [PATCH 067/245] New translations installation.md (Japanese) --- ja/installation.md | 24 +++++++++++++----------- 1 file changed, 13 insertions(+), 11 deletions(-) diff --git a/ja/installation.md b/ja/installation.md index e99d4d3cb2a..ec13bc47eaa 100644 --- a/ja/installation.md +++ b/ja/installation.md @@ -26,8 +26,8 @@ Composer がすべてをロードするのに、数分かかるでしょう。 作業に適したアーカイブ形式をダウンロードします。 -- **zip**: [3.3.20.1](https://download.craftcdn.com/craft/3.3/Craft-3.3.20.1.zip), [latest](https://craftcms.com/latest-v3.zip) -- **tar.gz**: [3.3.20.1](https://download.craftcdn.com/craft/3.3/Craft-3.3.20.1.tar.gz), [latest](https://craftcms.com/latest-v3.tar.gz) +- [zip](https://craftcms.com/latest-v3.zip) +- [tar.gz](https://craftcms.com/latest-v3.tar.gz) 新しい Craft プロジェクトを稼働したい場所でアーカイブを展開します。 @@ -142,19 +142,23 @@ Craft プロジェクトをホストするための新しいウェブサーバ ついに、Craft のセットアップウィザードを実行するときがきました。[ターミナル](#terminal-setup) または [ウェブブラウザ](#web-browser-setup) から実行できます。 +::: tip +We recommend using the `.test` TLD for local development, and specifically not `.local` on macOS since [conflicts with Bonjour can lead to performance issues](https://help.rm.com/technicalarticle.asp?cref=tec3015691). +::: + ## ステップ 6：セットアップウィザードの実行 -ターミナル上でプロジェクトのルートディレクトリに移動し、次のコマンドを実行してセットアップウィザードを開始します。 +Finally, it’s time to run Craft’s Setup Wizard. You can either run that from your [terminal](#terminal-setup) or your [web browser](#web-browser-setup). ### ターミナルによるセットアップ -このコマンドは、データベースへの接続方法を学んだ上で Craft のインストーラーを開始するために、いくつかの質問をします。それが終われば、ウェブブラウザから新しい Craft サイトにアクセスできるはずです。 +In your terminal, go to your project’s root directory and run the following command to kick off the Setup Wizard: ```bash ./craft setup ``` -ウェブブラウザで `http:///index.php?p=admin/install`（ウェブサーバーのホスト名で `` を置き換える）に移動します。ここまでのステップがうまくいっていれば、Craft のセットアップウィザードが迎えてくれるでしょう。 +The command will ask you a few questions to learn how to connect to your database, and then kick off Craft’s installer. Once it’s done, you should be able to access your new Craft site from your web browser. ### ウェブブラウザによるセットアップ @@ -166,9 +170,7 @@ The first step of the installer is to accept the [license agreement](https://cra ![Craft Installation License Agreement](./images/installation-step-1.png) -::: tip -Craft がすでにデータベースに接続可能な状態であれば、このステップはスキップされます。 -::: +The second step is to enter your database connection information. ::: tip If the Setup Wizard skips this step, it’s because Craft is already able to connect to your database. @@ -184,12 +186,12 @@ The final step is to define your System Name, Base URL, and Language. ![Craft Installation System Settings](./images/installation-step-4.png) -インストールが成功したら、Craft はブラウザをコントロールパネルにリダイレクトします。 +Click “Finish up” to complete the setup process. A few seconds later, you should have a working Craft install! -If it was successful, Craft will redirect your browser to the Control Panel. +If it was successful, Craft will redirect your browser to the control panel. ![Craft Installation Complete](./images/installation-step-5.png) -さぁ、素晴らしいものを築きあげましょう。 +Congratulations, you’ve just installed Craft! Now build something incredible. From 3bcd2ac2d8274ecc841090c8e245c2084d2108bc Mon Sep 17 00:00:00 2001 From: Brad Bell Date: Fri, 12 Jun 2020 17:33:37 -0700 Subject: [PATCH 068/245] New translations lightswitch-fields.md (Japanese) --- ja/lightswitch-fields.md | 49 ++++++++++++++++++++++++++++++++++++---- 1 file changed, 45 insertions(+), 4 deletions(-) diff --git a/ja/lightswitch-fields.md b/ja/lightswitch-fields.md index 8e7412f4531..ddeabe70875 100644 --- a/ja/lightswitch-fields.md +++ b/ja/lightswitch-fields.md @@ -2,16 +2,57 @@ Lightswitch フィールドでは、「はい」または「いいえ」の答えが必要なとき向けに、トグル入力を提供します。 -## フィールド +## Templating -## テンプレート記法 +### Querying Elements with Lightswitch Fields -このフィールドは、データベースから `1` または `0` のいずれかを返します。そのため、`on` の状態にあるかどうかを次のようにテンプレートからテストできます。 +When [querying for elements](dev/element-queries/README.md) that have a Lightswitch field, you can filter the results based on the Lightswitch field data using a query param named after your field’s handle. + +Possible values include: + +| Value | Fetches elements… | +| ------------------------ | ---------------------------------- | +| `true` or `':notempty:'` | with an enabled Lightswitch value. | +| `false` or `':empty:'` | with a disabled Lightswitch value. | + +```twig +{# Fetch entries with the Lightswitch field enabled #} +{% set entries = craft.entries() + .(true) + .all() %} +``` + +::: tip +Any elements that don’t have an explicit Lightswitch value set will be treated as if they have the default field value, per the field settings. +::: + +### Working with Lightswitch Field Data + +If you have an element with a Lightswitch field in your template, you can access its data using your Lightswitch field’s handle: ```twig -{% if entry.lightswitchFieldHandle %} +{% if entry. %}

    I'm on!

    {% else %}

    I'm off.

    {% endif %} ``` + +::: tip +If the element doesn’t have an explicit Lightswitch field value yet, the field’s default value will be returned. +::: + +### Saving Lightswitch Fields in Entry Forms + +If you have an [entry form](dev/examples/entry-form.md) that needs to contain a Lightswitch field, you can use this template as a starting point: + +```twig +{{ hiddenInput('fields[]', '') }} + +{{ tag('input', { + type: 'checkbox', + name: 'fields[]', + value: '1', + checked: (entry. ?? false) ? true : false, +}) }} +``` From 4397d13788bd6ebbb13a85ccd9ad903c53d26c0f Mon Sep 17 00:00:00 2001 From: Brad Bell Date: Fri, 12 Jun 2020 17:33:40 -0700 Subject: [PATCH 069/245] New translations tags-fields.md (Japanese) --- ja/tags-fields.md | 17 +++++++++++++---- 1 file changed, 13 insertions(+), 4 deletions(-) diff --git a/ja/tags-fields.md b/ja/tags-fields.md index b41018d8ebc..4d4403d2c39 100644 --- a/ja/tags-fields.md +++ b/ja/tags-fields.md @@ -43,10 +43,15 @@ 利用可能な値には、次のものが含まれます。 -| 値 | 取得するエレメント | -| -------------- | --------------------- | -| `':empty:'` | 関連付けられたタグを持たない。 | -| `':notempty:'` | 少なくとも1つの関連付けられたタグを持つ。 | +| 値 | 取得するエレメント | +| ------------------------------------------------------- | ----------------------------------------------------- | +| `':empty:'` | 関連付けられたタグを持たない。 | +| `':notempty:'` | 少なくとも1つの関連付けられたタグを持つ。 | +| `100` | that are related to the tag with an ID of 100. | +| `[100, 200]` | that are related to a tag with an ID of 100 or 200. | +| `['and', 100, 200]` | that are related to the tags with IDs of 100 and 200. | +| an [Tag](api:craft\elements\Tag) object | that are related to the tag. | +| an [TagQuery](api:craft\elements\db\TagQuery) object | that are related to any of the resulting tags. | ```twig {# Fetch entries with a related tag #} @@ -103,6 +108,10 @@ .all() %} ``` +::: tip +It’s always a good idea to clone the tag query using the [clone()](./dev/functions.md#clone) function before adjusting its parameters, so the parameters don’t have unexpected consequences later on in your template. +::: + ## 関連項目 * [タグクエリ](dev/element-queries/tag-queries.md) From eee1ac8d85b6bd51a8dfd97bcba922b78e827569 Mon Sep 17 00:00:00 2001 From: Brad Bell Date: Fri, 12 Jun 2020 17:33:41 -0700 Subject: [PATCH 070/245] New translations searching.md (Japanese) --- ja/searching.md | 18 +++++++++++------- 1 file changed, 11 insertions(+), 7 deletions(-) diff --git a/ja/searching.md b/ja/searching.md index 8d114438138..2271896efea 100644 --- a/ja/searching.md +++ b/ja/searching.md @@ -64,9 +64,13 @@ Craft は次の検索構文をサポートしています。 * title +::: warning +Searching is a great way to quickly query content broadly across elements, but if you’re querying field attributes the most precise way is through that field type’s [query parameter](dev/element-queries/#executing-element-queries). +::: + ## テンプレート記法 -`craft.assets()`、`craft.entries()`、`craft.tags()`、および、`craft.users()`は、検索クエリを指定したエレメントの絞り込みに利用できる `search` パラメータをサポートしています。 +`craft.assets()`, `craft.entries()`, `craft.tags()`, and `craft.users()` support a `search` parameter that you can use to filter their elements by a given search query. ```twig {# Get the user's search query from the 'q' query-string param #} @@ -80,7 +84,7 @@ Craft は次の検索構文をサポートしています。 ### スコアによる検索結果の順位付け -検索結果をベストマッチからワーストマッチの順に並び替えたい場合、`orderBy` パラメータに `'score'` をセットすることもできます。 +You can also set the `orderBy` parameter to `'score'` if you want results ordered by best-match to worst-match: ```twig {% set results = craft.entries() @@ -89,18 +93,18 @@ Craft は次の検索構文をサポートしています。 .all() %} ``` -この場合、返されるすべてのエレメントに `searchScore` 属性がセットされ、それぞれの検索スコアを知ることができます。 +When you do this, each of the elements returned will have a `searchScore` attribute set, which reveals what their search score was. ::: tip -動的な検索結果をリスト化する完全な例については、[検索フォーム](dev/examples/search-form.md)チュートリアルを参照してください。 +See our [Search Form](dev/examples/search-form.md) tutorial for a complete example of listing dynamic search results. ::: ## 検索インデックスの再構築 -Craft は検索インデックスを可能な限り最新に保つよう、最善を尽くしています。しかし、その一部を不正確にするかもしれない可能性がいくつかあります。検索インデックスが最新かつ最高データでないと疑われる場合、設定にある検索インデックスの再構築ツールで Craft に再構築させることができます。 +Craft does its best to keep its search indexes as up-to-date as possible, but there are a couple things that might render portions of them inaccurate. If you suspect that your search indexes don’t have the latest and greatest data, you can have Craft rebuild them by bulk-resaving your entries with the `resave/entries` command: ```bash -./craft resave/entries +./craft resave/entries --update-search-index ``` -You can specify which entries should be resaved with the `--section` and `--type` options, among others. Run `resave/entries --help` to see a full list of supported options. +You can specify which entries should be resaved with the `--section` and `--type` options, among others. Run `resave/entries --help` to see a full list of supported options. From 765614ee352cc177e1f0843a5b95a9058296c38f Mon Sep 17 00:00:00 2001 From: Brad Bell Date: Fri, 12 Jun 2020 17:33:43 -0700 Subject: [PATCH 071/245] New translations sections-and-entries.md (French) --- fr/sections-and-entries.md | 23 +++++++++++++++++------ 1 file changed, 17 insertions(+), 6 deletions(-) diff --git a/fr/sections-and-entries.md b/fr/sections-and-entries.md index 9de0a53faca..7e5ae03673e 100644 --- a/fr/sections-and-entries.md +++ b/fr/sections-and-entries.md @@ -19,7 +19,7 @@ Before you can create entries, you must create Sections to contain them. In each If you're using Craft with multiple sites then you can also define in your Section: -* Which sites entries in the section should target +* Which sites' entries in the section should target * Which sites are enabled by default for new entries To create a new section, go to Settings → Sections and click the “New Section” button. @@ -96,17 +96,23 @@ With the above Entry URI Format, a top-level entry’s URI might end up as `docs ### Preview Targets -Your entry content will likely show up in places other than just their main URLs. For example, the Blog index page will show excerpts of recent blog posts. +If you’re using Craft Pro, your section can have one or more **preview targets**, which are URLs of pages that your entries will show up on, making it possible for authors to preview entries as they are writing them in the control panel. -With Craft Pro, your sections will have a “Preview Targets” setting, where you can list additional places your entries will show up on your site, so that authors can quickly preview entries everywhere they appear. +Like entry URI formats, these preview target URLs are mini Twig templates that can contain entry properties and other dynamic values. -Each preview target has Name and a URI. Give each of your targets a clear name that authors will understand, such as “Homepage” or “Blog Index”. Set the URI to the actual URI you want to load when the target is selected. +If entries in your section have their own URLs, then you can create a preview target for the entry’s primary URL using the URL template, `{url}`. -The URI is a mini Twig template (just like Entry URI Formats), so you can make it dynamic if you need to. For example, if you are creating an “Archive” preview target, where the URI needs to include the year the entry was published, you can enter `archive/{postDate|date('Y')}`. +Create additional preview targets for any other areas the entry might show up, such as `news`, or `archive/{postDate|date('Y')}`. If the entries show up on the homepage, you can create a preview target with a blank URL. ![A section’s Preview Targets setting.](./images/preview-targets.png) +::: tip +If you want to include the entry’s ID or UID in a preview target URL, use `{sourceId}` or `{sourceUid}` rather than `{id}` or `{uid}`, so the source entry’s ID or UID is used rather than the draft’s. +::: + +::: tip You can also set the URI to a environment variable (e.g. `$NEWS_INDEX`, or a URL that begins with an alias (e.g. `@rootUrl/news` or `@rootUrl/news/{slug}`). See [Environmental Configuration](config/environments.md) to learn more about how those work. +::: When an author is editing an entry from a section with custom preview targets, the “Share” button will be replaced with a menu that lists the “Primary entry page” (if the section has an Entry URI Format), plus the names of each preview target. @@ -114,6 +120,11 @@ When an author is editing an entry from a section with custom preview targets, t The targets will also be available within Live Preview. +#### Preparing external front ends for Live Preview + +If your site’s front end lives outside of Craft, for example as a Vue or React app, you will need to have it check for the existence of a `token` query string parameter (or whatever your config setting is set to). If it’s in the URL, then you will need to pass that same token in the Craft API request that loads the page content. This token will cause the API request to respond with the correct content depending on what’s actually being edited (the source entry or a draft). + +You can pass the token via either a `token` query string parameter, or an `X-Craft-Token` header on the API request. ## Entry Types @@ -141,7 +152,7 @@ The entry is passed to this template as a variable named `object`. You can refer * `{{ object.property }}` *(normal Twig syntax)* * `{property}` *(shortcut syntax)* -*Note that the shortcut syntax only has one set of curly braces*. +_Note that the shortcut syntax only has one set of curly braces_. If Craft finds any of these in your Title Format, it will replace the `{` with `{{object.` and the `}` with `}}`, before passing the template off to Twig for parsing. From 5bca5b64edb1183cbd6e1bd6b833000a6417601e Mon Sep 17 00:00:00 2001 From: Brad Bell Date: Fri, 12 Jun 2020 17:33:44 -0700 Subject: [PATCH 072/245] New translations sections-and-entries.md (Japanese) --- ja/sections-and-entries.md | 39 ++++++++++++++++++++++++-------------- 1 file changed, 25 insertions(+), 14 deletions(-) diff --git a/ja/sections-and-entries.md b/ja/sections-and-entries.md index 97159977c66..3485057d1ce 100644 --- a/ja/sections-and-entries.md +++ b/ja/sections-and-entries.md @@ -19,7 +19,7 @@ Craft のマルチサイト機能を利用しているなら、次のこともセクションで定義できます。 -* セクション内のどのサイトのエントリをターゲットにするか +* Which sites' entries in the section should target * 新しいエントリ向けに、どのサイトをデフォルトで有効にするか 新しいセクションを作るには、「設定 > セクション」に移動し、「新規セクション」ボタンをクリックします。 @@ -96,34 +96,45 @@ Craft のマルチサイト機能を利用しているなら、次のことも ### 動的なエントリタイトル -チャンネルとストラクチャーセクションの両方では、入力タイプを用いて複数のタイプのエントリを定義できます。 +If you’re using Craft Pro, your section can have one or more **preview targets**, which are URLs of pages that your entries will show up on, making it possible for authors to preview entries as they are writing them in the control panel. -「設定 > セクション」のセクション名の横にある「入力タイプを変更してください。」リンクをクリックして、セクションの入力タイプを管理できます。セクションの入力タイプのインデックスに移動します。いずれかの入力タイプの名前をクリックすると、その設定ページへ移動します。 +Like entry URI formats, these preview target URLs are mini Twig templates that can contain entry properties and other dynamic values. -Each preview target has Name and a URI. Give each of your targets a clear name that authors will understand, such as “Homepage” or “Blog Index”. Set the URI to the actual URI you want to load when the target is selected. +If entries in your section have their own URLs, then you can create a preview target for the entry’s primary URL using the URL template, `{url}`. -入力タイプの設定は、次の通りです。 +Create additional preview targets for any other areas the entry might show up, such as `news`, or `archive/{postDate|date('Y')}`. If the entries show up on the homepage, you can create a preview target with a blank URL. ![A section’s Preview Targets setting.](./images/preview-targets.png) -タイトル形式は本格的な Twig テンプレートで、エントリが保存されるたびに解析されます。 +::: tip +If you want to include the entry’s ID or UID in a preview target URL, use `{sourceId}` or `{sourceUid}` rather than `{id}` or `{uid}`, so the source entry’s ID or UID is used rather than the draft’s. +::: -エントリは `object` という名称の変数としてこのテンプレートに渡されます。エントリの [プロパティ](api:craft\elements\Entry#public-properties) は、次の2つの方法で参照できます。 +::: tip +You can also set the URI to a environment variable (e.g. `$NEWS_INDEX`, or a URL that begins with an alias (e.g. `@rootUrl/news` or `@rootUrl/news/{slug}`). See [Environmental Configuration](config/environments.md) to learn more about how those work. +::: -_ショートカット構文には、中括弧が1つしかないことに注意してください_。 +When an author is editing an entry from a section with custom preview targets, the “Share” button will be replaced with a menu that lists the “Primary entry page” (if the section has an Entry URI Format), plus the names of each preview target. -Craft がタイトル形式の中でショートカット構文を見つけた場合、Twig の解析にあたりテンプレートへ渡す前に `{` を `{{object.` 、`}` を `}}` に置換します。 +!\[An entry’s Share menu with 3 custom preview targets.\](./images/share-with-targets.png =294x) +The targets will also be available within Live Preview. + +#### Preparing external front ends for Live Preview + +If your site’s front end lives outside of Craft, for example as a Vue or React app, you will need to have it check for the existence of a `token` query string parameter (or whatever your config setting is set to). If it’s in the URL, then you will need to pass that same token in the Craft API request that loads the page content. This token will cause the API request to respond with the correct content depending on what’s actually being edited (the source entry or a draft). + +You can pass the token via either a `token` query string parameter, or an `X-Craft-Token` header on the API request. ## 入力タイプ -いずれの構文でも Twig フィルタを使えます。 +Both Channel and Structure sections let you define multiple types of entries using Entry Types. -Craft の[グローバル変数](dev/global-variables.md)は、これらのテンプレートでも利用できます。 +You can manage your sections’ Entry Types by clicking the “Edit Entry Types” link beside the section’s name in Settings → Sections. That’ll take you to the section’s entry type index. Clicking on an entry type’s name takes you to its settings page: ![Entry Type Edit Settings](./images/sections-and-entries-entry-types.png) -少なくとも1つのセクションがあれば、CP のメインナビゲーションに「エントリ」タブが表示されます。クリックすると、エントリのインデックスに移動します。そこから、編集したいエントリに移動したり、新しいエントリを作成できます。 +Entry types have the following settings: * **名前** – 入力タイプの名前 * **ハンドル** – 入力タイプのテンプレートに対応するハンドル @@ -132,9 +143,9 @@ Craft の[グローバル変数](dev/global-variables.md)は、これらのテ ### Dynamic Entry Titles -エントリの編集ページでは、次のアクションを実行できます。 +If you want your entries to have auto-generated titles rather than requiring authors to enter them, you can uncheck the “Show the Title field?” checkbox. When you do, a new “Title Format” setting will appear, where you can define what the auto-generated titles should look like. -投稿日を空のままにした場合、Craft はエントリが有効な状態で保存された最初のタイミングで自動的にセットします。 +The Title Format is a full-blown Twig template, and it will get parsed whenever your entries are saved. The entry is passed to this template as a variable named `object`. You can reference the entry’s [properties](api:craft\elements\Entry#public-properties) in two ways: From 7225f7013da3e63c3d7312b72f0ed0746c72aba3 Mon Sep 17 00:00:00 2001 From: Brad Bell Date: Fri, 12 Jun 2020 17:33:46 -0700 Subject: [PATCH 073/245] New translations sites.md (French) --- fr/sites.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/fr/sites.md b/fr/sites.md index 22315c7a181..1194fd7ce53 100644 --- a/fr/sites.md +++ b/fr/sites.md @@ -78,7 +78,7 @@ Multiple sites can share the same host name, such as `https://craftcms.com/` and If you want to create a site with a different host name, you must configure your server to handle traffic for it. The host name can either point to the same web root as your current site (e.g. `web/`), or you may want to give it its own separate web root. If you do the latter, make sure you copy your `.htaccess` and `index.php` files into the new web root. ::: tip -If you have multiple sites using different root domains like `https://site-a.com` and `https://site-b.com`, with the way Craft’s [license enforcements works](https://craftcms.com/support/license-enforcement), you’ll want to pick one of the domains to access the Craft Control Panel from for *all* of the sites. +If you have multiple sites using different root domains like `https://site-a.com` and `https://site-b.com`, with the way Craft’s [license enforcements works](https://craftcms.com/support/license-enforcement), you’ll want to pick one of the domains to access the Craft control panel from for _all_ of the sites. ::: ::: warning @@ -103,7 +103,7 @@ The first step is to create the new site in the Settings of your Craft installat 1. Go to Settings → Sites and click the New Site button. 2. Choose the group your site should belong to using the drop-down. The group selection won't have any impact on your site's functionality. -3. Give your site a name. Craft uses the site name in the Control Panel and you can also display it in your templates using `{{ siteName }}`. +3. Give your site a name. Craft uses the site name in the control panel, and you can also display it in your templates using `{{ siteName }}`. 4. Based on the Site name, Craft will generate a Site Handle. You can edit the Handle if you'd like. You will use the Site Handle to refer to this site in the templates. 5. Choose the language for this site (see above for more information on how you can use languages). 6. If this site should be the Primary Site, toggle the Is Primary Site? to enable it. From ef1a27f4f957a123c28f7352731111620829b30b Mon Sep 17 00:00:00 2001 From: Brad Bell Date: Fri, 12 Jun 2020 17:33:48 -0700 Subject: [PATCH 074/245] New translations sites.md (Japanese) --- ja/sites.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/ja/sites.md b/ja/sites.md index aeea5dafb23..1f179deefd8 100644 --- a/ja/sites.md +++ b/ja/sites.md @@ -78,7 +78,7 @@ Craft はデフォルトサイトをプライマリサイトとしてセット 異なるホスト名でサイトを作成したい場合、それに対するトラフィックを処理するようサーバーを設定しなければなりません。ホスト名は現在のサイトと同じウェブルート（`web/`）を指すことも、独自の別のウェブルートにすることもできます。後者の場合、`.htaccess`、および、`index.php` ファイルを新しいウェブルートへ確実にコピーしてください。 ::: tip -`https://site-a.com` と `https://site-b.com` のような異なるルートドメインを使用するマルチサイトを持つ場合、Craft の [license enforcements works](https://craftcms.com/support/license-enforcement) の仕組みによって、_すべて_ のサイトのためにアクセスする Craft コントロールパネルのドメインをその中の1つから選択することができます。 +If you have multiple sites using different root domains like `https://site-a.com` and `https://site-b.com`, with the way Craft’s [license enforcements works](https://craftcms.com/support/license-enforcement), you’ll want to pick one of the domains to access the Craft control panel from for _all_ of the sites. ::: ::: warning @@ -103,7 +103,7 @@ Craft はデフォルトサイトをプライマリサイトとしてセット 1. 「設定 > サイト」に移動し、「新しいサイト」ボタンをクリックします。 2. ドロップダウンメニューからサイトが所属するグループを選択します。グループの選択により、サイトの機能に影響することはありません。 -3. 名前を付けてください。Craft はコントロールパネルのサイト名を利用し、`{{ siteName }}` を使ってテンプレート内に表示することもできます。 +3. Give your site a name. Craft uses the site name in the control panel, and you can also display it in your templates using `{{ siteName }}`. 4. サイト名をベースにして、Craft はサイトのハンドルを生成します。あなたが望むなら、ハンドルを編集できます。テンプレート内でこのサイトを参照するために、サイトハンドルを利用します。 5. サイトの言語を選択してください。（言語の使い方の詳細は、上記を参照してください） 6. このサイトをプライマリサイトにする場合は、「これはプライマリサイトですか？」をオンにします。to enable it. From 4189cdcfa4a9f0d9763fb28c1ecc7a25da6afc5e Mon Sep 17 00:00:00 2001 From: Brad Bell Date: Fri, 12 Jun 2020 17:33:49 -0700 Subject: [PATCH 075/245] New translations static-translations.md (French) --- fr/static-translations.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/fr/static-translations.md b/fr/static-translations.md index 47d40b37e9f..b7add06bf5a 100644 --- a/fr/static-translations.md +++ b/fr/static-translations.md @@ -7,7 +7,7 @@ If you’re building a multilingual site or app, then these messages will need t To do that, Craft employs Yii’s [Message Translations](https://www.yiiframework.com/doc/guide/2.0/en/tutorial-i18n#message-translation) feature, and pre-defines special translation categories: - `site` is used for messages that belong to the project. -- `app` is used for Craft Control Panel messages. +- `app` is used for Craft control panel messages. - Each plugin gets its own category as well, based on the plugin’s handle. ## Prep Your Messages @@ -35,7 +35,7 @@ echo Craft::t('site', 'Contact us'); Once you’ve prepped a message for translations, you need to supply the actual translation. -To do that, create a new folder in your project’s base directory called `translations/`, and within that, create a new folder named after the target language’s ID. Within that, create a file named after the translation category you want to create massages for (`site.php` for project messages, `app.php` to overwrite Craft's Control Panel messages, or `.php` to overwrite a plugin’s messages). +To do that, create a new folder in your project’s base directory called `translations/`, and within that, create a new folder named after the target language’s ID. Within that, create a file named after the translation category you want to create massages for (`site.php` for project messages, `app.php` to overwrite Craft's control panel messages, or `.php` to overwrite a plugin’s messages). For example, if you want to translate your project’s messages into German, this is what your project’s directory structure should look like: From 8711db33ad878b469031db4965ca31d0ac6ece2e Mon Sep 17 00:00:00 2001 From: Brad Bell Date: Fri, 12 Jun 2020 17:33:51 -0700 Subject: [PATCH 076/245] New translations static-translations.md (Japanese) --- ja/static-translations.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/ja/static-translations.md b/ja/static-translations.md index f1babefb457..eed04a3ec61 100644 --- a/ja/static-translations.md +++ b/ja/static-translations.md @@ -7,7 +7,7 @@ そのため、Craft は Yii の[メッセージ翻訳](https://www.yiiframework.com/doc/guide/2.0/en/tutorial-i18n#message-translation)機能を採用し、 特別な翻訳カテゴリを事前に定義しています。 - `site` はプロジェクトに属するメッセージに使用されます。 -- `app` はコントロールパネルのメッセージに使用されます。 +- `app` is used for Craft control panel messages. - それぞれのプラグインは、プラグインのハンドルに基づいて独自のカテゴリも取得します。 ## メッセージの準備 @@ -35,7 +35,7 @@ $label = Craft::t('site', 'Contact us'); 翻訳のためのメッセージを準備したら、実際の翻訳を提供する必要があります。 -そのために、プロジェクトのベースディレクトリに `translations/` と呼ばれる新しいフォルダを作成し、その中に対象言語の ID を名前とした新しいフォルダを作成します。その中に、メッセージを作成したい翻訳カテゴリの名前をつけたファイルを作成します（プロジェクトメッセージのための `site.php`、Craft のコントロールパネルのメッセージを上書きするための `app.php`、または、プラグインのメッセージを上書きするための `.php`）。 +To do that, create a new folder in your project’s base directory called `translations/`, and within that, create a new folder named after the target language’s ID. Within that, create a file named after the translation category you want to create massages for (`site.php` for project messages, `app.php` to overwrite Craft's control panel messages, or `.php` to overwrite a plugin’s messages). 例えば、プロジェクトのメッセージをドイツ語に翻訳する場合、プロジェクトのディレクトリ構造は次のようになります。 From b2e6d2a63deae3ca190250c3c5db9970ea040104 Mon Sep 17 00:00:00 2001 From: Brad Bell Date: Fri, 12 Jun 2020 17:33:53 -0700 Subject: [PATCH 077/245] New translations tags-fields.md (French) --- fr/tags-fields.md | 13 +++++++++---- 1 file changed, 9 insertions(+), 4 deletions(-) diff --git a/fr/tags-fields.md b/fr/tags-fields.md index 1cd05a8bfc4..f461b8cbe48 100644 --- a/fr/tags-fields.md +++ b/fr/tags-fields.md @@ -43,10 +43,15 @@ When [querying for elements](dev/element-queries/README.md) that have a Tags fie Possible values include: -| Value | Fetches elements… -| - | - -| `':empty:'` | that don’t have any related tags. -| `':notempty:'` | that have at least one related tag. +| Value | Fetches elements… | +| ------------------------------------------------------- | ----------------------------------------------------- | +| `':empty:'` | that don’t have any related tags. | +| `':notempty:'` | that have at least one related tag. | +| `100` | that are related to the tag with an ID of 100. | +| `[100, 200]` | that are related to a tag with an ID of 100 or 200. | +| `['and', 100, 200]` | that are related to the tags with IDs of 100 and 200. | +| an [Tag](api:craft\elements\Tag) object | that are related to the tag. | +| an [TagQuery](api:craft\elements\db\TagQuery) object | that are related to any of the resulting tags. | ```twig {# Fetch entries with a related tag #} From f5c38353322b10ae658e4fb152569ddf9c9713d6 Mon Sep 17 00:00:00 2001 From: Brad Bell Date: Fri, 12 Jun 2020 17:33:56 -0700 Subject: [PATCH 078/245] New translations testing-tips.md (French) --- fr/testing/testing-craft/testing-tips.md | 8 +++----- 1 file changed, 3 insertions(+), 5 deletions(-) diff --git a/fr/testing/testing-craft/testing-tips.md b/fr/testing/testing-craft/testing-tips.md index 7482b8537b2..ab2b99d621b 100644 --- a/fr/testing/testing-craft/testing-tips.md +++ b/fr/testing/testing-craft/testing-tips.md @@ -1,14 +1,12 @@ # Testing Tips -## Maintain your database +## Maintain Your Database The Craft module provides a `cleanup` and `transaction` option for the `codeception.yml` file. It is recommended that you set these options to `true`. ### `transactions` -The transaction option ensures that changes made to the database during your test are rolled back using a Yii2 -[transaction](https://www.yiiframework.com/doc/api/2.0/yii-db-transaction). This means that if you, -for example, save a `craft\db\ActiveRecord` instance before the next test that database row is removed. This prevents collisions and prevents you from spending hours debugging your tests. +The transaction option ensures that changes made to the database during your test are rolled back using a Yii2 [transaction](https://www.yiiframework.com/doc/api/2.0/yii-db-transaction). This means that if you, for example, save a `craft\db\ActiveRecord` instance before the next test that database row is removed. This prevents collisions and prevents you from spending hours debugging your tests. ::: warning If you are running MySQL the `[[%searchindex]]` table may be running the MyISAM Database driver. If this is the case transactions are [not-supported](https://dev.mysql.com/doc/refman/5.6/en/myisam-storage-engine.html). @@ -28,7 +26,7 @@ In the [getting started](../testing-craft/getting-started.md) section you set up Craft namespaces it's tests under one separate root namespace and then expands per test subject. I.E. Unit tests are namespaced under `crafttests\unit` while functional tests are namespaced under `crafttests\functional`. It is advised to apply this same convention to your tests. If you are testing a module or plugin you may want to provide support resources for testing, it is advised to namespace these using `my\plugin\namespace\test`. This is exactly how Craft does it as well. See the [element fixtures](../testing-craft/fixtures.md) as an example. -## Quickly set up tests using the dedicated console command +## Quick Setup via Console Command If you have a general understanding of the typical Craft testing setup, you can use the `tests/setup` console command which will do all of the important setup work for you. It will copy from Craft's `src/test/internal/example-test-suite` folder to either your project's root directory or a directory path of your choosing. All you then have to do is: From cb84f505ac2a805657165c35be4f5ff698d06e4b Mon Sep 17 00:00:00 2001 From: Brad Bell Date: Fri, 12 Jun 2020 17:33:58 -0700 Subject: [PATCH 079/245] New translations updating.md (French) --- fr/updating.md | 6 +++++- 1 file changed, 5 insertions(+), 1 deletion(-) diff --git a/fr/updating.md b/fr/updating.md index eaf66c5538e..32e389c8dc1 100644 --- a/fr/updating.md +++ b/fr/updating.md @@ -2,12 +2,16 @@ ## Updating from the Control Panel -When an update is available, users with the permission to update Craft will see a badge in the CP next to the Utilities navigation item in the sidebar. Click on Utilities and then choose Updates. You can also use the Updates widget on the Control Panel dashboard, which is installed by default. +When an update is available, users with the permission to update Craft will see a badge in the CP next to the Utilities navigation item in the sidebar. Click on Utilities and then choose Updates. You can also use the Updates widget on the control panel dashboard, which is installed by default. This section displays both Craft CMS updates and plugin updates. Each update has its own Update button. Clicking that will initiate Craft’s self-updating process. You can run all of the updates (Craft, all plugin updates available) using the Update All button at the top left of the Updates page. +::: tip +Craft’s [changelog](https://github.com/craftcms/cms/blob/master/CHANGELOG-v3.md) will warn you of any critical changes at the top of the release notes. While there aren’t usually any warnings, it’s always a good idea to check before updating. +::: + ## Updating from the Terminal Craft 3.0.38 and 3.1.4 introduced a new `update` console command that can be used to update Craft and plugins. From 298eeca9334a6e7def7c078a2f7822cc024f45a9 Mon Sep 17 00:00:00 2001 From: Brad Bell Date: Fri, 12 Jun 2020 17:34:00 -0700 Subject: [PATCH 080/245] New translations updating.md (Japanese) --- ja/updating.md | 24 ++++++++++++++---------- 1 file changed, 14 insertions(+), 10 deletions(-) diff --git a/ja/updating.md b/ja/updating.md index c3296deb369..901ac066502 100644 --- a/ja/updating.md +++ b/ja/updating.md @@ -2,48 +2,52 @@ ## コントロールパネルからのアップデート -アップデートが可能になると、Craft のアップデート権限を持つユーザーは CP のサイドバーにあるナビゲーション項目「ユーティリティ」の横にバッジを確認できるようになります。「ユーティリティ」をクリックし、その後「アップデート」を選択します。デフォルトでインストールされているコントロールパネルのダッシュボードにあるアップデートウィジェットを利用することもできます。 +When an update is available, users with the permission to update Craft will see a badge in the CP next to the Utilities navigation item in the sidebar. Click on Utilities and then choose Updates. You can also use the Updates widget on the control panel dashboard, which is installed by default. このセクションには、Craft CMS のアップデートとプラグインのアップデートの両方を表示します。それぞれのアップデートは、それ自身の「アップデート」ボタンを持っています。クリックすると、 Craft の自動更新プロセスが開始されます。 アップデートページの左上にある「すべてを更新」ボタンを使用して、（アップデート可能な Craft とプラグイン）すべてのアップデートを実行できます。 +::: tip +Craft’s [changelog](https://github.com/craftcms/cms/blob/master/CHANGELOG-v3.md) will warn you of any critical changes at the top of the release notes. While there aren’t usually any warnings, it’s always a good idea to check before updating. +::: + ## ターミナルからのアップデート -Craft 3.0.38 および 3.1.4 では、Craft およびプラグインのアップデートで利用可能な新しい `update` コンソールコマンドが導入されました。 +Craft 3.0.38 and 3.1.4 introduced a new `update` console command that can be used to update Craft and plugins. -利用可能なアップデートを確認するには、ターミナルで Craft プロジェクトに移動し、次のコマンドを実行してください。 +To see available updates, go to your Craft project in your terminal and run this command: ```bash ./craft update ``` -![update コマンドによるインタラクションの例。](./images/cli-update-info.png) +![An example interaction with the update command.](./images/cli-update-info.png) -一度にすべてをアップデートするには、次のコマンドを実行します。 +To update everything all at once, run this command: ```bash ./craft update all ``` -特定のものをアップデートするには、`all` をそのハンドル（Craft をアップデートするための `craft`、または、プラグインのハンドルのいずれか）に置き換えます。 +To update a specific thing, replace `all` with its handle (either `craft` to update Craft, or a plugin’s handle). ```bash ./craft update element-api ``` -![update コマンドによるインタラクションの例。](./images/cli-update-plugin.png) +![An example interaction with the update command.](./images/cli-update-plugin.png) -一度に複数のハンドルを渡すこともできます。 +You can also pass multiple handles in at once: ```bash ./craft update element-api commerce ``` -デフォルトでは、Craft は利用可能な最新バージョンにアップデートします。特定バージョンにアップデートするには、ハンドルに `:` を追加します。 +By default, Craft will update you to the latest available version. To update to a specific version, append `:` to the handle: ```bash ./craft update element-api:2.5.4 ``` -Craft は `composer install` コマンドのように動作する `update/composer-install` コマンドも提供しますが、Composer をインストールする必要はありません。 +Craft also provides an `update/composer-install` command, which behaves like the `composer install` command, but doesn’t require you to have Composer installed. From fe9f6090e965494664aeec89d16a4ab4821dae96 Mon Sep 17 00:00:00 2001 From: Brad Bell Date: Fri, 12 Jun 2020 17:34:01 -0700 Subject: [PATCH 081/245] New translations upgrade.md (French) --- fr/upgrade.md | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/fr/upgrade.md b/fr/upgrade.md index 57f3b6fc0a5..d1e29dc7626 100644 --- a/fr/upgrade.md +++ b/fr/upgrade.md @@ -9,7 +9,7 @@ Before you begin, make sure that: - you've reviewed the [changes in Craft 3](changes-in-craft-3.md) - your server meets Craft 3’s [minimum requirements](requirements.md) (Craft 3 requires PHP 7+ and at least 256 MB of memory allocated to PHP) - your site is running at least **Craft 2.6.2788** -- your plugins are all up-to-date, and you’ve verified that they’ve been updated for Craft 3 (you can see a report of your plugins’ Craft 3 compatibility status from the Updates page in the Craft 2 Control Panel) +- your plugins are all up-to-date, and you’ve verified that they’ve been updated for Craft 3 (you can see a report of your plugins’ Craft 3 compatibility status from the Updates page in the Craft 2 control panel) - your **database is backed up** in case everything goes horribly wrong Once you've completed everything listed above you can continue with the upgrade process. @@ -43,15 +43,15 @@ With Craft 3 downloaded and prepped, follow these steps to complete the upgrade: 10. Update your web server to point to your new project’s `web/` directory. -11. Point your browser to your Control Panel URL (e.g. `http://my-project.test/admin`). If you see the update prompt, you did everything right! Go ahead and click “Finish up” to update your database. +11. Point your browser to your control panel URL (e.g. `http://my-project.test/admin`). If you see the update prompt, you did everything right! Go ahead and click “Finish up” to update your database. -12. If you had any plugins installed, you’ll need to install their Craft 3 counterparts from the “Plugin Store” section in the Control Panel. (See the plugins’ documentation for any additional upgrade instructions.) +12. If you had any plugins installed, you’ll need to install their Craft 3 counterparts from the “Plugin Store” section in the control panel. (See the plugins’ documentation for any additional upgrade instructions.) Now that you have successfully upgraded your Craft 2 project to Craft 3, please take some time to review the [changes in Craft 3](changes-in-craft-3.md). ## Troubleshooting -#### I get the Craft installer when I access my Control Panel. +#### I get the Craft installer when I access my control panel. If this happens, it’s because your database connection settings in the `.env` file don’t quite match up to what they used to be. Most likely you forgot to set the correct `DB_TABLE_PREFIX`. From 342a1bc5ee703e12b11500e03a41491112942804 Mon Sep 17 00:00:00 2001 From: Brad Bell Date: Fri, 12 Jun 2020 17:34:03 -0700 Subject: [PATCH 082/245] New translations upgrade.md (Japanese) --- ja/upgrade.md | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/ja/upgrade.md b/ja/upgrade.md index 766960d73a0..1eac2e82922 100644 --- a/ja/upgrade.md +++ b/ja/upgrade.md @@ -9,7 +9,7 @@ - あなたは[Craft 3 の変更点](changes-in-craft-3.md)を確認しました。 - あなたのサーバーは Craft 3 の[最小要件](requirements.md)（Craft 3 には PHP 7 以降が必要で、PHP 割当メモリが少なくとも 256 MB 必要です）を満たしています。 - あなたのサイトは、少なくとも **Craft 2.6.2788** が実行されています。 -- プラグインはすべて最新の状態で、それらが Craft 3 向けにアップデートされていることを確かめました。（Craft 2 コントロールパネルのアップデートページから、プラグインの Craft 3 互換ステータスのレポートを見ることができます。） +- your plugins are all up-to-date, and you’ve verified that they’ve been updated for Craft 3 (you can see a report of your plugins’ Craft 3 compatibility status from the Updates page in the Craft 2 control panel) - なんらかの問題が起こった場合に備えて、**データベースをバックアップ**してあります。 上記リストをすべて満たしているなら、アップグレードプロセスを続行できます。 @@ -43,15 +43,15 @@ Craft 3 をダウンロードして準備したら、次のステップに従っ 10. 新しいプロジェクトの `web/` ディレクトリを参照するよう、ウェブサーバーの設定をアップデートします。 -11. ブラウザでコントロールパネルの URL（例： `http://my-project.test/admin`）にアクセスします。アップデートのプロンプトが表示されたら、すべてが正しく実行されています！「Finish up（完了）」ボタンをクリックしてデータベースを更新してください。 +11. Point your browser to your control panel URL (e.g. `http://my-project.test/admin`). If you see the update prompt, you did everything right! Go ahead and click “Finish up” to update your database. -12. プラグインをインストールしている場合、コントロールパネルの「プラグインストア」セクションから Craft 3 対応版をインストールする必要があります。（追加のアップグレードガイドについては、プラグインのドキュメントを参照してください。） +12. If you had any plugins installed, you’ll need to install their Craft 3 counterparts from the “Plugin Store” section in the control panel. (See the plugins’ documentation for any additional upgrade instructions.) これで Craft 2 プロジェクトから Craft 3 へのアップグレードが完了しました。[Craft 3 の変更点](changes-in-craft-3.md)を確認する時間を設けてください。 ## トラブルシューティング -#### コントロールパネルにアクセスすると Craft のインストーラーが表示されます。 +#### I get the Craft installer when I access my control panel. これが起こるのは、`.env` ファイルのデータベース接続情報が実際に必要な情報と完全に一致しないためです。多くの場合、正しい `DB_TABLE_PREFIX` を設定するのを忘れています。 From 4554b065397da254bdbf6b42f6a9054cea7f5574 Mon Sep 17 00:00:00 2001 From: Brad Bell Date: Fri, 12 Jun 2020 17:34:06 -0700 Subject: [PATCH 083/245] New translations users-fields.md (French) --- fr/users-fields.md | 13 +++++++++---- 1 file changed, 9 insertions(+), 4 deletions(-) diff --git a/fr/users-fields.md b/fr/users-fields.md index 14bb7157d9b..db3ebcaaa6f 100644 --- a/fr/users-fields.md +++ b/fr/users-fields.md @@ -34,10 +34,15 @@ When [querying for elements](dev/element-queries/README.md) that have a Users fi Possible values include: -| Value | Fetches elements… -| - | - -| `':empty:'` | that don’t have any related users. -| `':notempty:'` | that have at least one related user. +| Value | Fetches elements… | +| --------------------------------------------------------- | ------------------------------------------------------ | +| `':empty:'` | that don’t have any related users. | +| `':notempty:'` | that have at least one related user. | +| `100` | that are related to the user with an ID of 100. | +| `[100, 200]` | that are related to a user with an ID of 100 or 200. | +| `['and', 100, 200]` | that are related to the users with IDs of 100 and 200. | +| an [User](api:craft\elements\User) object | that are related to the user. | +| an [UserQuery](api:craft\elements\db\UserQuery) object | that are related to any of the resulting users. | ```twig {# Fetch entries with a related user #} From d59fb2dfc690d34fbe2bcfd575ac04f8140f8f66 Mon Sep 17 00:00:00 2001 From: Brad Bell Date: Fri, 12 Jun 2020 17:34:07 -0700 Subject: [PATCH 084/245] New translations users-fields.md (Japanese) --- ja/users-fields.md | 17 +++++++++++++---- 1 file changed, 13 insertions(+), 4 deletions(-) diff --git a/ja/users-fields.md b/ja/users-fields.md index 61989586a83..9290b37ff0f 100644 --- a/ja/users-fields.md +++ b/ja/users-fields.md @@ -34,10 +34,15 @@ 利用可能な値には、次のものが含まれます。 -| 値 | 取得するエレメント | -| -------------- | ----------------------- | -| `':empty:'` | 関連付けられたユーザーを持たない。 | -| `':notempty:'` | 少なくとも1つの関連付けられたユーザーを持つ。 | +| 値 | 取得するエレメント | +| --------------------------------------------------------- | ------------------------------------------------------ | +| `':empty:'` | 関連付けられたユーザーを持たない。 | +| `':notempty:'` | 少なくとも1つの関連付けられたユーザーを持つ。 | +| `100` | that are related to the user with an ID of 100. | +| `[100, 200]` | that are related to a user with an ID of 100 or 200. | +| `['and', 100, 200]` | that are related to the users with IDs of 100 and 200. | +| an [User](api:craft\elements\User) object | that are related to the user. | +| an [UserQuery](api:craft\elements\db\UserQuery) object | that are related to any of the resulting users. | ```twig {# Fetch entries with a related user #} @@ -94,6 +99,10 @@ .all() %} ``` +::: tip +It’s always a good idea to clone the user query using the [clone()](./dev/functions.md#clone) function before adjusting its parameters, so the parameters don’t have unexpected consequences later on in your template. +::: + ## 関連項目 * [ユーザークエリ](dev/element-queries/user-queries.md) From a2ea4db0bed4577a6cba2434238fa794dc4c1257 Mon Sep 17 00:00:00 2001 From: Brad Bell Date: Fri, 12 Jun 2020 17:34:09 -0700 Subject: [PATCH 085/245] New translations users.md (French) --- fr/users.md | 68 +++++++++++++++++++++++++++++------------------------ 1 file changed, 37 insertions(+), 31 deletions(-) diff --git a/fr/users.md b/fr/users.md index c3c98479e49..13e67464151 100644 --- a/fr/users.md +++ b/fr/users.md @@ -28,40 +28,46 @@ After you create your groups, you can assign users to groups by going into their ## Permissions -Craft Pro allows you to set permissions on users and groups, such as the ability to access the Control Panel, edit content within certain sections, etc. You can apply these permissions directly to user accounts as well as to user groups. When you apply permissions to a user group, all users that belong to that group will inherit them. +Craft Pro allows you to set permissions on users and groups, such as the ability to access the control panel, edit content within certain sections, etc. You can apply these permissions directly to user accounts as well as to user groups. When you apply permissions to a user group, all users that belong to that group will inherit them. The permissions Craft comes with are: -| Permission | Handle -| ---------- | ------ -| Access the site when the system is off | `accessSiteWhenSystemIsOff` -| Access the CP | `accessCp` -| ↳  Access the CP when the system is off | `accessCpWhenSystemIsOff` -| ↳  Perform Craft and plugin updates | `performUpdates` -| ↳  Access *[Plugin Name]* | `accessPlugin-[PluginHandle]` -| Edit users | `editUsers` -| ↳  Register users | `registerUsers` -| ↳  Assign permissions | `assignUserPermissions` -| ↳  Administrate users | `administrateUsers` -| Delete users | `deleteUsers` -| Edit *[Site Name]* | `editSite:[SiteUID]` -| Impersonate users | `impersonateUsers` -| Edit entries | `editEntries:[SectionUID]` -| ↳  Create entries | `createEntries:[SectionUID]` -| ↳  Publish entries | `publishEntries:[SectionUID]` -| ↳  Delete entries | `deleteEntries:[SectionUID]` -| ↳  Edit other authors’ entries | `editPeerEntries:[SectionUID]` -|     ↳  Publish other authors’ entries | `publishPeerEntries:[SectionUID]` -|     ↳  Delete other authors’ entries | `deletePeerEntries:[SectionUID]` -| ↳  Edit other authors’ drafts | `editPeerEntryDrafts:[SectionUID]` -|     ↳  Publish other authors’ drafts | `publishPeerEntryDrafts:[SectionUID]` -|     ↳  Delete other authors’ drafts | `deletePeerEntryDrafts:[SectionUID]` -| Edit *[Global Set Name]* | `editGlobalSet:[GlobalSetUID]` -| Edit *[Category Group Name]* | `editCategories:[CategoryGroupUID]` -| View *[Asset Volume Name]* | `viewVolume:[VolumeUID]` -| ↳  Upload files | `saveAssetInVolume:[VolumeUID]` -| ↳  Create subfolders | `createFoldersInVolume:[VolumeUID]` -| ↳  Remove files | `deleteFilesAndFoldersInVolume:[VolumeUID]` +| Permission | Handle | +| ---------------------------------------------------------------- | ------------------------------------------- | +| Access the site when the system is off | `accessSiteWhenSystemIsOff` | +| Access the CP | `accessCp` | +| ↳  Access the CP when the system is off | `accessCpWhenSystemIsOff` | +| ↳  Perform Craft and plugin updates | `performUpdates` | +| ↳  Access *[Plugin Name]* | `accessPlugin-[PluginHandle]` | +| Edit users | `editUsers` | +| ↳  Register users | `registerUsers` | +| ↳  Assign permissions | `assignUserPermissions` | +| ↳  Administrate users | `administrateUsers` | +| Delete users | `deleteUsers` | +| Edit *[Site Name]* | `editSite:[SiteUID]` | +| Impersonate users | `impersonateUsers` | +| Edit entries | `editEntries:[SectionUID]` | +| ↳  Create entries | `createEntries:[SectionUID]` | +| ↳  Publish entries | `publishEntries:[SectionUID]` | +| ↳  Delete entries | `deleteEntries:[SectionUID]` | +| ↳  Edit other authors’ entries | `editPeerEntries:[SectionUID]` | +|     ↳  Publish other authors’ entries | `publishPeerEntries:[SectionUID]` | +|     ↳  Delete other authors’ entries | `deletePeerEntries:[SectionUID]` | +| ↳  Edit other authors’ drafts | `editPeerEntryDrafts:[SectionUID]` | +|     ↳  Publish other authors’ drafts | `publishPeerEntryDrafts:[SectionUID]` | +|     ↳  Delete other authors’ drafts | `deletePeerEntryDrafts:[SectionUID]` | +| Edit *[Global Set Name]* | `editGlobalSet:[GlobalSetUID]` | +| Edit *[Category Group Name]* | `editCategories:[CategoryGroupUID]` | +| View *[Asset Volume Name]* | `viewVolume:[VolumeUID]` | +| ↳  Upload files | `saveAssetInVolume:[VolumeUID]` | +| ↳  Create subfolders | `createFoldersInVolume:[VolumeUID]` | +| ↳  Remove files and folders | `deleteFilesAndFoldersInVolume:[VolumeUID]` | +| ↳  Edit images | `editImagesInVolume:[VolumeUID]` | +| ↳  View files uploaded by other users | `viewPeerFilesInVolume:[VolumeUID]` | +|     ↳  Edit files uploaded by other users | `editPeerFilesInVolume:[SectionUID]` | +|     ↳  Replace files uploaded by other users | `replacePeerFilesInVolume:[SectionUID]` | +|     ↳  Remove files uploaded by other users | `deletePeerFilesInVolume:[SectionUID]` | +|     ↳  Edit images uploaded by other users | `editPeerImagesInVolume:[SectionUID]` | ## Public Registration From e138c604203a72236cc4af9540d7b8ededa76d97 Mon Sep 17 00:00:00 2001 From: Brad Bell Date: Fri, 12 Jun 2020 17:34:11 -0700 Subject: [PATCH 086/245] New translations searching.md (French) --- fr/searching.md | 8 ++++++-- 1 file changed, 6 insertions(+), 2 deletions(-) diff --git a/fr/searching.md b/fr/searching.md index fdf09455b43..838dbcb1e70 100644 --- a/fr/searching.md +++ b/fr/searching.md @@ -64,6 +64,10 @@ Assets, categories, entries, users, and tags each support their own set of addit * title +::: warning +Searching is a great way to quickly query content broadly across elements, but if you’re querying field attributes the most precise way is through that field type’s [query parameter](dev/element-queries/#executing-element-queries). +::: + ## Templating `craft.assets()`, `craft.entries()`, `craft.tags()`, and `craft.users()` support a `search` parameter that you can use to filter their elements by a given search query. @@ -100,7 +104,7 @@ See our [Search Form](dev/examples/search-form.md) tutorial for a complete examp Craft does its best to keep its search indexes as up-to-date as possible, but there are a couple things that might render portions of them inaccurate. If you suspect that your search indexes don’t have the latest and greatest data, you can have Craft rebuild them by bulk-resaving your entries with the `resave/entries` command: ```bash -./craft resave/entries +./craft resave/entries --update-search-index ``` -You can specify which entries should be resaved with the `--section` and `--type` options, among others. Run `resave/entries --help` to see a full list of supported options. +You can specify which entries should be resaved with the `--section` and `--type` options, among others. Run `resave/entries --help` to see a full list of supported options. From 08fcacdd7434cc25202c61ad0986c08b40308a1a Mon Sep 17 00:00:00 2001 From: Brad Bell Date: Fri, 12 Jun 2020 17:34:15 -0700 Subject: [PATCH 087/245] New translations matrix-fields.md (French) --- fr/matrix-fields.md | 97 +++++++++++++++++++++++++++++++++++++++++++-- 1 file changed, 93 insertions(+), 4 deletions(-) diff --git a/fr/matrix-fields.md b/fr/matrix-fields.md index 9eb3e1ba31e..170b8f96a12 100644 --- a/fr/matrix-fields.md +++ b/fr/matrix-fields.md @@ -6,8 +6,8 @@ Matrix fields allow you to create multiple blocks of content within a single fie Matrix fields have the following settings: -* **Configuration** – This is where you configure which block types should be available to your Matrix field, and which sub-fields each of those block types should have. -* **Max Blocks** – The maximum number of blocks that can be created within the field. (Default is no limit.) +- **Configuration** – This is where you configure which block types should be available to your Matrix field, and which sub-fields each of those block types should have. +- **Max Blocks** – The maximum number of blocks that can be created within the field. (Default is no limit.) ## The Field @@ -132,7 +132,96 @@ You can set [parameters](dev/element-queries/matrix-block-queries.md#parameters) It’s always a good idea to clone the Matrix query using the [clone()](./dev/functions.md#clone) function before adjusting its parameters, so the parameters don’t have unexpected consequences later on in your template. ::: +### Saving Matrix Fields in Entry Forms + +If you have an [entry form](dev/examples/entry-form.md) that needs to contain a Matrix field, you will need to submit your field value in this format: + +``` +- sortOrder +- blocks + - + - type + - fields + - + - + - + - type + - fields + - ... +``` + +`sortOrder` should be submitted as an array of all the block IDs you wish to persist (as well as any new block IDs), in the order they should be saved. + +If you want all existing blocks to persist in the same order they are currently in, then use this template to define your `sortOrder` array: + +```twig +{% if entry is defined %} + {% for blockId in clone(entry.).anyStatus().ids() %} + {{ hiddenInput('fields[][sortOrder][]', blockId) }} + {% endfor %} +{% endif %} +``` + +All of your block data should be nested under `blocks`, indexed by their IDs. Each block must submit its `type` and custom field data nested under a `fields` array. + +Here’s how you can output form fields for existing blocks, for a Matrix field with two block types (`text` and `image`): + +```twig +{% if entry is defined %} + {% for block in entry..all() %} + {# Prefix the block's input names with `fields[][blocks][]` #} + {% namespace "fields[][blocks][#{block.id}]" %} + {{ hiddenInput('type', block.type) }} + {% switch block.type %} + {% case 'text' %} + + {% case 'image' %} + {% set images = block..all() %} + {% if images|length %} +
      + {% for image in block..all() %} +
    • + {{ image.getImg({ width: 100, height: 100 }) }} + {{ hiddenInput('fields[][]', image.id) }} +
      • + {% endfor %} +
    + {% endif %} + {% endswitch %} + {% endnamespace %} + {% endfor %} +{% endif %} +``` + +::: tip +Outputting form fields for existing blocks is completely optional. As long as the block IDs are listed in the `sortOrder` array, they will persist even if they are missing from the form data. +::: + +To show a “New Block” form, first come up with a temporary ID for the block, prefixed with `new:`. For example, `new:1`, `new:2`, etc. + +Append the temporary ID to the `sortOrder` array, and use it when outputting the block’s form inputs. + +If you will likely need to include a JavaScript-powered component to the field, which appends new block inputs to the form. New blocks should have an “ID” of `new:X`, where `X` is any number that is unique among all new blocks for the field. + +For example, the first new block that is added to the form could have an “ID” of `new:1`, so its `type` input name would end up looking like this: + +```html + +``` + +Then define the form inputs for any additional blocks that should be appended to the input. + +```twig +{{ hiddenInput('fields[][sortOrder][]', 'new:1') }} + +{# Prefix the block's input names with `fields[][blocks][new:1]` #} +{% namespace "fields[][blocks][new:1]" %} + {{ hiddenInput('type', 'text') }} + +{% endnamespace %} +``` + ## See Also -* [Element Queries](dev/element-queries/README.md) -* +- [Element Queries](dev/element-queries/README.md) +- From 227d218c8d5c725c4363dff60d62683269e7165f Mon Sep 17 00:00:00 2001 From: Brad Bell Date: Fri, 12 Jun 2020 17:34:17 -0700 Subject: [PATCH 088/245] New translations matrix-fields.md (Japanese) --- ja/matrix-fields.md | 169 +++++++++++++++++++++++++++++++++----------- 1 file changed, 128 insertions(+), 41 deletions(-) diff --git a/ja/matrix-fields.md b/ja/matrix-fields.md index 930f1222829..ac886a2fcf6 100644 --- a/ja/matrix-fields.md +++ b/ja/matrix-fields.md @@ -6,8 +6,8 @@ 行列フィールドの設定は、次の通りです。 -* **構成** – ここでは、行列フィールドでどのようなブロックタイプが利用可能か、それらのブロックタイプがどのようなサブフィールドを持つ必要があるかを設定します。 -* **最大ブロック数** – フィールドに作成できるブロック数の上限（デフォルトは無制限です） +- **構成** – ここでは、行列フィールドでどのようなブロックタイプが利用可能か、それらのブロックタイプがどのようなサブフィールドを持つ必要があるかを設定します。 +- **最大ブロック数** – フィールドに作成できるブロック数の上限（デフォルトは無制限です） ## フィールド @@ -47,94 +47,181 @@ ### 行列フィールドデータの操作 -テンプレート内で行列フィールドを出力するには、行列フィールドに対して [for ループ](https://twig.symfony.com/doc/tags/for.html) を使用します。 +If you have an element with a Matrix field in your template, you can access its blocks using your Matrix field’s handle: ```twig -{% for block in entry..all() %} - ... -{% endfor %} +{% set query = entry. %} ``` -for ループ内に記述されたすべてのコードは、 フィールドに含まれるそれぞれの行列ブロックに対して繰り返されます。定義済みの変数 `block` にセットされる現在のブロックは、 モデルになります。 +That will give you a [Matrix block query](dev/element-queries/matrix-block-queries.md), prepped to output all of the enabled blocks for the given field. -次に、4つのブロックタイプ（見出し、テキスト、画像、および、引用）を持つ行列フィールドのテンプレートの実例を示します。`block.type` （）をチェックすることによって、現在のブロックタイプのハンドルを確認できます。 +To loop through all of the blocks, call [all()](api:craft\db\Query::all()) and then loop over the results: ```twig -{% for block in entry..all() %} +{% set blocks = entry..all() %} +{% if blocks|length %} +
      + {% for block in blocks %} + + {% endfor %} +
    +{% endif %} +``` - {% if block.type == "heading" %} +All of the code you put within the for-loop will be repeated for each Matrix block in the field. The current block will get set to that `block` variable we’ve defined, and it will be a model. -

    {{ block.heading }}

    +Here’s an example of what the template might look like for a Matrix field with four block types (Heading, Text, Image, and Quote). We can determine the current block type’s handle by checking `block.type` (). +```twig +{% for block in entry..all() %} + {% if block.type == "heading" %} +

    {{ block.heading }}

    {% elseif block.type == "text" %} - {{ block.text|markdown }} - {% elseif block.type == "image" %} - {% set image = block.image.one() %} {% if image %} {{ image.title }} {% endif %} - {% elseif block.type == "quote" %} -

    {{ block.quote }}

    – {{ block.cite }}
    - {% endif %} - {% endfor %} ``` ::: tip -このコードは [switch](dev/tags/switch.md) タグを利用して、簡略化できます。 +This code can be simplified using the [switch](dev/tags/switch.md) tag. ::: -### ブロックタイプのフィルタリング - -特定のタイプのブロックだけを出力したい場合、行列フィールドに「type」フィルタを追加します。 +If you only want the first block, call [one()](api:craft\db\Query::one()) instead of `all()`, and then make sure it returned something: ```twig -{% for block in clone(entry.).type('text').all() %} - {{ block.text|markdown }} -{% endfor %} +{% set block = entry..one() %} +{% if block %} + +{% endif %} ``` -あなたが望むなら、複数のブロックタイプを渡すことができます。 +If you only want to know the total number of blocks, call [count()](api:craft\db\Query::count()). ```twig -{% for block in clone(entry.).type('text, heading').all() %} - {% if block.type == "heading" %} -

    {{ block.heading }}

    - {% else %} - {{ block.text|markdown }} - {% endif %} -{% endfor %} +{% set total = entry..count() %} +

    Total blocks: {{ total }}

    ``` +If you just need to check if are blocks exist (but don’t need to fetch them), you can call [exists()](api:craft\db\Query::exists()): -### リミットの調整 +```twig +{% if entry..exists() %} +

    There are blocks!

    +{% endif %} +``` -デフォルトでは、行列フィールドは最初の100ブロックを返します。変更するには `limit` パラメータで上書きします。 +You can set [parameters](dev/element-queries/matrix-block-queries.md#parameters) on the Matrix block query as well. For example, to only fetch blocks of type `text`, set the [type](dev/element-queries/matrix-block-queries.md#type) param: ```twig -{% for block in clone(entry.).limit(5) %} +{% set blocks = clone(entry.) + .type('text') + .all() %} ``` +::: tip +It’s always a good idea to clone the Matrix query using the [clone()](./dev/functions.md#clone) function before adjusting its parameters, so the parameters don’t have unexpected consequences later on in your template. +::: + +### Saving Matrix Fields in Entry Forms + +If you have an [entry form](dev/examples/entry-form.md) that needs to contain a Matrix field, you will need to submit your field value in this format: + +``` +- sortOrder +- blocks + - + - type + - fields + - + - + - + - type + - fields + - ... +``` + +`sortOrder` should be submitted as an array of all the block IDs you wish to persist (as well as any new block IDs), in the order they should be saved. + +If you want all existing blocks to persist in the same order they are currently in, then use this template to define your `sortOrder` array: + +```twig +{% if entry is defined %} + {% for blockId in clone(entry.).anyStatus().ids() %} + {{ hiddenInput('fields[][sortOrder][]', blockId) }} + {% endfor %} +{% endif %} +``` -### ブロックの総数の取得 +All of your block data should be nested under `blocks`, indexed by their IDs. Each block must submit its `type` and custom field data nested under a `fields` array. -[length フィルタ](https://twig.symfony.com/doc/filters/length.html)を利用して、ブロックの総数を取得できます。 +Here’s how you can output form fields for existing blocks, for a Matrix field with two block types (`text` and `image`): ```twig -{{ entry.|length }} +{% if entry is defined %} + {% for block in entry..all() %} + {# Prefix the block's input names with `fields[][blocks][]` #} + {% namespace "fields[][blocks][#{block.id}]" %} + {{ hiddenInput('type', block.type) }} + {% switch block.type %} + {% case 'text' %} + + {% case 'image' %} + {% set images = block..all() %} + {% if images|length %} +
      + {% for image in block..all() %} +
    • + {{ image.getImg({ width: 100, height: 100 }) }} + {{ hiddenInput('fields[][]', image.id) }} +
      • + {% endfor %} +
    + {% endif %} + {% endswitch %} + {% endnamespace %} + {% endfor %} +{% endif %} ``` +::: tip +Outputting form fields for existing blocks is completely optional. As long as the block IDs are listed in the `sortOrder` array, they will persist even if they are missing from the form data. +::: + +To show a “New Block” form, first come up with a temporary ID for the block, prefixed with `new:`. For example, `new:1`, `new:2`, etc. + +Append the temporary ID to the `sortOrder` array, and use it when outputting the block’s form inputs. + +If you will likely need to include a JavaScript-powered component to the field, which appends new block inputs to the form. New blocks should have an “ID” of `new:X`, where `X` is any number that is unique among all new blocks for the field. + +For example, the first new block that is added to the form could have an “ID” of `new:1`, so its `type` input name would end up looking like this: + +```html + +``` + +Then define the form inputs for any additional blocks that should be appended to the input. + +```twig +{{ hiddenInput('fields[][sortOrder][]', 'new:1') }} + +{# Prefix the block's input names with `fields[][blocks][new:1]` #} +{% namespace "fields[][blocks][new:1]" %} + {{ hiddenInput('type', 'text') }} + +{% endnamespace %} +``` ## 関連項目 -* [エレメントクエリ](dev/element-queries/README.md) -* +- [エレメントクエリ](dev/element-queries/README.md) +- From fa1d57f67a7d2cba75174ceba296ca64463772a3 Mon Sep 17 00:00:00 2001 From: Brad Bell Date: Fri, 12 Jun 2020 17:34:18 -0700 Subject: [PATCH 089/245] New translations multi-select-fields.md (French) --- fr/multi-select-fields.md | 12 ++++++------ 1 file changed, 6 insertions(+), 6 deletions(-) diff --git a/fr/multi-select-fields.md b/fr/multi-select-fields.md index 01d483906ab..6cdc080b0b5 100644 --- a/fr/multi-select-fields.md +++ b/fr/multi-select-fields.md @@ -16,12 +16,12 @@ When [querying for elements](dev/element-queries/README.md) that have a Multi-se Possible values include: -| Value | Fetches elements… -| - | - -| `'foo'` | with a `foo` option selected. -| `'not foo'` | without a `foo` option selected. -| `['foo', 'bar']` | with `foo` or `bar` options selected. -| `['and', 'foo', 'bar']` | with `foo` and `bar` options selected. +| Value | Fetches elements… | +| ----------------------- | -------------------------------------- | +| `'foo'` | with a `foo` option selected. | +| `'not foo'` | without a `foo` option selected. | +| `['foo', 'bar']` | with `foo` or `bar` options selected. | +| `['and', 'foo', 'bar']` | with `foo` and `bar` options selected. | ```twig {# Fetch entries with the 'foo' option selected #} From 6964c3245d0b6485b06409969cae87b4c3d7426e Mon Sep 17 00:00:00 2001 From: Brad Bell Date: Fri, 12 Jun 2020 17:34:20 -0700 Subject: [PATCH 090/245] New translations multi-select-fields.md (Japanese) --- ja/multi-select-fields.md | 12 ++++++------ 1 file changed, 6 insertions(+), 6 deletions(-) diff --git a/ja/multi-select-fields.md b/ja/multi-select-fields.md index 1ae00339845..ccc2cee0230 100644 --- a/ja/multi-select-fields.md +++ b/ja/multi-select-fields.md @@ -16,12 +16,12 @@ 利用可能な値には、次のものが含まれます。 -| 値 | 取得するエレメント -| - | - -| `'foo'` | `foo` オプションが選択されている。 -| `'not foo'` | `foo` オプションが選択されていない。 -| `['foo', 'bar']` | with `foo` or `bar` options selected. -| `['and', 'foo', 'bar']` | with `foo` and `bar` options selected. +| 値 | 取得するエレメント | +| ----------------------- | -------------------------------------- | +| `'foo'` | `foo` オプションが選択されている。 | +| `'not foo'` | `foo` オプションが選択されていない。 | +| `['foo', 'bar']` | with `foo` or `bar` options selected. | +| `['and', 'foo', 'bar']` | with `foo` and `bar` options selected. | ```twig {# Fetch entries with the 'foo' option selected #} From 0e62e8b9305da9f269269a65393934559fc93990 Mon Sep 17 00:00:00 2001 From: Brad Bell Date: Fri, 12 Jun 2020 17:34:26 -0700 Subject: [PATCH 091/245] New translations plugins.md (French) --- fr/plugins.md | 14 ++++++++++---- 1 file changed, 10 insertions(+), 4 deletions(-) diff --git a/fr/plugins.md b/fr/plugins.md index ab065bca96f..a847f1c07bd 100644 --- a/fr/plugins.md +++ b/fr/plugins.md @@ -4,13 +4,13 @@ If you’re looking for plugin *development* documentation, check out the [Extending Craft](extend/README.md) section. ::: -Plugins extend Craft’s core functionality. They can introduce new Dashboard widgets, field types, Control Panel sections, Twig templating features, workflow actions, and more. +Plugins extend Craft’s core functionality. They can introduce new Dashboard widgets, field types, control panel sections, Twig templating features, workflow actions, and more. ## The Plugin Store -Craft’s Control Panel features a Plugin Store, where you can browse through hundreds of free and commercial plugins, install them with a single click, and pay for them. +Craft’s control panel features a Plugin Store, where you can browse through hundreds of free and commercial plugins, install them with a single click, and pay for them. -To access the Plugin Store, click on the “Plugin Store” item in Craft’s Control Panel navigation. From there you can browse through the various plugin categories and curated lists to discover new plugins. +To access the Plugin Store, click on the “Plugin Store” item in Craft’s control panel navigation. From there you can browse through the various plugin categories and curated lists to discover new plugins. ![The Craft Plugin Store](./images/plugin-store.png) @@ -34,7 +34,7 @@ Once you’ve completed the checkout process, your plugin installation will auto ## Managing Plugin Licenses -You can managed all of your plugin licenses from your [Craft ID](https://id.craftcms.com/) account, under Licenses → Plugins +You can manage all of your plugin licenses from your [Craft ID](https://id.craftcms.com/) account, under Licenses → Plugins If you don’t have a Craft ID account yet, you can create one by going to [id.craftcms.com/register](https://id.craftcms.com/register). @@ -42,6 +42,12 @@ Any plugin licenses that were purchased with the same email address as your Craf If you have a plugin license that isn’t showing up, go to Licenses → Claim License. You can enter its license key manually, or if you know the email address that was used for purchase, you can enter it in the “Claim licenses by email address” section. After verifying that you own the email address, any unclaimed licenses associated with that email address will be added to your account. +### Safeguarding Plugin License Keys + +By default your plugin license key will be stored in the database and `project.yaml`. You may, however, move that license key to a custom PHP constant and set the key using the `$VARIABLE_NAME` syntax. + +If you were to create a `MY_PLUGIN_KEY` environment variable, for example, you could then use `$MY_PLUGIN_KEY` in place of the key itself anywhere the plugin license key is required. + ## Transferring Plugin Licenses To transfer a plugin license to someone else’s Craft ID account, log into your Craft ID account, and click on the license under Licenses → Plugins, and then click the “Release License” button to release it from your account. Then the other person will be able to claim the license for themselves from the Licenses → Claim License page of their Craft ID account. From 111633f87b30c93c90b4820382da2311b846bd35 Mon Sep 17 00:00:00 2001 From: Brad Bell Date: Fri, 12 Jun 2020 17:34:27 -0700 Subject: [PATCH 092/245] New translations requirements.md (Japanese) --- ja/requirements.md | 29 +++++++++++++++++------------ 1 file changed, 17 insertions(+), 12 deletions(-) diff --git a/ja/requirements.md b/ja/requirements.md index 99bb3b48f80..8b427f0feed 100644 --- a/ja/requirements.md +++ b/ja/requirements.md @@ -28,20 +28,25 @@ Craft は次の PHP エクステンションが必要です。 * [Reflection](http://php.net/manual/en/class.reflectionextension.php) * [SPL](http://php.net/manual/en/book.spl.php) * [Zip](http://php.net/manual/en/book.zip.php) +* [DOM](http://php.net/manual/en/book.dom.php) ## オプションの PHP エクステンション * [Intl](http://php.net/manual/en/book.intl.php) – よりリッチな国際化のサポートを追加します。 -* [DOM](http://php.net/manual/en/book.dom.php) - と同様に XML フィードの解析に必要です。 ## オプションの PHP メソッドと設定 一部の共用ホスティング環境では、Craft の機能に影響を与える PHP メソッドや設定が無効になっています。 -* [allow_url_fopen](http://php.net/manual/en/filesystem.configuration.php#ini.allow-url-fopen) - アップデートやプラグインストアからのプラグインインストールを可能にするため、Craft では PHP 設定を有効にする必要があります。 -* [proc_*](http://php.net/manual/en/ref.exec.php) - プラグインストアを利用したり、メールの送信ができるよう PHP の `proc_` メソッドを有効にする必要があります。 +- [allow_url_fopen](http://php.net/manual/en/filesystem.configuration.php#ini.allow-url-fopen) must be enabled for updating and installing plugins from the Plugin Store. +- [proc_*](http://php.net/manual/en/ref.exec.php) methods must be enabled in order to utilize the Plugin Store and send emails. +- [ignore_user_abort](https://www.php.net/manual/en/function.ignore-user-abort.php) must be enabled for the [default, web-based queue runner](config:runQueueAutomatically) to operate. -## 必要なデータベースユーザー特権 +## Optional Extras + +* [Composer 1.30+](https://docs.craftcms.com/v3/installation.html#downloading-with-composer) - When installing Craft with Composer + +## Required Database User Privileges Craft のデータベースに接続するユーザーには、次の特権がなければなりません。 @@ -68,22 +73,22 @@ Craft のデータベースに接続するユーザーには、次の特権が * `REFERENCES` * `CONNECT` -## コントロールパネルのブラウザ要件 +## Control Panel Browser Requirements -Craft のコントロールパネルは、モダンブラウザが必要です。 +Craft’s control panel requires a modern browser: #### Windows と macOS -* Chrome 29 以降 -* Firefox 28 以降 -* Safari 9.0 以降 +* Chrome 29 or later +* Firefox 28 or later +* Safari 9.0 or later * Microsoft Edge #### モバイル -* iOS: Safari 9.1 以降 -* Android: Chrome 4.4 以降 +* iOS: Safari 9.1 or later +* Android: Chrome 4.4 or later ::: tip -Craft の CP のブラウザ要件は、実際のウェブサイトとは関係がありません。もしあなたがつらい仕事を苦にせず、IE 6 で完璧に表示されるサイトを望むのであれば、あたなの望む通りにできます。 +Craft’s control panel browser requirements have nothing to do with your actual website. If you’re a glutton for punishment and want your website to look flawless on IE 6, that’s your choice. ::: From f8925fba92298b4f2336588359f38b8e2f54d8b6 Mon Sep 17 00:00:00 2001 From: Brad Bell Date: Fri, 12 Jun 2020 17:34:29 -0700 Subject: [PATCH 093/245] New translations plugins.md (Japanese) --- ja/plugins.md | 26 ++++++++++++++++---------- 1 file changed, 16 insertions(+), 10 deletions(-) diff --git a/ja/plugins.md b/ja/plugins.md index acdbcecf1c2..7e97c30ec02 100644 --- a/ja/plugins.md +++ b/ja/plugins.md @@ -4,13 +4,13 @@ プラグイン _開発_ のためのドキュメントをお探しの場合は、[Craft の拡張](extend/README.md) セクションをチェックしてください。 ::: -プラグインは Craft のコア機能を拡張します。新しいダッシュボードウィジェット、フィールドタイプ、コントロールパネルセクション、Twig テンプレート機能、ワークフローアクションなどを導入することができます。 +Plugins extend Craft’s core functionality. They can introduce new Dashboard widgets, field types, control panel sections, Twig templating features, workflow actions, and more. ## プラグインストア -Craft のコントロールパネルはプラグインストアを特徴とし、数百の無料プラグインと商用プラグインをブラウズしたり、ワンクリックでインストールしたり、料金を支払うことができます。 +Craft’s control panel features a Plugin Store, where you can browse through hundreds of free and commercial plugins, install them with a single click, and pay for them. -プラグインストアにアクセスするためには、Craft のコントロールパネルのナビゲーションにある「プラグインストア」をクリックします。そこから、様々なプラグインカテゴリや選別されたリストをブラウズして、新しいプラグインを発見することができます。 +To access the Plugin Store, click on the “Plugin Store” item in Craft’s control panel navigation. From there you can browse through the various plugin categories and curated lists to discover new plugins. ![The Craft Plugin Store](./images/plugin-store.png) @@ -34,7 +34,7 @@ Craft が開発ドメイン上で実行されている場合、「試用」ボ ## プラグインライセンスの管理 -[Craft ID](https://id.craftcms.com/) アカウントの「Licenses → Plugins」から、すべてのプラグインライセンスを管理することができます。 +You can manage all of your plugin licenses from your [Craft ID](https://id.craftcms.com/) account, under Licenses → Plugins まだ Craft ID アカウントをお持ちでない場合は、[id.craftcms.com/register](https://id.craftcms.com/register) にアクセスしてアカウントを作成することができます。 @@ -42,25 +42,31 @@ Craft ID アカウントと同じメールアドレスで購入されたすべ プラグインライセンスが表示されない場合は、「Licenses → Claim License」に移動します。ライセンスキーを手動で入力するか、購入に利用したメールアドレスを知っている場合は “Claim licenses by email address” セクションにそれを入力することができます。メールアドレスの所有者であることを確認後、 メールアドレスに関連付けられている未使用のライセンスがアカウントに追加されます。 +### Safeguarding Plugin License Keys + +By default your plugin license key will be stored in the database and `project.yaml`. You may, however, move that license key to a custom PHP constant and set the key using the `$VARIABLE_NAME` syntax. + +If you were to create a `MY_PLUGIN_KEY` environment variable, for example, you could then use `$MY_PLUGIN_KEY` in place of the key itself anywhere the plugin license key is required. + ## プラグインライセンスの譲渡 -プラグインライセンスを他の Craft ID アカウントに譲渡するには、あなたの Craft ID アカウントにログインし、「Licenses → Plugins」で表示されるライセンスを選択し、 “Release License” ボタンをクリックしてアカウントから解放します。それによって、他の人が Craft ID アカウントの「Licenses → Claim License」ページから自分自身のライセンスを要求できるようになります。 +To transfer a plugin license to someone else’s Craft ID account, log into your Craft ID account, and click on the license under Licenses → Plugins, and then click the “Release License” button to release it from your account. Then the other person will be able to claim the license for themselves from the Licenses → Claim License page of their Craft ID account. ## 商用プラグインのライセンス -プラグインストアの商用ライセンスは、Craft のライセンスモデルに従わなければなりません。 +Commercial plugins in the Plugin Store must follow Craft’s licensing model: - 開発環境で自由に試すことができますが、本番環境での利用には支払いを必要とします。 - 商用ライセンスは Craft へのインストールごとに1回限り支払う料金で、購入後1年間はアップデートにアクセスできます。 - 追加のアップデートは、年ごとのアップデート料金で入手することができます。 - 質問不要で、ライセンスは購入から30日以内に全額返金することができます。 -さらに、プラグインストア内のすべてのプラグインは [MIT ライセンス](https://opensource.org/licenses/MIT) または [Craft ライセンス](https://craftcms.github.io/license/) のいずれかを使用する必要があります。（一般的に、無料プラグインは MIT ライセンス、商用プラグインは Craft ライセンスを使用します。） +Additionally, all plugins in the Plugin Store must use either the [MIT License](https://opensource.org/licenses/MIT) or the [Craft License](https://craftcms.github.io/license/). (Generally, free plugins will use the MIT License, and commercial plugins will use the Craft license.) -これらのルールは、カスタマーに対しプラグインのライセンスを安全かつ予測可能にするとともに、プラグインベンダーにとって持続可能なビジネスモデルを提供することにも役立ちます。 +Together, these rules make plugin licensing safe and predictable for customers, while also helping provide a sustainable business model for plugin vendors. ## 商用プラグインのサポート -わたしたちは、プラグインベンダーに特定のサポート要件を課すものではありません。サポートポリシーについて知るためには、ベンダーに確認する必要があります。そして、何が期待できるかを知ってください。 +We don’t impose any specific support requirements on plugin vendors. You will need to check with them to learn about their support policies, so you know what to expect. -プラグインベンダーが商用プラグインライセンスとして妥当なレベルのサポートを提供していないと感じる場合は、 にメールを送ってください。 +If you feel that a plugin vendor isn’t providing a reasonable level of support for a commercial plugin license, please send and email to about it. From b4a4ea4ac1c01ec9f54c203b3451a944c5d76a2a Mon Sep 17 00:00:00 2001 From: Brad Bell Date: Fri, 12 Jun 2020 17:34:30 -0700 Subject: [PATCH 094/245] New translations project-config.md (French) --- fr/project-config.md | 20 +++++++++++++++++--- 1 file changed, 17 insertions(+), 3 deletions(-) diff --git a/fr/project-config.md b/fr/project-config.md index 13dcba7fcbd..383c0741f62 100644 --- a/fr/project-config.md +++ b/fr/project-config.md @@ -55,7 +55,7 @@ There are a few things you should keep in mind when working with the project con When Craft detects that `project.yaml` has changed, it will ensure that the versions of Craft and plugins described in the file are compatible with what’s actually installed. -If there’s a discrepancy, you will need to fix that before Craft can begin syncing the file’s changes into the loaded project config. The only practical way to do that is by running `composer install`, as access to the Control Panel will be denied until the discrepancy is resolved. +If there’s a discrepancy, you will need to fix that before Craft can begin syncing the file’s changes into the loaded project config. The only practical way to do that is by running `composer install`, as access to the control panel will be denied until the discrepancy is resolved. ::: tip To avoid downtime on production, you should ensure that `composer install` is built into your deployment workflow. @@ -81,7 +81,7 @@ If you’re overriding volume settings with `config/volumes.php`, you can set se 'secret' => '$SECRET_ACCESS_KEY', ``` -Once you’ve made that change, re-save your volume in the Control Panel so your `project.yaml` file gets updated with the environment variable name. +Once you’ve made that change, re-save your volume in the control panel so your `project.yaml` file gets updated with the environment variable name. ::: ### Production Changes May Be Forgotten @@ -114,4 +114,18 @@ If any settings managed by the project config are modified elsewhere in the data ```bash ./craft project-config/rebuild -``` +``` + +One way to keep project config in sync is to version control `project.yaml` and use the console command for syncing any changes with Craft: + +```bash +./craft project-config/sync +``` + +If changes are not being picked up during the sync process, you can use the `--force` option: + +```bash +./craft project-config/sync --force +``` + +This will treat all project config values as added or updated, resulting in a longer sync process and potentially overriding any expected changes that might have been favored in the database. From e01a0a18e60dca43c9bcc6b1b7470ebdc1f5c3b5 Mon Sep 17 00:00:00 2001 From: Brad Bell Date: Fri, 12 Jun 2020 17:34:32 -0700 Subject: [PATCH 095/245] New translations project-config.md (Japanese) --- ja/project-config.md | 20 +++++++++++++++++--- 1 file changed, 17 insertions(+), 3 deletions(-) diff --git a/ja/project-config.md b/ja/project-config.md index f0b5bf79b8d..851f37a38d3 100644 --- a/ja/project-config.md +++ b/ja/project-config.md @@ -55,7 +55,7 @@ Craft はプロジェクトコンフィグによって管理される何かが `project.yaml` が変更されたことを Craft が検知すると、ファイルに記述される Craft およびプラグインのバージョンが実際にインストールされているものと互換性があることを確認します。 -それらに矛盾があった場合、Craft がファイルの変更をプロジェクトコンフィグへ同期する前に修正する必要があります。矛盾が解消されるまでコントロールパネルへのアクセスが拒否されるため、修正する唯一の実用的な方法は `composer install` を実行することです。 +If there’s a discrepancy, you will need to fix that before Craft can begin syncing the file’s changes into the loaded project config. The only practical way to do that is by running `composer install`, as access to the control panel will be denied until the discrepancy is resolved. ::: tip 本番環境のダウンタイムを回避するため、デプロイメントワークフローに `composer install` が組み込まれていることを確認する必要があります。 @@ -81,7 +81,7 @@ Craft はプロジェクトコンフィグによって管理される何かが 'secret' => '$SECRET_ACCESS_KEY', ``` -その変更を行ったら、`project.yaml` ファイルが環境変数名で更新されるよう、コントロールパネルのボリュームを再保存します。 +Once you’ve made that change, re-save your volume in the control panel so your `project.yaml` file gets updated with the environment variable name. ::: ### 本番環境の変更は忘れられるかもしれません @@ -114,4 +114,18 @@ return [ ```bash ./craft project-config/rebuild -``` +``` + +One way to keep project config in sync is to version control `project.yaml` and use the console command for syncing any changes with Craft: + +```bash +./craft project-config/sync +``` + +If changes are not being picked up during the sync process, you can use the `--force` option: + +```bash +./craft project-config/sync --force +``` + +This will treat all project config values as added or updated, resulting in a longer sync process and potentially overriding any expected changes that might have been favored in the database. From 0c05e7fa2abc0839029c276e0c49ae08f6808a29 Mon Sep 17 00:00:00 2001 From: Brad Bell Date: Fri, 12 Jun 2020 17:34:36 -0700 Subject: [PATCH 096/245] New translations relations.md (French) --- fr/relations.md | 178 ++++++++++++++++++++++++++++++++++-------------- 1 file changed, 125 insertions(+), 53 deletions(-) diff --git a/fr/relations.md b/fr/relations.md index 081901ef97f..020968b0ef5 100644 --- a/fr/relations.md +++ b/fr/relations.md @@ -1,8 +1,6 @@ # Relations -Craft has a powerful engine for relating elements to one another. You create those relationships using relational field types. - -Craft comes with five relational field types: +Craft has a powerful engine for relating elements to one another with five relational field types: * [Assets Fields](assets-fields.md) * [Categories Fields](categories-fields.md) @@ -14,24 +12,22 @@ Just like the other field types, you can add these to your [section](sections-an ## Terminology -Before working with relations in Craft, it's important to grasp the following terms, as they are relevant to the templating side of things. - -Each relation involves two elements: - -* **Source** element - it has the relational field, where you selected the other element. -* **Target** element - the one selected by the source. +Each relationship consists of two elements we call the *source* and *target*: -How does this look in practice? +- The source has the relational field where other elements are chosen. +- The target element is the one selected by the source. -If we have an entry for a drink recipe where we select the ingredients as relationships (via an Entries Field), we'd label the elements as follows: +Let’s say we’d like have an entry for a drink recipe where we select each ingredient as a relationship in an Entries field. -* Drink Recipe Entry: Source -* Ingredients: Target +To set this up: -To set this up, we create a new field of the Entries Field Type, give it the name Ingredients, check Ingredients as the source (the available elements will be from the Ingredients section), and leave the Limit field blank so we can choose as many ingredients as each recipe dictates. +1. Create a new field using the Entries field type, with the name “Ingredients”. +2. From the available source elements, check “Ingredients” so only those entries are options. +3. Leave the Limit field blank so we can choose however many ingredients each recipe needs. -Now we can assign the ingredients to each Drink entry via the new Ingredients relation field. +Now we can assign the ingredients to each Drink entry with the new Ingredients relation field. +By selecting multiple ingredients in an entry, we create several relationships—each with the recipe as the source and the ingredient as the target. ## Templating @@ -41,7 +37,7 @@ Once we have our relations field set up, we can look at the options for outputti If you’ve already got a hold of the source element in your template, like in the example below where we're outputting the Drink entry, you can access its target elements for a particular field in the same way you access any other field’s value: by the handle. -Calling the source's relational field handle (`ingredients`) returns an Element Criteria Model that can output the field’s target elements, in the field-defined order. +Calling the source’s relational field handle (`ingredients`) returns an [entry query](dev/element-queries/entry-queries.md) that can output the field’s target elements, in the field-defined order. If we want to output the ingredients list for a drink recipe, we'd use the following: @@ -67,62 +63,114 @@ You can also add any additional parameters supported by the element type: {% endfor %} ``` - ### The `relatedTo` Parameter Assets, Categories, Entries, Users, and Tags each support a `relatedTo` parameter, enabling all kinds of crazy things. -In its simplest form, you can pass in one of these things to it: +You can pass one of these things to it: + +- A single **element object**: , , , , or +- A single **element ID** +- A [**hash**](dev/twig-primer.md#hashes) with properties we’ll get into below: `element`, `sourceElement` or `targetElement` optionally with `field` and/or `sourceSite` +- An [**array**](dev/twig-primer.md#arrays) containing any mixture of the above options, which can start with `and` for relations on all elements rather than _any_ elements (default behavior is `or`, which you can omit or pass explicitly) -* A , , , , or object -* An element’s ID -* An array of element objects and/or IDs +#### Simple Relationships -By doing that, Craft will return all of the elements related to the given element(s), regardless of which one’s the source or target. +A simpler query might pass a single element object or ID, like a `drinks` entry or entry ID represented here by `drink`: ```twig -{% set relatedDrinks = craft.entries.section('drinks').relatedTo(drink).all() %} +{% set relatedDrinks = craft.entries() + .section('drinks') + .relatedTo(drink) + .all() %} +{# result: drinks entries with *any* relationship to `drink` (source or target) #} ``` -If you want to be a little more specific, `relatedTo` also accepts an object that contains the following properties: +Passing an array of elements returns results relating to any one of the supplied items: -* `element`, `sourceElement`, or `targetElement` -* `field` *(optional)* -* `sourceLocale` *(optional)* +```twig +{% set relatedDrinks = craft.entries() + .section('drinks') + .relatedTo([ gin, lime ]) + .all() %} +{# result: drinks entries with any relationship to `gin` or `lime` #} +``` + +Passing `and` at the beginning of an array returns results relating to *all* of the supplied items: + +```twig +{% set relatedDrinks = craft.entries() + .section('drinks') + .relatedTo([ 'and', gin, lime ]) + .all() %} +{# result: drinks entries with any relationship to `gin` and `lime` #} +``` -Set the first property’s key depending on what you want to get back: +#### Advanced Relationships -* Use `element` if you don’t care whether the returned elements are the source or the target of a relation with the element(s) you’re passing in -* Use `sourceElement` if you want to find elements related to the given element, where the given element is the source of the relation -* Use `targetElement` if you want to find elements related to the given element, where the given element is the target of the relation +You can query more specifically by passing `relatedTo` a [hash](dev/twig-primer.md#hashes) that contains the following properties: -Set the `field` property if you want to limit the scope to relations created by a particular field. You can set this to either a field handle or a field ID (or an array of handles and/or IDs). +| Property | Accepts | Description | +| ---------------------------------------------- | ------------------------------------------------------------------------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `element`, `sourceElement`, or `targetElement` | Element ID, element, [element query](dev/element-queries/), or an array with any of those. | Use `element` for source *or* target relations, `sourceElement` for relations where provided item/set is the source, or `targetElement` for relations where provided item/set is the target. | +| `field` (optional) | Field handle, field ID, or an array with either of those. | Limits scope to relations created by the supplied field(s). | +| `sourceSite` (optional) | [Site](api:craft\models\Site) object, site ID, or site handle. | Limits scope to relations created from the supplied site(s). | + +::: warning +Only use `sourceSite` if you’ve designated your relational field to be translatable. +::: + +This is the equivalent of calling `drink.ingredients.all()`: + +```twig +{% set ingredients = craft.entries() + .section('ingredients') + .relatedTo({ + sourceElement: drink, + field: 'ingredients' + }) + .all() %} +{# result: ingredients entries related from `drink`’s custom `ingredients` field #} +``` + +This doesn’t limit to a specific field, but it limits relations to the current site only: ```twig -{% set ingredients = craft.entries.section('ingredients').relatedTo({ - sourceElement: drink, - field: 'ingredients' -}) %} +{% set ingredients = craft.entries() + .section('ingredients') + .relatedTo({ + sourceElement: drink, + sourceSite: craft.app.sites.currentSite.id + }) + .all() %} +{# result: ingredients entries related from `drink`, limited to the current site #} ``` -Set the `sourceLocale` property if you want to limit the scope to relations created from a particular field. (Only do this if you set your relational field to be translatable.) You can set this to a locale ID. +This finds other drinks that uses the current one’s primary ingredient: ```twig -{% set ingredients = craft.entries.section('ingredients').relatedTo({ - sourceElement: drink, - sourceLocale: craft.app.language -}) %} +{% set moreDrinks = craft.entries() + .section('drinks') + .relatedTo({ + targetElement: drink.ingredients.one(), + field: 'ingredients' + }) + .all() %} +{# result: other drinks using `drink`’s first ingredient #} ``` #### Going Through Matrix -If you want to find elements related to a source element through a [Matrix](matrix-fields.md) field, just pass the Matrix field’s handle to the `field` parameter. If that Matrix field has more than one relational field and you want to target a specific one, you can specify the block type field’s handle using a dot notation: +If you want to find elements related to a source element through a [Matrix](matrix-fields.md) field, pass the Matrix field’s handle to the `field` parameter. If that Matrix field has more than one relational field and you want to target a specific one, you can specify the block type field’s handle using a dot notation: ```twig -{% set ingredients = craft.entries.section('ingredients').relatedTo({ - sourceElement: drink, - field: 'ingredientsMatrix.relatedIngredient' -}).all() %} +{% set ingredients = craft.entries() + .section('ingredients') + .relatedTo({ + sourceElement: drink, + field: 'ingredientsMatrix.relatedIngredient' + }) + .all() %} ``` #### Passing Multiple Relation Criteria @@ -130,12 +178,36 @@ If you want to find elements related to a source element through a [Matrix](matr There might be times when you need to factor multiple types of relations into the mix. For example, outputting all of the current user’s favorite drinks that include espresso: ```twig -{% set espresso = craft.entries.section('ingredients').slug('espresso').first() %} - -{% set cocktails = craft.entries.section('drinks').relatedTo(['and', - { sourceElement: currentUser, field: 'favoriteDrinks' }, - { targetElement: espresso, field: 'ingredients' } -]).all() %} +{% set espresso = craft.entries() + .section('ingredients') + .slug('espresso') + .one() %} + +{% set cocktails = craft.entries() + .section('drinks') + .relatedTo([ + 'and', + { sourceElement: currentUser, field: 'favoriteDrinks' }, + { targetElement: espresso, field: 'ingredients' } + ]) + .all() %} +{# result: current user’s favorite espresso drinks #} ``` -That first argument (`'and'`) specified that the query must match *all* of the relation criteria. You can pass `'or'` instead if you want *any* of the relation criteria to match. +Or you might want to pass an element query to find other users’ favorite drinks using the current one’s primary ingredient: + +```twig +{% set otherUsers = craft.users() + .not(currentUser) + .all() %} + +{% set recommendedCocktails = craft.entries() + .section('drinks') + .relatedTo([ + 'and', + { sourcElement: otherUsers, field: 'favoriteDrinks' }, + { targetElement: drink.ingredients.one(), field: 'ingredients' } + ]) + .all() %} +{# result: other users’ favorite drinks that use `drink`’s first ingredient #} +``` From 41c22b22e8081f907a0fde8dbdf60977d14fca2d Mon Sep 17 00:00:00 2001 From: Brad Bell Date: Fri, 12 Jun 2020 17:34:38 -0700 Subject: [PATCH 097/245] New translations relations.md (Japanese) --- ja/relations.md | 196 +++++++++++++++++++++++++++++++++--------------- 1 file changed, 134 insertions(+), 62 deletions(-) diff --git a/ja/relations.md b/ja/relations.md index 5f884355c2a..fc8934e394a 100644 --- a/ja/relations.md +++ b/ja/relations.md @@ -1,8 +1,6 @@ # リレーション -Craft は、エレメントを互いに関連付けるための強力なエンジンを持っています。関連フィールドタイプを利用して、それらの関連性を作成します。 - -Craft は次の5つの関連フィールドタイプがあります。 +Craft has a powerful engine for relating elements to one another with five relational field types: * [アセットフィールド](assets-fields.md) * [カテゴリフィールド](categories-fields.md) @@ -10,40 +8,38 @@ Craft は次の5つの関連フィールドタイプがあります。 * [タグフィールド](tags-fields.md) * [ユーザーフィールド](users-fields.md) -他のフィールドタイプと同様に、これらを[セクション](sections-and-entries.md#sections)、[ユーザー](users.md)、[アセット](assets.md)、[カテゴリグループ](categories.md)、[タググループ](tags.md)、および、[グローバル設定](globals.md)のフィールドレイアウトに追加できます。 +Just like the other field types, you can add these to your [section](sections-and-entries.md#sections), [user](users.md), [asset](assets.md), [category group](categories.md), [tag group](tags.md), and [global sets](globals.md)’ field layouts. ## 専門用語 -Craft のリレーションを操作する前に、それがテンプレート記法に関連するため、次の用語を把握することが重要です。 - -それぞれのリレーションは2つのエレメントを必要とします。 - -* **ソース**エレメント - 他のエレメントを選択した関連フィールドを持つもの -* **ターゲット**エレメント - ソースによって選択されたエレメント +Each relationship consists of two elements we call the *source* and *target*: -これは実際にどのように見えるのでしょう？ +- The source has the relational field where other elements are chosen. +- The target element is the one selected by the source. -（エントリフィールド経由で）関連する要素を選択したドリンクレシピ向けのエントリがある場合、エレメントに次のようにラベル付けします。 +Let’s say we’d like have an entry for a drink recipe where we select each ingredient as a relationship in an Entries field. -* ドリンクレシピエントリ：ソース -* 原材料：ターゲット +To set this up: -これを設定するために、エントリフィールドタイプの新しいフィールドを作成し、「原材料」という名前を付け、ソース（利用可能なエレメントが原材料セクションに存在するとします）から「原材料」を選択し、それぞれのレシピが必要とする多くの原材料を選択できるようリミット欄を空白のままにします。 +1. Create a new field using the Entries field type, with the name “Ingredients”. +2. From the available source elements, check “Ingredients” so only those entries are options. +3. Leave the Limit field blank so we can choose however many ingredients each recipe needs. -これで、それぞれのドリンクエントリに新しい「原材料」フィールドから原材料を割り当てることができます。 +Now we can assign the ingredients to each Drink entry with the new Ingredients relation field. +By selecting multiple ingredients in an entry, we create several relationships—each with the recipe as the source and the ingredient as the target. ## テンプレート記法 -リレーションフィールドをセットアップすると、テンプレート内で関連するエレメントを出力するためのオプションを見ることができます。 +Once we have our relations field set up, we can look at the options for outputting related elements in our templates. ### ソースエレメントを経由したターゲットエレメントの取得 -「ドリンク」エントリを出力している以下の例のように、すでにテンプレート内でソースレメントを保持している場合、他のフィールドの値にアクセスするのと同じ方法、すなわちハンドルによって、特定のフィールドのターゲットエレメントにアクセスできます。 +If you’ve already got a hold of the source element in your template, like in the example below where we're outputting the Drink entry, you can access its target elements for a particular field in the same way you access any other field’s value: by the handle. -ソースの関連フィールドのハンドル（`ingredients`）を呼び出すと、そのフィールドのターゲットエレメントをフィールドに定義された順序で出力することができる Element Criteria Model が返ります。 +Calling the source’s relational field handle (`ingredients`) returns an [entry query](dev/element-queries/entry-queries.md) that can output the field’s target elements, in the field-defined order. -ドリンクレシピの原材料リストを出力したい場合、次のようにします。 +If we want to output the ingredients list for a drink recipe, we'd use the following: ```twig {% if drink.ingredients|length %} @@ -59,7 +55,7 @@ Craft のリレーションを操作する前に、それがテンプレート {% endif %} ``` -エレメントタイプでサポートされている追加パラメータを付加することもできます。 +You can also add any additional parameters supported by the element type: ```twig {% for ingredient in drink.ingredients.section('ingredients') %} @@ -67,75 +63,151 @@ Craft のリレーションを操作する前に、それがテンプレート {% endfor %} ``` - ### `relatedTo` パラメータ -アセット、カテゴリ、エントリ、ユーザー、および、タグは、それぞれ `relatedTo` パラメータをサポートし、あらゆる種類のとんでもないことを可能にします。 +Assets, Categories, Entries, Users, and Tags each support a `relatedTo` parameter, enabling all kinds of crazy things. + +You can pass one of these things to it: -最も単純な書式としては、次のいずれかを渡すことができます。 +- A single **element object**: , , , , or +- A single **element ID** +- A [**hash**](dev/twig-primer.md#hashes) with properties we’ll get into below: `element`, `sourceElement` or `targetElement` optionally with `field` and/or `sourceSite` +- An [**array**](dev/twig-primer.md#arrays) containing any mixture of the above options, which can start with `and` for relations on all elements rather than _any_ elements (default behavior is `or`, which you can omit or pass explicitly) -* A , , , , or object -* エレメントの ID -* エレメントオブジェクト、および / または、 ID の配列 +#### Simple Relationships -それによって、ソースかターゲットかに関わらず、Craft は与えられたエレメントに関連するすべてのエレメントを返します。 +A simpler query might pass a single element object or ID, like a `drinks` entry or entry ID represented here by `drink`: ```twig -{% set relatedDrinks = craft.entries.section('drinks').relatedTo(drink).all() %} +{% set relatedDrinks = craft.entries() + .section('drinks') + .relatedTo(drink) + .all() %} +{# result: drinks entries with *any* relationship to `drink` (source or target) #} ``` -もう少し具体的であることを望むなら、`relatedTo` は次のプロパティを含むオブジェクトも受け入れます。 +Passing an array of elements returns results relating to any one of the supplied items: -* `element`, `sourceElement`、または `targetElement` -* `field` _（オプション）_ -* `sourceLocale` _（オプション）_ +```twig +{% set relatedDrinks = craft.entries() + .section('drinks') + .relatedTo([ gin, lime ]) + .all() %} +{# result: drinks entries with any relationship to `gin` or `lime` #} +``` + +Passing `and` at the beginning of an array returns results relating to *all* of the supplied items: + +```twig +{% set relatedDrinks = craft.entries() + .section('drinks') + .relatedTo([ 'and', gin, lime ]) + .all() %} +{# result: drinks entries with any relationship to `gin` and `lime` #} +``` -最初のプロパティのキーは、取得したいものにあわせてセットしてください。 +#### Advanced Relationships -* 返されるエレメントが、渡したエレメントとソースまたはターゲットのどちらで関連付くかを気にしない場合、`element`を使用します -* 与えられたエレメントのソースとして関連付くエレメントだけを見つけたい場合、`sourceElement` を使用します -* 与えられたエレメントのターゲットとして関連付くエレメントだけを見つけたい場合、`targetElement` を使用します +You can query more specifically by passing `relatedTo` a [hash](dev/twig-primer.md#hashes) that contains the following properties: -特定のフィールドで作成されたリレーションにスコープを制限する場合、`field` プロパティをセットします。フィールドハンドルかフィールド ID のいずれか（もしくは、ハンドル、および / または、ID の配列）をセットできます。 +| Property | Accepts | Description | +| ---------------------------------------------- | ------------------------------------------------------------------------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `element`, `sourceElement`, or `targetElement` | Element ID, element, [element query](dev/element-queries/), or an array with any of those. | Use `element` for source *or* target relations, `sourceElement` for relations where provided item/set is the source, or `targetElement` for relations where provided item/set is the target. | +| `field` (optional) | Field handle, field ID, or an array with either of those. | Limits scope to relations created by the supplied field(s). | +| `sourceSite` (optional) | [Site](api:craft\models\Site) object, site ID, or site handle. | Limits scope to relations created from the supplied site(s). | + +::: warning +Only use `sourceSite` if you’ve designated your relational field to be translatable. +::: + +This is the equivalent of calling `drink.ingredients.all()`: ```twig -{% set ingredients = craft.entries.section('ingredients').relatedTo({ - sourceElement: drink, - field: 'ingredients' -}) %} +{% set ingredients = craft.entries() + .section('ingredients') + .relatedTo({ + sourceElement: drink, + field: 'ingredients' + }) + .all() %} +{# result: ingredients entries related from `drink`’s custom `ingredients` field #} ``` -特定のフィールドで作成されたリレーションにスコープを制限する場合は、`sourceLocale` プロパティをセットします。（関連フィールドを翻訳可能にしている場合のみ、これを行います。）ロケール ID をここにセットします。 +This doesn’t limit to a specific field, but it limits relations to the current site only: ```twig -{% set ingredients = craft.entries.section('ingredients').relatedTo({ - sourceElement: drink, - sourceLocale: craft.app.language -}) %} +{% set ingredients = craft.entries() + .section('ingredients') + .relatedTo({ + sourceElement: drink, + sourceSite: craft.app.sites.currentSite.id + }) + .all() %} +{# result: ingredients entries related from `drink`, limited to the current site #} ``` -#### 行列を経由する - -[行列](matrix-fields.md)フィールド内のソースエレメントに関連するエレメントを見つけたい場合、行列フィールドのハンドルを `field` パラメータに渡します。複数の関連フィールドを持つ行列フィールドにある特定のフィールドだけをターゲットにしたい場合、ドット表記を利用してブロックタイプのフィールドハンドルを指定できます。 +This finds other drinks that uses the current one’s primary ingredient: ```twig -{% set ingredients = craft.entries.section('ingredients').relatedTo({ - sourceElement: drink, - field: 'ingredientsMatrix.relatedIngredient' -}).all() %} +{% set moreDrinks = craft.entries() + .section('drinks') + .relatedTo({ + targetElement: drink.ingredients.one(), + field: 'ingredients' + }) + .all() %} +{# result: other drinks using `drink`’s first ingredient #} ``` -#### 複数のリレーションの判定基準を渡す +#### Going Through Matrix -複数のタイプのリレーションを組み合わせる必要がある場合があります。例えば、エスプレッソを含む現在のユーザーのお気に入りの飲み物をすべて出力するには、次のようになります。 +If you want to find elements related to a source element through a [Matrix](matrix-fields.md) field, pass the Matrix field’s handle to the `field` parameter. If that Matrix field has more than one relational field and you want to target a specific one, you can specify the block type field’s handle using a dot notation: ```twig -{% set espresso = craft.entries.section('ingredients').slug('espresso').first() %} +{% set ingredients = craft.entries() + .section('ingredients') + .relatedTo({ + sourceElement: drink, + field: 'ingredientsMatrix.relatedIngredient' + }) + .all() %} +``` + +#### Passing Multiple Relation Criteria -{% set cocktails = craft.entries.section('drinks').relatedTo(['and', - { sourceElement: currentUser, field: 'favoriteDrinks' }, - { targetElement: espresso, field: 'ingredients' } -]).all() %} +There might be times when you need to factor multiple types of relations into the mix. For example, outputting all of the current user’s favorite drinks that include espresso: + +```twig +{% set espresso = craft.entries() + .section('ingredients') + .slug('espresso') + .one() %} + +{% set cocktails = craft.entries() + .section('drinks') + .relatedTo([ + 'and', + { sourceElement: currentUser, field: 'favoriteDrinks' }, + { targetElement: espresso, field: 'ingredients' } + ]) + .all() %} +{# result: current user’s favorite espresso drinks #} ``` -最初の引数（`'and'`）は、クエリがリレーションの基準と _すべて_ 一致しなければならないことを指定しています。リレーション基準の _いずれか_ とマッチさせたい場合、`'or'` を渡すことができます。 +Or you might want to pass an element query to find other users’ favorite drinks using the current one’s primary ingredient: + +```twig +{% set otherUsers = craft.users() + .not(currentUser) + .all() %} + +{% set recommendedCocktails = craft.entries() + .section('drinks') + .relatedTo([ + 'and', + { sourcElement: otherUsers, field: 'favoriteDrinks' }, + { targetElement: drink.ingredients.one(), field: 'ingredients' } + ]) + .all() %} +{# result: other users’ favorite drinks that use `drink`’s first ingredient #} +``` From 4b6a3103fe70a1f47aabd662a871a775bc15597b Mon Sep 17 00:00:00 2001 From: Brad Bell Date: Fri, 12 Jun 2020 17:34:39 -0700 Subject: [PATCH 098/245] New translations requirements.md (French) --- fr/requirements.md | 15 ++++++++++----- 1 file changed, 10 insertions(+), 5 deletions(-) diff --git a/fr/requirements.md b/fr/requirements.md index d8fbf29ac4a..8da98c1328e 100644 --- a/fr/requirements.md +++ b/fr/requirements.md @@ -28,18 +28,23 @@ Craft requires the following PHP extensions: * [Reflection](http://php.net/manual/en/class.reflectionextension.php) * [SPL](http://php.net/manual/en/book.spl.php) * [Zip](http://php.net/manual/en/book.zip.php) +* [DOM](http://php.net/manual/en/book.dom.php) ## Optional PHP Extensions * [Intl](http://php.net/manual/en/book.intl.php) – Adds rich internationalization support. -* [DOM](http://php.net/manual/en/book.dom.php) - Required for parsing XML feeds as well as . ## Optional PHP Methods and Configurations Some shared hosting environments will disable certain common PHP methods and configurations that affect Craft features. -* [allow_url_fopen](http://php.net/manual/en/filesystem.configuration.php#ini.allow-url-fopen) - Craft requires PHP configuration to be enabled for updating and installing plugins from the Plugin Store. -* [proc_*](http://php.net/manual/en/ref.exec.php) - The PHP `proc_` methods must be enabled in order to utilize the Plugin Store and to be able to send emails. +- [allow_url_fopen](http://php.net/manual/en/filesystem.configuration.php#ini.allow-url-fopen) must be enabled for updating and installing plugins from the Plugin Store. +- [proc_*](http://php.net/manual/en/ref.exec.php) methods must be enabled in order to utilize the Plugin Store and send emails. +- [ignore_user_abort](https://www.php.net/manual/en/function.ignore-user-abort.php) must be enabled for the [default, web-based queue runner](config:runQueueAutomatically) to operate. + +## Optional Extras + +* [Composer 1.30+](https://docs.craftcms.com/v3/installation.html#downloading-with-composer) - When installing Craft with Composer ## Required Database User Privileges @@ -70,7 +75,7 @@ The database user you tell Craft to connect with must have the following privile ## Control Panel Browser Requirements -Craft’s Control Panel requires a modern browser: +Craft’s control panel requires a modern browser: #### Windows and macOS @@ -85,5 +90,5 @@ Craft’s Control Panel requires a modern browser: * Android: Chrome 4.4 or later ::: tip -Craft’s Control Panel browser requirements have nothing to do with your actual website. If you’re a glutton for punishment and want your website to look flawless on IE 6, that’s your choice. +Craft’s control panel browser requirements have nothing to do with your actual website. If you’re a glutton for punishment and want your website to look flawless on IE 6, that’s your choice. ::: From 8cf62f5463fc64134c4292b78a84cf26b43a6a64 Mon Sep 17 00:00:00 2001 From: Brad Bell Date: Fri, 12 Jun 2020 17:34:41 -0700 Subject: [PATCH 099/245] New translations testing-tips.md (Japanese) --- ja/testing/testing-craft/testing-tips.md | 8 +++----- 1 file changed, 3 insertions(+), 5 deletions(-) diff --git a/ja/testing/testing-craft/testing-tips.md b/ja/testing/testing-craft/testing-tips.md index 7482b8537b2..ab2b99d621b 100644 --- a/ja/testing/testing-craft/testing-tips.md +++ b/ja/testing/testing-craft/testing-tips.md @@ -1,14 +1,12 @@ # Testing Tips -## Maintain your database +## Maintain Your Database The Craft module provides a `cleanup` and `transaction` option for the `codeception.yml` file. It is recommended that you set these options to `true`. ### `transactions` -The transaction option ensures that changes made to the database during your test are rolled back using a Yii2 -[transaction](https://www.yiiframework.com/doc/api/2.0/yii-db-transaction). This means that if you, -for example, save a `craft\db\ActiveRecord` instance before the next test that database row is removed. This prevents collisions and prevents you from spending hours debugging your tests. +The transaction option ensures that changes made to the database during your test are rolled back using a Yii2 [transaction](https://www.yiiframework.com/doc/api/2.0/yii-db-transaction). This means that if you, for example, save a `craft\db\ActiveRecord` instance before the next test that database row is removed. This prevents collisions and prevents you from spending hours debugging your tests. ::: warning If you are running MySQL the `[[%searchindex]]` table may be running the MyISAM Database driver. If this is the case transactions are [not-supported](https://dev.mysql.com/doc/refman/5.6/en/myisam-storage-engine.html). @@ -28,7 +26,7 @@ In the [getting started](../testing-craft/getting-started.md) section you set up Craft namespaces it's tests under one separate root namespace and then expands per test subject. I.E. Unit tests are namespaced under `crafttests\unit` while functional tests are namespaced under `crafttests\functional`. It is advised to apply this same convention to your tests. If you are testing a module or plugin you may want to provide support resources for testing, it is advised to namespace these using `my\plugin\namespace\test`. This is exactly how Craft does it as well. See the [element fixtures](../testing-craft/fixtures.md) as an example. -## Quickly set up tests using the dedicated console command +## Quick Setup via Console Command If you have a general understanding of the typical Craft testing setup, you can use the `tests/setup` console command which will do all of the important setup work for you. It will copy from Craft's `src/test/internal/example-test-suite` folder to either your project's root directory or a directory path of your choosing. All you then have to do is: From 76477aadf8c42f69fb0c25d3cdbe03fba74a4341 Mon Sep 17 00:00:00 2001 From: Brad Bell Date: Fri, 12 Jun 2020 17:34:42 -0700 Subject: [PATCH 100/245] New translations controllers.md (Japanese) --- ja/extend/controllers.md | 161 +++++++++++++++++++++++++++++++++++++++ 1 file changed, 161 insertions(+) create mode 100644 ja/extend/controllers.md diff --git a/ja/extend/controllers.md b/ja/extend/controllers.md new file mode 100644 index 00000000000..2234bbe6d43 --- /dev/null +++ b/ja/extend/controllers.md @@ -0,0 +1,161 @@ +# Controllers + +Plugins and modules can provide custom [controllers](https://www.yiiframework.com/doc/guide/2.0/en/structure-controllers) to Craft installations. + +Controllers should live within a `controllers/` folder within the plugin or modules’s base source folder, and be named in the format `FooBarController.php` (the `Controller` suffix is required). + +::: tip +For the most part, writing controllers for Craft is identical to writing controllers for Yii, so be sure to read the [Yii documentation](https://www.yiiframework.com/doc/guide/2.0/en/structure-controllers) as a starting point. +::: + +Craft controllers should extend , which offers a few advantages over its parent, : + +- You can easily control whether the controller should allow anonymous access by overriding [$allowAnonymous](api:craft\web\Controller::$allowAnonymous). (An active user session is required by default.) +- If an exception is thrown by a controller action and the request accepts a JSON response, the response will automatically be formatted as JSON, with an `error` key. +- It provides several helper methods that ease development. + +## Request Validation Methods + + offers several methods you can call from within your actions, to validate the current request: + +| Method | Description | +| -------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------- | +| [requireLogin()](api:craft\web\Controller::requireLogin()) | Requires that a user is logged in. | +| [requireGuest()](api:craft\web\Controller::requireGuest()) | Requires that the user is anonymous. | +| [requireAdmin()](api:craft\web\Controller::requireAdmin()) | Requires that the user is logged in with an Admin account. | +| [requirePermission()](api:craft\web\Controller::requirePermission()) | Requires that the user is logged in with an account that has a given permission. | +| [requireAuthorization()](api:craft\web\Controller::requireAuthorization()) | Requires that the user has been granted authorization to do something (whether or not they are logged in). | +| [requireElevatedSession()](api:craft\web\Controller::requireElevatedSession()) | Requires that the user has an elevated session. | +| [requirePostRequest()](api:craft\web\Controller::requirePostRequest()) | Requires that the request was sent as a POST request. | +| [requireAcceptsJson()](api:craft\web\Controller::requireAcceptsJson()) | Requires that the request was sent with an `Accept: application/json` header. | +| [requireToken()](api:craft\web\Controller::requireToken()) | Requires that the request was sent with a [token](api:craft\web\Request::getToken()). | +| [requireCpRequest()](api:craft\web\Controller::requireCpRequest()) | Requires that the request URI begins with the [control panel trigger](config:cpTrigger). | +| [requireSiteRequest()](api:craft\web\Controller::requireSiteRequest()) | Requires that the request URI doesn’t begin with the [control panel trigger](config::cpTrigger). | + +```php +public function actionFoo() +{ + // This action should only be available to the control panel + $this->requireCpRequest(); + + // ... +} +``` + +## Requesting Your Controller Action + +There are several ways to access your controller action in a request. + +### POST `action` Param + +Provide an `action` param set to your controller’s action path: + +```bash +curl -d "action=plugin-handle/controller/action" \ + -X POST https://my-project.test/ +``` + +### Custom Route + +Create your own endpoint for requests with a [custom URL rule](/routing.md#advanced-routing-with-url-rules) that resolves to your controller action. + +For example, in `config/routes.php`: + +```php +return [ + 'my/custom/endpoint' => 'plugin-handle/controller/action', +]; +``` + +### The `actions/` Route + +By default, Craft makes an `actions/` route available for appending any valid action path. This can be customized with the config setting. + +```bash +curl -X POST https://my-project.test/actions/plugin-handle/controller/action +``` + +## Handling Requests + +A controller action’s primary job is to handle an incoming web request, and determine the response. There are a few ways an action could go about that, depending on the needs. + +### Rendering Templates + +Controller actions can render and return Twig templates using . + +```php +use yii\web\Response; +use craft\web\View; + +public function actionFoo(): Response +{ + // Render and return the plugin's 'foo.twig' template + return $this->renderTemplate('plugin-handle/foo.twig', $variables, View::TEMPLATE_MODE_CP); +} +``` + + calls internally, which ensures all registered JS and CSS resources have been added to the rendered HTML, and then it will set the `Content-Type` header on the response, based on the MIME type of the template being rendered (using `text/html` as the default if the MIME type isn’t known). + +### Returning JSON + +Controller actions can return JSON responses using . + +```php +use Craft; +use yii\web\Response; + +public function actionFoo(): Response +{ + if (Craft::$app->request->acceptsJson) { + return $this->asJson([ + 'foo' => true, + ]); + } + + // ... +} +``` + +::: tip +You can call instead for an easy way to return a JSON response with an `error` key. +::: + +### Redirecting the Request + +Controller actions can redirect the request using . + +```php +use yii\web\Response; + +public function actionFoo(): Response +{ + return $this->redirect('bar'); +} +``` + +Or, if the request may contain a hashed `redirect` param, you can redirect to that using . + +```php +use yii\web\Response; + +public function actionFoo(): Response +{ + // Redirect the request based on a 'redirect' param + return $this->redirectToPostedUrl(); +} +``` + +If the controller action is saving something, you may want to allow forms’ `redirect` params to include dynamic tokens such as `{id}`, which should be replaced with the object’s attribute values. To support that, pass the object into [redirectToPostedUrl()](craft\web\Controller::redirectToPostedUrl()). + +```php +use yii\web\Response; + +public function actionFoo(): Response +{ + // ... + + // Redirect the request based on a 'redirect' param, + // which can contain entry attribute tokens, such as {id} + return $this->redirectToPostedUrl($entry); +} +``` From e782dba8d617602981d69087d0eac9ff8790356d Mon Sep 17 00:00:00 2001 From: Brad Bell Date: Fri, 12 Jun 2020 17:34:43 -0700 Subject: [PATCH 101/245] New translations queue.md (Japanese) --- ja/testing/testing-craft/queue.md | 13 ++++--------- 1 file changed, 4 insertions(+), 9 deletions(-) diff --git a/ja/testing/testing-craft/queue.md b/ja/testing/testing-craft/queue.md index ed4832ade2a..b6fdb7a0d34 100644 --- a/ja/testing/testing-craft/queue.md +++ b/ja/testing/testing-craft/queue.md @@ -4,9 +4,7 @@ Queueing is a crucial part of many Craft apps. The Craft queue allows you to off ## Running the Queue -Craft provides a simple way to run a queue and thus test your jobs. Queue testing can be performed from your -unit tests. Firstly you need to ensure that your test class has a `$tester` property. -Once this class property is declared you can call the following method: +Craft provides a simple way to run a queue and thus test your jobs. Queue testing can be performed from your unit tests. Firstly you need to ensure that your test class has a `$tester` property. Once this class property is declared you can call the following method: ```php $this->tester->runQueue(MyJob::class, [ @@ -22,15 +20,12 @@ $this->tester->runQueue(MyJob::class, [ Underneath Craft simply runs your job via `Craft::$app->getQueue()`. All methods and actions your job should perform on i.e. the database will thus be performed normally. ::: -## Checking queue data +## Checking Queue Data -Craft provides a `assertPushedToQueue` method that is accessible via the `$this->tester` -property. You must pass the description of the queue when calling this method. +Craft provides a `assertPushedToQueue` method that is accessible via the `$this->tester` property. You must pass the description of the queue when calling this method. Your test will fail if a job with the desired description is not found in the queue. ::: warning -`assertPushedToQueue` only supports the default Craft queue component (`craft\queue\Queue`). -Ensure that you are not setting a custom Queue component that does not extend the Craft class -or no assertions will be made. +`assertPushedToQueue` only supports the default Craft queue component (`craft\queue\Queue`). Ensure that you are not setting a custom Queue component that does not extend the Craft class or no assertions will be made. ::: From 658be49b9d4892b6f2dcd24f466c20c5c8886bbe Mon Sep 17 00:00:00 2001 From: Brad Bell Date: Fri, 12 Jun 2020 17:34:47 -0700 Subject: [PATCH 102/245] New translations cp-templates.md (French) --- fr/extend/cp-templates.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/fr/extend/cp-templates.md b/fr/extend/cp-templates.md index 8d6e974b6c0..4aeab8fbb44 100644 --- a/fr/extend/cp-templates.md +++ b/fr/extend/cp-templates.md @@ -1,6 +1,6 @@ # Control Panel Templates -The Control Panel is built using Twig templates, so extending it with new pages should feel familiar if you’ve worked with Twig on the front-end. +The control panel is built using Twig templates, so extending it with new pages should feel familiar if you’ve worked with Twig on the front-end. Plugins can define templates within the `templates/` folder within their base source folder. Templates within there can be referenced using the plugin’s handle as the template path prefix. From e45f01022c216489ad280e012bcb2e09652c618f Mon Sep 17 00:00:00 2001 From: Brad Bell Date: Fri, 12 Jun 2020 17:34:48 -0700 Subject: [PATCH 103/245] New translations cp-templates.md (Japanese) --- ja/extend/cp-templates.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/ja/extend/cp-templates.md b/ja/extend/cp-templates.md index ad46b50d76f..edc219b7e4e 100644 --- a/ja/extend/cp-templates.md +++ b/ja/extend/cp-templates.md @@ -1,6 +1,6 @@ # コントロールパネルのテンプレート -コントロールパネルは Twig テンプレートを使用して構築されているため、フロントエンドの Twig を操作していれば、新しいページでそれを拡張するのは慣れ親しんだ感じがするでしょう。 +The control panel is built using Twig templates, so extending it with new pages should feel familiar if you’ve worked with Twig on the front-end. プラグインは、ベースソースフフォルダにある `templates/` フォルダ内のテンプレートを定義できます。そこに含まれるテンプレートは、プラグインのハンドルをテンプレートパス接頭辞として使用することで参照できます。 From 938b0278f87a7aabb46482f1a8121db9cf8c4bf2 Mon Sep 17 00:00:00 2001 From: Brad Bell Date: Fri, 12 Jun 2020 17:34:53 -0700 Subject: [PATCH 104/245] New translations element-types.md (French) --- fr/extend/element-types.md | 94 +++++++++++++++++++++++--------------- 1 file changed, 56 insertions(+), 38 deletions(-) diff --git a/fr/extend/element-types.md b/fr/extend/element-types.md index 619b5867e96..19cf7536ce5 100644 --- a/fr/extend/element-types.md +++ b/fr/extend/element-types.md @@ -311,7 +311,7 @@ public function getEditorHtml(): string #### Managing Field Layouts -If you want your element type to support custom fields, you will also need to create a page somewhere within the Control Panel for managing your element type’s field layout. Craft provides a template include that will output a Field Layout Designer for you: +If you want your element type to support custom fields, you will also need to create a page somewhere within the control panel for managing your element type’s field layout. Craft provides a template include that will output a Field Layout Designer for you: ```twig {% include "_includes/fieldlayoutdesigner" with { @@ -448,7 +448,7 @@ Your element type can define “sources”, which are groups of elements defined Element type sources will be visible in the sidebar of element indexes, and within the settings of element relation fields. -To define your element type’s sources, add a protected static `defineSources()` method to your element class: +To define your element type’s sources, add a protected static [defineSources()](api:craft\base\Element::defineSources()) method to your element class: ```php protected static function defineSources(string $context = null): array @@ -481,7 +481,7 @@ When a source is selected, Craft will configure your [element query](#element-qu ## Index Page -You can give your [Control Panel section](cp-section.md) an index page for your element type using the following template: +You can give your [control panel section](cp-section.md) an index page for your element type using the following template: ```twig {% extends '_layouts/elementindex' %} @@ -491,7 +491,7 @@ You can give your [Control Panel section](cp-section.md) an index page for your ### Index Page Actions -You can define which [actions](element-action-types.md) your element type supports on its index page by adding a protected static `defineActions()` method on your element class: +You can define which [actions](element-action-types.md) your element type supports on its index page by adding a protected static [defineActions()](api:craft\base\Element::defineActions()) method on your element class: ```php protected static function defineActions(string $source = null): array @@ -507,11 +507,24 @@ protected static function defineActions(string $source = null): array All element types are [soft-deletable](soft-deletes.md) out of the box, however it’s up to each element type to decide whether they should be restorable. -To make an element restorable, just add the action to the array returned by your static `defineActions()` method. Craft will automatically hide it during normal index views, and show it when someone selects the “Trashed” status option. +To make an element restorable, just add the action to the array returned by your static [defineActions()](api:craft\base\Element::defineActions()) method. Craft will automatically hide it during normal index views, and show it when someone selects the “Trashed” status option. + +### Index Page Exporters + +You can define which [exporter types](element-exporter-types.md) your element type supports on its index page by adding a protected static [defineExporters()](api:craft\base\Element::defineExporters()) method on your element class: + +```php +protected static function defineExporters(string $source): array +{ + $exporters = parent::defineExporters($source); + $exporters[] = MyExporter::class; + return $exporters; +} +``` ### Sort Options -You can define the sort options for your element indexes by adding a protected static `defineSortOptions()` method to your element class: +You can define the sort options for your element indexes by adding a protected static [defineSortOptions()](api:craft\base\Element::defineSortOptions()) method to your element class: ```php protected static function defineSortOptions(): array @@ -527,7 +540,7 @@ When a sort option is selected on an index, its key will be passed to the `$orde ### Table Attributes -You can customize which columns should be available to your element indexes’ Table views by adding a protected `defineTableAttributes()` method to your element class: +You can customize which columns should be available to your element indexes’ Table views by adding a protected [defineTableAttributes()](api:craft\base\Element::defineTableAttributes()) method to your element class: ```php protected static function defineTableAttributes(): array @@ -544,7 +557,7 @@ protected static function defineTableAttributes(): array The first attribute you list here is a special case. It defines the header for the first column in the table view, which is the only one admins can’t remove. Its values will come from your elements’ method. ::: -If it’s a big list, you can also limit which columns should be visible by default for new [sources](#sources) by adding a protected `defineDefaultTableAttributes()` method to your element class: +If it’s a big list, you can also limit which columns should be visible by default for new [sources](#sources) by adding a protected [defineDefaultTableAttributes()](api:craft\base\Element::defineDefaultTableAttributes()) method to your element class: ```php protected static function defineDefaultTableAttributes(string $source): array @@ -610,7 +623,7 @@ public function getThumbUrl(int $size) When an element is saved, Craft’s Search service will index its “searchable attributes” as search keywords on the element. By default, the list of searchable attributes will only include the element’s title and slug, plus any custom field values. -If your element type has additional attributes you want to make searchable, add a protected static `defineSearchableAttributes()` method on your element and list them: +If your element type has additional attributes you want to make searchable, add a protected static [defineSearchableAttributes()](api:craft\base\Element::defineSearchableAttributes()) method on your element and list them: ```php protected static function defineSearchableAttributes(): array @@ -716,15 +729,6 @@ The Edit Category page offers a relatively straightforward example of how it cou Here’s a simple example of the code needed to save an element programatically, which could live within an `actionSave()` controller action: -```php -'categories//new' => 'categories/edit-category', - 'categories//' => 'categories/edit-category', - 'categories///' => 'categories/edit-category', - 'categories//new/' => 'categories/edit-category', -``` - -Once you’ve set up an edit page for your element type, you can add a [getCpEditUrl()](api:craft\base\ElementInterface::getCpEditUrl()) method to your element class, which will communicate your elements’ edit page URLs within the Control Panel. - ```php // Create a new product element $product = new Product(); @@ -735,19 +739,13 @@ $product->currency = Craft::$app->request->getBodyParam('currency'); $product->enabled = (bool)Craft::$app->request->getBodyParam('enabled'); // Set custom field values from POST data in a `fields` namespace -$entry->setFieldValuesFromRequest('fields'); +$product->setFieldValuesFromRequest('fields'); // Save the product $success = Craft::$app->elements->saveElement($product); ``` -## Relations - -### Relation Field - -You can give your element its own relation field by creating a new [field type](field-types.md) that extends . - -That base class does most of the grunt work for you, so you can get your field up and running by implementing three simple methods: +Once you’ve set up an edit page for your element type, you can add a [getCpEditUrl()](api:craft\base\ElementInterface::getCpEditUrl()) method to your element class, which will communicate your elements’ edit page URLs within the control panel. ```php public function getCpEditUrl() @@ -756,9 +754,13 @@ public function getCpEditUrl() } ``` -## Reference Tags +## Relations -If you want your elements to support reference tags (e.g. `{product:100}`), add a static `refHandle()` method to your element class that returns a unique handle that should be used for its reference tags. +### Relation Field + +You can give your element its own relation field by creating a new [field type](field-types.md) that extends . + +That base class does most of the grunt work for you, so you can get your field up and running by implementing three simple methods: ```php setAuthor($author); + } else { + parent::setEagerLoadedElements($handle, $elements); + } +} +``` From bc6f077b732698d1c22f1baff962fe67dcd6cea5 Mon Sep 17 00:00:00 2001 From: Brad Bell Date: Fri, 12 Jun 2020 17:34:54 -0700 Subject: [PATCH 105/245] New translations element-types.md (Japanese) --- ja/extend/element-types.md | 252 +++++++++++++++++++------------------ 1 file changed, 130 insertions(+), 122 deletions(-) diff --git a/ja/extend/element-types.md b/ja/extend/element-types.md index f968624c0b1..b2e87eee70d 100644 --- a/ja/extend/element-types.md +++ b/ja/extend/element-types.md @@ -38,6 +38,22 @@ use craft\base\Element; class Product extends Element { + /** + * @inheritdoc + */ + public static function displayName(): string + { + return 'Product'; + } + + /** + * @inheritdoc + */ + public static function pluralDisplayName(): string + { + return 'Products'; + } + /** * @var int Price */ @@ -293,7 +309,7 @@ public function getEditorHtml(): string #### フィールドレイアウトの管理 -プラグインのコントローラーの1つの投稿のための `` 内に include を配置してください。コントローラーは、次のようにフィールドレイアウトを保存できます。 +If you want your element type to support custom fields, you will also need to create a page somewhere within the control panel for managing your element type’s field layout. Craft provides a template include that will output a Field Layout Designer for you: ```twig {% include "_includes/fieldlayoutdesigner" with { @@ -435,7 +451,7 @@ protected static function defineSources(string $context = null): array エレメントクラスに protected static な `defineActions()`メソッドを追加することで、インデックスページでエレメントタイプをサポートする[アクション](element-action-types.md)を定義できます。 -すべてのエレメントは、デフォルトで[ソフトデリート](soft-deletes.md)できます。しかしながら、復元可能かどうかはそれぞれのエレメントタイプによって決まります。 +To define your element type’s sources, add a protected static [defineSources()](api:craft\base\Element::defineSources()) method to your element class: ```php protected static function defineActions(string $source = null): array @@ -451,7 +467,7 @@ protected static function defineActions(string $source = null): array ## インデックスページ -エレメントクラスに protected static な `defineSortOptions()` メソッドを追加することで、エレメントインデックス向けのソートオプションを定義できます。 +You can give your [control panel section](cp-section.md) an index page for your element type using the following template: ```twig protected static function defineSortOptions(): array @@ -465,7 +481,7 @@ protected static function defineSortOptions(): array ### 復元アクション -ソートオプションがインデックスで選択されると、キーが[エレメントクエリ](#element-query-class)クラスの `$orderBy` プロパティに渡されます（例：`['price' => SORT_ASC]`）。 +You can define which [actions](element-action-types.md) your element type supports on its index page by adding a protected static [defineActions()](api:craft\base\Element::defineActions()) method on your element class: ```php protected static function defineTableAttributes(): array @@ -482,13 +498,57 @@ protected static function defineTableAttributes(): array エレメントクラスに protected な `defineTableAttributes()` メソッドを追加することで、エレメントインデックスのテーブルビューで利用可能な列をカスタマイズできます。 +To make an element restorable, just add the action to the array returned by your static [defineActions()](api:craft\base\Element::defineActions()) method. Craft will automatically hide it during normal index views, and show it when someone selects the “Trashed” status option. + +### Index Page Exporters + +You can define which [exporter types](element-exporter-types.md) your element type supports on its index page by adding a protected static [defineExporters()](api:craft\base\Element::defineExporters()) method on your element class: + +```php +protected static function defineExporters(string $source): array +{ + $exporters = parent::defineExporters($source); + $exporters[] = MyExporter::class; + return $exporters; +} +``` + +### Sort Options + +You can define the sort options for your element indexes by adding a protected static [defineSortOptions()](api:craft\base\Element::defineSortOptions()) method to your element class: + +```php +protected static function defineSortOptions(): array +{ + return [ + 'title' => \Craft::t('app', 'Title'), + 'price' => \Craft::t('plugin-handle', 'Price'), + ]; +} +``` + +When a sort option is selected on an index, its key will be passed to the `$orderBy` property of your [element query](#element-query-class) class (e.g. `['price' => SORT_ASC]`). + +### Table Attributes + +You can customize which columns should be available to your element indexes’ Table views by adding a protected [defineTableAttributes()](api:craft\base\Element::defineTableAttributes()) method to your element class: + +```php +protected static function defineTableAttributes(): array +{ + return [ + 'title' => \Craft::t('app', 'Title'), + 'price' => \Craft::t('plugin-handle', 'Price'), + 'currency' => \Craft::t('plugin-handle', 'Currency'), + ]; +} +``` + ::: tip -ここでリストする最初の属性は、特別なケースです。唯一管理者が削除できない、テーブルビューの最初の列のヘッダーを定義します。その値は（`__toString()` メソッドが返す）エレメントの文字列表現です。 +The first attribute you list here is a special case. It defines the header for the first column in the table view, which is the only one admins can’t remove. Its values will come from your elements’ method. ::: -### テーブル属性 - -大きなリストの場合、エレメントクラスに protected な `defineDefaultTableAttributes()` メソッドを追加することで、新しい[ソース](#sources)向けのデフォルトで表示する列を制限することもできます。 +If it’s a big list, you can also limit which columns should be visible by default for new [sources](#sources) by adding a protected [defineDefaultTableAttributes()](api:craft\base\Element::defineDefaultTableAttributes()) method to your element class: ```php protected static function defineDefaultTableAttributes(string $source): array @@ -497,11 +557,7 @@ protected static function defineDefaultTableAttributes(string $source): array } ``` -テーブルセル向けに、Craft はデフォルトでエレメント属性の文字列の型を出力します。エレメントクラスに protected な `tableAttributeHtml()` メソッドを追加することで、セルの HTML を上書きできます。 - -### サムネイルビュー - -サムネイルビューは、[ソース](#sources)単位でエレメントインデックスページ向けに有効にすることができます。 +For the table cells, by default Craft will output whatever the string version of the element attribute is. You can override the cell HTML by adding a protected `tableAttributeHtml()` method on your element class: ```php protected function tableAttributeHtml(string $attribute): string @@ -518,9 +574,11 @@ protected function tableAttributeHtml(string $attribute): string } ``` -ソースのサムネイルビューを有効にするには、その定義に `hasThumbs` キーを追加してください。 +### Thumb View + +Thumbnail views can be be enabled for your element index page on a [source](#sources)-by-source basis. -次に、エレメントクラスに現在のエレメントのサムネイルの URL を返す `getThumbUrl()` メソッドを追加してください。 +To enable thumbnail view for a source, add a `hasThumbs` key to its definition: ```php protected static function defineSources(string $context = null): array @@ -539,7 +597,7 @@ protected static function defineSources(string $context = null): array } ``` -エレメントが保存されると、Craft の検索サービスはそのエレメントの検索キーワードとして「検索可能な属性」をインデックスします。デフォルトでは、検索可能な属性のリストにはエレメントのタイトルとスラグ、および、カスタムフィールドの値のみが含まれます。 +Then, add a `getThumbUrl()` method to your element class, which returns the URL to the current element’s thumbnail: ```php use craft\helpers\UrlHelper; @@ -552,11 +610,11 @@ public function getThumbUrl(int $size) } ``` -### エディタの HUD +## 検索可能な属性 -エレメントタイプに検索可能な属性を追加したい場合、エレメントに protected static な `defineSearchableAttributes()` メソッドを追加し、それらをリストに入れてください。 +When an element is saved, Craft’s Search service will index its “searchable attributes” as search keywords on the element. By default, the list of searchable attributes will only include the element’s title and slug, plus any custom field values. -エレメントが保存される際、エレメントがシステム内で独自の URI を持ち、存在する場合はどのような見た目になるかを探すために `getUriFormat()` メソッドが呼び出されます。 +If your element type has additional attributes you want to make searchable, add a protected static [defineSearchableAttributes()](api:craft\base\Element::defineSearchableAttributes()) method on your element and list them: ```php protected static function defineSearchableAttributes(): array @@ -565,7 +623,11 @@ protected static function defineSearchableAttributes(): array } ``` -そのため、エレメントの独自の URL を得る場合、このメソッドを実装し、 で解析できる文字列（例：`products/{slug}`）を返さなければなりません。通常、これはハードコードされたものではなく、ユーザー定義の文字列である必要があります。 +## エレメント URL + +When an element is being saved, its `getUriFormat()` method will be called to find out whether the element should have its own URI in the system, and if so, what it should look like. + +So if you want your elements to get their own URLs, you must implement this method and have it return a string that can be parsed with (e.g. `products/{slug}`). Usually this should be a user-defined string, rather than something hard-coded. ```php public function getUriFormat() @@ -574,11 +636,9 @@ public function getUriFormat() } ``` -## 検索可能な属性 +Whenever an element’s URL is requested, Craft will instantiate the element and call its `getRoute()` method, giving the element a chance to decide how the request should be [routed](https://www.yiiframework.com/doc/guide/2.0/en/runtime-routing). -エレメントの URL がリクエストされるたびに、Craft はエレメントをインスタンス化し、その `getRoute()` メソッドを呼び出し、リクエストがどのように[ルーティングされる](https://www.yiiframework.com/doc/guide/2.0/en/runtime-routing)べきか、エレメントに決定するチャンスを与えます。 - -内部的には、 はエレメントクラスで上書きしたい protected な `route()` メソッドを呼び出します。 +Internally, will call a protected `route()` method, which is what you should override in your element class: ```php protected function route() @@ -594,11 +654,11 @@ protected function route() } ``` -## エレメント URL +## エレメントの編集 -インデックスページや関連フィールド内でダブルクリックした際、エレメントエディタの HUD 経由でエレメントを編集できるようにするには、エレメントクラスに現在のユーザーがエレメントを編集する権限を持っているかどうかを返す `getIsEditable()` メソッドを追加してください。 +### Editor HUDs -デフォルトでは、エレメントエディターの HUD はカスタムフィールドだけが含まれます。タイトルフィールド、および / または、エレメント固有の属性フィールドを含めるには、エレメントクラスに `getEditorHtml()` メソッドを追加してください。 +To make your elements editable via Element Editor HUDs when double-clicked on within the index page or relation fields, add a `getIsEditable()` method to your element class, which returns whether the current user has permission to edit the element: ```php public function getIsEditable(): bool @@ -607,9 +667,7 @@ public function getIsEditable(): bool } ``` -エレメントタイプにフルサイズの編集ページを与えたい場合、テンプレート、ルート、コントローラーアクションのすべてをセットする必要があります。 - -カテゴリの編集ページは、それを実行するための比較的簡単な実例を提供します。 +By default the element editor HUD will only include custom fields. To include a Title field and/or any element-specific attribute fields, add a `getEditorHtml()` method to your element class: ```php public function getEditorHtml(): string @@ -634,52 +692,11 @@ public function getEditorHtml(): string } ``` -## エレメントの編集 - -### ページの編集 - -エレメントの編集ページをセットアップしたら、エレメントクラスにコントロールパネル内でエレメントの編集ページ URL を伝える [getCpEditUrl()](api:craft\base\ElementInterface::getCpEditUrl()) メソッドを追加してください。 - -```php -public function getCpEditUrl() -{ - return 'plugin-handle/products/'.$this->id; -} -``` - -を拡張する新しい[フィールドタイプ](field-types.md)を作成することで、エレメントに独自の関連フィールドを与えることができます。 - -```php -price = Craft::$app->request->getBodyParam('price'); +$product->currency = Craft::$app->request->getBodyParam('currency'); +$product->enabled = (bool)Craft::$app->request->getBodyParam('enabled'); -```php -use craft\elements\actions\CopyReferenceTag; +// Set custom field values from POST data in a `fields` namespace +$product->setFieldValuesFromRequest('fields'); -// ... +// Save the product +$success = Craft::$app->elements->saveElement($product); +``` -protected static function defineActions(string $source = null): array +Once you’ve set up an edit page for your element type, you can add a [getCpEditUrl()](api:craft\base\ElementInterface::getCpEditUrl()) method to your element class, which will communicate your elements’ edit page URLs within the control panel. + +```php +public function getCpEditUrl() { - return [ - [ - 'type' => CopyReferenceTag::class, - 'elementType' => static::class, - ], - // ... - ]; + return 'plugin-handle/products/'.$this->id; } ``` @@ -733,56 +749,48 @@ protected static function defineActions(string $source = null): array ### Relation Field -eager-loading サポートが自由に提供されない唯一のケースは、エレメントタイプが他のエレメントと「ハードコーディングされた」関連付けを持っている場合です。例えば、エントリは著者（ユーザーエレメント）を持ちますが、これらのリレーションはカスタムのユーザーフィールドではなく、`entries` テーブルの `authorId` カラムに定義されています。 +You can give your element its own relation field by creating a new [field type](field-types.md) that extends . -エレメントに他のエレメントとハードコーディングされたリレーションがあり、それらのエレメントを eager-loadable にしたい場合、エレメントクラスに `eagerLoadingMap()` メソッドを追加してください。 +That base class does most of the grunt work for you, so you can get your field up and running by implementing three simple methods: ```php -use craft\db\Query; -use craft\elements\User; -use craft\helpers\ArrayHelper; +select(['id as source', 'authorId as target']) - ->from(['{{%entries}}']) - ->where(['and', ['id' => $sourceElementIds], ['not', ['authorId' => null]]]) - ->all(); + public static function displayName(): string + { + return \Craft::t('plugin-handle', 'Products'); + } - return [ - 'elementType' => User::class, - 'map' => $map - ]; + protected static function elementType(): string + { + return Product::class; } - return parent::eagerLoadingMap($sourceElements, $handle); + public static function defaultSelectionLabel(): string + { + return \Craft::t('plugin-handle', 'Add a product'); + } } ``` ## リファレンスタグ -このファンクションは、すでに照会されたエレメント（「ソース」エレメント）と、eager-loading のハンドルを受け入れます。どのソースエレメント ID がどの「ターゲット」エレメント ID を eager-load すべきかのマッピングを返すサポートをします。 +If you want your elements to support reference tags (e.g. `{product:100}`), add a static `refHandle()` method to your element class that returns a unique handle that should be used for its reference tags. ```php -public function setEagerLoadedElements(string $handle, array $elements) +public static function refHandle() { - if ($handle === 'author') { - $author = $elements[0] ?? null; - $this->setAuthor($author); - } else { - parent::setEagerLoadedElements($handle, $elements); - } + return 'product'; } ``` -eager-loaded エレメントが保存されている場所を上書きする必要がある場合、エレメントクラスに `setEagerLoadedElements()` メソッドを追加してください。 +To make it easier for users to copy your elements’ reference tags, you may want to add a “Copy reference tag” [action](#index-page-actions) to your element’s index page. ```php use craft\elements\actions\CopyReferenceTag; From 4eb8a9d456e94d6b0af9f07cb8d957d96dd3e387 Mon Sep 17 00:00:00 2001 From: Brad Bell Date: Fri, 12 Jun 2020 17:34:56 -0700 Subject: [PATCH 106/245] New translations environmental-settings.md (French) --- fr/extend/environmental-settings.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/fr/extend/environmental-settings.md b/fr/extend/environmental-settings.md index c53d445819d..f2f0d0cace5 100644 --- a/fr/extend/environmental-settings.md +++ b/fr/extend/environmental-settings.md @@ -62,7 +62,7 @@ class MyModel extends Model ## Autosuggest Inputs -To guide users when entering your setting’s value in the Control Panel, give your setting an autosuggest input. +To guide users when entering your setting’s value in the control panel, give your setting an autosuggest input. ```twig {% import "_includes/forms" as forms %} From d6cd13733a47976500568f443e8a5df538c0cfd6 Mon Sep 17 00:00:00 2001 From: Brad Bell Date: Fri, 12 Jun 2020 17:34:57 -0700 Subject: [PATCH 107/245] New translations environmental-settings.md (Japanese) --- ja/extend/environmental-settings.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/ja/extend/environmental-settings.md b/ja/extend/environmental-settings.md index 77d6eda0fc9..244262e62da 100644 --- a/ja/extend/environmental-settings.md +++ b/ja/extend/environmental-settings.md @@ -62,7 +62,7 @@ class MyModel extends Model ## オートサジェスト入力 -コントロールパネルで設定値を入力するユーザーに案内するために、設定にオートサジェスト入力を提供できます。 +To guide users when entering your setting’s value in the control panel, give your setting an autosuggest input. ```twig {% import "_includes/forms" as forms %} From cb7e6869625170395206e147e5cd4b28770e6d53 Mon Sep 17 00:00:00 2001 From: Brad Bell Date: Fri, 12 Jun 2020 17:35:00 -0700 Subject: [PATCH 108/245] New translations cp-section.md (French) --- fr/extend/cp-section.md | 12 ++++++++---- 1 file changed, 8 insertions(+), 4 deletions(-) diff --git a/fr/extend/cp-section.md b/fr/extend/cp-section.md index 2ef76cfa0e1..4f8103d35a5 100644 --- a/fr/extend/cp-section.md +++ b/fr/extend/cp-section.md @@ -1,6 +1,6 @@ # Control Panel Section -Modules and plugins can add new sections to the Control Panel using the [EVENT_REGISTER_CP_NAV_ITEMS](api:craft\web\twig\variables\Cp::EVENT_REGISTER_CP_NAV_ITEMS) event: +Modules and plugins can add new sections to the control panel using the [EVENT_REGISTER_CP_NAV_ITEMS](api:craft\web\twig\variables\Cp::EVENT_REGISTER_CP_NAV_ITEMS) event: ```php use craft\events\RegisterCpNavItemsEvent; @@ -57,7 +57,7 @@ Your templates can specify which subnav item should be selected by setting a `se ## Plugin Sections -Plugins that only need to add one section can set a `$hasCpSection` property on their primary plugin class, rather than using the [EVENT_REGISTER_CP_NAV_ITEMS](api:craft\web\twig\variables\Cp::EVENT_REGISTER_CP_NAV_ITEMS) event: +Plugins that only need to add one section can set the `$hasCpSection` property on their primary plugin class, rather than using the [EVENT_REGISTER_CP_NAV_ITEMS](api:craft\web\twig\variables\Cp::EVENT_REGISTER_CP_NAV_ITEMS) event: ```php Date: Fri, 12 Jun 2020 17:35:03 -0700 Subject: [PATCH 109/245] New translations migrations.md (French) --- fr/extend/migrations.md | 23 +++++++++++------------ 1 file changed, 11 insertions(+), 12 deletions(-) diff --git a/fr/extend/migrations.md b/fr/extend/migrations.md index d5fbb0cc24f..a63c7674ed7 100644 --- a/fr/extend/migrations.md +++ b/fr/extend/migrations.md @@ -78,7 +78,9 @@ $result = (new Query()) If you want to log any messages in your migration code, echo it out rather than calling [Craft::info()](api:yii\BaseYii::info()): -If the migration is being run from a console request, this will ensure the message is seen by whoever is executing the migration, as the message will be output into the terminal. If it’s a web request, Craft will capture it and log it to `storage/logs/` just as if you had used `Craft::info()`. +::: tip +You can usually ignore the `safeDown()` method, as Craft doesn’t have a way to revert migrations from the control panel. +::: You can have Craft apply your new migration from the terminal: @@ -90,21 +92,18 @@ You can have Craft apply your new migration from the terminal: echo " > some note\n"; ``` -Craft will also check for new plugin migrations on Control Panel requests, for any plugins that have a new [schema version](api:craft\base\PluginTrait::$schemaVersion), and content migrations can be applied from the Control Panel by going to Utilities → Migrations. +::: warning +The , [batchInsert()](api:craft\db\Migration::batchInsert()), and [update()](api:yii\db\Migration::update()) migration methods will automatically insert/update data in the `dateCreated`, `dateUpdated`, `uid` table columns in addition to whatever you specified in the `$columns` argument. If the table you’re working with does’t have those columns, make sure you pass `false` to the `$includeAuditColumns` argument so you don’t get a SQL error. +::: Plugins can have a special “Install” migration which handles the installation and uninstallation of the plugin. Install migrations live at `migrations/Install.php` alongside normal migrations. They should follow this template: ```php -
    ```bash Content Migration - ./craft migrate/up - - -::: - -Or you can have Craft apply all new migrations across all migration tracks: +use craft\db\Query; -```bash -./craft migrate/all +$result = (new Query()) + // ... + ->all(); ``` ::: @@ -166,7 +165,7 @@ Or you can have Craft apply all new migrations across all migration tracks: ./craft migrate/all ``` -Craft will also check for new plugin migrations on Control Panel requests, for any plugins that have a new [schema version](api:craft\base\PluginTrait::$schemaVersion), and content migrations can be applied from the Control Panel by going to Utilities → Migrations. +Craft will also check for new plugin migrations on control panel requests, for any plugins that have a new [schema version](api:craft\base\PluginTrait::$schemaVersion), and content migrations can be applied from the Control Panel by going to Utilities → Migrations. ## Plugin Install Migrations From b10170fd697151aa0b9344b65d22fa91a242456d Mon Sep 17 00:00:00 2001 From: Brad Bell Date: Fri, 12 Jun 2020 17:35:05 -0700 Subject: [PATCH 110/245] New translations migrations.md (Japanese) --- ja/extend/migrations.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/ja/extend/migrations.md b/ja/extend/migrations.md index 3870fa2c490..09b9f1cbcdd 100644 --- a/ja/extend/migrations.md +++ b/ja/extend/migrations.md @@ -43,7 +43,7 @@ cd /path/to/project マイグレーションクラスには [safeUp()](api:yii\db\Migration::safeUp()) と [safeDown()](api:yii\db\Migration::safeDown()) メソッドが含まれます。マイグレーションが _適用される_ ときに `safeUp()` が実行され、_復帰させる_ ときに `safeDown()` が実行されます。 ::: tip -コントロールパネルから Craft がマイグレーションを元に戻す方法がないため、通常 `safeDown()` メソッドは無視できます。 +You can usually ignore the `safeDown()` method, as Craft doesn’t have a way to revert migrations from the control panel. ::: `safeUp()` メソッドから [Craft の API](https://docs.craftcms.com/api/v3/) にフルアクセスできますが、プラグインのマイグレーションはここでプラグイン独自の API を呼び出すことを避けるようにする必要があります。長い間にプラグインのデータベーススキーマが変化するように、スキーマに関する API の想定も変化します。古いマイグレーションが、まだ適用されていないデータベースの変更を前提とするサービスメソッドを呼び出すと、SQL エラーをもたらすでしょう。そのため、一般的には独自のマイグレーションクラスからすべての SQL クエリを直接実行する必要があります。コードを複製しているように感じるかもしれませんが、将来的にも保証されるでしょう。 @@ -63,7 +63,7 @@ $this->insert('{{%tablename}}', $rows); ``` ::: warning -、[batchInsert()](api:craft\db\Migration::batchInsert())、および、[update()](api:yii\db\Migration::update()) マイグレーションメソッドは、引数 `$columns` で指定したものに加えて `dateCreated`、 `dateUpdated`、`uid` テーブルのカラムにあるデータを自動的に挿入 / アップデートします。操作しているテーブルにこれらのカラムがない場合、引数 `$includeAuditColumns` に `false` を渡して、SQL エラーにならないようにしてください。 +The , [batchInsert()](api:craft\db\Migration::batchInsert()), and [update()](api:yii\db\Migration::update()) migration methods will automatically insert/update data in the `dateCreated`, `dateUpdated`, `uid` table columns in addition to whatever you specified in the `$columns` argument. If the table you’re working with does’t have those columns, make sure you pass `false` to the `$includeAuditColumns` argument so you don’t get a SQL error. ::: ::: tip @@ -110,7 +110,7 @@ echo " > some note\n"; ./craft migrate/all ``` -Craft はコントロールパネルのリクエストで新しい[スキーマバージョン](api:craft\base\PluginTrait::$schemaVersion)を持つプラグインの新しいプラグインのマイグレーションをチェックし、コンテンツのマイグレーションはコントロールパネルの「ユーティリティ > マイグレーション」から適用できます。 +Craft will also check for new plugin migrations on control panel requests, for any plugins that have a new [schema version](api:craft\base\PluginTrait::$schemaVersion), and content migrations can be applied from the Control Panel by going to Utilities → Migrations. ## プラグインのインストールマイグレーション From e222bbc4da121c955cda12aea9d4feb3608000f3 Mon Sep 17 00:00:00 2001 From: Brad Bell Date: Fri, 12 Jun 2020 17:35:08 -0700 Subject: [PATCH 111/245] New translations module-guide.md (French) --- fr/extend/module-guide.md | 7 +++++++ 1 file changed, 7 insertions(+) diff --git a/fr/extend/module-guide.md b/fr/extend/module-guide.md index c93e4310ad1..a34e7c6649d 100644 --- a/fr/extend/module-guide.md +++ b/fr/extend/module-guide.md @@ -92,6 +92,13 @@ class Module extends \yii\base\Module // Define a custom alias named after the namespace Craft::setAlias('@bar', __DIR__); + // Set the controllerNamespace based on whether this is a console or web request + if (Craft::$app->getRequest()->getIsConsoleRequest()) { + $this->controllerNamespace = 'bar\\console\\controllers'; + } else { + $this->controllerNamespace = 'bar\\controllers'; + } + parent::init(); // Custom initialization code goes here... From 117a70d1f54df87684825f1db1458c6b9131bb0c Mon Sep 17 00:00:00 2001 From: Brad Bell Date: Fri, 12 Jun 2020 17:35:13 -0700 Subject: [PATCH 112/245] New translations module-guide.md (Japanese) --- ja/extend/module-guide.md | 7 +++++++ 1 file changed, 7 insertions(+) diff --git a/ja/extend/module-guide.md b/ja/extend/module-guide.md index 05fb67230b7..a5c15c29254 100644 --- a/ja/extend/module-guide.md +++ b/ja/extend/module-guide.md @@ -92,6 +92,13 @@ class Module extends \yii\base\Module // Define a custom alias named after the namespace Craft::setAlias('@bar', __DIR__); + // Set the controllerNamespace based on whether this is a console or web request + if (Craft::$app->getRequest()->getIsConsoleRequest()) { + $this->controllerNamespace = 'bar\\console\\controllers'; + } else { + $this->controllerNamespace = 'bar\\controllers'; + } + parent::init(); // Custom initialization code goes here... From 71a820f2d3f80b6a844df59b5bc1b19bfcaa5267 Mon Sep 17 00:00:00 2001 From: Brad Bell Date: Fri, 12 Jun 2020 17:35:16 -0700 Subject: [PATCH 113/245] New translations plugin-guide.md (French) --- fr/extend/plugin-guide.md | 32 +++++++++++--------------------- 1 file changed, 11 insertions(+), 21 deletions(-) diff --git a/fr/extend/plugin-guide.md b/fr/extend/plugin-guide.md index 16cd3e950cc..62a94ea5a8f 100644 --- a/fr/extend/plugin-guide.md +++ b/fr/extend/plugin-guide.md @@ -9,7 +9,7 @@ Before you begin working on a plugin, you need to decide on a few things: - **Package name** – Used to name your Composer package for the plugin. (See Composer’s [documentation](https://getcomposer.org/doc/04-schema.md#name) for details.) We recommend prefixing the second segment (after the `/`) with `craft-`, to help identify that this is a Craft plugin. For example, `pixelandtonic/craft-recipes`. - **Namespace** – The root namespace that your plugin’s classes will live in. (See the [PSR-4](https://www.php-fig.org/psr/psr-4/) autoloading specification for details.) Note that this should *not* begin with `craft`; use something that identifies you, the developer. - **Plugin handle** – Something that uniquely identifies your plugin within the Craft ecosystem. (Plugin handles must begin with a letter and contain only lowercase letters, numbers, and dashes. They should be `kebab-cased`.) -- **Plugin name** – What your plugin will be called within the Control Panel. +- **Plugin name** – What your plugin will be called within the control panel. ## Setting up the basic file structure @@ -67,9 +67,8 @@ Create a `composer.json` file at the root of your plugin directory, and use this } }, "extra": { - "handle": "plugin-handle", "name": "Plugin Name", - "documentationUrl": "https://github.com/developer/repo/blob/master/README.md" + "handle": "plugin-handle" } } ``` @@ -78,38 +77,29 @@ Replace: - `package/name` with your package name. - `Developer Name` with your name, or the organization name that the plugin should be attributed to. -- `https://developer-website.tld` with the URL to the website the developer name should link to in the Control Panel. +- `https://developer-website.tld` with the URL to the website the developer name should link to in the control panel. - `email@developer-website.tld` with your support email. - `developer/repo` with the actual GitHub account and repository names where the plugin will live. - `master` with the actual primary branch name of your GitHub repository. - ``namespace\\prefix\` with your namespace prefix. (Use double-backslashes because this is JSON, and note this must end with``\`.) -- `plugin-handle` with your plugin handle. - `Plugin Name` with your plugin name. +- `plugin-handle` with your plugin handle. - `MIT` with `proprietary` if you plan to use [Craft License](https://craftcms.github.io/license/) (see [Choose a License](plugin-store.md#choose-a-license) on the “Publishing to the Plugin Store” page). If you’d prefer to release your plugin with the [Craft license](https://craftcms.github.io/license/) rather than [MIT](https://opensource.org/licenses/MIT), change the `license` value to `"proprietary"`. -Here’s a full list of the properties that can go in that `extra` object: +::: tip +While not strictly required by Composer, we recommend you explicitly set the `version` in your `composer.json` because it makes a couple things easier on you when developing the plugin. Don’t forget to keep it updated though! +::: + +In addition to `name` and `handle` (which are both required), there are a few other things you can include in that `extra` object: -- `handle` – The plugin handle *(required)*. - `class` – The [Plugin class](#the-plugin-class) name. If not set, the installer will look for a `Plugin.php` file at each of the `autoload` path roots. -- `basePath` – The base path to your plugin’s source files. This can begin with one of your `autoload` namespaces, formatted as a [Yii alias](https://www.yiiframework.com/doc/guide/2.0/en/concept-aliases) (e.g. `@vendorname/foo`). If not set, the directory that contains your primary Plugin class will be used. -- `name` – The plugin name. If not set, the package name (sans vendor prefix) will be used. -- `version` - The plugin version. If not set, the current package version will be used. -- `schemaVersion` – The plugin schema version. - `description` – The plugin description. If not set, the main `description` property will be used. - `developer` – The developer name. If not set, the first author’s `name` will be used (via the `authors` property). - `developerUrl` – The developer URL. If not set, the `homepage` property will be used, or the first author’s `homepage` (via the `authors` property). - `developerEmail` – The support email. If not set, the `support.email` property will be used. - `documentationUrl` – The plugin’s documentation URL. If not set, the `support.docs` property will be used. -- `sourceLanguage` – The plugin’s source language (defaults to `en-US`). -- `hasSettings` – Whether the plugin has settings (should be `true` or `false`). -- `hasCpSection` – Whether the plugin has its own section in the Control Panel (should be `true` or `false`). -- `components` – Object defining any [component configs](https://www.yiiframework.com/doc/guide/2.0/en/structure-application-components) that should be present on the plugin. - -::: tip -While not strictly required by Composer, we recommend you explicitly set the `version` in your `composer.json` because it makes a couple things easier on you when developing the plugin. Don’t forget to keep it updated though! -::: ::: warning If you’re updating a Craft 2 plugin, make sure to remove the `composer/installers` dependency if it has one. @@ -216,8 +206,8 @@ composer require package/name Plugins can provide an icon, which will be visible on the Settings → Plugins page. -![The Settings → Plugins page in Craft’s Control Panel.](../images/plugin-index.png) +![The Settings → Plugins page in Craft’s control panel.](../images/plugin-index.png) Plugin icons must be square SVG files, saved as `icon.svg` at the root of your plugin’s source directory (e.g `src/`). -If your plugin has a [Control Panel section](cp-section.md), you can also give its global nav item a custom icon by saving an `icon-mask.svg` file in the root of your plugin’s source directory. Note that this icon cannot contain strokes, and will always be displayed in a solid color (respecting alpha transparency). +If your plugin has a [control panel section](cp-section.md), you can also give its global nav item a custom icon by saving an `icon-mask.svg` file in the root of your plugin’s source directory. Note that this icon cannot contain strokes, and will always be displayed in a solid color (respecting alpha transparency). From cb0768a31b064676cd2a6788b0a5695cb4f69eb6 Mon Sep 17 00:00:00 2001 From: Brad Bell Date: Fri, 12 Jun 2020 17:35:18 -0700 Subject: [PATCH 114/245] New translations plugin-guide.md (Japanese) --- ja/extend/plugin-guide.md | 44 +++++++++++++++------------------------ 1 file changed, 17 insertions(+), 27 deletions(-) diff --git a/ja/extend/plugin-guide.md b/ja/extend/plugin-guide.md index 06ca23128fc..dd6d68b1893 100644 --- a/ja/extend/plugin-guide.md +++ b/ja/extend/plugin-guide.md @@ -9,7 +9,7 @@ - **パッケージ名** – プラグイン向けに Composer パッケージの名前として使用されます。（詳細については、[documentation](https://getcomposer.org/doc/04-schema.md#name) を参照してください。）これが Craft のプラグインだと識別する手助けになるため、2番目のセグメント（`/` の後）に接頭辞 `craft-` を付けることをお勧めします。例えば `pixelandtonic/craft-recipes` のような形です。 - **名前空間** – プラグインのクラスが稼働する、ルート名前空間。（詳細については、[PSR-4](https://www.php-fig.org/psr/psr-4/) オートローディング仕様を参照してください。）これは `craft\` ではじめるべき *ではない* ことに注意してください。あなたやデベロッパーを識別する何かを使用してください。 - **プラグインハンドル** – Craft のエコシステム内でプラグインを一意に識別する何か。（プラグインハンドルは、文字ではじまり、小文字の英字、数字、および、ダッシュのみでなければなりません。`kebab-cased` にすべきです。） -- **プラグイン名** – コントロールパネル内でプラグインを何と呼ぶか。 +- **Plugin name** – What your plugin will be called within the control panel. ## 基本ファイル構造の設定 @@ -67,9 +67,8 @@ } }, "extra": { - "handle": "plugin-handle", "name": "Plugin Name", - "documentationUrl": "https://github.com/developer/repo/blob/master/README.md" + "handle": "plugin-handle" } } ``` @@ -78,39 +77,30 @@ - `package/name` をパッケージ名にします。 - `Developer Name` をあたなの名前、または、プラグインが帰属する組織名にします。 -- `https://developer-website.tld` をコントロールパネルの開発者名にリンクするウェブサイトの URL にします。 +- `https://developer-website.tld` with the URL to the website the developer name should link to in the control panel. - `email@developer-website.tld` をサポートのメールアドレスにします。 - `developer/repo` をプラグインが稼働している実際の GitHub アカウントとリポジトリ名にします。 - `master` を GitHub リポジトリの実際のプライマリブランチ名にします。 - ``namespace\\prefix\\` を名前空間接頭辞にします。（これは JSON であるため、二重バックスラッシュを使用し、最後が``\\` でなければならない点に注意してください。） -- `plugin-handle` をプラグインハンドルにします。 -- `Plugin Name` をプラグイン名にします。 +- `Plugin Name` with your plugin name. +- `plugin-handle` with your plugin handle. - [Craft License](https://craftcms.github.io/license/) を使用する計画の場合、`MIT` を `proprietary` にします（「プラグインストアでの配布」ページの[ライセンスの選択](plugin-store.md#choose-a-license)を参照してください）。 [MIT](https://opensource.org/licenses/MIT) よりむしろ [Craft license](https://craftcms.github.io/license/) でプラグインをリリースしたい場合、`license` 値を `"proprietary"` に変更してください。 -`extra` オブジェクトにセットできるプロパティの完全なリストは、次の通りです。 - -- `handle` – プラグインハンドル _（必須）_ 。 -- `class` – [プラグインクラス](#the-plugin-class)名。設定されていない場合、インストーラーはそれぞれの `autoload` パスのルートで `Plugin.php` ファイルを探します。 -- `basePath` – プラグインのソースファイルへのベースパス。[Yii alias](https://www.yiiframework.com/doc/guide/2.0/en/concept-aliases)（例： `@vendorname/foo`） としてフォーマットされた `autoload` 名前空間の1つからはじめることができます。設定されてない場合、プライマリプラグインクラスを含むディレクトリが使用されます。 -- `name` – プラグイン名。設定されていない場合、（ベンダー接頭辞なしの）パッケージ名が使用されます。 -- `version` - プラグインのバージョン。設定されていない場合、現在のパッケージバージョンが使用されます。 -- `schemaVersion` – プラグインスキーマのバージョン。 -- `description` – プラグインの説明。設定されていない場合、メインの `description` プロパティが使用されます。 -- `developer` – 開発者の名前。設定されていない場合、（`authors` プロパティ経由で）最初の作者の `name` が使用されます。 -- `developerUrl` – 開発者の URL。設定されていない場合、`homepage` プロパティ、または、（`authors` プロパティ経由で）最初の作者の `homepage` が使用されます。 -- `developerEmail` – サポートのメールアドレス。設定されていない場合、`support.email` プロパティが使用されます。 -- `documentationUrl` – プラグインのドキュメントの URL。設定されていない場合、`support.docs` プロパティが使用されます。 -- `sourceLanguage` – プラグインのソース言語（デフォルトは `en-US`）。 -- `hasSettings` – プラグインの設定があるかどうか（`true` または `false`）。 -- `hasCpSection` – コントロールパネルにプラグイン独自のセクションを持つかどうか（`true` または `false`）。 -- `components` – プラグイン上に存在するべき [component configs](https://www.yiiframework.com/doc/guide/2.0/en/structure-application-components) を定義するオブジェクト。 - ::: tip -Composer が厳密に要求しているわけではありませんが、プラグインを開発する際にいくつかのことが簡単に行えるよう `composer.json` へ明示的に`version` を設定することをお勧めします。そして、アップデートし続けることを忘れないでください！ +While not strictly required by Composer, we recommend you explicitly set the `version` in your `composer.json` because it makes a couple things easier on you when developing the plugin. Don’t forget to keep it updated though! ::: +In addition to `name` and `handle` (which are both required), there are a few other things you can include in that `extra` object: + +- `class` – The [Plugin class](#the-plugin-class) name. If not set, the installer will look for a `Plugin.php` file at each of the `autoload` path roots. +- `description` – The plugin description. If not set, the main `description` property will be used. +- `developer` – The developer name. If not set, the first author’s `name` will be used (via the `authors` property). +- `developerUrl` – The developer URL. If not set, the `homepage` property will be used, or the first author’s `homepage` (via the `authors` property). +- `developerEmail` – The support email. If not set, the `support.email` property will be used. +- `documentationUrl` – The plugin’s documentation URL. If not set, the `support.docs` property will be used. + ::: warning Craft 2 プラグインをアップデートする場合、`composer/installers` 依存があれば確実に削除してください。 ::: @@ -216,8 +206,8 @@ composer require package/name プラグインは「設定 > プラグイン」ページに表示されるアイコンを提供できます。 -![The Settings → Plugins page in Craft’s Control Panel.](../images/plugin-index.png) +![The Settings → Plugins page in Craft’s control panel.](../images/plugin-index.png) プラグインアイコンは、プラグインのソースディレクトリ（例：`src/`）のルートに `icon.svg` として保存された、正方形の SVG ファイルでなければいけません。 -プラグインが [コントロールパネルのセクション](cp-section.md) を持つ場合は、プラグインのソースディレクトリのルートに `icon-mask.svg` ファイルを保存することによって、グローバルナビゲーション項目にカスタムアイコンを付けることもできます。このアイコンにはストロークを含めることができず、常に（アルファ透明度に関して）ソリッドカラーで表示されることに注意してください。 +If your plugin has a [control panel section](cp-section.md), you can also give its global nav item a custom icon by saving an `icon-mask.svg` file in the root of your plugin’s source directory. Note that this icon cannot contain strokes, and will always be displayed in a solid color (respecting alpha transparency). From 6a3643909141f2b8bce37035a82c512559134808 Mon Sep 17 00:00:00 2001 From: Brad Bell Date: Fri, 12 Jun 2020 17:35:20 -0700 Subject: [PATCH 115/245] New translations plugin-settings.md (French) --- fr/extend/plugin-settings.md | 10 ++++++---- 1 file changed, 6 insertions(+), 4 deletions(-) diff --git a/fr/extend/plugin-settings.md b/fr/extend/plugin-settings.md index a0636689fbc..6961bb807fa 100644 --- a/fr/extend/plugin-settings.md +++ b/fr/extend/plugin-settings.md @@ -4,7 +4,9 @@ ## Settings Model -Plugins that have global settings need to define a “settings model”, which is responsible for storing the setting values, and validating them. +Once you’ve indicated your plugin will have settings by enabling `hasCpSettings` in your main plugin class or `composer.json`, you’ll need to provide a model for defining them. + +This “settings model” is responsible for storing and validating the setting values. Settings models are just like any other [model](https://www.yiiframework.com/doc/guide/2.0/en/structure-models). To create it, create a `models/` directory within your plugin’s source directory, and create a `Settings.php` file within it: @@ -106,7 +108,7 @@ The config file cannot contain any keys that are not defined in the plugin’s s ## Settings Pages -Plugins can also provide a settings page in the Control Panel, which may make it easier for admins to manage settings values, depending on the plugin. +Plugins can also provide a settings page in the control panel, which may make it easier for admins to manage settings values, depending on the plugin. To give your plugin a settings page, create a `templates/` directory within your plugin’s source directory, and create a `settings.twig` file within it: @@ -154,11 +156,11 @@ class Plugin extends \craft\base\Plugin } ``` -With all that in place, your plugin will now get its own icon on the Settings page, and a cog icon in its row on the Settings → Plugins page, which will link to `/admin/settings/plugin-handle`. +With all that in place, your plugin will now get its own icon on the Settings page, and a cog icon in its row on the Settings → Plugins page, which will link to `/admin/settings/plugins/plugin-handle`. ### Advanced Settings Pages -When the `/admin/settings/plugin-handle` Control Panel URL is requested, your plugin is ultimately in charge of the response. Namely, your plugin’s `getSettingsResponse()` method. The default `getSettingsResponse()` implementation in will call your plugin’s `settingsHtml()` method, and then tell the active controller to render Craft’s `settings/plugins/_settings` template (the layout template for plugin settings pages), passing it the HTML returned by `settingsHtml()`. +When the `/admin/settings/plugins/plugin-handle` control panel URL is requested, your plugin is ultimately in charge of the response. Namely, your plugin’s `getSettingsResponse()` method. The default `getSettingsResponse()` implementation in will call your plugin’s `settingsHtml()` method, and then tell the active controller to render Craft’s `settings/plugins/_settings` template (the layout template for plugin settings pages), passing it the HTML returned by `settingsHtml()`. If a plugin needs more control over its settings page(s), it can override its `getSettingsResponse()` method and do whatever it wants with the request. From 56bd4ed5960b79f31bfb722112f086349c5d8077 Mon Sep 17 00:00:00 2001 From: Brad Bell Date: Fri, 12 Jun 2020 17:35:22 -0700 Subject: [PATCH 116/245] New translations cp-section.md (Japanese) --- ja/extend/cp-section.md | 18 +++++++++++------- 1 file changed, 11 insertions(+), 7 deletions(-) diff --git a/ja/extend/cp-section.md b/ja/extend/cp-section.md index 7a648ab00f0..4b0d2d4fb96 100644 --- a/ja/extend/cp-section.md +++ b/ja/extend/cp-section.md @@ -1,6 +1,6 @@ # コントロールパネルのセクション -モジュールとプラグインは、[EVENT_REGISTER_CP_NAV_ITEMS](api:craft\web\twig\variables\Cp::EVENT_REGISTER_CP_NAV_ITEMS) イベントを使用して新しいセクションをコントロールパネルに追加できます。 +Modules and plugins can add new sections to the control panel using the [EVENT_REGISTER_CP_NAV_ITEMS](api:craft\web\twig\variables\Cp::EVENT_REGISTER_CP_NAV_ITEMS) event: ```php use craft\events\RegisterCpNavItemsEvent; @@ -55,7 +55,7 @@ public function init() ## プラグインセクション -1つのセクションだけを追加したいプラグインは、[EVENT_REGISTER_CP_NAV_ITEMS](api:craft\web\twig\variables\Cp::EVENT_REGISTER_CP_NAV_ITEMS) イベントを使うのではなく、プライマリプラグインクラスの `$hasCpSection` プロパティで設定できます。 +Plugins that only need to add one section can set the `$hasCpSection` property on their primary plugin class, rather than using the [EVENT_REGISTER_CP_NAV_ITEMS](api:craft\web\twig\variables\Cp::EVENT_REGISTER_CP_NAV_ITEMS) event: ```php Date: Fri, 12 Jun 2020 17:35:23 -0700 Subject: [PATCH 117/245] New translations coding-guidelines.md (Japanese) --- ja/extend/coding-guidelines.md | 44 ++++++++++++++++++---------------- 1 file changed, 24 insertions(+), 20 deletions(-) diff --git a/ja/extend/coding-guidelines.md b/ja/extend/coding-guidelines.md index 45fd929e4dd..871a5531b36 100644 --- a/ja/extend/coding-guidelines.md +++ b/ja/extend/coding-guidelines.md @@ -15,6 +15,10 @@ Craft や Craft プラグイン向けのコードを書くときには、この - 型変換の後にスペースを置かないでください（`(int)$foo`）。 - `include` / `include_once` / `require` / `require_once` のファイルパスを括弧で囲まないでください。それらはファンクションではありません。 +::: tip +Craft’s PhpStorm settings repository includes a code style scheme and inspection profile: +::: + ## ベストプラクティス - 可能な限り、メソッド引数の型を宣言してください。 @@ -59,7 +63,7 @@ Craft や Craft プラグイン向けのコードを書くときには、この - Use the `DIRECTORY_SEPARATOR` constant rather than `'/'` when defining file paths. ::: tip -PhpStorm プラグインの [Php Inspections (EA Extended)](https://plugins.jetbrains.com/idea/plugin/7622-php-inspections-ea-extended-) は、これらのベストプラクティスの問題を見つけて修正するのに役立ちます。 +The [Php Inspections (EA Extended)](https://plugins.jetbrains.com/idea/plugin/7622-php-inspections-ea-extended-) PhpStorm plugin can help you locate and fix these sorts of best practice issues. ::: ## 名前空間とクラス名 @@ -71,18 +75,18 @@ PhpStorm プラグインの [Php Inspections (EA Extended)](https://plugins.jetb ## メソッド名 -**いかなる引数も受け取らない** Getter メソッド（何かをするのではなく、何かを返すことを主たる目的とするメソッド）は、`get` ではじめます。そして、対応するマジック Getter プロパティを文書化するために、クラスの docblock に対応する `@property` タグがあるべきです。 +Getter methods (methods whose primary responsibility is to return something, rather than do something) that **don’t accept any arguments** should begin with `get` , and there should be a corresponding `@property` tag in the class’s docblock to document the corresponding magic getter property. - `getAuthor()` - `getIsSystemOn()` - `getHasFreshContent()` -（省略できるかどうかに関わらず）**1つ、または、複数の引数を受け入れる** Getter メソッドは、「正しいと思う」場合のみ `get` ではじめます。 +Getter methods that **accept one or more arguments** (regardless of whether they can be omitted) should only begin with `get` if it “sounds right”. - `getError($attribute)` - `hasErrors($attribute = null)` -静的メソッドは、一般的に `get` ではじめるべきではありません。 +Static methods should generally not start with `get`. - `className()` - `displayName()` @@ -91,26 +95,26 @@ PhpStorm プラグインの [Php Inspections (EA Extended)](https://plugins.jetb ### 引数の型 -可能な限り、すべてのファンクションの引数に PHP 7.0 でサポートされる[引数の型宣言](http://php.net/manual/en/functions.arguments.php#functions.arguments.type-declaration)を使用してください。唯一の例外は、次の通りです。 +Use PHP 7.0-supported [argument type declarations](http://php.net/manual/en/functions.arguments.php#functions.arguments.type-declaration) for all function arguments whenever possible. The only exceptions should be: - [マジックメソッド](http://php.net/manual/en/language.oop5.magic.php)（例：`__toString()`） - 複数の `null` 以外の値型を受け入れる引数 - 親メソッドで型宣言を持たない、親クラスのメソッドを上書きするメソッド - インターフェースで必要なメソッドで、インターフェースメソッドに型宣言がないもの -2つの型を受け入れる引数の1つが `null` の場合、引数は `null` 以外の型を型宣言に持ち、デフォルト値を `null` とします。 +If an argument accepts two types and one of them is `null`, the argument should have a type declaration for the non-`null` type, and a default value of `null`. ```php public function foo(string $bar = null) ``` ::: tip -`null` を受け入れる引数の次に必須の引数がある場合も、これを実行します。これは、PHP で `null` を許可しながら引数型を強制する唯一の方法です。 +Do this even if there are required arguments following the argument that accepts `null`. This is the only way to enforce an argument type while also allowing `null` in PHP. ::: ### 戻り値の型 -可能な限り、すべてのメソッドに PHP 7.0 でサポートされる[戻り値の型宣言](http://php.net/manual/en/functions.returning-values.php#functions.returning-values.type-declaration)を使用してください。唯一の例外は、次の通りです。 +Use PHP 7.0-supported [return type declarations](http://php.net/manual/en/functions.returning-values.php#functions.returning-values.type-declaration) for all methods whenever possible. The only exceptions should be: - [マジックメソッド](http://php.net/manual/en/language.oop5.magic.php)（例：`__toString()`） - 複数の戻り値の型を持つメソッド @@ -129,7 +133,7 @@ public function foo(string $bar = null) ### インターフェース 対 実装クラス -`パブリックサービスメソッド上の @param`、`@return`、`@var`、`@method` および `@property` タグは、（該当する場合）実装クラスではなくインターフェースを参照します。 +`@param` , `@return` , `@var` , `@method` and `@property` tags on public service methods should reference Interfaces (when applicable), not their implementation class: ```php // Bad: @@ -144,7 +148,7 @@ public function foo(string $bar = null) */ ``` -インラインの `@var` タグは、インターフェースではなく実装クラスを参照します。 +Inline `@var` tags should reference implementation classes, not their interfaces: ```php // Bad: @@ -159,7 +163,7 @@ public function foo(string $bar = null) ### Happy Path -[Happy Path](https://en.wikipedia.org/wiki/Happy_path) を使用してください。すべて期待通りにできた場合、一般的にはメソッドの実行が最後に行き着くところまで処理されるべきです。 +Use [them](https://en.wikipedia.org/wiki/Happy_path). In general the execution of a method should only make it all the way to the end if everything went as expected. ```php // Bad: @@ -183,7 +187,7 @@ return true; ### `if`…`return`…`else` -このようにしないでください。それは意味がなく、一見すると紛らわしいです。 +Don’t do this. There’s no point, and can be misleading at first glance. ```php // Bad: @@ -205,7 +209,7 @@ return $bar; ### 戻り値の型 -リクエストを完了するコントローラーアクションでは、文字列（HTML）、または、Response オブジェクトのいずれかを返す必要があります。 +Controller actions that should complete the request must return either a string (HTML) or a Response object. ```php // Bad: @@ -219,7 +223,7 @@ return $this->renderTemplate($template, $variables); ### JSON アクション -JSON を返すオプションを持つコントローラーアクションでは、Ajax リクエストの場合ではなく、リクエストが明示的に JSON レスポンスを受け入れる場合に、JSON を返す必要があります。 +Controller actions that have the option of returning JSON should do so if the request explicitly accepts a JSON response; not if it’s an Ajax request. ```php // Bad: @@ -233,7 +237,7 @@ if (\Craft::$app->getRequest()->getAcceptsJson()) { } ``` -JSON *だけを* 返すコントローラーアクションでは、リクエストで JSON を受け入れる必要があります。 +Controller actions that *only* return JSON should require that the request accepts JSON. ```php $this->requireAcceptsJson(); @@ -273,7 +277,7 @@ $query->innerJoin('{{%bar}} bar', '[[bar.fooId]] = [[foo.id]]'); ## Getter と Setter -Getter および Setter メソッドは、クラスの docblock 内に対応する `@property` タグを持つ必要があります。それによって、PhpStorm のような IDE がマジックプロパティを知ることができます。 +Getter and setter methods should have a corresponding `@property` tag in the class’s docblock, so IDEs like PhpStorm can be aware of the magic properties. ```php /** @@ -293,7 +297,7 @@ class Entry } ``` -パフォーマンスを少し向上させデバッグを容易にするために、一般的にはマジックプロパティを通すよりむしろ、Getter および Setter メソッドを直接呼び出し続けるべきです。 +For a slight performance improvement and easier debugging, you should generally stick with calling the getter and setter methods directly rather than going through their magic properties. ```php // Bad: @@ -307,7 +311,7 @@ $entry->setAuthor($newAuthor); ### App コンポーネントの Getter -App コンポーネントには、App コンポーネントの Getter メソッドである [get()](api:yii\di\ServiceLocator::get()) を直接呼び出す、独自の Getter ファンクションが必要です。 +App components should have their own getter functions, which call the app component getter method [get()](api:yii\di\ServiceLocator::get()) directly: ```php /** @@ -319,7 +323,7 @@ public function getEntries() } ``` -そして、それらをマジックプロパティの代わりに使用する必要があります。 +And you should use those instead of their magic properties: ```php // Bad: @@ -329,7 +333,7 @@ public function getEntries() \Craft::$app->getEntries()->saveEntry($entry); ``` -同じメソッド内で同じ App コンポーネントを複数回参照する場合、ローカル参照をそこに保存します。 +If you will be referencing the same app component multiple times within the same method, save a local reference to it. ```php // Bad: From f14bf22fc792cff10e55fe33c2e4f0fa17483462 Mon Sep 17 00:00:00 2001 From: Brad Bell Date: Fri, 12 Jun 2020 17:35:25 -0700 Subject: [PATCH 118/245] New translations plugin-store.md (French) --- fr/extend/plugin-store.md | 16 +++++++++++++++- 1 file changed, 15 insertions(+), 1 deletion(-) diff --git a/fr/extend/plugin-store.md b/fr/extend/plugin-store.md index d694f4f1d88..537b95d15d1 100644 --- a/fr/extend/plugin-store.md +++ b/fr/extend/plugin-store.md @@ -27,7 +27,9 @@ To register your plugin, first make sure it’s published to a public GitHub rep If your plugins are published to a GitHub organization account, make sure that the organization is checked when authenticating your GitHub account. ::: -From your Craft ID account, go to Plugins → “Add a plugin”, and click the “Select” button next to your plugin’s repository. You will then be able to edit its description, screenshots, and other details. +From your Craft ID account, you’ll need to first go to “Account Settings”, make sure “Enable plugin developer features” is checked under your username, and choose “Save”. + +Once plugin developer features are enabled, add your plugin by going to Plugins → “Add a plugin”, and choose the “Select” button next to your plugin’s repository. You will then be able to edit its description, screenshots, and other details. ### Choose a Price @@ -42,10 +44,22 @@ If you wish to sell your plugin, choose a price point that makes sense. Here are You will also be required to pick a Renewal Price, which is the annual fee the Plugin Store will charge customers who wish to continue installing new updates, after the first year. Pick a Renewal Price that is around 20-50% of the initial Price. For example, if you are charging $99 for your plugin, your Renewal Price should be between $19-$49. +Pixel & Tonic takes a 20% processing fee on all plugin sales; be sure to factor that into your plugin pricing. + ::: warning If you initially submit your plugin as free, you will not be allowed to change it to commercial later. You can, however, give it a commercial [edition](plugin-editions.md) that offers extended functionality, as long as you don’t remove crucial functionality from the free edition. ::: +### Declare Craft Version Support + +Every plugin needs to explicitly require a minimum Craft CMS version in `composer.json`: + +```json +"require": { + "craftcms/cms": "^3.0.0" +} +``` + ### Submit for Approval Once you’re ready to submit the plugin, click the “Submit for approval” button. Once your plugin is approved, it will become visible on [plugins.craftcms.com](https://plugins.craftcms.com/). It won’t necessarily be available in the in-app Plugin Store yet, though, unless your plugin already has at least one [release](#plugin-releases). From 2d0b64ef4982420003804fbdfc0ed84200e03310 Mon Sep 17 00:00:00 2001 From: Brad Bell Date: Fri, 12 Jun 2020 17:35:26 -0700 Subject: [PATCH 119/245] New translations tags.md (French) --- fr/dev/tags.md | 721 ++++++++++++++++++++++++++++++++++++++++++++++++- 1 file changed, 707 insertions(+), 14 deletions(-) diff --git a/fr/dev/tags.md b/fr/dev/tags.md index 8c0f63e4258..ecd5051c1a3 100644 --- a/fr/dev/tags.md +++ b/fr/dev/tags.md @@ -1,16 +1,709 @@ # Tags -In addition to the template tags that [Twig comes with](https://twig.symfony.com/doc/tags/index.html), Craft provides a few of its own. - -- [cache](tags/cache.md) -- [css](tags/css.md) -- [exit](tags/exit.md) -- [header](tags/header.md) -- [hook](tags/hook.md) -- [js](tags/js.md) -- [nav](tags/nav.md) -- [paginate](tags/paginate.md) -- [redirect](tags/redirect.md) -- [requireLogin](tags/requirelogin.md) -- [requirePermission](tags/requirepermission.md) -- [switch](tags/switch.md) +The following [tags](https://twig.symfony.com/doc/2.x/templates.html#control-structure) are available to Twig templates in Craft: + +| Tag | Description | +| ------------------------------------------------------------------- | ------------------------------------------------------------ | +| [apply](https://twig.symfony.com/doc/2.x/tags/apply.html) | Applies Twig filters to the nested template code. | +| [autoescape](https://twig.symfony.com/doc/2.x/tags/autoescape.html) | Controls the escaping strategy for the nested template code. | +| [block](https://twig.symfony.com/doc/2.x/tags/block.html) | Defines a template block. | +| [cache](#cache) | Caches a portion of your template. | +| [css](#css) | Registers a ` + ``` From 9662927c3490699086c409e7ac34a527c127e4dc Mon Sep 17 00:00:00 2001 From: Brad Bell Date: Thu, 16 Jul 2020 22:47:38 -0700 Subject: [PATCH 228/245] New translations user-profile-form.md (French) --- fr/dev/examples/user-profile-form.md | 521 +++++---------------------- 1 file changed, 81 insertions(+), 440 deletions(-) diff --git a/fr/dev/examples/user-profile-form.md b/fr/dev/examples/user-profile-form.md index cec187ec415..e78ddc0635b 100644 --- a/fr/dev/examples/user-profile-form.md +++ b/fr/dev/examples/user-profile-form.md @@ -1,473 +1,114 @@ # User Profile Form -You can create a front-end form to let users edit their profiles without granting them access to the control panel. To do this, you can point your form to the same controller that the Control Panel uses for its profile form. (Jump down to [Form Action](#form-action) for more about forms and controllers.) - -We’ll provide two examples: The simplest possible profile form and a full-featured profile form. - -## Simple Profile - -The following fields don't require any validation. - -- first name -- last name -- photo - -If those are all you need, then the form can be quite simple. - -```twig -{% requireLogin %} - -
    - {{ actionInput('users/save-user') }} - - {{ csrfInput() }} - - {{ hiddenInput('userId', currentUser.id) }} - -
    - - -
    - -
    - - -
    - -
    - - - {% if currentUser.photo %} -
    - -
    - {% endif %} -
    - -
    - {# This file field takes precedence over the ”Delete photo” checkbox #} - - -
    - -
    - {# If a file has been selected, this has no effect #} - -
    - -
    - - Reset -
    -
    -``` - -The [Breaking it down](#breaking-it-down) section will cover these fields as they appear in the advanced profile example below. - -## Advanced Profile - -This example adds everything including: - -- first name -- last name -- photo -- username -- email -- password -- a custom field -- validation - -See the [Breakdown](#breakdown) section for details. See the [Extras](#extras) section for some example styles for this form. - -Keep in mind that there is a custom Bio field included in this example, so if you don’t have a Bio field, then delete that section after you copy and paste into your template. +You can create a form that allows users to edit their profile using the following code as a starting point: ```twig +{# Require that a user is logged in to view this form. #} {% requireLogin %} -
    - - {% set notice = craft.app.session.getFlash('notice') %} - {% if notice %} -

    {{ notice }}

    +{% macro errorList(errors) %} + {% if errors %} +
      + {% for error in errors %} +
    • {{ error }}
      • + {% endfor %} +
    {% endif %} +{% endmacro %} - {% set formUser = user is defined ? user : currentUser %} - - {% if formUser.hasErrors() %} -
    -

    Unable to save user. Please check for errors.

    +{# If there were any validation errors, a `user` variable will be passed to the + template, which contains the posted values and validation errors. If that’s not + set, we’ll default to the current user. #} +{% set user = user ?? currentUser %} -
      - {% for error in formUser.getFirstErrors() %} -
    • {{ error }}
      • - {% endfor %} -
    -
    - {% endif %} +{% if user.hasErrors() %} +

    Unable to save your profile.

    +{% endif %} + {{ csrfInput() }} - - {# {{ redirectInput('users/'~currentUser.username) }} #} - {{ actionInput('users/save-user') }} + {{ hiddenInput('userId', user.id) }} + {{ redirectInput("users/#{currentUser.username}") }} - {{ hiddenInput('userId', formUser.id) }} - -
    - - -
    + + {{ input('text', 'firstName', user.firstName, { + id: 'first-name', + class: user.hasErrors('firstName') ? 'error', + }) }} + {{ _self.errorList(user.getErrors('firstName')) }} -
    - - -
    + + {{ input('text', 'lastName', user.firstName, { + id: 'last-name', + class: user.hasErrors('lastName') ? 'error', + }) }} + {{ _self.errorList(user.getErrors('lastName')) }} - {% if formUser.photo %} -
    + {% if user.photo %} - -
    + {{ user.photo.getImg({width: 150, height: 150})|attr({ + id: 'user-photo', + alt: user.friendlyName, + }) }} -
    -

    If a new photo is selected, this checkbox has no effect.

    -
    {% endif %} -
    - - -
    + + {{ input('file', 'photo', null, { + id: 'photo', + accept: 'image/png,image/jpeg', + }) }} {% if not craft.app.config.general.useEmailAsUsername %} - {% set error = formUser.getFirstError('username') %} - {% set class = error ? 'has-error' : '' %} -
    - -

    If left blank, this will become the email address.

    - -

    {{ error }}

    - -
    + + {{ input('text', 'username', user.username, { + id: 'username', + class: user.hasErrors('username') ? 'error', + }) }} + {{ _self.errorList(user.getErrors('username')) }} {% endif %} - {% set error = formUser.getFirstError('email') %} - {% set class = error ? 'has-error' : '' %} -
    - - - {% if craft.app.projectConfig.get('users.requireEmailVerification') %} -

    New email addresses need to be verified.

    - {% endif %} - -

    {{ error }}

    - -
    - - {% set error = formUser.getFirstError('newPassword') %} - {% set class = error ? 'has-error' : '' %} -
    - -

    {{ error }}

    - -
    - - {% set error = formUser.getFirstError('currentPassword') %} - {% set class = error ? 'has-error' : '' %} -
    - -

    Required to change Password and Email

    -

    {{ error }}

    - -
    - - {# Custom field example. Delete if you don't have a `bio` field. #} - {% set error = formUser.getFirstError('bio') %} - {% set class = error ? 'has-error' : '' %} -
    - -

    {{ error }}

    - -
    - -
    - - Reset -
    -
    -``` - -### Breaking it down - -We’ll walk through the advanced form example step by step. - -#### Require Login -```twig -{% requireLogin %} -``` - -Make sure the user is logged in or else the template will throw errors doing anything with `currentUser`. Be sure to read the documentation for [{% requireLogin %} Tags](https://docs.craftcms.com/v3/dev/tags/requirelogin.html) to avoid unexpected `404 Not Found` errors. - -#### Form Action - -```twig -
    - {{ actionInput('users/save-user') }} -``` - -The `` tag does not have an `action=""` parameter on purpose. The hidden `name="action"` input tells Craft which controller and controller method to use. - -:::tip -The control panel profile form uses Craft’s [UserController::actionSaveUser()](api:craft\controllers\UsersController#method-actionsaveuser) controller and you’re free to use it on the front end too if it suits your needs. Otherwise, you can use it as inspiration to build your own controller in a custom module or plugin. -::: - -#### Notice - -```twig -{% set notice = craft.app.session.getFlash('notice') %} -{% if notice %} -

    {{ notice }}

    -{% endif %} -``` - -Upon success, this notice will display the message, “User saved.” That is, of course, unless you’ve set a redirect input. (Jump to [Optional Redirect](#optional-redirect) to see how.) - -#### User Variable - -```twig -{% set formUser = user is defined ? user : currentUser %} -``` - -When the form first loads, we use the `currentUser` variable. If there were validation errors, there will be a `user` variable with the previously-submitted values. - -#### CSRF - -```twig -{{ csrfInput() }} -``` - -The `csrfInput()` generator function is required in all forms for Craft’s [cross-site request forgery](https://en.wikipedia.org/wiki/Cross-site_request_forgery) protection unless you disabled it in the setting. - -#### Optional Redirect - -```twig -{# {{ redirectInput('users/'~currentUser.username) }} #} -``` - -That line is commented out, but demonstrates that upon a successful save, you can redirect to another page; perhaps a user’s home page based on their username. - -```twig -{{ hiddenInput('userId', formUser.id) }} -``` - -The user id is required to update the correct user. You’ll want to make sure group permissions are set not to allow users to edit other users’ profiles. - -#### Name Fields - -```twig -
    - - -
    - -
    - - -
    -``` - -These fields don’t need any validation, so they’re pretty straightforward. - -#### User Photo - -```twig -{% if formUser.photo %} -
    - - -
    - -
    - -

    If a new photo is selected, this checkbox has no effect.

    -
    -{% endif %} - -
    - - -
    -``` - -If a user photo exists, we’ll show it and include a checkbox for the option to delete it. No matter what, we’ll show a file field so they can choose a new photo. If this section feels unrefined, then some JavaScript enhancements might help. That’s up to you. - -#### Username - -```twig -{% if not craft.app.config.general.useEmailAsUsername %} - {% set error = formUser.getFirstError('username') %} - {% set class = error ? 'has-error' : '' %} -
    - -

    If left blank, this will become the email address.

    - -

    {{ error }}

    - -
    -{% endif %} -``` - -If you’ve set the config setting to `true`, then we won’t show the Username field. - -Here is where validation comes into play. Setting an `error` variable to `getFirstError('username')` tells us whether or not there is an error for this field. (It will be `null` if not.) If there is an error, then we’ll set the appropriate class names on HTML elements to reveal them and show the error message. - -You’ll find styles in the [Extras](#extras) section to show and hide HTML elements based on class names. Of course, you can handle that however you like. - -#### Email - -```twig -{% set error = formUser.getFirstError('email') %} -{% set class = error ? 'has-error' : '' %} -
    - + + {{ input('text', 'email', user.unverifiedEmail ?? user.email, { + id: 'email', + class: user.hasErrors('email') ? 'error', + }) }} + {{ _self.errorList(user.getErrors('username')) }} {% if craft.app.projectConfig.get('users.requireEmailVerification') %} -

    New email addresses need to be verified.

    +

    New email addresses need to be verified.

    {% endif %} -

    {{ error }}

    - -
    -``` - -That is like the Username field except for showing a message that the user should expect to verify a new email address if you’ve ticked the checkbox for “Verify email addresses?” in the control panel under Settings → Users → Settings. The [Current Password](#current-password) field will be required to change an email address. - -#### Password - -```twig -{% set error = formUser.getFirstError('newPassword') %} -{% set class = error ? 'has-error' : '' %} -
    - -

    {{ error }}

    - -
    -``` - -The user can change their password, but they’ll need to enter their [Current Password](#current-password) too. There will be an error if the given password is too short. - -#### Current Password - -```twig -{% set error = formUser.getFirstError('currentPassword') %} -{% set class = error ? 'has-error' : '' %} -
    - -

    Required to change Password and Email

    -

    {{ error }}

    - -
    -``` - -This field is required when the email address or password has changed. Otherwise, the user can leave it blank. You could use some fancy JavaScript to hide or show this based on the state of the other fields. - -#### Custom Field: Bio - -```twig -{% set error = formUser.getFirstError('bio') %} -{% set class = error ? 'has-error' : '' %} -
    - -

    {{ error }}

    - -
    -``` - -Let’s say you added a custom field named “Bio” with a handle of `bio` to the user profile field layout under Settings → Users → Fields. Let’s also say it’s a required field. The difference here is that custom fields belong in a `fields` array with names like `field[]`. - -:::tip -Handling complex custom fields, like Matrix or third-party plugin fields, can seem complicated. You might want to view the source code of a user profile form in the control panel to see how to handle those types of fields. -::: - -#### Form Submission + + {{ input('password', 'newPassword', null, { + id: 'new-password', + class: user.hasErrors('newPassword') ? 'error', + }) }} + {{ _self.errorList(user.getErrors('newPassword')) }} + + + {{ input('password', 'password', null, { + id: 'current-password', + class: user.hasErrors('currentPassword') ? 'error' + }) }} + {{ _self.errorList(user.getErrors('currentPassword')) }} + + {# Custom “Bio” field #} + + {{ tag('textarea', user.bio, { + id: 'bio', + name: 'fields[bio]', + class: user.hasErrors('bio') ? 'error', + }) }} + {{ _self.errorList(user.getErrors('bio')) }} -```twig -
    - Reset -
    -``` - -A link to reload the current page is a good way to reset the form because it will use `currentUser` variable, and validation errors on will be forgotten. - -## Extras - -Here are some styles to make the forms on this page more readable in your browser. - -```html - + ``` From ea19b9d2eb0bdc99e673b717cf1152a431d18463 Mon Sep 17 00:00:00 2001 From: Brad Bell Date: Thu, 16 Jul 2020 22:47:39 -0700 Subject: [PATCH 229/245] New translations entry-form.md (Japanese) --- ja/dev/examples/entry-form.md | 78 +++++++++++++++++++---------------- 1 file changed, 42 insertions(+), 36 deletions(-) diff --git a/ja/dev/examples/entry-form.md b/ja/dev/examples/entry-form.md index 8fd84e8ed18..762da3b657c 100644 --- a/ja/dev/examples/entry-form.md +++ b/ja/dev/examples/entry-form.md @@ -1,54 +1,60 @@ # エントリの投稿フォーム -次のコードを利用して、サイトのフロントエンド向けに新しいエントリの投稿フォームを作成できます。 +You can create a form for submitting new entries using the following code as a starting point: ```twig {% macro errorList(errors) %} - {% if errors %} -
      - {% for error in errors %} -
    • {{ error }}
      • - {% endfor %} -
    - {% endif %} + {% if errors %} +
      + {% for error in errors %} +
    • {{ error }}
      • + {% endfor %} +
    + {% endif %} {% endmacro %} +{# If there were any validation errors, an `entry` variable will be passed to the + template, which contains the posted values and validation errors. If that’s not + set, we’ll default to a new entry. #} +{% set entry = entry ?? create('craft\\elements\\Entry') %} +
    - {{ csrfInput() }} - {{ actionInput('entries/save-entry') }} - {{ redirectInput('viewentry/{slug}') }} - {{ hiddenInput('sectionId', '2') }} - {{ hiddenInput('enabled', '1') }} - - - - - {% if entry is defined %} - {{ _self.errorList(entry.getErrors('title')) }} - {% endif %} - - - - - {% if entry is defined %} - {{ _self.errorList(entry.getErrors('body')) }} - {% endif %} - - + {{ csrfInput() }} + {{ actionInput('entries/save-entry') }} + {{ redirectInput('viewentry/{slug}') }} + {{ hiddenInput('sectionId', '2') }} + {{ hiddenInput('enabled', '1') }} + + + {{ input('text', 'title', entry.title, { + id: 'title', + class: entry.hasErrors('title') ? 'error', + }) }} + {{ _self.errorList(entry.getErrors('title')) }} + + + {{ tag('textarea', entry.body, { + id: 'body', + name: 'body', + class: entry.hasErrors('body') ? 'error', + }) }} + {{ _self.errorList(entry.getErrors('body')) }} + +
    - ``` -「sectionId」は必ずエントリを保存したいセクションの実際の ID に調整してください。 +Be sure to change the `sectionId` value to the actual ID of the section want to save the entry to. エントリを送信するユーザーは、そのセクションのエントリを作成するための権限を持っている必要があります。 -### エントリの編集フォーム +::: tip +You can accept anonymous entry submissions using the [Guest Entries](https://plugins.craftcms.com/guest-entries) plugin. +::: + +### Editing Existing Entries -不可視項目の「entryId」を追加すると、既存のエントリを保存するためのフォームに変更できます。 +You can modify the form to save existing entries by adding an `entryId` hidden input to the form: ```twig {{ hiddenInput('entryId', entry.id) }} From 0072940c5f0f816a9504c7fbf5bce7411046ec78 Mon Sep 17 00:00:00 2001 From: Brad Bell Date: Thu, 23 Jul 2020 13:26:08 -0700 Subject: [PATCH 230/245] New translations getting-started.md (French) --- fr/testing/testing-craft/getting-started.md | 1 + 1 file changed, 1 insertion(+) diff --git a/fr/testing/testing-craft/getting-started.md b/fr/testing/testing-craft/getting-started.md index 61b71246f9a..71e85fcd316 100644 --- a/fr/testing/testing-craft/getting-started.md +++ b/fr/testing/testing-craft/getting-started.md @@ -100,6 +100,7 @@ use craft\test\TestSetup; ini_set('date.timezone', 'UTC'); // Use the current installation of Craft +define('CRAFT_TESTS_PATH', __DIR__); define('CRAFT_STORAGE_PATH', __DIR__ . '/_craft/storage'); define('CRAFT_TEMPLATES_PATH', __DIR__ . '/_craft/templates'); define('CRAFT_CONFIG_PATH', __DIR__ . '/_craft/config'); From 1d9832f49664eae6330993f240335cd9f8f7c365 Mon Sep 17 00:00:00 2001 From: Brad Bell Date: Thu, 23 Jul 2020 13:26:10 -0700 Subject: [PATCH 231/245] New translations getting-started.md (Japanese) --- ja/testing/testing-craft/getting-started.md | 1 + 1 file changed, 1 insertion(+) diff --git a/ja/testing/testing-craft/getting-started.md b/ja/testing/testing-craft/getting-started.md index 61b71246f9a..71e85fcd316 100644 --- a/ja/testing/testing-craft/getting-started.md +++ b/ja/testing/testing-craft/getting-started.md @@ -100,6 +100,7 @@ use craft\test\TestSetup; ini_set('date.timezone', 'UTC'); // Use the current installation of Craft +define('CRAFT_TESTS_PATH', __DIR__); define('CRAFT_STORAGE_PATH', __DIR__ . '/_craft/storage'); define('CRAFT_TEMPLATES_PATH', __DIR__ . '/_craft/templates'); define('CRAFT_CONFIG_PATH', __DIR__ . '/_craft/config'); From 9c22a9b4941f5a25c848e0a04efb8f2f71c87948 Mon Sep 17 00:00:00 2001 From: Brad Bell Date: Sun, 26 Jul 2020 09:16:37 -0700 Subject: [PATCH 232/245] New translations tags.md (Japanese) --- ja/dev/tags.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/ja/dev/tags.md b/ja/dev/tags.md index adea2cce165..6d0ba4daeb0 100644 --- a/ja/dev/tags.md +++ b/ja/dev/tags.md @@ -82,7 +82,7 @@ You can combine this parameter with [globally](#globally) to cache templates on ::: ::: warning -If you change the template code within a `{% cache %}` that uses a custom key, any existing template caches will not automatically be purged. You will either need to assign the tag a new key, or clear your existing template caches manually using the Clear Caches tool in Settings. +If you change the template code within a `{% cache %}` that uses a custom key, any existing template caches will not automatically be purged. You will either need to assign the tag a new key, or clear your existing template caches manually using the Clear Caches tool in Utilities. ::: #### `for` @@ -149,7 +149,7 @@ Your caches will automatically clear when any elements (entries, assets, etc.) w If you have any element _queries_ within the tags (e.g. a `craft.entries`), and you create a new element that should be returned by one of the queries, Craft will also be able to figure that out and clear the cache. -You can also manually clear all of your template caches from the Settings page, using the “Clear Caches” tool. +You can also manually clear your caches from the Utilities page, using the “Clear Caches” tool, or by using the `./craft clear-caches` console command. ### When to use `{% cache %}` tags From c3d69296b0885dcf3aafb5d7a765acee70db832e Mon Sep 17 00:00:00 2001 From: Brad Bell Date: Sun, 26 Jul 2020 09:16:39 -0700 Subject: [PATCH 233/245] New translations tags.md (French) --- fr/dev/tags.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/fr/dev/tags.md b/fr/dev/tags.md index 95198d1aafc..38df2214609 100644 --- a/fr/dev/tags.md +++ b/fr/dev/tags.md @@ -82,7 +82,7 @@ You can combine this parameter with [globally](#globally) to cache templates on ::: ::: warning -If you change the template code within a `{% cache %}` that uses a custom key, any existing template caches will not automatically be purged. You will either need to assign the tag a new key, or clear your existing template caches manually using the Clear Caches tool in Settings. +If you change the template code within a `{% cache %}` that uses a custom key, any existing template caches will not automatically be purged. You will either need to assign the tag a new key, or clear your existing template caches manually using the Clear Caches tool in Utilities. ::: #### `for` @@ -149,7 +149,7 @@ Your caches will automatically clear when any elements (entries, assets, etc.) w If you have any element _queries_ within the tags (e.g. a `craft.entries`), and you create a new element that should be returned by one of the queries, Craft will also be able to figure that out and clear the cache. -You can also manually clear all of your template caches from the Settings page, using the “Clear Caches” tool. +You can also manually clear your caches from the Utilities page, using the “Clear Caches” tool, or by using the `./craft clear-caches` console command. ### When to use `{% cache %}` tags From 7d9ebcba4428db098158ad693e75fcb248dc8010 Mon Sep 17 00:00:00 2001 From: Brad Bell Date: Wed, 29 Jul 2020 06:34:37 -0700 Subject: [PATCH 234/245] New translations relations.md (Japanese) --- ja/relations.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/ja/relations.md b/ja/relations.md index fc8934e394a..2eebd8becb2 100644 --- a/ja/relations.md +++ b/ja/relations.md @@ -205,7 +205,7 @@ Or you might want to pass an element query to find other users’ favorite drink .section('drinks') .relatedTo([ 'and', - { sourcElement: otherUsers, field: 'favoriteDrinks' }, + { sourceElement: otherUsers, field: 'favoriteDrinks' }, { targetElement: drink.ingredients.one(), field: 'ingredients' } ]) .all() %} From 87f0d37b558294954f39da9e43dd92532fe83766 Mon Sep 17 00:00:00 2001 From: Brad Bell Date: Wed, 29 Jul 2020 06:34:39 -0700 Subject: [PATCH 235/245] New translations relations.md (French) --- fr/relations.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/fr/relations.md b/fr/relations.md index 020968b0ef5..7e7ab5d2010 100644 --- a/fr/relations.md +++ b/fr/relations.md @@ -205,7 +205,7 @@ Or you might want to pass an element query to find other users’ favorite drink .section('drinks') .relatedTo([ 'and', - { sourcElement: otherUsers, field: 'favoriteDrinks' }, + { sourceElement: otherUsers, field: 'favoriteDrinks' }, { targetElement: drink.ingredients.one(), field: 'ingredients' } ]) .all() %} From 5228e3b561f5d5cbec4c01712ff0e67384a70d36 Mon Sep 17 00:00:00 2001 From: Brad Bell Date: Wed, 29 Jul 2020 09:58:30 -0700 Subject: [PATCH 236/245] New translations headless.md (French) --- fr/dev/headless.md | 2 ++ 1 file changed, 2 insertions(+) diff --git a/fr/dev/headless.md b/fr/dev/headless.md index 738c4b2395b..d66545483f2 100644 --- a/fr/dev/headless.md +++ b/fr/dev/headless.md @@ -4,6 +4,8 @@ Craft’s templating system isn’t the only way to get your content out of Craf If you want to use Craft as a “headless” CMS, meaning it acts as a content API instead of (or in addition to) a regular website, there are a few ways you can go about it. +To see exactly what enabling Headless Mode does, see the [`headlessMode` config setting](../config/config-settings.md#headlessmode). + ::: tip Check out CraftQuest’s [Headless Craft CMS](https://craftquest.io/courses/headless-craft) course to learn more about using Craft as a headless CMS. ::: From a65c8eab00f2459946053b401789873a6cce040e Mon Sep 17 00:00:00 2001 From: Brad Bell Date: Wed, 29 Jul 2020 09:58:33 -0700 Subject: [PATCH 237/245] New translations headless.md (Japanese) --- ja/dev/headless.md | 12 +++++++----- 1 file changed, 7 insertions(+), 5 deletions(-) diff --git a/ja/dev/headless.md b/ja/dev/headless.md index ee12e54f379..04eda1cd7a9 100644 --- a/ja/dev/headless.md +++ b/ja/dev/headless.md @@ -4,22 +4,24 @@ Craft のテンプレートシステムは、Craft のコンテンツを取得 Craft を通常のウェブサイト（または、それに加える）の代わりにコンテンツ API として動作するという意味でのヘッドレス CMS として使用する場合、いくつかの方法があります。 +To see exactly what enabling Headless Mode does, see the [`headlessMode` config setting](../config/config-settings.md#headlessmode). + ::: tip -Craft をヘッドレス CMS として使用する方法について学ぶために、CraftQuest の [Headless Craft CMS](https://craftquest.io/courses/headless-craft) コースをチェックしてください。 +Check out CraftQuest’s [Headless Craft CMS](https://craftquest.io/courses/headless-craft) course to learn more about using Craft as a headless CMS. ::: ## GraphQL -Mark Huot 氏による [CraftQL](https://github.com/markhuot/craftql) プラグンは、設定なしの [GraphQL](https://graphql.org/) サーバーをインストールされた Craft に追加します。 +Craft comes with a built-in, self-generating [GraphQL API](../graphql.md). ## JSON API -ファーストパーティの [Element API](https://github.com/craftcms/element-api) は、コンテンツのための読み取り専用の [JSON API](http://jsonapi.org/) を作成する簡単な方法です。 +The first-party [Element API](https://github.com/craftcms/element-api) offers a simple way to create a read-only [JSON API](http://jsonapi.org/) for your content. ## REST API -Craft で REST API を作成する方法を詳しく知るために、Nate Iler 氏の Dot All 2017 のプレゼンテーション [How to Create a Full REST API](http://dotall.com/sessions/how-to-create-a-full-rest-api-with-craft-3) を見てください。 +Watch Nate Iler’s [How to Create a Full REST API](http://dotall.com/sessions/how-to-create-a-full-rest-api-with-craft-3) presentation from Dot All 2017 for an in-depth look at how to create a REST API with Craft. ## カスタムなもの -モジュールやプラグインは、新しい HTTP エンドポイントを提供するためのカスタムのフロントエンド[コントローラー](https://www.yiiframework.com/doc/guide/2.0/en/structure-controllers)を定義できます。 はじめるには、[Craft の拡張](../extend/README.md)を参照してください。 +Modules and plugins can define custom front-end [controllers](https://www.yiiframework.com/doc/guide/2.0/en/structure-controllers) that provide new HTTP endpoints. See [Extending Craft](../extend/README.md) to get started. From ab3fb971fb119cdf9db625168cbf9b848ce297d3 Mon Sep 17 00:00:00 2001 From: Brad Bell Date: Wed, 29 Jul 2020 09:58:52 -0700 Subject: [PATCH 238/245] New translations config-settings.md (French) --- fr/config/config-settings.md | 5 ++++- 1 file changed, 4 insertions(+), 1 deletion(-) diff --git a/fr/config/config-settings.md b/fr/config/config-settings.md index 1889f7b2708..f5fa08dfc6e 100644 --- a/fr/config/config-settings.md +++ b/fr/config/config-settings.md @@ -1211,7 +1211,7 @@ Since -Bool Whether the system should run in Headless Mode, which optimizes the system and control panel for headless CMS implementations. +Whether the system should run in Headless Mode, which optimizes the system and control panel for headless CMS implementations. When this is enabled, the following changes will take place: @@ -1222,6 +1222,9 @@ When this is enabled, the following changes will take place: - Twig will be configured to escape unsafe strings for JavaScript/JSON rather than HTML by default for front-end requests. - The , , , and settings will be ignored. +::: tip +When Headless Mode is enabled, users will not be able to set an initial password, set a new password, or verify their email address unless they have the "Access the control panel" permission. Make sure to grant this permission to content editors and administrators who should be able to log into the control panel. +::: ### `imageDriver` From 5c68490ac82145d0c666b6f30d9d6f77bd7c683b Mon Sep 17 00:00:00 2001 From: Brad Bell Date: Wed, 29 Jul 2020 09:58:54 -0700 Subject: [PATCH 239/245] New translations config-settings.md (Japanese) --- ja/config/config-settings.md | 7 +++++-- 1 file changed, 5 insertions(+), 2 deletions(-) diff --git a/ja/config/config-settings.md b/ja/config/config-settings.md index 31a5a133fea..08831d0839e 100644 --- a/ja/config/config-settings.md +++ b/ja/config/config-settings.md @@ -1211,7 +1211,7 @@ Since -Bool Whether the system should run in Headless Mode, which optimizes the system and control panel for headless CMS implementations. +Whether the system should run in Headless Mode, which optimizes the system and control panel for headless CMS implementations. When this is enabled, the following changes will take place: @@ -1219,9 +1219,12 @@ When this is enabled, the following changes will take place: - `{port}` -現在のデータベースポート - `{server}` - 現在のデータベースホスト名 - `{user}` -データベースのに接続するユーザー -- `{database}` - 現在のデータベース名 +- Twig will be configured to escape unsafe strings for JavaScript/JSON rather than HTML by default for front-end requests. - The , , , and settings will be ignored. +::: tip +When Headless Mode is enabled, users will not be able to set an initial password, set a new password, or verify their email address unless they have the "Access the control panel" permission. Make sure to grant this permission to content editors and administrators who should be able to log into the control panel. +::: ### `imageDriver` From b43be9f198b27d9dcd0b34ed06ff761a76c9540c Mon Sep 17 00:00:00 2001 From: Brad Bell Date: Fri, 31 Jul 2020 13:42:45 -0700 Subject: [PATCH 240/245] New translations category-queries.md (Japanese) --- ja/dev/element-queries/category-queries.md | 12 ++++++------ 1 file changed, 6 insertions(+), 6 deletions(-) diff --git a/ja/dev/element-queries/category-queries.md b/ja/dev/element-queries/category-queries.md index 1cf1be8e518..df9db5acbe4 100644 --- a/ja/dev/element-queries/category-queries.md +++ b/ja/dev/element-queries/category-queries.md @@ -524,12 +524,12 @@ Narrows the query results based on the categories’ IDs. Possible values include: -| 値 | 取得するカテゴリ | -| --------------- | ------------------------- | -| `1` | with an ID of 1. | -| `'not 1'` | not with an ID of 1. | -| `[1, 2]` | with an ID of 1 or 2. | -| `['not', 1, 2]` | not with an ID of 1 or 2. | +| 値 | 取得するカテゴリ | +| ------------------ | ---------------------------- | +| `1` | with an ID of 1. | +| `'not 1'` | not with an ID of 1. | +| `[1, 2]` | with an ID of 1 or 2. | +| `['not, 1, 2, 7']` | not with an ID of 1, 2 or 7. | From 8d6293239d009cad9b4bbc1ac3a87d93e10594e1 Mon Sep 17 00:00:00 2001 From: Brad Bell Date: Fri, 31 Jul 2020 13:42:50 -0700 Subject: [PATCH 241/245] New translations category-queries.md (French) --- fr/dev/element-queries/category-queries.md | 12 ++++++------ 1 file changed, 6 insertions(+), 6 deletions(-) diff --git a/fr/dev/element-queries/category-queries.md b/fr/dev/element-queries/category-queries.md index 5c569862c86..5eb8feab1e8 100644 --- a/fr/dev/element-queries/category-queries.md +++ b/fr/dev/element-queries/category-queries.md @@ -524,12 +524,12 @@ Narrows the query results based on the categories’ IDs. Possible values include: -| Value | Fetches categories… | -| --------------- | ------------------------- | -| `1` | with an ID of 1. | -| `'not 1'` | not with an ID of 1. | -| `[1, 2]` | with an ID of 1 or 2. | -| `['not', 1, 2]` | not with an ID of 1 or 2. | +| Value | Fetches categories… | +| ------------------ | ---------------------------- | +| `1` | with an ID of 1. | +| `'not 1'` | not with an ID of 1. | +| `[1, 2]` | with an ID of 1 or 2. | +| `['not, 1, 2, 7']` | not with an ID of 1, 2 or 7. | From cb4b7ac4e9e2a95daffdfd753f2f7b60dbfdfd0c Mon Sep 17 00:00:00 2001 From: Brad Bell Date: Fri, 31 Jul 2020 13:48:16 -0700 Subject: [PATCH 242/245] New translations category-queries.md (Japanese) --- ja/dev/element-queries/category-queries.md | 13 ++++++------- 1 file changed, 6 insertions(+), 7 deletions(-) diff --git a/ja/dev/element-queries/category-queries.md b/ja/dev/element-queries/category-queries.md index df9db5acbe4..0082af71995 100644 --- a/ja/dev/element-queries/category-queries.md +++ b/ja/dev/element-queries/category-queries.md @@ -524,13 +524,12 @@ Narrows the query results based on the categories’ IDs. Possible values include: -| 値 | 取得するカテゴリ | -| ------------------ | ---------------------------- | -| `1` | with an ID of 1. | -| `'not 1'` | not with an ID of 1. | -| `[1, 2]` | with an ID of 1 or 2. | -| `['not, 1, 2, 7']` | not with an ID of 1, 2 or 7. | - +| 値 | 取得するカテゴリ | +| --------------- | ------------------------- | +| `1` | with an ID of 1. | +| `'not 1'` | not with an ID of 1. | +| `[1, 2]` | with an ID of 1 or 2. | +| `['not', 1, 2]` | not with an ID of 1 or 2. | ::: code From 0b0d68ebd616fca4f157ea0c7d272e28c302995b Mon Sep 17 00:00:00 2001 From: Brad Bell Date: Fri, 31 Jul 2020 13:48:18 -0700 Subject: [PATCH 243/245] New translations category-queries.md (French) --- fr/dev/element-queries/category-queries.md | 13 ++++++------- 1 file changed, 6 insertions(+), 7 deletions(-) diff --git a/fr/dev/element-queries/category-queries.md b/fr/dev/element-queries/category-queries.md index 5eb8feab1e8..a244c460c94 100644 --- a/fr/dev/element-queries/category-queries.md +++ b/fr/dev/element-queries/category-queries.md @@ -524,13 +524,12 @@ Narrows the query results based on the categories’ IDs. Possible values include: -| Value | Fetches categories… | -| ------------------ | ---------------------------- | -| `1` | with an ID of 1. | -| `'not 1'` | not with an ID of 1. | -| `[1, 2]` | with an ID of 1 or 2. | -| `['not, 1, 2, 7']` | not with an ID of 1, 2 or 7. | - +| Value | Fetches categories… | +| --------------- | ------------------------- | +| `1` | with an ID of 1. | +| `'not 1'` | not with an ID of 1. | +| `[1, 2]` | with an ID of 1 or 2. | +| `['not', 1, 2]` | not with an ID of 1 or 2. | ::: code From f2e8c742407626b9e2c285e15d7a9587f47145fa Mon Sep 17 00:00:00 2001 From: Brad Bell Date: Mon, 3 Aug 2020 07:22:40 -0700 Subject: [PATCH 244/245] New translations assets-fields.md (Japanese) --- ja/assets-fields.md | 5 +++-- 1 file changed, 3 insertions(+), 2 deletions(-) diff --git a/ja/assets-fields.md b/ja/assets-fields.md index 2d6830526db..9f003f7d186 100644 --- a/ja/assets-fields.md +++ b/ja/assets-fields.md @@ -209,10 +209,11 @@ Assets fields can handle new file uploads as well: Don’t forget to set `enctype="multipart/form-data"` on your `
    ` tag so your browser knows to submit the form as a multipart request. ::: -Alternatively, you can submit Base64-encoded file data, which the Assets field will decode and treat as an uploaded file: +Alternatively, you can submit Base64-encoded file data, which the Assets field will decode and treat as an uploaded file. To do that, you have to specify both the data and the filename like this: ```twig -{{ hiddenInput('fields[][]', 'data:image/jpeg;base64,') }} +{{ hiddenInput('fields[][data][]', 'data:image/jpeg;base64,') }} +{{ hiddenInput('fields[][filename][]', 'myFile.ext') }} ``` ## 関連項目 From 32698ab71c3b3620e15e25985ba1f527a5263fdd Mon Sep 17 00:00:00 2001 From: Brad Bell Date: Mon, 3 Aug 2020 07:23:00 -0700 Subject: [PATCH 245/245] New translations assets-fields.md (French) --- fr/assets-fields.md | 5 +++-- 1 file changed, 3 insertions(+), 2 deletions(-) diff --git a/fr/assets-fields.md b/fr/assets-fields.md index a019a6f2ba8..32216cbac56 100644 --- a/fr/assets-fields.md +++ b/fr/assets-fields.md @@ -209,10 +209,11 @@ Assets fields can handle new file uploads as well: Don’t forget to set `enctype="multipart/form-data"` on your `` tag so your browser knows to submit the form as a multipart request. ::: -Alternatively, you can submit Base64-encoded file data, which the Assets field will decode and treat as an uploaded file: +Alternatively, you can submit Base64-encoded file data, which the Assets field will decode and treat as an uploaded file. To do that, you have to specify both the data and the filename like this: ```twig -{{ hiddenInput('fields[][]', 'data:image/jpeg;base64,') }} +{{ hiddenInput('fields[][data][]', 'data:image/jpeg;base64,') }} +{{ hiddenInput('fields[][filename][]', 'myFile.ext') }} ``` ## See Also