Creare starter kit per SimplyCod Studio

1. Introduzione

Uno starter kit non è un tema WordPress eseguibile. È un pacchetto di progetto che SimplyCod Studio importa, con pagine, media e impostazioni globali descritti in JSON.

Questa separazione rende il kit indipendente dal tema WordPress attivo e permette al plugin di conservarne una copia interna. Le pagine eliminate possono quindi essere ricreate dalla copia memorizzata senza richiedere nuovamente lo ZIP originale.

2. Avvio rapido

1. Crea una cartella di lavoro, per esempio studio-architettura.
2. Aggiungi nella radice il file simplycod-kit.json.
3. Crea le cartelle pages e media.
4. Scrivi almeno una pagina JSON con version: 2.
5. Inserisci le immagini locali e richiamale tramite token.
6. Definisci design system, intestazione, footer e menu nel manifest.
7. Comprimi il contenuto della cartella, senza una cartella contenitore aggiuntiva.
8. Carica lo ZIP da SimplyCod Studio → Aggiungi nuovo e verifica tutte le pagine.

3. Struttura dello ZIP

studio-architettura.zip
├── simplycod-kit.json
├── pages/
│   ├── home.json
│   ├── progetti.json
│   └── contatti.json
└── media/
    ├── hero.jpg
    ├── progetto-01.jpg
    └── marchio.png

Nello ZIP installabile sono ammessi il manifest, i file pagina JSON e i media supportati. Tieni documentazione, file sorgente, PSD, script e appunti fuori dallo ZIP distribuibile.

4. Il manifest simplycod-kit.json

Il manifest identifica il prodotto, elenca le pagine e contiene la configurazione globale da applicare durante l'importazione.

{
  "format": "simplycod-starter-kit",
  "schema_version": 1,
  "id": "studio-architettura",
  "name": "Studio Architettura",
  "version": "1.0.0",
  "description": "Starter kit per studi professionali.",
  "author": "Nome autore",
  "homepage": "https://example.com",
  "min_plugin_version": "0.22.0",
  "home": "home",
  "pages": [
    { "key": "home", "title": "Home", "slug": "home", "layout": "pages/home.json", "status": "publish" },
    { "key": "projects", "title": "Progetti", "slug": "progetti", "layout": "pages/progetti.json", "status": "publish" },
    { "key": "contact", "title": "Contatti", "slug": "contatti", "layout": "pages/contatti.json", "status": "publish" }
  ],
  "media": {
    "hero": "media/hero.jpg",
    "brand": "media/marchio.png"
  },
  "menu": {
    "name": "Navigazione principale",
    "items": ["home", "projects", "contact"]
  },
  "design": {
    "primary_color": "#176b5b",
    "secondary_color": "#d85b43",
    "text_color": "#182321",
    "surface_color": "#ffffff",
    "font_family": "system",
    "content_width": 1180,
    "button_radius": 4
  }
}

5. Pagine e layout

Ogni file pagina descrive il canvas dell'editor. Usa version: 2 e un array sections. La pagina resta modificabile visualmente dopo l'importazione.

{
  "version": 2,
  "sections": [
    {
      "background": "#10231f",
      "text_color": "#ffffff",
      "padding": 96,
      "background_image": "{{media:hero}}",
      "background_image_id": "{{media_id:hero}}",
      "background_size": "cover",
      "background_position": "center center",
      "background_position_x": 50,
      "background_position_y": 50,
      "background_attachment": "scroll",
      "overlay_color": "#10231f",
      "overlay_opacity": 58,
      "columns": [
        {
          "width": 100,
          "blocks": [
            { "type": "heading", "content": "Spazi pensati per vivere", "level": "h1" },
            { "type": "text", "content": "Progettiamo luoghi essenziali, luminosi e durevoli." },
            { "type": "button", "label": "Scopri i progetti", "url": "{{page:projects}}", "style": "primary" }
          ]
        }
      ]
    }
  ]
}

6. Sezioni e colonne

Una sezione contiene impostazioni visive e da una a più colonne. La somma delle larghezze dovrebbe essere 100. Su schermi piccoli l'editor gestisce l'impilamento delle colonne.

