# The official DynAPI2 F.A.Q.

##### last update: 2001.02.13

- 1. What's the DynAPI2

- 1.1 Who created the DynAPI

- 1.1.2. Who maintains the f.a.q.
- 1.1.3. Where to get the f.a.q.

- 1.2. Why upgrade
- 1.3. Differences between DynAPI and DynAPI2
- 1.4. Differences between DynAPI and Dynacore
- 1.5. Compatibility between DynAPI1 and DynAPI2

- 2. Where can I find the latest version

- 2.1. When is the next release
- 2.2. Where can I find support

- 2.2.2. Mailinglist overview

- 2.3. Where can I find the documentation
- 2.4. Other resources
- 2.5. Snapshot releases

- 3. Which browsers are supported

- 3.1. When will browser X be supported
- 3.2. I tested on browser X, here are the results
- 3.3. What about the Mac?
- 3.4. DOM compliant

- 4. How can I contribute

- 4.1. "Why don't you guys do this, or add that?"
- 4.2. This thing isn't working at all
- 4.2.1. Where can I submit bugs?
- 4.3. How can I become a developer
- 4.4. Using CVS.

- 4.4.1. Who should use CVS.
- 4.4.2. Using CVS on Windows.

- 5. What are widgets

- 5.1. What widgets are there
- 5.2. Where should I upload my widgets
- 5.3. Where is widget X

- 6. Known bugs

- 6.1. Doing advanced things
- 6.2. Limited Javascript knowledge
- 6.3. Load external content into layers
- 6.4. Accessing html elements in layers

# 1. What's the DynAPI2

DynAPI2 is the follow up to the original DynAPI available from the DynDuo site at http://www.dansteinman.com. The DynAPI is a cross-browser DHTML library giving you full controll over dynamic layers, documents and events.
The DynAPI2 is an opensourced project and is available under the GNU license. If you want to develop good working DHTML websites or webapplications, there's probably no other library that gives you so much power with only a few lines of Javascript code. Here's a short example of how you could create a dynamic layer and manipulate it's appearance:

    myLayer = new DynLayer()
    myLayer.setSize(100,100)
    myLayer.moveTo(200,200)
    myLayer.setBgColor('#c0c0c0')
    myLayer.setHTML('A dynamic layer')

    DynAPI.document.addChild(myLayer)

There are even shorter ways of creating dynamic layers, but this example should prove the great object oriented programming you can do with the DynAPI2.

# 1.1. Who created the DynAPI

The DynAPI2 was initiated by Dan Steinman (who also developed the original DynAPI and DynDuo tutorial at http://www.dansteinman.com/dynduo). The project was started somewhere around January 2000 (I think that was the beginning) and a small group of developers has been developing it since then.
I won't go into making a list of all the developers that have helped, but here's the short list that is also supplied with the DynAPI2 library:
The DynAPI is created by Dan Steinman
Thanks to:

- Micah Goulart
- Chris Bodar
- Pascal Bestebroer
- Bill Tammen
- Scott Andrew
- Robert Rainwater
- Ryan Grenz
- Clack Pacheco
- Jordi 'Ilmaestro' Ministral
- Brandon Myers

# 1.1.2. Who maintains the f.a.q.

Ehm, the name would be Pascal Bestebroer? I'm not planning on being the only f.a.q. maintainer, but since I started this f.a.q. I'll be taking atleast some responsibility for it :) I'm one of the developers and have been getting a lot of mail from people asking the same questions over and over, so this is basically the reason I started this f.a.q. I'm hoping the other developers will help by adding questions and answers to this f.a.q. I'll make this f.a.q. available at the sourceforge site and my own website (http://www.dynamic-core.net/core/files/faq.dynapi2.html).

# 1.1.3. Where to get the f.a.q.

The latest f.a.q. can be found on my own website, because it's uploaded there first (http://www.dynamic-core.net/core/files/faq.dynapi2.html). But it's also available at the urls mentioned in 2.3 Other resources and should be available in the DynAPI2 distribution as well (although outdated).

# 1.2. Why upgrade

