Muotoile ja sisennä XML

XML-muotoilu (tunnetaan myös nimillä XML-asettelu, XML-sisennys tai pretty print) tarkoittaa tiiviin tai minifioidun XML-asiakirjan uudelleenjärjestämistä sisennettyyn rakenteeseen, joka on luettavissa rivi riviltä. Hyvin muotoiltu XML parantaa ihmisen luettavuutta, mikä on välttämätöntä, kun on luettava SOAP-vastausta, selattava RSS-syötettä tai tarkastettava konfiguraatiotiedoston sisältöä.

Käytännössä XML muotoillaan neljästä pääsyystä:

• Vianetsintä: sulkemattoman tagin, puuttuvan attribuutin tai epäloogisen rakenteen nopea havaitseminen.
• Manuaalinen integrointi: fragmentin siisti kopiointi konfiguraatiotiedostoon rikkomatta olemassa olevaa sisennystä.
• Koodin katselmointi: kahden XML-asiakirjan version vertaileminen Git-diffissä muuttuu luettavaksi, kun jokainen tagi on omalla rivillään.
• Dokumentaatio ja esimerkit: muotoiltu XML on paljon opettavaisempi teknisessä dokumentaatiossa tai README-tiedostossa.

XML on edelleen kaikkialla ohjelmistoekosysteemissä. Tässä ovat muodot, joissa kehittäjät käyttävät useimmin XML-muotoilijaa:

• SOAP-vastaukset: SOAP-verkkopalveluiden palauttamat <soap:Envelope>-kuoret saapuvat yleensä minifioituina.
• RSS- ja Atom-syötteet: syndikaatiosyötteen tarkastamiseen tai auditointiin.
• Spring-, Maven (pom.xml)-, Ant-, Ivy-konfiguraatiot: Java-koontitiedostot ja riippuvuustiedostot.
• AndroidManifest.xml ja muut Android-projektin XML-resurssit.
• SVG-tiedostot: suunnitteluohjelmistosta viety vektorikuva on usein pakattu yhdelle riville.
• Verkkokaupan viennit: Google Shopping -tuotesyötteet, Magento-, Shopify- tai PrestaShop-viennit.
• OOXML-asiakirjat: .docx-, .xlsx- ja .pptx-tiedostot ovat ZIP-arkistoja, jotka sisältävät XML-tiedostoja, joita on usein tarkastettava.
• XML-sivustokartat: hakukoneille tarjottavat sitemap.xml-tiedostot.

XML-muotoilija ei vain lisää välilyöntejä sattumanvaraisesti. Se suorittaa kaksi vaihetta:

1. Jäsennys: asiakirja luetaan ja muunnetaan DOM-puuksi (Document Object Model). Tämä vaihe varmistaa myös, että XML on oikein muotoiltu (tagit oikein sisäkkäin, attribuutit lainausmerkeissä, vain yksi juurielementti).
2. Sisennetty serialisointi: DOM-puu lähetetään uudelleen tekstimuodossa rivinvaihtojen kera elementtien välillä ja sisennys on suhteessa puun syvyyteen.

Tämä puupohjainen lähestymistapa takaa, että asiakirjan looginen rakenne pysyy täsmälleen samana: vain tagien välisiä merkityksettömiä välilyöntejä muutetaan. CDATA-osiot, kommentit ja käsittelyohjeet säilytetään. Edistyneemmät muunnokset (XSLT) tai kyselyt (XPath) toimivat muuten samalla DOM-puulla.

Toimintatapa on tarkoituksella yksinkertainen:

1. Liitä XML-asiakirjasi tekstialueelle tai lataa .xml-tiedosto.
2. Vahvista lomake: asiakirja analysoidaan ja sisennetään automaattisesti.
3. Muotoiltu tulos ilmestyy tulosalueelle. Jos jäsennyksessä tapahtuu virhe, viesti ilmoittaa ongelman laadun ja likimääräisen sijainnin.
4. Kopioi tulos siihen tarkoitetulla painikkeella tai lataa se integroidaksesi sen suoraan projektiisi.

Muutamia noudatettavia käytäntöjä siistin ja kestävän XML:n tuottamiseksi:

• Sisennys: 2 tai 4 välilyöntiä tiimisi käytännön mukaan. Pysy johdonmukaisena koko projektissa.
• Rivinvaihdot: yksi elementti per rivi, mikä tekee Git-diffeistä hyödyllisiä.
• CDATA-osiot: hyvä muotoilija säilyttää <![CDATA[ ... ]]> -lohkot kokonaisuudessaan ilman niiden sisällön uudelleensisennystä, koska ne käsitellään raakatekstinä.
• Koodaus: ilmoita koodaus aina ensimmäisellä rivillä: <?xml version="1.0" encoding="UTF-8"?>. UTF-8 on tosiasiallinen standardi.
• Attribuutit: jos elementillä on paljon attribuutteja, jotkut tiimit laittavat ne eri riveille luettavuuden vuoksi; muuten ne pysyvät samalla rivillä kuin avaava tagi.
• Kommentit: muotoilijan on säilytettävä <!-- ... --> sellaisenaan.

Tässä on konkreettinen esimerkki muotoilijan kaunistamasta tiiviistä XML:stä.

Ennen (yksi rivi, lukukelvoton):

<root><item id="1">val</item><item id="2">val2</item></root>

Jälkeen (muotoiltu 2 välilyönnillä):

<?xml version="1.0" encoding="UTF-8"?>
<root>
  <item id="1">val</item>
  <item id="2">val2</item>
</root>

Looginen rakenne on täsmälleen sama: vain visuaalinen asettelu muuttuu.

Suurempi XML-asiakirja näyttää muotoilun jälkeen tältä:

<?xml version="1.0" encoding="UTF-8"?>
<root>
  <user id="12345">
    <name>John Doe</name>
    <email>johndoe@example.com</email>
    <address>
      <street>123 Main St</street>
      <city>Springfield</city>
      <state>IL</state>
      <postalCode>62704</postalCode>
      <country>USA</country>
    </address>
    <phoneNumbers>
      <phoneNumber type="home">555-1234</phoneNumber>
      <phoneNumber type="work">555-5678</phoneNumber>
    </phoneNumbers>
    <preferences>
      <newsletter>true</newsletter>
      <theme>dark</theme>
    </preferences>
    <lastLogin>2024-06-14T09:30:00Z</lastLogin>
  </user>
</root>