Shoporama templates

Herunder finder du information til hvordan du udvikler et Shoporama-tema.

Overblik

Overordnet set består et Shoporama-tema er en række html-filer der ligger i en mappe på vores ftp-server. Template-sproget i de enkelte filer er Smarty, som nævnes herunder.

I de enkelte templates er der adgang til en række objekter og metoder. Dem kan du læse mere om i vores Template API.

Kontakt os på support@shoporama.dk hvis du har spørgsmål.

Smarty

Motoren i vores template-system er baseret på Smarty.

Vi har af bagudkompatible årsager version 2.6 installeret, men den vedligeholder vi ikke længere, og vi anbefaler at alle bruger version 4.x. Versionen indstilles under indstillinger for shoppen.

Bemærk at denne dokumentation tager kun højde for version 4.x.

Forskellen på standard Smarty og vores er at vi bruger <{ og }> som delimiter. Dvs. syntaksen er:

<h1>Velkommen til <{$webshop->getName()|escape}></h1>

Tips

Undersøg indhold

Hvis du er i tvivl om hvad en variabel er, eller hvad en funktion returerer, kan du køre den igennem var_dump. Hvis du har fat i et objekt vil du altid kunne se hvilke metoder der findes i vores Template API.

Du bruger var_dump på følgende måde:

<{$order|var_dump}>

Check objekter

I nogle tilfælde er det relevant at sikre sig, at hvis man bruger en variabel som et objekt, at det også er et objekt. Ellers vil templaten ikke virke. Vi stiller nogle globale variabler som fx $product, og $webshop med flere. For de variabler er det ikke nødvendigt. Der kan checkes på en af følgende måder:

<{* Typisk tilstrækkelig *}>
<{if $profile}>
	<{$profile->getName()}>
<{/if}>

<{* Lidt grundigere *}>
<{if is_object($profile)}>
	<{$profile->getName()}>
<{/if}>

<{* Meget grundig *}>
<{if is_a($profile, "SafeProfile")}>
	<{$profile->getName()}>
<{/if}>

Debug

Hvis du vil se hvilke variabler der er tilgælgelig på den side du udvikler kan du sætte Smarty i debug-mode og se variablerne i et nye vindue. Indsæt følgende kode i din template:

<{debug}>

Læs mere om Smarty4 her: Smarty 4 Documentation.

Filstruktur

Du får ftp-adgang til din shop, og i roden af dit bibliotek skal du lægge dit tema. Navnet på mappen er navnet på temaet.

Sti	Funktion
`/{navn}`	Hovedmappe til dit tema
`/{navn}/components`	Mappe med komponenter til Page Builder
`/{navn}/components/sections.json`	Liste over hvilke sections der må indsættes på hvilke sider
`/{navn}/components/tags.json`	Tags til brug i temaet
`/{navn}/components/sections`	Mappe til de enkelte sections-filer
`/{navn}/extensions`	Udvidelser til Shoporamas indbyggede datatyper.
`/{navn}/templates`	Mappe til templates
`/{navn}/templates/mails`	Mappe til mail-templates

Det er som udgangspunkt frit hvordan filerne i /{navn}/templates navngives. Dog med nogle få undtagelser:

Sti Funktion

/{navn}/templates/global.html

Den overordnede side der indeholder strukturen for hele shoppen. Selve indholdet indsættes der hvor denne template viser <{$contents}>, som er en speciel variabel der kommer fra nedenstående index.html. Dvs. en meget simpel global.html kunne se sådan ud:

<!DOCTYPE html>
<html>
<head>
	<title><{$webshop->getName()|escape}></title>
</head>

<body>

	<nav>
		<!-- Din navigation -->
	</nav>

	<div>
		<{$contents}>
	</div>

</body>

</html>

/{navn}/templates/index.html

Denne template bruges til at vise indholdet af hvad-end-man-nu-ser. Dvs. et produkt, en landingsside, eller kurven m.m. Et forslag til hvordan den kan se ud er følgende:

<{if $inc}>

	<{include file=$inc}>

<{elseif $category}>

	<{include file="category.html"}>

<{elseif $landing_page}>

	<{include file="landing_page.html"}>

<{elseif $product}>

	<{include file="product.html"}>

<{elseif $page}>

	<{include file="page.html"}>

<{elseif $blog_post}>

	<{include file="blog_post.html"}>

<{/if}>

/{navn}/templates/printed_invoice.html Bruges fra admin hvis man ønsker at printe en følgeseddel. Indholdet af ordren vil altid ligge i variablen $order.

/{navn}/templates/mails

Mappe til mail-templates. Skal indeholde følgende filer:

File name	Content	Relevante variabler
`after_purchase.html`	Hvis du ønsker at sende dine kunder en mail noget tid efter de har handlet.	`$products`, `$order`
`basket_mail.html`	Mail der automatisk kan sendes hvis kunden har indtastet sin mail-adresse, men ikke checket ud.	`$basket_url`, `$basket`
`in_stock_mail.html`	Mail der kan sendes hvis en vare kommer på lager igen, og kunden har skrevet sig op.	`$product`
`invoice_dropshipping.html`	Mail til dropshipping-leverandør.	`$products`, `$order`
`invoice.html`	Fakturaen for ordren.	`$order`
`order_credit.html`	Mail hvis ordren krediteres.	`$order`
`order_sent.html`	Mail der sendes når ordren afsendes.	`$order`
`payment_mail.html`	Hvis kunden har gennemført en bestilling, men ikke gennemført betalingen.	`$payment_url`, `$order`
`product_review_mail.html`	Mail der kan sendes til kunden hvis man ønsker anmeldelser.	`$order`
`user-reset-password-mail.html`	Mail med link til nulstil password. For at få URL'en skal der bruges `$customer->getTokenUrl()`.	`$customer`
`user-welcome-mail.html`	Velkomst-mail hvis kunden opretter en konto i shoppen.	`$customer`

