Register | Log in

Mozilla.com

  1. Project:en
  2. ExampleExtension
Table of contents
  1. 1. User Experience
    1. 1.1. Needs (Editor)
    2. 1.2. Needs (Viewing)
  2. 2. Administrator Experience
    1. 2.1. Needs (Security)
    2. 2.2. Needs (UI)
  3. 3. MediaWiki
    1. 3.1. Needs (Edits)
  4. 4. Syntax
    1. 4.1. In-Page
    2. 4.2. In-Article-Linking
    3. 4.3. Template
      1. 4.3.1. Basic
    4. 4.4. Magic Char Usage
    5. 4.5. Content Library

ExampleExtension

For those who may stumble upon this article by accident, this is not an article describing a Firefox, Thunderbird or otherwise "Extension". It is an Extension for MediaWiki to allow wiki-driven working examples and/or samples. This will allow much of the burden to be taken off of dria. And more samples and working examples to be written.

This document will describe the needs on all ends of an "ExampleExtension". The reason for this is to ensure that all angles are thought out prior to the beginning of work for it.

SourceViewExtension, CodeExampleExtension - other possible names

User Experience

Needs (Editor)

  • There needs to be a way to utilize a template for an example, to minimize extrenuous work in creating them. (For example, a specific template for <canvas> example use (so we only need to provide the JS code).
  • There needs to be a way to create an example "in-page" (as in with surrounding text <example>...</example>
  • The learning curve for utilizing this should be small, and intuitive.
  • There should be a way to specify the example to additionally appear in-page (as in, current <pre> tags)
    • Optionally limiting the output to a 'section' of the example.
  • There needs to be a way to specify xyz alternate page as "part" of the example, while still hiding it from the real source. (For examples that need external linkage, ie. Images, <link>ed CSS, etc.)
  • Need to be able to specify mime type to use (for XUL, for CSS, for HTML vs XHTML, etc.)

Needs (Viewing)

  • There needs to be links to "working" versions of the example.
    • Should the links work for "all" versions of the example (as is currently designed, aka newest) or only to the version initially linked to [using a specific rcid]?
  • There needs to be links to "Full" source of each example.
  • UI must not surprise a person browsing MDC, as in, he/she must not click on an example link expecting something other than a "working" example to appear.
  • There should be an apparant way to edit a live example (possibly via template syntax links)
  • A download link to the file - eg some XUL examples will only run on local machine
  • Syntax highlighting eg with GeSHi - Generic Syntax Highlighter
  • May be required in a popup or chrome window (XUL tutorial is a good example)
  • May need to execute server side code (eg some php)

Administrator Experience

Needs (Security)

  • There needs to be a way to disallow all examples from being able to be run. (Incase of a major security flaw with this extension. To try and allow a quick 'disable' without spontaneously breaking all pages which use <example>)
  • There needs to be a way to audit created examples.
    • Possible Solutions include, Whitelisting selective examples, Blacklisting selective examples, Automatic Whitelists for "groups" of users, Automatic Whitelists for users with xyz number of wiki changes, Automatic Blacklists for users ever blocked, etc.
  • Possible desire to whitelist/blacklist selective mime-type attempts.

Needs (UI)

  • Should be straightforward, (minimal learning curve, to allow new sysops/admins to have an easy time manipulating settings).
  • Probably Administration to be performed on its own Special: page.
  • Provide a "Recently Changed Examples", with easy options to "Approve" or "Deny" this example with an optional reason.

MediaWiki

Needs (Edits)

  • Edits to core MediaWiki software should be as minimal as possible, to make ease of update easier, and to ensure as few problems with future versions of MediaWiki as possible. (This extension should be an extension in every way possible, with as few MediaWiki changes as humanly possible).
  • Where Edits are needed, if possible, create MediaWiki hooks instead of "in-spot changes" (Hooks can potentially be backported to MediaWiki itself.

Syntax

In-Page

In-Page syntax will likely be the most common. (For samples which use a template please see the Template section below). This is entirely subject to change, and is simply what I (Callek) have in mind currently. 

<example mime="text/html">
   <html>
   <head><title>Hello World</title></head>
   <body><p>Hello World!</p></body>
   </html>
</example>

<example template="DOM" magic-char="%" mime="does not matter">
%HTML%
<p id="sample">This is some text</p>
%/HTML%
%JS%
document.getElementById("sample").style = "color:blue;";
%/JS%
</example>

In this example, the Mime-type will be taken from the template, and teh one specified here ignored. magic-char can be defaulted if ommitted.

In-Article-Linking

(Link to Other Page Example) 

<example-link exId="ExampleID" href="wiki-page"></example-link>

the "exampleId" must be specified in the target page. (Using standard 'id' attribute). (exId may be omitted if there is only one example on the page).

Template

Templates should be as straightforward as possible. Making creating/editing and using them as easy as can possibly be.

Basic

Template:Examples:Basic 

<example-template mime="text/html">
<html>
  <head><title>Basic HTML Example</title></head>
  <body>
     %content%
  </body>
</html>
</example-template>

(A page using the template) 

<example template="Basic">
<p>Hello World!</p>
</example>

(potential Output) 

<html>
  <head><title>Basic HTML Example</title></head>
  <body>
     <p>Hello World!</p>
  </body>
</html>

Magic Char Usage

Declaring the Magic Char 

<example-template magic-char="%">

(not needed if chosen to use the default magic char)

Uses: 

%content%

Inserts any "non-blocked" content here, similar to the XBL <content /> 

%block name="Foo"%

creates a block; Will insert text from original example when it is surrounded by %Foo% and %/Foo% (like HTML construction). 

%change-magic char="^"%
^some-Magic-Declaration^
^change-magic char="%"^

Key thing to note, the magic declaration must be ended with the _original_ magic character.

Error Condition:

  • Unknown Magic Declarations are discarded and ignored.

Content Library

One other possibilty is to create a library of content that can be used across projects.

Examples of this would be a tutorial that needs 'ok and cancel icons. Instead of unploading images etc, a library version of an would be available at example.mozilla.org/icons/16x16/ok.png

Some of the items I can think of are

  • A standard set of icons in 16/24/32 sizes (what format) for ok, cancel, help, file open, save as, edit etc etc eg XUL_Tutorial uses images
  • A set of misscelanous large images/photos of various sizes - eg of tux, linus, a gecko - stuff that could be used on example web pages - eg a photoalbum via ajax tutirual
  • A few base CSS style sheets -
  • Some stock Javascript functions eg screen resizing/centering, switching layers and of course AJAX

Page last modified 07:17, 25 Apr 2006 by Pmash

Tags:

Files (0)