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

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

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:

general-post-body_<kieli>.phtml

general-post-head_<kieli>.phtml

header-navibar.phtml

search-post-facets_<kieli>.phtml

record-post-metadata_<kieli>.phtml

record-post-toolbar_<kieli>.phtml

record-post-recommendations_<kieli>.phtml

login-pre_<kieli>.phtml

login-post_<kieli>.phtml

online-payment_<kieli>.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-sm-6">
        <h1>Otsikko</h1>
		<h2>Otsikko</h2>
		<h3>Otsikko</h3>
		<h4>Otsikko</h4>
        <p>Sisältötekstiä. <strong>Lihavoitu teksti</strong> </p>
		<p><a href="<?= $this->url('search-home')?>">Etusivulle</a></p>
		<ul>
			<li>lista 1</li>
			<li>lista 1</li>
			<li>lista 1</li>
			<li>lista 1</li>
		</ul>
    </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ä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.

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:

tooltip_facet_html

tooltip_local_search

tooltip_pci_search_html

tooltip_metalib_search_html

tooltip_local_advanced

tooltip_pci_advanced_html

tooltip_metalib_advanced

tooltip_myaccount_html

tooltip_tabs_local_html

tooltip_tabs_pci_html

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