Generelt om strukturen i mail-templates

Som udgangspunkt opdeles alle mail-templates i to dele. Den ene del til emnet og den anden del til indholdet. Måden templaten inddelen er ved at checke om variablen $subject er sat. Hvis den er, skal templaten returnerer emnet. Ellers skal den returnere indholdet. Eks.:

<{if $subject}>

	Emnet på mailen

<{else}>

	Indholdet af mailen

<{/if}>

Dog med undtagelse af de to mails invoice.html og invoice_dropshipping.html hvor emnet styres via admin admin og ikke via templaten.

Billeder, stylesheets, m.m. i temaet

Du må lægge dine billeder, og stylesheets, m.m. hvor du ønsker, men vi anbefaler at du fx bruger en struktur som /{navn}/images og /{navn}/css. Når du henviser til filerne skal du bruge variablen $theme_url der indeholder URL'en til temaet. Bemærk at den kan ændre sig, så du kan ikke altid skrive URL'en manuelt ind i dit tema. Men variablen vil altid virke. Hvis du vil linke til billedet /{navn}/images/img.gif skal du derfor skrive <img src="<{$theme_url}>/images/img.gif">.

Udvidelser

Shoporama indeholder nogle forskellige datatyper. Fx produkter og kategorier. De datatyper indeholder nogle foruddefinerede felter som fx titel, beskrivelse, og pris. Det er muligt at udvide de mest almindelige datatyper med sine egne felter. Udvidelser skal placeres i temaet i filen /{navn}/extensions/{datatype}.json, hvor de mulige datatyper er product, landing_page, category, static_page, og blog_post.

Json-filen skal indeholde et array af grupper, hvor hver gruppe indeholder en række felter. Formatet er følgende:

Field Content Type

name Navnet på gruppen af felter string

description Længere beskrivelse string

fields Array af felter array

Field	Content
`title`	Titlen på feltet
`description`	Længere beskrivelse hvis relevant
`id`	ID til at hente værdien ud med
`type`	En af følgende typer: `multi`, `list`, `text`, `richtext`, `longtext`, `number`, `bool`, `image`, `images`
`options`	Værdier hvis `type` er enten `list` eller `multi`. Formatet er "options": { "foo": "Foo", "bar": "Bar", "baz": "Baz" }
`placeholder`	Evt. placeholder
`default`	Default værdi

Nedenstående er et eksempel på json i filen extensions/product.json:

[
	{
		"name": "Billeder",
		"description": "Her kan du tilføje billeder",
		"fields": [
			{
				"title": "Et enkelt billede",
				"id": "my-image",
				"type": "image"
			},
			{
				"title": "En serie af billeder",
				"id": "my-images",
				"type": "images"
			}
		]
	},
	{
		"name": "Indstillinger",
		"description": "Herunder kan du indstille diverse",
		"fields": [
			{
				"title": "my-setting",
				"description": "Vælg flere ..",
				"id": "tags",
				"type": "multi",
				"options": {
					"foo": "Foo",
					"bar": "Bar",
					"baz": "Baz"
				}
			}
		]
	}
]

Giver følgende interface:

På de datatyper der understøtter udvidelser skal værdierne hentes ud via metoden getExtensionValue('ID'), hvor ID er ID'et fra json-filen. Afhængig af datatypen på feltet kan indholdet returneres som en tekst, array, eller objekt. Eks.:

Materiale: <{$product->getExtensionValue('materiale')}>

Eller:

<{if $img = $product->getExtensionValue('img')}>
	<{$img->getSrc(50, 50, 'fit')}>
<{/if}>

Eller hvis man vil loope billeder igennem:

<{foreach $product->getExtensionValue('my-images') as $image}>
	<img src="<{$image->getSrc(50, 50, 'box')}>">
<{/foreach}>

Globale variabler

Variabel Content

$webshop

Generelt objekt der indeholder webshoppen, men indeholder også en del funktioner til at trække diverse data ud af shoppen. Læs mere om Webshop objektet. Eksempel på hvordan $webshop bruges til at trække en liste over kategorier:

<{foreach $webshop->getCategories() as $category}>
	<{$category->getName()|escape}>
<{/foreach}>

$product Produkt-objektet hvis du ser en produktside

$category Kategori-objektet hvis der vises en kategori

$landing_page Landingsside-objektet hvis du er inde på en landingsside

$page Objektet til den statiske side hvis du er inde på sådan en

$blog_post Bloginglægs-objektet hvis du ser et blogindlæg

$inc

Navnet på den specielle - ikke dynamiske, side der afvikles. Værdierne til denne kan være also.html, search.html, basket.html, address.html, shipping.html, approve.html, payment.html, thanks.html, order.html, product_review.html, subscription.html, blog.html, user-sign-up.html, user-sign-in.html, user-sign-out.html, user-edit.html, user-reset-password.html, user-profile.html, user-orders.html, user-subscriptions.html, user-change-card.html, 404.html, 410.html.

Da vi validerer indholdet kan du med fordel bruge nedenstående kode, og på den måde styre visningen i en include-fil:

<{if $inc}>
	<{include file=$inc}>
<{/if}>

$shipping Den valgte fragtmetode

$pager_array Pager hvis den aktelle siden indeholder sidebladring. Indholdet af array'et er elementerne max, current, total, url, og first_url.

$pager Pager-objekt.

$current_url Den absolutte URL på den aktuelle side.

$top_url Reletiv URL til den aktuelle side.

$get Et array med alle GET-variabler.

$post Et array med alle POST-variabler.

$cookie Et array med alle COOKIE-variabler.

