[OpenLayers-Dev] best practices in examples

Fri Sep 17 06:48:07 EDT 2010

On Sep 17, 2010, at 6:14 AM, ext Marc Jansen wrote:

> 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

Is this different from the #3 immediately previous?

> 	• 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?

This is basically expected; we never added 'run exampleparser.py' to the build
process. If you want to file a bug on it, there's a 'release.sh' or something
like it in tools that is used to build releases; if we update that tool, I'm
happy to build future releases that way, and also rebuild it for the existing
releases for which it matters.

-- Chris

> Just my two €-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
> 
> <ATT00001..txt>