# Dokumentace

Newlogic Core používá pro svojí základní funkcionalitu Gulp. Ten lze různě konfigurovat.

# Config

Nastavení configu lze upravovat v gulpfile.js v rámci inicializace knihovny

Příklad základního nastavení:

// gulpfile.js
import {defineConfig} from  "@newlogic-digital/core";

export default defineConfig({
  styles: {
    purge: {
      content: ['src/scripts/**/*.js', 'src/templates/**/*.twig', 'app/Presenters/templates/**/*.latte', 'temp/cdn/*.js']
    }
  }
})

Newlogic Core používá moderní zápis ES modulů, v package.json je nutné mít nastaveno type: "module". V některých případech se tomuto dá vyhnout přejmenováním .js na .mjs

Do gulpfile.js lze psát i vlastní Gulp tasky. Lze taky přímo využít interní třídy a to Utils, Scripts, Styles, Templates, Icons, Emails, Cms, Serve, Watch a Core.

K instanci configu lze přistupovat pomocí Config.

Pro použití vlastních configů k ostatním nástrojům lze přidat následující configy

• postcss.config.cjs (lze definovat i v gulpfile.js pro jednotlivé moduly, nebo rozšířit)
• tailwind.config.js (lze definovat i v gulpfile.js)
• vite.config.js (kompletně nahradí interní vite config)

# Hlavní nastavení

# errors

• Type: boolean

• Default: true

  Povolení zobrazování chyb při kompilaci, pokud nastane chyba tak se příkaz přeruší. Vhodné pro produkční build aby se předešlo chybám.

# vite

• Type: boolean

• Default: false

  Přepnutí do Vite módu, zejména vhodné pro SPA aplikace ve Vue. Při tomto nastavení se většina tasků Newlogic Core deaktivuje a buildovací proces se plně přenechává Vite.

  Při tomto použití je nutné používat vlastní config vite.config.js

# serve.index

• Type: string

• Default: /public/index.html

  Výchozí stránka která se má otevřít při zapnutí serveru, např. login.html, ve výchozím stavu se otvírá vždycky /public/index.html

  (v cestě musí být i public, je to workaround protože Vite má bug kdy při otevření rovnou na /index.html nefunguje reload při watchi)

# serve.mode

• Type: string

  Možnost natvrdo nastavit mód serveru, lze nastavit dev, build a production. Ve výchozím stavu se nastavuje automaticky podle tasků serve, serve:build, serve:production

  (dev a build používají vždy dev)

# modules

• Type: object

  Dodatečné moduly kterými lze rozšířit funkcionalitu. V současné chvíli lze rozšířit funkcionality .hbs šablon. Ale lze sem naimportovat cokoliv a pak se k instanci dostat přes config a vytvořit si třeba vlastní tasky.

    import hbs from "./src/module.hbs.js";
    
    export default {
        modules: {hbs}
    }
  

# Cesty

# paths.temp

• Type: string

• Default: "temp"

  Zde se ukládají dočasné soubory

# paths.cdn

• Type: string

• Default: "temp/cdn"

  Zde se ukládají stažené cdn odkazy použité v projektu, pro případný lokální vývoj a cache.

# paths.input.root

• Type: string

• Default: "src"

  Hlavní root složka zdrojových souborů

# paths.input.main

• Type: string

• Default: "src/main.json"

  Cesta k hlavnímu nastavovacímu souboru pro šablony

# paths.input.templates

• Type: string

• Default: "src/templates"

  Cesta k kde se nachází šablony

# paths.input.scripts

• Type: string

• Default: "src/scripts"

  Cesta k kde se nachází javascript

# paths.input.styles

• Type: string

• Default: "src/styles"

  Cesta k kde se nachází styly

# paths.input.icons

• Type: string

• Default: "src/icons"

  Cesta k kde se nachází iconfont

# paths.input.emails

• Type: string

• Default: "src/emails"

  Cesta k kde se nachází email šablony a styly

# paths.input.assets

• Type: string

• Default: "src/assets"

  Cesta k kde se nachází další soubory jako obrázky, písma apod.

# serve.output.rewrite

• Type: boolean

• Default: true

  Zda se má obsah načítat relativně ve složce public, např. routování cesty z /public/assets/main.css na /assets/main.css

# paths.output.root

• Type: string

• Default: "dist"

  Hlavní output složka zkompilovaných souborů

# paths.output.scripts

• Type: string

• Default: "dist/scripts"

  Cesta k kde se nachází zkompilované javascript soubory

# paths.output.styles

• Type: string

• Default: "dist/styles"

  Cesta k kde se nachází zkompilované styly

# paths.output.icons

• Type: string

• Default: "dist/styles"

  Cesta k kde se nachází zkompilovaný iconfont

