[docs] Custom control documentation should be updated

RESOLVED FIXED

Status

Core Graveyard
XForms
RESOLVED FIXED
12 years ago
2 years ago

People

(Reporter: surkov, Assigned: surkov)

Tracking

Firefox Tracking Flags

(Not tracked)

Details

(URL)

Attachments

(1 attachment, 1 obsolete attachment)

16.98 KB, text/plain
aaronr
: review+
Details
(Assignee)

Description

12 years ago
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?

Comment 1

12 years ago
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
(Assignee)

Comment 2

12 years ago
Created attachment 241568 [details]
page1

That is the first try. I need advice.
Assignee: xforms → surkov.alexander
Status: NEW → ASSIGNED
Attachment #241568 - Flags: review?(aaronr)

Comment 3

12 years ago
(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.
(Assignee)

Comment 4

12 years ago
(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.

Comment 5

12 years ago
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.
(Assignee)

Comment 6

12 years ago
(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.

Comment 7

12 years ago
Created attachment 242084 [details]
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)
(Assignee)

Comment 8

12 years ago
I putted your version with minor changes on mdc. Also I posted bug 356508 for following up work.
Status: ASSIGNED → RESOLVED
Last Resolved: 12 years ago
Resolution: --- → FIXED
Product: Core → Core Graveyard
You need to log in before you can comment on or make changes to this bug.