View Full Version : Documentation holes for Touch creating 2.x custom components

26 Nov 2012, 3:48 PM
There are several patterns for creating new UI components.
The one's I've identified so far are ..

No inheritance
Render UI using template (example is the recently blogged Audio control)
Inherit from Field types (Decorator and non Decorator cases)
Inherit from Container or Panel - Render UI using items array (static and non-static) containing nested xtypes.
... I'm sure there are more ...
Each of these requires quite different coding patterns to construct and due to poor documentation you have a to chase all over the place to try and figure out and find the pattern you need. Since the recent ST 2.x class model changes the patterns have all changed. What we badly need in docs is coverage of each of the different patterns for creating custom components - and all in once place! This is so a beginner can identify the pattern they need and then code from a boilerplate example.

Bits of information are in the ExtJS docs for Components but its unclear how much of this applies to ST 2.x .

The docs also need a table or diagram summary of the firing sequence of events and what's expected in each override. If an override should call a parent, it need a summary of what to put to before and after the parent call. This should nail down best practice. The boiler plate code should have placeholder comment for each of these so you can just copy paste the pattern code and fill in the blanks. I think this would reduce the support cost on the forums and get everyone coding to the right patterns.

Note: I'm currently trying to find one for inheriting from a Container that renders using an initial items list that is adjusted in the constructor. Can't find any examples for ST 2.x . Recent Blog post on Component building is no use as its based on rendering templates.

28 Nov 2012, 10:50 AM
Documentation, guides, tutorials, examples are all things that are always work in progress. Some things that you mention are quite advanced techniques and can be learned by looking at the source code which has been the best way I have learned how things work on things I haven't worked on.

2 Dec 2012, 4:45 PM
I agree that creating components is probably beyond the 1st step for beginners - but you really need some rail tracks / guidelines to pick the pattern you need for a given component.

The recurring questions are:

What event do they expect me to use to handle something?
How has this changed in this release?
Defining exactly how each type of component is designed to be built in a framework is, IMHO, an essential part of the framework. You're declaring how you intend developers to use the events, overrides and properties for each pattern case.

You can go reverse engineering in the code or surfing for an example but the problem with that is that you have no idea how well supported this pattern is likely to be in the future or if the example code you find is now out of date. It's also not clear if the Sencha team has given these design patterns much thought. I'm sure they probably have - but without coding guidelines I'm just killing time playing guessing games with the risk that it will all break on the next release. I'm trying to read the mind of the framework designers and cost of failure is high on big projects.

Giving coders the correct "kick start" means we're much more likely to follow "best practice" rather than "guessed practice" based on reverse engineering. Invariably you miss an important step (often just a single line of code) that can take days to crack. If you're luck enough to be "in the know" about Sencha it can be hard to see what it's like for those starting out.

An alternative might be to create a github account with boilerplate examples for each of these cases.