# SimplyCod Starter Kit SDK

This folder documents the version 1 package format accepted by SimplyCod Studio.

## Package structure

Create a ZIP whose root contains the manifest. Do not wrap the files in an additional folder.

```text
simplycod-kit.json
pages/
  home.json
  contact.json
media/
  hero.jpg
  transparent-mark.png
```

Only the following files are accepted:

- `simplycod-kit.json`
- JSON layout files under `pages/`
- JPG, PNG, GIF, WebP, and AVIF images under `media/`

PHP, JavaScript, SVG, HTML, CSS, and executable files are rejected. Packages are limited to 32 MB compressed, 30 MB extracted, 150 entries, 8 MB per entry, and 20 pages.

## Manifest

See `example/simplycod-kit.json` for a complete working manifest.
The machine-readable definition is available in `simplycod-kit.schema.json`.

Required fields:

- `format`: must be `simplycod-starter-kit`
- `schema_version`: must be `1`
- `id`: unique lowercase slug for the package
- `name`: display name
- `version`: package version
- `pages`: one to twenty page definitions

Each page requires `key`, `title`, `slug`, and `layout`. The layout can be an inline object or a path such as `pages/home.json`. Page status accepts `draft` or `publish` and defaults to `draft`.

Optional fields:

- `min_plugin_version`: minimum compatible SimplyCod Studio version
- `home`: published page key to set as the static home page; draft pages are never assigned automatically
- `menu`: menu name and ordered page keys
- `media`: map of media keys to image paths
- `design`, `header`, and `footer`: settings applied after import

## Portable tokens

Use these strings anywhere inside layouts, header settings, or footer settings:

- `{{page:contact}}`: permalink of the imported page whose key is `contact`
- `{{page_id:contact}}`: WordPress ID of that page
- `{{media:hero}}`: URL of the imported image mapped as `hero`
- `{{media_id:hero}}`: WordPress attachment ID of that image

The importer resolves tokens only after WordPress has created the corresponding records.

Always use both the attachment ID and URL when the component supports them:

```json
{
  "type": "image",
  "image_id": "{{media_id:brand_mark}}",
  "url": "{{media:brand_mark}}",
  "content": "Alternative text"
}
```

For section backgrounds use `background_image_id` and `background_image`. For galleries use `id` and `url` in every image object. SimplyCod Studio can recover the URL from the attachment ID when one value is missing.

Direct paths such as `media/hero.jpg`, `./media/hero.jpg`, and `/media/hero.jpg` are accepted for compatibility and converted to portable media tokens during import. Tokens remain the recommended format.

## Image formats

The package accepts `.jpg`, `.jpeg`, `.png`, `.gif`, `.webp`, and `.avif` files. PNG alpha transparency is preserved. Actual WebP and AVIF processing depends on the image support enabled in the WordPress server.

Guidelines:

- use JPG for photographic backgrounds where transparency is not required;
- use PNG for logos, marks, interface graphics, and images requiring transparency;
- keep every image below 8 MB;
- use lowercase portable filenames containing letters, numbers, dots, hyphens, or underscores;
- provide meaningful alternative text in image and gallery components;
- never embed image data as Base64 inside JSON.

## Form component

Version 0.22.0 adds native forms to starter-kit layouts:

```json
{
  "type": "form",
  "title": "Request information",
  "submit_label": "Send request",
  "success_message": "Thank you. We will reply shortly.",
  "recipient": "optional@example.com",
  "fields": [
    {
      "type": "email",
      "name": "email",
      "label": "Email",
      "placeholder": "name@example.com",
      "required": true
    },
    {
      "type": "select",
      "name": "topic",
      "label": "Topic",
      "options": ["Website", "Portal", "E-commerce"],
      "required": true
    }
  ]
}
```

Supported field types are `text`, `email`, `tel`, `url`, `number`, `date`, `select`, `textarea`, and `checkbox`. Field names are sanitized keys and must be unique within the form. Select options are plain strings.

When `recipient` is empty, submissions are sent to the WordPress administration email. Forms include nonce validation, server-side field validation, a honeypot, safe sanitization, and Reply-To handling for the first valid email field. Starter-kit authors must still provide suitable privacy wording and configure mail delivery for the destination WordPress installation.

## Complete example

The `example/` source and bundled `simplycod-complete-example-kit.zip` demonstrate the complete format. The package contains three draft pages, JPG and transparent PNG media, a gallery, portable page links, a menu, global settings, and a working contact form.

## Safety and rollback

The complete archive and manifest are validated before content is created. If page, media, menu, or settings import fails, SimplyCod Studio removes the records created by that import and restores the previous global settings.

Uploading the same package ID again is treated as a repair operation. Pages that are still available keep their edits, while missing or trashed pages are recreated from the package and their menu links are repaired. If every expected page exists, no content or settings are changed.

Install the included `simplycod-complete-example-kit.zip` from **SimplyCod Studio > Starter Kits** to test the workflow.