Skip to end of metadata
Go to start of metadata

<ac:macro ac:name="unmigrated-inline-wiki-markup"><ac:plain-text-body><![CDATA[

<ac:macro ac:name="unmigrated-inline-wiki-markup"><ac:plain-text-body><![CDATA[

Zend Framework: Zend_Microformat Component Proposal

Proposed Component Name Zend_Microformat
Developer Notes http://framework.zend.com/wiki/display/ZFDEV/Zend_Microformat
Proposers Pádraic Brady
Matthew Weier O'Phinney (Zend Liaison)
Revision 1.0: Pending Community Review (wiki revision: 8)

Table of Contents

1. 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.

2. References

3. Component Requirements, Constraints, and Acceptance Criteria

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.

4. Dependencies on Other Framework Components

  • Zend_Http
  • Zend_Exception

5. Theory of 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.

6. Milestones / Tasks

  • 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

7. Class Index

  • Zend_Microformat
  • Zend_Microformat_Exception

Please see Zend_Microformat sub-proposals for additional classes in this namespace.

8. Use Cases

UC-01

Fetch a result object containing all supported Microformat data possible

UC-02

Fetch a result object containing only XFN data

UC-03

Fetch a result object containing only XFN data, and try again for hCard data

UC-04

Iterate across hCard results to list FN values

UC-05

Iterate across hCard results to list N values*

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.

UC-07

Create a new hCard, using Zend_Config

jbloggs.xml

9. Class 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.

]]></ac:plain-text-body></ac:macro>

]]></ac:plain-text-body></ac:macro>

