[OpenLayers-Dev] best practices in examples

Fri Sep 17 06:14:31 EDT 2010

Hi all,

Since tags are now being used by the search box, I would add the notice 
to provide comma-seperated tags for the respective example inside a div 
with id = "tags", e.g.:

<div id="tags">
             panning, animation, effect, smooth, panMethod
</div>

While going through the examples at the FOSS4G codesprint, I again 
realised that the presentation of the examples could possibly enhanced:

    * The search box should auto-suggest (and -complete), since only
      "full" matches will give results at all
    * maybe we could agree on certain standard tags like e.g.
      "basic"/"enhanced", ... to naturally group the examples by topics
    * The tags under the shortdesc of the examples on the left side
      should be clickable links, that do a search by the clicked tag
    * Every documentation file should include a link to the examples
      page that filters the examples by an appropriate keyword, so that
      when you are seeing the docs for OpenLayers.Layer.Google a link
      like "http://openlayers.org/dev/examples/?q=google" is included
    * That would of course mean that these URL params need to parsed by
      example-list.html
    * I would also provide the output of tools/exampleparser.py for
      every release (That means checking in example-list.js and
      example-list.xml). AFAICT one currently needs to build this file
      when you download an archive from the openlayers website. That way
      the search doesn't work for someone without further work to do.

BTW: the list of examples for the current stable release 
(http://dev.openlayers.org/releases/OpenLayers-2.10/examples/) only 
gives the directory listing instead of the example-list.html page. The 
current trunk example list (http://openlayers.org/dev/examples/) is 
working as expected. Shall I file a bug on this?

Just my two EUR-cents.

Regards,
Marc

On 16.09.2010 22:45, Tim Schaub wrote:
> Hey-
>
> We've gotten feedback over the last couple years about our examples 
> generating a bit of confusion.  Because, in general, we add to and do 
> not modify examples, we are not necessarily demonstrating 
> best-practices use of OpenLayers.
>
> In addition to getting rid of examples that demonstrate the use of 
> deprecated code, I think we should update existing examples in a 
> couple ways.  These are minor, but I think we should (at least) do the 
> following:
>
> * use <!DOCTYPE html> (xhtml is dead)
> * remove superfluous "/" attributes on elements that don't need a 
> closing tag (i.e. void elements like <br>, <link>, <img>, and <input> 
> don't have a closing tag)
> * include script tags at the end of the body
>
> Nothing urgent about this, but if folks want to provide patches for 
> the current example set, your contributions are welcome.
>
> http://trac.osgeo.org/openlayers/wiki/CodingStandards#WritingExamples
>
> Feedback welcome.
> Tim 

-------------- next part --------------
An HTML attachment was scrubbed...
URL: http://lists.osgeo.org/pipermail/openlayers-dev/attachments/20100917/c2535ebe/attachment-0001.html