$user_id ID'et på shopejeren der er logget ind i admin. Denne variabel sættes hvis man følger et link til shoppen fra admin.

$customer Customer-objekt hvis kunden er logget ind i shoppen.

$remote_addr IP-adressen på kunden der ser siden.

$admin_url URL til Shoporama-admin

$selected_payment_gateway ID'et på den valgte betalingsgateway.

$join_mailinglist En indikator om kunden har markeret at denne vil tilmeldes nyhedsbrev.

$basket_url URL til kurven og dens indhold.

$products_matches ID'er på produkter der har matchet en rabat eller kampagne

$campaign_ids ID'er på kampagner hvis produkterne i kurven matcher en kampagne.

$campaigns Hvis der er en aktive kampagner.

$campaign_discount Rabatten fra de aktive kampagner.

$campaign_matches Et array af produkter der matcher en kampagne. Hvis der ikke er nogen produkter er variablen null.

$unpaid_order Hvis kunden har en ubetalt ordre.

$unpaid_recurring_order Ubetalt abonnement.

$basket

kurvens indhold som et array, hvor de enkelte elementer er produkterne i kurven, med værdierne:

Variabel	Content
`.id`	unikt id på linjen
`.product_id`	id'et på produktet
`.in_stock`	true/false om produktet er på lager
`.product`	produktet
`.attributes`	produktets attributter
`.own_id`	sku-nummeret
`.amount`	antallet i kurven
`.comment`	evt. kommentar
`.bundle`	array af produktet hvis produktet er en samlepakke

Eksempel på hvordan ovenstående bruges:

<{foreach $basket as $row}>
	<{if $image = $row.product->getImage()}>
		<img src="<{$image->getSrc(50, 50, 'box')|escape}>">
	<{/if}>

	<{$row.amount}> x <{$row.product->getName()|escape}>

	i alt

	<{$row.product->getRealPrice($row.amount, $row.attributes)|number_format:2:",":"."}>
	<{$webshop->getCurrency()}>

<{/foreach}>

Kig i Template API'et for at se hvilke metoder der er tilgængelig på de forskellige objekter.

$subscriptions Kurvens abonnementer. Fungerer på samme måde som $basket

$price Subtotalen på kurvens indhold. Dvs. uden fragt.

$shipping_price Fragtprisen på kurven.

$total_price Samlet pris på kurvens indhold.

$vat Momsen på kurvens indhold.

$basket_weight Kurvens samlede vægt (til fx fragt).

$total_amount Kurvens samlede antal produkter.

$voucher Rabatkoden hvis der er en.

$voucher_discount Rabatten fra rabatkoden.

$shipping_country Det valgte leveringsland.

$nofollow Angiver om nofollow er sat på siden.

$meta_title Titlen på siden.

$meta_description Beskrivelse af siden.

$canonical URL til sidens canonical.

$session_order Array med faktureringsadressen. Indeholder felterne name, company_name, vat_number, address, address2, zipcode, city, email, phone, ean_number, comments

$session_del Array med leveringsadressen. Indeholder felterne: name, company_name, address, address2, zipcode, city

$session_extra Array med ekstrafelter på ordren. Hvis der POST'es et felt med extra[test]=123 vil $session_extra.test være 123, og den gemmes på ordren.

Template-funktioner

Nedenstående er de Shoporama-specifikke funktioner der kan anvendes i templates:

Funktion Description

t

Det er muligt at indbygge sprogsupport i dine templates. Dog ikke klassisk sprogsupport, hvor man kan vælge teksten på flere sprog, men sprogsupport, hvor det er muligt at ændre teksten i admin. Det fungerer ved at pakker teksten ind i en <{t}>-blok. Efter templaten er blevet renderet i browseren kan teksten efterfølgende redigeres i admin. Eks.:

<{t}>Din kurv<{/t}>

Bemærk at hvis du ændrer teksten i dine template-filer, så vil den nye tekst optræde i admin som en ny tekst. Der er ikke nogle ID'er eller navne, ud over indholdet, det gør teksten unik.

Du kan sætte attributten section på blokken for at inddele dine tekster i mere overskuelige dele. Samt hint hvis du vil give et hint i admin når teksten redigeres:

<{t section="basket" hint="Bruger i overskriften"}>Din kurv<{/t}>

Hvis du har variabelt indhold som du vil sende med, uden at værdien kommer i admin, kan du bruge nedenstående syntaks:

<{t amount=$total_amount price=$total_price|number_format:2:",":"." hint="Til kurven"}>
    Du har {amount} ting til {price} kroner i kurven.
<{/t}>

Hvis det passer bedre ind i din struktur kan du også bruge t som en modifier på dine variabler/funktioner:

<{$title = "Min titel her"}>
<{$title|t}>

Ovenstående vil vise følgende i admin:

Argumenter	Bekrivelse
`section`	Sektion til inddeling i admin
`hint`	Hint der bruges i admin som hjælpetekst

cache

Hvis en template indeholder en masse tunge kald der ikke behøver være live-opdateret - som fx varianter på produkter, menu, eller kategorioversigt, så indeholder Shoporama en caching-funktion der kan gøre shoppen en del hurtigere. Funktionerne der bruges er hhv. cache og get_cache. Der først markerer den del der skal caches, og senere henter det cachede data ud. Eks.:

<{get_cache name="my_cache" ttl=3600 assign="c"}>

<{if $c}>

	Fra cache: <{$c}>

<{else}>

	Live:

	<{cache name="my_cache"}>
		<{$smarty.now}>
	<{/cache}>

<{/if}>

Funktionen cache pakker indholdet ind og tildeler det navnet som angives i name. Når indholdet skal trækkes ud bruges der get_cache der tager argumenterne name, som brugt tidligere, og ttl som angiver i sekunder hvor gammelt indholdet må være. Hvis argumentet undlades er default én time.

