Skip to content

ecomyseo/prestashop_skills / prestashop_theme_migration

prestashop_theme_migration

Verified

FileKindSize
SKILL.mdskill md27.9 KB
references/breaking-changes.mdmarkdown35.6 KB
references/checkout.mdmarkdown14.5 KB
references/hummingbird.mdmarkdown40.1 KB
references/images.mdmarkdown14.4 KB
references/seo.mdmarkdown23.3 KB
references/timeline.mdmarkdown10.5 KB

references/checkout.md

View on GitHub
# Proceso de compra: cambios y verificación

El checkout es la parte del tema que **no se puede romper**. Un fallo de
maquetación se ve y se corrige; un fallo de checkout no se ve y se factura en
pedidos perdidos.

Buena noticia: entre 1.7.0 y 1.7.8.11 el checkout apenas cambia. Toda la ruptura
está concentrada en **8.0**, y luego en 9.1 con el multi-envío.

## 🔴 8.0 — El `id` del formulario de pago

El cambio más peligroso de toda la migración.

```smarty
{* ≤ 1.7.8.11 — checkout/_partials/steps/payment.tpl *}
<form id="payment-form" method="POST" action="{$option.action nofilter}">

{* ≥ 8.0 *}
<form id="payment-{$option.id}-form" method="POST" action="{$option.action nofilter}">
```

**Por qué importa:** con un solo método de pago activo el `id` era único y todo
funcionaba por casualidad. Con varios, todos los formularios compartían el mismo
`id`, y `document.getElementById('payment-form')` devolvía siempre el primero.
El cliente elegía transferencia y se le enviaba el formulario de tarjeta.

**Al migrar hacia 8.0+:** aplicar el cambio y revisar además los módulos de pago.
Cualquier módulo que haga `$('#payment-form').submit()` o
`document.getElementById('payment-form')` deja de funcionar. Los módulos
oficiales ya están adaptados; los de terceros y los hechos a medida, no
necesariamente.

**Al migrar un tema hacia atrás** (raro, pero pasa con temas comprados para 8.x
que se instalan en 1.7.8): mantener el `id` dinámico es inofensivo salvo que un
módulo antiguo dependa del `id` fijo.

Lo que **no** ha cambiado nunca y por tanto es seguro conservar:

```
#payment-option-{$option.id}-container      contenedor de cada opción
#payment-option-{$option.id}                el radio
.js-payment-option-form                     formulario asociado
.additional-information                     información extra de la opción
{hook h='displayPaymentByBinaries'}         botones de pago externos
#conditions-to-approve / .js-terms          aceptación de condiciones
```

## 🔴 8.0 — `$customer` → `$order_customer` en la confirmación

```smarty
{* ≤ 1.7.8.11 — checkout/order-confirmation.tpl *}
{l s='An email has been sent to your mail address %email%.' … sprintf=['%email%' => $customer.email]}

{* ≥ 8.0 *}
… sprintf=['%email%' => $order_customer.email]
```

Con `PS_DEBUG_MODE` activo es error fatal en la página de confirmación —
justo después de cobrar. Sin debug, sale el mensaje con el email vacío. En ambos
casos el pedido ya está creado: no se pierde la venta, pero da muy mala imagen.

## 🟠 8.0 — Transformación de invitado en cliente

```smarty
{* ≤ 1.7.8.11 *}
{block name='customer_registration_form'}
  {if $customer.is_guest}
    <div id="registration-form" class="card">
      <h4 class="h4">{l s='Save time on your next order, sign up now' d='Shop.Theme.Checkout'}</h4>
      {render file='customer/_partials/customer-form.tpl' ui=$register_form}
    </div>
  {/if}
{/block}

{* ≥ 8.0 *}
{if !$registered_customer_exists}
  {block name='account_transformation_form'}
    <div class="card">
      {include file='customer/_partials/account-transformation-form.tpl'}
    </div>
  {/block}
{/if}
```

Cambian la variable de control (`$customer.is_guest` → `$registered_customer_exists`,
con la lógica **invertida**), el nombre del bloque y el mecanismo (`{render}` con
`$register_form` → `{include}` de un parcial nuevo). Copiar solo una parte deja
el formulario visible pero sin enviar.

## 🟠 8.0 — Etiqueta de impuestos

```smarty
{* ≤ 1.7.8.11 *}  {if $configuration.taxes_enabled}{$cart.labels.tax_short}{/if}
{* ≥ 8.0 *}       {if $configuration.display_taxes_label && $configuration.taxes_enabled}{$cart.labels.tax_short}{/if}
```

