# ocyan.plugin.carbasa

`ocyan.plugin.carbasa` is a presentation-oriented Ocyan plugin that layers Carbasa theme behavior on top of the Ocyan/Coyote stack. It provides frontend templates, SCSS, JavaScript behavior, and Wagtail block additions that shape navigation, page sections, and optional webshop presentation.

This plugin does not expose standalone business workflows. Its value is in theme integration: headers, navigation behavior, page blocks, webshop styling, and frontend interaction patterns that extend existing Ocyan and Wagtail plugins.

## What Carbasa solves

Carbasa exists to make a Coyote-based site or webshop feel like a complete theme package without forcing project-specific template forks everywhere. In practice it provides:

- Carbasa-specific frontend templates and layout variants
- reusable Wagtail blocks
- header and megamenu behavior
- search and mobile menu interaction behavior
- optional webshop presentation integration when Oscar/webshop mode is enabled

## How it integrates

### Ocyan

The plugin is discovered through `config.json` and `entrypoint.py`:

- `config.json` declares `ocyan.plugin.carbasa` as the Ocyan plugin entry
- `entrypoint.py` contributes app extensions and settings through `CarbasaConfig`

At runtime the plugin registers itself with:

- `oxyan.themes`
- `ocyan.plugin.coyote`
- optionally `ocyan.plugin.barebone` when webshop mode is not active

### oxyan.themes

Carbasa is primarily a theme-layer plugin. Most of its effect is delivered through:

- template overrides
- SCSS/CSS
- frontend JavaScript

The plugin expects the host project to already provide the broader theme infrastructure that resolves these templates and assets.

### Coyote blocks

Carbasa extends the Wagtail/Coyote side with additional frontend block templates and frontend behavior. The block definitions live in:

- `ocyan/plugin/carbasa/blocks.py`

The visual rendering lives mostly in:

- `ocyan/plugin/carbasa/templates/carbasa/`
- `ocyan/plugin/carbasa/templates/coyote/`
- `ocyan/plugin/carbasa/templates/partials/`

### Oscar / webshop mode

When `config.is_webshop` is true, Carbasa additionally registers its webshop extension and extends:

- `ocyan.plugin.carbasa.webshop`
- `ocyan.plugin.coyote.oxyan_extension`
- `ocyan.plugin.wagtail_oscar_integration...`

This means webshop styling and template behavior only become active when the host project is running in webshop mode.

## Architecture summary

Carbasa is intentionally light on backend code.

It currently has:

- app config: `apps.py`
- plugin entrypoint: `entrypoint.py`
- block definitions: `blocks.py`
- frontend templates
- SCSS/CSS assets
- frontend JavaScript assets
- optional webshop extension code

It currently does **not** provide:

- Django models
- database migrations
- standalone views
- standalone URL patterns
- admin-only business workflows

That means most production risk in this plugin is frontend risk:

- template correctness
- accessibility
- keyboard behavior
- null-safe JavaScript behavior
- asset pipeline clarity

## Installation and setup

Install the package in the same way as the rest of the Ocyan plugin stack, typically as an editable source or package dependency in the host project.

Required parent plugins and dependencies:

- `ocyan.core`
- `ocyan.plugin.coyote`
- `oxyan.themes`

Optional webshop-related dependencies:

- `ocyan.plugin.wagtail_oscar_integration`
- Oscar/webshop project configuration that enables `config.is_webshop`

Typical local integration pattern in Kitchensink/Ocyan projects:

1. add the source to the project dependency/buildout configuration
2. include the plugin in Ocyan plugin discovery
3. run Django checks
4. run a migration dry-run to confirm the plugin remains migration-free
5. verify frontend templates and assets in the browser

## Public and admin URLs

Carbasa does not expose its own standalone public or admin URLs.

Instead it affects rendering indirectly through:

- template overrides
- block templates
- theme layout templates
- optional webshop templates

If a page appears to “use Carbasa”, it is usually because the host project is rendering Carbasa templates through the theme/plugin extension system rather than because Carbasa registered a direct route.

## Template override strategy

Carbasa relies on template-level integration. Key template areas include:

- `templates/base.html`
- `templates/layout.html`
- `templates/layout_3_col.html`
- `templates/carbasa/...`
- `templates/coyote/...`
- `templates/partials/...`
- `templates/roadrunner_bs4/...`

The plugin should be treated as a presentation/theme plugin. Template changes should be reviewed carefully because they affect:

- accessibility
- responsive behavior
- keyboard interaction
- webshop rendering
- site-wide navigation/header behavior

## Static asset strategy

### Runtime JavaScript source of truth