# paths.output.emails

• Type: string

• Default: "dist"

  Cesta kde se nachází zkompilované emaily

# paths.output.emailsWww

• Type: string

• Default: "dist/img"

  Alternativní složka pro zkompilované emaily, vhodné pro šablony do PHP

# paths.output.emailsImg

• Type: string

• Default: "dist/img"

  Cesta k kde se nachází obrázky k emailům

# paths.output.assets

• Type: string

• Default: "dist/assets"

  Cesta kam se kopírují soubory ze input.assets s vlastním hashem v názvu

# Ikony

# icons.format

• Type: string

• Default: "css"

  Výchozí formát souborů stylů, lze nastavit "css" a "less". Při nastavení less se stáhnout soubory pro iconfont ve formátu less.

# icons.name

• Type: string

  Název iconfontu, ve výchozím stavu se bere z názvu projektu. Důležité pro správné stažení z icomoon.io

# icons.filename

• Type: string

• Default: "iconfont"

  Název zkompilovaného souboru iconfontu

# icons.id

• Type: string

• Default: "iconfont"

  Id icomoon.io projektu ze kterého se má iconfont stahovat

# icons.local

• Type: boolean
• Default: false

Zda se má přeskočit stahování iconfontu a používají se jen lokální soubory

# icons.revision

• Type: boolean

• Default: true

  Zda se má u zkompilovaného souboru doplnit do jména hash revize

# icons.optimizations

• Type: boolean

• Default: true

  Zda se má zkompilovaný soubor optimalizovat a minifikovat

# icons.postcss

• Type: object

  Lze vložit vlastní postcss pluginy (jako pole), nebo rozšířit současné přidáním postcss.extend

# Scripty

# scripts.optimizations

• Type: boolean

• Default: true

  Zda se má zkompilovaný soubor optimalizovat a minifikovat

# scripts.revision

• Type: boolean

• Default: true

  Zda se má u zkompilovaného souboru doplnit do jména hash revize

# scripts.legacy

• Type: boolean

• Default: true

  Zda se májí kompilovat javacripty i v es5 legacy formátu

# scripts.polyfillUrls

• Type: string[]

• Default: []

  Doplnění URL na polyfilly které se mají načíst s legacy javascriptama

# scripts.polyfillFeatures

• Type: string

• Default: "default"

  Nastavení polyfill funkcionality které se používají s legacy javascriptem. Zde se použavají nastavení z polyfill.io oddělené čárkou

# scripts.importResolution.directories

• Type: string[]

• Default: []

  V jakých složkách se má mají vytvářet automatické importy k souborům

# scripts.importResolution.filename

• Type: string

• Default: "+.js"

  Název souboru který se vyvtoří pro automatické importy, v tomto souboru jsou naimportovány všechny soubory ze složky

# scripts.importMap.build

• Type: boolean

• Default: true

  Zde se při kompilování mají do souborů doplnit cdn odkazy z importmapy, pokud je vypnuto použijí se node_modules

# scripts.importMap.cdn

• Type: string

• Default: "esm.sh"

  Které CDN se má použít pro generování importmapy, lze nastavit esm.sh, esm.run nebo jspm.dev (vhodné jen pro vývoj)

# scripts.importMap.target

• Type: string

• Default: "es2020"

  používá se pro esm.sh konfiguraci, lze nastavit es2020, esnext, es2015, deno

# scripts.importMap.version

• Type: string

  upřesnění použití esm.sh verze, např. v40

# scripts.importMap.trailingSlashes

• Type: regex

  Které knihovny obsahují podmoduly ke kterém je potřeba přistupovat v cestě modulu. Např. /(dayjs|@fullcalendar|vanillajs-datepicker)/

# scripts.importMap.shortUrl

• Type: boolean

• Default: false

  Zda v importmapách použít zkrácenou URL, např ve formátu esm.sh nebo esm.run

# scripts.importMap.localDownload

• Type: boolean

• Default: false

  Zda se mají soubory z cdn lokálně stáhnout do temp/cdn složky

# Styly

# styles.format

• Type: string

• Default: "css"

  Výchozí formát souborů stylů, lze nastavit "css" a "less". Soubory lze kombinovat, ale pro úplné použití je doporučeno nastavit výchozí formát.

# styles.optimizations

• Type: boolean

• Default: true

  Zda se má zkompilovaný soubor optimalizovat a minifikovat

# styles.clean

• Type: object

• Default: {}

  Možnost rozšířit další nastavení CleanCSS

      {
          level: {1: {specialComments: 0}, 2: {all: false}}
      }
  

# styles.purge.enabled

• Type: boolean

