Tämä sivu koskee VuFind2-organisaationäkymiä ja uutta hallintaliittymää.
Näkymän räätälöinti tehdään pääosin tiedostonhallinnan kautta muokkaamalla näkymän teemaa. Teema on Finnassa se kerros, jonka perusteella tuotetaan näkymän selaimelle näytettäväksi annettava sisältö. Tässä dokumentissa kerrotaan räätälöinnin perusasiat.
Yleisperiaatteita teeman tiedostojen muokkaamisessa
Kunkin näkymän hakemisto on organisaation mukaan nimetyssä juurihakemistossa. Esimerkiksi Kansalliskirjaston näkymä "testi" on hakemistossa /kansalliskirjasto/testi
. Teemahakemisto (vastedes <teemat>
) on näkymän alihakemisto themes
.
Näkymät käyttävät custom-teemaa, jonka tiedostot sijaitsevat hakemistossa /themes/custom. custom-teema perii Finna-teeman. Näkymän räätälöinti tehdään yliajamalla Finna-teeman tiedostoja. Esimerkiksi jos halutaan räätälöidä tiedostoa /themes/finna/templates/footer.phtml
, tästä tiedostosta tehdään kopio /themes/custom/templates/footer.phtml
. Tämän jälkeen teema käyttää alkuperäisen Finna-hakemistossa sijaitsevan tiedoston sijaan uutta custom
-hakemistossa sijaitsevaa tiedostoa. Samannimisen tiedoston voi tehdä myös kokonaan alusta aloittaen tyhjästä tiedostosta.
Esimerkki 1
Tavoite: halutaan muokata sivun alaosassa näkyviä linkkejä.
Siirrytään hakemistoon /themes/finna/templates ja valitaan tiedosto footer.phtml
. Klikataan "Kopioi":
Tiedosto kopioidaan hakemistoon /themes/custom/templates:
Esimerkki 2
Tavoite: halutaan muokata etusivun otsikkotekstejä.
Luodaan hakemisto <teemat>/custom/Search
ja sen sisälle tyhjä tiedosto home-header.fi.tpl
käyttämällä alla olevia painikkeita:
Tästä lähin näkymä käyttää custom-teemaan luotua home-header.fi.tpl
-tiedostoa ndl-teeman samannimisen tiedoston sijaan.
Custom-teeman paikallinen tiedosto korvaa Finna-teeman vastaavan tiedoston kokonaisuudessaan. Paikallisessa tiedostossa on siis yleensä oltava kaikki oletustiedostossa olevat elementit (jos niitä ei nimenomaan haluta poistaa), vaikka muokkaukset koskisivat vain osaa niistä.
Joillekin tiedostoille on olemassa erillinen mahdollisuus kumulativiisiin muutoksiin, ja tämän käyttö on toivottavaa. Näitä ovat lähinnä <teemat>/ndl/css
-hakemiston alla olevat default.css
ja home.css
. Sen sijaan että kopioitaisiin ne custom-teeman alle, luodaan tiedostot <teemat>/custom/default_custom.css
ja <teemat>/custom/home_custom.css
. Näihin ei kannata kopioida mitään muista tiedostoista, sillä ne eivät korvaa mitään tiedostoa vaan niiden sisältö vain lisätään jo aktiivisiin CSS-sääntöihin. Tämän merkittävä etu on, että muokkaukset eivät irrota mitään tiedostoa keskitetystä ylläpidosta.
Sivupohjat
Teema on Finnassa se kerros, jonka perusteella tuotetaan näkymän selaimelle näytettäväksi annettava sisältö. Teema rakentuu sivupohjien (template, tiedostopääte .phtml
) ympärille. Tyypillisesti sivupohjan perusteella tuotetaan HTML-sisältöä, joka annetaan selaimelle näkymän käyttäjän nähtäväksi.
Tässä esitellään kuvankaappausten avulla tärkeimmät sivupohjat, joille sisältöä voi lisätä.
Useimmissa sivupohjissa on jo sisältöä jota voi muokata. Tämän lisäksi /themes/custom/templates/content/Additions
alla on sivupohjia, jotka on tarkoitettu sisällön lisäämiseen muutamiin sellaisiin paikkoihin, joissa sitä ei oletuksena ole.
Kannattaa pääsääntöisesti muokata mahdollisimman spesifiä sivupohjaa. Esimerkiksi /themes/finna/templates/layout/layout.phtml-sivupohja tekee paljon asioita, jotka ovat olennaisia näkymän toiminnalle ja joihin tulee keskitetystä ylläpidosta usein muutoksia päivitysten yhteydessä. Tämä tarkoittaa, että jos näkymä käyttää muokattua layout.phtml
-tiedostoa, päivityksen yhteydessä on yleensä tehtävä paljon muutoksia käsin. Parempi ratkaisu on jättää layout.phtml
keskitettyyn ylläpitoon ja tutkia voisiko haluamansa muutokset tehdä syvemmälle tiedostorakenteeseen, sivupohjiin jotka eivät muutu jatkuvasti.
Ulkoasumuutokset kannattaa pyrkiä toteuttamaan tyylitiedostoilla. Näin pidetään ohjelmalogiikka erillään ulkoasusta.
Etusivu
Etusivun sisältö on jaettu järjestyksessä ylhäältä alaspäin seuraaviin sivupohjiin:
Sivupohja | |
---|---|
templates/search/home/home-left.phtml | Hakupalkin alla vasemmalla. Esimerkki miten sisältöä voi jakaa useampaan palstaan. |
templates/search/home/homerighttop.phtml | Hakupalkin alla oikealla. |
templates/search/home/home-2.phtml | Infolaatikot. |
templates/search/home/home-3.phtml | |
templates/search/home/home-4.phtml | |
templates/footer.phtml |
RSS-syötteet näytetään infolaatikoiden alla (karuselli) ja home-3-phtml:n alla (uutislistaus, pystykaruselli), mikäli nämä ovat käytössä.
Tarpeettomista etusivun sivupohjista voi luoda tyhjät tiedostot custom-teeman alle milloin niitä ei näytetä.
Additions-sivupohjat
Additions-sivupohjat (custom-teeman hakemistossa templates/content/Additions) ovat yksinkertainen tapa sijoittaa omaa sisältöä käyttöliittymään tiettyihin paikkoihin:
Sivupohja | |
---|---|
general-post-body_<kieli>.phtml | HTML:n body -elementin lopussa. |
general-post-head_<kieli>.phtml | HTML:n head -elementin lopussa. Tänne voi lisätä esimerkiksi hyödyllisiksi katsomiaan meta -elementtejä |
header-navibar.phtml | Yläreunan navigointipalkin oikeassa reunassa. Tähän voi sijoittaa esimerkiksi logon tai linkin ulkoiselle sivustolle. |
search-post-facets_<kieli>.phtml | Hakutulossivulla, fasettien jälkeen. |
record-post-metadata_<kieli>.phtml | Tietuesivulla, tietuekenttien jälkeen. |
record-post-toolbar_<kieli>.phtml | Tietuesivulla, tietuekuvan toimintojen alapuolella. |
record-post-recommendations_<kieli>.phtml | Tietuesivulla, samankaltaisten teosten jälkeen. |
login-pre_<kieli>.phtml | Kirjautumissivun alussa. |
login-post_<kieli>.phtml | Kirjautumissivun lopussa. |
online-payment_<kieli>.phtml | Verkkomaksulomakkeella. |
Sisältösivut
Tavallista tekstisisältöä (esim. hakuohjeita) sisältävät sivupohjat ovat teeman templates/content
-alihakemistossa nimellä sivunnimi.phtml
.
Kieliversiot voidaan sijoittaa samaan sivupohjaan (käyttämällä translate-komentoa, ks. alla) tai luomalla jokaista kieliversiota varten oma sivupohja, joka nimetään sivunnimi_<kielikoodi>.phtml, esimerkiksi sivunnimi_fi.phtml (kielikoodit: fi = suomi, sv = ruotsi, en-gb = englanti).
Sivupohjissa käytetään HTML-muotoiluja ja Bootstrap CSS-kehystä. Sisällön jakaminen ruudukkopohjaa tehdään käyttämällä Bootstrapin CSS-luokkia. Omien sisältösivujen skaalautuvuus (eli toimivuus eri näytön leveyksillä) kannattaa testata joko oikealla mobiililaitteella, mobiiliemulaattorilla tai yksinkertaisesti vaihtamalla selainikkunan leveyttä.
Esimerkkejä yleisimmistä muotoiluista (lisää esimerkkejä Finna-teeman sivupohjissa):
CSS-luokka | Esimerkki | |
---|---|---|
col-xs-12 | Sisältöalue, yksi palsta | <div class="col-xs-12"><h2>Otsikko</h2></div> |
col-sm-6 | Sisältöalue, kaksi palstaa | <div class="col-md-6">Palsta 1</div> <div class="col-md-6">Palsta 2</div>
|
col-sm-4 | Sisältöalue, kolme palstaa | <div class="col-md-4">Palsta 1</div> <div class="col-md-4">Palsta 2</div><div class="col-md-4">Palsta 3</div> |
list-bullets | UL-lista, jossa elementtien edessä "pallo" | <ul class="list-bullets"> <li>Elementti 1</li> <li>Elementti 2</li> </ul> |
HTML-muotoilujen lisäksi sivupohjissa käytetään mm. seuraavia lisätoimintoja (muita esimerkkejä voi katsoa Finna-teeman sivupohjista)
<? $this->headTitle('xxx'); $this->content()->setHeading('xxx'); ?> | Sivun otsikon asettaminen. |
<h2>Otsikko</h2> | Otsikko. |
<p>Tekstiä</p> | Tekstikappale. |
| |
<img src="<?=$this->imageSrc('tiedostonimi.jpg')?>"> | Kuvan lisääminen sivulle. Kuva tallennetaan hakemistoon /themes/custom/images |
| |
<a href="<?= $this->fileSrc('tiedostonimi.jpg')?>"> | Tiedoston linkitys sivulle. Tiedosto tallennetaan hakemistoon /themes/custom/files |
<?=$this->translate('XXX');?> | Käännös tekstille XXX käyttäjän valitsemalla kielellä. Mikäli jokaista kieliversiota varten on oma sivuns, tätä ei tarvitse käyttää. |
<a href="<?=$this->url(‘<toiminto>');?>”> | Linkki näkymän toimintoon. Esimerkkejä toiminnoista (kaikki toiminnot listataan tiedostoissa /module/VuFind/config/module.config.php ja /module/Finna/config/module.config.php):
|
|
|
<?= $this->url('content-page', ['page' => '<sivu>'])?> | Linkki sivulle (/Content/xx). Esimerkiksi ohjesivulle linkitetään seuraavasti: <?=$this->url('content-page',['page'=>'help'])?> |
Jos halutaan luoda esimerkiksi suomenkielinen sivu "Yleistä tietoa", se luodaan Content
-alihakemistoon ja nimetään (pienellä alkukirjaimella) halutulla tavalla, esimerkiksi generalinformation_fi.phtml
. Tämän jälkeen sivu näkyy sivuston suomenkielisessä versiossa osoitteessa <sivuston url>/Content/generalinformation
.
Sisältösivulle voi helposti lisätä sivun sisäisen navigaation:
<div class="row"> <div class="col-sm-3 sidebar"> <div class="content-navigation-menu"> </div> </div> <div class="col-sm-9"> <div id="esim1" class="content-section"> <h2>Sivun ensimmäinen osa</h2> <p>Lorem ipsum</p> </div> <div id="esim2" class="content-section"> <h2>Sivun toinen osa</h2> <p>Lorem ipsum</p> </div> </div> </div>
Sivun osiot lisätään div-elementteihin, joissa on CSS-luokka "content-section" ja id-attribuutti. Navigointivalikko sijoitetaan automaattisesti div-elementtiin, jossa on CSS-luokka "content-navigation-menu". Esimerkissa valikko näytetään sivun vasemmassa reunassa, mutta sjoittelua voi vapaasti muuttaa.
Ylävalikko
Ylävalikon rakenne määritellään asetustiedostossa local/config/vufind/navibar.ini. Tiedostoa muokkaamalla voi poistaa tai lisätä kokonaisen valikon tai yksittäisen valikon elementin.
Esimerkki: lisätään uusi valikko, joka sisältää kolme linkkiä:
; Inherit main configuration [Parent_Config] relative_path = ../finna/navibar.ini [valikko] valikko_1 = 'content-asiakkaana-kirjastossa' valikko_2 = 'http://www.finna.fi' valikko_3 = 'http://www.finna.fi,_blank' valikko_4 = 'myresearch-fines,_blank'
Valikko sijoitetaan uuteen osioon (esimerkissä "valikko"), jonka voi vapaasti nimetä. Valikon elementit ovat muotoa <linkin nimi> = <linkin osoite>. Linkin osoite on muotoa <kansion nimi>-<tiedoston nimi>.
Navibar.ini ei ulotu palautelomakelinkkiin, kielivalintoihin eikä kirjautumiseen. Palautelomakelinkki on mahdollista poistaa osiossa [Feedback] asetuksella tab_enabled = false. Kielet ja niiden järjestys määräytyvät osion [Languages] asetusten ja niiden keskinäisen järjestyksen mukaan.
Linkki voi johtaa
- sisältösivulle (esimerkiksi content-asiakkaana-kirjastossa > /Content/asiakkaana-kirjastossa)
- näkymän toimintoon (esimerkiksi myresearch-fines > Oman tilin maksut)
- ulkoiselle sivulle (esimerkiksi http://www.finna.fi).
Linkki avataan uuteen ikkunaan jos linkin osoitteen perään laittaa pilkun ja '_blank', esimerkiksi:
- valikko_3 = 'http://www.finna.fi,_blank'
Valikon tekstit määritellään luomalla uudet käännökset avaimilla "menu_valikko" (valikon otsikko) ja menu_valikko_1, menu_valikko_2 ... (valikon linkit).
Esimerkki: lisätään linkkejä Tietoa meistä -valikkoon. Uudet elementit sijoitetaan osioon, joka nimetään samoin kuin Finnan käyttämä valikko (ks. /local/config/finna/navibar.ini):
; Inherit main configuration [Parent_Config] relative_path = ../finna/navibar.ini [about_us] valikko_1 = 'content-asiakkaana-kirjastossa' valikko_2 = 'content-asiakkaana-kirjastossa'
Esimerkki: korvataan Tietoa meistä -valikon sisältö kokonaisuudessaan lisäämällä osio override_full_sections -määrittelyyn:
; Inherit main configuration [Parent_Config] relative_path = ../finna/navibar.ini override_full_sections = "about_us" [about_us] valikko_1 = 'content-asiakkaana-kirjastossa' valikko_2 = 'content-asiakkaana-kirjastossa'
Kontekstuaaliset ohjeet
Näkymässä on mahdollista näyttää ohjeikoneita, joita klikkaamalla avataan aiheeseen liittyä ohje puhekuplaan. Ohjeikoneiden paikat on ennalta määritelty näkymän sivupohjissa, mutta ohjeiden sisältö on vapaasti määriteltävissä.
Ohjeet laitetaan päälle päivittämällä ohjeen sisältö muiden käännösten tapaan:
Ohjeen käännös | Sijainti käyttöliittymässä |
tooltip_facet_html | Fasetit hakutuloksissa |
tooltip_local_search | Paikallinen haku, hakukenttän yhteydessä |
tooltip_pci_search_html | PCI haku, hakukenttän yhteydessä |
tooltip_metalib_search_html | MetaLib haku, hakukenttän yhteydessä |
tooltip_local_advanced | Paikallinen tarkennettu haku, otsikkopalkki |
tooltip_pci_advanced_html | Tarkennettu PCI haku, otsikkopalkki |
tooltip_metalib_advanced | Tarkennettu MetaLib haku, otsikkopalkki |
tooltip_myaccount_html | Oma tili, otsikkopalkki |
tooltip_tabs_local_html | Paikallisen indeksin välilehti |
tooltip_tabs_pci_html | PCI välilehti |
tooltip_tabs_metalib_html | MetaLib välilehti |
tooltip_tabs_combinened_html | Jaetun hakutuloksen välilehti |
Mikäli ohjeen käännös on tyhjä, ohjeikonia ei näytetä.
Kohdekenttärajaimet / hakutyypit
Hakukentässä olevilla rajaimilla voi tehdä monia asioita, mm. kohdistaa haun tiettyyn kenttään. Näillä rajaimilla voi käyttää kaikkia searchspecs.yaml-asetuksissa saatavilla olevia parametreja. Käytössä olevat rajaimet konfiguroidaan asetutiedoston searchbox.ini osiossa [CombinedHandlers].
Tyylitiedostot
Selaimen näytettäväksi annettava HTML-sisältö tuotetaan sivupohjilla. HTML-sisältö voidaan kuitenkin näyttää käyttäjälle eri tavoin: tekstien fontteja, värejä, marginaaleja ja muita ulkoasullisia asioita voidaan muuttaa CSS-tyylitiedostojen avulla.
Näkymän ulkoasua voi muokata joko käyttämällä Less-esikäsittelijää tai kirjoittamalla suoraan CSS-määrittelyjä. Tehdessäsi tyylitiedostoihin esimerkiksi leveyteen, korkeuteen tai marginaaleihin liittyviä muutoksia, ota huomioon niiden mahdolliset vaikutukset eri päätelaitteilla.
Less-tyylitiedostot
Less-esikäsittelijä laajentaa CSS-tyylitiedostoja monilla toiminnoilla. Näistä näkymän muokkausta helpottaa muuttujat, joihin on kerätty Finna-teeman useasti toistuvat määrittelyt (värit, fontit, jne). Määrittelya muokkaamalla vaikutus näkyy kaikkialla käyttöliittymässä missä muuttujaa käytetään.
Muuttujat löytyvät teeman tiedostosta less/variables.less. Oletuksena tiedoston muuttujat on kommentoituna, milloin muuttujan arvo luetaan Finna-teemasta. Muuttuja otetaan käyttöön poistamalla kommentointi (kauttaviivat rivin alusta) ja tallentamalla tiedosto. Esimerkiksi linkkien väriä voi muuttaa ottamalla käyttöön muuttuja @link-color:
//@body-bg: #fff; //@text-color: @gray; @link-color: #ff00a7; // defines all link color, also for linked icons //@link-hover-color: @link-color;
Less-tiedostoihin tukevat CSS-määrittelyjä, eli .less tiedosoihin voi kirjoittaa tavallista CSS:ää. Omat määrittelyt sijoitetaan tiedostoon less/custom.less.
Hallintaliittymä tarkastaa Less-tiedoston tallentamisen yhteydessä ja ilmoittaa mahdollisista syntaksivirheistä:
Virheellistä tiedostoa ei käsitellä, eivätkä sen muokkaukset tule näkyville käyttöliittymään.
CSS-tyylitiedostot
Less-tyylitiedostojen lisäksi omat CSS-määrittelyt voi sijoittaa teeman tiedostoon css/custom.css.
JavaScript
Selaimen näytettäväksi annettava HTML-sisältö tuotetaan sivupohjilla. Osa Finnan toiminnallisuudesta on selainpohjaista ja toteutetaan selaimessa ajettavalla JavaScript (tiedostopääte .js
) -koodilla, joka ladataan sivupohjista. JavaScript-muokkausten tekeminen ei siis välttämättä edellytä muutoksia sivupohjiin.
Omaa toiminnallisuutta voi lisätä teeman tiedostoon js/custom.js. Tiedoston metodia finnaCustomInit kutsutaan automaattisesti sivun latauksen yhteydessä. Voit luonnollisesti luoda myös uusia funktioita ja kutsua niitä finnaCustomInit()
-funktiosta.
Konfiguraatiotiedostot
Näkymän käyttämät asetustiedostot sijaitsevat hakemistossa /local/config/vufind.
Usein tiedosto perii määrittelyt hakemiston /local/config/finna asetustiedostosta. Perintä määritellään kohdassa Parent_Config > relative_path. Perinnän voi estää osioittain listaamalla nämä osiot kohdassa Parent_Config > override_full_sections.
Esimerkki: /local/config/vufind/config.ini perii Finnan config.inin määrittely lukuunottamatta osioita Languages,AlphaBrowse_Types,SearchTabs:
[Parent_Config] relative_path = "../finna/config.ini" override_full_sections = "Languages,AlphaBrowse_Types,SearchTabs" ...paikalliset määrittelyt...