This is probably a question I can't answer but if you like to use a better code base to create your websites on I highly recommend using the DynAPI2 library. Although the DynAPI contains some great code it's a bit "ugly" to use. If you want to have the option of creating layers at any time (after document.onload for example) you'll have to upgrade. If you want a supported DynAPI, you'll also have to upgrade because basically the old code is not supported,enhanced or fixed anymore.

# 1.3. Differences between DynAPI and DynAPI2

The DynAPI code, although very good, is outdated and in some cases hard to work with. The new DynAPI2 code uses a much better object oriented approach. If you'r used to developing with the original DynAPI you'll have to learn some new things for the DynAPI2.. but please note that it's worth it.
I'm probably skipping a few things, but here's a short list of the main differences:

- Layer generation

  DynAPI couldn't generate layers after the document had finished loading, this is changed in DynAPI2. No more need to write the DIV or CSS tags, just create a new DynLayer object.

- Events

  DynAPI2 features a great eventlistener object based on Java style programming (also used in DOM2 events), it's possible to make any layer catch any event at any time.

- Browser compatibility

  DynAPI was compatible with IE4 (IE5?) and NS4, but since it's not getting enhancements and bugfixes it won't work with newer browsers and features. The DynAPI2 is compatible with IE4,IE5,IE5.5, NS4 and Mozilla (NS6) It's also being made compatible for Mac versions of the above mentioned browsers, and should be compatible for Linux users.

# 1.4. Differences between DynAPI and Dynacore

The DynAPI2 (as found at http://dynapi.sourceforge.net) is the official release as started by Dan Steinman and is being continued by a group of developers (including little me). The Dynacore is my personal distribution of the DynAPI2, it's based on DynAPI2 code and ideas but differs in certain areas from the official one. These are usually ideas that I wanted to include but others didn't, and ideas that others wanted to include and I didn't will be left out of the Dynacore.
It all depends on your own taste, if you like the Dynacore version better then use that one, if you like to stick with the official version just use that one.. it shouldn't be a problem. The only problem might be when you want to mix them up, there will be NO SUPPORT from either side for this, just make a choice!

# 1.5. Compatibility between DynAPI1 and DynAPI2

The DynAPI2 uses a complete new code-base and is not build on the DynAPI1 code. It was build from scratch. Ofcourse there was some compatibility planned between the two versions but I think that the differences are growing more and more between the two versions (mainly because DynAPI1 is discontinued).
For one, this means that all DynAPI1 widgets are not always present in DynAPI2. This should eventually change and for more information see 5.3. It also means that if your working on a project using DynAPI1 it's probably wise to finish it using the old DynAPI1 and not try to convert it because that will most likely take more time then you planned.

# 2. Where can I find the latest version

There have been some problems with version controll, but at this point you should get the latest version from http://dynapi.sourceforge.net/. It's the DynAPI2 developers site, and contains the latest "official" release.

# 2.1. When is the next release

Because this project is opensource and most developers are working on this in freetime, it's very hard to put a deadline on things. The main idea is "it's done when it's done". It's understood that a previous release sometimes looks very outdated compared to the latest snapshot, but that's just how it works. You are ofcourse free to use the daily snapshot but as stated at some places in this faq: it's code which is under development; meaning that if it works today it might be broken tomorrow, something which won't happen in the release (if it's broken tomorrow, it was also broken today :-).

# 2.2. Where can I find support

For support you should join the DynAPI2 mailinglists, the lists are very active and many people there will be able to answer your questions. To join the mailing list visit the DynAPI2 website and read for more information http://dynapi.sourceforge.net. There are no more forums available, the official forum at Dan Steinman was closed, and the forums at sourceforge have been replaced with the mailing lists.
Please make sure to read the archives, because there's a big chance that your question has already been asked and answered before.

# 2.2.2. Mailinglist overview

When posting to the mailing lists, please make sure to use the correct list. There are three lists with each there own usage, by using the correct lists you save everybody some time when sorting out problems and development posts.

- Help (dynapi-help)

  If you are using the DynAPI2 and need help with anything, use this list. Most developers are also monitoring this list and will help out when possible.

- Widget Development (dynapi-widgetdev)

  If you have new widgets, or ideas for widgets this is the list to post them to and get some discussion going.

- Development (dynapi-dev)

  Used for DynAPI2 development. Mostly used by the developers and people helping out with bug fixes, new functionality, etc..