Argumenter	Bekrivelse
`name`	Bruges til at angive navnet på det cachede element. Det er muligt at bruge dynamiske navne fra variabler.

get_cache

Funktion der returnerer det cachede indhold fra cache-funktionen.

Argumenter	Bekrivelse
`name`	Navnet på det cachede element som brugt i `cache`.
`ttl`	Time To Live. Antal sekunder som cachen må være gyldig i.
`assign`	Navnet på den variaben som indholdet skal assignes til.

Theme settings

Det er muligt at tilføje nogle generelle indstillinger til temaer ved at tilføje en theme_settings.json i roden af temaet, og fremprovokere noget lignende nedenstående:

Strukturen er følgende:

Name Content Datatype

info Navnet på temaet string

features Array af features temaet indeholder. Bruges kun til visning i admin. Kun brugbart hvis temaet er generelt og flere brugere kan vælge det. Fx ["Feature A", "Feature B", "Feature C"] array

demo URL til evt. demoside string

settings

Array af felter der kan redigeres:

array

Name Content Datatype

.path ID på felter der indgår i variablen, som første element, når værdien hentes ud. Hvis path sættes til design vil værdierne ligge i $settings.design.{feltnavn} string

.name Navn der vises i admin string

.description Beskrivelse der vises i admin string

.fields

De enkelte felter der kan redigeres af brugeren

array

Name	Content	Datatype
`.path`	ID'et til når værdien skal hentes ud. Hvis `path` sættes til `color` og det overliggende felt var `design`, kan feltet hentes ud via `$settings.design.color`	`string`
`.name`	Navn der vises i admin	`string`
`.description`	Beskrivelse der vises i admin	`string`
`.type`	Typen af feltet. De gyldige typer er: `image`, `color`, `string`, `bool`, `wysiwyg`, og `list`.	`string`
`.values`	Værdier hvis `type` er sat til `list`. Formater er følgende: [ { "name": "cheese", "value": "Ost" }, { "name": "ham", "value": "Skinke" } ]	`array`

Eksempel på indhold af fil

{
	"info": "Mit tema",
	"settings": [
		{
			"path": "design",
			"name": "Design",
			"description": "Indstillinger for dit design",
			"fields": [
				{
					"path": "logo",
					"name": "Toplogo",
					"description": "Upload dit logo her",
					"type": "image"
				},
				{
					"path": "background_color",
					"name": "Baggrundsfarve",
					"description": "Baggrundsfarven på shoppen",
					"type": "color"
				},
				{
					"path": "size",
					"name": "Bredde",
					"description": "Bredden på siden",
					"type": "list",
					"values": [
						{
							"name": "Afgrænset",
							"value": "boxed"
						},
						{
							"name": "Fuld bredde",
							"value": "fullwidth"
						}
					]
				}
			]
		},
		{
			"path": "contact",
			"name": "Kontaktoplysninger",
			"description": "Dine kontaktoplysninger der vises i temaet",
			"fields": [
				{
					"path": "mail",
					"name": "E-mail-adresse",
					"description": "Indtast din e-mail-adresse her",
					"type": "string"
				}
			]
		},
	]
}

Page Builder

Page Builderen er et værktøj til at opbygge indhold via sektioner udfra JSON-filer. Disse sektioner kan placeret på forskellige sider i webshoppen. Hvilke sider de kan placeres i defineres i filen /{navn}/components/sections.json. Indholdet af de enkelte sektioner defineres i hver sin egen fil, der placeres i /{navn}/components/sections/{sektion}.json.

Hvis man har gjort ovenstående vil Design linket i toppen af admin automatisk lede til Page Builderen:

Strukturen i opbygningen af sektioner er som følgende:

File Content

/{navn}/components/sections.json

Indeholder en liste over sidetyper samt et array af hvilke sektioner der er tilladt. Ud over sidetyper kan man også bruge egne tags.

{
	"Sidetype": ["sektionA", "sektionB"]
}

Der findes følgende sidetype:

Sidetype	Bekrivelse
`product`	Produktsider
`category`	Categories
`landing_page`	Dynamic categories
`static_page`	Pages
`blog_post`	Blogindlæg
`basket`	The basket
`address`	Adressesiden
`shipping`	Fragtsiden
`approve`	Godkeldelsessiden
`thanks`	Takkesiden, som kunden typisk ser efter ordren er gennemført
`search`	Søgesiden
`also`	Mersalgssiden, der kan bruges hvis man viser en opsalgsside efter kunden har lagt produkter i kurven
`order`	Ordresiden, der viser ordrens indhold via et link
`#tags`	Valgfrie tags du selv opretter

Et eksempel på en sections.json, hvor brugeren må tilføje sektionerne slider, photos, og quiz til landingssider, men kun slider til produktsider, og på #footer må der indsættes en about sektion vil se sådan ud:

{
	"landing_page": ["slider", "photos", "quiz"],
	"product":      ["slider"],
	"#footer":      ["about"]
}

/{navn}/components/tags.json

Tags bruges til lokationer som man selv opfinder, og som man kan trække ud som det passer en. Det kan være at man har brug for en #footer som man trækker ud og viser nederst på shoppen, eller en #xmas opsætning man kun bruger i december. Formatet for tags.json er:

{
	"tag1": "Beskrivelse ...",
	"tag2": "Beskrivelse ...",
	"tag3": "Beskrivelse ..."
}

De enkelte tags dukker automatisk op i admin når brugeren opretter en ny opsætning:

For at trække indholdet af tags ud i temaet bruges funktionen getBlocks() på følgende måde:

