Benutzung von Expressions
Entwickelt und getestet für PIM 8.17, gültig ab PIM 8.8
Einleitung
Ziel
Diese Anwenderdokumentation dient dazu, den täglichen Umgang mit Expressions (Attributwerte mit berechneten Formelausdrücken) zu vereinfachen.
Der erste Abschnitt
ist im FAQ / Best-Practice Format gehalten, damit dieser Teil als Nachschlagewerk bei der täglichen Arbeit verwendet werden kann. Der Leitsatz lautet: "Wie kann ich … ?"
Im zweiten Abschnitt
werden spezielle Einzelfragen und Fragen zu Spezifikationen behandelt.
Im dritten Abschnitt
werden häufige Fehler vorgeführt und eine Lösungsfindung zu den Problemen erarbeitet. Dazu findet sich am Schluss der Dokumentation ein Glossar, in dem Fachwörter näher eingehend beschrieben werden.
Voraussetzungen
Es wird vorausgesetzt, dass der Leser:
- das Datenmodell (Entitäten) und Zusammenhänge im PIM und ggf. DAM kennt und versteht.
- IDs für Attribute, Terms etc. recherchieren kann.
- Grundwissen in JavaScript hat.
- mit allgemeinen Programmierkonstrukten wie Variablen, Schleifen, if-Bedingungen und objektorientierten Techniken generell Erfahrung hat.
Begriffserklärung (Glossar)
Im laufe der folgenden Anwenderdokumentation werden möglicherweise Fachbegriffe auftauchen, die Ihnen Unbekannt sein könnten. Im folge daraus steht Ihnen auf der letzten Seite ein Glossar zur Verfügung, in dem diese Begrifflichkeiten erklärt werden.
Scope
Diese Dokumentation behandelt die Expressions und deren Möglichkeiten in PIM 8.17 (ab PIM 8.8)
Spezielle DAM Themen sind nicht Teil dieses Dokumentes.
Diese Dokumentation ist keine allgemeine Einführung in JavaScript. Dazu wird auf die übliche Sekundärliteratur verwiesen.
Diese Dokumentation ist keine allgemeine Einführung in PIM oder DAM
Bemerkung:
Die Beschreibungen und Screenshots wurden mit der englischen (en) PIM Oberfläche erstellt.
- Einleitung
- FAQ – Wie kann ich … ?
- ein Produkt-Basisdaten-Feld verwenden?
- einen einfachen Attributwert verwenden?
- einen mehrsprachigen Attributwert verwenden?
- mehrwertige Attribute verwenden?
- auf ein Attribut mit einer Werteliste zugreifen?
- auf ein mehrwertiges Attribut mit einer Werteliste zugreifen?
- auf textTable bzw. "freie Tabellen" Attribute zugreifen?
- Formatierung von Zahlen
- Nullsafe
- Ein Datum mit deutscher Formatierung ausgeben (tt.mm.jjjj)?
- Einen Term verwenden?
- Custom JS Functions
- Spezifikationen und spezielle Fragen
- Troubleshooting
- Glossar
FAQ – Wie kann ich … ?
ein Produkt-Basisdaten-Feld verwenden?
Um ein Produkt-Basisdaten-Feld mit Expressions zu verwenden, müssen Sie als erstes ein Produkt auswählen. Anschließend müssen Sie den Reiter “Attributes” auswählen, einen Haken auf das Feld “Is Expression” setzen und auf den “Value” Inhalt klicken, um den Expression Editor zu öffnen. Dann müssen Sie die Expression einfügen um auf die Schaltfläche Run klicken um die Expression auszuführen:
Um zum Beispiel auf das Basisdaten Feld ‘productId’ zuzugreifen, wird “product.” gefolgt von der Basis Datenfeld-ID aufgerufen (siehe Beispiel im Codeblock).
product.productId
Beachten Sie die Groß- und Klein Schreibweise von productId
Was wird bei nicht vorhandenen Feldern ausgegeben?
Falls die Expression ein Feld ausgeben soll welches keinen Wert besitzt, wird "null" ausgegeben.(Nicht gleichzusetzen mit leerem Wert)
Was ist ein Produkt-Basisdaten-Feld im Gegensatz zu einem Attribut?
Alle Felder, die Sie auf dem Reiter “Basisdaten” im PIM finden gehören zu den Stammdaten. Alle Produkte besitzen dieselben Felder als Basisdaten.
Attribute sind frei konfigurierbar und können jedem Produkt, und jeder Klassifizierung zugeordnet werden.
Attribute sind flexibel vom Namen, Typ sowie bei der Datenherkunft (z.B. aus Wertelisten).
Jedoch müssen Erweiterte-Attribut-Definitionen im voraus definiert werden, da diese später nicht veränderbar sind (z.B.: Ob das Attribut die Erweiterung “multi-language” besitzt).
einen einfachen Attributwert verwenden?
Alle markierten Felder müssen mit Ihren Daten ausgetauscht werden.
Soll ein Attributwert als Expression verwendet werden, darf das Attribut selbst nicht in der Expression benutzt/abgefragt werden
Dies wäre ein Selbstaufruf/Rekursion welcher zumindest so nicht ausführbar ist.)
Beispiel:
Ausgabe:
Beispiel:
Beispiel-Ausgabe:
Was wird bei nicht vorhandenen/leeren Attributwerten ausgegeben?
Es wird nichts zurückgegeben, angezeigt wird "null".
Welche Sprache hat der Wert?
Attributwerte sind entweder einsprachig, mehrsprachig oder sprachunabhängig.
einen mehrsprachigen Attributwert verwenden?
Den Wert in der Kontextsprache ausgeben:
Beispiel 1:
Rückgabewert für die Kontextsprache ‘de-DE’
Den Wert in einer anderen Sprache zugreifen?
↓
Liefert den ersten Wert für die Kombination aus angegebenem Attribut, und SprachId (z.B. de-DE, oder en-GB).
Beispiel 2:
Rückgabewert
mehrwertige Attribute verwenden?
Die Methode liefert ein Array von Objekten zurück. Über die Angabe des SprachIds und des Tags greifen Sie auf Attribute zu bei denen diese Attribute Eigenschaften gepflegt sind.
Beispiel:
Rückgabewert:
Beispiel für die String-Ausleitung, d.h. die Ausgabe aller Werte als ein Text:
auf ein Attribut mit einer Werteliste zugreifen?
Beispiel Abfrage:
Rückgabewert:
grün
gelb
Bei der Verwendung von TermID als Wertelisteneintrag liefert die TermID den Term ("$TermID") in der Kontextsprache zurück.
Wie ersetze ich die TermID ("$TermID") die in der Werteliste steht durch den tatsächlichen übersetzen Term?
Der Term wird in ihrer Kontextsprache, das ist normalerweise die Sprache des angemeldeten Benutzers, angezeigt.
Wie bekomme ich den übersetzen Term in einer anderen Sprache?
Um eine Werteliste mit übersetzten Terms ausgegeben zu bekommen müssen sie den Code vom Codeblock (s.o) in die Expression eingeben, mit ihrem Attribut ersetzen und ausführen.
Rückgabe-Beispiel:
green
blue
auf ein mehrwertiges Attribut mit einer Werteliste zugreifen?
Kombinieren Sie den Zugriff auf mehrwertige Attribute mittels:
product.attributeValue('AttributId' ,'tag [optional]')
Mit der Term Übersetzung von Wertelisten:
description(product.attributeValue('Attribut_mit_werteliste''Attribut_mit_werteliste','SprachId')
Alle Werte ohne Wertelisten-Übersetzung als einen String erhalten Sie mit:
Beispiel:
Rückgabe:
grün, gelb, blau
Alle Werte mit Wertelisten-Übersetzung in der Kontextsprache als einen String erhalten Sie mit:
Beispiel:
Rückgabe:
yellow
blue
Alle Werte mit Wertelisten-Übersetzung in einer anderen Sprache als einen String erhalten Sie mit:
Beispiel:
Rückgabe:
grün, gelb, blau
auf textTable bzw. "freie Tabellen" Attribute zugreifen?
Die gesamte Tabelle geben Sie aus mit:
↓
liefert eine Liste und kann dadurch nicht in Attributen vom Typ String zurückgegeben werden.
*Bitte beachten Sie, dass Sie die folgenden Expressions in einem String-Attribut ausführen müssen.
Eine einzelne Zeile geben Sie aus mit:
Eine einzelne Spalte geben Sie aus mit:
Eine einzelne Zelle geben Sie aus mit:
Auf die Terms in einer bestimmten Sprache greifen sie wie folgt zu:
return null;
}
var translation = term( (termId.indexOf('$')!=0 ? '$' : '') + termId);
if (!translation) {
translation = (termId.indexOf('$')!=0 ? termId : termId.slice(1));
}
return translation;
}
Formatierung von Zahlen
Wobei Number ein numerischer Wert sein muss.
*Sinnvollerweise eine Dezimalzahl benutzen
Strings sind hier nicht zulässig.
Das verwendete Zahlenformat ist die entsprechende Länder-Einstellung der Kontextsprache. Das wird dann lokalisierte Zahl genannt.
Beispiele:
formatDecimalNumber(product.attributeValue(parseFloat('Decimaltyp_AttributId')
Wie kann ich einen String-Wert ausgeben?
Benutzen Sie zur Umwandlung von Strings in Number die JavaScript Funktion parseFloat(String).
Beispiel:
Achtung: "parseFloat()" erwartet eine US-Dezimalzahl mit Dezimalpunkt (123.45) anstelle dem deutschen Dezimalkomma (123,45). Wird eine "Zahl mit deutscher Formatierung in die Expression eingetragen, wird ein String übergeben und "parseFloat()" gibt alles vor dem Dezimalkomma zurück und schneidet den Rest ab.
Beispiel: 123.456 →123.46 aber 123,456 → 123.00
Wie gebe ich product.attributeValue(parseFloat())als lokalisierte Zahl aus?
Sie geben im Feld für die Expression den unten aufgeführten Beispiel-Code mit ihrem eigenen Wert ein.
Nullsafe
Sie sollten Ihren Code immer null safe programmieren, da man dadurch Fehler, die durch “null” vorbeugt.
Beispiel einer Null Safe Expression:
if(product.attributeValue('AttributId')!= null){
nullsafetest=true;
} else {
nullsafetest=false
}
Beispiel einer Null Safe Expression in PIM
In diesem Beispiel wird mit der Null Safe Abfrage geprüft, ob das Attribute (“IsNew”) leer oder nicht leer ist. Wie man an dem Ergebnis sehen kann, wird ein “true” wiedergegeben, also ist das Feld nicht leer.
Ein Datum mit deutscher Formatierung ausgeben (tt.mm.jjjj)?
Wobei String ein Attributwert sein kann oder auch ein komplexer, zusammengesetzter Ausdruck.
Das verwendete Zahlenformat ist die entsprechende Länder-Einstellung der Kontextsprache.
Einen Term verwenden?
Der Term wird in der Kontextsprache ausgegeben.
Der Term wird in der angegeben Sprache ausgegeben.
Was passiert, wenn ich einen Term in Attributen verwende, die kein mehrsprachiges Attribut sind?
Der Term wird leer zurückgegeben.
Was passiert bei einem leeren Term?
Konkret: TermID ist angelegt, aber Term-Wert leer: $TermId = '' ;
Terms die in einer bestimmten Sprache einen leeren String hinterlegt bekommen haben, benutzen den angelegten Fallback-Term.
Was passiert bei einer nicht existierenden TermID?
Falls ein Term ausgegeben werden soll welches nicht vorhanden ist, wird "null" wiedergegeben. Sprich, das Feld besitzt keinen Wert. (Nicht gleichzusetzen mit leerem Wert)
Was passiert bei einem generell nicht freigegebenen Term, bei fehlendem 2nd Approval oder wenn nur eine Sprache nicht freigegeben ist?
Es wird null zurückgegeben, angezeigt wird "null", da dieser Term noch nicht existiert.
Custom JS Functions
Die Custom JS Functions sind dazu da, um Kundenspezifische Funktionen in PIM einzufügen, welche mit Expressions ausgeführt werden können. Außerdem können lange Codeblöcke in einfache kurze Funktionen umgewandelt werden, welches Leistung spart, da hunderte Zeilen Codes in eine Zeile komprimiert werden. Ein weiterer Vorteil ist, dass bei überarbeitung der Funktion, alle Produktwerte automatisch angepasst werden. Das spart Zeit und Arbeitsaufwand.
Dieses Programm soll Zahlenbereiche z.B.: Elektrische Spannungen ausgeben, sollte einer der beiden Werte (Min oder Max) null sein, so wird es in nur einer Richtung angelegt (z.B: Maximal 8 Volt).
Es wird der Code Null Safe programmiert.
Beispiel:
return formatDecimalNumber(parseFloat(product.attributeValue('attributeIdMin')
+ '...' +
formatDecimalNumber(parseFloat(product.attributeValue('attributeIdMax')
} else if(product.attributeValue(attributeIdMin)== null){
return '...' +
formatDecimalNumber(parseFloat(product.attributeValue('attributeIdMax')
} else {
return formatDecimalNumber(parseFloat(product.attributeValue('attributeIdMin')
+ '...'
}
können Sie stattdessen als
in die Expression eingeben.
Um die Funktionen einzufügen, müssen Sie in der PIM - Oberfläche auf den Menüpunkt System -> Customization Area navigieren, um den File-Explorer zu öffnen.
Danach klicken Sie auf das “Datei erstellen”
Icon, danach müssen Sie “/integration/externalProduct/customJSFunctions.js” eingeben um die Datei zu erstellen.
Um die CustomJSFunctions einzufügen, müssen Sie die Datei bearbeiten.
Dazu müssen Sie ihren Code einfügen und laden diese hoch.
Spezifikationen und spezielle Fragen
Leere Attribute prüfen
Wie kann geprüft werden ob das Attribut leer ist?
1.null
product.attributeValue('AttributId') != null
2. Leere Strings
product.attributeValue('AttributId').toString() != ''
3. Ist ein Wert vorhanden
product.attributeValue('AttributId')String() != '';
Leere Basisdaten-Felder prüfen
Sie können prüfen ob Basisdaten-Felder leer sind indem folgendes in die Expression eingeben
Mehrwertige Attribute prüfen
Es kann grundsätzlich folgendes benutzt werden um zu prüfen ob ein Attribut mehrwertig ist, sollte das der Fall sein, wird dann eine Liste mit mehreren Elementen zurückgegeben.
Auf Werteliste prüfen
Wie kann geprüft werden ob es sich um eine Werteliste handelt?
Es kann hier die js-Abfrage:
kann in einer boolean Expression verwendet werden.
Anzahl der Attributwerte
Wie kann die Anzahl der Attributwerte abgefragt werden?
Um die Anzahl der Attributwerte herauszufinden, müssen Sie folgendes in die Expression eingeben:
das .toString() benötigen Sie nur, sobald Sie die Funktion als Expression in einem Attribut mit dem Typ String ausführen.
Mehrere Werte zu einem String verbinden
Nutzen Sie die Standard JavaScript "list" Funktion zusammen mit der Methode "filter".
Schritt 1: alle Wert in eine list Variable
Schritt 2: alle Einträge in der "list" Variable mit "filter" nacheinander durchlaufen und die Einträge mit "join" mit dem gewünschten Trennzeichen verknüpfen.
Beispiel:
product.attributeValue('AttributId','SprachId[optional]'),
product.attributeValue('AttributId2','SprachId[optional]'),
];
list.filter(Boolean).join('; ')
Listen als String ausgeben
Beispiel:
product.attributeValue('AttributId'),
product.attributeValue('AttributId2'),
product.attributeValue('AttributId3'),
product.attributeValue('AttributId4')
];
list.filter(Boolean).join('; ')
Kundeneigene JavaScript Funktionen verwenden
Sie können hiermit komplexe Typumwandlungen, Wert-Fehlerprüfungen, Zusammenstellungen von Werten usw. auf einen einfachen Funktionsaufruf reduzieren. Damit bleiben Expressions und Ausdrücke nutzbar für Anwender ohne Programmierkenntnisse.
Sie finden die entsprechende Datei dafür in der Customization Area unter
./integration/externalProduct/customJSFunctions.js
Typische Anwendungsfälle sind:
- die Arbeit mit textTable oder Markdown Feldern
- erweiterte Umwandlungsfunktionen von String in "echte" Dezimalfelder.
- das Zusammenfügen von Listenfeldern in einer langen String auf eine einheitliche Art
- das vereinfachen der Arbeit mit Terms mit dem Ziel lange und komplexe Ausdrücke zu vermeiden
Sprachkürzel/SprachId
Ein Wert der sich aus Sprache und "Dialekt" oder lokaler Ausprägung zusammensetzt. Die Kürzel sind im PIM hinterlegt. Die Kürzel sind von IETF normiert.
Beispiele:
de-DE: Deutsches Deutsch
de-AT: Österreichisches Deutsch
en-GB: Britisches Englisch
en-US: US-Amerikanisches Englisch
zh-ZH: Chinesisch (Festland)
zh-TW: Taiwanesisch
Troubleshooting
Fehlerhafte Expressions
Wird eine fehlerhafte Expression ausgeführt, wird dazu eine vom Fehler abhängige Meldung ausgegeben. In der entsprechenden Anwendungs-Logdatei wird die Exception ausgegeben.
Enthält eine gültige Expression einen Verweis auf eine fehlerhafte Expression, so wird die ganze Expression als fehlerhafte gewertet.
Term oder Attribut fehlt in einer Sprache (Fallback)
Fehlt ein Term oder Attributwert in einer bestimmten Sprache wird ein Fallback ausgegeben.In Fallbacks gibt es eine Reihenfolge, die abhängig von der Konfiguration auf die Terms/Werte einer anderen Sprache zurückgreift. Dieses Verfahren ist mehrstufig, das heißt dass die Reihenfolge der Sprachen konfigurierbar.
Jedoch ist es auch möglich einen Basiswert als Fallback anzulegen.
Beispiel mit Kontextsprache Spanisch:
Spanischer Wert nicht vorhanden → englischer Wert wird benutzt.
englische Übersetzung nicht vorhanden? → deutscher Wert wird benutzt.
deutsche Übersetzung nicht vorhanden? → null
Fehler: Datenfeld besitzt falschen Datentyp.
Die Expression wurde in einem “Boolean” Feld ausgeführt, welches nur ein Wahr/Falsch Wert ausgeben kann, nicht wie in diesem Fall benötigt, einen String.
Um den Fehler in Zukunft zu vermeiden, muss auf die vorhandenen, sowie auf die benötigten Datentypen geachtet werden
Fehler: Rekursion in der Expression
Eine Expression kann nicht auf sich selbst gestartet bzw. ausgeführt werden.
Mit der Expression
Geben Sie die ShortDescription eines Produktes als Expression aus. Diese darf aber nicht selbst im Datenfeld “Short Description” ausgeführt werden. Andere String-Datenfelder eignen sich dafür aber problemlos.
Fehler: Werteliste wird nicht ausgegeben
Wenn Sie versuchen ein Attribut mit einer Werteliste als Expression auszugeben kann es zu diesem Fehler kommen.
Das Attribut-Feld, dass Sie als Werteliste in einer Expression ausgeben möchten besitzt keine mehrwertige Werteliste. Um den Fehler zu beheben, müssen Sie ein Attribut-Feld auswählen, welches eine Werteliste besitzt.
Glossar
Im folgenden werden Wörter bzw. Begriffe genauer definiert und erklärt, die in der Dokumentation vorkommen.
Scope - Umfang bzw. Größe der Dokumentation
DAM - Digital Asset Manager
Kontext Sprache - Sprache des Inhaltes von PIM. Standardmäßig in Deutsch
FAQ - Frequently Asked Questions. Häufig gestellte Fragen
Troubleshooting - Sektion der Dokumentation in der häufig auftretende Fehler beschrieben und behandelt werden
Custom JS Function - Speziell angepasste Javascript Funktionen in PIM
Value - Wert/Inhalt eines Attributes
Term - Begriff, der in verschiedene Sprachen übersetzt werden kann
Expression - Ausdruck in PIM, der eine Funktion beschreibt die berechnet werden kann
Null Safe - Exception wird abgefangen, damit es zu keinem Programmabbruch kommt
Void - Es gibt keinen Rückgabewert
Rekursion - Selbstaufruf eines Ausdrucks
Fallback - Rückfall auf den Standardwert