{"id":13568210,"url":"https://github.com/kitconcept/volto-blocks-grid","last_synced_at":"2025-10-15T04:53:48.688Z","repository":{"id":37411782,"uuid":"329038108","full_name":"kitconcept/volto-blocks-grid","owner":"kitconcept","description":"Sophisticated Page Layouts for Plone 6 (Volto)","archived":false,"fork":false,"pushed_at":"2023-10-27T08:30:29.000Z","size":2179,"stargazers_count":5,"open_issues_count":13,"forks_count":5,"subscribers_count":5,"default_branch":"main","last_synced_at":"2025-05-11T12:11:33.974Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"https://volto.kitconcept.com","language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/kitconcept.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":"SECURITY.md","support":null,"governance":null,"roadmap":null,"authors":null}},"created_at":"2021-01-12T15:59:47.000Z","updated_at":"2023-10-29T12:14:08.000Z","dependencies_parsed_at":"2022-07-08T01:30:45.911Z","dependency_job_id":"a8ceefce-3a10-4a8d-a809-4abd735b7f85","html_url":"https://github.com/kitconcept/volto-blocks-grid","commit_stats":{"total_commits":230,"total_committers":12,"mean_commits":"19.166666666666668","dds":"0.11304347826086958","last_synced_commit":"2110ddf5c46996a78a2dd83977bd8f0745416ceb"},"previous_names":[],"tags_count":39,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kitconcept%2Fvolto-blocks-grid","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kitconcept%2Fvolto-blocks-grid/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kitconcept%2Fvolto-blocks-grid/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kitconcept%2Fvolto-blocks-grid/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/kitconcept","download_url":"https://codeload.github.com/kitconcept/volto-blocks-grid/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":254330806,"owners_count":22053052,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2024-08-01T14:00:21.691Z","updated_at":"2025-10-15T04:53:43.658Z","avatar_url":"https://github.com/kitconcept.png","language":"JavaScript","funding_links":[],"categories":["Add-ons"],"sub_categories":["Layout add-ons"],"readme":"# Volto Blocks Grid (by kitconcept)\n\n[![NPM](https://img.shields.io/npm/v/@kitconcept/volto-blocks-grid.svg)](https://www.npmjs.com/package/@kitconcept/volto-blocks-grid)\n[![Build Status](https://github.com/kitconcept/volto-blocks-grid/actions/workflows/code.yml/badge.svg)](https://github.com/kitconcept/volto-blocks-grid/actions)\n[![Build Status](https://github.com/kitconcept/volto-blocks-grid/actions/workflows/unit.yml/badge.svg)](https://github.com/kitconcept/volto-blocks-grid/actions)\n[![Build Status](https://github.com/kitconcept/volto-blocks-grid/actions/workflows/acceptance.yml/badge.svg)](https://github.com/kitconcept/volto-blocks-grid/actions)\n\n![kitconcept GmbH](https://raw.githubusercontent.com/kitconcept/volto-form-builder/master/kitconcept.png)\n\nVolto Blocks Grid allows sophisticated page layouts for Plone 6 (Volto).\n\n![gif-video](https://user-images.githubusercontent.com/486927/114311809-8b032600-9af0-11eb-90e0-0944294a6084.gif)\n\n[Full size video](https://user-images.githubusercontent.com/486927/114309930-40ca7680-9ae9-11eb-873d-0504bddc0682.mov)\n\n## Philosophy\n\nAt kitconcept, we think that providing a full featured, two dimensional free will layout\n(eg. Plone Mosaic-ish like) experience to users is often overwhelming for them,\nspecially if these users are not technical or power users. Providing a proper and\ncomprehensive UX for this kind of layouts are often hard and counter intuitive,\nspecially when dealing with behaviors in responsive layouts. Our experience is that\nallowing that also enables an easy path to craft \"ugly layouts\" way out of the (most\nprobably) existing site style guide.\n\nBy providing a mean to restrict the users to unidimensional layouts (and still enabling\nthem to build with them 2D layouts) are better than an UX that allows you to arbitrary\nposition blocks in a 2D space.\n\nAlso, unidimensional grids are also more in line of the current design trends in modern\nweb, where we can often find these unified one rowed sections, specially in landing pages.\n\n## Compatibility\n\nFrom Volto 17 alpha 16, the Grid block included in this add-on is now in core.\n\nDue to a change in CSS happening in Volto 16.0.0 RC2, this is the compatibility grid for this add-on:\n\n|Version   |Volto version |\n|----------|--------------|\n|\u003e=5.2.0   |\u003e=16.0.0-rc.2 |\n|\u003c=5.1.1   |\u003c=16.0.0-a50  |\n\n## Block included in this package\n\n### Grid block\n\nThis block can contain any registered block in the application. By default, it's\nrestricted to `Image`, `Text`, `slate`, `Teaser` and `Listing`. More can be customized via the\nblock config `gridAllowedBlocks` key:\n\n```js\n  __grid: {\n    id: '__grid',\n...\n    gridAllowedBlocks: ['teaser', 'image', 'listing', 'text'],\n  },\n```\n\nYou can even further customize the blocks config available for the inner blocks by passing `blocksConfig` key as a block config. You can add different variations, schemaEnhancers, etc or remove them as well:\n\n```js\nconfig.blocks.blocksConfig.__grid.gridAllowedBlocks: ['teaser', 'image', 'slate'];\nconfig.blocks.blocksConfig.__grid.blocksConfig: {\n  // One could customize the blocks inside the grid like this:\n  ...config.blocks.blocksConfig,\n  teaser: {\n    ...config.blocks.blocksConfig.teaser,\n    variations: [\n      {\n        id: 'default',\n        isDefault: true,\n        title: 'Default',\n        template: DefaultBody,\n      },\n      {\n        id: 'variation2',\n        title: 'variation #2',\n        template: DefaultBody2,\n      },\n    ],\n  },\n};\n```\n\n### Teaser Grid block\n\nThis block is restricted by default to contain `Teaser` block type.\n\n### Image Grid block\n\nThis block is restricted by default to contain `Image` block type.\n\n## Create your own block types\n\nYou can craft your personalized grid types by restricting the block types allowed inside\nby creating a new block type and using the `gridAllowedBlocks` key:\n\n```js\nimport {\n  GridViewBlock,\n  GridEditBlock,\n  TeaserViewBlock,\n  TeaserEditBlock,\n} from './components';\n\n...\n  teaserGrid: {\n    id: 'teaserGrid',\n    title: 'Teaser Grid',\n    icon: imagesSVG,\n    group: 'teasers',\n    view: GridViewBlock,\n    edit: GridEditBlock,\n    restricted: false,\n    mostUsed: true,\n    sidebarTab: 1,\n    gridAllowedBlocks: ['teaser'],\n  },\n    teaser: {\n    id: 'teaser',\n    title: 'Teaser',\n    icon: imagesSVG,\n    group: 'common',\n    view: TeaserViewBlock,\n    edit: TeaserEditBlock,\n    restricted: true,\n    mostUsed: true,\n    sidebarTab: 1,\n    blockSchema: TeaserSchema,\n    dataAdapter: TeaserBlockDataAdapter,\n    imageScale: 'teaser'\n  },\n```\n\nany registered block types are allowed.\n\n## Teaser block\n\nThis package includes a Teaser block that allows you to pull content from a source content object and brings in to a block (`title`, `head_line`, `description`, and `preview_image` fields). It tries to get these fields from the original source content first, and allows you to override them afterwards.\n\nThe Teaser block can be used in Grids and as standalone block as well. In the standalone version, it includes an alignment styling option to position the target teased image.\n\nYou'll find the `preview_image` field in `plone.volto` (and previous to that, in `kitconcept.volto`) add-on. You should add it to the content types that you plan to use as teased elements. If no `preview_image` field is present in the source content, it will fallback to the `image` (eg. `Lead image` behavior), if any. If no image fields are present, it won't show any image unless you override it (using the local `preview_image` field) in the block's config.\n\nIt includes a configuration option `imageScale` (see above example) that allows you to use an specific scale for the `preview_image`. It defaults to `teaser` scale.\n\n### Data adapter\n\nWhen a target is selected in a teaser block, an adapter is executed in case that you want to manipulate the data that it's being saved into the block. In case that you want to override the data adapter you have to provide your own adapter in the Teaser block settings `dataAdapter`.\n\n```js\nimport { TeaserBlockDataAdapter } from './components/Teaser/adapter';\nimport { TeaserSchema } from './components/Teaser/schema';\n...\n  teaser: {\n    ...\n    blockSchema: TeaserSchema,\n    dataAdapter: TeaserBlockDataAdapter,\n  },\n```\n\nThe default adapter only saves locally (for caching purposes) the fields `title`, `head_line`, `description`, and `preview_image`. You can add your own there if you need more data from the target in your block.\n\n## Compatibility\n\n5.0.0 -\u003e Volto 16.0.0 or above\n2.0.0 -\u003e Volto 12.14.0 and \u003c Volto 16.0.0\n1.0.0 -\u003e Anything lower\n\n## Teaser included in Volto core\n\nFrom Volto 16.14.0 the Teaser block as it's in `volto-blocks-grid` version 7.0.0 is now included in Volto core.\n\nBecause of the add-on config priority, if you have `volto-blocks-grid` installed in your project, the Teaser block from the add-on (and your project amendments to the config, if any) there will be applied and used.\n\nIn case you want to use the core one, you need to re-apply the core configuration for the Teaser block in your project or add-ons.\n\n## Grid included in Volto core\n\nFrom Volto 17 alpha 16 the Grid block as it's in `volto-blocks-grid` version 7.x.x is now included in Volto core.\n\nThe Volto core grid uses the Volto internals default blocks-in-block architecture.\nThis differs from the grid block data structure in the add-on `@kitconcept/volto-blocks-grid`.\nBecause of this difference, they are not compatible, and a data migration is necessary from the add-on to the Volto grid block.\n\nHowever, the Volto core grid block uses a different internal name, `gridBlock`, so both blocks can coexist at the same time.\nNonetheless, it is recommended to enable only one grid block type for your users, and eventually use a single version to avoid unexpected behaviors and bugs.\n\n## Similar products\n\nYou can try other similar products developed by some of our fellow community members and\ncompanies.\n\n- [@eeacms/volto-grid-block](https://github.com/eea/volto-grid-block)\n- [volto-subblocks](https://github.com/collective/volto-subblocks)\n\n## Install\n\nIf you already have a Volto project, just update `package.json`:\n\n```JSON\n\"addons\": [\n    \"@kitconcept/volto-blocks-grid\"\n],\n\n\"dependencies\": {\n    \"@kitconcept/volto-blocks-grid\": \"*\"\n}\n```\n\nIf not, create one:\n\n```shell\nnpm install -g yo @plone/generator-volto\nyo @plone/volto my-volto-project --addon @kitconcept/volto-blocks-grid\ncd my-volto-project\n```\n\nInstall new add-on and restart Volto:\n\n```shell\nyarn install\nyarn start\n```\n\nGo to http://localhost:3000\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fkitconcept%2Fvolto-blocks-grid","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fkitconcept%2Fvolto-blocks-grid","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fkitconcept%2Fvolto-blocks-grid/lists"}