<{if $blocks = $webshop->getBlocks("#foo")}>
	<{foreach $blocks as $block=>$elements}>
		[...]
	<{/foreach}>
<{/if}>

/{navn}/components/sections

I dette bibliotek placeres de enkelte sektioner i hver deres json-fil. Hver fil er navngivet efter navnet på sektionen. Hvis sektionen hedder slider skal indholdet ligge i /{navn}/components/sections/slider.json. Strukturen for filerne er følgende

Field Bekrivelse Type

title Navnet der vises i admin string

description Beskrivelse der vises i admin string

fields

Et array af felter

array

Field	Bekrivelse	Type
`.id`	ID'et på feltet. Bruges når indholdet loopes igennem i temaet	`string`
`.type`	Indholdets type. Gyldige typer er: `list`, `text`, `integer`, `image`, `images`, `bool`, `richtext`, `longtext`, og `repeater`	`string`
`.options`	Bruges kun til felter af typen `list`, og den indeholder en serie af valgmuligheder som fx: [...] "options": { "hat": "Hat", "glasses": "Briller", "beard": "Skæg" }, [...]	`string`
`.title`	Titlen på feltet	`string`
`.description`	Beskrivelse af feltet	`string`
`.max`	Maksimum felter der kan tilføjes	`int`
`.required`	Om feltet er påkrævet	`bool`
`.placeholder`	Placeholder til admin	`string`
`.default`	Evt. default-værdi til feltet	`string`
`.fields`	Bruges kun hvis typen er `repeater`, og kan indeholde samme felter som sektioner. Et simplificeret eksempel på en slider-repeater kan være: [...] "type": "repeater", "fields": [ { "id": "headline", "type": "text", "title": "Overskrift" }, { "id": "img", "type": "image", "title": "Billedet" } ] [...]	`string`
`.field_title`	Bruges kun hvis typen er `repeater`, og indeholder navnet på de enkelte elementer i repeateren	`string`

Visninger

Der er forskellige strategier for at trække data ud. Som udgangspunkt vil der være en $page_blocks på de sider der matcher en opsætning. Den kan loopes den igennem, eller indholdet kan trækkes ud via $webshop->getBlocks('#foo'). Eller indholdet kan tilgås via navnet på sektionen.

Som udgangspunkt vil vi anbefale at man placerer visningen af de enkelte sektioner i separate filer, som fx /{navn}/templates/sections/{section}.html. Derefter er det nemt at loope $page_blocks igennem og inkludere den rigtige visning på følgende måde:

<{if $page_blocks}>

	<{foreach $page_blocks as $section}>
		<{$type = $section._type}>

		<{if $webshop->templateExists("sections/$type.html")}>

			<{include file="sections/$type.html"}>

		<{/if}>

	<{/foreach}>

<{/if}>

Bemærk at rækkens type ligger i variablen _type.

Nedenstående sektion kalder vi images - indholdet ligger derfor i /{navn}/components/sections/images.json.

{
	"title": "Overskrift og billeder",
	"fields": [
		{
			"id": "headline",
			"type": "text",
			"title": "Overskrift"
		},
		{
			"id": "images",
			"type": "images",
			"title": "Billeder"
		}
	]
}

Det giver følgende interface i admin:

For at trække indholdet ud via ovenstående metode kan /{navn}/templates/sections/images.html indeholde følgende:

<h1><{$section.headline|escape}></h1>

<{foreach $section.images as $image}>
	<img src="<{$image->getSrc(150, 150, 'box')}>">
<{/foreach}>

Mht. datatype er det vigtigt at være opmærksom på hvad de enkelte felter indeholder. De kan være enten string, array, eller object. Dvs. man bør gøre noget lignende:

[...]
<{foreach $section as $name=>$val}>
	<{if is_array($val)}>
		Repeater eller array af billeder
	<{elseif is_object($val)}>
		Et billede
	<{else}>
		Tekst, tal, eller lignende
	<{/if}>
<{/foreach}>
[...]

Bemærk at det altid er muligt at bruge var_dump for at undersøge hvad variablen indeholder, og på den måde loope den korrekt igennem.

Visninger

Med udgangspunkt i tidligere nævnt struktur gennemgås herunder de enkelte visninger. For at forstå de enkelte objekter, og hvilke metoder der er tilgængelige anbefaler vi at kigge i vores Template API.

Download vores Alaska-tema for at se eksempler på de forskellige visninger.

Products

Visningen at produkter kan ligge i product.html, men det er valgfrit. Det er altid index.html der afvikler de enkelte visninger. Men vi anbefaler at man bruger denne struktur. For at vide at der afvikles en produktvisning checkes der om $product er til stede.

Læg i kurv

Produkter tilføjes til kurven ved at lave et POST kald til en vilkårlig side - typisk bare den side man allerede viser, med argumenterne product_id, attributes[{attribut_id}]={attribut_value_id}, og amount. Attributten skal kun tilføjes hvis produkter har varianter.

Et simpelt eksempel på hvordan man lægger produkter i kurven kan være:

<form action="" method="post">
	<input type="hidden" name="product_id" value="<{$product->getProductId()}>"/>
	<input type="number" name="amount" value="1" min="1"/>
	<input type="submit" value="Læg i kurv">
</form>

Med varianter:

<form action="" method="post">
	<input type="hidden" name="product_id" value="<{$product->getProductId()}>"/>

	<{foreach $product->getProfile()->getAttributeList() as $attribute}>
		<{if $attribute->getIsVariant() && $attribute->getDataType() == "valuelist"}>
			<select name="attributes[<{$attribute->getAttributeId()}>]">
				<{foreach $attribute->getValues() as $value}>
					<option value="<{$value->getAttributeValueId()}>">
						<{$attribute->getName()|escape}>: <{$value->getVal()|escape}>
					</option>
				<{/foreach}>
			</select>
		<{/if}>
	<{/foreach}>

	<input type="number" name="amount" value="1" min="1"/>
	<input type="submit" value="Læg i kurv">
