diff --git a/CHANGELOG.md b/CHANGELOG.md index 38d232b..2b74ec6 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -4,6 +4,10 @@ All notable changes to this project will be documented in this file. The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/), and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html). +## 2.0.0 - 2022-08-08 +### Added +- Initial Craft 4 release + ## 1.4.0 - 2022-08-08 ### Added - Added support for craft-twigfield ([#81](https://github.com/besteadfast/craft-preparse-field/pull/81) - thanks @khalwat) diff --git a/README.md b/README.md index 5d6cd40..8fa1deb 100644 --- a/README.md +++ b/README.md @@ -4,83 +4,76 @@ A fieldtype that parses Twig when an element is saved and saves the result as pl ## Requirements -This plugin requires Craft CMS 3.2.0 or later. - -_The Craft 2 version can be found in the [craft2](https://github.com/besteadfast/craft-preparse-field/tree/craft2) branch_ +This plugin requires Craft CMS 4.0.0 or later and PHP 8.0.2 or later. ## Installation To install the plugin, follow these instructions. -1. Open your terminal and go to your Craft project: +1. Open your terminal and go to your Craft project: cd /path/to/project -2. Then tell Composer to load the plugin: +2. Then tell Composer to load the plugin: composer require besteadfast/craft-preparse-field -3. In the Control Panel, go to Settings → Plugins and click the “Install” button for Preparse Field. +3. In the Control Panel, go to Settings → Plugins and click the “Install” button for Preparse Field. ## Usage -When creating a new Preparse field, you can add the Twig that you want to run to the fields settings. When an element with a preparse field is saved, the code will be parsed. The element itself is available as `element` in twig. +When creating a new Preparse field, you add the Twig that you want run to the field's settings. When an element with that Preparse field is saved, the code will be parsed and the resulting value saved as plain text. + +It's worth noting that the Preparse field is only updated when the element the field is on is saved. If you grab data from a related element (like in the category title example below), and then update the related element, the preparsed value will not automatically be updated. -**Usage in Matrix** -When a Preparse field is added to a Matrix block, that block will be available to the Twig code as the variable `element`. The element that the Matrix field belongs to will be available under `element.owner`. +In the Twig, the element that the Preparse field is added to is available as a variable named `element`. It's best to use this variable (as opposed to something like `entry` or `asset`) because it's possible you add the same Preparse field to multiple element types. This also means that when a Preparse field is added to a Matrix, SuperTable, or Neo block, that block will be what is available as `element`, so if you want to access the element that the Matrix/SuperTable/Neo field belongs to, you will want to use `element.owner`. ### Examples -If you have a category field in your entry named `entryCategory`, you can save the category title to the preparse field by adding the following Twig to the field settings: +If you have a category field on your element named `relatedCategory`, you can save the category title to the Preparse field by adding the following Twig to the field settings: - {{ element.entryCategory | length ? element.entryCategory.first().title }} + {{ element.relatedCategory.one().title ?? '' }} -This is useful for saving preparsed values to a field for use with sorting, searching or similar things. +This is useful for saving preparsed values to a field for use with sorting, searching, or similar things. -You can also do more advanced stuff, for instance for performance optimizing. Let's say you have three different asset fields that may or may not be populated. having to check these in the template may require a bunch of queries since you can't check if a field has a relation in Craft, without actually querying for it. You could do something like this to get the id of the asset to use: +You can also do more advanced stuff, for instance performance optimizing. Let's say you have three different asset fields that may or may not be populated. Having to check these in the template may require a bunch of queries since you can't check if a field has a relation in Craft without actually querying for it. You could do something like this to get the id of the asset to use: {% if element.smallListImage | length %} - {{ element.smallListImage.first().id }} + {{ element.smallListImage.one().id }} {% elseif element.largeListImage | length %} - {{ element.largeListImage.first().id }} + {{ element.largeListImage.one().id }} {% elseif element.mainImage | length %} - {{ element.mainImage.first().id }} - {% endif %} - -You'd probably want to wrap that in `{% spaceless %} ... {% endspaceless %}` to make it more useful. - -Or you could just use it to do some bulk work when saving, like pre-generating a bunch of image transforms with [Imager](https://github.com/aelvan/Imager-Craft): - - {% if element.image | length %} - {% set transformedImages = craft.imager.transformImage(element.image.first(), [ - { width: 1000 }, - { width: 900 }, - { width: 800 }, - { width: 700 }, - { width: 600 }, - { width: 500 }, - { width: 400 }, - { width: 300 }, - { width: 200 }, - { width: 100 } - ]) %} + {{ element.mainImage.one().id }} {% endif %} -The template path is set to your site template path, so you can even include whole templates if you want to do more advanced stuff and/or want to keep your fields Twig in version control: -{% include '_fields/myFieldInclude' %} -Make sure that you always write solid Twig, taking into account that fields may not be populated yet. If an error occurs in your Twig, the element will not be saved. - -## Cache gotchas +_You'd probably want to wrap that in `{% apply spaceless %} ... {% endapply %}` to make it more useful..._ + +Or you could just use it to do some bulk work when saving, like pre-generating a bunch of image transforms with [Imager X](https://plugins.craftcms.com/imager-x?craft4): + + {% if element.mainImage | length %} + {% set transformedImages = craft.imager.transformImage(element.mainImage.one(), [ + { width: 1000 }, + { width: 900 }, + { width: 800 }, + { width: 700 }, + { width: 600 }, + { width: 500 }, + { width: 400 }, + { width: 300 }, + { width: 200 }, + { width: 100 } + ]) %} + {% endif %} -The preparse field is only updated when an element is saved. If you grab data from a related element (like in the category title example above), and then update the related element, the preparsed value will not automatically be updated. +Preparse also has access to your site's template root, so you can even include local templates if you want to do more advanced stuff and/or want to keep your field's Twig in version control: -## Locales gotchas + {% include '_partials/customPreparseFieldStuff' %} -The preparse field is made to work with localized sites, but there is one gotcha. It is important that the fields that you process, and the preparse field itself, has the same locales setup. If the target field is set up to be localized to two different languages, and your preparse field is not, the value will be updated to the target field value in the language that was saved last. If your target field is not localized, but you localize your preparse field, you will need to save the entry in both languages if you change the target field. +Make sure that you always write solid Twig, taking into account that fields may not be populated yet. If an error occurs in your Twig, the element will not be saved. [Code defensively!](https://nystudio107.com/blog/handling-errors-gracefully-in-craft-cms#defensive-coding-in-twig) -## Price, license and support +## Price, License, and Support -The plugin is released under the MIT license, meaning you can do whatever you want with it as long as you don't blame us. **It's free**, which means there is absolutely no support included, but you might get it anyway. Just post an issue here on github if you have one, and we'll see what we can do. :) +The plugin is released under the MIT license, meaning you can do whatever you want with it as long as you don't blame us. **It's free**, which means there is absolutely no support included, but you might get it anyway. Just post an issue here on GitHub if you have one, and we'll see what we can do. :) ## Changelog diff --git a/composer.json b/composer.json index 4b41c90..9d529a9 100644 --- a/composer.json +++ b/composer.json @@ -2,7 +2,7 @@ "name": "besteadfast/craft-preparse-field", "description": "A fieldtype that parses Twig when an element is saved and saves the result as plain text.", "type": "craft-plugin", - "version": "1.4.0", + "version": "2.0.0", "keywords": [ "craft", "cms", @@ -28,13 +28,13 @@ } ], "require": { - "craftcms/cms": "^3.2.0", - "nystudio107/craft-twigfield": "^1.0.0" + "craftcms/cms": "^4.0.0", + "nystudio107/craft-twigfield": "^1.0.0", + "php": "^8.0.2" }, "autoload": { "psr-4": { - "besteadfast\\preparsefield\\": "src/", - "aelvan\\preparsefield\\": "src_legacy/" + "besteadfast\\preparsefield\\": "src/" } }, "extra": { diff --git a/src/PreparseField.php b/src/PreparseField.php index dd4a434..1121a58 100644 --- a/src/PreparseField.php +++ b/src/PreparseField.php @@ -1,6 +1,6 @@ true]); } - catch(\Exception $e) + catch(Exception $e) { Craft::error($e->getMessage()); } @@ -197,7 +196,7 @@ public static function log($msg, $level = 'notice', $file = 'Preparse') * @param string $level * @param string $file */ - public static function error($msg, $level = 'error', $file = 'RecurringOrders') + public static function error($msg, string $level = 'error', string $file = 'Preparse') { static::log($msg, $level, $file); } diff --git a/src/fields/PreparseFieldType.php b/src/fields/PreparseFieldType.php index 502d5c5..50e6ddb 100644 --- a/src/fields/PreparseFieldType.php +++ b/src/fields/PreparseFieldType.php @@ -1,6 +1,6 @@ columnType === Schema::TYPE_DECIMAL) { return Db::getNumericalColumnType(null, null, $this->decimals); @@ -111,9 +113,9 @@ public function getContentColumnType(): string * @return null|string * @throws LoaderError * @throws RuntimeError - * @throws SyntaxError + * @throws SyntaxError|Exception */ - public function getSettingsHtml() + public function getSettingsHtml(): ?string { $columns = [ Schema::TYPE_TEXT => Craft::t('preparse-field', 'Text (stores about 64K)'), @@ -149,9 +151,9 @@ public function getSettingsHtml() * @return string * @throws LoaderError * @throws RuntimeError - * @throws SyntaxError + * @throws SyntaxError|Exception */ - public function getInputHtml($value, ElementInterface $element = null): string + public function getInputHtml(mixed $value, ?ElementInterface $element = null): string { // Get our id and namespace $id = Craft::$app->getView()->formatInputId($this->handle); @@ -178,7 +180,7 @@ public function getInputHtml($value, ElementInterface $element = null): string /** * @inheritdoc */ - public function getSearchKeywords($value, ElementInterface $element): string + public function getSearchKeywords(mixed $value, ElementInterface $element): string { if ($this->columnType === Schema::TYPE_DATETIME) { return ''; @@ -188,8 +190,9 @@ public function getSearchKeywords($value, ElementInterface $element): string /** * @inheritdoc - */ - public function getTableAttributeHtml($value, ElementInterface $element): string + * @throws InvalidConfigException + */ + public function getTableAttributeHtml(mixed $value, ElementInterface $element): string { if (!$value) { return ''; @@ -202,10 +205,11 @@ public function getTableAttributeHtml($value, ElementInterface $element): string return parent::getTableAttributeHtml($value, $element); } - /** - * @inheritdoc - */ - public function normalizeValue($value, ElementInterface $element = null) + /** + * @inheritdoc + * @throws \Exception + */ + public function normalizeValue(mixed $value, ?ElementInterface $element = null): mixed { if ($this->columnType === Schema::TYPE_DATETIME) { if ($value && ($date = DateTimeHelper::toDateTime($value)) !== false) { @@ -219,22 +223,21 @@ public function normalizeValue($value, ElementInterface $element = null) /** * @inheritdoc */ - public function modifyElementsQuery(ElementQueryInterface $query, $value) + public function modifyElementsQuery(ElementQueryInterface $query, mixed $value): void { if ($this->columnType === Schema::TYPE_DATETIME) { if ($value !== null) { /** @var ElementQuery $query */ $query->subQuery->andWhere(Db::parseDateParam('content.' . Craft::$app->getContent()->fieldColumnPrefix . $this->handle, $value)); } - return null; } - return parent::modifyElementsQuery($query, $value); + parent::modifyElementsQuery($query, $value); } /** * @inheritdoc */ - public function getContentGqlType() + public function getContentGqlType(): Type|array { if ($this->columnType === Schema::TYPE_DATETIME) { return DateTimeType::getType(); @@ -242,5 +245,3 @@ public function getContentGqlType() return parent::getContentGqlType(); } } - -class_alias(PreparseFieldType::class, \aelvan\preparsefield\fields\PreparseFieldType::class); diff --git a/src/services/PreparseFieldService.php b/src/services/PreparseFieldService.php index e73eca9..e10be0f 100644 --- a/src/services/PreparseFieldService.php +++ b/src/services/PreparseFieldService.php @@ -1,6 +1,6 @@ getFieldLayout(); if ($fieldLayout) { - foreach ($fieldLayout->getFields() as $field) { - if ($field && $field instanceof PreparseFieldType) { + foreach ($fieldLayout->getCustomFields() as $field) { + if ($field instanceof PreparseFieldType) { /** @var PreparseFieldType $field */ // only get field content for the right event listener @@ -76,11 +76,11 @@ public function getPreparseFieldsContent(Element $element, string $eventHandle): * @param PreparseFieldType $field * @param Element $element * - * @return null|string + * @return null|string|DateTime * @throws Exception */ - public function parseField(PreparseFieldType $field, Element $element) - { + public function parseField(PreparseFieldType $field, Element $element): DateTime|string|null + { $fieldTwig = $field->fieldTwig; $columnType = $field->columnType; $decimals = $field->decimals; @@ -137,22 +137,21 @@ public function parseField(PreparseFieldType $field, Element $element) return $fieldValue; } - /** - * Checks to see if an element has a preparse field that should be saved on move - * - * @param $element - * - * @return bool - */ + /** + * Checks to see if an element has a preparse field that should be saved on move + * + * @param Element $element + * + * @return bool + */ public function shouldParseElementOnMove(Element $element): bool { $fieldLayout = $element->getFieldLayout(); if ($fieldLayout) { - foreach ($fieldLayout->getFields() as $field) { - if ($field && $field instanceof PreparseFieldType) { - /** @var PreparseFieldType $field */ - $parseOnMove = $field->parseOnMove; + foreach ($fieldLayout->getCustomFields() as $field) { + if ($field instanceof PreparseFieldType) { + $parseOnMove = $field->parseOnMove; if ($parseOnMove) { return true; diff --git a/src/templates/_components/fields/_input.twig b/src/templates/_components/fields/_input.twig index 9a25c32..0b31a99 100644 --- a/src/templates/_components/fields/_input.twig +++ b/src/templates/_components/fields/_input.twig @@ -1,6 +1,6 @@ {# /** - * Preparse Field plugin for Craft CMS 3.x + * Preparse Field plugin for Craft CMS 4.x * * Field Input * diff --git a/src/templates/_components/fields/_settings.twig b/src/templates/_components/fields/_settings.twig index dbfd1fe..65a2268 100644 --- a/src/templates/_components/fields/_settings.twig +++ b/src/templates/_components/fields/_settings.twig @@ -1,6 +1,6 @@ {# /** - * Preparse Field plugin for Craft CMS + * Preparse Field plugin for Craft CMS 4.x * * Field Settings * diff --git a/src_legacy/fields/PreparseFieldType.php b/src_legacy/fields/PreparseFieldType.php deleted file mode 100644 index eabd808..0000000 --- a/src_legacy/fields/PreparseFieldType.php +++ /dev/null @@ -1,3 +0,0 @@ -