Arendajale

Samatekst - samatekstide (palindroomide) veebiredaktor ja pilves hoitav tekstikogu

Koodirepo - Funktsioonikataloog - Koodimeetrikad - Näppimisest, konfimisest ja tööriistade isetegemisest

Tehnoloogiad
Funktsionaalsed omadused
Teksti esitusvormingud
Tekstikogu
Logimine
Koodi põhimõtted
Testimine
Redaktori tööpõhimõte
Töövahendid
Lahendused
Visuaalne hierarhia
Autentimine ja pääsuhaldus
Meetrikad

Tehnoloogiad

Klient:
- ~~`Bootstrap4`~~
  (UI raamistik)
  - GitHub (koodihoidla)
  - Visual Studio Code (koodiredaktor)
Server:
- Google Apps
  - Google Apps Script (programmeerimiskeel)
  - Google Apps Script Editor (koodiredaktor)
Andmebaas:
- Google Sheet
Autentimine:
- Google Sign-In (OpenID Connect standardile vastav)
Dokumentatsioon:
- GitHub Pages (github.io, Jekyll)

Arhitektuurijoonis

Funktsionaalsed omadused

1 Samatekstide mõiste ja terminite tutvustus, koos näidetega (“Mis on samatekst?”)
2 Samatekstiredaktor
- 2.1 Samateksti sisestamisel programm hoiab teksti kogu aeg samatekstina
  - 2.1.1 Lisab või kustutab ise peegeltähe
- 2.2 Tekst võib sisaldada kirjavahemärke.
- 2.3 Teksti saab kustutada (Backspace ja Delete ühe tärgi kaupa).
- 2.4 Tekstis saab liikuda ja kursorit seada.
- 2.5 Tekstisisestusalasse saab teksti asetada (Ctrl+V).
  - 2.5.2 Teksti asetamisel kontrollib teksti vastavust samateksti reeglitele
- 2.6 Kesktäht (-tähed) kuvatakse rõhutatult.
- 2.7 Samateksti pooled saab vahetada.
- 2.8 Saab alustada uut samateksti.
- 2.9 Teksti saab salvestada pilvemällu.
  - 2.9.1 Salvestamisel saab märkida, kas tekst on kavand.
3 Samatekstilisuse kontroll
- 3.1 Eraldi saab kontrollida, kas tekst on samatekst
4 Tekstikogu
- 4.1 Saab lehitseda salvestatud tekste.
- 4.2 Salvestatud tekste saab otsida.
  - 4.2.1 Tähekombinatsiooni sisaldumise järgi
  - 4.2.2 Kesktähe kaudu.
5 Infopaanil pakutakse väikest abiteksti
6 Sõnastik ligi 47 000 sõnaga
- 6.1 Sõnastikust saab otsida
  - 6.1.1 Otsistringi ja *-i abil
  - 6.1.2 Regex-ga
  - 6.1.3 Võimalus kuvada otsitulemused pöördkujul
- 6.2 Otsingute ajalugu
6a Kohanimekogu üle 74 000 kohanimega
7 Seotud tekstide kuvamine
- 7.1 Samaväärsed tekstid (=)
- 7.2 Eellased (>) ja järglased (<)
- 7.3 Ühise alamsõne järgi (pikkusega vähemalt 4)
8 Teksti samatekstilisuse kontroll
- 8.1 Saab asetada või sisestada teksti ja kontrollida selle vastavust samateksti reeglitele
9 Valik samatekste
10 Google kontoga sisselogimine
- salvestamisõigus ainult autenditud kasutajal
- salvestatakse autori nimi ja e-posti aadress

Teksti esitusvormingud

