documentation #82 Update documentation for new Metadata extension (ss…

…tok)

This PR was merged into the master branch.

Discussion
----------

|Q            |A  |
|---          |---|
|Bug Fix?     |no |
|New Feature? |no |
|BC Breaks?   |no |
|Deprecations?|no |
|Fixed Tickets|   |
|License      |MIT|

Commits
-------

688ff2f Update documentation for new Metadata extension
5bf08ae Move metadata-1.0.xsd to extension package

doc/installing.rst

@@ -45,23 +45,17 @@ Doctrine
 * `rollerworks/search-doctrine-orm`_ allows searching a relational SQL database using `Doctrine2 ORM`_.
 * `rollerworks/search-doctrine-dbal`_ allows searching a relational SQL database using `Doctrine2 DBAL`_.
 
-JmsMetadata
-^^^^^^^^^^^
+Metadata extension
+^^^^^^^^^^^^^^^^^^
 
-https://github.com/rollerworks/rollerworks-search-jms-metadata
+https://github.com/rollerworks/rollerworks-search-metadata
 
-Provides a :doc:`Metadata <metadata>` loader using the `jms/metadata`_ package.
-
-.. caution::
-
-    The ``jms/metadata`` package is licensed under the Apache2 licence
-    which is incompatible with GNU GPLv2 and up.
+Provides a :doc:`Metadata <metadata>` loader using the `rollerworks/metadata`_ package.
 
 .. _`Composer`: http://getcomposer.org/
 .. _`downloading Composer`: http://getcomposer.org/download/
-
 .. _`rollerworks/search-doctrine-orm`: https://github.com/rollerworks/rollerworks-search-doctrine-orm
 .. _`rollerworks/search-doctrine-dbal`: https://github.com/rollerworks/rollerworks-search-doctrine-dbal
 .. _`Doctrine2 ORM`: http://www.doctrine-project.org/projects/orm.html
 .. _`Doctrine2 dbal`: http://www.doctrine-project.org/projects/dbal.html
-.. _`jms/metadata`: https://github.com/schmittjoh/metadata
+.. _`rollerworks/metadata`: https://github.com/rollerworks/rollerworks-search-metadata

doc/metadata.rst

@@ -4,145 +4,18 @@ Metadata
 Class metadata is used by the ``FieldSetBuilder`` to populate a ``FieldSet`` instance
 field configuration with the metadata of a Model class.
 
-The information can be stored directly with the class using `PHP Annotations`_,
-or as a separate file using either YAML or XML.
+To actually use the metadata component you first need a compatible metadata loader.
 
-.. note::
-
-    To actually use the metadata component you first need a compatible
-    metadata loader.
-
-    One of the supported loaders is the `RollerworksSearch Jms-Metadata loader`_
-    which you need to install yourself.
-
-    See the 'JmsMetadata' subsection in :doc:`/installing/` for more information.
-
-    For this example the JmsMetadata loader is used.
-
-The ``FileLocator`` will try to guess the the metadata config-dir by
-matching the namespace prefix to the given Model class-name.
-
-In the example below the Model class ``Acme\Store\Model\Product``
-will be mapped to the ``src/Acme/Store/Resources/Rollerworks/Search/`` directory-namespace
-and tries to find the corresponding class-name ``Product`` as either ``Product.yml`` or
-``Product.xml``.
-
-.. code-block:: php
-
-    use Metadata\Driver\FileLocator;
-    use Metadata\Driver\DriverChain;
-    use Metadata\MetadataFactory;
-    use Doctrine\Common\Annotations\Reader;
-    use Rollerworks\Component\Search\Metadata\JmsMetadataReader;
-    use Rollerworks\Component\Search\Metadata\Driver as MetadataDriver;
-
-    $locator = new FileLocator(array(
-        'Acme\Store\Model' => 'src/Acme/Store/Resources/Rollerworks/Search/',
-        'Acme\User\Model' => 'src/Acme/User/Resources/Rollerworks/Search/',
-    ));
-
-    // You'd properly want to use one of the provided caches
-    // See: https://github.com/schmittjoh/metadata/tree/master/src/Metadata/Cache
-
-    $driver = new DriverChain(array(
-        new MetadataDriver\AnnotationDriver(),
-        new MetadataDriver\XmlFileDriver($locator),
-        new MetadataDriver\YamlFileDriver($locator),
-    ));
-
-    $metadataFactory = new JmsMetadataReader(new MetadataFactory($driver));
-    $searchFactory = new SearchFactory(..., $metadataFactory);
-
-.. configuration-block::
-
-    .. code-block:: php-annotations
+RollerworksSearch doesn't come bundled with a metadata loader, but
+you can use the `RollerworksSearch Metadata extension`_ as compatible metadata loader.
 
-        // src/Acme/Store/Model/Product.php
-
-        namespace Acme\Store\Model;
-
-        use Rollerworks\Component\Search\Metadata as Search;
-
-        class Product
-        {
-            /**
-             * @Search\Field("product_id", required=false, type="number")
-             */
-            protected $id;
-
-            /**
-             * @Search\Field("product_name", type="text")
-             */
-            protected $name;
-
-            /**
-             * @Search\Field("product_price", type="decimal", options={min=0.01})
-             */
-            protected $price;
-
-            // ...
-        }
-
-    .. code-block:: yaml
-
-        # src/Acme/Store/Resources/Rollerworks/Search/Product.yml
-        id:
-            # Name is the search-field name
-            name: product_id
-            type: number
-            accept-ranges: true
-            accept-compares: true
-
-        name:
-            name: product_name
-            type: text
-
-        price:
-            name: product_price
-            accept-ranges: true
-            accept-compares: true
-            type:
-                name: decimal
-                params:
-                    min: 0.01
-
-    .. code-block:: xml
-
-        <!-- src/Acme/Store/Resources/Rollerworks/Search/Product.xml -->
-
-        <?xml version="1.0" encoding="UTF-8"?>
-        <properties>
-            <property id="id" name="product_id">
-                <type name="number" />
-            </property>
-            <property id="name" name="product_name">
-                <type name="text" />
-            </property>
-            <property id="name" name="product_name">
-                <type name="text" />
-            </property>
-            <property id="price" name="product_price" accept-ranges="true" accept-compares="true">
-                <type name="text">
-                    <param key="min" type="float">0.01</param>
-                    <!-- An array-value is build as follow. Key and type are optional, type is required for collections -->
-                    <!--
-                    <option key="key" type="collection">
-                        <option type="string">value</option>
-                        <option type="collection">
-                            <value key="foo">value</option>
-                        </option>
-                    </option>
-                    -->
-                </type>
-            </property>
-        </properties>
-
-.. caution::
+.. note::
 
-    A class can accept only one metadata definition format.
+    The `RollerworksSearch JMS Metadata extension`_ is deprecated and will no longer
+    be supported in future versions.
 
-    For example, it is not possible to mix YAML metadata definitions with
-    annotated PHP class definitions.
+    You only need to update the PHP, all metadata already defined is still compatible.
+    But the ``required`` flag is no longer available and needs to be removed.
 
-.. _`PHP Annotations`: http://docs.doctrine-project.org/projects/doctrine-common/en/latest/reference/annotations.html
-.. _`RollerworksSearch Jms-Metadata loader`: https://github.com/rollerworks/rollerworks-search-jms-metadata
+.. _`RollerworksSearch Metadata extension`: https://github.com/rollerworks/rollerworks-search-metadata
+.. _`RollerworksSearch JMS Metadata extension`: https://github.com/rollerworks/rollerworks-search-jms-metadata