dojo / dapi

Dojo 1 - API viewer.

dojo

This is the foundation package for the Dojo 1 Toolkit. While still being maintained, new development is primarily focused on modern Dojo.

Checkout the Dojo framework website or if you want a more detailed technical status and overview, checkout the Dojo roadmap.

This package is sometimes referred to as the “core”, it contains the most generally applicable sub-packages and modules. The dojo package covers a wide range of functionality like Ajax, DOM manipulation, class-type programming, events, promises, data stores, drag-and-drop and internationalization libraries.

Installing

Installation instructions are available at dojotoolkit.org/download.

Getting Started

If you are starting out with Dojo, the following resources are available to you:

• Tutorials

• Reference Guide

• API Documentation

• Community Forum

What to Use Dojo For and When to Use It

The following is a brief sampling of some of the areas where Dojo may prove to be the right tool for your next project:

• For keeping your code fast and maintainable, Dojo offers an asynchronous module definition (AMD) loader -- encapsulating pieces of code into useful units, loading small JavaScript files only when they are needed, and loading files separately even when they are dependent on one another.

• When you want to easily extend existing classes, share functionality among a number of classes, and maximize code reuse, Dojo provides class-like inheritance and “mixins.”

• For creating advanced and customizable user interfaces out of refined, efficient, and modular pieces, Dojo’s Dijit framework offers several dozen enterprise-ready widgets -- including buttons, textboxes, form widgets with built-in validation, layout elements, and much more -- along with themes to lend them a consistent look. All of this is available for mobile environments as well.

• For working with advanced vector graphics, Dojo’s GFX API can render graphics in a wide variety of formats, with support for seamless manipulation (skewing, rotating, resizing), gradients, responding to mouse events, and more.

• The dojox/charting library supports powerful data visualization and dynamic charting, including a variety of 2D plots and animated charting elements.

• When you need feature-rich, lightweight, and mobile-friendly grids/tables, Dojo offers the dgrid widget, along with customizable default themes and accompanying features such as in-cell editing, row/cell selection, column resizing/reordering, keyboard handling, pagination, and more.

• Dojo is the officially supported framework for the ArcGIS API for JavaScript, one of the most widely used enterprise-grade APIs for web mapping and spatial analysis -- learning to use Dojo will open doors to creating richer web mapping applications using that API.

License and Copyright

The Dojo Toolkit (including this package) is dual licensed under BSD 3-Clause and AFL. For more information on the license please see the License Information. The Dojo Toolkit is Copyright (c) 2005-2018, JS Foundation. All rights reserved.

dapi's Issues

link to reference doc is wrong

For example, on the dijt/Menu page where it says:

See the dijit/_WidgetBase reference documentation for more information TODO:

Clicking the link has no effect.

extension-module missing from methods

See dojo/NodeList

http://dojotoolkit.org/api/1.9/dojo/NodeList addClass is defined as an extension-module where as
http://localhost:3000/api/1.9/dojo/NodeList.html addClass isn't.

e.g.
`

addClass (className) adds the specified class to every node in the list

`

as compared to:

`

addClass (className) adds the specified class to every node in the list

`

Seems there's a defect both in summary and full description

Also note there seems to be markup errors, closing spans etc

clarify meaning of upper right icons

Regarding the meaning of the icons in the upper right next to the "View options:" labe... The (Et) icon makes it seem like the whole module is an extension module (whatever that means), rather than people knowing it's a toggle button to show/hide extension methods in the module.

Probably something with checkboxes like this would be more intuitive:

Show: ☑extensions ☑privates ☑inherited

Taken from http://dojo-toolkit.33424.n3.nabble.com/What-s-included-in-CDN-distro-td3998287.html.

todo's outstanding for extension modules

As per Adrians comments. Just about to check in but there might be some outstanding icons for properties, if so, use this to track

more test coverage

Add spider to the travis test? e.g. actually successfully running/testing library code

support for old versions

The old viewer serves pages starting from Dojo version 1.3. It seems easy enough for your new viewer to support that too, by either:

1. Call lib.old/generate.php on the fly when you need to get a page from an old version
2. Pre-generate all the pages for all the dojo versions, using the "static" option to app.js or for dojo V1.6 and earlier, using the spider PHP code. I seem to have removed that code from my repository but it's there in the history, see https://github.com/wkeese/api-viewer/blob/1260dbeaa1f9722e30bfc14b12a16d3b1ccc183d/lib/spider.php

kwArgs objects not showing as a pseudo class

e.g. http://dojotoolkit.org/api/1.9/dojo/main.__IoArgs shows the "this is not a real constructor"

Am just about to check this in but @wkeese I'd like feedback on this please.
I didn't realise that pseudo classes are all matched via the module name beginning with __
Seems rather brittle and I'm not sure I've seen that docd in the ref guide etc

