Merge pull request #68 from dantleech/xml_reference

Added an XML reference

en/index.rst

@@ -33,8 +33,8 @@ Mapping Objects onto a Document Repository
   :doc:`Hierarchies and References <reference/association-mapping>` |
   :doc:`Inheritance <reference/inheritance-mapping>`
 
-* **Mapping Driver References**: (TODO: build this in a sane way, without duplicating too much information)
-  :doc:`Docblock Annotations <reference/annotations-reference>` |
+* **Mapping Driver References**:
+  :doc:`Docblock Annotations <reference/annotations-mapping>` |
   :doc:`XML <reference/xml-mapping>` |
   :doc:`YAML <reference/yml-mapping>` |
   :doc:`Metadata Drivers <reference/metadata-drivers>`

en/reference/annotations-reference.rst → en/reference/annotations-mapping.rst

@@ -1,5 +1,5 @@
-Annotations Reference
-=====================
+Annotation Mapping
+==================
 
 In this chapter a reference of every PHPCR-ODM annotation is given with short
 explanations on their context and usage.

en/reference/xml-mapping.rst

@@ -0,0 +1,67 @@
+XML Mapping
+===========
+
+This chapter gives a brief overview of the XML mapping by example. In general,
+the attributes correspond to their annotation counterparts with the difference that
+the attribute names are slugified as opposed to being camelCase
+(``referring-document`` instead of ``referringDocument``). See :doc:`annotations-reference`.
+
+The following example implements all of the possible XML mapping elements:
+
+.. code-block:: xml
+
+    <doctrine-mapping xmlns="http://doctrine-project.org/schemas/orm/doctrine-mapping"
+        xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+        xsi:schemaLocation="https://raw.github.com/doctrine/doctrine2/master/doctrine-mapping.xsd">
+
+        <document name="Acme\Document\Example" referenceable="true" translator="attribute" versionable="simple">
+            <!-- Identification -->
+            <uuid name="uuid" />
+            <id name="path" />
+            <nodename name="name" />
+
+            <!-- Hierarchy -->
+            <parent-document name="parent" />
+            <children name="children" />
+            <child name="block" node-name="block" />
+            <depth name="depth" />
+
+            <!-- PHPCR -->
+            <node name="phpcrNode" />
+
+            <!-- Translation -->
+            <locale name="locale" />
+
+            <!-- Field mappings -->
+            <field name="title" type="string" translated="true" />
+            <field name="resourceLocator" property="resource-locator" type="string" translated="true" />
+            <field name="creator" type="long" translated="true" nullable="true" />
+
+            <!-- References -->
+            <reference-one name="anyDocumentReference"/>
+            <reference-one name="user" target-document="Acme\Document\User"/>
+            <reference-many name="articles" target-document="Acme\Document\Article"/>
+            <referrers name="tags" referring-document="Acme\Document\Tag" />
+            <mixed-referrers name="allReferrers" />
+
+            <!-- Versioning -->
+            <version-name name="versionName" />
+            <version-created name="versionCreated" />
+
+        </document>
+
+    </document>
+
+Mapped super-classes can be mapped as follows:
+
+.. code-block:: xml
+
+    <doctrine-mapping xmlns="http://doctrine-project.org/schemas/orm/doctrine-mapping"
+        xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+        xsi:schemaLocation="https://raw.github.com/doctrine/doctrine2/master/doctrine-mapping.xsd">
+
+        <mapped-superclass name="Acme\Document\Example" referenceable="true" translator="attribute" versionable="simple">
+            <!-- ... -->
+        </mapped-superclass>
+
+    </doctrine-mapping>