Good Code Style Guide 1

[MyAccount]

Ich hoffe dass sich hier einige mit einbringen können. Den Code möchte ich hier im ersten Thread stetig anpassen, wie es sich aus den hoffentlich folgenden Posts eben ergibt.

Code: Alles auswählen

<?php
/**
* Include
* see contenido/include/api/functions.api.general.php
* cInclude "(frontend",...) includes own classes
* cInclude "(classes",...) includes contenido classes
*/
cInclude("frontend", "includes/functions.yni.whatsitfor.php");
cInclude ("classes", "class.htmlelements.php");

/**
* Initialization
* $yniBooVar1 for ...
* $yniIntVar2 for ...
* $yniArrSetting for setting array
* $yniObjLink for html links
*/
$yniBooVar1    = false;
$yniIntVar2    = 1;
$yniArrSetting = array();
$yniObjLink    = 0;

/**
* Setting
* $yniArrSetting["myVar1"] for ...
* $yniArrSetting["myVar1"] for ...
* $yniObjLink for ...
*/
$yniArrSetting["myVar1"] = "CMS_VALUE[0]";
$yniArrSetting["myVar3"] = "CMS_VALUE[1]";
$yniObjLink              = new cHTMLLink ( "CMS_VALUE[0]" );

/**
* for details see contenido/classes/class/htmlelements.php
* setContent   = text within the <a>-tag
* setClass     = sets class
* setID        = sets unique ID
* setEvent     = sets javascript event
* setAttribute = sets any attribute (e.g. title)
*/
$yniObjLink->setContent("quasi monopolistische Suchmaschine");
$yniObjLink->setClass("cssLinkKlasse");
$yniObjLink->setID("myLink1");
$yniObjLink->setEvent("click", "alert('foo')");
$yniObjLink->setEvent("onmouseover", "changeColor('id')");
$yniObjLink->setAttribute("title","gelber Tooltip Text");

/**
* output
* never use html output within the modules
*/
print $yniObjLink->toHtml();

?>

Code: Alles auswählen

<?php
/**
* Include
* see contenido/include/api/functions.api.general.php
* cInclude "(frontend",...) includes own classes
* cInclude "(classes",...) includes contenido classes
*/
cInclude("frontend", "includes/functions.yni.whatsitfor.php");
cInclude ("classes", "class.htmlelements.php");

Die Funktion cInclude ist ein Short-Cut für die Funktion contenido_include. Die Funktion befindet sich in contenido/include/api/functions.api.general.php. Eine sehr nützliche Funktion, da mit dem ersten Ausdruck angegeben wird, wo die Klasse zu finden ist. In diesem Beispiel "frontend" befindet sich die Datei im Ordner includes des aktuellen Mandantenverzeichnisses.

Code: Alles auswählen

/**
* Initialization
* $yniBooVar1 for ...
* $yniIntVar2 for ...
* $yniArrSetting for setting array
* $yniObjLink for html links
*/
$yniBooVar1    = false;
$yniIntVar2    = 1;
$yniArrSetting = array();
$yniObjLink    = 0;

Warum Initalisieren? Zur Sicherheit. Je nach PHP-Konfiguration auf dem Webserver könnte man z.B. die Variable $yniBolLoginOk einfach mit dem Aufruf dieser URL http://www.domain.tld/skript.php?yniBolLoginOk=1 überschreiben.

Code: Alles auswählen

/**
* Setting
* $yniArrSetting["myVar1"] for ...
* $yniArrSetting["myVar1"] for ...
* $yniObjLink for ...
*/
$yniArrSetting["myVar1"] = "CMS_VALUE[0]";
$yniArrSetting["myVar3"] = "CMS_VALUE[1]";
$yniObjLink              = new cHTMLLink ( "CMS_VALUE[0]" );

