Önkormányzati költségvetés vizualizáció 2.0+
KÖKÖ: Közérthető Költségvetés
Az oldal alapja a StartBootstrap / Creative sablon, illetve az önkormányzati költségvetés vizualizáció v1.x.
Copyright © 2020 DeepData Ltd.
Beüzemelés
A weboldal a Gridsome keretrendszeren alapul, ami a forrásfájlokból egy optimalizált weboldalt generál.
A beüzemelés lépései:
- Telepíts Node.js-t és Yarn-t, ezek adják az alapvető környezetet a projekthez.
- Telepítsd a Gridsome-ot parancssorból:
yarn global add @gridsome/cli
, ez fogja legenerálni a kész weboldalt. - A projekt mappájában futtasd le a
yarn install
parancsot, ez letölti a szükséges csomagokat anode_modules
mappába. - Másold be az önkormányzattól kapott XLSX fájlt az
input
mappába,budget.xlsx
néven. - Futtasd le a
yarn new-config
parancsot, ez legenerálja azinput/config.xlsx
fájlt, melynek tartalma részben függ abudget.xlsx
-től. - Töltsd ki a
config.xlsx
fájlt, ez tartalmazza a weboldal beállításait és szövegeit. - Ellenőrizd, hogy az alábbiakban bemutatott XLSX fájlok mind jelen vannak-e az
input
mappában, és mindegyiknek megfelelő-e a formátuma. - A projekt mappájában futtasd le a
yarn prepare
parancsot, ez azinput
mappában levő fájlokban rejlő adatokat átalakítja a vizualizációnak megfelelő formátumra. A generált adatfájlok azsrc/data
mappába kerülnek, a weboldal fejlesztésekor és generálásakor innen lesznek kiolvasva. - A projekt mappájában indítsd el a
gridsome develop
parancsot, mely egy lokális webszervert nyit. Ezután a http://localhost:8080/ címen meg tudod tekinteni a weboldal előnézetét. Ahogy módosítod a fájlokat, az előnézet is frissülni fog. A programot aCtrl+C
kombinációval lehet leállítani. - A weboldal legenerálásához használd a
gridsome build
parancsot. (Ez lefuttatja aprepare
szkriptet is.) A kész weboldal adist
mappába kerül, ennek tartalmát kell a webszervereddel hosztolnod. - A kereső naplózás funkciójához szükség van telepített PHP interpreterre is, valamint a következő parancs lefuttatására a hosztolt mappában:
touch search.log && sudo chown www-data:www-data search.log
. Asearch.log
fájlt érdemes publikusan elérhetetlenné tenni (ld.static/.htaccess
). Ha erre a naplózó funkcióra nincs szükség, atrack-search.php
fájlt ajánlott törölni a webszerverről.
Mappastruktúra
- dist/ (generált) - Ebbe a mappába generálja a Gridsome a kész weboldalt.
- input/ - Ebbe a mappába kell helyezni az input adatokat.
- scripts/ - Ebben a mappában segédszkriptek vannak.
- src/ - A weboldal forrásfájljai.
- static/ - A weboldal statikus fájljai, amik a build folyamat során érintetlenül át lesznek másolva a kimeneti mappába. Ezen belül lehet elhelyezni a képeket és videókat.
Adatok
A vizualizáció az alábbi adatfájlokból dolgozik:
- input/budget.xlsx - A vizualizáció adatainak forrása.
- input/config.xlsx - A weboldal beállításai és szövegei.
- input/tags.xlsx - A kereső által használt címkehalmazok.
- src/data/config.js - A weboldal beállításai, szövegei.
- src/data/data.json (generált) - A vizualizáció adatai, előkészítve.
- src/data/functions.tsv (generált) - A funkcionális kategóriák fa struktúrája.
- src/data/milestones.json (generált) - A fejlesztések leírásai, előkészítve.
- src/data/tags.json (generált) - A kereső által használt címkehalmazok, előkészítve.
- src/data/tooltips.json (generált) - Az egyes kategóriákhoz tartozó tooltip-ek szövegei, előkészítve.
Markdown formátum
Az alábbiakban bemutatott input fájlokban helyenként támogatott a Markdown formátum használata. Ez azt jelenti, hogy az egyszerű szöveghez hozzáadhatók a Markdown nyelv speciális karakterei és szerkezetei, annak érdekében, hogy a szöveg végül a honlapon formázottan jelenjen meg. A KÖKÖ által támogatott Markdown jelölések és formázások az alábbiak:
Input (Markdown szöveg) | Output (honlapon megjelenő formázott szöveg) |
---|---|
A **második** szó félkövér lesz. |
A második szó félkövér lesz. |
A _második_ szó dőlt lesz. |
A második szó dőlt lesz. |
Itt egy [linket](https://www.markdowntutorial.com/) helyeztünk el. |
Itt egy linket helyeztünk el. |
- Ez |
|
1. Ez pedig |
|
A listák esetében fontos, hogy az első listaelem előtt és az utolsó listaelem után legyen 1-1 üres sor.
input/budget.xlsx
Az általános KGR rendszer importja. A munkafüzet több munkalapból állhat, melyek elnevezése a következő alakú lehet: ÉVSZÁM <TÍPUS>
vagy ÉVSZÁM_<TÍPUS>
, ahol a <TÍPUS>
helyén BEVÉTEL
, BEVETEL
, KIADÁS
vagy KIADAS
állhat (a kis- és nagybetűk nincsenek megkülönböztetve). Az ÉVSZÁM
tetszőleges szöveg lehet, nem csak számjegyek.
A munkalapoknak 2 formátumát ismeri a program. Az egyik az elmúlt évekre vonatkozik, a másik a prognózisokra. A bevételi és kiadási oldal adott éven belül azonos formátumú. Prognózisok esetében a funkcionális bontást nem tartalmazza az input.
Elmúlt évekre vonatkozó formátum
Az ilyen munkalapokon megtalálható a mátrix, vagyis nem csak közgazdasági bontásban vannak az adatok, hanem funkcionális bontásban is. Elvárt formátum:
- 1. sor: lényegtelen
- 2. sor: a 4. (D) oszloptól kezdve funkcionális kategóriák
<AZONOSÍTÓSZÁM> <ELNEVEZÉS>
formában. Az elnevezés lényegtelen. A programnak csak az azonosítószám kell, amit szóközzel kell elválasztani a többi adattól, pl.: "042120 Mezőgazdasági támogatások". - 3. sortól kezdve:
- 1. oszlop: egy legalább kétjegyű számot kell tartalmaznia ahhoz, hogy a program az adott sort adatsornak vegye és feldolgozza, noha e cella értéke nem lesz másra használva (így kézileg hozzáadott soroknál megadható akár
99
is). - 2. oszlop: közgazdasági kategória elnevezése és kiegészítő információi.
- A cellákban szerepelnie kell a kategória azonosítójának,
(B123)
vagy(K123)
formában. Ezek az azonosítók egymással hierarchiában vannak: egyBx
azonosító gyermekei aBx
prefixű, eggyel több számjegyű azonosítók, ÉS aBx
azonosítójú, "ebből:" kezdetű kategóriák. Előfordul, hogy a szintek között nem egy, hanem két számjegy különbség van. - Az azonosítóknál az
FH
ésFT
prefix is engedélyezett, melyek 1 számjegyes szintje a Mérleg ábrán fog megjelenni, középen, zöld színnel. - A cellában opcionálisan szerepelhet egy összegképlet, de ezt a program nem használja, és ki is fogja vágni.
- Példa: "Működési célú támogatások államháztartáson belülről (=07+...+10+21+32) (B1)"
- A cellákban szerepelnie kell a kategória azonosítójának,
- 3. oszlop: az adott közgazdasági kategóriához tartozó összeg
- 4. oszloptól kezdve: az adott közgazdasági (sor) és funkcionális (oszlop) kategóriához tartozó számérték.
- A számértékből beolvasáskor a
,
és szóköz karakterek eltávolításra kerülnek.
- 1. oszlop: egy legalább kétjegyű számot kell tartalmaznia ahhoz, hogy a program az adott sort adatsornak vegye és feldolgozza, noha e cella értéke nem lesz másra használva (így kézileg hozzáadott soroknál megadható akár
Prognózisra vonatkozó formátum
Az ilyen munkalapokról hiányzik a funkcionális bontás. A formátum hasonló az előbbiekben leírtakhoz, az alábbi módosításokkal:
- 1.-3. sor: lényegtelen
- a közgazdasági kategóriák bontása a 4. sortól kezdődik
input/config.xlsx
Ez a fájl írja le a weboldal beállításait és szövegeit. A szerkeszthető oszlopokat sárgás szín jelöli.
Ez a fájl a budget.xlsx
alapján van generálva, a "tooltips <ÉVSZÁM>" munkalapok az aktuális költségvetésben szereplő kategóriákat tartalmazzák.
A "config" munkalap formátuma:
- az 1. sor a fejléc, melynek első 2 eleme kötelezően "key" és "value"
- a 2. sortól kezdve kulcs-érték párok, magyarázattal:
- 1. oszlop: kulcs, mely azonosítja a beállítást/szöveget a program számára
- 2. oszlop: testreszabható érték, bizonyos esetekben a Markdown formátum támogatott (ez a magyarázatban jelezve van)
- 3. oszlop: magyarázat
A "tooltips <ÉVSZÁM>" munkalapok formátuma:
- az 1. sor a fejléc, a cellák értéke nincs megkötve
- a 2. sortól kezdve kulcs-érték párok, magyarázattal:
- 1. oszlop: funkcionális/közgazdasági kategória azonosító (funkcionális bontásnál egy természetes szám, közgazdasági bontásnál a
B123
vagy aK123
alakú azonosító) - 2. oszlop: funkcionális/közgazdasági kategória megnevezése
- 3. oszlop: testreszabható súgószöveg az adott kategóriához
- 1. oszlop: funkcionális/közgazdasági kategória azonosító (funkcionális bontásnál egy természetes szám, közgazdasági bontásnál a
A "milestones" munkalap formátuma:
- az 1. sor a fejléc, melynek oszlopai kötelezően (a sorrend mindegy):
- "nodeId"
- "year"
- "imageFile"
- "videoFile"
- "title"
- "descriptionInMarkdown"
- "tags"
- a 2. sortól kezdve a fejlesztések adatai:
- "nodeId" oszlop: azon kategória azonosítója, amelyhez ez a fejlesztés tartozik (funkcionális bontásnál egy természetes szám, közgazdasági bontásnál a
B123
vagy aK123
alakú azonosító). Több azonosító is megadható, vesszővel elválasztva. Opcionális. - "year" oszlop: azon év, amelyhez a fejlesztés tartozik
- "imageFile" oszlop: a fejlesztéshez tartozó képfájl elérési útvonala vagy URL-je (linkje)
- "videoFile" oszlop: a fejlesztséhez tartozó videó (opcionális), ami egy MP4 fájlra kell mutasson
- "title" oszlop: a fejlesztés megnevezése, minél rövidebb, annál jobb
- "descriptionInMarkdown" oszlop: a fejlesztés rövid leírása, Markdown formátum támogatott
- "tags" oszlop: a fejlesztés címkéi, vesszővel elválasztva
- "nodeId" oszlop: azon kategória azonosítója, amelyhez ez a fejlesztés tartozik (funkcionális bontásnál egy természetes szám, közgazdasági bontásnál a
A "functions munkalap formátuma:
A funkcionális kategóriák fa struktúráját írja le.
- az 1. sor a fejléc, melynek oszlopai kötelezően (a sorrend mindegy):
- "id"
- "name"
- "parent"
- a 2. sortól kezdve a funkcionális kategóriák definíciói
- "id" oszlop: a kategória azonosítója, egész szám
- "name" oszlop: a kategória megnevezése
- "parent" oszlop: a szülő kategória azonosítója, egész szám. Ha nem létező definiált kategóriára mutat, akkor az aktuális kategória a gyökérbe kerül.
input/tags.xlsx
A kereső funkciónak 4 címkehalmazra van szüksége:
- bevételi oldal, közgazdasági bontás
- bevételi oldal, funkcionális bontás
- kiadási oldal, közgazdasági bontás
- kiadási oldal, funkcionális bontás
Ezeket az adatokat a tags.xlsx
-ben, egyetlen munkalapon (az elsőn!) kell megadni, az alábbi szerkezetben:
- az 1. sor opcionálisan lehet fejléc
- további sorok:
- 1. oszlop az oldalt jelöli:
expense
(kiadás) vagyincome
(bevétel) - 2. oszlop a bontást jelöli:
econ
(közgazdasági) vagyfunc
(funkcionális) - 3. oszlop a kategória azonosítót tartalmazza: funkcionális bontásnál egy természetes szám, közgazdasági bontásnál a
B123
vagy aK123
alakú azonosítókat használni. A cellában az azonosító után opcionálisan szerepelhet egy szóköz után a kategória elnevezése is a szerkesztést segítendő, de ezt a program nem fogja olvasni. - 4. oszlop tartalmazza a címkéket: vesszővel, és opcionálisan még szóközzel is elválasztott kifejezések
- 1. oszlop az oldalt jelöli:
src/data/functions.tsv (generált)
Tartalma a config.xlsx "functions" munkalappal ekvivalens, fejléc sor nélkül.
src/data/data.json (generált)
Ezt a fájlt a budget.xlsx
tartalmából generálja a prepare-data.js
szkript. Ez a fájl tartalmazza a több éves költségvetési adatokat az alábbi struktúrában:
{
"<évszám>": {
"expense": {
"econ": { ... },
"func": { ... }
},
"income": {
"econ": { ... },
"func": { ... }
}
},
...
}
Az expense
mező a kiadások, az income
a bevételek adatait tartalmazza. Az econ
a közgazdasági, míg a func
a funkcionális bontásban írja le az adatokat. Mindkét bontás 1-1 gyökér node-ot tartalmaz. A node-ok struktúrája:
{
"id": 123,
"name": "...",
"value": 12345678,
"children": [ ... ]
}
- id - A kategória azonosítója, funkcionális kategória esetén természetes szám, közgazdasági kategóriáknál
B123
vagyK123
alakú azonosító. - name - A kategória elnevezése.
- value - Az adott node-hoz tartozó összeg.
- children - Gyerek node-ok tömbje.
src/data/milestones.json (generált)
Ezt a fájlt a milestones.xlsx
tartalmából generálja a prepare-milestones.js
szkript. Ez a fájl tartalmazza a Fejlesztések szakasz tartalmát.
Formátuma JSON, struktúra:
{
"milestones": {
"fejl-1": {
"year": 2018,
"picture": "...",
"title": "...",
"description": "...",
"vid": "..."
},
...
},
"rels": {
"2018": {
"K123": "fejl-1",
...
},
...
}
}
A milestones
objektumban a kulcsok a fejlesztés azonosítók, az érték pedig egy objektum az alábbi mezőkkel:
year
: évszám (amelyikhez a fejlesztés tartozik)picture
: a képfájl elérési útvonalatitle
: fejlécdescription
: leírás
A rels
objektum évekre bontva tartalmazza a kategóriákhoz tartozó fejlesztéseket. A bontásokhoz tartozó objektumban a kulcsok a kategória azonosítók, az értékek a fejlesztés azonosítók.
src/data/tags.json (generált)
Ezt a fájlt a tags.xlsx
tartalmából generálja a prepare-tags.js
szkript. Ez a fájl tartalmazza a 4 címkehalmazt a 2 költségvetési oldalhoz és 2 bontáshoz.
Formátuma hasonló struktúrát követ, mint a data.json
, csak itt nincsenek évszámok, és node-ok helyett címkehalmazokat ír le.
{
"expense": {
"econ": [ "címke1", "címke2", ... ],
"func": [ ... ]
},
"income": {
"econ": [ ... ],
"func": [ ... ]
}
}
src/data/tooltips.json (generált)
Ezt a fájlt a config.xlsx
-ben levő tooltips <ÉVSZÁM>
munkalapokból generálja a prepare-tooltips.js
szkript. Ez a fájl tartalmazza a kategóriákhoz tartozó tooltip-ek szövegeit, évekre bontva.
Formátuma JSON: egyetlen objektum, benne év, ill. kategória azonosító (B1
, B2
, K1
, K2
, stb.) kulcsokhoz rendelve a tooltip szövegek.
Ha egy kategóriához nem szerepel tooltip szöveg ebben a fájlban, ott nem fog megjelenni a tooltip.
{
"2020": {
"B1": "Lorem ipsum for B1",
"B2": "Lorem ipsum for B2",
...
},
"2020 MÓDOSÍTOTT": {
...
},
...
}
Szövegek és beállítások
Az oldalon megjelenő szövegeket és a SEO beállításokat (amik nem a data.json
-ból jönnek) az input/config.xlsx
fájlban lehet szerkeszteni, mely tartalmazza az egyes mezők magyarázatait is.
A képeket (favicon, logók, fejlesztések képei, stb.) az admin felület segítségével lehet egyszerűen cserélni. Az admin felületet az npm run admin
paranccsal lehet indítani és alapértelmezésként a http://localhost:8081/ címen lesz elérhető, "admin" felhasználónévvel és "admin" jelszóval.
Keresési napló
Az oldalon található kereső naplózza a beírt keresőkifejezéseket és a találatok számát. Mindezt a search.log
fájlba menti ki, melynek formátuma TSV, oszlopai:
- előfordulások száma (hányszor szerepelt az alábbi keresőkifejezés az alábbi találatszámmal)
- keresőkifejezés
- találatok száma
Admin felület beüzemelése
Magának a költségvetés site-nak a beüzemelése ezekből a fázisokból áll (ez van fentebb részletesebben):
- A forráskódban cserélni/módosítani kell az Excel és képfájlokat.
- Le kell generálni a site-ot a forráskódból (
npm run build
). - Ezután a
dist
mappában egy statikus weboldal fájljai lesznek, ezt lehet egy webszerverrel (pl. Apache, Nginx) hosztolni.
Az admin modul eme 3 lépés megkönnyítésére szolgál. Ez egy webalkalmazás, ami a forráskód mappájában fut, így le tudja cserélni a fájlokat, és meg tudja hívni az npm run build
parancsot. Mindezen műveletekhez pedig egy webes felületet biztosít.
Admin beüzemelés lépései részletesen:
- Telepíts Node.js-t és Yarn-t, ezek adják az alapvető környezetet a projekthez.
- A projekt mappájában futtasd le a
yarn install
parancsot, ez letölti a szükséges csomagokat anode_modules
mappába. - Készíts másolatot az
.env.example
fájlról.env
néven. - Szerkeszd az
.env
fájlt, hogy beállítsd az admin felületet:ADMIN_PORT=8081
- a port száma, amin a webes felület elérhető leszADMIN_USER=admin
- ezzel a felhasználónévvel lehet majd elérni az admin felületetADMIN_PASS=admin
- ezzel a jelszóval lehet majd elérni az admin felületetPUBLIC_URL=https://pelda.koltsegvetes.hu/
- az admin felület jobb felső sarkában levő zöld gomb ide fog linkelniDEPLOY_CMD=
- itt lehet megadni azt a parancsot, ami adist
mappát (vagyis a legenerált költségvetés site-ot) a webszerverre kiteszi (pl. ez lehet akár másolás, feltöltés, de akár lehet üresen is hagyni, ha a költségvetést ugyanazon a gépen levő webszerverrel hosztolod és erre a mappára állítottad be a root-ot)
- Az admin felület az
npm run admin
paranccsal indítható el, és böngészőben pl. a http://localhost:8081/ címen lesz elérhető.
Ahhoz, hogy az admin felület publikusan is elérhető legyen, az alábbiakra van szükség:
- Állíts be egy domain nevet (pl. admin.pelda.koltsegvetes.hu) úgy, hogy arra a szerverre mutasson, ahol az admin fut.
- Telepíts és indíts el egy webszervert (pl. Apache vagy Nginx) ugyanazon a gépen.
- Állítsd be a webszervert úgy, hogy kiszolgálja az 1. pontban beállított domain nevet, és proxy-zza a kéréseket az admin felület portjára.
Apache példa konfig:
<VirtualHost *:80>
ServerAdmin elek@teszt.hu
ServerName admin.pelda.koltsegvetes.hu
ProxyPass / http://localhost:8081/
ProxyPassReverse / http://localhost:8081/
</VirtualHost>
Nginx példa konfig:
server {
listen 80;
server_name admin.pelda.koltsegvetes.hu;
location / {
proxy_redirect off;
proxy_set_header Host $host;
proxy_set_header X-Real-IP $remote_addr;
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
proxy_set_header X-Forwarded-Proto $scheme;
proxy_read_timeout 1m;
proxy_connect_timeout 1m;
proxy_pass http://127.0.0.1:8081;
}
}