Feature Discussions

[wiegele]

Hallo zusammen,

ich finde die FS Dokumentation bedarf einer Überarbeitung.

Bei der Suche nach Lösungen in der FS Dokumentation, fällt es mir oft sehr schwer den roten Faden nicht zu verlieren.

Eine durchgängige nachvollziehbare Dokumentation für einzelne Funktionen ist oft nicht vorhanden.

Es fehlt häufig ein kleines Detail zur Lösung des Problems.

Mir graust es oft, die Dokumentation zu verwenden.

Man steht am Ufer sieht den Bootssteg, die darauf liegenden Paddel und die Insel auf die man möchte.

Hier nur einmal ein kleines Beispiel dazu.

Auf der Suche nach der Verwendung von Funktionen in FS kann ich keine erschöpfende Antwort darauf finden, wie ich Funktionen Parameter übergeben kann.

$CMS_VALUE(methodenName([Argumente]))$

Das finde ich als Dokumentation nicht ausreichend, da die CMS_FUNCTION Deklaration scheinbar anderes interpretiert wird als bei anderen Hochsprachen.

Wie verwendet man Funktionen mit einem Mix aus CMS_PARAM und CMS_VALUE_PARAM?

Muss das erste CMS_PARAM jetzt als Argument angeben werden?

Wie Funktionen verwendet werden habe ich mir jetzt aus anderen bereits bestehenden Implementationen abgeleitet.

Man sollte doch meinen, zu diesem Beispiel würde man in der Hilfe unter der Eingabe von

CMS_Function Parameterübergabe etwas finden. Leider nicht.

Wo ich jetzt auf jeden Fall vermutet hätte eine Lösung zu finden wäre in „Funktionen im Header: define“.

Auch wenn ich hier weiter ausgeholt habe, sollte dies als Verbesserungsvorschlag eingehen und nicht ein Thema sein über das man diskutiert.

Mfg Dirk Wiegele

[Peter_Jodeleit]