</form>

Ovenstående kan selvfølgelig gøres mere kompliceret hvis man ønsker at vise lagerstatus, samlepakker, m.m.

Dynamic categories

Landingssider indeholder en $landingpage samt $products som er et array af produkter der skal vises på siden.

Hvis siden kræver en pager indsættes den på følgende måde:

<{if $pager}>
	<{$pager->render()}>
<{/if}>

Pages

Statiske sider vil indeholde en $page.

Blog

Bloggen kan inddeles i to sider: blog.html og blog_post.html, hvor første kan trække en liste over blogindlæg via:

<{$blog_posts = $webshop->getBlogPosts()}>

Selve visningen af de enkelte blogindlæg foregår ved at kigge på variablen $blog_post.

If the list of blogposts is from a category there will be a $category available at the category.

Product reviews

I product_review.html er der adgang til $order, og som er ens ordre. Man kan kun anmelde produkter man har købt. Ud fra ordren kan man trække produkterne via $order->getOrderProducts(). For at gemme produktanmeldelserne skal man lave et POST kald til samme side med følgende indhold:

<{if $order}>
	<{if $get.voted}>
		Tak!
	<{else}>
		<form action="" method="post">
			<{foreach $order->getOrderProducts() as $product}>
				<{$product->getName()|escape}>
				Stjerner:
				<input type="number" min="1" max="5" name="rating[<{$product->getProductId()}>]">
				Anmeldelse
				<textarea name="description[<{$product->getProductId()}>]"></textarea>
			<{/foreach}>
			<input type="submit" value="Skriv anmeldelse"/>
		</form>
	<{/if}>
<{/if}>

$get.voted er true når kunden har anmeldt.

For at linke til anmeldelsessiden fra din ordre skal du bruge $order->getReviewUrl().

Search

Søgningen fungerer ved at lave et GET kald til /search hvor argumentet ?search= skal være ens søgeord. Eks.:

<form action="/search">
	<input type="text" name="search" value="<{$get.search|escape}>"/>
	<input type="submit" value="Søg"/>
</form>

Searches are made in products, categories, blogposts and dynamic categories. To present the search result you must go through the four variables $products, $categories, $blog_posts, and $landing_pages

/also

also.html er vores side til mersalg. Som udgangspunkt er der adgang til $product, og udfra den kan man komme med forslag til kunden. Det kan fx være relevant at bruge $product->getRelatedProducts(), $product->getAlsoBought(), eller $webshop->getPopularProducts().

404

Bruges kun til at vise 404-sider.

410

Bruges kun til at vise 410-sider.

Captcha

Der indsættes automatisk en captcha når man prøver at tilmelde sig nyhedsbrev, eller skrive kommentarer. Dette er for at undgå spam. Det er muligt selv at designe siden i captcha.html, og den skal som minimum indeholde:

<form action="" method="post">
	<{$form}>

	<{if $error}>Fejl i koden<{/if}>

	<img src="<{$imgstr}>">

	Skriv indholdet at ovenstående felt:
	<input type="text" name="c">

	<input type="submit" value="OK">
</form>

Det er muligt at lade ens kunder logge ind i shoppen. Hvis vedkommende er er logget ind vil der være en $customer der indeholder informationer om brugeren. Alle sider der redigerer, logger ind, m.m. skal submitte via POST til siden selv.

File name	Description	Relevante variabler/parametre i formularen
`/user-edit.html`	Bruges til redigering af kundens data. Det er muligt at tilføje felter til kunden. Se mere under denne tabel.	`company`, `vat_number`, `name`, `email`, `phone`, `address`, `zipcode`, `city`, `country_id`, `shipping_name`, `shipping_address`, `shipping_zipcode`, `shipping_city`, `shipping_country_id`, `pass1`, `pass2`.
`/user-orders.html`	Kundens tidligere ordrer	`$my_orders`
`/user-profile.html`	Visning af kundens data	`$customer`
`/user-reset-password.html`	Bruges til nulstilling af password	`email`, `password`
`/user-sign-in.html`	Login siden. Brug `redir` hvis kunden efter login skal sendes videre til en URL.	`email`, `password`, `redir`
`/user-sign-up.html`	En formular som kunden bruger til at registrere sig.	`name`, `email`, `phone`, `address`, `zipcode`, `city`, og `country_id`

Egne felter til kunden

Det er muligt i admin at definere egne felter til ens brugere. De felter redigeres på følgende måde:

<{foreach $webshop->getCustomerFields() as $field}>
	<{if $field->getType() == "list"}>
		<{$field->getName()|escape}>
		<select name="field[<{$field->getCustomerFieldId()}>]">
			<{foreach $field->getValues() as $value}>
				<option <{if $field->getVal() == $value}>selected="selected"<{/if}> value="<{$value|escape}>">
					<{$value|escape}>
				</option>
			<{/foreach}>
		</select>
	<{elseif $field->getType() == "string"}>
		<{$field->getName()|escape}>
		<input type="text" name="field[<{$field->getCustomerFieldId()}>]" value="<{$field->getVal()|escape}>">
	<{/if}>
<{/foreach}>

Check ud

Check ud flowet er simpelt set en serie af html-sider der hver især indeholder en formular der POST'er noget data til sig selv, og hvis feltet next er sat, vil Shoporama sende videre til næste side i flowet. Typisk vil man sætte "Næste" knappen til name="next". Der kan altid linkes til tidligere sider i flowet. Når kunden har indtastet sine oplysninger ligger disse i to arrays hhv. $session_order og $session_del. Fx $session_order.name.