function return type hyperlinks broken

Load the page for any widget and look at details for the placeAt() function. The return type is dijit/_WidgetBase, but you can't click it.

reminder to fix moduletree.js not handling 1.10

It compares versions using float, it needs to compare lexically

e.g. https://github.com/lbod/dapi/blob/master/public/scripts/api/ModuleTree.js#L50
in the tree load dijit > dijit/CalendarLite._MonthWidget and compare between 1.9 and 1.10

extra comma after Extends...

For example on http://localhost:3000/api/1.9/dijit/Fieldset it says:

Extends dijit/TitlePane,

URL doesn't work with final slash

https://dojotoolkit.org/dapi/ works but https://dojotoolkit.org/dapi doesn't. Ideally both should work, especially since https://dojotoolkit.org/api (without a slash) works.

Filing this ticket here but it's likely an issue with the dojo website itself. Perhaps it will resolve itself after the dapi is deployed officially and renamed to api.

How to generate details.json?

Hi,

I create this issue to clarify "how to generate Dojo API Documentation", because I'm a little lost.

At first, I'm developping https://github.com/angelozerr/tern.dojotoolkit which generate tern plugin from the old dojo api.json. tern plugin is used for the javascript inference engine tern.js http://ternjs.net/ to benefit with completion ,refactor, ect inside a JS Editor (Emacs, Vim, Sublime, Eclipse, etc). You can see screeshot about dojotoolkit completion with Eclipse at https://github.com/angelozerr/tern.java/wiki/Tern-&-DojoToolkit-support

As I said you, I use 1.6 old api.json https://github.com/angelozerr/tern.dojotoolkit/blob/master/api/1.6/api.json and I use it to generate dojo tern plugin.

In the dojo documentation http://dojotoolkit.org/reference-guide/1.9/util/doctools/generate.html there is a link to
https://github.com/wkeese/old-api-viewer/blob/master/README.rst and in this project there is a link to https://github.com/lbod/dapi

So I suspose that your project, is the new mean to generate documentation for dojo. After reading your documentation, you generate tree.json + details.json. In my case I need details.json (API+Documentation)

In the https://github.com/lbod/dojo-api-data you provide details.json, but not for 1.6, 1.7, do you think it's possible to provide it?

Thank's for your answer.

Regard's Angelo

clicking TreeNode for already open tab does not switch to that tab

For example, in the Tree, click _WidgetBase: the _WidgetBase tab is created and selected.

Then, click _Widget: the _Widget tab is created and selected.

Then, click _WidgetBase again. Nothing happens. It should switch back to the _WidgetBase tab.

background gray behind "permalink" slides away

If you scroll a page, the permalink link stays fixed in position but the gray background behind it disappears.

1.6 and earlier permalinks are broken

If you go to http://dojotoolkit.org/api/?qs=1.6/dojo/io/script , and then click on permalink, it will try to take you to http://dojotoolkit.org/api/1.6/dojo/io/script/ which is broken.

make collapsible sections obvious

http://dojo-toolkit.33424.n3.nabble.com/What-s-included-in-CDN-distro-td3998287.html points out that it's unclear that the "Module summary" section is expandable, and suggests:

Perhaps the arrow should be on the left of the text and darker/bigger.

Of course this applies to all the collapsible sections.

anchor links broken

Try for example opening the "property summary" section on the dijit/_WidgetBase page, and clicking "baseClass". Nothing happens. It should scroll down to the full definition.

method description missing

See for example in http://dojotoolkit.org/api/1.9/dojo/parser vs. http://dapi.eu01.aws.af.cm/api/1.8/dojo/parser.

The parse() method in the "Methods" section (not the "Method Summary" section) is missing it's description.

extra commas in HTML output around examples

See the definition of dijit/_WidgetBase/containerNode:

,
    1.  ,  <div data-dojo-type=myWidget>
    5.  </div>,
,

properties and property summary missing

See http://dapi.eu01.aws.af.cm/api/1.8/dojo/parser and compare with http://dojotoolkit.org/api/1.8/dojo/parser

no hyperlinks in module level summary?

At least, on the page for dijit/_tree/dndSource (version 1.9), where it says:

Deprecated module, use dijit/tree/dndSource instead.

The dijit/tree/dndSource text did not become a hyperlink.

tree link selected when changing tabs to a module version different to tree version

This is just a reminder to fix, it should be a quick fix checking the loaded tree version versus the module version.....

Example user journey to recreate:

• load default viewer (e.g. v1.9)
• in the tree open for example dijit/_base
• switch loaded version to 1.8
• in the tree open for example dijit/_Calendar
• select the 1.9 tab for dijit/_base and the tree will select the dijit/_base item in the 1.8 tree

