Fragen zur API (-Dokumentation)

[knb]

Habe mal ein Script geschrieben, und mir mit Doxygen mal die Dokumentation für die 4.6.15er Version erstellt.

Da haben sich vorläufig ein paar Fragen ergeben.

Klasse DB_Sql wird nicht mit erfasst beim doxygen Durchlauf, weil die Klasse in ../conlib liegt.
Könnte man nich auch den Kram in conlib mit erfassen ? Zusätzliches doxy-api.conf anlegen, geht doch einigermassen?
(Habe dazu gerade einen Feature Request gepostet.)
Was ist eigentlich der Grund dafür dass diese Dateien in einem eigenen Verzeichnis ../conlib liegen und auf .inc enden?

Warum die unterschiedliche Namenskonvention bei den Klassennamen? Kommt mir etwas inkonsistent vor. Was bedeuten die Präfixe ("c", cAPI, etc)? Sind das nur die Vorlieben der jeweiligen Programmierer oder steckt eine weitergehendes Konzept dahinter?
Sagt es was aus über:
Gibt es offizielle oder inoffizielle Klassen? welche sind veraltet, welche neu und werden empfohlen,
Welche sind neu und ggf. noch nicht fertig?
Ist die "deprecated" Liste (in der doxygen contenido API Dokumentation) auf dem neuesten Stand?

Gibt es ein default Verzeichnis wo man selbstgeschriebene API scripts ablegen sollte?
Ich nehme jetzt zur Entwicklung das contenido/tools Directory, weil dort ja schon einige andere Scripts (von 4fb) drin liegen.
Was dagegen? Sollte man sich ein eigenes Unterverzeichnis in tools anlegen? Oder lieber ein eigenes Dir auf der gleichen Ebene wie "tools"?

Wie würde ein Stub oder API-Script-Grundgerüst aussehen für ein API-Script welches auf Contenido zugreift
bei dem sich der User aber erst einloggen muss damit es überhaupt was macht?

Z.B.
Welche von den cInclude Zeilen sollten in so ein script stets mit reingenommen werden, weil man sie eigentlich immer braucht? Ich meine so was wie ...

cInclude ("includes", 'functions.i18n.php');
cInclude ("includes", 'functions.api.php');
cInclude ("includes", 'functions.general.php');
etc etc ....

Könnte man nicht so ein PHPScript-Template mitliefern, d.h in die Installations-Zipdatei reinpacken? Wäre m.E. ganz hilfreich.

[emergence]

Klasse DB_Sql wird nicht mit erfasst beim doxygen Durchlauf, weil die Klasse in ../conlib liegt.
Könnte man nich auch den Kram in conlib mit erfassen ? Zusätzliches doxy-api.conf anlegen, geht doch einigermassen?

ja könnte man... das andere posting hab ich bereits verschoben...

Was ist eigentlich der Grund dafür dass diese Dateien in einem eigenen Verzeichnis ../conlib liegen und auf .inc enden?

das mit .inc ist historisch bedingt -> das war schon in der phplib so...
das mit eigenem verzeichniss -> wenn man mehrere contenido backends verwendet... conlib und pear müssten dann nicht nochmal raufgeladen werden...

Warum die unterschiedliche Namenskonvention bei den Klassennamen? Kommt mir etwas inkonsistent vor. Was bedeuten die Präfixe ("c", cAPI, etc)? Sind das nur die Vorlieben der jeweiligen Programmierer oder steckt eine weitergehendes Konzept dahinter?

ähm, ich würd mal sagen -> vorliebe des programmierers...
zum rest

Gibt es offizielle oder inoffizielle Klassen? welche sind veraltet, welche neu und werden empfohlen,
Welche sind neu und ggf. noch nicht fertig?
Ist die "deprecated" Liste (in der doxygen contenido API Dokumentation) auf dem neuesten Stand?

ähm, darüber hab keine infos...

Gibt es ein default Verzeichnis wo man selbstgeschriebene API scripts ablegen sollte?

sollte ? ähm, nein...

[knb]

noch mehr fragen ... werde für mein nächstes Posting in diesem Thread versuchen mehr anzusammeln , aber hier erstmal noch was:

es gibt jede Menge Class Member Fuctions die mit Unterstrich "_" anfangen. Sind diese Funktionen "privat", also sollte/darf man diese Funktionen nicht benutzen? DARF man sie nicht benutzen oder kann man sie durchaus benutzen, weil der Unterstrich eigentlich gar nichts bedeutet?