Funktionsaufrufe innerhalb von CMS_VALUE-Ausdrücken in FirstSpirit unterscheiden sich nicht von "anderen Hochsprachen", der Syntax ist <Variablenname>.<Funktionsname>(<Parameterliste>). Beispiel: $CMS_VALUE(s.substring(0, 5)$

Wegen der Erwähnung von CMS_PARAM und CMS_VALUE_PARAM vermute ich aber, das hier der Syntax von Headerfunktionen gemeint ist. Aufrufe von Headerfunktionen werden als XML notiert und unterscheiden sich daher stark von klassischen Programmiersprachen. Die Parameter werden dabei als XML-Attribut-Werte übergeben. Dabei muss man bei der Parameterübergabe zwischen "konstanten textuellen Werten" und "Variablennamen" unterscheiden können.

Beispiel:

<CMS_PARAM name="justify" value="left" />

"left" könnte ein Variablenname oder eben der Text "left" sein. Um dazwischen zu unterscheiden, gibt es die zwei Arten der Parameterübergabe, CMS_PARAM für Konstanten und CMS_VALUE_PARAM für Variablen/Ausdrücke.

Man kann auch über CMS_VALUE_PARAM konstante Texte übergeben, dafür muss man diese in doppelte Anführungszeichen einfassen. Da XML selber wieder eine Einfassung von Attributwerten verlangt, muss man dafür dann einache Tics verwenden:

 <CMS_VALUE_PARAM name='...' value='"my text"' />

Wie man an diesem Beispiel sehen kann, ist dies nicht gut lesbar. Und genau das ist der Hintergrund für diese Trennung.

Ich hoffe, ich konnte ihnen hiermit einen Hinweis auf das fehlende Ruderboot liefern.

In jedem Fall wäre ich über einen Hinweis dankbar, ob dies eine hilfreiche Ergänzung für die Dokumentation wäre oder ob ich mit meiner Vermutung total daneben liege.

[Peter_Jodeleit]

Per PM kamen noch folgende Anmerkung: Das Verständnisproblem bezieht sich konkret auf Headerfunktion "define". Da fehlen in der Dokumentation tatsächlich Hinweise auf die Benutzung der so definierten Variablen innerhalb des Templates. Das wird korrigiert (interne ID #113988).

<CMS_HEADER>

  <CMS_FUNCTION name="define" resultname="myVariableName">

    <CMS_PARAM name="text" value="some text" />

    <CMS_VALUE_PARAM name="meaning_of_life" value="6 * 7" />

  </CMS_FUNCTION>

</CMS_HEADER>

$CMS_VALUE(myVariableName.text)$ $-- some text --$

$CMS_VALUE(myVariableName.meaning_of_life)$ $-- 42 --$

Noch ein Hinweis in eigener Sache: Verbesserungsvorschläge für die Dokumentation werden gerne angenommem. Je konkreter die Hinweise sind, desto schneller lässt sich Abhilfe schaffen

[wiegele]

Ich möchte noch Mal anmerken, dass es sich bei der Headerfunktion nur um ein Beispiel handelt.

Ich finde man kommt oft an Stellen in der Dokumentation an denen das Bindeglied zur nächsten Information fehlt.

[hoebbel]

Hallo Herr Wiegele,

verstehe ich das richtig, dass Sie sich im Prinzip eine Dokumentation wünschen, die einzelne grundsätzliche Dinge zusammenhängend beschreibt?

Für die speziellen Aspekte [also zum Nachschlagen] wäre dann die aktuelle Dokumentation ausreichend.

Oder anders herum gefragt:

Wenn die "Step by Step" [User: FIRSTDoku / Pass: FSdown_V2] Dokumentation umfangreicher bzw. tiefergehender wäre, würde das das Problem beseitigen?

Für den speziellen Fall müsste dann zum Beispiel bei der Erläuterung der Navigationsfunktion der Unterschied der drei Parametertypen an sinnvollen Beispielen erläutert werden.

Viele Grüsse aus Dortmund,

  Holger Höbbel

[rbitdd]

Hallo,

ich gebe auch mal meinen Senf dazu ab:

Wenn man die Dokumentation von der Version 3.x und älter noch kennt, ist die Dokumentation von 4.x echt umfassend und gut.

Leider muss ich Herrn Wiegele dennoch recht geben, als dass die Doku durchaus noch Verbesserungspotential hat.

Ein Beispiel:

Ich habe heute Vormittag nach den Methoden / Eigenschaften von FS_LIST gesucht.

Erwartet hätte ich diese unter der Beschreibung von FS_LIST. Leider wurde ich dort nicht fündig.

Auf den Seiten der einzelnen Ausprägungen von FS_LIST, z.B. INLINE, konnte ich einen Verweis auf den Datentypen finden.

Der Verweis auf diese Seite ist imho vollkommen ausreichend, es wäre jedoch schön, wenn man diesen Verweis zumindest zusätzlich auch auf der Beschreibungsseite von FS_LIST finden könnte.

Es würden sich sicherlich noch andere Beispiele finden lassen.

Des Weiteren würde ich noch anregen, dass ein Update der Dokumentation (odfs) zu den Updates der Server-Versionen z.B. als ZIP zur Verfügung gestellt werden könnte.

Ich habe vor einigen Wochen den aktuellen Stand der Doku verteilt, weil einige Kollegen immer nur das fs_server.jar ausgetauscht hatten. (Gerne erstelle ich dazu einen eigenen FR )

Viele Grüße

D.

[wiegele]

Hallo Herr Höbbel,

eine umfangreichere Step by Step(Howto's) Anleitung fände ich persönlich sehr gut.

[rschulz]

Noch ein Beispiel aus der API Dokumentation:

Die Beschreibung von isLocked() ist irreführend, da nur der Lock in der aktuellen Session geprüft wird, was in den Javadocs nicht erwähnt wird.

Hier sollte auch eine @link Annotation zu isLockedOnServer(boolean) vorhanden sein.

[kohlbrecher]

Hallo Dirk,

vielen Dank für deine Idee zur Verbesserung von FirstSpirit. Es ist uns wichtig, aus den Erfahrungen unserer Kunden und Partner zu lernen. Aus diesem Grund schätzen wir Feedback und freuen uns über jede Anregung.

Unsere Dokumentation wird kontinuierlich verbessert. Um immer auf die aktuellste Dokumentation zuzugreifen empfehle ich die Verwendung der Online Dokumentation FirstSpirit - Übersicht über die Dokumentation .

Konkrete Fehler oder unklare Punkte bitte an unseren Technical Support kommunizieren, so dass wir die betroffenen Stellen überarbeiten können.

Viele Grüße

Jan