• Default: true

  Zda se má na styly aplikovat knihovna PurgeCSS, která odebere nepoužité styly z finálního buildu.

# styles.purge.content

• Type: string[]

  Které soubory se mají kontrolovat vůči PurgeCSS, např. ['src/scripts/**/*.js', 'src/templates/**/*.twig']

# styles.purge.options

• Type: object

  Další nastavení PurgeCSS, zde lze nastavit které styly se mají vynechávat apod.

      safelist: {
          standard: [/(class|is-|to-|grecaptcha)/],
          deep: [/(ui-wsw|wsw|datepicker)/]
      }
  

# styles.purge.nodeResolve

• Type: boolean

• Default: true

  Zahrnout node_modules knihovny v styles.purge.content

# styles.purge.tailwind

• Type: object

• Default: { keyframes: true }

  Další nastavení PurgeCSS pro Tailwind

# styles.ratio.content

• Type: string[]

• Default: ["main.css"]

  Které soubory se mají kontrolovat pro výpočet aspect ratia, např. ['src/templates/**/*.twig', 'app/Presenters/templates/**/*.latte']

  Kontroluje se atribut data-ratio="4/3", při taskách styles a serve se potom přidají třídy s vlastnostmi aspect-ratio. Při produkčním buildu se použije padding-bottom

# styles.ratio.files

• Type: string[]

• Default: ["main.css"]

  Název css souboru do kterého se mají generovat data-ratio styly

# styles.vendor.cache

• Type: boolean

• Default: true

  Zda se mají načítat vendor CDN odkazy v CSS z cache

# styles.vendor.path

• Type: string

• Default: ""

  Cesta kde se uchovávají vendor importy pro CSS knihovny

# styles.importResolution.subDir

• Type: boolean

• Default: true

  Zda se mají importovat i podsložky

# styles.importResolution.directories

• Type: string[]

• Default: []

  V jakých složkách se má mají vytvářet automatické importy k souborům

# styles.importResolution.filename

• Type: string

• Default: "+.css"

  Název souboru který se vyvtoří pro automatické importy, v tomto souboru jsou naimportovány všechny soubory ze složky

# styles.import

• Type: string[]

• Default: ["all"]

  Jakým způsobem CleanCSS zpracovává importy souborů, ve výchozím nastavení se všechny importy zpracovávají přímo a ve výsledým buildu nejsou tak žádné importy

# styles.join

• Type: object

• Default: {"main.css": ["temp/tailwind.css"]}

  Spojování css souborů dohromady, např. pro tailwind

# styles.tailwind

• Type: object

tailwind: {
  cache: true,
  postcss: {},
  basename: "tailwind.css"
}

Další konfigurace pro tailwind, do postcss lze vložit vlastní postcss pluginy (jako pole), nebo rozšířit současné přidáním postcss.extend

# styles.postcss

• Type: object

  Lze vložit vlastní postcss pluginy (jako pole), nebo rozšířit současné přidáním postcss.extend

# Šablony

# templates.format

• Type: string

• Default: "twig"

  Výchozí formát souborů šablon, lze nastavit "twig" a "hbs". Soubory lze kombinovat, ale pro úplné použití je doporučeno nastavit výchozí formát.

# templates.layout

• Type: string

• Default: "Layout/Main"

  Výchozí cesta k šabloně která se má použít jako layout

# templates.placeholder.webp

• Type: boolean

• Default: true

  Zda se má pro placeholder helper v šablonách použít formát .webp

# templates.placeholder.picsum

• Type: boolean

• Default: false

  Zda se má pro placeholder helper v šablonách použít generování obrázků ze služby Picsum

# templates.placeholder.lorempixel

• Type: string

• Default: ""

  Zda se má pro placeholder helper v šablonách použít generování obrázků ze služby lorempixel, jako parametr se nastavuje preferovaný obrázek třeba "cats"

# Emaily

# emails.removeClasses

• Type: boolean

• Default: false

  Zda se při kompilování emailů mají odstraňovat třídy z elementů v html

# emails.inlineOnly

• Type: boolean

• Default: false

  Zda se při kompilování emailů mají styly aplikovat jenom inline způsobem style=""

# emails.zipPrefix

• Type: string[]

• Default: ["email"]

  Z kterých emailů vytvořit zip, uvádí se prefix jakým mají názvy zkompilovaných šablon začínat

# emails.postcss

• Type: object

  Lze vložit vlastní postcss pluginy (jako pole), nebo rozšířit současné přidáním postcss.extend

# Assety

# assets.revision

• Type: boolean

• Default: true

  Zda se má u zkompilovaného souboru doplnit do jména hash revize

# Tailwind

• Type: boolean

  Zde se nastavuje TailwindCSS, stejným způsobem jako v souboru tailwind.config.js