Podstawy pliku XML

Nie musisz być informatykiem, żeby poradzić sobie z importem plików XML!

Zdajemy sobie sprawę, że techniczne tematy potrafią być skomplikowane, dlatego przygotowaliśmy ten poradnik, aby w prosty sposób wyjaśnić, jak działa plik XML i jak korzystać z niego w FeedManagerze do importu produktów z hurtowni.

Ten artykuł nie zawiera wszystkich możliwych informacji o pliku XML, ale znajdziesz tu odpowiedzi na najczęstsze pytania, które mogą pojawić się w trakcie konfiguracji.

Masz inne pytanie? Skontaktuj się z nami przez czat lub napisz na help@redcart.pl!

Co to jest plik XML i jak jest zbudowany?

XML to język znaczników, a nie język programowania. Oznacza to, że nie posiada np. wbudowanych pętli. Jego głównym celem jest przechowywanie i przesyłanie danych w sposób zrozumiały zarówno dla człowieka, jak i dla komputera.

XML wymaga ścisłej struktury i poprawnej składni! Nawet drobne błędy, takie jak brak zamknięcia znacznika, mogą sprawić, że plik nie zostanie poprawnie odczytany.

Dane w XML są uporządkowane w formie hierarchii, która przypomina drzewo – są elementy główne i podrzędne.

Podstawowe elementy struktury pliku XML

1. Deklaracja XML - Zawsze na początku pliku. Informuje, że to plik XML.

   <?xml version="1.0" encoding="UTF-8"?>

2. Element główny (root) - Zawiera cały plik. W nim znajdują się wszystkie dane.

   <produkty> ... </produkty>

3. Elementy podrzędne - To w nich znajduje się każdy produkt, parametr, zdjęcie itd.

   <produkt>
       <nazwa>T-shirt</nazwa>
       <cena>49.99</cena>
   </produkt>

4. Atrybuty - Dodatkowe informacje w nawiasie przy nazwie elementu.

   <parametr nazwa="Kolor">Czarny</parametr>

5. Komentarze - Komentarze w XML są oznaczane w następujący sposób:

   <!-- To jest komentarz -->

Dzięki tej strukturze systemy (takie jak FeedManager) mogą łatwo “zrozumieć”, co jest czym w pliku np. która wartość to nazwa, cena, opis itp.

Pamiętaj, że każdy plik XML z hurtowni może wyglądać inaczej.

Nie ma jednej “poprawnej” odpowiedzi, jak zmapować pola w FeedManagerze. Wszystko zależy od tego, jak plik został przygotowany przez dostawcę.

Przechodząc krok po kroku przez naszą instrukcję, nauczysz się czytać strukturę pliku i rozpoznawać, co oznaczają poszczególne elementy. W razie trudności polecamy otworzyć plik XML w osobnej karcie (np. w przeglądarce lub edytorze tekstu). To znacznie ułatwia zrozumienie, który tag odpowiada za jaką informację.

Poniżej znajduje się uproszczony przykład struktury XML opisującej jeden produkt:

<produkt>
    <nazwa>T-shirt męski</nazwa>
    <opis>Bawełniany T-shirt z krótkim rękawem.</opis>
    <cena>49.99</cena>
    <waluta>PLN</waluta>
    <kategoria>Odzież>Męska>Koszulki</kategoria>
    <producent>ExampleBrand</producent>
    <kod_producenta>EX-TSHIRT-001</kod_producenta>
    <kod_ean>1234567890123</kod_ean>
    <stan_magazynowy>150</stan_magazynowy>
    <zdjecie>https://domena.pl/zdjecia/tshirt1.jpg</zdjecie>
    <parametry>
        <parametr nazwa="Kolor">Czarny</parametr>
        <parametr nazwa="Rozmiar">L</parametr>
    </parametry>
</produkt>

Tag główny

W pliku XML, który zawiera wiele produktów, każdy pojedynczy produkt jest opisany w osobnym tagu.

FeedManager musi wiedzieć, który dokładnie element oznacza tylko jeden produkt, aby poprawnie zaimportować dane.

Przykład:

<produktyzhurtowni>
    <produkty>
        <produkt id="4444">
            <nazwa>Smartfon XYZ</nazwa>
            <cena>999.99</cena>
            <opis>Nowoczesny smartfon z dużym ekranem</opis>
        </produkt>
        <produkt id="4445">
            ...
        </produkt>
    </produkty>
</produktyzhurtowni>

W tym przykładzie:

1. Tag główny całego pliku to: <produktyzhurtowni>

2. Tag, który otacza pojedynczy produkt, to: <produkt> (który znajduje się na liście produktów - tag <produkty>)

Aby poprawnie zmapować produkty w FeedManagerze, należy wskazać ścieżkę do tego tagu: produktyzhurtowni.produkty.produkt

Przykłady nazw głównych tagów

1. <produkt>

2. <item>

3. <offer>

4. <product> – wersja angielska tagu <produkt>

Co oznacza @ w mapowaniu?

W pliku XML dane mogą być zapisane na dwa różne sposoby: jako podtag albo jako atrybut. W FeedManagerze znak @ oznacza właśnie atrybut.

Przykład:

<produkt id="4684">
    <nazwa>Smartfon XYZ</nazwa>
    <cena>999.99</cena>
</produkt>

Jeśli widzisz coś takiego jak @id w mapowaniu to znaczy, że to atrybut, ponieważ znajduje się wewnątrz znacznika otwierającego, czyli: <produkt id="4684">.

Co oznacza # w mapowaniu?

Czasami, gdy mapujesz pole z pliku XML, możesz zobaczyć w FeedManagerze coś takiego jak np. name.#text. To oznacza, że w tagu znajduje się czysty tekst.

Przykład:

<name lang="pl">Laptop Lenovo IdeaPad 3</name>

1. <name> - Tag

2. lang="pl" - Atrybut, dodatkowa informacja w tym przypadku o języku

3. Laptop Lenovo IdeaPad 3 - Tekst, który znajduje się wewnątrz tego tagu.

name.#text oznacza, że z tagu zostanie pobrany tylko jego tekst, czyli zawartość między znacznikami, bez żadnych dodatkowych struktur.

Co oznacza CDATA w pliku XML?

CDATA to specjalny sposób zapisu treści w pliku XML, który mówi komputerowi, żeby traktować wszystko co jest w środku jako zwykły tekst, bez interpretacji tego jak kod. W plikach tego typu niektóre znaki, takie jak <, > czy &, mają szczególne znaczenie i są używane do oznaczania tagów i mogą zaburzyć poprawną strukturę pliku, jeśli pojawią się w nieodpowiednim miejscu.

<![CDATA[ Tutaj jest tekst!! ]]>

Podsumowanie

Teraz wiesz, czym jest plik XML, jak wygląda jego struktura oraz jak krok po kroku przygotować się do importu produktów w narzędziu FeedManager. Pamiętaj, że każdy plik XML może wyglądać nieco inaczej – dlatego tak ważne jest, aby dokładnie przeanalizować jego strukturę przed importem. Dzięki temu unikniesz błędów i przyspieszysz cały proces konfiguracji.