Changes between Initial Version and Version 1 of SynControlCenter

Timestamp:

08/08/08 00:10:41 (16 years ago)

Author:

trac

Comment:

--

SynControlCenter

@@ +1 @@
+= 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.
+
+== 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 www.syn3.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:
+ * list''bla''.php  Een lijst van items waar de user uit kan kiezen door ergens op te klikken.
+ * edit''bla''.php  Als de user ergens op klikt kom hij in de edit-file.
+ * show''bla''.php  Soms is het nodig om 1 ding te tonen in plaats van een lijst. Dan begint hij met show.
+ * add''bla''.php  Voor het toevoegen van nieuwe items aan de lijst. Vaak gebruik je hiervoor edit''bla''.php zonder een get-parameter.
+ * del''bla''.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 '''form.php'''
+ * 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.
+
+Controleren of de user een bepaalde licentie optie heeft: ModuleMatch() en ModuleNeeded().
+
+== 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 www.syn3.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'.
+