Pagetool 0.1.1

Et sideværktøj ligger i en .pagetool-fil og indsættes i Pages med typen pagetool. Værktøjet kan følge en artikel, arbejde med en tabel, dele en oplysning eller lade læseren beregne og gemme lokale indstillinger. Pages 0.4.2 indeholder rendereren, så statiske sites og standalone-CLI bruger samme HTML og browserkode.

Kom i gang

Åbn Pagetool fra Ele-menuen eller kommandoen Opret pagetool.
Vælg funktion og filsti. Opret filen.
Angiv eventuelt en .page under Side til forhåndsvisning. Vælg kildens navngivne element i Mål, og vælg et felt, når kilden er en record.
Ret indstillingerne. Tryk Gem fil. Versionstjek forhindrer overskrivning af en fil, der er ændret af en anden editor siden indlæsningen.
Indsæt et Pagetool-element i Pages og vælg filen under Pagetool-fil.

{"type":"pagetool","body":{"src":"tools/laeseguide.pagetool"}}

Samme fil kan bruges med en anden kilde og et nyt værktøjs-id:

{"type":"pagetool","body":{"src":"tools/laeseguide.pagetool","target":"anden-artikel","toolId":"anden-guide"}}

Angiv et stabilt id på den valgte sektion, gruppe, tabel, søgesamling eller record. contentId understøttes også. Navnet kan ændres uden at bryde bindingen. Eksempel: {"type":"group","id":"artikel","parts":[...]}. Et pagetool kan også gemmes som genbrugt .site-element; relative filreferencer følger elementfilens placering. field kan tilsidesættes ved indsættelsen.

Format

{
  "schema": "ele.pagetool/v1",
  "id": "laeseguide",
  "title": "På denne side",
  "function": "reading",
  "source": {"kind":"content","target":"artikel"},
  "placement": {"mode":"sticky","top":20,"mobile":"compact"},
  "options": {
    "wpm":220,"levels":[2,3],"numbered":false,"exclude":[],
    "parts":["time","remaining","progress","toc","previous","next","top"],
    "progress":"bar"
  },
  "storage": {"enabled":false},
  "preview": {"page":"../artikel.page"}
}

preview er kun for editoren og kommer ikke med i den publicerede konfiguration. Selve .pagetool-kilden kopieres heller ikke automatisk til eksporten. Værktøjets HTML, nødvendig konfiguration og runtime er indbygget i siden.

Kilder

kind	Felter	Anvendelse
content	target	`main` eller et stabilt element-id
data	target	Interaktiv Pages-tabel eller søgesamling
field	target, field	Et tekst- eller talfelt i en record, også `produkt.sku`
url		Offentlig URL fra site-modellens `props.url` og `prefix`
section	target	Offentlig URL med afsnittets stabile id
value	value	Fast tekst eller tal
input	value, label	Besøgendes tekst eller tal

Feltkilden publicerer den valgte værdi i værktøjet. Resten af recorden føjes ikke til værktøjets konfiguration. Pages' almindelige eksport af en recordfil er uændret. Brug kun publicerbare data i sidens records. URL-kilder kræver en offentlig HTTP(S)-adresse; localhost afvises. I den native editor findes adressen i nærmeste entydige site-model. Et preview.publicUrl kan angive en præcis adresse ved særlige routes. Pages' egen preview og eksport bruger altid sidens faktiske beregnede URL.

Funktioner og options

function	Centrale indstillinger
reading	wpm, levels, exclude, parts, numbered, progress: bar/ring/percent
context	notes: [{target, text, url?, label?}]
qr	size (80-800 px), correction: L/M/Q/H, caption, downloads
copy / share	label
download	format: csv/json/text, filename, label
print	label; target main eller bestemt sektion
filter	search, fields, ranges, sort (feltnavne)
summary	field til sum og gennemsnit; antal vises altid
compare	fields, max (standard 4)
random	vælger blandt de filtrerede poster
calculator	inputs, formula, label, suffix, digits
convert	units: [{id,label,factor,offset?}], digits
checklist	items: [{id,label}]
reading-settings	tekststørrelse, linjeafstand, læsebredde
view-switch	liste/kort for Pages-søgesamlinger

Input til beregneren har id, label, value, min, max, step. Regneudtryk tillader tal, variabelnavne, parenteser, + - * / % og funktionerne min, max, round, floor, ceil, abs, sqrt. Der køres ingen eval eller brugerdefineret JavaScript. Division med nul og uendelige resultater giver en synlig fejl. Enhedsomregning bruger (værdi * fra.factor + fra.offset - til.offset) / til.factor; den kan derfor også bruges til temperatur.