{
  "background": "#f2f6f4",
  "text_color": "#182321",
  "padding": 72,
  "columns": [
    {
      "width": 45,
      "blocks": [
        { "type": "image", "url": "{{media:portrait}}", "image_id": "{{media_id:portrait}}", "content": "Ritratto del professionista" }
      ]
    },
    {
      "width": 55,
      "blocks": [
        { "type": "heading", "content": "Un progetto su misura", "level": "h2" },
        { "type": "text", "content": "Dall'idea alla consegna, seguiamo ogni dettaglio." }
      ]
    }
  ]
}

Sfondi

Per immagini proporzionalmente diverse dall'area usa cover e scegli il punto focale con background_position. Usa contain quando l'immagine deve essere interamente visibile. background_attachment può essere scroll o fixed.

7. Componenti disponibili

{
  "type": "gallery",
  "columns": 3,
  "images": [
    { "id": "{{media_id:project_1}}", "url": "{{media:project_1}}", "alt": "Casa sul lago" },
    { "id": "{{media_id:project_2}}", "url": "{{media:project_2}}", "alt": "Interno contemporaneo" }
  ]
}

8. Immagini e media

SimplyCod Studio accetta JPG, JPEG, PNG, GIF, WebP e AVIF. Le immagini vengono importate nella Libreria Media di WordPress. I PNG mantengono la trasparenza; WebP e AVIF dipendono dal supporto del server WordPress.

"media": {
  "hero": "media/hero.jpg",
  "portrait": "media/portrait.jpg",
  "brand": "media/marchio.png",
  "project_1": "media/progetto-01.jpg"
}

{
  "type": "image",
  "url": "{{media:brand}}",
  "image_id": "{{media_id:brand}}",
  "content": "Marchio Studio Architettura",
  "width": 180
}

• Compila sempre il testo alternativo per immagini informative.
• Usa JPG o WebP per fotografie; PNG per loghi e trasparenze.
• Ridimensiona le foto alla risoluzione realmente necessaria.
• Usa nomi file minuscoli, senza spazi né caratteri speciali.
• Non collegare immagini temporanee ospitate su siti esterni.

9. Token portabili

I token vengono risolti durante l'importazione. Evitano ID WordPress e URL legati al sito su cui il kit è stato creato.

10. Moduli nativi

Il componente form genera campi reali, effettua validazione server, usa protezioni nonce e honeypot e invia il messaggio con wp_mail().

{
  "type": "form",
  "title": "Parliamo del tuo progetto",
  "recipient": "",
  "subject": "Nuova richiesta dal sito",
  "submit_label": "Invia la richiesta",
  "success_message": "Grazie, la richiesta è stata inviata.",
  "fields": [
      { "type": "text", "name": "full_name", "label": "Nome e cognome", "required": true },
      { "type": "email", "name": "email", "label": "Email", "required": true },
      { "type": "tel", "name": "phone", "label": "Telefono" },
      { "type": "select", "name": "project_type", "label": "Tipo di progetto", "options": ["Nuovo sito", "Restyling", "E-commerce"] },
      { "type": "textarea", "name": "message", "label": "Raccontaci la tua idea", "required": true },
    { "type": "checkbox", "name": "privacy", "label": "Accetto il trattamento dei dati", "required": true }
  ]
}

Tipi supportati: text, email, tel, url, number, date, select, textarea e checkbox. I nomi dei campi devono essere univoci e compatibili con sanitize_key().

11. Menu e collegamenti

Il menu è definito nel manifest e collega le pagine tramite le loro chiavi. L'action button dell'header è un elemento separato e non deve essere duplicato fra le voci del menu.

"menu": {
  "name": "Menu principale",
  "items": ["home", "services", "contact"]
}

Le voci sono chiavi di pagine dichiarate nel manifest. Per un collegamento esterno usa un pulsante o un componente social nella pagina. Per un pulsante interno usa url: "{{page:contact}}"; per un'ancora usa menu_anchor e collega il pulsante a #id-ancora.

12. Sistema di design