File name	Description	Relevante variabler/parametre i formularen
`basket.html`	Viser kurvens indhold. Simpelt eksempel hvordan `$basket` bruges: <{foreach $basket as $line}> <{$line.amount}> x <{$line.product->getName()}> <{foreach $line.attributes as $a}> <{$a.name\|escape}>: <{$a.value\|escape}> <{/foreach}> <{/foreach}> For at ændre på antallet skal det `POST`'es på følgende måde [...] <input name="amount[<{$line.id}>]" value="<{$line.amount}>" /> [...] For at tilføje en rabatkode skal der `POST`'es en `voucher` med rabatkoden. Hvis rabatkoden er ugyldig vil `$get.wrong_voucher` være til stede i templaten. Leveringslandet kan ændres ved at `POST`'e en `del_country_id` med ID'et på leveringslandet.	`$basket`, `$voucher`, `$voucher_discount`, `$campaign_ids`, `$campaign_discount`, `$price`, `$shipping_price`, `$total_price`, `$vat`
`address.html`	Siden hvor leveringsoplysningerne indtastes. Hvis `mailinglist` sættes til `1` tilmeldes kunden til nyhedsbrev. Hvis `create_profile` sættes til `1` oprettes der en profil til kunden så vedkommende efterfølgende kan logge ind.	`order_country_id`, `order_name`, `order_company_name`, `vat_number`, `ean_number`, `order_address`, `order_zipcode`, `order_city`, `email`, `phone`, `comments`, `del_name`, `del_company_name`, `del_address`, `del_zipcode`, `del_city`, `del_country_id`, `mailinglist`, `create_profile`
`shipping.html`	Bruges til at vælge leveringsmetode. De enkelte leveringsmetoder kan trækkes ud via `$webshop->getShippings()`. For at gemme leveringsmetode skal der `POST`'es en `shipping_id` med ID'et på den leveringsmetode. Hvis leveringsmetoden har et pakkeshop tilknyttet trækkes de ud via `$shipping->getDeliveryShops()`. Du kan vælge pakkeshop på følgende måde: [...] <{if $shipping->getModule()}> <select name="shop"> <{foreach $shipping->getDeliveryShops() as $shop}> <option value="<{$shop.number}>"> <{$shop.name\|escape}> <{$shop.street\|escape}> <{$shop.zip\|escape}> <{$shop.city\|escape}> </option> <{/foreach}> </select> <{/if}> [...]	`shipping_id`, `shop`
`approve.html`	Godkendelsessiden. Bruges til at vise ordren. Hvis shoppen indeholder flere betalingsgateways kan disse vælges på denne side. De hentes ud via `$webshop->getPaymentGateways()` og submittes via `payment_gateway_id` for at skifte.	`$basket`, `$shipping`, `payment_gateway_id`
`thanks.html`	Takkesiden. Bruges til at vise ordren der er gennemført.	`$order`

Ajax

Shoporama har to indbyggede ajax-kald. Det ene kan trække produkter ud på forskellige måder (filtrering), og det andet er en generel og simpel søgning der søger i produkter, kategorier, og landingssider.

Filtrering

Filtreringen ligger i filen /ajax som ligger i roden af alle shops

Argument	Description	Example
`atags`	En liste af tags på attributværdierne, attributværdier er indstillinger på attributterne på produkternes profiler. værdierne på `atags` skal være adskilt af komme, men tillader grupperinger adskilt af pipe som en logisk `OR`.	ajax?atags=female,black\|white
`product_ids`	Liste af product_id'er adskilt af pipe.	ajax?product_ids=1\|2\|3\|4
`price_range`	Returnerer produkter der ligger indenfor et prisområde. Beløbene skal adskilles af pipe.	ajax?price_range=100\|200
`categories`	En pipe-separeret liste af kategorier produkterne skal ligge i. Hvis argumentet `exclude=1` sættes returneres der en liste af produkter der ikke har kategorierne.	ajax?categories=5\|9\|2 ajax?categories=5\|9\|2&exclude=1
`sort`	Sort order. You man set these values `popular`, `weight`, `name`, `price`, `created`. Whether sorting should be ascending or descending is set by `sort_order`. Set it to eihter `asc` or `desc`.	ajax?sort=price&sort_order=desc
`attribute_values`	En liste af id'er på attributværdierne som produkterne skal have. Listen adskilles af pipe. Hvis argumentet `exclude=1` sættes returneres der en liste over produkter der ikke matcher.	ajax?attribute_values=9\|8\|12
`suppliers`	Pipe-separeret liste af id'er på leverandører.	ajax?suppliers=8\|2
`landing_pages`	Pige-sepereret liste af id'er på landingssider produkterne skal optræde på.	ajax?landing_pages=5\|24
`extension.{id}`	Hvis temaet bruger udvidede felter kan der trækkes produkter ud på baggrund af dem. Der laves absolutte søgninger, så de felter der giver mest mening at bruge er `bool`, `multi`, `number`, og `list`. Der kan bruges pipe-separerede værdier hvis produkterne skal matche bare én af værdierne.	ajax?extension.foo=1&extension.tags=foo\|bar
`attribute_tags_in_stock`	Liste af tags på attributværdier der skal være på lager. Listen kan pipe-separeres.	ajax?attribute_tags_in_stock=foo\|bar
`attribute_tags`	Liste af tags der skal være sat på produkterne. Listen kan pipe-separeres.	ajax?attribute_tags=foo\|bar
`attribute_tag`	Samme som `attribute_tags` bare kun med et enkelt tag.	ajax?attribute_tag=foo
`force_categories`	En pipe-separeret liste over kategori-id'er der alle skal være sat på produkterne.	ajax?force_categories=5\|9\|2
`limit`	Maks. antal produkter der skal returneres.	ajax?limit=10
`offset`	Startposition ift. hvor i listen af produkter man ønsker at hente fra.	ajax?offset=100&limit=10
`meta`	Pipe-separeret liste af ekstrafelter man ønsker at se på produkterne i resultatet. Hvis man sætter `meta=_all` returneres alle.	ajax?meta=foo\|bar ajax?meta=_all
`only_in_stock_variants`	Sættes til `1` eller `0` afhængig af om hvert produkt i resultatet kun skal medtage varianter der er på lager. Default er `0`.	ajax?only_in_stock_variants=1
`include_meta`	Sættes til `1` eller `0` afhængig af om man ønske et ekstra `meta`-felt i resultatet der indeholder beskrivelser af produkterne i resultatet. Det er oplysninger om hvilke attributter, kategorier, og brands der findes. Default er `0`.	ajax?include_meta=1
`include_pagination`	Sættes til `1` eller `0` afhængig af om man ønske et ekstra `pagination`-felt i resultatet der indeholder paging oplysninger. Felterne i array'et er `offset`, `limit`, `count`, `total`. Default indstilling er `0`.	ajax?include_pagination=1
`pretty`	Sættes til `1` eller `0` afhængig af om json-svaret skal formateres pænt eller ej.	ajax?pretty=1