En `cart-summary-totals.tpl` y `order-confirmation-table.tpl`. Sin la condición
nueva, las tiendas que han desactivado la etiqueta la siguen viendo. Es un
requisito legal en algunos países, así que no es cosmético.

## 🟠 8.0 — Venta cruzada cambia de sitio

`{hook h='displayCrossSellingShoppingCart'}` sale de `checkout/cart-empty.tpl` y
entra en `checkout/cart.tpl`. Si el tema sobreescribe ambos ficheros y solo se
migra uno, el bloque aparece en el carrito vacío (donde no sirve de nada) y
desaparece del carrito con productos (donde vendía).

## 🟠 8.0 — Otros

- Nuevo hook `{hook h='displayCheckoutBeforeConfirmation'}` al final de
  `steps/payment.tpl`. Varios módulos de pago y de RGPD lo usan; si el tema
  sobreescribe `payment.tpl` y no lo incluye, esos módulos no pintan nada.
- `steps/addresses.tpl`: nuevo atributo `data-id-address="{$id_address}"`, que
  el JS usa para asociar la dirección al bloque.
- `<p class="cart-payment-step-not-needed-info">` en el aviso de "no se requiere
  pago" (pedidos a coste cero).
- Embalaje reciclable: `$is_recyclable_packaging` en `order-final-summary.tpl` y
  `$order.details.recyclable` en `order-confirmation.tpl`.
- En `cart.tpl` se limpian `col-xs-12` redundantes:
  `cart-grid-body col-xs-12 col-lg-8` → `cart-grid-body col-lg-8`. En Bootstrap 4
  `col-xs-12` es el comportamiento por defecto, así que no cambia nada visual.

## 🟡 8.2 — Contenido extra del transportista

```smarty
{* 8.1 *}
<div class="row carrier-extra-content js-carrier-extra-content"{if $delivery_option != $carrier_id} style="display:none;"{/if}>

{* 8.2 *}
<div class="carrier-extra-content js-carrier-extra-content"{if ($delivery_option != $carrier_id) || ($delivery_option == $carrier_id && empty($carrier.extraContent))} style="display:none;"{/if}>

{* 9.0 — vuelve `row`, se revierte la condición *}
<div class="row carrier-extra-content js-carrier-extra-content"{if $delivery_option != $carrier_id} style="display:none;"{/if}>
```

La clase `row` va y viene entre 8.1, 8.2 y 9.0. Sin ella, los transportistas se
desalinean; con ella donde no toca, se descuadra el paso de envío. Usar la
variante de la versión destino y comprobarlo visualmente con dos o más
transportistas activos.

Módulos de puntos de recogida (Correos, SEUR, Packlink…) inyectan su mapa en
`carrier-extra-content`. Si el tema sobreescribe `shipping.tpl` y pierde la clase
`js-carrier-extra-content`, el mapa no se muestra ni se puede elegir punto: el
cliente no puede completar el pedido.

## 🟠 9.1 — Multi-envío

Ver `breaking-changes.md` § 9.1. Resumen operativo: mientras el *feature flag* de
multi-envío esté desactivado, un tema de 9.0 funciona sin cambios. Si se activa,
hay que implementar las plantillas `*-multishipment.tpl` o el cliente verá un
único transportista para un pedido que se envía en varios paquetes.

Bifurcar siempre con la variable protegida, para no romper 9.0:

```smarty
{if isset($is_multishipment_enabled) && $is_multishipment_enabled}
```

## 🔴 9.2 — One Page Checkout (`ps_onepagecheckout`)

⚠️ A 24-07-2026 **no existe 9.2 estable**: esto sale de `9.2.0-beta.1` y de la
doc oficial, y hay que revalidarlo cuando se publique.

Es el cambio de checkout más grande desde 8.0. Módulo **nativo empaquetado**, no
de terceros. Doc:
<https://devdocs.prestashop-project.org/9/modules/checkout/theme-developers/>

### Cómo se activa (y por qué puede pillarte por sorpresa)

No sustituye plantillas del tema por copia: se engancha a
`hookDisplayOverrideTemplate` e **intercepta** `template_file === 'checkout/checkout'`
cuando el controlador es `OrderController`, devolviendo
`module:ps_onepagecheckout/views/templates/front/checkout/checkout.tpl`.