for a full list of DynAPI2 mailinglists visit: http://www.mail-archive.com/index.php3?hunt=dynapi this also contains searching facilities to search the mailinglist archives.

# 2.3. Where can I find the documentation

If your used to Dan Steinman's dynduo tutorial your in for a shock because that's not available for this version of the API. Some basic documentation has been written and a step-by-step tutorial is available and that's it. The documentation and tutorials are still being modified and updated to make it easier for new users to get into using the API and together with the examples included in the library it should be possible to create some things in a short time. For more information on the available documentation visit the DynAPI2 website (see 2.4)

# 2.4. Other resources

Here's a list of different resources for DynAPI2 code, examples and news:

- dynapi.sourceforge.net

  Official DynAPI2 site and mailinglists

- www.sourceforge.net/projects/dynapi

  official Developers site and mailinglists

- www.dansteinman.com

  Dan Steinmans homepage

- www.cantir.com/dynapi

  Jordi Ministral's DynAPI2 website

- www.dynamic-core.net

  Containing widgets, code and tutorials

- www.richardinfo.com

  Contains a more or less complete Widget archive.

# 2.5. Snapshot releases

As mentioned in chapter 2, the latest official release can always be downloaded from the DynAPI2 website. If how ever you need the most uptodate version available to do your development on, there's also a daily snapshot available. These snapshot files are created automatically from the CVS tree (for more info on CVS see chapter 4.4). This means they are the most uptodate packages available for the DynAPI. BUT! These packages are using development code, meaning that it's quite possible that certain things are broken one day which were working the previous day.. The snapshot releases should be considered HIGHLY BETA and might contain a lot of non-working code.
The snapshot files can be downloaded from: http://dynapi.sourceforge.net/snapshot/ or the latest can be downloaded from: http://dynapi.sourceforge.net/snapshot/dynapi.zip.

# 3. Which browsers are supported

The current version of the API is mainly worked on by windows users, so logically the windows browsers will be supported better then other platforms. Here's the list of browsers:

Internet Explorer 4 | (windows)
Internet Explorer 5 | (windows)
Internet Explorer 5.5 | (windows)
Netscape Communicator 4.7 | (windows, linux and 95% Mac)
Netscape Communicator 6 | (windows, linux?)
Mozilla (milestone 16 and higher) | (windows, linux?)

Note that these browsers might not be fully 100% supported but we're targetting these browsers. For a better and more complete compatibility matrix please visit http://www.shireyproductions.com/dynapi/matrix/default.htm

# 3.1. When will browser X be supported

Good question, the most important thing to remember is the simple fact that Internet Explorer and Netscape are the most used browsers (IE alone is 85% of the users). So even if you don't like Microsoft or Netscape you'll have to face reality. If you need support for another "exotic" browser you'r best bet would be to do it yourself, the browsers mentioned above are the only ones that have full support at this time.
I think there's only one "real" browser left and that's Opera. I've been playing with it personally and it's a good browser, but I had a lot of problems getting javascript to run in it.. another bad thing about it is that it's not free so not many people will own it (why buy if you can it for free?). - Update: Since Opera 5 the browser IS free.

# 3.2. I tested on browser X/platform Y

Mailing or posting results of your tests are not very usefull. Javascript is a hard language to debug and knowing that something isn't working does not automatically lead us to the errors in the code. Testing in Javascript requires alot of code changing, inserting and removing alert messages, and checking different parts of functions.
The DynAPI (and mainly the dynlayer object) is so big that finding the exact position of the error is just not so simple. It's great that you can test the code for us but we can't really use your feedback on it because of no debugging capabilities.

# 3.3. What about the Mac?

This is probably the MOST asked question out there, the problem is that the main developers are all working on either Win32 or Linux machines. Seeing that the DynAPI2 user base is growing rapidly there should still be hope that someday all the DynAPI2 code will work correctly on Mac IE and Mac NS, sadly for now this is not the case.
We need some good javascript developers with Mac's (or other systems/browsers combinations) that can do the debugging them selves.. it's the only way that will work.

# 3.4. DOM compliant

