Atom 1.0

24. dubna 2006

•

Poskytování obsahu prostřednictvím RSS se už dávno stalo běžným prvkem webů, které často přidávají nový obsah. Variantou k rozšířenému RSS je formát Atom. Cílem autorů formátu Atom bylo přímo nahrazení stávajících RSS formátů. Prostředkem k dosažení tohoto cíle se stal logický návrh vycházející ze zkušeností s RSS. V létě 2005 Atom dospěl k „dospělé“ verzi 1.0.

Co je Atom

Atom je standardizovaný XML formát určený k poskytování obsahu na webu. Stejnému účelu slouží známější formát RSS. V prosinci 2005 byl Atom publikován jako RFC 4287. Informace obsažené v dokumentech Atom mohou uživatelé číst v desktopových nebo on-line čtečkách, nebo mohou být prostřednictvím Atom API zpřístupněné dalším aplikacím. V tomto článku najdete popis Atom verze 1.0.

Podobně jako RSS, je i Atom podmnožinou XML. Pro formát Atom tedy platí stejná obecná pravidla jako pro XML. Pro Atom dokumenty platí:

Dokumenty Atom musí být well-formed XML dokumenty.
Musí být označeny MIME typem application/atom+xml.
Všechny elementy musí být součástí jmenného prostoru Atom.
Hodnoty se zapisují jako prostý text.
Časy se zapisují podle RFC 3339.

Příklad ukazuje minimální obsah Atom souboru:

<?xml version=“1.0″ encoding=“utf-8″ ?>
<feed xmlns=“http://www.w3.org/2005/Atom“>
<title>Example.com</title>
<link href=“http://www.example.com/“/>
<updated>2006-04-06T20:30:34+01:00</updated>
<author>
<name>Jiří Bureš</name>
</author>
<id>urn:uuid:123-456-789</id>
<entry>
<title>Formát Atom 1.0</title>
<link href=“http://www.example.com/2006-04-06/atom.htm“/>
<id>urn:uuid:123-456-a72</id>
<updated>2006-04-06T20:30:34+01:00</updated>
<summary>Stručný popis článku</summary>
</entry>
</feed>

Z ukázky je patrná jednoduchá struktura Atom dokumentu:

dokument začíná informací o verzi XML a použitém kódování
Atom dokument je uzavřen do právě jednoho elementu feed
následují informace o Atom dokumentu (elementy title, link, updated a author)
informace o jednotlivých položkách jsou vnořeny do elementu entry

Povinné elementy

<feed>: Element nejvyšší úrovně. Atom zdroj obsahuje právě jeden kořenový element feed.

Element feed

<id>: Jednoznačně identifikuje zdroj pomocí trvalé URI.
<title>: Název Atom zdroje v lidsky čitelné podobě (měl by odpovídat názvu zdroje – většinou názvu daného webu). Rodičovský element feed musí obsahovat právě jeden element title.
<updated>: Čas poslední změny daného Atom zdroje.

Element entry

Příkladem entry (česky „záznam“) je například spot na blogu nebo článek na zpravodajském webu.

<id>: Jednoznačná neměnná identifikace záznamu, trvalé URI.
<title>: Nadpis v lidsky čitelné podobě. Nadpis by neměl být prázdný.
<updated>: Čas, kdy byl daný záznam naposledy významně změněn (tedy ne po opravě překlepů a podobně). Časové údaje Atom kanálů musí být v souladu s W3C Date and Time Formats. Časový údaj by měl obsahovat informaci o časové zóně.

Doporučené elementy

Element feed

<author>

Každý Atom kanál by měl obsahovat alespoň jeden element author. Má vnořený povinný element name a může mít také vnořené elementy uri a email:

<email>: Součást elementu author. E-mailová adresa autora (RFC2822).
<name>: Jméno autora (případně firmy a podobně) v lidsky čitelné podobě, musí být řetězec.
<uri>: Součást elementu author. Obsahuje URI (RFC2396) spojené s autorem.

<link>

Související webová stránka. Povinně obsahuje atribut href a dalších pět atributů nepovinných.

Element entry

<author>

Jméno autora záznamu. Přitom jeden záznam může mít více autorů. Pokud je autorem záznamu jiný autor, než je autor uvedený v rodičovském elementu feed nebo ve zdroji odkazovaném v elementu source, musí záznam obsahovat element author.

<content>

Úplný obsah daného záznamu nebo odkaz na něj. Element content je povinný, pokud není v elementu entry uveden element summary nebo alternate.

Může obsahovat atribut type, který obsahuje jednu z hodnot text (obsah elementu je prostý text, je to výchozí hodnota), html (element může obsahovat HTML značky zapsané s využitím HTML znakových entit) nebo xhtml (ve vnořeném div elementu mohou být vedle HTML znakových entit také být řádkové XHTML značky). Podobně může být atribut type použit v elementech title, summary a rights.

<link>

Element link určuje související webovou stránku. Obsahuje atributy:

href – URI (RFC2396) daného záznamu (povinný atribut)
hreflang – jazyk zdroje
length – délka zdroje v bytech
rel – typ vztahu (vedle jiných právě jeden s hodnotou alternate na daný type a hreflang atribut; dále může obsahovat tyto hodnoty: enclosure, related, self, via)
title – popisek v lidsky čitelné podobě
type – typ media podle RFC2045

<summary>

Krátké shrnutí nebo citát daného záznamu. Element summary použijte, pokud záznam neobsahuje content nebo je kódován v base64 případně obsahuje atribut src.

Nepovinné elementy

Element feed

<category>

Kategorie zdroje. Element má jediný povinný atribut term. Dále může obsahovat atributy scheme (pomocí URI odkazuje na použité schéma) a label (obsahuje zobrazovaný lidsky čitelný popisek).

<category term="sport"/>.

<contributor>

Přispěvatel do daného zdroje. Element feed může obsahovat jeden nebo více elementů contributor. Element má další vnořené elementy jako element author.

<generator>

Řetězcová identifikace aplikace použité pro generování Atom zdroje v lidsky čitelné formě. V elementu feed se vyskytuje nejvýše jednou. Může obsahovat atributy:

uri – URI odkazující na generátor
version – verze generátoru

<icon>

Malý obrázek (ikona) zdroje nejlépe ve tvaru čtverce: <icon>/images/ikona.gif</icon>.

<logo>

Větší obrázek zdroje, který by měl mít dvojnásobnou šířku než výšku: <logo>/images/logo.gif</logo>.

<rights>

<subtitle>

Titulek, tedy podrobnější popis zdroje.

Element entry

<category>: Obdobný význam i formát jako element category ve feed.
<contributor>: Přispěvatel do daného záznamu. Element entry může obsahovat jeden nebo více elementů contributor. Zapisuje se jako stejnojmenný element ve feed.
<published>: Čas vytvoření nebo zveřejnění (dostupnosti) daného záznamu.
<source>: Element se používá, pokud je záznam kopírován z jednoho kanálu do jiného.
<rights>: Autorská práva k danému záznamu v lidsky čitelné formě.

Jak vytvořit Atom

Atom je XML dokument se vším, co k tomu patří. Mimo jiné se tedy jedná o prostý textový dokument (doporučená koncovka .atom, často se ale používá název souboru atom.xml). A jak takový dokument autor vytvoří, je na něm. Může jeho obsah editovat ručně ve vhodném textovém editoru, nebo může dokument generovat automaticky (například pomocí PHP z databáze a podobně).