Labels:
zend_webservices zend_webservices Delete
exception exception Delete
api api Delete
claims claims Delete
proposals proposals Delete
html html Delete
xml xml Delete
proposal proposal Delete
identity identity Delete
hcard hcard Delete
xfn xfn Delete
zend_microformat zend_microformat Delete
Enter labels to add to this page:
Please wait 
Looking for a label? Just start typing.
  1. Feb 05, 2008

    <p>This is pretty cool, and I am loving it already. <ac:emoticon ac:name="smile" /></p>

    <p>Now my question is - any plans to also "create" microformats? E.g. - let's say I want to spit out hcard, or generate xfn data? I know most if not all of the microformats are dead simple, but I guess it can never get too simple.</p>

  2. Feb 05, 2008

    <p>Hi Till,</p>

    <p>Yep, the plan is to also generate microformatted data as HTML/XHTML/XML. I'll be adding some use cases for those once I have a firmer fix on the range of inputs. I suspect Zend_Config will be present here, but I don't want to rule out leaving Zend_Config as a factory method input, with individual microformats having their own designated OO APIs for appending data.</p>

    <p>If necessary I'll make a few assumptions about a reasonable API for some use cases, and wait for my completion of Zend_Microformat_Xfn's proposal to visit specific APIs.</p>

  3. Feb 06, 2008

    <p>A few questions remaining:<br />
    How do you plan to actually make the result accessible? Is the result of Zend_Microformat::findAll() an array or a comfortable object tree with iterators and accessors (yes, I have a preference here :-P)?<br />
    Which microformats will be implemented in the first feature set?<br />
    How is the relation to Zend_Feed_*, as e.g. hAtom is pretty similiar and should maybe reuse the consumption objects?</p>

  4. Feb 06, 2008

    <p>To clarify this: Zend_Microformat_hAtom should maybe reuse some Zend_Feed-parts. That's what I wanted to say.</p>

  5. Feb 06, 2008

    <p>Hi Lars,</p>

    <p>I'll be working on those use cases today. My intention is probably your preference - a predominantly OO interface that is both iterable and countable. The result from findAll() will be a very simple object where the results are segregated as in:</p>

    <ac:macro ac:name="code"><ac:plain-text-body><![CDATA[
    $mf = new Zend_Microsoft('http://www.example.com');
    $mfs = $mf->findAll();
    $xfn = $mfs->xfn;
    foreach($xfn as $data) {
    // ...
    }
    ]]></ac:plain-text-body></ac:macro>

    <p>Once the use cases up, I'll wait for community comments and see what changes should be incorporated into my own initial pass.</p>

  6. Feb 06, 2008

    <p>Zend_Microsoft??? ROFL! I need to get off this laptop pronto...</p>

  7. Feb 06, 2008

    <p>After recovering from MS mentions...</p>

    <p>I have added several more Use Cases showing example uses of finding and using results from Microformat queries. I've also added some generation Use Cases. As noted in the proposal, these have no one specific style, and the OO accessor and generator depends entirely on the specific Microformat in use. For consistency, these new uses cases assume we're using hCard.</p>

  8. Feb 08, 2008

    <p>Brilliant, looks very cool! I've been tinkering with microformats and the opening of the social graph lately. Thought about starting/joining a proposal for building a FOAF parser for ZF. Could do well with Microformats, particularly XFN.</p>

    <p>Any knowledge of existing proposals/suggestions to do this in ZF?</p>

    1. Feb 09, 2008

      <p>Hi Joakim,</p>

      <p>I'm not aware of any FOAF component proposals. At present I'm just parsing FOAF using DOM though I certainly wouldn't mind a wrapper implementation. Perhaps you should propose it? <ac:emoticon ac:name="wink" /> At the moment I'm implementing a blog aggregator which is using hCard and XFN to express aggregated blogger details from the front page or individual (optional) bios. I will be using FOAF as the initial storage vehicle for those since it supports a more centralised offline medium.</p>

      <p>You have my vote...<ac:emoticon ac:name="wink" /></p>

  9. Feb 08, 2008

    <p>I'm very interested to see this develop; I use microformats all over the place in my projects.  One thing, though...the proposal indicates that this class can be used to programatically generate and output microformatted HTML/XHTML; this is a great idea, but how will the output format be decided upon?</p>

    <p>For instance, I have lots of uses for hCards in my applications, but the particular elements used and the order in which they occur vary considerably.  I might mark up a user profile with hCard on one page listing several profiles, each in its own row of a table, and then on another page listing just that one profile on its own, inside a <div>.  And then at the bottom of all of those pages I might have an <address> hCard listing contact information for the site owners.</p>

    <p>In thinking about this, the decorator chains from Zend_Form came to my mind; could something similar be implemented here, allowing developers to specify their own templates without taking away whatever sensible defaults might otherwise be provided?</p>

    1. Feb 09, 2008

      <p>Hi Adam,</p>

      <p>The initial development will get around to keeping the data element isolated, so from there I suspect that there will be decoration involved and I've also added a blank proposal for a future Zend_View_Helper_Microformat. I'm applying TDD here so I haven't reached an implementation yet - though since I need some of this pretty quickly you can bet the proposals for XFN and hCard will end up with something you can comment on soon.</p>

  10. Jun 02, 2008

    <ac:macro ac:name="note"><ac:parameter ac:name="title">Zend Comments</ac:parameter><ac:rich-text-body>
    <p>The Zend Framework team approves this proposal for immediate development in the<br />
    extras incubator. We have the following notes and suggestions:</p>

    <ul>
    <li>Overloading of properties<br />
    The examples show usage like thie following:
    <ac:macro ac:name="code"><ac:default-parameter>php</ac:default-parameter><ac:plain-text-body><![CDATA[
    $hcard->n->honorific-prefix = 'Mr';
    ]]></ac:plain-text-body></ac:macro>
    which will result in parse errors, as PHP does not allow dashes in variable names. I suggest using Zend_Filter_Inflector to inflect camelCase to dash-separated internally. This will allow the component to follow ZF guidelines for variable naming, as well as retain the semantic link to the underlying specification.</li>
    <li>Utilize iterators where reasonable<br />
    A number of comments indicate that they would like results returned as an iterator. Our recommendation is to use iterators if they make sense to the design, but not require them out of necessity.</li>
    <li>Aggregate data<br />
    In the XFN proposal, he has a use case like the following when generating an XFN microformat:
    <ac:macro ac:name="code"><ac:default-parameter>php</ac:default-parameter><ac:plain-text-body><![CDATA[
    $xfn->relations = array('friend', 'met', 'neighbor');
    ]]></ac:plain-text-body></ac:macro>
    We suggest that accessors for adding the relations would be useful:
    <ac:macro ac:name="code"><ac:default-parameter>php</ac:default-parameter><ac:plain-text-body><![CDATA[
    $xfn->addRelation('friend')
    ->addRelation('met')
    ->addRelation('neighbor');
    $xfn->addRelation('friend')>addRelation('met')>addRelation('neighbor');
    ]]></ac:plain-text-body></ac:macro>
    This would allow for programmatic creation of the format, and if similar accessors were created for retrieving, testing existence of, and removal of the relations, this could be even more powerful.</li>
    <li>Use Accessors<br />
    Most use cases show using public properties (either via overloading or direct use) to set and/or retrieve information. However, this does not allow for easy testing of existence, like the following:
    <ac:macro ac:name="code"><ac:default-parameter>php</ac:default-parameter><ac:plain-text-body><![CDATA[
    if ($hcard->hasNickname()) {
    }
    if ($hcard->hasNickname()) {
    }
    ]]></ac:plain-text-body></ac:macro>
    While I do not want to discourage using either overloading or public properties, accessors would allow for better control over the data provided (allowing normalization or error reporting), as well as for methods such as the above for testing existence of data.</li>
    <li>View Helpers<br />
    A view helper for generating microformat information to embed in the view should be considered part of the proposal.</li>
    </ul>
    </ac:rich-text-body></ac:macro>

  11. Mar 18, 2009

    <p>Paddy, status?</p>

  12. Oct 20, 2010

    <p>This would be really nice to have in ZF.</p>