Closed Bug 24689 Opened 21 years ago Closed 13 years ago
XUL Reference Manual
First draft is available for review. Write comments, additions, feedback, et al against this bug so we can update and keep track of progress on this piece of documentation.
The specified URL did not work for me. Instead, I found a document located at: http://www.mindspring.com/~ioeschger/XULREF/intro.html Is this the correct URL? Thanks.
The URL works for me, though not if you click the URL link directly in bugzilla. The link in the text box is appended to www.bugzilla.org, and a Not Found message results. But if I copy the and paste the URL in the Location box, it works for me.
The link to the XULREF has been updated. Though you can still grab it at: http://www.mindspring.com/~ioeschger/XULREF/XUL_Reference.html for some period of time, the latest and greatest will be at: http://www.coastside.net/~oeschger/XULREF/XUL_Reference.html ...until I put it on mozilla. ian
Status: NEW → ASSIGNED
Updating QA Contact...adding ornduff to cc list.
QA Contact: nobody → oeschger
Ian, couple of nits....I'd change the URL in this form (in the URL field near the top of the bug report) to the mozilla URL. Also, I'd add a hyperlink in the doc itself (at the top of the doc) to the bug report. Indicate that the doc is a draft, and that people can add comments in the bug. Why say that the doc is a "complete reference for the XPToolkit." Why use XPToolkit at all? The relationship between XUL and XPToolkit isn't explained in the doc, but maybe the subject is best not dealt with at all in the doc. But I wouldn't start the doc with that sentence without further explication.
Changed the url. Thanks, Jan. I'll add a pointer to the bug, perhaps a brief explanation of what the XPToolkit has to do with XUL, and a DRAFT note on the front.
Sorry for the spam: updated the intro page for the XULREF per leger's suggestions
Uh, that would be "rudman's suggestions." Thanks for making the changes.
The link to "broadcasters and observers" is broken.
Thanks, Andrew Given the fact that all XUL widgets must be formatted like key/value pairs (e.g., onclick="doFunc()" ), I was hoping to document all the members as attributes regardless of their type. This may have been confusingly consistent of me. I know and love DannyG's layout of the Navigator JS Object Model. Let me look this over.
There is no documentation on the <browser> and <editor> tags. And I just learned that you dont have to use <html:iframe> but can use just <iframe> now... Separating out the methods and stuff is really helpful in that it makes it easier to find them quickly.
There's no reference for the XML "setup" of a simple xul file - meaning there's no entry which explains this header info: xmlns:html="http://www.w3.org/TR/REC-html40" xmlns="http://www.mozilla.org/keymaster/gatekeeper/there.is.only.xul" Also there should be references to: 1) how to insert a stylesheet 2) how to insert js code 3) how to use overlays 4) how to use RDF overlays
I mention the window "preamble" in the window area under the xmlns attribute and others. I need to say more about this. Note also the methods section in the window object's spelling. As for these other omissions you mention, I am hoping to include these in the XUL Programmer's Guide and not here in the widget reference. I've sort of flip-flopped a couple times about the focus of this guide, about sticking just to the actual widgets or broadening to include information about things like how to include a stylesheet. I'll have to look at them one by one. Thanks for all your helpful feedback, Andrew.
How about all page "zip" for download?
Looks like the links to text and image elements doesnt work. It should at least have "under construction" or something there instead of a broken link.
Removed the new icons and made some more changes: * <tab> is now a closed element with the value attribute * oncommand has been added to all the box-derived elements * <titledbox> was added to the box page, though it doesn't actually seem to be working in my build. * <stack> language was spruced up a bit * references to <titledbutton> were squelched Still waiting on <html>, <script>, and a few others before I call it Third Draft.
new version of the zip file checked in -- the third zipped up "milestone", I think.
Added text widgets reference: <text /> and <textfield />. Both of these are begging the XBL question, which I will focus on shortly.
Summary: XUL Reference Manual First Draft → XUL Reference Manual
There is no information in the keyset/key section about the "keycode" attribute on the key element. I discovered this only after scouring through chrome files... might be a good thing to document.
Added keycode attribute documentation to <key> and keyref.html Thanks, Joe.
Added oncreate and ondestroy to popup-like widgets. Files: popup.html, popupref.html, menupop.html, menuref.html. Scouring for more missing events in XULREF per joe hewitt's suggestion.
Added a nice little sample and screenshot of <treecol>, which was underdescribed. Still more work to do on tree-related attributes and events
two points. Please rename Xul_Reference.html to index.html. The way you have it now, its hard to figure out which of the many files in that directory is the top level one. Doing this also lets you use shorter, more intuitive URLs. http://mozilla.org/xpfe/xulref/ It would also make the document a lot easier to use if you didn't use frames. The use of frames makes it so people can't bookmark items or use the history. Also, since you need to set the size of the right menu bar in PX units the layout of the document is wrong for people using nonstandard sized fonts.
Prefixed URL with http:// to make it work directly.
What about a cookbook type section showing how to create a simple UI with a small interface to some C++ code?
Added index.html page per endico's request, but keeping XUL_Reference.html around just in case. For now. pointer is now www.mozilla.org/xpfe/xulref, as it should be. Will also update our own links to this manual. Thanks, Dawn
Added some additional explanation to the broadcastref section per Simon's request. Still working on fleshing out this topic in the xulref.... -i.
Hi Ian, two remarks, first you have a section called "Img Elements", which mislead me somehow, want to call it "Image Elements"? As it is empty right now, I had quite a time with the <img> tag. Browsing the source and moving to <image> just made it easier alot ;-) Secondly, in the second example for trees, the <treehead> section is messed up in the closing tags. Could you add some hints on indenting the children? Thanx, I like those pages, otherwise I wouldn't find bugs ;-) Axel
Added <grid> widgets, <menubutton> and menu updates
Added content windows to xulref. Need some more details, but <editor> <browser> and <iframe> are now under "content windows" in TOC.
Added <html> and html:namespace elements page. Updated index
Hi Is anybody still updating this documentation ? Is this stuff current ? I am thinking of writing a new skin so it would be really handy for me to have a completely updated document for reference. Thanks. Biswapesh.
Adding myself to the CC list.
I'm missing the bulletinboard element. Shouldn't that be in here? There are more XUL elements or attributes in http://lxr.mozilla.org/seamonkey/source/layout/xul/content/src/nsXULAtomList.h that aren't in this reference.
Looks like <template> is missing too
You may want to cooperate with the guy on xulplanet.com. He's keeping his tutorial and reference very up to date. Tutorial: http://www.xulplanet.com/tutorials/xultu/ Reference: http://www.xulplanet.com/tutorials/xultu/elemref/mxdref.html
The 'Content Widgets' section could do with some sprucing up. The differences between <editor>, <browser> and <iframe> widgets should be highlighted. The introduction to all there needs some updating. Has anyone experimented with multiple <iframes>'s? I'm looking to implement some form of multi-doc interface (MDI).
I think you want a <stack/> or <deck/> containing iframes.
The stack or deck with multiple iframes in it apparently doesn't work too well. The iframes compete for rendering space and sort of draw on top of one another.
Yeah, about mozilla had problems w/ this. Refer to Editor which I think solved this problem. At worst you should be able to hide the iframes that should not display.
The introduction includes a section on XUL syntax that says "There are a couple of very slight departures from the core XML syntax, but for the most part, the syntax rules are the same." I'm not quite sure what the "slight departures" are, but AFAIK XUL is a direct *application* of XML. As it reads currently, the section implies that "XUL is essentially like XML". I'd recommend rewriting it to say "XUL is XML". It's fine to summarize XML well-formedness rules that might be new to HTML developers, but I'd definitely include a link to the XML 1.0 spec as the definitive set of rules for any and all XML applications.
The sub-section titled "Organization of XUL Interfaces" in the Introduction says that a package includes "a DTD specifying localization strings in the interface". The role of a DTD is to specify a set of validity rules for an XML application. DTDs can also contain entity declarations which we happen to use as a convenient means of separating localizable strings from the structure of the document. I'd recommend changing the words quoted above to "a DTD that contains entity declarations for localizable strings".
Updated intro.html per vidur's comments. Thanks a lot, Vidur. I will try to make some more updates to the xulref this week based on discussion in this bug and emails I've been getting. Any help 24689-followers can give is appreciated.
It would be nice to have some search functionality exclusive to xulref, as opposed to using the general mozilla.org search.
Made some updates this morning: added observes attribute to box (and its ilk), fixed the observes node documentation, updated the navigation pane and the index, fixed some typos in checkbox.html and others, added hbox and vbox docs. I will be continuing to try and get this doc current.
Added some more: "Layout Managers" section in navbar, <bulletinboard> element (finally), "read-only" to textfield. Changed "Content Widgets" to "View Elements" per andreww's suggestion.
coming shortly: scrollbox, broadcasters docs
adding "equalsize" to box-based elements, got scrollbox fixed
Would it be possible to create a printer friendly version of the document here: http://www.mozilla.org/xpfe/xulref/XUL_Reference.html Either a single view of html or a PDF. I'd be willing to help accomplish this.
added/updated 2/22/01: * grippy element: src and accesskey (more to come here) * "Handles" category in navbar (navbar getting too busy, thinking about new groupings, collapsibility,...) * box.collapsed, box.valign * methods and attributes on tree: tree.selectItem, selectedItems, getNextItem, getPreviousItem, tree.collapsed, tree.getItemAtIndex, tree.valign * removed js from bug link in intro.html * treecell.selectedCell, treerow.selectedRow with DOM examples
added radio.group added observes to all box-derived elements fixed context description in common.html, added it to box attr list (still have to add it to box-derived elements). thanks, neil. Great feedback.
I like to download the Fourth Draft, but I keep getting the Third Draft! After opening the downloaded zip file I see a link to a NEW version. Using this link, I keep download the Third Draft, same link. Yak... BTW, Did anybody here wrote a DTD for XUL?? I have a validator, but I'm missing a DTD.
I notice that you mention box-derived elements; is there a hierarchy? If so it might help if the navigation frame reflects this. To H-J: You can't write a DTD because attributes are user-definable.
Neil, XUL needs a DTD for Internationalization, take a look at this line: "The localized text must be defined in a separate DTD or DTD fragment." Wrtten by danm. XUL is like (X)HTML using a pre-defined set of tagnames, and that can be stored in a custom DTD for validation. For Ian: 1 - why didn't you mention a link to the: "XUL Programmer's Guide" in index.html? 2 - why didn't you include a link to a history section (this way we know what files you changed). 3 - where can we find the milestone for the next draft? Can you include that into the manual? 4 - when will you make a new zipfile for the link? The text "new" now is rather odd because it links to an "old"(er) zipfile.
The reason dtd's will die is contained in this invalid line: XUL is like (X)HTML using a pre-defined set of tagnames, and that can be stored in a custom DTD for validation. XUL does not exactly use a pre-defined set of tagnames, or at least not one that a validator can know w/o having access to the entire application. however, our dtd's have a much simpler structure :-)
H-J: In Mozilla DTDs are being used as localizable entity holders and not, as you might imagine, as document type definitions. I'm afraid timeless is right about the difficulty and unlikelihood of having a real XUL DTD some time soon, though you _can_ make subset DTDs that do a good job or parsing what they do know and ignoring what they don't, which is as close as I think we will get. And I'm not sure I understand what you mean about the link to the XUL Programmer's Guide. You mean on the docs index page? And what is the XUL Programmer's Guide. You mean the xultu? Please advise here. Zip file and history: I will make a new archive when I update the draft--whose changes I will continue to note here, but maybe you're right and I should do a history in the doc. I lose out on the cvs history goodies by getting rid of the mozilla menu, and maybe I should find someone to get that in (particularly given someone's recent recquest to have the xulref look more like a mozilla doc). Thanks, H-J
Right, I will only use a custom build DTD for XUL to validate my documents. and yes I mean the text "For more detailed information, see the XUL Programmer's Guide." in your index.html. What's that, where can I locate that file? Note, I wrote an XUL edition of your index.html, as an examples. The menu uses tabs, documents are displayed with <browser>. Psssssss, whispering: "i'm writing a new tageditor for HomeSite. I'm also working on a custom XUL CodeSweeper for HomeSite. Templates are finished already. But I didn't told you this, Ok!"
Title boxes is missing a </title> It is: <titledbox style="background-color: lightblue;" orient="vertical"> <title> <button value="Click Me" /> <button value="Push Me" /> </titledbox> It should be: <titledbox style="background-color: lightblue;" orient="vertical"> <title>My title</title> <button value="Click Me" /> <button value="Push Me" /> </titledbox>
Missing the <stringbundle> and <stringbundleset> elements
.... and the (new) command="" attribute
see bug 70746 and bug 70747 <textfield/> is now <textbox/> value changed to label for several entities (but not all) Adding a dependency on hyatt and ben's xul 1.0 bug
Depends on: 70753
made xul 1.0 changes (still a few more to do): value -> label in many cases, textfield -> textbox, menulist.data -> menulist.value. Will add commands attribute all over the place today, along with context. Calling it fifth draft, will make a new zip.
Iano, the section on 'View Elements' needs updating - specifically the pages on the <browser>, <editor> and <iframe> elements. It would be nice to have a little on the differences between then (especially <iframe> and <browser>), e.g the interfaces available via the bindings for these elements.
I recently posted about using the FAQ-O-Matic for this (see my post in n.p.m.webtools), what do you think?
I setup a playground so that you can see how the faq-o-matic works and how it might work for this. http://220.127.116.11/cgi-bin/fom.cgi Enjoy!!
Zach For some reason, I could look at the entry you made but could not access the Appearance thing, add new entries, or Search. It's looks cool, though. Actually, Dawn Endico was talking about doing some kind of end-user documentation site for mozilla.org with a tool like this. It's a very compelling way to get work done. Anyway, I like the idea of doing something like this. I wonder how navigable the xulref would be in this format, however, given its size. Like: Mightn't the xulref start to fracture in a FAQ structure like this (e.g., someone would start putting attribute descriptions as siblings of a XUL element, and this might confuse readers). I assume you mean we would move the existing docs into a framework like this and then have people add entries about things they know. Let's talk. What does everyone else think? Votes? Other approaches?
I'll look into the permissions and start converting in entries
Ok, permissions fixed!
Just my personal opinion, whenever I see a faq-o-matic, I get discouraged. The ones I have seen so far lacked the answers to my questions, and in general tend to provide the questions people can answer, instead of answering the question newbies have. And the colors are disgusting ;-), so you know right away what you're in for. The ones I saw had too many subcategories. It's not that I don't like the concept, but the ones I saw so far made me leave fast. I prefer one owner of a page, keeping the content simple, with a tough structure. Axel
Thanks for bringing this up, as it gives me a chance to talk about some of the 'myths' of the faq-o-matic. First of all, I can change the colors, if we go live with this, that will certainly be done. Secondly, I was planning on allowing only a select group of users the option to do more radical adjustments. Any user will be able to make comments, etc... But only those who have been pre-screened can move around categories, make sub-categories, etc... We can work out the exact permissions setup later. To avoid the "sub-category happy" problem, I am trying to work out an arrangement now, which will keep the structure reasonible. Once this is set, I can set things so that only a very small group of people have the authority to change it. Also, the system can save the whole thing in other formats, so that if you wanted, say, a text document with the whole xul spec, it's just a few clicks away... I am going to post a schema here soon, that will show how I plan to lay things out. As always, comments are expected.
I changed the color scheme, it isn't perfect, but it doesn't make me puke! I also started to add categories, let me know what you think. Zach
Can't you have a little link at the bottom the the page `Add an entry' or `Help us with the documentation', and then if you bring up that, you get the form on the page? That way, we can have all the textfields and stuff hidden as long as the user/reader doesn't want to fill out an entry.
Doing that would require chaning the perl source. I COULD do it, but would rather not, as it makes upgrading a problem. What would also work is to tell people in a blob on the front page that they may choose apperence and set settings there if they wish to contribute. Note that what everyone is able to do now will be restricted into groups. I was thinking that we could have one group: xulref_lovers, which can do anything (somewhat like a despot in despot), another group called xulref_friends which can't move categories around and trash categories, etc... Anyone else would have a reduced set of permissions. Also, the individual sub- categories can have different permissions, so one category can let anyone do anything, while another is much more restricted (the front page could work this way). We can work out the details later. For now, I will leave things as they are, so that you can get a feel for the platform.
Ian, can you please change the tab info because this one is using label now instead of value.
Attribute 'read-only' for <textbox> should be changed into 'readonly' And what about adding attribute 'disabled' for <textbox> that one is missing now.
Just checked in some tab doc updates. May need another pass through these. Let me know if I missed something
Ian, can you also change the 'key' documentation and add an complete and working example how to setup key interception. I will add an example, but you don't have to use it at all.
Great example, H-J. I will put it in the xulref today.
XULRef needs to say something about the syntax for pref tracking - pref="true" preftype=bool" prefname="foo.bar.baz" etc. etc. Gerv
There don't seem to be docs on <outliner>
See bug 90314 for the new widget, <spinbuttons/> that I'm implementing. This will need to be documented, I guess, and I can do the legwork if someone else wants to take care of the formatting...
I missed description and label, as well as deprecation notices for html, tree and other pre XUL1.0 friends. (Lost track, but we have dependencies;-)) Axel
*XULREF OVERHAUL* Finally making a concerted effort to get the xulref updated per XUL 1.0 and its myriad recent changes. Have a long way to go, but new documentation pays quite a bit more attention to xbl, has a structure that makes it easier to maintain (i.e. has various "articles" that explain concepts, then element pages, separate attribute pages, and so forth), is concise and pleasant to look at, and can be previewed here until I move it onto mozilla.org: www.brownhen.com/newref/xulref.html I am working currently on the xbl primer doc, available at: www.brownhen.com/newref/d_xbl.html Now is a great time to take a look and help me get things organized, get everything represented, contribute articles or descriptions, make suggestions, complain about how it looks terrible in browsers that are not Gecko-based, & cetera. As you can see, it's little more than a shell right now. As I get a little further along (but well before it's "done"), I will spam the newsgroups and make more noise. Thanks a lot. -ian
My god i just searched for XUL stuff on google.com and it came up with your brownhen stuff..wow...anyway I am in the process of totally reorganizing how the documentation index page is done (much better now) will have a beta site up soon. Letting you know. BTW i have had a hell of time trying to figure out what goes where with stuff being spread out of over xpfe, xptoolkit, xul etc.
The xulref at www.mozilla.org/xpfe/xulref is SO far behind (which is why I am working on a totally different version, noted in the comment above, maybe not available for the moment now that I have a new ISP), but I've made some updates per recent requests: fixed menulist attribute is selectedItem, with a capital "I", grid documentation is being updated per evaughan's thoughtful suggestions, and there is an updated version of the zip archive at www.mozilla.org/xpfe/Xulref.zip (note the initial cap).
When using Build ID: 2002031104 to preview the renedering of the following code in an XUL document, the XUL widgets do not display properly. The test examples were taken from the XUL Programmers' Reference Last updated: 02/28/01. Is the proposed XUL standard fully emplemented in this build? <?xml-stylesheet href="chrome://global/skin/" type="text/css"?> <window id="new-menu-stuff" xmlns:html="http://www.w3.org/1999/xhtml" xmlns="http://www.mozilla.org/keymaster/gatekeeper/there.is.only.xul"> <menubar> <menu name="File"> <menu name="New"> <menuitem name="Navigator" cmd="commandid:newnavigator" /> <menuitem name="Message" cmd="commandid:newmessage" /> <menuitem name="Blank Page" cmd="commandid:newblankpage" /> <separator/> <menuitem name="Blank Page From Template..." cmd="commandid:blankpagefromtemplate" /> </menu> <menuitem name="Open" cmd="commandid:open" /> <separator/> <menuitem name="Close" cmd="commandid:close"/> <menuitem name="Save As..." cmd="commandid:saveas"/> <separator/> <menuitem name="Quit" cmd="commandid:quit"/> </menu> <menu name="Edit"> </menu> </menubar> <tabcontrol align="vertical"> <tabbox align="horizontal"> <tab value="Tab One" /> <tab value="Tab Two" /> <tab value="Tab Three" /> </tabbox> <tabpanel flex="100%"> <button value="View One"/> <button value="View Two"/> <button value="View Three"/> </tabpanel> </tabcontrol> <titledbox style="background-color: lightblue;" orient="horizontal"> <title value="Nice Buttons"> </title> <button value="Click Me" /> <button value="Push Me" /> </titledbox> <box width="150" orient="vertical" autostretch="never" style="border: solid 2px; background-color: lightblue" valign="baseline"> <button value="button1" style="font-size: 12pt"/> <button value="button2" style="font-size: 12pt"/> <button value="button3" style="font-size: 12pt"/> </box> </window>
yeah, it is really exciting... but how can i distribute my software? ask users to install mozilla or ns6 first? replace their ie or other stuff? do you have a min-size set of dll(s), so(s) or other image that i can combine with my code?
The zip file needs to be updated to reflect fifth draft!
Hi all, I've just downloaded the 1.3a version of Mozilla for Window$. I noticed : - "image" attribute for <button> elements is said to be "src" in XULRef...but "src" does not work - "position" attribute for <popup> elements is not described in the XULRef I also tried to set a "checked" attribute to a <menuitem> without success. ... <popupset> ... <popup id="examplesMenuPopUp" position="at_pointer"> <menuitem label="NCBI" oncommand="" checked="true"/> <menuitem label="Toto" oncommand="" checked="false" /> </popup> .. </popupset> ... <box context="examplesMenuPopUp"> <description> Let's popup ! </description> </box> ... Did I miss a link to an update of XUL Programmer's Reference ? Thanks for your attention, Luc.
> I also tried to set a "checked" attribute to a <menuitem> without success. You need to use <menuitem type="checkbox">
Is there an XUL DTD to validate against? If not, I'd like to try to put one together.
It seems that in a <grid> you can nest <rows> tags. This is useful if you want to repeat a multi-row block of data with XUL Templates. If this is an intended feature (which I hope, since it works), maybe it should be mentioned in the manual? Here's some code to illustrate this: <grid datasources="datasource.rdf" ref="urn:root"> <template> <rule> <rows> <rows uri="rdf:*"> <row> <label value="identifier:" control="identifier" /> <textbox id="identifier" value="rdf:http://purl.org/dc/elements/1.1/identifier" /> </row> <row> <label value="description:" control="description" /> <textbox id="description" value="rdf:http://purl.org/dc/elements/1.1/description" /> </row> </rows> </rows> </rule> </template> </grid>
XUL menu.label example error On http://www.mozilla.org/xpfe/xulref/menuel.html#label the example for Label is missing the > at the end of the tag. It ends with "/" rather than "/>"
moving stuff over to an outside-the-firewall email for the time being, looking for people to pick these Help and doc bugs up for me.
Assignee: oeschger → oeschger
Status: ASSIGNED → NEW
taking over some of Ian's bugs
Assignee: oeschger → stolenclover
The link http://www.mozilla.org/xpfe/Xulref.zip points at an old zip file, which contains the fourth draft of the reference. The online pages, instead, are on their fifth draft. Anyone who may update this?
zipped HTML version is of the fourth edtion of the reference manual. the webpage is the fifth version.
http://www.mozilla.org/xpfe/xulref/tree.html#getAt getItemAtIndex has wrong description. This is a good resource, but something definitive (like a W3C TR sort of thing) would be invaluable not only to aid developers, but to encourage new developers.
Note http://groups-beta.google.com/group/mozilla.dev.mdc/browse_thread/thread/3f4bafbecc948443/351691938127962e#351691938127962e I want to redirect this reference to the XUL reference on MDC http://developer.mozilla.org/en/docs/XUL_Reference, which is much more up to date. If anybody knows of useful information in http://www.mozilla.org/xpfe/xulref that's not in the MDC reference, please migrate it to MDC (feel free to consult with me if you're unsure).
filed bug 367834 for removal of the reference.
Status: NEW → RESOLVED
Closed: 13 years ago
Resolution: --- → INVALID
You need to log in before you can comment on or make changes to this bug.