Closed Bug 348819 Opened 18 years ago Closed 18 years ago

[docs] Custom control documentation should be updated

Categories

(Core Graveyard :: XForms, defect)

defect
Not set
normal

Tracking

(Not tracked)

RESOLVED FIXED

People

(Reporter: surkov, Assigned: surkov)

References

()

Details

Attachments

(1 file, 1 obsolete file)

16.98 KB, text/plain
aaronr
: review+
Details
When next xforms version will be ready to ship then we should update Custom Control documentation at http://developer.mozilla.org/en/docs/XForms:Custom_Controls.

1) I guess we should tell about @typelist attribute.
2) We should provide info about our base bindings. Now example on "Custom Controls" page can be simplified since it can be inherited from 'xformswidget-output-base'.
3) It's better to put other example because current one is wheel invoking since output[mediatype] will be in xforms package.
4) We should provide a link to see how the example work.
5) It's better to have examples for xhtml and xul both.
6) We should say that user can extend only standard widgets in nice way. And he should use types or mediatype in common case for that.
7) And if he wants to put new widgets (of non xforms tagname or namespace) then it can do some magic by placing xf:input and etc into his widget since bug 306526 is not fixed and nobody knows when it will be :).
8) And at the end, we should say about what xforms version we write this all.

I guess we should tell all about our xforms controls creating practice :). Thoughts?
Marked this blocking 0.7 release (bug 334603) for now.  We can remove it later if we decide that we aren't ready with it.

Some simple examples might be especially nice.  I've written a couple of custom controls samples for people to do things like putting a maxlength on a xf:input, for example.  And I've been asked about how to show a disabled trigger, so if I get that control bind done in time, that might be nice to reference.  Neither are fancy, but useful when converting an HTML form to XForms.

We should do a simple scripting example or two, too.  To show how to get to get to the instance data via script, maybe using XPath, and also modifying it and rebuilding, etc. the model.  Been asked about that a couple of times, too.

XUL examples would be awesome.  Great for regression testing, too.

We'll end up having a sizeable list of stuff to do to make this this well documented and easy to use.  I'm more than ok with splitting some of this stuff out into other bugs to make this work more manageable and do a little bit for each preview we release.
Blocks: 334603
Attached file page1 (obsolete) —
That is the first try. I need advice.
Assignee: xforms → surkov.alexander
Status: NEW → ASSIGNED
Attachment #241568 - Flags: review?(aaronr)
(In reply to comment #2)
> Created an attachment (id=241568) [edit]
> page1
> 
> That is the first try. I need advice.
> 

I'm about 1/2 way through my editing.

You probably need to determine what the best way is to link to example files.  Do they want example files to live on the wiki or elsewhere?  We could put them up with our samples.
(In reply to comment #3)
> (In reply to comment #2)
> > Created an attachment (id=241568) [edit]
> > page1
> > 
> > That is the first try. I need advice.
> > 
> 
> I'm about 1/2 way through my editing.
> 
> You probably need to determine what the best way is to link to example files. 
> Do they want example files to live on the wiki or elsewhere?  We could put them
> up with our samples.
> 

I talked with asquella on #devmo. He said we should post bugs about upload request on mdo product. So, I guess we can leave this changes for 0.8 (0.75) version. Probably we can leave 'example' section as it is since it is I belive steal work and bugs fixing of other component can take some time.
I'm almost done with my editing.  One thing I've found today is that I don't think we should even mention the nsIXFormsDelegate interface.  The custom control author should really ever have to call any of these directly.  For example, widgetAttached be done automaically for them by wiget base binding and they can get access to the accessors through the widget base binding, too.
(In reply to comment #5)
> I'm almost done with my editing.  One thing I've found today is that I don't
> think we should even mention the nsIXFormsDelegate interface.  The custom
> control author should really ever have to call any of these directly.  For
> example, widgetAttached be done automaically for them by wiget base binding and
> they can get access to the accessors through the widget base binding, too.
> 

You are almost right. Regular xforms custom control author don't need to know about nsIXFormsDelegate interface because he should use our base XBL bindings. But we have example where need to delay widgetAttached call. It's range for xhtml. Probably xforms custom control author will be forced to do it also. But it's rather exclusion than often used thing. I guess we can file new bug for this and leave this one without nsIXFormsDelegate description.
Attached file page1 v2
edited content of page1 and removed nsIXFormsDelegate section
Attachment #241568 - Attachment is obsolete: true
Attachment #242084 - Flags: review+
Attachment #241568 - Flags: review?(aaronr)
I putted your version with minor changes on mdc. Also I posted bug 356508 for following up work.
Status: ASSIGNED → RESOLVED
Closed: 18 years ago
Resolution: --- → FIXED
Product: Core → Core Graveyard
You need to log in before you can comment on or make changes to this bug.

Attachment

General

Created:
Updated:
Size: