Clarify attachTo documentation/add default direction

[mister-walter]

Both #129 and #130 are related to users not realizing that a direction is required in an attachTo string. I also ran into this issue, though I eventually realized that this was a requirement after going through the javascript on the demo page.

The documentation does state that the attachTo string must be 'of the form "element on"', but I think that it would be of benefit to the users to add a note or warning somewhere stating this more clearly.

For the future, it might make sense to have a default direction value so that the user doesn't have to think about this detail unless they want to change it. Alternatively, it might make sense to throw an error or at least log a message to the console if a user doesn't provide a direction in attachTo.

[RobbieTheWagner]

I think we should potentially throw an error or at least a warning, as I think a default might be unclear to some people.

[RobbieTheWagner]

@BrianSipple @chuckcarpenter any ideas about how to make this clearer, document better, provide defaults somehow etc? Perhaps we should just standardize the API and force it to be object form, instead of a string, after we release 2.0?

[BrianSipple]

I think the clearest design would be to have two attributes -- say, attachTarget and placement.

We separate the concerns of targeting and placement, and it's a clarity win-win for users and our code -- which wouldn't have to worry about objects or strings or parsing any potential combination of the two 😄.

... but yeah, if we go that route, I can definitely see it being a 3.0 change.

[RobbieTheWagner]

I like them being colocated, but we could enforce only one format.

[BrianSipple]

In that case, I think an object is the better choice. It's declarative and unambiguous for both sides.

[stale]

This issue has been automatically marked as stale because it has not had recent activity. It will be closed if no further activity occurs. Thank you for your contributions.