Näkymän räätälöinti tehdään pääosin tiedostonhallinnan kautta muokkaamalla näkymän asetustiedostoja ja 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.
Konfiguraatiotiedostot
Näkymän asetukset löytyvät hakemistosta /local/config/vufind. Hallintaliittymä kirjoittaa näihin ja näitä voi myös muokata tiedostonhallinnan kautta. Asetustiedostoja kannattaa muokata tiedostonhallinnassa vain jos haluttua muutosta ei voi tehdä hallintaliittymän graafisen puolen kautta (esimerkiksi RSS-syötteiden ja ylävalikon asetukset).
vufind-hakemiston tiedostot perivät Finnan yleiset asetukset, jotka sijaitsevat saman nimisissä tiedostoissa hakemistossa /local/config/finna. Asetustiedostossa voi yliajaa joko kokonaisen osion tai vain osion tietyn parametrin. Osiot, jotka yliajetaan kokonaisuudessaan määritellään Parent_Config-osion override_full_sections kohdassa.
Esimerkiksi /local/config/vufind/config.inin tiedostossa määritellään osiot Languages, AlphaBrowse_Types ja SearchTabs yliajettaviksi kokonaan:
[Parent_Config] relative_path = "../finna/config.ini" override_full_sections = "Languages,AlphaBrowse_Types,SearchTabs"
Sen sijaan saman tiedoston Site-osioon voi lisätä uuden asetuksen yliajamatta koko osiota.
Esimerkki: lisätään Site-osion systemMessages taulukkoon uusi ilmoitus.
[Site] ... systemMessages[] = "Kirjastojärjestelmässä huoltotöitä maanantaina 1.1. klo 10-11."
Yleensä jos osiosta halutaan poistaa valintoja, osio täytyy yliajaa kokonaan.
Esimerkki: määritellään tarkennetun haun lomakkeen halutut kentät osiossa Advanced_Searches. Lisätään yliajettavan osion nimi kohtaan override_full_sections.
[Parent_Config] relative_path = "../finna/searches.ini" override_full_sections = "Views,Autocomplete_Sections,Advanced_Searches" [Advanced_Searches] AllFields = adv_search_all Title = adv_search_title JournalTitle = adv_search_journaltitle Author = adv_search_author Subject = adv_search_subject
Väliaikaistiedostot
Finna kirjoittaa väliaikaistiedostoja local/cache-hakemistoon tai sen alihakemistoihin. Näitä tiedostoja (esim. hakemistosta löytyviä kuvia tai rss-syötteitä) ei voi käyttää omiin tarkoituksiin, koska cache-hakemistojen sisältö voidaan poistaa milloin tahansa, eikä sitä julkaista näkymän julkaisutoimintoa käytettäessä.
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 sisällön räätälöinti tehdään yliajamalla Finna-teeman tiedostoja tai lisäämällä additions-sivupohjia. On suositeltavaa käyttää additions-sivupohjia teeman alkuperäisten tiedostojen muokkauksen sijaan, koska silloin ei tarvitse huolehtia itse teeman alkuperäisiin tiedostoihin tehtävien muutosten ja korjausten kopioinnista omiin ylikirjoitettuihin tiedostoihin. Additions-sivupohjia on kuitenkin vain tietyissä yleisesti käytetyissä kohdissa, ja niillä voi tehdä vain lisäyksiä sivuille.
Esimerkiksi jos halutaan räätälöidä tiedostoa /themes/finna/templates/footer.phtml
, tästä tiedostosta tehdään paikallinen versio /themes/custom/templates/footer.phtml
. Helpoiten tämä onnistuu etsimällä haluttu tiedosto Finna-teeman alta ja valitsemalla "Ylikirjoita tiedosto", jolloin tiedosto kopioidaan custom-teeman alle oikeaan hakemistorakenteeseen ja avataan muokattavaksi tiedostoeditoriin.
Samannimisen tiedoston voi tehdä myös kokonaan alusta aloittaen tyhjästä tiedostosta.
Esimerkki
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:
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ä.
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.
Toisista sivupohjista on erilliset versiot eri kieliversioille. Näissä tapauksissa sivupohjan nimen perässä on kielikoodi ennen tiedostopäätettä, esimerkiksi home-1_fi.phtml. Mikäli nimessä ei ole kielikoodia, samaa tiedostoa käytetään kaikissa kieliversioissa.
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. Sivupohjat voi tehdä kaikille kielille yhteisesti (esim. header-navibar.phtml) tai kielikohtaisesti lisäämällä tiedoston nimeen _kielikoodi
(esim. header-navibar_fi.phtml). Yleisesti käytetyt kielikoodit ovat fi
, sv
ja en-gb
. Allaolevassa listassa on tiedostojen nimet ilman kielikoodia.
Sivupohja | |
---|---|
general-post-body.phtml | HTML:n body -elementin lopussa. |
general-post-head.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.phtml | Hakutulossivulla, fasettien jälkeen. |
record-post-metadata.phtml | Tietuesivulla, tietuekenttien jälkeen. |
record-post-toolbar.phtml | Tietuesivulla, tietuekuvan toimintojen alapuolella. |
record-post-recommendations.phtml | Tietuesivulla, samankaltaisten teosten jälkeen. |
login-pre.phtml | Kirjautumissivun alussa. |
login-post.phtml | Kirjautumissivun lopussa. |
online-payment.phtml | Verkkomaksulomakkeella. |
checkedout-pre-list.phtml | Asiakkaan lainalistan yläpuolella (myös silloin, kun lainoja ei ole). |
checkedout-post-list.phtml | Asiakkaan lainalistan alapuolella. |
holds-pre-list.phtml | Asiakkaan varauslistan yläpuolella (myös silloin, kun varauksia ei ole). |
holds-post-list.phtml | Asiakkaan varauslistan alapuolella. |
storageretrievalrequests-pre-list.phtml | Asiakkaan varastonoutopyyntölistan yläpuolella (myös silloin, kun pyyntöjä ei ole). |
storageretrievalrequests-post-list.phtml | Asiakkaan varastonoutopyyntölistan alapuolella. |
illrequests-pre-list.phtml | Asiakkaan kaukolainalistan yläpuolella (myös silloin, kun kaukolainoja ei ole). |
illrequests-post-list.phtml | Asiakkaan kaukolainalistan alapuolella. |
fines-pre-list.phtml | Asiakkaan maksulistan yläpuolella (myös silloin, kun maksuja ei ole). |
fines-post-list.phtml | Asiakkaan maksulistan alapuolella. |
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="https://finna.fi">Finna</a> | Ulkoinen linkki. |
<a href="<?=$this->url(‘<toiminto>');?>”>Linkki</a> | Linkki näkymän toimintoon. Esimerkkejä toiminnoista (kaikki toiminnot listataan tiedostoissa /module/VuFind/config/module.config.php ja /module/Finna/config/module.config.php):
|
<a href="<?= $this->url('content-page', ['page' => 'xx'])?>">Linkki</a> | Linkki sisältösivulle (/Content/xx). Esimerkiksi ohjesivulle linkitetään seuraavasti: <?=$this->url('content-page',['page'=>'help'])?> |
<a href="<?=$this->url(‘<toiminto>');?>#ankkuri”> | Linkitys tiettyyn kohtaan sivulla. Esimerkiksi ohje-sivun kohtaan Tarkennettu haku: <a href="<?= $this->url('content-page', ['page' => 'help'])?>#advancedsearch">Tarkennetun haun ohje</a> |
Uuden sisältösivun luominen
Jos halutaan luoda esimerkiksi suomenkielinen sivu "Yleistä tietoa", se luodaan /themes/custom/templates/Content
-hakemistoon 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 sijoittaa vapaasti omaa HTML-sisältöä ja muotoiluja. Esimerkki:
<? $this->headTitle($this->translate('Oma sivu')); $this->content()->setHeading($this->translate('Oma sivu')); ?> <div class="row"> <div class="col-md-10 col-lg-8"> <h1>Otsikko</h1> <h2>Otsikko</h2> <h3>Otsikko</h3> <h4>Otsikko</h4> <p>Sisältötekstiä. <strong>Lihavoitu teksti</strong></p> <ul> <li>lista 1</li> <li>lista 1</li> <li>lista 1</li> <li>lista 1</li> </ul> </div> </div> <div class="row"> <div class="col-md-6"> <h2>Palsta 1</h2> <p>Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore e</p> </div> <div class="col-md-6"> <h2>Palsta 2</h2> <p>Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore e</p> </div> </div> <div class="row"> <div class="col-md-4"> <h2>Palsta 1</h2> <p>Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore e</p> </div> <div class="col-md-4"> <h2>Palsta 2</h2> <p>Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore e</p> </div> <div class="col-md-4"> <h2>Palsta 3</h2> <p>Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore e</p> </div> </div>
Ensimmäisellä rivillä asetetaan sivun otsikko näkymään selaimen otsikkopalkissa ja sisältösivun otsikkopalkissa. Tässä "Oma sivu" on käännösavain, jonka kielikäännökset syötetään muiden käännösten tapaan.
SIvun sisältö on jaettu allekkain kolmen div-elementin sisään, joissa käytetään CSS-luokkaa "row". Ensimmäisen sisällä on esimerkkejä tekstin muotoilusta. Toisen osion sisältö on jaettu kahteen palstaan ja kolmannen kolmeen palstaan. Bootstrapin CSS-luokkien (col-md-6, col-md-4 jne) käyttäminen varmistaa, että sivupohjata toimii eri päätelaitteilla.
Uuden sivun voi myös muokata olemassa olevan sisältösivun pohjalta. Yksipalstaisen sivun malliksi käy /themes/finna/templates/content/about_fi.phtml.
Sivun sisäinen navigaatio
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.
Mallin voi myös kopioida Ohje-sivulta: /themes/finna/templates/content/help_fi.phtml.
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...