Svaret fra /ajax er et array i nedenstående format:

[
    {
        "product_id": 139735,
        "own_id": "skunumme",
        "name": "Produktnavn",
        "supplier_id": 0,
        "supplier_name": "",
        "category_ids": [
            3661,
            2113,
            2106,
            1973
        ],
        "category_names": [
            "Bob",
            "Forside",
            "Ged",
            "Giraf"
        ],
        "description": "<p>...</p>",
        "list_description": "",
        "profile_name": "Default m. variant",
        "allow_negative_stock": 1,
        "brand_name": "TESTBRAND",
        "sale_price": 0,
        "real_price": 80,
        "price": 80,
        "price_dk": "80,00",
        "approx_shipping": 0,
        "delivery_time": "",
        "delivery_time_not_in_stock": "",
        "url": "https://example.com/produkt",
        "stock": 0,
        "attr_stock": null,
        "variant_stock": [
            {
                "attribute_id": 2740,
                "attribute_value_id": 16287,
                "name": "S",
                "weight": 10,
                "cnt": 4
            },
            {
                "attribute_id": 2740,
                "attribute_value_id": 16289,
                "name": "L",
                "weight": 30,
                "cnt": 9
            }
        ],
        "stock_string_da": "Nej",
        "avg_rating": null,
        "thumbnail": "https://example.com/cache/1/9/6/9/bob-fit-200x200x90.png",
        "meta_values": [
            null
        ],
        "online_since": 1651685711,
        "has_campaigns": true,
		"campaign_info": [
            {
                "name": "Bob",
                "price_model": "cheapest_free",
                "min_product_count": 4,
                "price": 0,
                "percent": 0,
                "created": "2023-02-01 14:55:47",
                "expires": null
            }
        ]
    }
]

Af hastighedsmæssige årsager cacher vi svaret fra ajax-filen, men i testmiljø kan der tilføjes rebuild=1 som argument for at siden genopbygges. Vi anbefaler at man ikke gør det i produktionsmiljøet, da det kan sløve siden markant.

Search

Siden /ajax_search indeholder en generel søgning til produkter, kategorier, og landingssider. Den kan fx bruges til en autocomplete i ens søgefelt. Den tager følgende argumenter:

Argument	Description	Example
`term`	Søgeordet.	ajax_search?term=ostemad
`limit`	Maks. antal resultater.	ajax_search?term=ostemad&limit=25
`include`	A comma separated list of datatypes you wish to search. Values may be `products`, `categories`, `blog_posts`, and `landing_pages`	ajax_search?term=ostemad&include=products,categories
`pretty`	Sættes til `1` eller `0` afhængig af om json-svaret skal formateres pænt eller ej.	ajax_search?term=ostemad&pretty=1

Resultatet er et array i nedenstående format:

[
    {
        "name": "Produkt et",
        "supplier": "",
        "description": "<p>...</p>",
        "price": 80,
        "sale_price": null,
        "normal_price": 80,
        "currency": "DKK",
        "price_dk": "80,00",
        "url": "https://example.com/produkt-et",
        "stock": 0,
        "stock_string_da": "Nej",
        "review_avg": 0,
        "thumbnail": "https://example.com/cache/1/9/8/4/box-100x100x90.png",
        "type": "product"
    },
    {
        "name": "Produkt to",
        "supplier": "",
        "description": "<p>...</p>",
        "price": 80,
        "sale_price": null,
        "normal_price": 80,
        "currency": "DKK",
        "price_dk": "80,00",
        "url": "https://example.com/produkt-to",
        "stock": 0,
        "stock_string_da": "Nej",
        "review_avg": 0,
        "thumbnail": "https://example.com/cache/1/9/6/9/bob-box-100x100x90.png",
        "type": "product"
    }
]

Shoporama templates

Menu

Page Builder

Visninger

Login

Check ud

Ajax

Overblik

Smarty

Tips

Undersøg indhold

Check objekter

Debug

Filstruktur

Generelt om strukturen i mail-templates

Billeder, stylesheets, m.m. i temaet

Udvidelser

Globale variabler

Template-funktioner

Theme settings

Eksempel på indhold af fil

Page Builder

Visninger

Visninger

Products

Læg i kurv

Dynamic categories

Categories

Pages

Blog

Product reviews

Search

/also

404

410

Captcha

Login

Egne felter til kunden

Check ud

Ajax

Filtrering

Search