Näkymän räätälöinti

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:

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.

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:

templates/search/home/home-left.phtml

templates/search/home/homerighttop.phtml

templates/search/home/home-2.phtml

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.

general-post-body.phtml

general-post-head.phtml

header-navibar.phtml

search-post-facets.phtml

record-post-metadata.phtml

record-post-toolbar.phtml

record-post-recommendations.phtml

login-pre.phtml

login-post.phtml

online-payment.phtml

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):

col-xs-12

<div class="col-xs-12"><h2>Otsikko</h2></div>

col-sm-6

<div class="col-md-6">Palsta 1</div>
<div class="col-md-6">Palsta 2</div>

col-sm-4

<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 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'); ?>

<p>Tekstiä</p>

<img src="<?=$this->imageSrc('tiedostonimi.jpg')?>">

<?=$this->translate('XXX');?>

<a href="<?=$this->url(‘<toiminto>');?>”>Linkki</a>
<a href="<?= $this->url('search-home')?>">Etusivulle</a> 

<?=$this->url('content-page',['page'=>'help'])?>

<a href="<?=$this->url(‘<toiminto>');?>#ankkuri”>
<?= $this->url('content-page',  ['page' => '<sivu>'])?>#ankkuri 

<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.

Ylävalikko

Seuraava ohje koskee 8.9.2016 julkaistavaa versiota.

Ylävalikon rakenne määritellään Muut asetukset -välilehden kohdassa Navigointivalikko.

Listalla esitetään valikkoelementit ja näihin kuuluvat linkit, jotka näytetään kun valikko avataan. Elementtien järjestystä voi muokata raahaamalla elementin haluttuun kohtaan listalla. Ylävalikkoon voi lisätä uuden valikkoelementin klikkaamalla listan lopussa olevaa "Lisää valikkoelementti" nappia.  Finnan navigointivalikon oletuselementit voi asettaa piiloon tai esille elementin kohdalla olevasta valintaruudusta. Itse lisätyt elementit voi poistaa klikkaamalla elementin kohdalla olevaa punaista ruksia.

Valikkoelementtien ja linkkien asetuksia muokataan kynä-ikonia klikkaamalla. Valikkoelementin asetuksissa määritetään käännöskoodi ja valikon otsikko näkymän käyttämille kieliversioille:

Linkin asetuksissa määritetään käännöskoodi, nimi ja valinnainen kuvaus, linkin toiminto, avataanko toiminto uudelle välilehdelle ja missä kieliversioissa linkki näytetään.

Toiminto on jokin seuraavista:

• Sisältösivu: avaa valitun sisältösivun. Kansio-ikonia klikkaamalla näyteään lista, joka sisältää Finnan sisältösivut ja näkymän omat sisältösivut hakemistosta /themes/custom/templates/content.
• URL: avaa www-osoitteen
• Toiminto: organisaationäkymän toiminto, esimerkiksi:
  • Näkymän etusivu: search-home
  • Tarkennettu haku: advanced-search
  • Selailunäkymä: browse-home
    jne

Linkille voi määritellä kielikohtaisen toiminnon valitsemalla pois "Käytä samaa toimintoa muilla kielillä" ja määrittämällä toiminnot kaikille kielille.

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:

tooltip_facet_html

tooltip_local_search

tooltip_pci_search_html

tooltip_local_advanced

tooltip_pci_advanced_html

tooltip_myaccount_html

tooltip_tabs_local_html

tooltip_tabs_pci_html

tooltip_tabs_combinened_html

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...