The current runtime JavaScript source of truth is:

- `ocyan/plugin/carbasa/static/carbasa/js/carbasa.js`

This is the file currently loaded by templates, specifically through `templates/layout.html`.

### Bundle artifacts

These files exist in the repository:

- `ocyan/plugin/carbasa/static/index.js`
- `ocyan/plugin/carbasa/static/index.js.map`

They are generated bundle artifacts from the plugin asset pipeline. They are **not currently loaded by Carbasa templates**.

That means:

- they should not be treated as the runtime JS source of truth
- they should not be edited casually by hand
- they should not be removed without first verifying the build and release pipeline that produced them

### Source/build pipeline

The source-side asset pipeline currently includes:

- `js/carbasa.js`
- `webpack.config.js`
- `prd.config.js`
- `package.json`

At the moment:

- `js/carbasa.js` is the webpack entry source
- templates still load `static/carbasa/js/carbasa.js`
- bundle artifacts are present but not wired into runtime templates

This split is important. Future asset refactors should verify the actual runtime path before changing or rebuilding bundle outputs.

## SCSS/CSS organization

Carbasa styling is delivered through SCSS/CSS files inside the plugin’s static tree and referenced by host templates.

Key principles for maintenance:

- keep large styling out of templates
- prefer SCSS/CSS files under the plugin static tree
- avoid inline `<style>` blocks
- keep frontend behavior and styling changes scoped to the relevant component blocks

## `config.json` settings

Carbasa exposes the following Ocyan settings in `config.json`.

### `same_hight_product_image`

- type: boolean
- default: `false`
- purpose: makes product images render with the same height

Important:

- this key contains a legacy typo: `same_hight_product_image`
- the typo is preserved for backward compatibility
- do **not** rename it in-place without a deliberate alias/migration strategy

If a future cleanup is desired, the safer approach is to add a compatibility alias first and only then phase in a corrected key name.

### `compressed_gallery`

- type: boolean
- default: `false`
- purpose: compresses the gallery into a four-block gallery layout

### `header_centered`

- type: boolean
- default: `false`
- purpose: centers the header logo

### `header`

- type: dropdown
- default: `basic`
- allowed values:
  - `basic`
  - `big`
  - `mega`

This setting works together with the `OXYAN_HEADER_OPTIONS` values contributed from `entrypoint.py`.

## Maintenance notes

This plugin is presentation/theme-oriented.

That has a few consequences:

1. It has no models, migrations, views, or URLs to stabilize backend behavior.
2. Most operational risk lives in templates, accessibility, and frontend JavaScript.
3. Regression testing should prioritize navigation, keyboard interaction, layout rendering, and webshop presentation.
4. Generated bundle files should not be changed unless the build pipeline is explicitly verified.

## Testing and verification

Recommended local checks:

```bash
./.venv/bin/python -m ruff check ocyan/plugin/carbasa
/path/to/kitchensink/bin/black --check --exclude 'migrations/*' ocyan
/path/to/kitchensink/.venv/bin/python -m unittest discover -s ocyan/plugin/carbasa/tests -p 'test*.py'
/path/to/kitchensink/bin/manage check
/path/to/kitchensink/bin/manage makemigrations --check --dry-run carbasa
```

## Release checklist

Before shipping a Carbasa change:

1. run Ruff
2. run Black check
3. run Carbasa smoke tests
4. run host-project `bin/manage check`
5. run migration dry-run and confirm no changes are detected
6. manually verify browser behavior for:
   - header
   - search overlay / search toggle
   - megamenu
   - mobile menu
   - tabs block
   - accordion block
   - dropdown interactions
   - webshop catalogue and detail pages if webshop mode is enabled

## Browser/manual verification checklist

Use manual browser verification for:

- desktop header behavior
- mobile navigation behavior
- Escape key behavior in search/menu/mega menu
- tabs keyboard and aria wiring
- accordion semantics and toggle behavior
- optional webshop gallery/product listing behavior

## Known limitations

Current limitations to keep in mind:

- the asset pipeline has two JavaScript tracks (`js/carbasa.js` and `static/carbasa/js/carbasa.js`) and only one is the live runtime path
- bundle artifacts are present without being the active template-loaded runtime source
- frontend behavior still needs browser verification after structural changes
- accessibility and semantic cleanup should continue to be treated as ongoing maintenance work

## Recommended future improvements

Likely future maintenance work:

- verify and simplify the asset build pipeline
- decide whether generated bundle artifacts should remain committed
- continue accessibility hardening for presentation templates
- document host-project expectations for theme override precedence more explicitly