Tabelfelter svarer til CSV-kolonnenavnene. Søgesamlinger bruger posternes feltnavne. Filtre på arrays virker som tagfiltre; øvrige kategorier matches præcist. Søgningen følger målets eksisterende søgning. Summer og downloads omfatter alle filtrerede rækker, også dem uden for den aktuelle tabelside. CSV-download beskytter tekst, der ellers kan fortolkes som regnearksformler.

Placering og adgang

placement.mode: block, sticky eller bar. Venstre/højre placering vælges med Pages-regioner og områder. Områdernes bredder kan sættes i sidens layout. top er afstanden fra skærmens top og kan tilpasses en fast header. En høj boks får egen scroll. Flere værktøjer i et område, som alene indeholder værktøjer, samles i én sticky-stak, når mindst ét af dem er sticky.

Mobil: block, compact eller hide. Sidstnævnte kræver placement.supplement:true. Sticky ophører på smalle skærme. Indholdet bliver stående. Tastaturfokus er synligt, labels følger felterne, og reduceret bevægelse respekteres. Fremdrift beskriver position gennem indhold, ikke dokumenteret læsning. Uden JavaScript findes artikel, statiske QR-koder, læsetid og afsnitslinks stadig.

Lokal lagring og fælles data

Kun læseposition, tjekliste og læseindstillinger gemmes, når storage.enabled er slået til. Nøglen er ele.pagetool.v1:<offentlig URL>:<værktøjs-id>. Nulstilling sker i værktøjet eller gennem Pages-elementet local-reset. Blokeret eller fyldt storage giver en besked og forhindrer ikke brug af siden. Værktøjerne sender ingen læsepositioner, input eller indstillinger til en server.

En broker pr. dokument deler scroll/resize/input-hændelser. Hvert mål har én ResizeObserver og én MutationObserver. Målinger deles, ordtælling caches og invalideres ved indholdsændring. Tabeller og søgesamlinger stiller deres eksisterende udvalg til rådighed via eleDataset. Pagetool henter ikke datasættet igen. Afmontering og genrendering fjerner abonnementerne. window.elePages.pagetools har mount, unmount, reset, dispose og en lille debug()-optælling.

Eksempler

examples/model.site-model bygger 11 sider. Her er læseguide, kontekstnoter, varenummer/QR/kopi, offentlig adresse/deling, CSV-filter/sum/download, sammenligning/tilfældig udvælgelse, prisberegner/enheder, tjekliste/nulstilling, læseindstillinger/print og søgesamling med liste/kort. Alle tal og produkter er demo.

Afgrænsninger i 0.1.1

Den selvstændige editor viser et enkelt læselayout af kildesidens tekst, tabeller og records. Pages-editoren viser det fulde sidelayout. Medier og alle særlige Pages-elementer gengives ikke i det forenklede kildepreview.
Den native editors kildeside angives som filsti. Elementer og felter vælges derefter ved navn. Nested recordfelter kan angives i rå JSON; top-level felter findes i feltvælgeren.
Datasæt kan være Pages-tabeller eller Pages-søgesamlinger. Andre elementtyper skal tilbyde samme eleDataset-kontrakt, før de kan bindes. Liste/kort er kun til søgesamlinger. Ved dynamiske eksterne datasæt kendes alle feltnavne ikke nødvendigvis før indlæsning; manglende værdier vises tomme.
Sammenligning bruger helst en id-kolonne. Uden id er rækker med identisk indhold ikke særskilte valg. Brug id ved gentagne eller dynamiske poster.
Read settings ændrer målområdets arvede typografi; eksplicit styling i enkelte underafsnit kan kræve en tilpasning af sitets CSS.
Print er browserens printdialog. SVG/PNG-download bruger browserens download.

Udvikling, test og udgivelse

Kør python3 build.py før pakning. Det bygger den selvstændige browserkode, synkroniserer renderer/runtime til Pages og kopierer Pages' tabelmotor til editoren. Native preview starter importerede moduler og kræver ingen ændring af Eles CSP. Statiske sider indeholder den samme motor som almindelig JavaScript. development/bin/publish udfører synkroniseringen for begge pakker.

Pages-tests omfatter bindingsfejl og rendererparitet. Den udvidede DOM-test i development/fixtures/pagetool/test-runner/acceptance.mjs kræver jsdom 26.1.0 og jsqr 1.4.0; den afprøver filtrering, oprydning, beregninger, storage, fallback og uafhængig QR-aflæsning. QR-generator: qrcode-generator 2.0.4, MIT, Kazuhiko Arase. Original kilde og licens ligger under vendor/.