This probably shouldn't happen as it's a different loaded version tree

usage section lists MID not plain name

For example, it says:

var foo = new dijit/Fieldset(params,srcNodeRef);

instead of:

var foo = new Fieldset(params,srcNodeRef);

top level function usage and property classes missing

This is a tracker for property css classes missing (inherited) e.g. http://dojotoolkit.org/api/1.9/dijit/_TemplatedMixin.searchContainerNode

and "top level function" usage missing e.g. functions not constructors. see http://dojotoolkit.org/api/1.9/dojo/on for an example

permalink support

If app.js is meant to replace apache, it needs to handle permalink URL's like

http://localhost:3000/1.8/dijit/Dialog

.... which should return the index.html type page (with the BorderContainer and Tree) but with the dijit/Dialog tab automatically downloaded.

Currently this is handled from apache via the rule in .htaccess:

# but for anything else (ex: 1.8/dijit/Dialog), handle it from index.php
RewriteRule ^(.*)$ index.php?qs=$1 [L,QSA]

allow an array of versions to be spidered

As per the title, iterate over versions to spider

1.3 legacy docs - review tree.json & regenerate

It appears the tree.json is not correct. See http://dojotoolkit.org/api/?qs=1.3/dojox/grid/TreeSelection

dojox/grid/TreePath, dojox/grid/TreeGrid are the same

I'll need to run the php tools to regenerate again and compare

CSS for code spans missing?

See for example in http://dojotoolkit.org/api/1.9/dojo/parser vs. http://dapi.eu01.aws.af.cm/api/1.8/dojo/parser.

In the "Methods" section, the description for the constructor lists the "scripts" parameter. In http://dojotoolkit.org/api/1.9/dojo/parser

<script type="dojo/*">

is highlighted (much like in this tracker) but in http://dapi.eu01.aws.af.cm/api/1.8/dojo/parser it's not.

1.10 docs will need to be created soon

@wkeese @dylans

icons

Put back all the icons (in the Tree and the pages for individual modules).

offline viewing

Support the API viewer without a web server, but with the same UI.

You have the basics, but I think you'd need to convert the stylus files into plain CSS at the same time you output the static HTML files. Alternately I guess the browser could convert the stylus to CSS, but as long as you are running a preprocessor to generate HTML files you might as well generate CSS files too.

"event" section shows privates even when it shouldn't

See dijit/_WidgetBase page, the "Event summary" section. It lists functions like _onBlur even though the "privates" toggle button (upper right) is in the off position.

Likewise for the "Events" (i.e. the event details) section.

reference doc links inflexible?

Looking at http://dapi.eu01.aws.af.cm/api/1.8/dijit/_CssStateMixin and clicking the reference doc link, it goes to http://dapi.eu01.aws.af.cm/reference-guide/1.8/dijit/_CssStateMixin.rst.

Besides that file not being in your staging area, the real issue is that the link from dojotoolkit.org is not http://dojotoolkit.org/reference-guide/1.8/dijit/_CssStateMixin.rst but rather http://dojotoolkit.org/reference-guide/1.8/dijit/_CssStateMixin.html. Note how the extension is different.

I guess it's just that you should be generating the API guide against a built version of the reference doc rather than a source version, and that the default config setting should look for .html rather than .rst.

IE11 broke - trailing commas

Unsure how I left the jshint options as is but trailing commas in object literals are ignored, it breaks IE11

permalinks with matching file/folder names broken in static outpu

Load the static output from dapi over apache.
Open up a tab which has a module name matching a folder name e.g. 1.9/dijit/_base/

Clicking the permalink will either display the folder contents or a 403 (depending on apache indexes config).
e.g. http://localhost/api/1.9/dijit/_base

remove client side URL rewrites

If I select 1.4 in the dropdown and bring up dijit/Calendar, then click the Permalink, the URL bar goes to https://dojotoolkit.org/api/?qs=1.4/dijit/Calendar. Happens for 1.3 〜 1.7.

Two issues:

• Ideally it would be https://dojotoolkit.org/dapi/1.10/dijit/Calendar.html rather than using the URL query string (question mark syntax).
• The URL switched from referencing dapi to api. I guess that won't be an issue when this is deployed for real, but probably indicates some underlying problem.

This problem is leftover effect from when we were serving pages statically and the rewrite was happening in client-side javascript. By turning off javascript and clicking the Permalink URL (and then view source) I can see:

<script type="text/javascript">
  // If user loads this page directly, redirect to index page, with parameter to initially show tab for this module.
  // If google loads this page directly it will hopefully ignore this script and just index the documentation below.
  // Also, when this page is loaded via XHR this script block should be ignored.
  location = "/api/?qs=1.10/dijit/_OnDijitClickMixin" + location.hash;

