IDE/proposal summaries

From MemberWiki

Revision as of 00:53, 26 October 2007 by Bertrand.Le.Roy@microsoft.com (Talk | contribs)
(diff) ←Older revision | Current revision (diff) | Newer revision→ (diff)
Jump to: navigation, search

This wiki page contains high-level short executive summary proposals from various members of this committee that contain proposed technology approaches for addressing the IDE WG's use cases and requirements.

Each executive summary should have its own section titled something like "Acme Proposal" (in wiki markup: =Acme Proposal=) followed by a handful of paragraphs that outline the proposed approach. If the executive summary is more than one printed page, it is probably too long. Supplemental details should be placed elsewhere, such as on a separate wiki page.

Contents

Adobe Proposal

What we're most interested in is an XML format for describing specific Ajax widgets (controls) rather than entire libraries. In this scenario, <widget> would be a top-level tag; in our early prototypes, each file has contained a single widget tag, but I can't think of a reason there couldn't be more than one. Theoretically, this would allow us to read files that described entire libraries and their widgets all at once, as we could just extract the parts we need.

The basic information we *must* have includes the default HTML that should be dropped on the page for the widget to work; the constructor or other JavaScript that's unique to the page; the JS and CSS files on which the widget depends (and that would be linked or imported); and the various constructor arguments and options. We also need to know where the constructor should be inserted. Currently the assumption is that the default HTML will be inserted at the IP.

I posted a sample of the XML structure we've developed a couple weeks ago; I think since then we've moved the author attribute to be a tag so that we can indicate roles such as developer, customizer, distributor, etc., and we added a couple attributes to the assetfile tag to indicate dependencies within files (e.g., images included by stylesheets).

Aptana Proposal

Aptana's XML format is intended to support both libraries and widgets. The current file format uses one XML file for both metadata and documentation, and a second XML file for packaging of libraries and supporting pieces (snippets, documentation, wizards, etc.). The Aptana system was designed with the idea that a library author could create a complete package of items and allow their users to easily download and update that as items changed.

The various XML pieces discussed are all listed here: http://www.openajax.org/member/wiki/IDE_Survey

Our proposal would be to take the existing ScriptDoc format and add in the extra missing pieces.

Pros

  • Tested/used with a number of popular Ajax libraries.
  • Currently in use with a variety of tooling options for generating XML/HTML documentation from JS.
  • Similar to existing JSDoc standard with modifications and extensions.

Missing Pieces

  • Several widget and general library metadata tags need to be included.
  • XML extensibility
  • We have the idea of snippets, but not formally tied to what gets "dropped" in a page when a control is used. This needs a bit of extension.

Microsoft Proposal

(in progress)

Microsoft Visual Studio 2008 uses two file formats for library description and documentation. The first format contains the meta-data and is used to drive IntelliSense. The second one contains the documentation and is localizable.

The pros of those file formats include:

  • Well-defined XML schema
  • Not specific to JavaScript (can be used to describe server-side components, .NET or Java libraries, etc.)
  • Localizable thanks to the separation of reflection and textual meta-data
  • Can be easily extracted from in-code doc-comments and/or external documentation tools
  • In use today
  • Compatible with existing tools
  • Extensibility through schema

Cons include:

  • Lacks some Ajax-specific pieces of data

Our proposal is to extend the schema to include the missing data that the OpenAjax specs require and a generic extensibility mechanism based on XML extensibility.

The extraction tool for Microsoft Ajax in-code doc comments can be found here.

The doc comment format was discussed here.

The reflection file schema is here.

Examples of a reflection file that validates against this schema (MicrosoftAjax.org) and a documentation file (MicrosoftAjax.xml) can be downloaded from this page

jMaki Proposal

(in progress)


jMaki was designed to integrate third party toolkits and it follows a set of conventions as well as a small amount of configuration for tooling.

