From 07328cf9f0dde51107916a4b4a3b5b922c4b48c5 Mon Sep 17 00:00:00 2001 From: "Nathan J. Brauer" Date: Tue, 2 Apr 2024 13:21:37 -0700 Subject: [PATCH] DOC Updated documentation for new DataObject initialisation task --- docs/en/migrating-from-single-language.md | 147 +++++++++++++++++----- 1 file changed, 119 insertions(+), 28 deletions(-) diff --git a/docs/en/migrating-from-single-language.md b/docs/en/migrating-from-single-language.md index 6fce063c..5137e43d 100644 --- a/docs/en/migrating-from-single-language.md +++ b/docs/en/migrating-from-single-language.md @@ -4,12 +4,14 @@ In case you want to add fluent to an existing site to add multi language functio ## Install fluent -use composer to install fluent, see [installation](installation.md) +Use composer to install fluent, see [installation](installation.md) ## Configure fluent -* add locales -You can either do this in the backend, or for the first setup you can utitlise `default_records` to add the locales to the db. +* Add locales + +You can either do this in the backend, or for the first setup you can utitlise `default_records` to add the locales to +the db. A fluent.yml might look like: ``` @@ -33,32 +35,121 @@ TractorCow\Fluent\Model\Locale: When you run `dev/build?flush` again, this adds the records to the database if the locales table is still empty. -## Publish available pages in your default locale +## Populating initial localised content for existing Pages and DataObjects in your default locale -Now your site is broken, cause no pages have been published and added as translated page in your default locale. -You can either publish all pages manually or use [publishall](https://docs.silverstripe.org/en/4/developer_guides/debugging/url_variable_tools/#building-and-publishing-urls) to publish all pages in bulk. -If you run `/admin/pages/publishall` in your browser your site will be fixed again and you can start adding translated content. +Now your site is broken because nothing has been published and added as translated data in your default locale. You can +either manually localise all DataObjects & Pages manually or use one of the automation options below. ### Automated tools for localisation -`InitialPageLocalisation` dev task can be used to either only localise or localise & publish your pages. -This dev task can be run either via CLI or queued as a job if Queued jobs module is installed. - -Localise only example - -``` -dev/tasks/initial-page-localisation-task -``` - -Localise & publish example - -``` -dev/tasks/initial-page-localisation-task publish=1 -``` - -Localisation in batches can be done by using the `limit` option. -Example below will localise & publish five pages on each run. - -``` -dev/tasks/initial-page-localisation-task publish=1&limit=5 -``` +#### From the CMS (SiteTree only) + +Use Silverstripe's +built-in [publishall](https://docs.silverstripe.org/en/4/developer_guides/debugging/url_variable_tools/#building-and-publishing-urls) +tool to publish all Pages in bulk. +Run `/admin/pages/publishall` in your browser and your site will be fixed again and you can start adding translated +content. + +_This method will work with Pages only (not localised DataObjects)._ + +#### Commandline or Queued Jobs (SiteTree and DataObjects) + +The `InitialPageLocalisation` and `InitialDataObjectLocalisationTask` dev tasks may be used to localise and, optionally, +publish your `Versioned` data (including Pages) from the commandline or queued as a job (if the Queued Jobs module is installed). + +`InitialPageLocalisation` - localise all `SiteTree` objects (Pages) + +`InitialDataObjectLocalisationTask` - localise all Fluent-enabled DataObjects (excluding `SiteTree`) + +1. Example: Localise all Pages (default, without publishing) + + ``` + dev/tasks/initial-page-localisation-task + ``` + +2. Example: Localise & publish all Pages + + ``` + dev/tasks/initial-page-localisation-task publish=1 + ``` + +3. Example: Localising Pages in batches can be done by using the `limit` option. + This will localise & publish five pages on each run. + + ``` + dev/tasks/initial-page-localisation-task publish=1&limit=5 + ``` + +4. Example: All the same functionality is available for localising all DataObjects, including `Versioned` and non-Versioned classes + + ``` + dev/tasks/initial-dataobject-localisation-task + ``` + or + + ``` + dev/tasks/initial-dataobject-localisation-task publish=1&limit=5 + ``` + +#### Customize your own initialisation dev task + +Perhaps you want to be more selective in how you initialise your localised content. +The `InitialDataObjectLocalisationTask` class can be easily extended to either list exactly which classes you want to +initially localise, or you can exclude specific classes from initialisation. + +1. **Initialise specific classes:** The following example will create a task which localises **_ONLY_** `BlogPost` +pages, `Testimonial` objects, _and their subclasses (if any)_. + + ```php + class CustomLocalisationTask extends InitialDataObjectLocalisationTask + { + /** + * @var string + */ + private static $segment = 'custom-localisation-initialisation-task'; + + /** + * @var string + */ + protected $title = 'Custom localisation initialisation'; + + /** + * @var string[] + */ + protected array $include_only_classes = [ + \SilverStripe\Blog\Model\BlogPost::class, + \AcmeCo\Model\Testimonial::class + ]; + + } + ``` + +2. **Initialise all DataObjects but exclude some:** The following example will create a task which localises **_ALL_** +DataObjects **_except_** `BlogPost` pages, `Testimonial` objects, _and their subclasses (if any)_. + + ```php + class CustomLocalisationTask extends InitialDataObjectLocalisationTask + { + /** + * @var string + */ + private static $segment = 'custom-localisation-initialisation-task'; + + /** + * @var string + */ + protected $title = 'Custom localisation initialisation'; + + /** + * @var string[] + */ + protected array $exclude_classes = [ + \SilverStripe\Blog\Model\BlogPost::class, + \AcmeCo\Model\Testimonial::class + ]; + + } + ``` + +3. **One or the other:** You may specify `$include_only_classes` OR `$exclude_classes` - not both. +If `$include_only_classes` is not an empty array, `$exclude_classes` will be ignored.