2.4 "Modeling Application Data" docs need clarification, and other frustrations

I've been trying to muddle my way through implementing Collections, DataRepeaters, and bound properties in my app, and frankly the Modeling Application Data documentation is not helping very much. Specifically, there are several things driving me nuts about the "Binding Models and Collections to Views" section:
  • The very first code segment (which is fairly lengthy) represents something you should not be doing. Why are you even showing me this? I don't need to be sold on using bindings; I already know they're saving me code. If you want to sell them, stick that somewhere more general. This is confusing and makes the documentation difficult to reference after the initial read-through.
  • The "Binding in Collection-Aware Controls" sub-section does the exact same thing. I know how to use Repeater, and if I didn't I would be checking the documentation on lists and repeaters. Show me how to use DataRepeater, please.
  • When we finally do get a code segment illustrating DataRepeater, it leaves several questions unanswered: How on earth does the DataRepeater know that it should access the Collection defined in the data property? Is this some sort of naming magic? If so, where is this documented (because it sure as heck isn't mentioned anywhere in this documentation or the API documentation that I can find)? Is there any way to define a DataRepeater with a specific collection linked to it inline without needing to leverage special "magic" names (this is, again, not mentioned in the API docs at all)? Why is the binding from string ".model.PROPERTY" when further up it is explicitly stated that a leading "." means "this", and the DataRepeater has no published model property or method? Why is DataRepeater the only Component I have ever seen to hijack the components array to use a non-Component anonymous object that in turn has a components and bindings property?
I tried delving into the DataRepeater source code to see if that would answer some questions, but even there I'm stymied. There appears to be an undocumented (and undeclared) "collection" property, but it's aliased as "data()". Should I be accessing either of those things at all (data is @protected)? The API docs mention that DataRepeater inherits from Controller and its chain of kinds, but it doesn't have a "kind" property anywhere, so I am unclear on what the actual chain of inheritance is (leaving me unable to dig up the chain of parent kinds to see if this stuff is declared somewhere higher up).

Overall, trying to use Collections and bindings has been extremely frustrating, and I'm starting to wonder if I wouldn't have saved more time just implementing standard lists with by-hand updating, extra code and all.

Comments

  • edited April 2014
    Thanks for your feedback - we are definitely working on updating our documentation as that is a high priority of ours right now, but I can understand some of your frustration. :) In the meantime, if you haven't looked over it already, here is a Moonstone tutorial that has serves as additional guidance for using the Data layer: http://enyojs.com/docs/2.4.0-pre.1/getting-started/moonstone-app-tutorial.html

    To answer some of the questions you had: the collection and model properties are indeed special properties; you should only be setting the collection property and not data. The API documentation you're looking at might be outdated in terms of talking about controllers, sorry about that!
Sign In or Register to comment.