The major aspects are:

  • The Widget model - See jMkai Widget model for more. The key concept is that jMaki defines / wraps all widgets in a namespaced object that requires a single argument. The single argument contains runtime information about the widget including the location, value, service, and unique id of the widget instance and an optional associative array of additional user defined arguments. The different arguments are described in an optional widget.json file. Widget are located in a directory structure under a /resources directory of a web application where the directory names are the namespace of the widget. The lifecyle is better described here
  • widget.json File - This file lives alongside the widget and describes 1) User defined arguments used by a widget 2) Default values for the widget if not provided 3) Optional dependency information for a given widget including theming, libraries, and styles. When the dependency information refers to local resources these resources are *relative* to the widget. Meaning you can zip up a widget or set of widgets and its dependencies and install them in a given tool.
{
    "name" : "Clock",
    "type" : "dojo",
    'version' : '1.0',
    'jmakiVersion' : '1.0',    
    "image" : "images/dojo-clock.jpg",
    "description" : "This widget is a clock.",
    "args": [
        {"clockType" : {
           "type":"STRING", 
            "description" : "The clock type.",
            "defaultValue" : 'black',
             'values': [
                {'name' : 'Plain', 'value' : 'plain', 'description' : 'Clock with blue background.'},
                {'name' : 'Black', 'value' : 'black', 'description' : 'Clock with black background.'},
                {'name' : 'Black Texture', 'value' : 'blackTexture', 'description' : 'Clock with black texture background.'},
                {'name' : 'Gray', 'value' : 'gray', 'description' : 'Clock with gray background.'},
                {'name' : 'Gray Plastic', 'value' : 'grayPlastic', 'description' : 'Clock with gray plastic background.'}
               ]
            }
         },
    	{"timeZoneOffset": {
    	     "type":"NUMBER",
    	     "description": "The time Offset.",
    	     "defaultValue": 0
    	    }
    	 },
        {"label":{
            "type":"STRING",
            "description":"The label at the top of the clock.",   
            "defaultValue": ""
            }
        },
        {"labelColor":{
            "type":"STRING",
              "description":"The color of the label.",
              "defaultValue": "#000"
             }
         },
        {"topLabelColor":{
            "description":"The color of the label at the top of the clock.",
            "type":"STRING",
            "defaultValue": "#efefef"
           }
        },
        {"handColor":{
            "type":"STRING",
            "description":"The color of the clock hand.",
            "defaultValue": "#788598"
             }
         },
        {"handBorderColor": {
            "type":"STRING",
            "description":"The color of the borders around the minute and hour hands.",
            "defaultValue": "#6f7b8c"
            }
         },
        {"secondHandColor":{
            "type":"ARRAY",
            "description":"The color of the second hand in [R,G,B, opaicity] format.",
            "defaultValue": [201, 4, 5, 0.8]
             }
        },
        {"showAMPM":{
            "type":"BOOLEAN",
            "description":"Where or not to show an AM/PM with the clock",
            "defaultValue": true
        }
        } 
    ],
    'config' : {
          'type' :
           { 'id' : 'dojo', 
             'libs' : [
                   '../resources/libs/dojo/v0.4.3/djd43.js'
               ],
               'preload' : 'if (typeof djConfig ==\'undefined\') djConfig = { parseWidgets: false, searchIds: [] };',
               'resources' : [
                 '../resources/libs/dojo/v0.4.3/src'
               ]
    }
  }
}

A human readable version of the arguments is here.

  • A widget library model - Basically this is a zipped file containing the widget resources (including local assets) and the templates that will be droppable in a page. The templates are defined in a directory structure that mimics the widget model which starts at the same level as resources but starts with the name 'templates'. Templates are simply code fragments that are dropped in a page and are language (JSP/JSF/Ruby/PHP/Phobos) specific. All libraries (zip files) in jMaki are versioned using Maven style naming conventions and are individually upgradeable. For example Dojo, its widget wrappers, themes and all of the templates can be delivered in this manner and processed correctly by jMaki.

Here is a JSP fragment:

<a:widget name="dojo.clock"  />

Here is a PHP fragmement:

<?php
   addWidget( array("name" => "dojo.clock" ));
?>

And Ruby:

<%= jmaki_widget name='dojo.clock'
-%>


Here is a real widget library.

Personal tools