_addPath() : XmlParser
_buildGroupWhereStatements() : ItemCollection
_buildHeaderData() : Contenido_Navigation
_buildImagePath() : cWidgetTreeView
_buildWhereStatements() : ItemCollection
_changeKeyCase() : XmlParser
_characterData() : XmlParser
etc

Es gibt in der API generell zwei Zugriffsmöglichkeiten: Über Functions die keiner Klasse speziell zugeordnet sind, und es gibt Klassen mit Member Functions. Sollte man generell eher Klassen verwenden, und nur wenns nicht anders geht, eine Funktion ? Oder ist diese Frage bereits falsch gestellt, weil bestimmte Sachen sich nicht bestimmten Klassen zuordnen lassen? (Naja man hätte ja eine Klassendatei class.util.php oder so definieren und da alles reinpacken können ... wahrscheinlich historische Gründe ... "organisches Wachstum" )

Andererseits habe ich schon viele Module gesehen die ein neues DB_Contenido objekt anlegen, und dann SQL statements zusammenbasteln und so auf die Datenbank zugreifen. Immerhin per API, aber trotzdem ginge es oft sauberer per objektbasiertem Zugriff.


Was bedeutet das Präfix "str" aus functions.str. ? Anscheinend nicht "String" denn diese Funktionen (Beispiel) machen doch nichts mit Strings ... weder als Input, noch als Output noch mittendrin:

strRemakeTreeTable ()
strDeeperCategoriesArray($idcat_start)
strDeleteCategory($idcat)


Jemand müsste mal ein Paper schreiben "The complete idiot's guide to the Contenido API" wo man so an die Thematik herangeführt wird.

[emergence]

Was bedeutet das Präfix "str" aus functions.str. ?

str -> structure

[HerrB]

Alle Deine Fragen lassen sich einfach beantworten: Historisch gewachsen und 1000nde Installationen, die die vorhandenen Bezeichnungen verwenden...

Bei Klassen ist kein Präfix alter Code, "c"-Präfix mittelalt und "cAPI" relativ neu (halt der Versuch, eine saubere API zu gestalten).

Was meinst Du mit "selbstgeschriebene API scripts"? Wenn man der Nomenklatur folgt, würden eigene API-Dateien vermutlich in contenido/classes/<Name> am Besten aufgehoben sein (e.g. contenido/classes/knb).

Ist die "deprecated" Liste (in der doxygen contenido API Dokumentation) auf dem neuesten Stand?

Wenn einer dran gedacht hat, an die tote Funktion/Klasse/whatever deprecated ranzuschreiben, ja... wirklich blind würde ich mich nicht darauf verlassen.

contenido/tools enthält i.A. eigenständig laufende Skripe, die man wie einen Schraubenschlüssel gelegentlich mal braucht - es ist kein Ort für Dateien mit Klassen- oder Funktionsdeklarationen, die man im Backend oder Frontend einbindet.

Für Klassen würde ich contenido/classes und dort ein Unterverzeichnis nehmen (wie erwähnt), Funktionen unter contenido/includes und dort ein Unterverzeichnis.

Wie würde ein Stub oder API-Script-Grundgerüst aussehen für ein API-Script welches auf Contenido zugreift

Mal einen Blick in die cronjobs werfen.

bei dem sich der User aber erst einloggen muss damit es überhaupt was macht?

Schwerer, wenn Du Backend meinst, siehe contenido/main.php, frame_left.php usw.

Welche von den cInclude Zeilen sollten in so ein script stets mit reingenommen werden, weil man sie eigentlich immer braucht? Ich meine so was wie ...

Im Prinzip siehe cronjobs, main.php und startup.php - so richtig die Liste habe ich da noch nicht ausmachen können.

Könnte man nicht so ein PHPScript-Template mitliefern, d.h in die Installations-Zipdatei reinpacken? Wäre m.E. ganz hilfreich.

Habe ich nicht ganz verstanden, aber Du meinst vermutlich eine Datei, wo man einfach nur eigenen Code einfügen muss, damit es funktioniert? Tja, wie gesagt, die cronjobs sind sowas (aber ohne Anmeldung); ansonsten würde ich es nicht unbedingt machen, denkt keiner dran, ist nie aktuell und im Problemfall eine Sicherheitslücke.

Gruß
HerrB

[HerrB]

Unterstrich = Privat. Aber ob sich alle dran gehalten haben...

Es gibt in der API generell zwei Zugriffsmöglichkeiten: Über Functions die keiner Klasse speziell zugeordnet sind, und es gibt Klassen mit Member Functions. Sollte man generell eher Klassen verwenden, und nur wenns nicht anders geht, eine Funktion ?