Vielleicht kann hier noch jemand was schreiben, wann man welche Anführungszeichnen (") (') nehmen soll?

Code: Alles auswählen

/**
* for details see contenido/classes/class/htmlelements.php
* setContent   = text within the <a>-tag
* setClass     = sets class
* setID        = sets unique ID
* setEvent     = sets javascript event
* setAttribute = sets any attribute (e.g. title)
*/
$yniObjLink->setContent("quasi monopolistische Suchmaschine");
$yniObjLink->setClass("cssLinkKlasse");
$yniObjLink->setID("myLink1");
$yniObjLink->setEvent("click", "alert('foo')");
$yniObjLink->setEvent("onmouseover", "changeColor('id')");
$yniObjLink->setAttribute("title","gelber Tooltip Text");

Tipp von stese. Sehr nette Klasse aus der Contenido-Installation contenido/classes/class.htmlelements.php hier anhand eines HTML-Links demonstriert.

Code: Alles auswählen

/**
* output
* never use html output within the modules
*/
print $yniObjLink->toHtml();
?>

Tipp von stese. Niemals HTML-Code (<a href=".CMS_VALUE[0]."...) direkt im Modul ausgeben.

[MyAccount]

Dann gleich mal den ersten Kommentar dazu.

Kommentare wie z.B. bei PhpDoc mit /** anstelle von # oder //?

Vorschlag von stese:
Den Variablen die eigenen Initialen voranstellen, dann den Typ der Variablen und dann einen verständlichen Namen.

Boolean (Boo)
Integer (Int)
Fließkomma-Zahl (Flo)
String / Zeichenkette (Str)
Array (Arr)
Object (Obj)

Variablen, die man nutzen will vorher initalisieren?

[Halchteranerin]

Kommentare wie z.B. bei PhpDoc mit /** anstelle von # oder //?

Ich kenne PHPDoc nicht, aaaber ...
Eigentlich kommentiert man mehrzeilig mit

Code: Alles auswählen

/*
mehrzeiliger
Kommentar
*/

und einzeilig mit

Code: Alles auswählen

//einzeiliger Kommentar

/** habe ich bisher noch nicht gesehen, es sei denn, jemand hatte so etwas wie
/*********
*********/
gebastelt.

[MyAccount]

Ja, das ist korrekt. Aaaaber... Wer phpdoc nicht kennt, dem sei es hiermit dieser Link:http://www.phpdoc.org/ ans Herz gelegt. Ist im Übrigen das State of the art-Tool für saubere Dokumentierung unter PHP.

[stese]

naja bevor wir hier anfangen was eigenes zu stricken sollten wir f4b bitten ihre programmierrichtlinien doch auch mit zu veröffentlichen. ich habe in den im bundle mitgelieferten docs und in den apidocs geschaut und nix gefunden.

in den richtlinien wird im regelfall auf alle eventualitäten detailiert eingegangen.

[MyAccount]

Naja, was die Dokumentation angeht...

Code: Alles auswählen

<?php
/**
 * article specification class
 */

class ArtSpecCollection extends ItemCollection {
	/**
     * Constructor Function
     * @param none
     */
	function ArtSpecCollection()

Das nur als Beispiel aus contenido/classes/class.artspec.php



Gruß MyAccount

PS: Hab oben mal noch die inklude-Geschichte eingebaut. Fände es nicht schlecht, wenn man bei globalen Klassen, den Ursprung der Klasse mit angibt...

PPS: Und noch einer. Was mit besonders gut gefallen hat, ist HerrBs Auslagerung oder eher Einlagerung der "CMS_VALUE[]"s in ein extra Array.

[stese]

so, ich mach mal kurz weiter ....

in modulen möglichst kein ausgeschriebenes html verwenden, statt dessen bei einfachen HTML Ausgaben die Contenido HTML API verwenden.

1. sicherstellen, dass htmlapi geladen wurde:

Code: Alles auswählen

cInclude ("classes", "class.htmlelements.php"); 

2. entsprechendes HTML Element erzeugen - beispiel hier a-tag:

Code: Alles auswählen

$objLink = new cHTMLLink ( "http://www.google.de" );

3. weitere Eigenschaften des Objektes festlegen

Code: Alles auswählen

// text innerhalb des atags - beschreibung
$objLink->setContent("quasi monopolistische Suchmaschine");

// css class setzen
$objLink->setClass("cssLinkKlasse");

// eindeutige id setzen
$objLink->setID("myLink1");

// javasscript eventhandler setzen
$objLink->setEvent("click", "alert('foo')");
$objLink->setEvent("onmouseover", "changeColor('id')");

// title tag hinzufügen
$objLink->setAttribute("title","gelber Tooltip Text");

// link erzeugen und ausgeben lassen:
print $objLink->toHtml();

prinzipiell kann so jeder HTML Tag erzeugt werden, vorgefertigte html tag Methoden sind z.B.
cHTMLButton, cHTMLCheckbox, cHTMLDIV, cHTMLForm, cHTMLFormElement, cHTMLHiddenField, cHTMLIFrame, cHTMLImage, cHTMLLabel, cHTMLLink, cHTMLOptionElement, cHTMLPasswordbox, cHTMLRadiobutton, cHTMLSelectElement, cHTMLSPAN, cHTMLTable, cHTMLTableData, cHTMLTableHead, cHTMLTableRow, cHTMLTextarea, cHTMLTextbox, cHTMLUpload

weitere html elemente lassen sich relativ einfach hinzufügen, indem man sich die datei classes/class.htmlelements.php und die pear klasse HTML/common.php näher anschaut.

Bei umfangreicheren HTML Konstrukten die Template-Klasse nutzen