Nederlands Installatiehandleiding Pro Vocem DTS / Framework Neem de volgende stappen om het framework klaar te maken om er een website mee te gaan opzetten: •
Maak online op de locatie / host waar de website moet gaan draaien een nieuwe MySQL database aan met de naam ‘websitetree’. De naam moet exact kloppen, dus geen hoofdletters. Als u graag een andere naam wilt gebruiken, omdat u bijvoorbeeld meerdere instanties van het framework op hetzelfde domein wilt toepassen, geef hier dan rustig een andere naam op en verander in de klasse ‘class.dbconnect.php’ het attribuut $dbName naar deze nieuwe naam.
•
Maak een hoofdgebruiker aan voor deze database en stel daartoe een gebruikersnaam en wachtwoord naar keuze in.
•
Open PHPMyAdmin voor de nieuwe database en klik op ‘import’ / ‘importeer’. Blader naar het bestand ‘websitetree.sql’ en klik onderaan het formulier op ‘start’. De database wordt gevuld met enkele tabellen met daarin enige initialiserende records, die noodzakelijk zijn om de website aan de gang te krijgen.
•
Open het bestand ‘class.dbconnect.php’ uit de map ‘lib’ en wijzig bovenin deze class de attributen (klassevariabelen) $dbUser en $dbPass door de gebruikersnaam en het wachtwoord in te vullen die u heeft toegekend aan de hoofdgebruiker van de database, toen u deze aanmaakte. Ook kunt u hier bij het attribuut $bugMailAddress een mailadres opgeven waar naartoe foutmeldingen worden gemaild, als deze zich bij essentiële databaseoperaties voordoen. Opmerking: het mailen van fouten werkt alleen als daartoe in de op de server aanwezige PHP/MySQL installatie de juiste afhankelijkheden zijn geïnstalleerd. Er dient op de server een mailer daemon actief te zijn, die zelfstandig berichten kan verzenden. De handleiding van PHP zegt hierover het volgende: Requirements: For the Mail functions to be available, PHP must have access to the sendmail binary on your system during compile time. If you use another mail program, such as qmail or postfix, be sure to use the appropriate sendmail wrappers that come with them. PHP will first look for sendmail in your PATH, and then in the following: /usr/bin:/usr/sbin:/usr/etc:/etc:/usr/ucblib:/usr/lib. It's highly recommended to have sendmail available from your PATH. Also, the user that compiled PHP must have permission to access the sendmail binary. In de meeste gevallen regelt de webhost dit volledig. Sla het bestand op en sluit het.
•
Als u het standaardmailadres heeft gewijzigd, verdient het de voorkeur deze verandering ook door te voeren op het attribuut $_bugMailAddress uit de klasse ‘class.dboperation.php’.
•
Het beheergedeelte van het framework maakt gebruik van cookies (de eigenlijke website die ermee wordt gemaakt niet, althans, in zoverre u als ontwikkelaar hierin door het toevoegen van content geen verandering brengt). Daartoe kan e.e.a. ingesteld worden in de klasse
‘class.login.php’. De attributen $DOMAIN en $COOKIE_PATH regelen respectievelijk het (sub)domein waarop de cookies actief mogen zijn en eventueel een pad-beperking binnen dat (sub)domein op de webserver. In wezen zijn dit veiligheidsinstellingen. Hoe specifieker e.e.a. wordt opgegeven, hoe veiliger de uiteindelijke website wordt. Standaard zijn de waarden zo breed mogelijk ingesteld, door ze leeg te laten (‘’). Hierdoor zijn de cookies standaard beschikbaar binnen alle mappen vanaf alle subdomeinen van het hoofddomein. Naar eigen inzicht kunt u deze waarden beperken. •
Open het bestand ‘footer.inc’ en wijzig (geldige HTML!) eventueel de footer die u graag op uw webpagina’s wilt weergeven.
•
Kopieer alle mappen en losse bestanden van het framework naar de gewenste ‘httpdocs’map (soms ‘htdocs’) op de server via uw favoriete FTP-client.
•
Vanaf dit moment kunt u uw website al benaderen. Dit komt doordat er bij het framework als voorbeeld een html-template en css-bestand wordt geleverd. Vraag de map ‘httpdocs ‘ op via uw browser. U krijgt iets soortgelijks als hieronder getoond, te zien:
•
Door het bestand ‘template.html’ te wijzigen, kunt u de indeling van de pagina op geheel eigen wijze vorm geven. De diverse elementen die door het framework uit de database worden aangeleverd kunnen worden ingezet m.b.v. zogenaande ‘tags’. Deze tags hebben het volgende format: ‘{tagnaam}’. Welke tags beschikbaar zijn en wat ze allemaal doen, kunt u terugvinden in ‘available_tags.txt’. LET OP: deze tags kunt u ALLEEN in een template, zoals ‘template.html’ gebruiken.
•
Als u de lay-out op orde hebt, kunt u de opmaak gaan wijzigen. Hiertoe kunt u ofwel lokaal het bestand ‘default.css’ in de map ‘css’ wijzigen met uw favoriete CSS-editor, ofwel u kunt inloggen in het beheersysteem van het framework en de online CSS-editor (met syntax highlighting) gebruiken.
•
Als u wilt inloggen in het beheersysteem, heeft u een gebruikersnaam en wachtwoord nodig. Bij afname van het systeem bij Pro Vocem wordt in de database van tevoren in ieder geval één hoofdgebruiker aangemaakt. De bijbehorende inloggegevens vindt u in het bestand ‘admin_login.txt’. Let op dat u dit bestand niet per ongeluk op deze webserver zet!
•
Om in te loggen browst u naar de volgende locatie: http://[(sub)domein of httpdocsmap]/admin
•
Op deze pagina wordt u geconfronteerd met een inlogscherm. Hier kunt u de inloggegevens uit het tekstbestand invoeren en het beheersysteem betreden. Eenmaal succesvol ingelogd krijgt u iets soortgelijks als hieronder getoond, te zien:
•
Op de beheerpagina ‘contentboom’ kunt u de structuur van de website (de sitemap) wijzigen. De sitemap is binnen het framework altijd op gezet als een boomstructuur. Bovenin de pagina vindt u het editor-gedeelte. Hier kunt u de content van de momenteel geselecteerde pagina wijzigen. U kunt in het editor-venster ofwel geldige HTML invoeren, ofwel geldige PHP code invoeren. Al naar gelang uw wensen kunt u de syntax highlighting aanpassen aan uw wensen, hoewel automatisch de juiste highligtingtaal wordt gekozen als een opgeslagen contentpagina eenmaal geladen wordt. De PHP code dient omgeven te worden door officiële tags. Op dit moment wordt ALLEEN het volgende format geaccepteerd:
Waarbij de ellips vervangen dient te worden door geldige PHP-statements. In scripts die op contentpagina’s worden geplaatst, kunt u uitgaan van een bestaande, open en werkende connectie met de database van het framework. Als u dus gebruik wilt maken van data uit deze database, dan kunt u direct beginnen met het schrijven van statements die queries opstellen en uitvoeren. Om content op het scherm te laten verschijnen, kunt u het beste gebruik maken van een outputbuffer en (een) echo() statement(s) [print-to-client]. Dit betekent ook dat u op één contentpagina HTML en PHP niet door elkaar dient te gebruiken. Als u dit toch nodig acht, maak er dan een volledige PHP-pagina van (met aan het begin en einde de genoemde PHP-tags) en output de nodige HTML via echo() statements (voor kleine hoeveelheden) of heredoc syntax (voor grotere lappen). •
Als u de boomstructuur zelf wilt aanpassen, kunt u in de sectie ‘sitemap’ terecht. U vindt hier de boomstructuur op het scherm weergegeven als een ingesprongen lijst. Klik op een link binnen de boom om de content van de betreffende pagina te wijzigen of om een opdracht uit te voeren. Een opdracht kan het aanmaken van een nieuwe link in de boom zijn (zowel interne links binnen de boom of links naar externe websites, waarvoor u de ‘X’ van eXtern kunt gebruiken). Links kunnen als siblings (dus op gelijke diepte met andere links) of als children (dus onder andere links) worden aangemaakt. LET OP: de hoofdlinks, die we roots noemen, daar ze in de root van de boom worden aangemaakt, maken tezamen het hoofdmenu voor de website dat op elke pagina terugkomt. De links in de laag eronder (alle kinderen van alle roots) worden per hoofdlink in een contextmenu weergegeven. LET OP: op de beheerpagina wordt door het algoritme, dat de boomstructuur opstelt (tekent) en naar de database schrijft, rekening gehouden met een boom van onbeperkte diepte. U kunt in principe dus telkens nieuwe kinderen van zojuist aangemaakte links maken. Echter, de weergave van de boomstructuur op de pagina ‘index.php’, heeft een maximale statische diepte van 3. Dat wil zeggen dat de ‘hoofdlinks’ (roots) kinderen en kleinkinderen kunnen hebben, maar daar houdt het momenteel op. Voor de meeste eenvoudige websites is dit uiteraard meer dan voldoende. Hoewel u in het beheersysteem gewoon achterkleinkinderen kunt aanmaken in de boomstructuur, kunt u deze vanuit de template NIET benaderen voor weergave op de eigenlijke webpagina.
•
Een geselecteerde link kunt u verwijderen uit de boom, zolang deze geen kinderen heeft. Als u dus een hoofdlink wilt verwijderen, die vijf kinderen heeft, die elk 3 kleinkinderen hebben, dan dient u dus 3 * 5 = 15 + de hoofdlink zelf = 16 links te verwijderen. Dit lijkt omslachtig, maar het alternatief is dat automatisch alle kinderen van een link worden verwijderd uit de database, inclusief content en bijbehorende afbeeldingen (zie hieronder), wat enigszins risicovol is. Eén verkeerde klik op de proverbiale knop zou dan 16 contentpagina’s vernietigen. Dat kan niet de bedoeling zijn. U dient als developer dus bewust elke pagina die u kwijt wilt manueel te verwijderen.
•
Een geselecteerde link kunt u met een stapgrootte van één per keer omhoog of omlaag verplaatsen in de boom (knoppen: Move Up / Move Down). Als u een hoofdlink met kinderen en kleinkinderen verplaatst, worden deze automatisch allemaal mee verplaatst.
•
De knop ‘Wijzig’ slaat de eventueel gewijzigde NAAM van de link op in de database. Het kan immers voorkomen dat u een link anders wilt noemen.
•
Bijzondere gevallen: > Links naar externe URL’s zijn in de boom ROOD gekleurd, en niet BLAUW (de kleur voor normale, interne links). Als u een link naar een externe URL opent voor mutatie, dan ziet u in het editorscherm alleen de URL staan, waarnaar de link verwijst. Hier kunt u de URL dan ook aanpassen. Zet hier echter verder geen andere informatie bij. > De HOME link is een speciaal en beschermd geval: De link kan niet omhoog of omlaag worden verplaatst, kan niet worden verwijderd en de naam ervan kan niet worden gewijzigd. Als u de naam toch wilt wijzigen, kunt u dit in de database direct aanpassen in de kolom ‘nodename’ van de tabel ‘treenodes’. De home-link heeft in die tabel altijd ID # 1. LET OP: het zelf wijzigen van de naam direct in de database is door de ontwikkelaar niet getest. Het kan zijn dat deze wijziging onverwachte gevolgen kent.
•
Per contentpagina kunt u een site header pic opgeven. Hiervoor kijkt u bij de sectie ‘Header image’, halverwege de pagina. Om een header aan deze pagina toe te voegen, dient u de exacte bestandsnaam (hoofdlettergevoelig) van het afbeeldingsbestand, inclusief extensie, maar exclusief volledig pad, in te geven en op te slaan. Vervolgens dient u de afbeelding in de map ‘pic’ te plaatsen.
•
Per contentpagina kunt u tot maximaal 6 in tags benaderbare afbeeldingen opgeven. Hiervoor kijkt u bij de sectie ‘Afbeeldingen’, onderaan de pagina. Uitleg over het toevoegen van afbeeldingen vindt u aldaar.
•
Onder het tabblad ‘nieuwsberichten’ kunt u nieuwsberichten voor uw website toevoegen, verwijderen en wijzigen. Denk om de volgende aandachtspunten: > Om op uw webpagina nieuwsberichten te kunnen weergeven, dient u een nieuwspagina aan uw website toe te voegen. > Dit kunt u op elke gewenste plek in de boomstructuur doen. Van belang is wel dat u deze pagina de UNIEKE interne pagename ‘news’ geeft. Als u toch graag een andere naam wilt gebruiken, kunt u dat gewoon doen, maar dan dient u in het bestand ‘index.php’ de constante $NEWS_PAGE_NAME dezelfde waarde te geven (standaard staat deze waarde dus uiteraard op ‘news’). Zolang de namen overeen komen, zal de nieuwspagina functioneren. > Als u de pagina hebt toegevoegd, opent u het bestand ‘newspage_nodecontent.php’ in de map ‘mod’. > U kopieert de code uit dit bestand en plakt deze in de contenteditor van uw nieuwspagina, waarmee u alles wat er al in stond, dient te overschrijven. > De constante $MAX_ITEMS die bovenin deze code een waarde krijgt (standaard 10) geeft het maximum aantal berichten dat op de nieuwspagina getoond zal worden. Deze waarde kunt u naar believen wijzigen. > Hierna slaat u de boel op. Vanaf dat moment kunt u de nieuwspagina gebruiken. > In het bestand ‘index.php’ kunt u de constante $NUM_NEWS_ITEMS ook nog wijzigen. Deze constante bepaalt hoeveel nieuwsberichten er in de nieuwskolom met ‘meest recente berichten’ komt. Standaard staat deze waarde op 7. > Het aanmaken, verwijderen en bewerken van berichten in het beheersysteem spreekt voor zich. Met de ‘EDIT’ link achter elk bericht in de lijst onder de editor
>
•
selecteert u een bericht voor bewerking (het licht blauw op). Met de ‘Delete’ knop kunt u berichten verwijderen. Er dient echter altijd minimaal één bericht in de database achter te blijven. Dit wordt overgelaten aan de ontwikkelaar. Tenslotte kunt u met de knop ‘Nieuw bericht’ een nieuw bericht aanmaken. Bij het drukken op de knop wordt al het werk al gedaan, ook opslaan in de database. Hierna hoeft u alleen nog maar de content van het bericht zelf (geldige HTML) aan te passen en op te slaan. LET OP: de content van nieuwsberichten dient uit geldige HTML te bestaan! Immers, op de nieuwspagina zelf worden de berichten weergegeven, waar u ze uiteraard ook moet kunnen opmaken (CSS). Gebruik dus HTML tags bij het schrijven van berichten.
Onder het tabblad ‘CSS’ kunt u de CSS-opmaakregels voor de website zelf wijzigen. Standaard wordt er om een voorbeeld te kunnen weergeven al een volledige stylesheet aangeleverd. Deze CSS-regels vindt u dan ook terug in het editorscherm op deze pagina. Deze pagina leest het ascii-bestand ‘default.css’ uit en schrijft eventueel door u opgeslagen veranderingen ook weer hier naartoe weg. De CSS komt dus NIET uit de database, wat u ook de mogelijkheid geeft van de FTP-server het bestand uit de map ‘css’ te downloaden en in uw favoriete editor aan te passen. Hierna kunt u het gewoon weer uploaden. De online toegankelijkheid van de CSS is een feature die het gemakkelijk maakt voor zelfverzekerde ontwikkelaars kleine veranderingen snel en zonder onnodige overhead (zoals versiebeheer) uit te voeren. LET OP: Een aantal CSS klasse- en ID-namen zijn voor het framework gereserveerd voor gebruik met bepaalde tags. Dit kan een beperking opleveren in het geven van namen, ID’s en klassen aan HTML-tags in uw template of in de content van pagina’s of nieuwsberichten. De gereserveerde namen kunt u terugvinden in ‘css_reserved_names.txt’.
•
Onder het tabblad ‘gebruikers’ kunt u gebruikers van het beheersysteem van het framework toevoegen en verwijderen. De eerste gebruiker kunt u niet verwijderen. Er dient namelijk altijd minimaal één gebruiker geregistreerd te zijn om het systeem nog te kunnen gebruiken. Op deze pagina kunt u automatisch wachtwoorden laten genereren (zelden noodzakelijk), bestaande wachtwoorden decrypten, wachtwoorden van bestaande gebruikers wijzigen, naam en gebruikersnaam van bestaande gebruikers wijzigen en kunt u uiteraard nieuwe gebruikers aanmaken.