Mat-O-Wahl - Dokumentation

Kurzanleitung

Voraussetzungen

Mat-o-Wahl und DSGVO (EU Datenschutz-Grundverordnung)

Allgemeine Hinweise

Allgemein

Alle wichtigen Einstellungen werden in einer Textdatei namens definition.js im Verzeichnis /data gemacht. Diese kann mit einem Texteditor (Notepad, Wordpad, ...) bearbeitet werden. Zur besseren Übersicht sollte die Datei aber mit einem Editor mit Syntax-Hervorhebung bearbeitet werden, z.B. Notepad++ für Windows oder andere.

In dieser Datei kann man Kontaktinformationen für das Impressum angeben und erklärende Texte wer und was gewählt wird. Außerdem werden hier die Dateien mit den Parteien und den Fragen definiert.

Hinweis zu CSV-Dateien

Alle Fragen und Parteipositionen sind in einfachen CSV-Dateien abgespeichert. Das sind normale Textdateien, die man sowohl mit einem Texteditor (z.B. Notepad, Wordpad, ...) als auch mit einer Tabellenkalkulation (MS Excel, OO Calc, ...) bearbeiten kann. Die Spalten sind voneinander mit einem einfachen Trennzeichen getrennt, z.B. ein Komma oder ein Semikolon. Die Namen dieser CSV-Dateien kann man selbst in der "definition.js"-Datei angeben.

Beispiel einer CSV-Datei

Ansicht einer kommagetrennten CSV-Datei im Texteditor (Ausschnitt aus der Parteien-CSV-Datei) ...

Partei_kurz:;"Bananen"
Partei_lang:;"Bananenrepublikpartei"
Partei_Beschreibung:;"Warum ist die Banane krumm? [...]
Partei_URL:;"https://www.banane.ba"
Partei_Bild:;"data/banane.jpg"
1;"Gelb ist die beste Farbe! Lorem ipsum [...]
[...]

Kurze Video-Anleitung

Beispielhaftes Vorgehen mit einigen Einstellungen. (2:13 min)

• Die Datei der Fragen verändern.
• Die Datei der Parteien und Antworten verändern.
• Die allgemeinen Einstellungen verändern.

Schreibweise