</script>

I remember having a perl script that added those <script> blocks but now I can't find the check-in. I don't see those script blocks [anymore] either in https://github.com/wkeese/dojo-api-data/tree/master/1.6/dijit/Calendar, so I'm confused.

There's also this code in app.js:

// rewite the url to the ?qs= parm, meaning all legacy permalinked docs are still loaded via XHR.
// the only other option is dynamically including the html in the template which wouldn't be good for performance
// TODO: the .html extension is an issue, here im stripping it (compared to legacyfilelocation), this is also mirrored in the client JS (and FWIW apache)
res.redirect(301, config.contextPath + '?qs=' + requestedVersion + '/' + modulefile.replace(/\./g, "/"));

A related issue is that after doing the above, the dropdown says 1.10 instead of 1.4, even though the tree is showing 1.4. Selecting 1.10 in the dropdown list manually now has no effect. (But I can get back to the 1.10 tree by selecting 1.9 first, then selecting 1.10).

examples missing

See for example in http://dojotoolkit.org/api/1.9/dojo/parser vs. http://dapi.eu01.aws.af.cm/api/1.8/dojo/parser.

In the "Methods" section, the description for the parse() method lists examples, but in http://dapi.eu01.aws.af.cm/api/1.8/dojo/parser it doesn't.

split app.js

As per the comment in app.js, split app.js into two files, one for the web server and one for static page generation (maybe called live.js and static.js?). The static page generation file shouldn't have a dependency on node express.

doc cleanup

There's been a few changes since the last wiki updates, this is just a holder to make sure the wiki is updated appropriately when code is complete

async/promise loading

A tracker for some of the current sync loading calls.

Should look at either node promise modules or bootstrapping dojo for promises, the aim is better performance and consistent, less bloated code, to manage sync and async calls

tree link not selected

On the old viewer, navigating http://dojotoolkit.org/api/1.9/dijit/Fieldset will select dijit/Fieldset in the left hand tree, but something like http://localhost:3000/api/1.9/dijit/Editor just leaves the tree closed.

Likewise, switching back to a previously opened tab should select the corresponding row in the Tree, but doesn't.

http://dojotoolkit.org/api/1.9/dijit/Fieldset isn't perfect either though because it doesn't scroll to the selected Tree element.

clicking jsdoc-summary-toggle causes nodeType = null in query

a tracker for:

• load for example http://localhost:3000/api/?qs=1.9/dojo/NodeList
• click on any of the jsdoc-summary-toggle arrows on the summary headings

Uncaught TypeError: Cannot read property 'nodeType' of null

"close all" option on tab context menu

The "close all" option is on the menu listing all the tabs (which is only visible when when the tab labels overflow), but I expected it to be on each tab label. I.E. for each tab label to have a Menu with two or three choices (close, close all, close others).

Seems like you wanted the same thing, judging from your TODO comment in the code:

/* temp - add a close all option - move to context menu on the tab label */

legend

I updated the legend to be accessible from mobile in wkeese/old-api-viewer@3044944#index.php.

This change should be "merged" into your templates.

do we need this registered via npm?

Currently the dapi repository is registered as an npm module e.g. see https://npmjs.org/package/dapi

Is this actually needed?
It's not a package, it's an application and I can't see how this fits with npm usage.
Is there really any benefit registering npm for dapi when all it requires is a git checkout and then npm install ?

"Optional" keyword missing

See for example in http://dojotoolkit.org/api/1.9/dojo/parser vs. http://dapi.eu01.aws.af.cm/api/1.8/dojo/parser.

The parameters to the parse() method (parse() in the "Methods" section, not the "Method Summary" section) should be described as optional.

SEO

See wkeese/old-api-viewer@72459f0 and wkeese/old-api-viewer@fec9707 which together (theoretically) make the API pages indexable by google. You need to do something similar.

REST service

The old API viewer had a REST service to embed API documentation in the reference doc. Do we still want that?

Like http://dojotoolkit.org/api/rpc/1.8/dojo/dom, although for some reason it isn't working there, but Kitson has it working on his local box.

The code is (or was) in https://github.com/wkeese/api-viewer/blob/master/rpc/index.php.

Permalinks in static output

@wkeese I know we've discussed this over email but I'd like to firm up the requirement.
Permalinks in the dynamic runtime (node.js) are easy to manage, however when spidering static markup, permalinks won't work unless more work is done.

One option is to use a rewrite rule in apache (or whatever server is used) something like /api/dojo/parser > 301 redirect to /staticapi.html?module=dojo/parser. api.js could then use the qry parms to request the correct content pane href to load

Another option, though not great, would be adding config to switch off permalinks for static generated markup

provide a configuration object

The app currently has hardcoded configuration, this is a place holder to track that configuration options are provided.