View Source

<ac:macro ac:name="unmigrated-inline-wiki-markup"><ac:plain-text-body><![CDATA[{zone-template-instance:ZFDEV:Zend Proposal Zone Template}

{zone-data:component-name}
Zend_Microformat
{zone-data}

{zone-data:proposer-list}
[Pádraic Brady|mailto:padraic.brady@yahoo.com]
[Matthew Weier O'Phinney (Zend Liaison)|~matthew]
{zone-data}

{zone-data:revision}
1.0: Pending Community Review
{zone-data}

{zone-data:overview}
Designed for humans first and machines second, microformats are a set of simple, open data formats built upon existing and widely adopted standards. Instead of throwing away what works today, microformats intend to solve simpler problems first by adapting to current behaviors and usage patterns (e.g. XHTML, blogging).

Zend_Microformat will form the backbone of a set of both compound and elemental microformats implemented and proposed separately (so anyone else can take part in the fun!). The initial microformat targeted for implementation is the XHTML Friends Network (XFN) microformat. Should this proposal be accepted into the Zend Framework, subsequent proposals will be made for many others.

The purpose of the core Zend_Microformat component is to act as an overall URL fetcher and parser which targets any desired microformat to be parsed from the resulting HTML/XHTML and returned in a more specific collection object per microformat. The same will be achievable using the sub-components for each microformat, but having a central utility class just offers more consistency to the overall API.
{zone-data}

{zone-data:references}
* [About Microformats|http://microformats.org/about/]
* [Microformats.org Wiki|http://microformats.org/wiki/]
* [Zend_Microformat_Hcard Proposal|http://framework.zend.com/wiki/pages/viewpage.action?pageId=42388]
{zone-data}

{zone-data:requirements}
These requirements are subject to modification pending community review and my own personal whims (which is what you get for reading something marked Under Construction ;)).

* This component *will* provide central responsibility for fetching URLs, and managing the parsing and formation of collection objects, for the selected microformat.
* This component *will* be used to enforce a relatively common API across all sub-components. Reasonably, because each microformat has it's own unique requirements.
* This component *may* act as a anchor point for a microformat factory method.
* In general, this component (or its sub-components) *will* allow for both the parsing of, and generation of, microformat XHTML, HTML and XML.
* Where relevant, this component *will* delegate to other Zend Framework components should it prove a path of least resistance.
{zone-data}

{zone-data:dependencies}
* Zend_Http
* Zend_Exception
{zone-data}

{zone-data:operation}
The core Zend_Microformat component is not intended to prove a huge overarching presence. Instead it's a focal point for common functionality required for all microformats. A simple operation would involve using Zend_Microformat to fetch (using Zend_Http) a URL, cache the resulting XHTML/HTML/XML, and subsequently parse the cached output for one or more collections of microformat data.

Where sub-components for specific microformats are utilised, Zend_Microformat will be utilised via composition. There is no intent for Zend_Microformat to include static methods which enable Zend_Http instance reuse since URL results are temporarily cached for any subsequent operations.
{zone-data}

{zone-data:milestones}
* Milestone 1: Assemble some initial use cases to explore desired API
* Milestone 2: Commence proof-of-concept coding (will discard after)
* Milestone 3: Pending review, complete initial development using TDD
* Milestone 4: Complete acceptance testing, verify unit test coverage
* Milestone 5: Let's assume documentation is written during development
{zone-data}

{zone-data:class-list}
* Zend_Microformat
* Zend_Microformat_Exception

Please see Zend_Microformat sub-proposals for additional classes in this namespace.
{zone-data}

{zone-data:use-cases}
|UC-01|
*Fetch a result object containing all supported Microformat data possible*
{code}$mf = new Zend_Microformat('http://www.example.com');
$results = $mf->findAll();{code}

|UC-02|
*Fetch a result object containing only XFN data*
{code}$mf = new Zend_Microformat('http://www.example.com');
$results = $mf->find('xfn');{code}

|UC-03|
*Fetch a result object containing only XFN data, and try again for hCard data*
{code}$mf = new Zend_Microformat('http://www.example.com');
$xfnResults = $mf->find('xfn');
$hcardResults = $mf->find('hcard');{code}

|UC-04|
*Iterate across hCard results to list FN values*
{code}$mf = new Zend_Microformat('http://www.example.com');
$hcards = $mf->find('hcard');
echo 'Located ', count($hcards), ' hCard(s):', PHP_EOL;
foreach($hcards as $hc) {
echo $hc->fn, "\n";
}{code}

|UC-05|
*Iterate across hCard results to list N* values*
{code}$mf = new Zend_Microformat('http://www.example.com');
$hcards = $mf->find('hcard');
echo 'Located ', count($hcards), ' hCard(s):', PHP_EOL;
foreach($hcards as $hc) {
echo $hc->n->nickname, PHP_EOL;
echo $hc->n->url, PHP_EOL;
echo $hc->n->tel, PHP_EOL, PHP_EOL;
}{code}

|UC-06|
*Create a new hCard, and generate HTML markup for embedding*

Note that hCard FN and N properties are required under the hCard specification.

{code}$mf = new Zend_Microformat;
$hcard = $mf->new('hcard');
$hcard->fn = 'Joe Bloggs';
$hcard->n->nickname = 'jbloggs';
$hcard->n->honorific-prefix = 'Mr';
$hcard->n->given-name = 'Joe';
$hcard->n->family-name = 'Bloggs';
echo $hcard->generate();{code}

|UC-07|
*Create a new hCard, using Zend_Config*

jbloggs.xml
{code}<?xml version="1.0"?>
<configdata>
<hcard>
<fn>Joe Bloggs</fn>
<n>
<nickname>jbloggs</nickname>
<honorific-prefix>Mr.</honorific-prefix>
<given-name>Joe</given-name>
<family-name>Bloggs</family-name>
</n>
</hcard>
</configdata>{code}

{code}$config = new Zend_Config_Xml('./jbloggs.xml', 'hcard');

$mf = new Zend_Microformat;
$hcard = $mf->new('hcard', $config);
echo $hcard->generate();{code}

{zone-data}

{zone-data:skeletons}
Please see the above use cases. Based on these, source code will be developed following Test-Driven Development and therefore class skeletons will not be presented in this proposal prematurely. The TDD process will implement Zend_Microformat specifically to enable the use cases presented above.
{zone-data}

{zone-template-instance}]]></ac:plain-text-body></ac:macro>