Alle Texte auf einer Zeile (also alle Werte außer den Zahlen) müssen mit Anführungszeichen (") umschlossen werden.
Texte über mehrere Zeilen (z.B. im Impressum) dürfen mit einem Akzent (`) umschlossen werden. Alle modernen Browser verstehen diese Syntax. Alte Versionen des Internet Explorer haben damit Probleme.

Bei den Dateinamen sollte man keine Leerzeichen und Sonderzeichen wie Umlaute oder ß verwenden und man muss außerdem auf Groß- und Kleinschreibung achten! Eine "datei.txt" ist keine "Datei.txt".

Einstellungen am Beispiel Obsthausen

Mat-O-Wahl öffnen - Definition.js öffnen (Link auf externen Github-Server)

Allgemeine Einstellungen

Variable	Wert	Beschreibung
Parteien und Fragen
fileQuestions	Obsthausen_Fragen.csv (Link auf externen Github-Server)	Die Datei mit den Fragen an die Parteien. In diesem Fall gibt es sechs Fragen. Die erste Spalte der CSV-Datei enthält eine Kurzzusammenfassung der Frage, die zweite Spalte enthält die eigentliche Frage.
intQuestions	6	Anzahl der Fragen an die Parteien. (seit Version 0.5)
fileAnswers	Obsthausen_Parteien.csv (Link auf externen Github-Server)	Die Datei mit den Antworten der Parteien und Informationen zur Partei / zum Kandidat. (seit Version 0.5) Die Datei hat folgenden Aufbau: Partei_kurz: ; Parteiname kurz (z.B. APPD) Partei_lang: ; Parteiname lang (z.B. Appelpartei Deutschlands) Partei_Beschreibung: ; Partei-Beschreibung (optional, z.B. Die Apfelpartei steht seit vielen Jahren für alle Angelegenheiten des Apfels.) Partei_URL: ; Partei-Webseite (z.B. https://www.appelpartei.ap) Partei_Bild: ; Partei-Logo / Bilddatei (z.B. images/appel.png) Danach kommen die Positionen und Antworten der Parteien, z.B. -1;Wir sind dagegen weil ... 0;Hier gibt es keine Meinung von uns oder neutral, weil ... 1;Wir sind dafür weil ... # ; Zum Schluss kommt noch ein Leerzeile ohne Funktion, nur für die Übersicht. Danach geht es mit der nächsten Partei weiter.
intParties	4	Anzahl der Parteien / Kandidaten. (seit Version 0.5)
arPartyFiles	...	Diese Variable wird seit Version 0.5 (08/2020) nicht mehr benötigt. Eine Liste mit Dateien der Parteipositionen. In diesem Fall gibt es vier Parteien, die zu jeder der sechs Fragen geantwortet haben. Die erste Spalte der CSV-Datei enthält die Position der Partei in Form einer Zahl. -1 steht für "stimme nicht zu", 0 für "Enthaltung" und 1 für "stimme zu". Die zweite Spalte enthält eine ausformulierte Begründung der Position.
arPartyNamesShort, arPartyNamesLong, arPartyLogosImg, arPartyInternet	...	Diese Variable wird seit Version 0.5 (08/2020) nicht mehr benötigt. Listen mit den Parteinamen in kurzer und langer Form, eine Liste mit Bildern zu den Parteilogos und eine Liste mit Links zu den Parteiseiten im Internet.
Aussehen und Verhalten
intPartyLogosImgWidth, intPartyLogosImgHeight	10%	Einstellung für die Bildgröße der Partei-Logos / Kandidaten-Logos in der Ergebnisliste. Die Breite und Höhe kann in Pixel oder Prozent angegeben werden.
intPartyDefaultShow	3	Diese Variable wird seit Version 0.3 (11/2018) nicht mehr benötigt. Siehe stattdessen die Erweiterung extras/addon_limit_results.js Anzahl der Parteien, die beim Einblenden der detaillierten Ergebnisliste sofort angezeigt werden sollen. Im Beispiel werden die ersten drei von den vier vorhanden Parteien angezeigt. Um alle Parteien anzeigen zu lassen, gibt man eine 0 ein.
descriptionShowOnStart	1	Soll am Anfang eine kurze Beschreibung angezeigt (1) werden oder sollen gleich die Fragen (0) starten? Wenn die Fragen sofort starten, gibt es einen kurzen "Loading"-Hinweis. (seit Version 0.6)
Namen der Variablen bis Version 0.5.1: heading1, heading2, explainingText Namen der Variablen ab Version 0.6: descriptionHeading1, descriptionHeading2, descriptionExplanation	...	Texte mit Überschriften und einer kurzen Erklärung zur Wahl.
Impressum
imprintLink	"system/imprint.html" oder "https://www.seite-von-meinem-kleinen-verein.de/impressum.html"	Impressum - Option A): Standard-Link auf das Impressum. Sie können hier aber auch auf Ihr eigenes Impressum verweisen. Falls Sie ein eigenes Impressum nutzen, können Sie Option B einfach ignorieren. Außerdem wäre ein Hinweis auf den Mat-o-Wahl günstig, z.B. "Der XXXXX-o-Mat basiert auf dem www.Mat-O-Wahl.de von Mathias Steudtner und ist freie Software unter GPL 3 Lizenz."
imprintGeneral, imprintContact, imprintVATid, imprintDisputeResultion, imprintEditors, imprintProgramming, imprintPictures, imprintPrivacyUrl	...	Impressum - Option B): Angaben für das Standard-Mat-o-Wahl-Impressum. Die Angaben spiegeln die rechtliche Situation in Deutschland 2020 wider. Der Fokus liegt dabei auf eingetragenen Vereinen (e.V.). Achtung: Dies ist keine Rechtsberatung. Ein eigenes Impressum ist meistens besser.

Wenn Sie eine Einstellung frei lassen wollen, löschen Sie bitte nicht die ganze Zeile, sondern nur den Inhalt. Ein Wert ohne Datenschutzerklärung sieht z.B. so aus: var imprintPrivacyUrl = "";

Erweiterte Einstellungen

Variable	Wert	Beschreibung
separator	";" oder ","	Das Trennzeichen mit welchem die CSV-Dateien voneinander getrennt sind. Microsoft Excel speichert zumeist mit Semikolon und OpenOffice Calc mit Komma ab. Alle CSV-Dateien müssen das gleiche Trennzeichen benutzen.
design	default.css	(bis Version 0.5.1) Eine StyleSheet-Datei (CSS) mit Formatvorlagen im Ordner /STYLES/
design	["default.css","buttons-colors-on.css", "progressbar.css"];	(ab Version 0.6) Eine Liste von StyleSheet-Dateien (CSS) mit Formatvorlagen im Ordner /STYLES/
addons	[] oder z.B. auch ["extras/addon_results_textfilter_by_button.js"]; oder z.B. auch ["extras/addon_results_textfilter_by_button.js", "extras/addon_check_iframe_resize_client.js", "extras/addon_limit_results.js"]	(ab Version 0.6) Eine Liste von Erweiterungen. Die Beschreibungen finden sich in den jeweiligen Dateien und in diesem Dokument.
language	de	Eine Sprachdatei mit den Texten im Ordner /i18n/

Profi-Einstellungen

Variable	Wert	Beschreibung
statsRecord	true oder 1, false oder 0	(optional - für Experten) Bietet die Möglichkeit die Ergebnisse des Nutzers an einen Server zu senden. Dafür muss jedoch eine Datenschutzerklärung vorhanden sein und der Nutzer muss der Übermittlung seiner Daten aktiv zustimmen ("OptIn-Verfahren").
statsServer	http://localhost/extras/statistics/vote_db.php	(optional - für Experten) Die Adresse und der Name des Skripts, welche die Daten empfängt. Es werden zwei Variablen übertragen - mowpersonal und mowparties. "mowpersonal" enthält die persönliche Auswahl des Nutzers in der Form Zustimmung/Ablehnung/Enthaltung/Übersprungen. Also z.B.: 1,-1,0,99 "mowparties" enthält die Anzahl der Übereinstimmungen mit den Parteien in der angegebenen Reihenfolge, z.B. 5,1,0,2 Ein Aufruf für 6 Fragen und 4 Parteien könnte dann also so aussehen: /vote_db.php?mowpersonal=1,1,-1,1,0,-1&mowparties=1.5,2,4,3.5

Testen der Einstellungen

Im Stammverzeichnis befindet sich eine QUICKTEST.HTML-Datei. Diese prüft die wichtigsten Einstellungen und sagt Ihnen, ob es einen schwerwiegenden Fehler in der Konfiguration gibt.

Der Mat-O-Wahl funktioniert (theoretisch) nicht beim Starten von lokaler Festplatte aus. Dies liegt am Sicherheits-Konzept aller modernen Browser. Diese verbieten das Ausführen von lokalen Dateien.
"Lokal" bedeutet die interne Festplatte oder SSD, die externe USB-Festplatte oder auch einen USB-Stick. Der Browser öffnet diese Dateien intern mit dem "file://"-Protokoll.

Der Mat-O-Wahl läuft aber:

• auf einem internen Webserver, wie Apache, nginx oder mit einem einfachen localhost-Aufruf, z.B. in Java oder python (http(s)://-Protokoll)
• auf einem externen Webserver / Webspace Ihrer Wahl (http(s)://-Protokoll)
• auf der lokalen Festplatte mit Google Chrome / Chromium mit dem Startparameter --allow-file-access-from-files
• auf der lokalen Festplatte mit Mozilla Firefox mit der Einstellungen (Adresszeile about:config) browser.tabs.remote.separateFileUriProcess = true

Allgemeines

Erweiterungen werden über die Variable addons in der DEFINITION.JS geladen. Standardmäßig ist diese Variable leer und es wird keine Erweiterung geladen.

var addons = []

Man kann eine oder x-beliebige viele (JavaScript)-Erweiterungen laden. z.B.

• Beispiel für eine Erweiterung: var addons = ["extras/addon_results_textfilter_by_button.js"]
• Beispiel für drei Erweiterungen: var addons = ["extras/addon_results_textfilter_by_button.js", "extras/addon_check_iframe_resize_same_domain.js", "extras/addon_whats_your_favorite_party.js"]
• Beispiel für eine Erweiterung in einem anderen Ordner: var addons = ["my_folder/my_file.js"]

Erweiterung ⇨ Textfilter für mehrere Wahlen

Funktion

Einstellungen

Datei öffnen (Link auf externen Github-Server)

1. Ein (Sonder)-Zeichen oder eine Zeichenkette für die Filter (im Array / in der Liste) bestimmen
   In diesem Beispiel gibt es vier Filter:
   var TEXTFILTER_KEYWORDS = ["​", "👤", "‍", "‎"]
   Die Sonderzeichen in diesem Beispiel sind "unsichtbare" Zeichen.
   Es könnte aber auch ein Text wie "BMK" (Bürgermeister-Kandidat), "StR" (Stadtrat), "Nord" oder ähnliches sein.
2. Einen Text für die Buttons in der gleichen Reihenfolge vergeben
   In diesem Beispiel gibt es vier Buttons:
   var TEXTFILTER_BUTTONTEXTS = ["Alle anzeigen", "Bürgermeisterkandidaten 👤 anzeigen", "Südfrüchte anzeigen", "Runde Früchte anzeigen"]
3. Das / Die gewünschte(n) Filter-Sonderzeichen in der PARTEIEN-ANTWORTEN.CSV in der Zeile mit der langen Parteibeschreibung einfügen. (bis Version 0.6.0.2: die Zeile mit dem kurzen Parteinamen)
   In diesem Beispiel gibt es mehrere Zeichen zu einer Partei. Es werden also mehrere Filter angewendet.
   Aktuelles Vorgehen seit Version 0.6.0.3:
   Partei_Beschreibung: ; "Die Apfelpartei steht seit vielen Jahren für alle Angelegenheiten des Apfels. 👤 ​ ‎"
Partei_Beschreibung: ; "Warum ist die Banane krumm? [...] alle Belange der Bananen. ​ ‍"
   Altes Vorgehen bis Version 0.6.0.2:
   Partei_kurz: ; "👤 APPD ​ ‎"
Partei_kurz: ; "Bananen ​ ‍"
4. Die Erweiterung in der DEFINITION.JS aktivieren.
   var addons = ["extras/addon_results_textfilter_by_button.js"]
5. Fertig.

Einschränkungen

• Es ist ein einfacher Textfilter. Wenn das gesuchte Zeichen woanders vorkommnt, wird es auch dort eingeblendet / ausgeblendet. z.B. Suche nach "ana" findet "Bananenpartei", "Ananaspartei" und "Anarchistische Partei"

Erweiterung ⇨ Einbinden des Mat-o-Wahl per <iframe> und Größe ändern

Funktion

Einstellungen

Host-Datei öffnen (Link auf externen Github-Server)
Client-Datei öffnen (Link auf externen Github-Server)

1. Wir benötigen etwas Code auf der Hauptseite, welche auch den iframe lädt. Damit wird die _host-Datei geladen und eine Funktion, welche die Höhe des Mat-o-Wahl im iframe empfängt.

   <script src="https://www.seite-von-meinem-kleinen-verein.de/mat-o-wahl/extras/addon_check_iframe_resize_host.js"></script>

<iframe id="myIframe" src="https://www.seite-von-meinem-kleinen-verein.de/mat-o-wahl/index.html" style="min-width:100%;" loading="lazy">
</iframe>

<script type="text/javascript">
document.getElementById("myIframe").addEventListener( "load", function() { fnMatoWahlIframeEventListener("myIframe"); } );
</script>

2. Die (Client)-Erweiterung in der DEFINITION.JS aktivieren.

   var addons = ["extras/addon_check_iframe_resize_client.js"]

Einschränkungen

• Bitte prüfen Sie, ob nicht schon eine CSS height existiert.
• Der Mat-o-Wahl nutzt die Bootstrap CONTAINER-FLUID-class. Es könnte zu unschönen Rändern auf dem Smartphone kommen.
• Wenn man zur nächsten Frage springt, kann es (in seltenen Fällen) passieren, dass das Frame-Fenster die Frage teilweise wieder verdeckt. Das liegt daran, dass die Fragen und Antwort-Buttons kurz ausgeblendet werden (so dass man nicht aus versehen doppelt klickt). Damit reduziert sich auch die Frame-Höhe. Im Moment (Juli/2021) wird alle 250ms die Höhe geprüft. Der Bildlauf liegt bei 1,5 Sekunden. Mit dieser Einstellung ist meiner Meinung ein guter Kompromiss gefunden.

Erweiterung ⇨ Nur eine bestimmte Anzahl Ergebnisse (Parteien) am Anfang anzeigen

Funktion

Einstellungen

Datei öffnen (Link auf externen Github-Server)

1. Die Anzahl der Ergebnisse in der Variable intPartiesShowAtEnd angeben
   In diesem Beispiel werden am Ende zuerst drei Ergebnisse angezeigt. Beim Klick auf den Mehr-Knopf werden wieder drei Ergebnisse nachgeladen.
   var intPartiesShowAtEnd = 3;
2. Einen Text für die Buttons vergeben
   var TEXT_RESULTS_BUTTON_SHOW_MORE = "Weitere Ergebnisse zeigen"
var TEXT_RESULTS_BUTTON_SHOW_LESS = "Weniger Ergebnisse zeigen"
3. Die Erweiterung in der DEFINITION.JS aktivieren.
   var addons = ["extras/addon_limit_results.js"]
4. Fertig.

Einschränkungen

• Die Erweiterung berechnet die jeweiligen Werte anhand des vorherigen Werts. Damit kann sich die Ergebnisanzeige beim "Mehr" und "Weniger"-Klicken irgendwann ändern. z.B. 12 Ergebnisse insgesamt.
  Start: 5 + 5 = 10 + 5 = 12 (max.)
  12 (max.) - 5 = 7 - 5 = 02 - 5 = 01 (min.)
  01 (min.) + 5 = 6 + 5 = 11 + 5 = 12 (max.)

Erweiterung ⇨ Lieblingspartei am Anfang abfragen

Funktion

Einstellungen

Datei öffnen (Link auf externen Github-Server)

1. Die Willkommensnachricht bzw. Erklärung definieren
   var TEXT_ADDON_FAVORITE_PARTY_WELCOME_MESSAGE = "Bevor wir anfangen, eine kurze Frage:
Wenn morgen Wahl wäre, wen würdest du normalerweise wählen?"
2. Einen Text für den Button, wenn man die Frage überspringt
   var TEXT_ADDON_FAVORITE_PARTY_SKIP_DECISION = "Überspringen / Keine Antwort"
3. Farbe und Transparenz (auf einer Skala von 0.0 - 1.0 = 0 - 100%) des Ergebnisses
   var STYLE_ADDON_FAVORITE_PARTY_COLOR = "#fff"
var STYLE_ADDON_FAVORITE_PARTY_OPACITY = "0.8"
4. Die Erweiterung in der DEFINITION.JS aktivieren.
   var addons = ["extras/addon_favorite_party.js"]
5. Fertig.

Einschränkungen

• keine

Noch Fragen offen?