Skip to content

Catalogue: galleries, size charts, import and export ​

The basics — categories, options, variants, prices, stock — are covered in Quick start and For developers. This page is the four things that have no section anywhere else.

Several pictures per product, with the main image first. There is no gallery table in the shop, and that is a rule rather than a saving: PageBlocks already has a gallery, whole. pb_files is polymorphic storage — the owner is a row, the field is a field, the order is a sort index, the caption is a title — uploading and deleting are its controller's job, and the model fetches the gallery by field name on its own. {$product->gallery} works without a line of our code.

So the shop does not add a schema; it declares a field. The field is gallery, a galleryfield on the product constructor.

galleryfield is a paid PageBlocks field type

On the free edition the field is not drawn in the form, so there is nowhere to upload to. This is a deliberate choice: a gallery of our own would mean a second file-storage mechanism on the same site.

The storefront is built for the absence. With an empty gallery the template prints the single product image exactly as it did before the field existed, and a one-frame gallery is also treated as empty — there is nothing to switch between, and wrapping a lone picture in a carousel is broken layout on every product whose gallery nobody filled in.

The field arrived with PageBlocks alfa36, released to make it work. On an older platform there is nowhere for it to live. See What ships where.

On a shop that already exists, the field arrives by migration

The seed skips fields that are already there, and the product constructor was created long before the gallery. So on a working shop the seed would never add it: the gallery code would be present and the form field absent, with nothing to fill it from. A fresh install gets the field from the seed, an upgrade gets it from a migration.

Only images are shown, and in sort-index order. A video dropped into the gallery is skipped rather than printed in an img tag.

Size charts ​

A chart is a reference entry, not a block of text pasted into each product — pb_shop_size_charts, managed on its own Size charts tab.

FieldWhat it holds
keythe identifier
namewhat it is called
option_idwhich option the chart explains — "Size", "Shoe size"
sourcethe table itself as text: the first row is headings, the first column is sizes
notehow to measure

A chart is attached through the size_chart_id constructor field, and it is inherited: a product's own chart wins, otherwise its category's, otherwise the parent category's, up to ten levels. Filling it on the category is the normal path; you fill it on a product when that particular model fits differently from the rest of its category.

On the product page the chart is rendered as a grid, with the row matching the buyer's chosen size highlighted — which is why the chart names an option rather than floating free.

A chart found but unpublished shows nothing

Inheritance looks for the nearest chart, and it does not skip over an unpublished one to keep searching upward. Unpublishing a category's chart hides the table on those products rather than falling back to the grandparent.

Import and export: CSV and XLSX ​

Both formats, both directions, from the shop section. Without this a catalogue of any size cannot be filled at all, which is why it is in the core and not a module.

GET   /mgr/pbs/catalog/export/csv
GET   /mgr/pbs/catalog/export/xlsx
POST  /mgr/pbs/catalog/import

The columns ​

In export order, which is not cosmetic — it is what a person sees on opening the file in Excel. First what identifies the row, then what it is, then money, then stock, then the wide text columns, which go to the right:

alias  sku  type  title  categories  currency  price  old_price
track_stock  stock  weight  image  menuindex  published  description  content

Plus, generated from your shop's own setup:

  • price_<CODE> and old_price_<CODE> for every currency beyond the base one;
  • option_<KEY> for each option in the reference.

How a row is read ​

One row is either a product or a variant, and the sku column decides: empty means the row describes the product, filled means it describes a variant of the product named by alias. So a product with three sizes is four rows — one for itself and three for its variants.

Six columns are read only from the product row and ignored on variant rows: type, categories, currency, track_stock, description, content. They belong to the product, and a variant claiming its own category would be a contradiction, not an override.

The identity key is the alias for a product and the sku for a variant — not the id. That is what makes the import idempotent: the same file applied twice updates, it does not duplicate.

An empty cell does not clear a value on update

It means "not specified", not "set to nothing". That is the right default for the common case — a column someone deleted from the spreadsheet should not wipe every product's description — but it does mean you cannot blank a field by emptying its cell. Clear it in the manager.

One more thing worth knowing: alias has no unique index in the database. The import treats it as a key, so two products sharing an alias will have their import land on whichever comes first. It is recorded as a defect; until it is fixed, do not create duplicate aliases.

The import reports back how many products and variants were created, how many updated, and how many rows were skipped.

Next ​

pbShop — a shop component for PageBlocks