Metadata-Version: 2.3
Name: platzky_promocode
Version: 0.5.2
Summary: Plugin for revealing promo codes.
License: MIT
Author: ravenw-wing
Requires-Python: >=3.10,<4.0
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Requires-Dist: platzky (>=2.0.0a15,<3.0.0)
Description-Content-Type: text/markdown

# platzky-promocode

A [platzky](https://github.com/platzky/platzky) plugin that adds a click-to-reveal promo code button.

The reveal is a native `<details>` disclosure, so the plugin ships no JavaScript: it works under a strict CSP and is keyboard- and screen-reader-accessible without any script.

## Installation

```sh
pip install platzky_promocode
```

## Configuration

Plugins are configured in platzky's **database**, under a top-level `plugins` object keyed by
plugin name (for the JSON database that is inside `DB.DATA`; the GraphQL and MongoDB backends
store the same structure):

```json
{
    "plugins": {
        "promocode": {
            "is_active": true,
            "allowed_content_types": ["post", "page"],
            "config": {
                "text": "Reveal your discount",
                "color": "#e63946"
            }
        }
    }
}
```

The key (`promocode`) must match the plugin's entry-point name.

| Field | Required | Default | Description |
|---|---|---|---|
| `is_active` | yes | `false` | The plugin is skipped entirely unless this is `true` |
| `allowed_content_types` | yes | `[]` | Content types the plugin may transform. Platzky provides `post`, `page` and `comment`; a host application adds its own. Empty means the plugin loads but transforms nothing |
| `config` | no | `{}` | Plugin settings, see below |

`allowed_content_types` is enforced by the engine and intersected with the content types the
plugin accepts, so it can only narrow them, never widen them. This plugin accepts *every*
content type the application knows — a promo code is inert markup, so there is nowhere it is
unsuited to — which means the grant alone decides where it runs, and naming a type here is
the only thing that switches it on.

Name the types your application actually has. A grant naming an unknown type silently does
nothing, and platzky says so at startup:

```
Plugin PromocodePlugin is granted content type 'field', which this application does not
produce; the grant has no effect. Known types: comment, page, post
```

### Plugin settings (`config`)

| Field | Required | Default | Description |
|---|---|---|---|
| `text` | no | `"Reveal Promo Code"` | Button label before reveal — a plain string, or a `{locale: label}` map for per-language labels |
| `color` | no | `"#4caf50"` | Button background (any CSS color literal) |

### Translated button labels

`text` can be a map of locale codes to labels instead of a single string. The label
matching the visitor's active locale is used, falling back to the first entry in the
map when there is no match:

```json
{
    "plugins": {
        "promocode": {
            "is_active": true,
            "allowed_content_types": ["post", "page"],
            "config": {
                "text": {
                    "en": "Reveal Promo Code",
                    "pl": "Pokaż kod promocyjny",
                    "uk": "Показати промокод"
                }
            }
        }
    }
}
```

## Usage in blog content

Embed the promo code directly in post content using the shortcode:

```markdown
Get 20% off with code [promocode]SUMMER24[/promocode] — don't miss out!
```

An optional `color` attribute overrides the configured button colour:

```markdown
Grab your [promocode color="#e91e63"]SAVE20[/promocode] before it expires!
```

## Usage in a host application's content field

A platzky host application can render the same button from one of its own content fields,
with no per-plugin frontend code. Name the field after the shortcode (`promocode`) — that is
how the host knows to route it here — and give it the code itself, or a dict with per-entry
overrides:

```json
{
    "promocode": { "code": "HABZASPOT", "color": "green" }
}
```

`allowed_content_types` must include whichever content type the host uses for such fields
(see the config above). Nothing else is needed: the shortcode renders the field itself and
the host displays that rendering — there is no bundle to serve and nothing to register on
the frontend.

Add `head` to `allowed_page_sections` as well, so the plugin's stylesheet is injected:

```yaml
plugins:
  promocode:
    is_active: true
    allowed_content_types: ["post", "page"]  # plus the host's own field type, if any
    allowed_page_sections: ["head"]
```

