Docs not comprehensive

[courajs]

urlTemplate: '{+host}/posts/{postId}/comments{/id}', What does it mean to put the + or the leading / in the brackets?

What arguments are available to the urlSegments callbacks?

[amiel]

Yes. This is very true.

Until I (or someone else) gets to improving the documentation, here are a few answers to your specific questions:

+ tells url templates not to escape the field (for example, without the +, a host might end up being http%3A%2F%2Femberjs.com)

A leading / inside the bracket includes the slash only if there is a value. For example:

var template = new UrlTemplate("/comments/{/id}");
template.fillWithObject({ id: "1" }); // => "/comments/1";
template.fillWithObject({}); // => "/comments";

Full documentation on url-templates can be found here: https://tools.ietf.org/html/rfc6570

urlSegments get these arguments: (adapter, type, id, snapshot, query)

[courajs]

As discussed in #4, we should mention escaping:

But yes, I think it would be better if {+namespace} alongside {namespace: '/api'} was the default example.

[courajs]

urlSegments get these arguments: (adapter, type, id, snapshot, query)

It is actually called with adapter as this, with arguments: (type, id, snapshot, query)

[courajs]

We should list the *UrlTemplate properties available, or mention that they automatically match up with all the urlFor* in BuildURLMixin

[amiel]

Thanks for thinking about this and gathering thoughts here!

[amiel]

Also, until I get a chance to dig in to the documentation further, there are two excellent blog posts that are far better at documenting what is possible than the README:

1. http://blog.ksol.fr/ember-data-working-with-custom-api-endpoints/
2. http://blog.ksol.fr/ember-data-working-with-nested-api-resources/

[amiel]

I'm starting to add some documentation in the wiki. In #11 I plan no slim down the README to just one example and mostly getting started information.

[courajs]

In this case I think you should definitely link to the wiki in the read me. I personally never check the wiki, and I've heard similar things from others

On Fri, Dec 18, 2015 at 5:27 PM, Amiel Martin notifications@github.com wrote:

I'm starting to add some documentation in the wiki. In #11 I plan no slim down the README to just one example and mostly getting started information.

Reply to this email directly or view it on GitHub: https://github.com/amiel/ember-data-url-templates/issues/8#issuecomment-165911268

[amiel]

Definitely will do.

[amiel]

@drspaniel I've written some documentation in the wiki and included a link in the README.

There's still a few places where I've left myself TODOs as I didn't get to documenting everything mentioned here today. Please let me know if you have any feedback (also, feel free to make edits as you see fit).

[amiel]

@drspaniel ok, I think I've finished at least a good draft of each section. Would you close this if you think it's good enough for now; otherwise make some edits or let me know what you think needs changed.

[courajs]

:sparkles: Totally awesome and thorough :sparkles: Thanks so much!