Documentation Ideas.

[Symbi0nt]

Hi there,

after searching the forum I found out that you are working on the docs right know. I hope that is still the case, so I don't want to bother here around.

I consider myself as a not so bad javascript coder, but I'm on frameworks it depends really on the documentation and examples what I can achive or not and in what time.

The documentation is right know very basic imho. So it's like running it with a JDoc like program, so every method/property has its basic tag who don't say that much.

Right know I'm trying to get a menu/menutoolbar to work with just some clickable items. No colorpicker, no checkboxes just Items. In the docs there is a "TextItem", a "Item" and a "BaseItem" everything could be the one I need. Well I don't know, because The docs to that kind of item tell me almost nothing. No text what this actually is or what it can do.

So here my little advice if you want a growing base of ext users.

If it is possible for your Doc Tool to add pictures and sourcecode, a tiny example with a screenshot (trimmed) who it will look like at the top of the documented page would be very nice. Well that is for widgets good I think.

A text which tels me that this is an base class I should use subclasses A, B, C or D to get what I want would be nice too.

I miss that kind of stuff very much.

[jack.slocum]

Did you look at the example in the menus directory of the download? It very simple to set up a menu.

IMO running samples are more informative than screenshots.

[Symbi0nt]

Well I did.

You as an advanced user and developer of your own framwork might find it not usefull, but to get ppl started and WORKING with the API it might help.

May be you know your API so well, that you can't _see_ problem of other ppl like an book author how can't see anymore mistakes in gramma also by reading over the page for the fourth time.

For example right off my day:

I use a 1:1 copy of your complex layout example. The one with north, center, west etc. I gave up with that tree thing and added in the west panel a link with an ajax call to prototype. And I would like to check if the panel in the 'center' already exists which I would like to put the data in it. So I checked the source and there was:

[...]
layout.add('west', new Ext.ContentPanel('west', {title: 'West'}));
layout.add('east', new Ext.ContentPanel(Ext.id(), {autoCreate:true, title: 'Dynamic Tab', closable: true}));
layout.add('east', new Ext.ContentPanel('autoTabs', {title: 'Auto Tabs', closable: true}));
layout.add('center', new Ext.ContentPanel('center1', {title: 'Close Me', closable: true}));
layout.add('center', new Ext.ContentPanel('center2', {title: 'Center Panel', closable: false}));
[...]

Ok, I think a simple call to he layout object could help me and I'm done with it.

So I made the 'layout' variable public in the whole document at first and then I wrote a function like this:

function onFooBarLoading() { if(!$('newTab')) { layout.add('center', new Ext.ContentPanel('newTab', {title: 'Persons', closable: true})); }

Well nothing happend on the page. I added layout.beginUpdate(); and layout.endUpdate() around that layout call, but still nothing happend.

Well I set some BP in FireBug and steped through it, but it seems that JS ignores what it should do. Anyway. I set up the 'newTab' static and was done with it. No Idea though which syntax I dynamicly have to add a new tab. "My way" which I assumed sounded ok to me.

May be later in development I will come back to that point and have a 2nd look. May be some call to a special update function I have forget to call or so.

[Joe]

We purchased a five person developer license and love the toolset - it is the best.

That said - and to this persons point, I have been heads down on this for a month and had to read LOTS of code and do lots of debugging to make things even work. The root of the problem is the starting point provided in the examples.

If you look at the main documentation file - it opens in an iframe. So if you say - 'ok - let me copy this and try to "move foward" ' - bad. Open 20 pages using Ext in each iframe and your system turns into a slug and 100 meg of memory is used up (was a load test).

If you copy any example (outside of chooser), they hard code the divs. Doing this is bad, now you use a content panel and update manager - open up 2 example files and boom - does not work because it loads the widget into the first loaded div.

There is no explanation of this nor any details on how to work around this or how to correctly write applications using this framework. The examples are exactly how you should not program using this framework.

I think providing examples that are more in line with how people should be programming and providing some basic docs on good and bad practices should be top priority.

I realize you can not put "rocket science - 20 page code chunks" out there, but some basic examples and then some more advanced examples may help.

I not want to sound like I am saying "the docs are bad", they are very helpful and well structured. However the direction the examples send you in is bad.

Hope this feedback helps.

[Symbi0nt]

I'm scrolling through the classes and found that some mainclasses already have a nice describtion text and a example code. This is nice. I guess I just read the classes which are not fully documented.

Instead of pictures there are links to your blog jack. Good idea in the first place, but in 2 years your blog might have changed or your provider had a disc crash.

[cdomigan]

Joe, I completely agree. I had several false starts and wild goose chases doing what I thought was the right thing (I too copied the docs to start with!). Even now I'm only half-convinced I've got my basic structure right

[jack.slocum]

On the docs:

This is why it only uses 1 iframe. It presents no loading problems or memory issues. It was not intended to be an example of how to create 20 iframes, as I would never recommend doing that.

The examples are exactly how you should not program using this framework.
Each example demonstrates the use of that component, not overall application setup. There is nothing currently in the examples on setting up the base for an application as the needs of the application vary by the application.

[brian.moeskau]

I've been working on the docs, and I'll add that there are two primary goals: 1) coverage, and 2) adding extra descriptiveness and inline examples beyond the basic description. For the 1.0 release, the primary focus is on #1 since there is just so much to document, but as time allows, #2 will become more and more the goal. We're also hoping that as more tutorials come online, having code directly in the API docs will become less important.

Regarding examples, can you point to examples in ANY language or framework that demonstrate application-level best practices? Almost every code example in existence is meant to demonstrate a very narrow slice of functionality, that is the nature of examples. That said, we recognize the need for some architectural/application-level best practices and examples, and we have some things in the works. Only 24 hours in the day, you know

[Joe]

Thank you for you replies.

Your docs are nice - just providing some basic feedback on the direction I see people going. As you can see from my other posts, I am providing code to show how to not use frames at all. But like cdomigan - I am only 1/2 convinced that my overall structure is correct.

Due to lack confidence in direction - I have been playing with iframes and worked out a way to connect to the existing Ext and parent object from within a frame. Ext is 'connected' to the document in which it was created in not the iframe doc. The iframe has it own doc and window, unlike the Ajax loaded pages. I'll post details in the other threads when I have a good sample - and see what discussion that brings.

Using the forum works for now - nice that you have it and are active in it.

Cheers

[tad_scsi]

The 'best practices' thing has been the biggest stumbler for me, as well. I was hoping to get my head around this stuff enough to hopefully give others some direction on that, particularly from the angle of roll-your-own widgets and secondarily from the perspective of graceful degradation. I wish we could all forget about people who don't enable JavaScript because they are paranoid, but I have stumbled into two such souls in just the last month. For back-end or intranet applications we get to dictate the environment and heavy dynamic generation is not bad, but a boon.

On front-end, open to the world apps like e-commerce sites I prefer to not look terribly 'canned' and not too 'desktoppy' - and therein are my biggest questions. Though I think I am getting the hang on some of that - I often wonder if I am using the right tool. BorderLayout is an excellent solution for the back-end, but too heavy perhaps for a looser looking general page where you may not want the layout so tightly structured, yet you want the excellent re-sizing control and cross browser problem solving the BL gives you. I'm GUESSING I should start with a Layer as a page container and then use other containers within it when necessary.

That's the sort of stuff I have been experimenting with and hope maybe to find some good approaches and share them. It's totally understandable at this stage that such detailed doc.s are not yet available and, when comparing to many other toolsets/frameworks out there, I'd say these guys were further along in their documentation than certain others that have enjoyed larger teams and a lot more publicity. In general, friendlier and not quite so arrogant either.