Document how to customize widgets

[Ben Smith]

It would be nice to have documentation on how to customize form widgets. Here's an example of something that I just figured out, and that would be nice to see in the documentation.

You can customize how a widget is rendered by overriding it's renderer.render method. This class renders radio buttons as a horizontal line, instead of in a list.

class HorizRadioRenderer(forms.RadioSelect.renderer):
    def render(self):
        """Outputs radios"""
        return mark_safe(u'\n'.join([u'%s\n' % w for w in self]))

[bjunix]

I am also missing documentation on how to actually write your own custom widgets. Is this worth a separate ticket?

[fadeev]

finished reference for creation of custom widgets, improved cross-linking between form-fields, widgets, and form media pages, changed link on main page from Built-in widgets to Widgets

[fadeev]

Reference part for the Custom Widget is done, still need to create a topic guide, which probably should be a separate ticket.

Also, organized the widget.txt doc a bit - split widget classes into several logical groups and added section on how to add media to the widgets.

[Russell Keith-Magee]

@fadeev -- You only close a ticket when it has actually been committed to trunk. You're looking for the 'has patch' flag -- that tells other people that there is a patch that needs to be reviewed.

[dmclain]

This ticket may be superseded by #15667, specifically RadioSelect.rendered is being deprecated and the widget API is being overhauled/documented. Documenting the current behavior in 1.3 may be counterproductive by encouraging people to develop against an API that is going away.

[Julien Phalip]

The doc about widgets has recently been improved in [16408], however there are still several bits from the patch in this ticket that are worth considering. The patch now needs to be updated to fit with the latest version of the doc.

[Jacob]

Milestone 1.3 deleted

[Tim Graham]

I'm working on updating the patch from fadeev

[Tim Graham]

Updated parts of fadeev that are still applicable

[Claude Paroz]

Globally looks good to me. Some minor typos: "is is combined", "which is probably is", "customise", "all memeber". You might also want to capitalize 'css file's to 'CSS files' for consistency.

[Tim Graham <timograham@…>]

In a73838fde33374573b8e765dfcb0225287d396c0:

Fixed #11185 - Expanded docs on customizing widgets; thanks fadeev for the draft patch.

[Tim Graham <timograham@…>]

In 1b5b8b874fb79a8d2b2bc7ca8f93535ff8196167:

[1.4.x] Fixed #11185 - Expanded docs on customizing widgets; thanks fadeev for the draft patch.

Backport of a73838fde33374573b8e765dfcb0225287d396c0 from master.