Ülevaade
- Suur osa funktsionaalsusest on seotud samatekstide teisendamisega ühest esitusest (kujust) teise. Samatekst võib olla mitmes erinevas esituses:
  1. kasutajale nähtav esitus tekstisisestusalal (#Tekst)
  2. siseesitus
  3. HTML-esitus kuvamiseks tekstisisestusalal
  4. pilveesitus (salvestatud kuju)
  5. esitus tekstikogus ja arhiivkogus
  6. HTML-esitus kuvamiseks tekstikogus
  7. esitus sirvija konsoolil (logimine silumise eesmärgil).
Tähtsamad teisendused:

              Esitus teksti-     (1)
              sisestusalal   +------->  Siseesitus
                  ^                         +
                  |                     +   |
                  | (2)                 |   |
                  +           (2)       |   | (3)
                  HTML   <---------------+   |
                                            |
                                            v
                  HTML    <------------+ Pilveesitus
                  +           (4)
                  |
                  | (4)
                  v
              Tekstikogu
              esitus

(1) kasutaja sisestab tekstisisestusalal; klahvivajutused püütakse sündmuste keydown ja keypress abil kinni, filtreeritakse (lubatud tähed ja kirjavahemärgid), tehakse kindlaks kursori (ingl caret) asukoht. Sisestatavat teksti hoitakse sisekujul.
(2) Tähe lisamisel lisab programm automaatselt peegeltähe ja uuendab tekstisisestusalal olevat teksti.
(3) Kasutaja saab teksti salvestada. Programm teisendab salvestatava teksti pilveesitusse.
(4) Salvestatud tekste saab sirvida ja otsida. Salvestatud tekstid esitatakse kuval HTML abil.

Siseesitus
Sisemiselt hoitakse kesktähte alati kahekordselt. Teavet kesktähe kordsuse kohta hoiab globaalne muutuja kuvaKeskelementYhekordselt.
Samuti hoitakse siseesituses kursori positsiooni (sümbol |).
Reavahetus hoitakse sümboliga /.
Näiteks: IT//|Säh, hästi!
Samma|s tähendab Samas, kui kuvaKeskelementYhekordselt = true
Esitus tekstisisestusalal
Nähtav:
IT//|Säh, hästi!
| - tühitekst
Kesktäht (või -tähed) esitatakse rõhutatult.
Reavahetus esitatakse sümboliga /.
Kuvatakse HTML-esituse abil.
- Kuval esitatav tekst on jagatud viie span-elemendi vahel (võivad olla tühjad): A, K1, Kt, K2, B.
- Tühiteksti puhul pannakse esimesse span-elementi (A) 0-pikkusega tühik (), seda selleks, et tekstisisestusala div-element ei kollapseeruks.
Näited:
IT//Säh, hästi!
 - tühiteksti esitamine 0-pikkusega tühiku abil
Esitus tekstikogus
Näide:

    IT

    Säh, hästi!

Kuval esitatakse kesktäht (või -tähed) rõhutatult.
Reavahetus teostatakse,  -elemendi abil.
Kuvatakse HTML-esituse abil. Näide:
IT Säh, hästi!
Esitus pilvemälus
Ühekordne kesktäht esitatakse ühekordselt
Reavahetus hoitakse sümboliga /. Näide: IT//Säh, hästi!

Tekstikogu

Salvestamine
- Toimub väikeses dialoogis, kus kontrollitakse, kas ikka tahetakse salvestada ja soovi korral määratakse, kas tekst on kavand. Salvestusdialoog on modaalse olemusega.
- Salvestatakse Google Sheet-le, kasutades Google Sheets REST API-t.
- Pilve salvestatakse puhta tekstina (rõhutusteta, kesktäht ühekordselt, kui nii on määratud).
- Kontrollitakse, kas sama tekst on juba olemas.
Filtri- e otsidialoog
- Võib olla avatud samaaegselt teksti sisestuse alaga, kuna tekstisisestussündmusi püütakse tekstisisestusalas.
- Filtreerimisel ei jagata väljundit lehekülgedeks.
Turvalisus
- Injection-ründe kaitse. Google Sheet-iga seotud serverirakenduses (Google Apps Script-is) kontrollitakse üle, et tekst ei sisalda HTML-i.
- samuti kontrollitakse API poolel, et HTTP POST-päringuga salvestamiseks saadetud tekst on tõesti samatekst. TO DO

Logimine

Logitakse nii kliendi kui ka serveri poolel
Kliendi poolel logitakse:
- tekstiredigeerimist (elemendis Tekst)
  - nii kasutaja klahvivajutusi
  - kui ka programmi poolt väljastatud teksti
- filtri seadmist (otsistring + piiravad tingimused)
- Logitasemed:
  - 0 - ei logita midagi
  - 1 - logitakse tekstisisestus ja -väljastus
  - 2 - lisaks eelmisele logitakse keydown ja keypress sündmused jm
- Logimise sisselülitamine:
  - logimistase = 2; sirvija konsoolil
  - vaikimisi on logimistase 1
- Logikirje algab funktsiooni nimega
Serveri poolel logitakse:
- ajatempel, teksti saatnud isiku nimi ja eposti aadress, identiteeditõendi kontrolli tulemus (aud OK, aud NOT OK) ja saadetud tekst

Koodi põhimõtted

Mittetriviaalne funktsionaalsus omaette nimega funktsioonidega, mis seotud kasutajaliidese sündmustega eraldi.

Testimine

Funktsioonitestimise automatiseerimiseks on leht SamasTest.html; testid pannakse kirja failis SamasTest.js.

Redaktori tööpõhimõte

Kasutaja sisendi kinnipüüdmine
Kasutaja tegevused tekstisisestusväljas (elemendis Tekst) püütakse kinni sündmuste keydown, keypress ja paste jälgimisega ja töötlemisega.

                              #Tekst
                        (tekstisisestusväli)  
                                  ↓
          keydown             keypress             paste
                        (sündmusekäsitlejad) 
              ↓                    ↓                
    tootleEriklahv(keyCode)  lisaTahtVoiPunktuatsioon(charCode)
              ↓                    ↓                
        tootleBackspace()
        tootleDelete()
        kuvaKesktahtYhekordselt = true
        kuvaKesktahtYhekordselt = false
        suurtaheks()
        vaiketaheks()
              ↓                    ↓                
        kuvaTekst()

Sündmuse keydown käsitleja püüab kinni eriklahvivajutused, mida redaktoris tavapärasest eriliselt töödeldakse: 8 (Backspace), 46 (Delete), 33 (PgUp), 34 (PgDn), 38 (Up), 40 (Down). Nende vaikimisi toiming tühistatakse ja vajutusi käsitletakse tavapärasest erinevalt. Suunab eriklahvivajutuste töötlemiseks funktsiooni tootleEriklahv.
Sündmuse keypress käsitleja suunab kasutaja sisestatud tärgi töötlemiseks funktsiooni lisaTahtVoiPunktuatsioon.
Sündmuse paste käsitleja puhastab asetatava teksti kõrvalistest tärkidest ja kontrollib, kas asetamise tulemusena tekkinud tekst on samatekst. Kui ei ole, siis annab veateate ja sisendit ei aktsepteeri.
Kasutaja sisendi töötlemiseks on vaja tuvastada ka kursori (caret) positsioon. Seda teeb funktsioon tuvastaCaretJaSeaSisekursor.
Teksti kuvamine
HTML kujule teisendavad markeeriTekst ja markeeriTekstikoguTekst.
Tekstisisestusala caret positsiooni seab funktsioon seaCaret.
Kuvatakse ka tähtede arv tekstis.

Töövahendid

Javascripti parimad praktikad: https://github.com/wearehive/project-guidelines
Javascripti süntaksikontrollija: http://esprima.org/demo/validate.html
HTML validaator: https://validator.w3.org/nu/#file (Firefox-i kontekstimenüüst )

Lahendused

Teave
Kõigi HTML veebi-API-de nimekiri: https://developer.mozilla.org/en-US/docs/Web/
HTML sündmuste kohta: https://www.w3schools.com/tags/ref_eventattributes.asp
JQuery sündmusekäsitlejate seadmine: https://www.w3schools.com/jquery/jquery_events.asp
DOM Node objekt: https://www.w3schools.com/xml/dom_node.asp
jQuery-ga tippudele ligipääsemine: https://api.jquery.com/get/
Sündmused
Tähesisestuse töötlemiseks on keypress parem kui keydown, sest keypress näitab, milline tärk sisestati (eristab suur- ja väiketähti). keydown näitab millist klahvi vajutati.
Väga hea seletus: http://stackoverflow.com/questions/1367700/whats-the-difference-between-keydown-and-keypress-in-net
Nuppude töötlus
Kasutajaliidese alade peitmine klassiga peidetud (style='display: none;'); parem kui JQuery show, hide ja toggle.
Nuppude mitteaktiivseks tegemine klassiga disabled.
Miks ei kasuta input elementi
Input elemendis vt: setSelectionRange() HTML veebi-APIs HTMLInputElement - https://developer.mozilla.org/en-US/docs/Web/API/HTMLInputElement/setSelectionRange
JQuery-s ei ole oninput võimalust, vt http://stackoverflow.com/questions/11189136/fire-oninput-event-with-jquery
Vt ka http://stackoverflow.com/questions/9906885/detect-backspace-and-del-on-input-event
Mitmesugust
Arvesta ka Mac-i metakey-ga: http://stackoverflow.com/questions/2903991/how-to-detect-ctrlv-ctrlc-using-javascript
break lause ei tööta Javascript forEach-ga.
Tärgi asetamine stringi - vt http://stackoverflow.com/questions/4313841/javascript-how-can-i-insert-a-string-at-a-specific-index
Ctrl+V (Paste) käsitlemine - Vt https://www.w3.org/TR/clipboard-apis/ - Vt onpaste sündmus https://www.w3schools.com/jsref/event_onpaste.asp - Kasutatud on: http://stackoverflow.com/questions/6902455/how-do-i-capture-the-input-value-on-a-paste-event
Caret (kursori) paigutamine contenteditable div elemendis
Range - The Range interface represents a fragment of a document that can contain nodes and parts of text nodes. Vt https://developer.mozilla.org/en-US/docs/Web/API/Range
Vt: http://stackoverflow.com/questions/6249095/how-to-set-caretcursor-position-in-contenteditable-element-div
document.createRange() vt: https://developer.mozilla.org/en-US/docs/Web/API/Document/createRange
Range objekt vt: https://developer.mozilla.org/en-US/docs/Web/API/Range
Selection objekt vt: https://developer.mozilla.org/en-US/docs/Web/API/Selection
Caret paigutamine tühja teksti - kasuta 0-pikkusega tühikut, vt: http://stackoverflow.com/questions/4063144/setting-the-caret-position-to-an-empty-node-inside-a-contenteditable-element

Visuaalne hierarhia

Visuaalne hierarhia (joonis)

Autentimine ja pääsuhaldus

Google Sign-In for Websites: https://developers.google.com/identity/sign-in/web/
vt lähemalt: Pääsuhaldus.

Meetrikad

Koodimeetrikad on esitatud mõõdikulauana: Meetrikad.html.
Meetrikaid hoitakse Google Sheet-l. Google Sheet pakub oma andmeid REST API kaudu, JSON-vormingus.