The DynAPI is being created to be cross-browser compliant. Although the W3C is setting standards (DOM1, DOM2), the browsers that comply to these standards might not always work correctly. The problem lies in a few factors. The main factor being Javascript, Javascript standards are not part of the W3C's DOM, although there is a Javascript standard, this is something not (yet) supported by all browsers. This is also the main problem we have when trying to make DynAPI work crossbrowser. Another problem is that there are no real DOM compliant browsers yet. There are ofcourse a few browsers that are being developed to be DOM compliant, but at this time these browsers seem to contain small bugs that can screw up the DynAPI code.
The main goal is to get things working correctly under NS6 (seeing as it is the best known DOM compliant browser) and from there on it should be possible to support all other DOM compliant browsers.

# 4. How can I contribute

"I like the project alot, I have been using it for a while and want to help how can I contribute?"
This is a question I've been getting alot, so here's the answer: http://dynapi.sourceforge.net. This is the URL for the developers site, join the mailing lists and you can post bug fixes and patches and help others out.. that's all you need to know! The DynAPI2 is opensourced so basically everybody can contribute.
Things like documentation is something that could really use some talented people so if you understand the code or atleast know what every function of the API does go and write some great docs.
Note, if you can not program in Javascript (or not good enough, or don't understand any of the code used in the API) you should first get your self familiar with it, because with out the knowledge you won't be able to really contribute anything. Writing documentation, helping with this f.a.q require you to know the code.. it's hard but also the reality.

# 4.1. "Why don't you guys do this, or add that?"

The people that are developing the API are doing it for different reasons, but most of us do it just for the fun we're having with it. The things we add or fix are (probably) only done because we need to use it ourselves somewhere, if you have good ideas to add to the API why not give it a shot yourself?
Posting or mailing these questions is not a bad thing and very apreciated, but please don't depend on us to actually do anything with it. If you really need a feature and it's not in yet I guess you'll have two choices, do it yourself, or wait until one of the developers needs it.

# 4.2. This thing isn't working at all

I've been reading a few posts here and there from people saying that the thing isn't working at all, or not working correctly. One thing to keep in mind is the fact that there are already alot of people working with this library and that they are having no problem at all. In most cases there's a "user" error or another system problem. The API code is at this time working almost bug-free and should be considered a complete library. Ofcourse there are still some bugs in there somewhere, or missing features but that's the case with 99% of all software available.
If you get error messages with your own code, please check the examples supplied with the library. If they also fail to work you might be using either an unsupported browser/platform, a bad installation of your browser, or have installed the DynAPI2 incorrectly on your system. In any case the supplied examples should work under the correct browser/platform combinations mentioned in chapter 3.
If the examples work but your own code seems to fail the problem becomes harder. In alot of cases the linking of the DynAPI files is not correct and you should check that first. If you use external widgets, it's wise to check the supplied examples/documentation of the widget to see that you'r using it correctly. If this still hasn't fixed your problems, please join the mailinglists at sourceforge (see 2.1) and post a detailed description of your problem and code.

# 4.2.1. Where can I submit bugs?

The best place to submit bugs is at the Sourceforge site http://www.sourceforge.net/projects/dynapi in the bugs section, Sourceforge supplies us with a great tool for keeping track of bugs. Alot of people post there bugs in the mailinglists, this is great but it also means that with the high-traffic of those lists that bugs might get lost.
When submitting your bugs please make sure to specify the bug as clearly as possible (with the smallest example code if possible) this way it's alot easier for developers to recreate the situation. Also try to leave your name somewhere (if you have a sourceforge user name it will be done automatically) this is easier then communicating with "nobody".
If for some reason your bug is closed without a fix, this might mean that the bug was not reproduceable.. if the bug can't be recreated it's hard to fix and will most likely be closed specifying the reason.

# 4.3. How can I become a developer

Currently there's only a short list of developers for the DynAPI2, this doesn't mean those developers are the only ones doing the coding. Thru the mailing lists more people are helping out on this project. There are no special rules on who can or can not join the developers list, but I think it all depends on how much you can and are contributing to the project. There's a large difference between someone giving feedback, and someone fixing multiple bugs and adding extra functionality.. so I guess only people doing alot of development, and showing a "long-term" commitment are added to the developers list and given full access to patches/bugs, etc.. But everyone on the developers list is part of the DynAPI developers.

# 4.4. Using CVS.

If you want to contribute, make sure to use the latest code. The DynAPI2 project uses CVS (Concurrent Version Controll) for development. There are daily-snapshots created of the complete CVS tree, this is one way of getting the latest version. The full snapshot can be downloaded from http://dynapi.sourceforge.net/snapshot/dynapi.zip please note that this daily-snapshot is for developers, if you just want to use the DynAPI2 you should download the latest official release from the DynAPI2 website (see 2.1). This snapshot could include bugs and errors that still need to be fixed before a new release is made.

# 4.4.1. Who should use CVS.

CVS should only be used by DynAPI2 developers. It's not an official distribution version, but development code that can still be buggy, and should not be used by end-users. If you want to join the development of the DynAPI2 please visit the dynapi2 website and read there for more instructions.

# 4.4.2. Using CVS on Windows.

Here are some quick and dirty instructions for setting up CVS on windows. (Thanks to Robert Rainwater)
Files
WinCVS: ftp://sunsite.cnlab-switch.ch/mirror/cvsgui/WinCvs11b17.zip
SSH: ftp://ftp.dei.uc.pt/.disk2/Crypto/SSH/contrib/ssh-1.2.14-win32bin.zip
Installation
Install WinCVS as per the instructions provided.

- Unzip ssh-1.2.14-win32bin.zip to a directory (ex. c:\ssh).
- Add c:\ssh to the PATH variable.
- Create a HOME directory (ex. c:\home).
- Create environment variable HOME with value c:\home
- Restart
- Start WinCVS.
- It should prompt to enter your CVS Root (if not, choose Admin|Preferences).
  Enter the cvs root as: ":ext:@cvs.dynapi.sourceforge.net:/cvsroot/dynapi" Below CVSRoot, choose SSH Server for authentication. Then click the Ports tab and click "Check for alternate rsh name" to enable it. Then choose OK and your set.

Also, you can choose View|Browse Location|Change to change to a working directory, so you will not see your whole hard drive in the view. Choose c:\home for example.
Now your set.
To checkout a module, Right click Home and choose checkout and then you would enter the name of the module. A DOS box will pop up that will require your sourceforge password.
You can then checkout "dynapi" to get the latest version.
For more detailed info visit:
https://sourceforge.net/docman/display_doc.php?docid=766&group_id=1

# 5. What are widgets

Having cross-browser code is great, but what can you do with it? One of the cooler things you can do with the DynAPI2 is creating widgets. Widgets are small components that can be used on your webpage or in your webapplication, things like buttons,toolbars,checkboxes are all widgets and can be created using the DynAPI2 code (or DHTML in general, but the DynAPI2 makes it easier to code them cross-browser).

# 5.1. What widgets are there

This is hard to say, basically everybody can make widgets so there might be a widget for everything you can think of. The DynAPI2 comes with a library of default widgets. At this point it's not defined yet which widgets should be in the default widget set. In any case the old DynAPI1 widgets should be converted to DynAPI2 versions (most have already)

# 5.2. Where should I upload my widgets

Good question.. your website? There's no official location availabe yet that contains a widget archive (see 5.3 for more info). Also please don't expect that your widgets are being added to the DynAPI2 distribution. DynAPI2 will be supplied with a standard set of widgets (either the same package or as seperate download from the DynAPI2 website). If we would add all widgets to the distribution it would become bloated and might also scare new users by having so much code and not knowing what to do with it. For now just use your own website and post a message in one of the mailinglists (see 2.1). If you don't own a website you could get a free one at one of the many free web space providers (geocities, xoom,etc).

# 5.3. Where is widget X

Most of the original DynAPI1 widgets have (or will be) ported to the DynAPI2. If it's not available at the sourceforge site, or on any of the developers personal websites (see 2.3) it's probably not created yet. You might want to try and post a message in one of the mailinglists (see 2.2) asking for a certain widget or ofcourse the all time favourite, create the widget your self. For a nice collection of most widgets available visit www.richardinfo.com.

# 6. Known bugs

As with any piece of software the DynAPI also contains bugs, some of these bugs will eventually be fixed but some other bugs are more browser-problems and hard to fix using DynAPI code. Here's a list of the bugs and if possible a work-around.

- Netscape4.04;

  This browser has some problems with parsing Javascript. Some things can be fixed by adding `return true/false` lines into functions, but problems may still exist. Advise: upgrade to a newer Netscape version

- Resizing browser; browser:Netscape 4.x

  Occurs in Netscape browsers, layers will not be correctly re-rendered. This is a Netscape bug and the DynAPI code will try to work-around it.. this does NOT happen on all NS4 browsers, and problems might differ (noticed this on different machines).

- offsetWidth/offsetHeight; browser:Netscape 6+

  There are some problems with getting these values from layers. We're still working on solutions for this. A possible work around is using a setTimeout() of 0 which seems to do the trick (as reported).

- Hourglass syndrome; browser: Internet Explorer

  This bug shows an hourglass (sometimes blinking) while your page has already completed loading. The problem is most likely that you've used a bgImage on one of the layers, and that layer is being moved,resized,or otherwise changed. IE will try to reload the background image everytime this layers appearance changes. Work around would be to either use a `setHTML('<img src="..."'>)` call or minimize the amount of changes

- Images on layers in another frame; browser: Netscape 4.x

  When creating a layer in another frame, and then trying to set an image in it Netscape will either render it completely wrong (colored-lines) or render the image in the wrong frame (i.e. the frame the DynAPI code is in, and not the target frame). There's no work-around for this available, and is a browser-bug

- Form components always ontop; browser: any

  I don't consider this a real bug, but there are alot of question about this. This is just the way browsers handle form-elements. They will ALWAYS place it on top of your layers. The only workaround would be to place the elements in one layer, and hide that one when other layers need to be on top..Can't be fixed.

- Memory leaks; browser: any

  At this point we're not yet sure if we can fix this, but using DHTML will cause your browser to use icreasing amounts of memory. This might eventually cause your browser to crash. This problem seems to be bigger for Internet Explorer users then Netscape users, but happens in both browsers.

- Scrolling problems; browser: any

  Not a real bug, but when using DHTML Layers that extend beyond the browsers frame borders there are some differences in how browsers handle this. In Netscape there will be no scrollbars showing up, yet in IExplorer there will always be scrollbars moving. This causes problems any way you want it. If you like the IE style you can emulate it with NS by using the following code:
  `document.width=<pixels>
  document.height=<pixels>`
  This resizes the browsers document showing the scrollbars. If, however, you like it the NS style (no scrollbars) you can add the keyword `scroll=no` in the property of the <body> tag for IE.

- Naming inline layers/variables; browser: Internet Explorer

  One bug/feature in IE causes problems when creating a variable with the same name as an inline layer. It will cause problems in IE, it will not see the difference between the inline layer and the variable. Workaround: use another name :)