Consecuencia práctica: **con el módulo activo, tu `checkout/checkout.tpl` deja de
pintarse**. Si el tema tenía ahí personalizaciones, desaparecen sin dar ningún
error. Es exactamente el mismo síntoma desconcertante que el de los maquetadores
descrito en el SKILL: subes el cambio, vacías caché, y el HTML sigue igual.

### La variable de guarda

```smarty
{if isset($is_one_page_checkout_enabled) && $is_one_page_checkout_enabled}
```

🔴 `$is_one_page_checkout_enabled` **solo está asignada en la página de
checkout**. Usarla sin `isset()` en cabecera, pie o cualquier otra plantilla da
aviso de Smarty con `PS_DEBUG_MODE` activo.

### Contrato DOM: esto es API, no decoración

Si se sobreescriben las plantillas del OPC, estos selectores **deben
conservarse**. Quitar uno rompe el pago sin dar ningún error visible — la misma
categoría de fallo que el `id` del formulario de pago de 8.0:

```
.one-page-checkout                        wrapper que activa el JS
#opc-form
#opc-delivery-address-content-list        #opc-billing-address-content-list
#opc-delivery-methods                     #opc-payment-methods
#opc-pay-button                           #opc-pay-amount
#pay-with-{paymentOptionId}-form
input[name^="conditions_to_approve["][required]
#opc-template-loader  #opc-template-carriers-error  #opc-template-payment-error
#modal-delivery       #modal-invoice
```

Los tres `#opc-template-*` son elementos `<template>`: si el tema los elimina por
"limpiar HTML que no se ve", el checkout pierde el indicador de carga y los
mensajes de error de transportista y de pago.

### Variables y eventos nuevos

Variables del contexto OPC: `$formFields`, `$contactFields`,
`$additionalCustomerFields`, `$useSameAddressField`, `$deliveryFields`,
`$invoiceFields`, `$invoiceMetaFields`, `$delivery_options`,
`$selected_delivery_option`, `$payment_options`, `$selected_payment_module`,
`$selected_payment_selection_key`, `$conditions_to_approve`,
`$validation_errors`, `$validation_error_messages`, `$opc_urls`,
`$hookDisplayBeforeCarrier`, `$hookDisplayAfterCarrier`.

Eventos nuevos del bus `prestashop.on()`: familias `opcCarriers*`,
`opcPaymentMethods*`, `opcDeliveryAddressSelected`, `opcBillingAddressSelected`,
`updatedOpcAddressForm`, `opcGuestInit*`, `opcFinalSubmitStarted`,
`opcFormValidated`, `opcSubmitFailed`, `opcCartSummaryUpdated`.

Objeto runtime `window.ps_onepagecheckout` (`enabled`, `urls`, `messages`).
**Prohibido hardcodear endpoints**: leerlos siempre de ahí o de `$opc_urls`.

Hook nuevo para módulos: `actionCheckoutBuildProcess`.
CSS base: `views/public/one-page-checkout.css` (handle
`module-ps-onepagecheckout`, prioridad 200).

### 🔴 El aviso que decide el presupuesto

Verbatim de la doc oficial:

> *"If your theme was created from Classic or provides a custom theme structure,
> overrides of the One Page Checkout views will be broader"*

Es decir: el OPC funciona out-of-the-box sobre **Hummingbird**; sobre un tema
derivado de **classic** exige overrides bastante más amplios. Si el cliente
quiere checkout de una página en 9.2, **ese coste va en la propuesta y se estima
aparte**, no se asume dentro del "subir de versión".

Y como todo lo que toca el checkout: es lo último que se toca y lo primero que se
verifica, con el checklist completo de abajo, de principio a fin.

## Checklist de verificación

**Obligatorio antes de dar por buena una migración.** No vale con que la página
cargue: hay que llegar hasta el pedido confirmado.

### Carrito
- [ ] Añadir producto simple, con combinación y pack.
- [ ] Añadir producto personalizable (texto y fichero).
- [ ] Cambiar cantidades con los botones `+` / `−` (touchspin) y escribiéndolas.
- [ ] Eliminar línea. Comprobar que los totales se recalculan sin recargar.
- [ ] Aplicar y quitar un cupón.
- [ ] Carrito vacío: se ve el mensaje correcto.

### Checkout
- [ ] Como invitado, como cliente nuevo y como cliente ya registrado.
- [ ] Registro: el medidor de fuerza de contraseña aparece y valida (8.0+).
- [ ] Alta y edición de dirección; dirección de facturación distinta de la de envío.
- [ ] **Elegir entre al menos dos transportistas**, y con uno que tenga contenido
      extra (punto de recogida).
