| Version 2 (modified by , 16 years ago) (diff) |
|---|
Opbouw SCC
De sourcecode van de SCC vind je hier: source:trunk/npl/syn3/webint/src
Je hebt speciale rechten nodig in svn om hier bij te kunnen.
Hieronder volgt een korte opsomming van de werking van de SCC, maar voor voorbeelden moet je in de destbetreffende files kijken.
Modules
Iedere Syn-3 module bevind zich in een apparte directory. Doordat er files met een bepaalde naam in deze directory staan komt de module in 'het systeem'.
Op het moment dat je inlogt word het menu opgebouwd door alle menuman.php files te includen. Deze file bevat de menukeuzes van de destbetreffende module. Sommige menukeuzes zijn afhankelijk van een bepaalde optie in je licentie. Deze optie staat er dan ook achter.
Example module
Ga naar https://server:10000/examplemodule/listthings.php om de voorbeeld module te zien.
Ook de drbd module is een goed voorbeeld: https://server:10000/drbd/edit.php
Deze module is gebaseerd op het nieuwe form2.php (ipv form.php). Deze module is veel overzichtelijker en makkelijker te onderhouden dan modules die volgens het oude systeem zijn gemaakt. Gebruik deze vanaf nu als leidraad voor nieuwe modules.
form2.php heeft als nieuwe features:
- alle input controle zit in de backend model.
- aanroepen van functies gaat via duidelijke hash arrays
- geposte form data zit nu niet meer in vage $new_... globals.
- phpcode van een form is nu makkelijk leesbaar
- phpcode is nu makkelijk copy/paste baar. zonder in documentatie hoeven te kijken.
Wizard
De wizard kijkt bij het inloggen, updaten en veranderen van de licentie automatich of er nog dingen 'gewizard' moeten worden. Dit doet de wizard door alle wizardman.php files te includen.
Multilanguage
Meertalige ondersteuning is zeer eenvoudig: In plaats van een stuk tekst ergens neer te zetten, roep je een functie aan die je een logische label geeft. Deze functies worden vervolgens door de handige scripts gegenereerd. (zie hieronder) Later als je klaar bent met coden of als je zin hebt kun je met de Language editor op translate.syn-3.nl de taal labels invullen.
Een taal label heeft het volgende formaat om herkent te worden door het systeem:
echo _HelloWorld($parameter1,$parameter2...);
De parameters zijn optioneel, en komen terug in de langauge editor als $a en $b enz.
Met de language editor kun je dan de juiste tekst voor de HelloWorld? label in iedere taal defineren. Er zijn ook mensen die de zooi voor ons van het nederlands naar engels en duits vertalen, dus dit hoef je zelfs niet eens verplicht te doen!
Scheiding van layout en functionaliteit
Om een scheiding aan te brengen tussen model/view/controller hebben we de volgende afspraak: De logica (model) komt in een file model.php in de module directory. Let op: Veel modules hebben hun model nog in een phpfile met een andere naam zitten, maar doen we vanaf nu niet meer!
Hierin maak je functies als volgt:
/** Korte omschrijving van de functie
*
* Detail omschrijving...blabla...
* @param $in[parameter1] Omschrijving van parameter1
* @param $in[parameter2] Omschrijving van parameter2
*/
function modulenaam_FunctieNaam($in)
{
...fix die shit...
return ($ret)
}
Hierbij is $in een hasharray met de benodigde parameters. Dit doen we om de sourcecode leesbaar te houden.
Het commentaar is in dit formaat, zodat we automatisch API documentatie kunnen genereren.
De frontend (controller/view) zet je in logische verschillende php files. De indeling hiervan kun je wederom halen uit bestaande voorbeelden. TODO: Welke is een GOED voorbeeld?
De naamgeving is ongeveer als volgt:
- listbla.php Een lijst van items waar de user uit kan kiezen door ergens op te klikken.
- editbla.php Als de user ergens op klikt kom hij in de edit-file.
- showbla.php Soms is het nodig om 1 ding te tonen in plaats van een lijst. Dan begint hij met show.
- addbla.php Voor het toevoegen van nieuwe items aan de lijst. Vaak gebruik je hiervoor editbla.php zonder een get-parameter.
- delbla.php Pagina om verwijderen te bevestigen indien nodig.
- Probeer voor de rest zelf logische namen te verzinnen. Let erop dat het overeenkomt en past bij de bestaande naamgeving. Dus niet ineens hoofdletters of streepjes gebruiken.
API documentatie
Als je de functies op de juiste manier documenteert zullen deze uiteindelijk in de api documentatie komen.
Het basis framework is reeds gedocumenteert. Die hier: source:trunk/npl/syn3/webint/docs . Deze kun je openen in je browser als je de SVN tree hebt.
Hierin vind je documentatie voor:
- Globale include file met handige functies: common.php Deze altijd includen!
- Error check functies om data te checken op input geldigheid error.php
- Form afhandeling form2.php (form.php niet meer gebruiken voor nieuwe modules, is volgens het oude systeem)
- File afhandeling, lezen, schrijven, bewerken van files file.php
- Process beheer, starten stoppen van services. proc.php
- Logging van gebreurtenissen en visuele terugkopelling aan de user: log.php
- Monitoren van de status van een bepaald iets (deze mailed ook): ../monitoring/state.php
- Controleren van licentie opties reg.php
- Functies aanroepen die op shop.syn-3.nl draaien: rpcclient.php
Het is essentieel dat je deze functies zoveel mogelijk gebruikt! Het is niet toegestaan om zelf textfiles te openen of commandos uit te voeren met normale php-functies zoals fopen() of system()! Ook emails sturen is uit den boze omdat we hier het monitoring en logging systeem voor hebben.
Om de user te vertellen dat iets 'gelukt' of 'gebeurd' is nadat men op Opslaan klikt gebruik je LogInfo?() of LogWarn?(). Als iets misgaat gebruik je LogError?().
Dingen executen die niet mogen mislukken doe je met SafeExec?(). Uitgebreidere opties om te executen heb je met Cmd().
Opbouw van formulieren etc. kun je halen uit de reeds bestaande modules. (examplemodule)
Controleren of de user een bepaalde licentie optie heeft: ModuleMatch?() en ModuleNeeded?().
Lezen schrijven van php arrays naar human readable config files: FileExport/FileImport?.
Lezen schrijven van bash shell settings files: FileReadSetting?(s)/FileWriteSetting?(s)
Lezen schrijven van plain textfiles: FileRead?(raw)/FileWrite?(raw)
Bepaalde regels vervangen in een textfile: FileReplaceLine?
GET en POST
Het uitlezen van GET en POST variabellen moet altijd via $_REQUEST gebeuren.
Verder is er een duidelijk onderscheid wanneer je GET of POST moet gebruiken.
- GET: Dit doe je om een bepaalde pagina op te vragen, bijvoorbeeld: useradmin/edituser.php?name=geert
- POST: Dit doe je om data op de server op te slaan. Bijvoorbeeld als men een user gewijzigd heeft en op Opslaan drukt.
Soms word een get echter wel gebruikt om dingen te verwijderen via een Icoontje. Bijvoorbeeld een prullebak je die linkt naar useradmin/edituser.php?name=test&del=1. Hier zijn overigens ook speciale functie voor. LinkIcon_Del() in dit geval.
Coding standaard
De volgende regels gelden (deze is nog niet compleet!):
- De php files moeten ten alle tijde netjes en overzichtelijk zijn.
- Alle functies documenteren
- Constantes: $HOOFDLETTERS
- Functie namen: FunctieNaam?()
- Model functie: module_FunctieNaam()
- Variabellen: foreach ($users as $user). Gebruik dus een s als het een array is.
- De gegenereerde HTML code moet geldig zijn maar niet netjes! Het is veel belangrijker dat htmlcode op een nette manier in je php-file staat, met eventueel commentaar. Of je hiervoor echo's of ?> of tabs en spaties gebruikt maakt niet uit, als het maar netjes is. Dat de browser een slordige bende krijgt boeit niemand! (zolang het maar geldige html is). Als ik iemand tijd zie besteden aan het genereren van 'nette' html code gaat hij aan de galg!
- Een model-functie die tekst echo't moet beginnen met Print. dus modulenaam_PrintBla().
Handige scripts
Genereren language labels
Het genereren van de langaguage labels gaat als volgt:
psy /home/psy/syn3/npl/syn3/webint # php updatelang.php _voorbeeldlabel1 in examplemodule/selectmode.php is NEW Adding _VoorbeeldLabel1 to central database... Downloading and executing updated language file for examplemodule: Generating examplemodule/lang_nlD.php Generating examplemodule/lang_nl.php Generating examplemodule/lang_enD.php Generating examplemodule/lang_en.php Generating examplemodule/lang_deD.php Generating examplemodule/lang_de.php Generating examplemodule/lang_plD.php Generating examplemodule/lang_pl.php Generating examplemodule/lang_ptD.php Generating examplemodule/lang_pt.php
Hierna is alles 'gefixed'.
Let op: Je moet vanaf kantoor.datux.nl komen. Het toevoegen van labels kan namelijk zonder authenticatie :)
Nu kun je de labels invullen op translate.syn-3.nl met de language editor. Hiervoor heb een Mambo account en rechten in de database nodig, anders komen je wijzigingen in de review-queue en worden ze nog niet actief.
Mocht je labels online gewijzigd hebben of wil je de nieuwste vertalingen:
psy /home/psy/syn3/npl/syn3/webint # php updatelang.php all Downloading and executing updated language file for .: Generating ./lang_nlD.php ...enz...enz...
Hierna zijn alle taallabels van alle modules bijgewerkt. Met svn status zie je hoeveel er veranderd is. Deze zooi kun je dan weer committen.
Uploaden naar testserver
Om je wijzigingen snel en handig uit te testen gebruik je upload.sh. Dit script voert automatisch de updatelang.php uit en upload daarna de files naar de server. Het script ziet automatisch wanneer je wijzigingen gemaakt hebt:
psy /home/psy/syn3/npl/syn3/webint # ./upload.sh 192.168.0.150 Checking ssh key on 192.168.0.150...@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@ @ WARNING: REMOTE HOST IDENTIFICATION HAS CHANGED! @ @@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@ IT IS POSSIBLE THAT SOMEONE IS DOING SOMETHING NASTY! Someone could be eavesdropping on you right now (man-in-the-middle attack)! It is also possible that the RSA host key has just been changed. The fingerprint for the RSA key sent by the remote host is 09:09:34:00:b8:b5:84:f4:60:9a:56:8f:56:bc:94:15. Please contact your system administrator. Add correct host key in /root/.ssh/known_hosts to get rid of this message. Offending key in /root/.ssh/known_hosts:4 Password authentication is disabled to avoid man-in-the-middle attacks. Keyboard-interactive authentication is disabled to avoid man-in-the-middle attacks. Permission denied (publickey,password,keyboard-interactive). SSHKEYFIX: Removing hostkey of 192.168.0.150...OK Warning: Permanently added '192.168.0.150' (RSA) to the list of known hosts. root@192.168.0.150's password: Installing public key...OK Disabling _voorbeeldlabel in central database. building file list ... done sent 18924 bytes received 20 bytes 37888.00 bytes/sec total size is 3349858 speedup is 176.83 ...systeem wacht op wijzigingen
Nadat je op 'Save' drukt in je editor onderneemt het script gelijk actie:
voorbeeldlabel5 in examplemodule/selectmode.php is NEW Adding _VoorbeeldLabel5 to central database... Downloading and executing updated language file for examplemodule: Generating examplemodule/lang_nlD.php Generating examplemodule/lang_nl.php Generating examplemodule/lang_enD.php Generating examplemodule/lang_en.php Generating examplemodule/lang_deD.php Generating examplemodule/lang_de.php Generating examplemodule/lang_plD.php Generating examplemodule/lang_pl.php Generating examplemodule/lang_ptD.php Generating examplemodule/lang_pt.php Disabling _voorbeeldlabel in central database. Disabling _voorbeeldlabel4 in central database. building file list ... done examplemodule/lang_de.php examplemodule/lang_deD.php examplemodule/lang_en.php examplemodule/lang_enD.php examplemodule/lang_nl.php examplemodule/lang_nlD.php examplemodule/lang_pl.php examplemodule/lang_plD.php examplemodule/lang_pt.php examplemodule/lang_ptD.php examplemodule/selectmode.php sent 26566 bytes received 364 bytes 53860.00 bytes/sec total size is 3349888 speedup is 124.39 Disabling _voorbeeldlabel4 in central database. building file list ... done sent 18928 bytes received 20 bytes 37896.00 bytes/sec total size is 3349888 speedup is 176.79 ....script wacht weer
Installeren op echte server
Om je wijzigingen snel bij een klant of op een live server te installeren moet je ze eerst encrypten en packagen. (zodat men de sourcecode niet ziet)
Dit kan volgens het systeem beschreven bij SynPackaging. Hier een voorbeeld:
psy /home/psy/syn3/npl # ./remoteinstall webint 192.168.0.150 rebuild * Build check: |REBUILD REQUIRED: ./src/examplemodule/selectmode.php has changed! |REBUILDING /home/psy/syn3/npl/syn3/webint/webint.SlackBuild: (....build output...) * install: Checking ssh key on 192.168.0.150...OK 192.168.0.150: Uploading and installing 192.168.0.150: Running installpkg /tmp/webint-4.0-noarch-3593mod.tgz 192.168.0.150: Installing package webint-4.0-noarch-3593mod... 192.168.0.150: PACKAGE DESCRIPTION: 192.168.0.150: Executing install script for webint-4.0-noarch-3593mod... 192.168.0.150: 192.168.0.150: Running etc-update... 192.168.0.150: Running ldconfig...DONE 192.168.0.150: Syncing changes to disk...DONE 192.168.0.150: Postinstall check... 192.168.0.150: >> Bezig met configureren van post.webint 192.168.0.150: OK 192.168.0.150: Installed /tmp/webint-4.0-noarch-3593mod.tgz. 192.168.0.150: Install on 192.168.0.150 OK All installs done psy /home/psy/syn3/npl #
Dit zijn dus DE 2 manieren om je SCC wijzigingen op een server te trappen.
Commit regels
Wanneer mag je je wijzigingen aan de SCC committen in de SVN tree?
Zorg er voor dat je je commits opdeelt in logische stukken: Dus bugfixes los van nieuwe features en uitbreidingen. Als je 2 modules wijzigd, commit dan ook PER module.
De volgende regels gelden, voordat je mag comitten:
- Er mag niks 'stuk' gaan aan het reeds bestaande systeem.
- De eindgebruiker mag niet bij een module kunnen komen die nog niet af is: Meestal hoort bij een nieuwe module een extra licentie optie. Hier kun je dan op controleren in de menuman.php of andere files,zodat mensen zonder deze optie jou module of uitbreiding niet zien.
- Uitbreidingen moeten backwards compatible zijn met het oude systeem.
- De code moet reeds voldoen aan alle regels op deze pagina. Daarom is het handig om je gelijk vanaf het begin hieraan te houden en je niet voor te nemen achteraf nog alles aan te passen of te 'fixen'.