Yep.

Funktionsklassen finde ich sub-optimal, da ich erst ein Objekt erzeugen muss, um eine Funktion auszuführen, um danach das Objekt wieder zu zerstören.

Andererseits habe ich schon viele Module gesehen die ein neues DB_Contenido objekt anlegen, und dann SQL statements zusammenbasteln und so auf die Datenbank zugreifen. Immerhin per API, aber trotzdem ginge es oft sauberer per objektbasiertem Zugriff.

Wenn Du Dir den Code ansiehst, wirst Du merken, dass es gaaaanz viel altes Geraffel gibt, welches dann schleichend in neuen Code übergeht. Sauberer, besser, aber auch langsamer geht es via API (bzw. genericdb). Leider ist aber die genericdb z.Z. in ihren Möglichkeiten limitiert, so kann man z.B. z.Z. keine Felder zur Rückgabe auswählen, nicht wirklich einfach aus mehreren Tabellen Daten erhalten oder eine Verknüfung realisieren, die nicht auf den Tabellen-IDs beruht oder ein Distinct erfordert. Die Select- und flexSelect-Methode der ItemCollection (genericdb) ist nur eine "Quick and Dirty"-Lösung, um für das Objekt direkte SQL-Abfragen zu ermöglichen. Eigentlich haben beide Methoden keine Existenzberechtigung, aber ohne gehts im Moment auch nicht.

Jemand müsste mal ein Paper schreiben "The complete idiot's guide to the Contenido API" wo man so an die Thematik herangeführt wird.

Tja, müsste. Problem daran ist, dass es noch gar keine komplette API gibt und beim Schreiben einer Doku für das aktuelle System man vermutlich zu dem Schluss kommt, dass es keinen Sinn macht, die ollen Kamellen auch noch zu beschreiben...

Gruß
HerrB

[knb]

mit "selbstgeschriebene API scripts" meinte ich PHP Scripts die von "ausserhalb" auf das Contenido CMS zugreifen und dort systemweit irgendwas machen. Beispiele wäre das alte "copyclient.php" script hier aus dem Forum, oder das davon inspirierte deleteclient.php script . Oder tools/upgrade.php.

Um solch radikale Eingriffe auszuführen ist es einfach besser, wenn man gerade *nicht* im Backend eingeloggt ist.

Ich finde es teilweise einfacher sowas als externes Script zu programmieren weil man sich dann gleich auf die eigentliche Aufgabe konzentrieren kann und nicht extra berücksichtigen muss wie man das ganze ins Contenido Backend (oder Frontend) integriert .

Meist muss man aber sicherstellen dass nicht jeder beliebige User das Script ausführen kann... und daher sollte ein script auf den Contenido-internen Authentifizierungs-Mechanismus zurückgreifen. Also eigentlich arbeitet man doch im Backend, nur nicht mit dem GUI/Frameset.

Mit meiner Frage meinte ich nicht "wo sollte ich meine eigenen Contenido-Objektmodell-basierten Klassen ablegen" ... obwohl die Frage auch hätte von mir sein können

Die "relativ neue" cAPI-Klassenpräfix-Namenskonvention wurde m.E. aber auch nicht konsequent durchgehalten. Zum Beispiel gibt es keine Klasse cAPIFrontenduserCollection sondern nur FrontendUserCollection ... obwohl die Frontenduser Verwaltung ein neues Feature aus dem 4.6er Release ist (und es somit irgendwie cAPI- Klasse geben sollte).

Aber egal, jetzt muss man halt damit leben. Geht ja auch wenn man weiss womit man es zu tun hat

[HerrB]

Die "relativ neue" cAPI-Klassenpräfix-Namenskonvention wurde m.E. aber auch nicht konsequent durchgehalten. Zum Beispiel gibt es keine Klasse cAPIFrontenduserCollection sondern nur FrontendUserCollection ... obwohl die Frontenduser Verwaltung ein neues Feature aus dem 4.6er Release ist (und es somit irgendwie cAPI- Klasse geben sollte).

Die Klasse liegt in contenido/classes (und ist da sogar schon länger drin), daher folgt sie der "alten" Nomenklatur. Nur Klassen, die in contenido/classes/contenido liegen, tragen die cAPI-Kennung...

Aber ansonsten: Ja, konsequent isses nich. Ich selbst bin mit meinen Klassen unglücklich, da "Recipient" nicht wirklich ein guter Name für eine Klasse ist... (aber ich habe mich halt am vorhandenen Code orientiert).

Gruß
HerrB