Il blocco design crea una base coerente per tutte le pagine. Scegli colori con contrasto sufficiente e valori adatti sia al desktop sia al mobile.

"design": {
  "primary_color": "#176b5b",
  "secondary_color": "#d85b43",
  "text_color": "#182321",
  "surface_color": "#ffffff",
  "font_family": "system",
  "content_width": 1180,
  "button_radius": 4,
  "canvas_template": 1
}

13. Header e footer

Il kit può fornire una configurazione iniziale per intestazione e piè di pagina. L'utente potrà poi modificarli graficamente nelle rispettive aree di SimplyCod Studio.

"header": {
  "layout": "standard",
  "brand_type": "logo",
  "logo_id": "{{media_id:brand}}",
  "background_color": "#ffffff",
  "text_color": "#182321",
  "height": 76,
  "sticky": true,
  "logo_width": 190,
  "cta_label": "Richiedi un preventivo",
  "cta_url": "{{page:contact}}",
  "cta_new_tab": 0,
  "items": [
    { "id": "brand", "type": "brand" },
    { "id": "spacer", "type": "spacer" },
    { "id": "navigation", "type": "navigation" },
    { "id": "cta", "type": "cta" }
  ]
},
"footer": {
  "layout": "centered",
  "show_brand": 1,
  "background_color": "#17211f",
  "text_color": "#ffffff",
  "padding": 48,
  "description": "Progettiamo luoghi essenziali e durevoli.",
  "copyright": "(c) {year} {site}",
  "items": [
    { "id": "brand", "type": "brand" },
    { "id": "navigation", "type": "navigation" },
    { "id": "copyright", "type": "copyright" }
  ]
}

I tipi ammessi nell'header sono brand, navigation, cta e spacer. Nel footer sono disponibili anche socials, copyright e row. Valida sempre il pacchetto contro lo schema SDK della versione minima dichiarata.

14. Creare e validare il pacchetto

1. Controlla che tutti i JSON siano sintatticamente validi.
2. Verifica che ogni file citato nel manifest esista rispettando maiuscole e minuscole.
3. Rimuovi file nascosti come .DS_Store e cartelle di sviluppo.
4. Comprimi il contenuto della cartella, non la cartella stessa.
5. Installa il kit in un WordPress pulito e controlla frontend, editor e mobile.

cd studio-architettura
zip -r ../studio-architettura-1.0.0.zip simplycod-kit.json pages media

unzip -l studio-architettura-1.0.0.zip

15. Versioni, aggiornamenti e ripristino

Mantieni lo stesso id nelle nuove versioni e incrementa version. La copia del blueprint conservata da SimplyCod Studio permette di ricreare pagine mancanti senza disporre nuovamente dello ZIP.

La reinstallazione ripristina le pagine eliminate, ma non dovrebbe sovrascrivere automaticamente le pagine esistenti che l'utente ha modificato. Progetta quindi ogni versione pensando a questo comportamento conservativo.

16. Esempio completo commentato

Il pacchetto ufficiale di esempio raccoglie in un unico kit le casistiche più importanti:

• Tre pagine con navigazione interna tramite token.
• Fotografie JPG e un marchio PNG con trasparenza.
• Hero con sfondo, overlay e allineamento controllato.
• Galleria e componenti immagine con URL e ID media.
• Modulo contatti nativo con campi, privacy e validazione.
• Design system globale riutilizzato dalle pagine.

17. Diagnostica

18. Checklist prima della distribuzione

• ID del kit stabile, univoco e documentato.
• Versione aggiornata e note di rilascio disponibili.
• Da 1 a 20 pagine, tutte presenti e valide.
• Nessun URL o ID WordPress del sito di sviluppo.
• Media locali ottimizzati, inclusi test JPG e PNG.
• Test alternativi delle immagini compilati.
• Menu, home, pulsanti e ancore verificati.
• Moduli testati, anche con errori di validazione.
• Header e footer controllati su desktop e mobile.
• Ripristino di una pagina eliminata verificato.
• ZIP entro i limiti e privo di file non ammessi.
• Licenze dei materiali compatibili con la distribuzione.