- [ ] Aceptar condiciones: sin marcarlas, el botón de pedido no debe dejar seguir.
- [ ] **Elegir entre al menos dos métodos de pago** y confirmar que se envía el
      formulario correcto. Es la comprobación crítica de 8.0+.
- [ ] Pedido de importe cero, si la tienda los permite.

### Checkout de una página (solo 9.2, si `ps_onepagecheckout` está activo)
- [ ] Confirmar **quién pinta el checkout**: con el módulo activo, tu
      `checkout/checkout.tpl` no se usa. Verificar contra el HTML servido.
- [ ] Cambiar de dirección de envío y de facturación **sin recargar**, y que el
      resumen del carrito se actualiza.
- [ ] Marcar y desmarcar "usar la misma dirección para facturación".
- [ ] Cambiar de transportista y comprobar que **el total y los gastos de envío
      se recalculan** en `#opc-pay-amount`.
- [ ] Cambiar de método de pago y confirmar que se muestra el
      `#pay-with-{id}-form` correcto.
- [ ] Sin aceptar condiciones, `#opc-pay-button` no debe permitir pagar.
- [ ] Forzar un error de transportista y otro de pago: deben salir los mensajes
      de `#opc-template-carriers-error` y `#opc-template-payment-error`.
- [ ] Comprobar que el indicador de carga (`#opc-template-loader`) aparece.
- [ ] Los modales `#modal-delivery` y `#modal-invoice` abren y cierran.
- [ ] Repetirlo todo como invitado y como cliente registrado.

### Confirmación
- [ ] La página de confirmación muestra el email del cliente (no un hueco vacío).
- [ ] Referencia del pedido, método de pago y totales correctos.
- [ ] Enlace de descarga de factura, si está habilitada.
- [ ] Invitado: aparece el formulario de transformación a cuenta y **funciona**.
- [ ] El pedido consta en el back office con el estado correcto.

### Después de la compra
- [ ] Historial de pedidos y detalle del pedido.
- [ ] Solicitud de devolución (y que los productos virtuales no sean devolvibles, 8.0+).
- [ ] Descarga de producto virtual.

### Regresión general (fuera del checkout)

El checkout es lo crítico, pero una migración toca más superficie. Repaso corto:

- [ ] Home: bloques de destacados, slider, newsletter.
- [ ] Listado de categoría: paginación, orden, y **filtros facetados** — filtrar,
      quitar filtro y comprobar que el listado se recarga por AJAX sin perder la
      maquetación.
- [ ] Buscador: con resultados y sin resultados.
- [ ] Ficha: cambiar de combinación y verificar que se actualizan **precio,
      stock, referencia e imagen**. Es lo primero que rompe un tema mal migrado.
- [ ] Ficha: producto sin stock, producto virtual, pack, producto personalizable.
- [ ] Vista rápida (*quickview*) desde el listado.
- [ ] Cuenta de cliente: registro, login, recuperar contraseña, direcciones.
- [ ] Página de marcas y de proveedores (rehechas en 9.0).
- [ ] CMS, contacto y mapa del sitio.
- [ ] Una página 404.

### Entorno
- [ ] Repetir el pedido en móvil, no solo en escritorio.
- [ ] Con `PS_DEBUG_MODE` activado, sin ningún aviso de Smarty en toda la ruta.
- [ ] Con la caché de Smarty y el CCC (combinar/comprimir) **activados**, que es
      como estará en producción. Bastantes fallos solo salen con CCC activo.
slack-gif-creatoranthropics/skillsKnowledge and utilities for creating animated GIFs optimized for Slack. Provides constraints, validation tools, and animation concepts. Use when users request animated GIFs for Slack like "make me a GIF of X doing Y for Slack."Stars: 198kUpdated Claude CodeCodexVerifiedInstall
ponytailDietrichGebert/ponytailLazy senior dev mode for any coding task: the smallest change that fully solves it, and a reply a busy human understands in one read.Stars: 194kUpdated Claude CodeCodexVerifiedInstall
ponytail-debtDietrichGebert/ponytailHarvest every shortcut: comment into one debt ledger, so deferrals get tracked instead of forgotten. One-shot report.Stars: 194kUpdated Claude CodeCodexVerifiedInstall
ponytail-debtDietrichGebert/ponytailList every `shortcut:` comment (and older `ponytail:` ones) as a debt ledger. One-shot report, changes nothing. Use for "ponytail debt", "what did ponytail defer", "list the shortcuts", /ponytail-debt.Stars: 194kUpdated Claude CodeCodexVerifiedInstall