From b234c56aaba7a97d9b46d677fdef4b1dd2ddd59d Mon Sep 17 00:00:00 2001 From: Josh Crawford Date: Mon, 20 May 2024 00:07:40 +1000 Subject: [PATCH] version 4.0.0 --- CHANGELOG.md | 13 +- composer.json | 6 +- config.codekit3 | 8 + docs/.sidebar.json | 29 +- docs/feature-tour/layouts.md | 7 - docs/get-started/installation-setup.md | 18 - docs/get-started/introduction.md | 4 + docs/get-started/requirements.md | 7 - docs/get-started/upgrading-from-v2.md | 21 - .../super-table-block-queries.md | 489 ------------------ docs/template-guides/available-variables.md | 23 - docs/template-guides/block-querying.md | 36 -- docs/template-guides/front-end-form.md | 47 -- docs/template-guides/php-example.md | 89 ---- docs/template-guides/rendering-content.md | 28 - 15 files changed, 19 insertions(+), 806 deletions(-) delete mode 100644 docs/feature-tour/layouts.md delete mode 100644 docs/get-started/installation-setup.md create mode 100644 docs/get-started/introduction.md delete mode 100644 docs/get-started/requirements.md delete mode 100644 docs/get-started/upgrading-from-v2.md delete mode 100644 docs/getting-elements/super-table-block-queries.md delete mode 100644 docs/template-guides/available-variables.md delete mode 100644 docs/template-guides/block-querying.md delete mode 100644 docs/template-guides/front-end-form.md delete mode 100644 docs/template-guides/php-example.md delete mode 100644 docs/template-guides/rendering-content.md diff --git a/CHANGELOG.md b/CHANGELOG.md index e0b4d4b..05e2006 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -1,21 +1,14 @@ # Changelog -## 4.0.0-beta.3 - 2024-04-12 +## 4.0.0 - 2024-05-20 +> {note} Super Table has now reached its end-of-life. Read more in the [announcement](https://verbb.io/blog/so-long-super-table). ### Added -- Add support for `Fields::EVENT_DEFINE_COMPATIBLE_FIELD_TYPES` when converting to Matrix, to remove warning about changing Super Table to Matrix fields. - Add `super-table/migrate` console command to convert Super Table fields to Matrix fields. -## 4.0.0-beta.2 - 2024-04-03 - -### Fixed -- Fix some Craft 5 migration issues. (thanks @brandonkelly). - -## 4.0.0-beta.1 - 2024-03-04 - ### Changed - Now requires PHP `8.2.0+`. -- Now requires Craft `5.0.0-beta.1+`. +- Now requires Craft `5.0.0+`. ## 3.0.12 - 2023-10-05 diff --git a/composer.json b/composer.json index 3717508..0f29891 100644 --- a/composer.json +++ b/composer.json @@ -2,7 +2,7 @@ "name": "verbb/super-table", "description": "Super-charge your content builders and create nested Matrix fields.", "type": "craft-plugin", - "version": "4.0.0-beta.3", + "version": "4.0.0", "keywords": [ "craft", "cms", @@ -26,8 +26,8 @@ ], "require": { "php": "^8.2", - "craftcms/cms": "^5.0.0-beta.1", - "verbb/base": "^3.0.0-beta.1" + "craftcms/cms": "^5.0.0", + "verbb/base": "^3.0.0" }, "autoload": { "psr-4": { diff --git a/config.codekit3 b/config.codekit3 index 742e8c1..b5b505d 100644 --- a/config.codekit3 +++ b/config.codekit3 @@ -162,6 +162,14 @@ "oAP" : "\/src\/SuperTable.php", "oF" : 0 }, + "\/src\/translations\/en\/super-table.php" : { + "cB" : 0, + "ft" : 8192, + "hM" : 0, + "oA" : 2, + "oAP" : "\/src\/translations\/en\/super-table.php", + "oF" : 0 + }, "\/src\/variables" : { "ft" : 65536, "oA" : 1, diff --git a/docs/.sidebar.json b/docs/.sidebar.json index ba0efaf..a24cc4d 100644 --- a/docs/.sidebar.json +++ b/docs/.sidebar.json @@ -3,34 +3,7 @@ "title": "Get Started", "collapsable": false, "children": [ - "get-started/installation-setup", - "get-started/requirements", - "get-started/upgrading-from-v2" - ] - }, - { - "title": "Feature Tour", - "collapsable": false, - "children": [ - "feature-tour/layouts" - ] - }, - { - "title": "Template Guides", - "collapsable": false, - "children": [ - "template-guides/available-variables", - "template-guides/rendering-content", - "template-guides/block-querying", - "template-guides/front-end-form", - "template-guides/php-example" - ] - }, - { - "title": "Getting Elements", - "collapsable": false, - "children": [ - "getting-elements/super-table-block-queries" + "get-started/introduction" ] } ] diff --git a/docs/feature-tour/layouts.md b/docs/feature-tour/layouts.md deleted file mode 100644 index 58a1d44..0000000 --- a/docs/feature-tour/layouts.md +++ /dev/null @@ -1,7 +0,0 @@ -# Layouts -For any Super Table, you can choose between 3 layout options - Row, Table and Matrix. This is an option when creating your Super Table field. The Table layout will present fields vertically and in a tabular format - exactly as you'd expect from a Table field. Row on the other hand will present fields horizontally, similar to how a Matrix field works. The Matrix - self-explanatory, shows fields in a Matrix-like layout. - -Which layout you choose will likely depend on what sort of fields you have in your Super Table, and the number of fields. For a Super Table containing 4 or more fields, your best option is to use the Row Layout. - -## Static option -A Super Table field can be set to be static, which turns the field into a non-repeatable collection of fields. This can be useful for a multitude of cases where you wish to simply group a collection of fields together, and not necessarily have them repeatable. diff --git a/docs/get-started/installation-setup.md b/docs/get-started/installation-setup.md deleted file mode 100644 index cc7924e..0000000 --- a/docs/get-started/installation-setup.md +++ /dev/null @@ -1,18 +0,0 @@ -# Installation & Setup -You can install Super Table via the plugin store, or through Composer. - -## Craft Plugin Store -To install **Super Table**, navigate to the _Plugin Store_ section of your Craft control panel, search for `Super Table`, and click the _Install_ button. - -## Composer -You can also add the package to your project using Composer and the command line. - -1. Open your terminal and go to your Craft project: -```shell -cd /path/to/project -``` - -2. Then tell Composer to require the plugin, and Craft to install it: -```shell -composer require verbb/super-table && php craft plugin/install super-table -``` diff --git a/docs/get-started/introduction.md b/docs/get-started/introduction.md new file mode 100644 index 0000000..e683fec --- /dev/null +++ b/docs/get-started/introduction.md @@ -0,0 +1,4 @@ +# Introduction +Super Table has been [retired](https://verbb.io/blog/so-long-super-table) for Craft 5. Any existing installs of Super Table on Craft 4 will be migrated to Matrix when upgraded to Craft 5. + +Read the [blog post](https://verbb.io/blog/so-long-super-table) for further detail. \ No newline at end of file diff --git a/docs/get-started/requirements.md b/docs/get-started/requirements.md deleted file mode 100644 index 2eaabcb..0000000 --- a/docs/get-started/requirements.md +++ /dev/null @@ -1,7 +0,0 @@ -# Requirements - -## Craft CMS -Super Table requires Craft CMS 5.0 or greater. - -## PHP -Super Table requires PHP 8.2 or greater. diff --git a/docs/get-started/upgrading-from-v2.md b/docs/get-started/upgrading-from-v2.md deleted file mode 100644 index a088e3c..0000000 --- a/docs/get-started/upgrading-from-v2.md +++ /dev/null @@ -1,21 +0,0 @@ -# Upgrading from v2 -While the [changelog](https://github.com/verbb/super-table/blob/craft-5/CHANGELOG.md) is the most comprehensive list of changes, this guide provides high-level overview and organizes changes by category. - -## Renamed Classes -The following classes have been renamed. - -Old | What to do instead ---- | --- -| `verbb\supertable\models\SuperTableBlockTypeModel` | `verbb\supertable\models\SuperTableBlockType` -| `verbb\supertable\record\SuperTableBlockRecord` | `verbb\supertable\record\SuperTableBlock` -| `verbb\supertable\record\SuperTableBlockTypeRecord` | `verbb\supertable\record\SuperTableBlockType` -| `verbb\supertable\services\SuperTableService` | `verbb\supertable\services\Service` - -## Query Params -Some element query params have been removed: - -Old Param | What to do instead ---- | --- -| `ownerLocale` | `site` or `siteId` -| `ownerSite` | `site` -| `ownerSiteId` | `siteId` diff --git a/docs/getting-elements/super-table-block-queries.md b/docs/getting-elements/super-table-block-queries.md deleted file mode 100644 index b5c7fc6..0000000 --- a/docs/getting-elements/super-table-block-queries.md +++ /dev/null @@ -1,489 +0,0 @@ -# Super Table Block Queries -You can fetch Super Table blocks in your templates or PHP code using **Super Table block queries**. - -::: code -```twig Twig -{# Create a new Super Table block query #} -{% set mySuperTableBlockQuery = craft.superTable.blocks() %} -``` -```php -// Create a new Super Table block query -$mySuperTableBlockQuery = \verbb\supertable\elements\SuperTableBlockElement::find(); -``` -::: - -Once you’ve created a Super Table block query, you can set [parameters](#parameters) on it to narrow down the results, and then execute it by calling `.all()`. An array of Super Table Block objects will be returned. - -::: tip -See [Introduction to Element Queries](https://craftcms.com/docs/3.x/element-queries.html) to learn about how element queries work. -::: - -## Example -We can display content from all the Super Table blocks of an element by doing the following: - -1. Create a Super Table block query with `craft.superTable.blocks()`. -2. Set the [owner](#owner), and [fieldId](#fieldid) parameters on it. -3. Fetch the Super Table blocks with `.all()`. -4. Loop through the Super Table blocks using a [for](https://twig.symfony.com/doc/2.x/tags/for.html) tag to output the contents. - -```twig -{# Create a Super Table block query with the 'owner', and 'fieldId' parameters #} -{% set mySuperTableBlockQuery = craft.superTable.blocks() - .owner(myEntry) - .fieldId(10) %} - -{# Fetch the Super Table blocks #} -{% set superTableBlocks = mySuperTableBlockQuery.all() %} - -{# Display their contents #} -{% for block in blocks %} -