# 6.1. Doing advanced things

After reading the tutorials and looking at the examples you might be able to do the most basic stuff, but if you want more there's not much documentation available yet. The examples and widgets should provide you with enough information on how to do more advanced stuff, but for now there's no real method reference available. A Developers reference for the Dynacore is available which is for maybe 10% different from the official DynAPI, and this will be converted into a DynAPI2 reference somewhere in the future (hopefully NEAR)

# 6.2. Limited Javascript knowledge

"I want to use the DynAPI but have limited (or no) Javascript knowledge"
Sadly you'll need Javascript knowledge in most cases. You might get something to work using copy-and-paste development, but once things go wrong it will become difficult to fix things. At this time there are no development tools available for the DynAPI, but hopefully this will change in the future, making it possible to do WYSIWYG development.

# 6.3. Load external content into layers

"How can I load external pages into dynlayers".
The only way to do this is by using the LoadPanel widget, this provides functionality for loading URL's into a normal DynLayer. The LoadPanel widget should be supplied with your DynAPI2 distribution.

# 6.4. Accessing form elements in layers

DynLayers can contain form elements or images, in some cases you'll need to be able to retrieve values from these form elements or set the image source. This can be done using the `.doc` property of a layer. This property refers to the layer's document. So to access a form in a layer this is basically how to do it:

      myLayer.doc.formname.formelement.value

or setting an image's source:

     myLayer.doc.images['imagename'].src=newsource

Note that in IE the image array is a global array, so you can't use the name "thisimage" in two different layers.

back