{{ block.text }}

-{% endfor %} -``` - -::: warning -In order for the returned Super Table block(s) to be populated with their custom field content, you will need to either set the [fieldId](#fieldid) or [id](#id) parameter. -::: - -## Parameters -Super Table block queries support the following parameters: - - - -### `asArray` -Causes the query to return matching Super Table blocks as arrays of data, rather than Super Table block objects. - -::: code -```twig Twig -{# Fetch Super Table blocks as arrays #} -{% set mySuperTableBlocks = craft.superTable.blocks() - .asArray() - .all() %} -``` - -```php PHP -// Fetch Super Table blocks as arrays -$superTableBlocks = \verbb\supertable\elements\SuperTableBlockElement::find() - ->asArray() - ->all(); -``` -::: - - - -### `dateCreated` -Narrows the query results based on the Super Table blocks’ creation dates. - -Possible values include: - -| Value | Fetches Super Table 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. - -::: code -```twig Twig -{# Fetch Super Table blocks created last month #} -{% set start = date('first day of last month')|atom %} -{% set end = date('first day of this month')|atom %} - -{% set mySuperTableBlocks = craft.superTable.blocks() - .dateCreated(['and', ">= #{start}", "< #{end}"]) - .all() %} -``` - -```php PHP -// Fetch Super Table blocks created last month -$start = new \DateTime('first day of next month')->format(\DateTime::ATOM); -$end = new \DateTime('first day of this month')->format(\DateTime::ATOM); - -$superTableBlocks = \verbb\supertable\elements\SuperTableBlockElement::find() - ->dateCreated(['and', ">= {$start}", "< {$end}"]) - ->all(); -``` -::: - - - -### `dateUpdated` -Narrows the query results based on the Super Table blocks’ last-updated dates. - -Possible values include: - -| Value | Fetches Super Table 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. - -::: code -```twig Twig -{# Fetch Super Table blocks updated in the last week #} -{% set lastWeek = date('1 week ago')|atom %} - -{% set mySuperTableBlocks = craft.superTable.blocks() - .dateUpdated(">= #{lastWeek}") - .all() %} -``` - -```php PHP -// Fetch Super Table blocks updated in the last week -$lastWeek = new \DateTime('1 week ago')->format(\DateTime::ATOM); - -$superTableBlocks = \verbb\supertable\elements\SuperTableBlockElement::find() - ->dateUpdated(">= {$lastWeek}") - ->all(); -``` -::: - - - -### `fieldId` -Narrows the query results based on the field the Super Table blocks belong to, per the fields’ IDs. - -Possible values include: - -| Value | Fetches Super Table 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. - -::: code -```twig Twig -{# Fetch Super Table blocks in the field with an ID of 1 #} -{% set mySuperTableBlocks = craft.superTable.blocks() - .fieldId(1) - .all() %} -``` - -```php PHP -// Fetch Super Table blocks in the field with an ID of 1 -$superTableBlocks = \verbb\supertable\elements\SuperTableBlockElement::find() - ->fieldId(1) - ->all(); -``` -::: - - - -### `fixedOrder` -Causes the query results to be returned in the order specified by [id](#id). - -::: code -```twig Twig -{# Fetch Super Table blocks in a specific order #} -{% set mySuperTableBlocks = craft.superTable.blocks() - .id([1, 2, 3, 4, 5]) - .fixedOrder() - .all() %} -``` - -```php PHP -// Fetch Super Table blocks in a specific order -$superTableBlocks = \verbb\supertable\elements\SuperTableBlockElement::find() - ->id([1, 2, 3, 4, 5]) - ->fixedOrder() - ->all(); -``` -::: - - - -### `id` -Narrows the query results based on the Super Table blocks’ IDs. - -Possible values include: - -| Value | Fetches Super Table blocks… -| - | - -| `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 Twig -{# Fetch the Super Table block by its ID #} -{% set superTableBlock = craft.superTable.blocks() - .id(1) - .one() %} -``` - -```php PHP -// Fetch the Super Table block by its ID -$superTableBlock = \verbb\supertable\elements\SuperTableBlockElement::find() - ->id(1) - ->one(); -``` -::: - -::: tip -This can be combined with [fixedOrder](#fixedorder) if you want the results to be returned in a specific order. -::: - - - -### `inReverse` -Causes the query results to be returned in reverse order. - -::: code -```twig Twig -{# Fetch Super Table blocks in reverse #} -{% set mySuperTableBlocks = craft.superTable.blocks() - .inReverse() - .all() %} -``` - -```php PHP -// Fetch Super Table blocks in reverse -$superTableBlocks = \verbb\supertable\elements\SuperTableBlockElement::find() - ->inReverse() - ->all(); -``` -::: - - - -### `limit` -Determines the number of Super Table blocks that should be returned. - -::: code -```twig Twig -{# Fetch up to 10 Super Table blocks #} -{% set mySuperTableBlocks = craft.superTable.blocks() - .limit(10) - .all() %} -``` - -```php PHP -// Fetch up to 10 Super Table blocks -$superTableBlocks = \verbb\supertable\elements\SuperTableBlockElement::find() - ->limit(10) - ->all(); -``` -::: - - - -### `offset` -Determines how many Super Table blocks should be skipped in the results. - -::: code -```twig Twig -{# Fetch all Super Table blocks except for the first 3 #} -{% set mySuperTableBlocks = craft.superTable.blocks() - .offset(3) - .all() %} -``` - -```php PHP -// Fetch all Super Table blocks except for the first 3 -$superTableBlocks = \verbb\supertable\elements\SuperTableBlockElement::find() - ->offset(3) - ->all(); -``` -::: - - - -### `orderBy` -Determines the order that the Super Table blocks should be returned in. - -::: code -```twig Twig -{# Fetch all Super Table blocks in order of date created #} -{% set mySuperTableBlocks = craft.superTable.blocks() - .orderBy('elements.dateCreated asc') - .all() %} -``` - -```php PHP -// Fetch all Super Table blocks in order of date created -$superTableBlocks = \verbb\supertable\elements\SuperTableBlockElement::find() - ->orderBy('elements.dateCreated asc') - ->all(); -``` -::: - - - -### `owner` -Sets the [ownerId](#ownerid) and [siteId](#siteid) parameters based on a given element. - -::: code -```twig Twig -{# Fetch Super Table blocks created for this entry #} -{% set mySuperTableBlocks = craft.superTable.blocks() - .owner(myEntry) - .all() %} -``` - -```php PHP -// Fetch Super Table blocks created for this entry -$superTableBlocks = \verbb\supertable\elements\SuperTableBlockElement::find() - ->owner($myEntry) - ->all(); -``` -::: - - - -### `ownerId` -Narrows the query results based on the owner element of the Super Table blocks, per the owners’ IDs. - -Possible values include: - -| Value | Fetches Super Table 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. - -::: code -```twig Twig -{# Fetch Super Table blocks created for an element with an ID of 1 #} -{% set mySuperTableBlocks = craft.superTable.blocks() - .ownerId(1) - .all() %} -``` - -```php PHP -// Fetch Super Table blocks created for an element with an ID of 1 -$superTableBlocks = \verbb\supertable\elements\SuperTableBlockElement::find() - ->ownerId(1) - ->all(); -``` -::: - - - -### `search` -Narrows the query results to only Super Table blocks that match a search query. - -See [Searching](https://craftcms.com/docs/4.x/searching.html) for a full explanation of how to work with this parameter. - -::: code -```twig Twig -{# Get the search query from the 'q' query string param #} -{% set searchQuery = craft.app.request.getQueryParam('q') %} - -{# Fetch all Super Table blocks that match the search query #} -{% set mySuperTableBlocks = craft.superTable.blocks() - .search(searchQuery) - .all() %} -``` - -```php PHP -// Get the search query from the 'q' query string param -$searchQuery = \Craft::$app->getRequest()->getQueryParam('q'); - -// Fetch all Super Table blocks that match the search query -$superTableBlocks = \verbb\supertable\elements\SuperTableBlockElement::find() - ->search($searchQuery) - ->all(); -``` -::: - - - -### `site` -Determines which site the Super Table blocks should be queried in. - -The current site will be used by default. - -Possible values include: - -| Value | Fetches Super Table blocks… -| - | - -| `'foo'` | from the site with a handle of `foo`. -| a [Site](https://docs.craftcms.com/api/v4/craft-models-site.html) object | from the site represented by the object. - -::: code -```twig Twig -{# Fetch Super Table blocks from the Foo site #} -{% set mySuperTableBlocks = craft.superTable.blocks() - .site('foo') - .all() %} -``` - -```php PHP -// Fetch Super Table blocks from the Foo site -$superTableBlocks = \verbb\supertable\elements\SuperTableBlockElement::find() - ->site('foo') - ->all(); -``` -::: - - - -### `siteId` -Determines which site the Super Table blocks should be queried in, per the site’s ID. - -The current site will be used by default. - -::: code -```twig Twig -{# Fetch Super Table blocks from the site with an ID of 1 #} -{% set mySuperTableBlocks = craft.superTable.blocks() - .siteId(1) - .all() %} -``` - -```php PHP -// Fetch Super Table blocks from the site with an ID of 1 -$superTableBlocks = \verbb\supertable\elements\SuperTableBlockElement::find() - ->siteId(1) - ->all(); -``` -::: - - - -### `uid` -Narrows the query results based on the Super Table blocks’ UIDs. - -::: code -```twig Twig -{# Fetch the Super Table block by its UID #} -{% set superTableBlock = craft.superTable.blocks() - .uid('xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx') - .one() %} -``` - -```php PHP -// Fetch the Super Table block by its UID -$superTableBlock = \verbb\supertable\elements\SuperTableBlockElement::find() - ->uid('xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx') - ->one(); -``` -::: - - - -### `with` -Causes the query to return matching Super Table blocks eager-loaded with related elements. - -See [Eager-Loading Elements](https://craftcms.com/docs/4.x/eager-loading-elements.html) for a full explanation of how to work with this parameter. - -::: code -```twig Twig -{# Fetch Super Table blocks eager-loaded with the "Related" field’s relations #} -{% set mySuperTableBlocks = craft.superTable.blocks() - .with(['related']) - .all() %} -``` - -```php PHP -// Fetch Super Table blocks eager-loaded with the "Related" field’s relations -$superTableBlocks = \verbb\supertable\elements\SuperTableBlockElement::find() - ->with(['related']) - ->all(); -``` -::: - - - diff --git a/docs/template-guides/available-variables.md b/docs/template-guides/available-variables.md deleted file mode 100644 index f95a4de..0000000 --- a/docs/template-guides/available-variables.md +++ /dev/null @@ -1,23 +0,0 @@ -# Available Variables -The following methods are available to call in your Twig templates: - -### `craft.superTable.blocks()` -See [Super Table Block Queries](docs:getting-elements/super-table-block-queries) - -### `craft.superTable.getRelatedElements()` -Expands the default relationship behaviour to include Super Table fields so that the user can filter by those too. - -```twig -{% set reverseRelatedElements = craft.superTable.getRelatedElements({ - relatedTo: { - targetElement: entry, - field: 'superTableFieldHandle.columnHandle', - }, - ownerSite: 'siteHandle', - elementType: 'craft\\elements\\Entry', - criteria: { - id: 'not 123', - section: 'someSection', - } -}).all() %} -``` diff --git a/docs/template-guides/block-querying.md b/docs/template-guides/block-querying.md deleted file mode 100644 index 829624c..0000000 --- a/docs/template-guides/block-querying.md +++ /dev/null @@ -1,36 +0,0 @@ -# Block Querying -The below is by no means a full solution, but will certainly assist in querying content from a Super Table field. - -::: code -```twig Twig -{% set blocks = craft.superTable.blocks({ ownerId: '149081', fieldId: '563' }).all() %} - -{% for block in blocks %} - {% for field in block.getFieldLayout().getCustomFields() %} - {% set value = block.getFieldValue(field.handle) %} - - {{ dump(value) }} - {% endfor %} -{% endfor %} -``` - -```php PHP -use verbb\supertable\elements\SuperTableBlockElement; - -$query = SuperTableBlockElement::find() - ->ownerId('149081'); // Element ID - commonly an entry - ->fieldId('563'); // Super Table field ID - -$blocks = $query->all(); - -foreach ($blocks as $block) { - $values = []; - - foreach ($block->getFieldLayout()->getCustomFields() as $field) { - $value = $block->getFieldValue($field->handle); - - var_dump($value); - } -} -``` -::: diff --git a/docs/template-guides/front-end-form.md b/docs/template-guides/front-end-form.md deleted file mode 100644 index 17727f2..0000000 --- a/docs/template-guides/front-end-form.md +++ /dev/null @@ -1,47 +0,0 @@ -# Front-end Form -Updating a Super Table field from a front-end form is straightforward - it's very similar to a Matrix. - -Refer to the following code - we have a Super Table field with handle `mySuperTableField` in our User profile, which we want to modify. This could apply to any endpoint in Craft, be it Entries, Global Set, etc. - -First, we need to output any existing rows for this field, otherwise they will be overwritten. These can be hidden inputs if you don't want them to appear. - -The variables below will help you figure out the correct block type to use (even though a Super Table field will only ever have one block type). - -```twig -{% set fieldHandle = 'mySuperTableField' %} -{% set field = craft.app.fields.getFieldByHandle(fieldHandle) %} -{% set blocktype = craft.superTable.getSuperTableBlocks(field.id)[0] %} - -
- {{ csrfInput() }} - - - - {# Start with the top-level Super Table field #} - - - {# Ensure any existing rows in your Super Table field are saved #} - {% for block in currentUser[fieldHandle] %} - - - - - {% endfor %} - - {# Add a new row of data - note the `new1` #} - - - - {# Repeat for all your fields in your Super Table field #} - - - {# Add another new row of data #} - - - - {# Repeat for all your fields in your Super Table field #} - - - -
-``` diff --git a/docs/template-guides/php-example.md b/docs/template-guides/php-example.md deleted file mode 100644 index 46ebe6e..0000000 --- a/docs/template-guides/php-example.md +++ /dev/null @@ -1,89 +0,0 @@ -# PHP Example -The below is an example in PHP to programmatically save a Super Table field with content. - -```php -use Craft; -use craft\elements\Entry; -use verbb\supertable\SuperTable; - -// Set up your new Entry -$entry = new Entry(); -$entry->getContent()->title = 'My Title'; -$entry->sectionId = 1; -$entry->authorId = 1; - -// Create your Super Table blocks. Make sure to change the `fields` array to reflect -// the handles of your fields in your Super Table field. -$superTableData = []; - -// Get our Super Table field -$field = Craft::$app->getFields()->getFieldByHandle('socialMedia'); -$blockTypes = SuperTable::$plugin->getService()->getBlockTypesByFieldId($field->id); -$blockType = $blockTypes[0]; // There will only ever be one SuperTable_BlockType - -$superTableData['new1'] = [ - 'type' => $blockType->id, - 'enabled' => true, - 'fields' => [ - 'fieldOne' => 'Some string or data', - 'fieldTwo' => '12' - ] -]; - -// You can repeat this part for each block you want to add, just increment the newN number. -$superTableData['new2'] = [ - 'type' => $blockType->id, - 'enabled' => true, - 'fields' => [ - 'fieldOne' => 'Some more text', - 'fieldTwo' => '16' - ] -]; - -// Set the blocks for the Super Table field - ensure you change the handle to reflect your Super Table field handle -$entry->setFieldValues(['superTableField' => $superTableData]); - -// When you're done, save the entry -Craft::$app->getElements()->saveElement($entry); -``` - -## Updating existing field content -Using the above example as a basis, you can not only add new blocks, but retain existing blocks as well. Here, we make use of Craft's delta updates feature to save partial Super Table data. - -```php -use Craft; -use craft\elements\Entry; -use verbb\supertable\SuperTable; - -// Get our Super Table field -$field = Craft::$app->getFields()->getFieldByHandle('superTableField'); -$blockTypes = SuperTable::$plugin->getService()->getBlockTypesByFieldId($field->id); -$blockType = $blockTypes[0]; // There will only ever be one SuperTable_BlockType - -// Get the entry we want to modify -$entry = Entry::find()->id(1234)->one(); - -// Get the `sortOrder` of all existing blocks. This helps with delta updates. -$sortOrder = (clone $entry->superTableField)->anyStatus()->ids(); -$sortOrder[] = 'new:1'; - -// Create your new block info -$newBlock = [ - 'type' => $blockType->id, - 'enabled' => true, - 'fields' => [ - 'fieldOne' => 'This is new block text', - ], -]; - -// Set the field value for your Super Table field, including the new block, and existing `sortOrder` -$entry->setFieldValue('superTableField', [ - 'sortOrder' => $sortOrder, - 'blocks' => [ - 'new:1' => $newBlock, - ], -]); - -// When you're done, save the entry -Craft::$app->elements->saveElement($entry); -``` diff --git a/docs/template-guides/rendering-content.md b/docs/template-guides/rendering-content.md deleted file mode 100644 index dd1fcb0..0000000 --- a/docs/template-guides/rendering-content.md +++ /dev/null @@ -1,28 +0,0 @@ -# Rendering Content -The below shows some typical Twig templating examples for field setups. - -## Super Table field - -```twig -{% for row in entry.superTablePlainText.all() %} - {{ row.plainText }} -{% endfor %} -``` - -## Static Super Table field - -```twig -{{ entry.superTableRichText.richText }} -``` - -## Matrix in Super Table field - -```twig -{% for row in entry.superTableMatrix.all() %} - {% for block in row.matrix.all() %} - {% if block.type == 'block1' %} - {{ block.plainText }} - {% endif %} - {% endfor %} -{% endfor %} -```