URLs and Routing

[stubailo]

Article outline

https://github.com/meteor/guide/blob/master/outlines/routing.md

Major decision points

1. Flow Router because it works well across Blaze and React, and is relatively simple
2. The URL/Router is not the main driver of the app - it's just another data source
3. Only "smart" components should read the route data (see more in the Blaze or UI articles)
4. Server side routing/HTTP API is not covered here

[stubailo]

This article currently assumes this issue will be solved: meteor/meteor#1602

[stubailo]

It's not clear if the loading indicator section belongs here - it's kind of a legacy thing from the Iron Router days that people expect loading to be tied to the router?

[stubailo]

@zimme your package is in here!

@arunoda this is using Flow Router, I wonder what you have to say or add about it.

[stubailo]

@banglashi I also mention flow router helpers in here.

[stubailo]

@deanius what is the status of okgrow:analytics with Flow Router? This guide assumes that it will just work.

[arunoda]

@stubailo let me go through this.

[robfallows]

@stubailo : re okgrow:analytics, we're using astronomerio for analytics routing. No idea if one is "better" than the other, but both seem to offer similar functionality.

[vladshcherbin]

@stubailo I think the routing guide is very long and has many unnecessary parts.

• Why did you choose long questions instead of slick Table of Contents?
• Do we really need to tell, what a url is and what it serves for? I thought the guide is not for complete novices..
• The parts, where it is shown, how to render the template. Or how to subscribe and highlight the active route. And then, permissions - they are also done on a template level. All this things were part of Iron Router, the Flow Router only handles urls. All the other stuff is done not on a Router level. And this is one of the main things that confuses people.

How about splitting this guide into Router and Templates/Views guides?

What do you think?

[stubailo]

Why did you choose long questions instead of slick Table of Contents?

The questions at the top are more meant to be a summary of the topic. See the Rails guide here: http://guides.rubyonrails.org/routing.html

There should be a table of contents automatically generated from the headings of the article, we just haven't built that yet. I agree it makes the whole thing a bit harder to understand, but that's the current state.

Do we really need to tell, what a url is and what it serves for?

The point of this section is to emphasize that routes serve a very different purpose in client-side rendered apps. In a server side app, you need a route for every single thing. In a client-side app, you only need routes for stuff that needs to be linkable. The rest can be done in JavaScript.

All the other stuff is done not on a Router level. And this is one of the main things that confuses people.

I think you're absolutely right. By mentioning these topics here, we're conceptually tying them to the router. Let's break it down:

Definitely router topics

• showing active route
• helpers for generating links
• displaying different templates for different routes (probably the main function of a router!)
• analytics
• redirecting to other routes when a URL has been moved

Are probably template/view structure topics

• showing nice messages when the user can't see data
• loading data

[stubailo]

@robfallows I feel like the OK Grow package is more relevant to most people since it supports a wide variety of analytics services. As far as I can see, Astonomer just supports... Astronomer?

[vladshcherbin]

@stubailo I think, we should cover at least this topics:

• intro
  • what the routing does and tell, that we suggest using flow-router. Add here the installation in one line.
• basic routing
  • show some examples of simple route actions
• route parameters
  • show, how to accept route params, have optional ones, etc
• named routes
  • dedicate a chapter as it simplifies routing, linking and is a preferred way to build links
• route groups
  • show the examples with route groups
• triggers
  • show some examples with triggers
• displaying views
  • tell, that there are different engines and the examples are similar. show the example with blaze (blaze-layouts package) (without showing templates part) and add a link to the views/templates guide to read all about it. There, we can tell, how to build links, highlight them, manage permissions, etc.
• redirects
  • show, how to handle redirects
• 404
  • show, how to handle 404
• advanced complex examples
  • complex examples, like multiple languages, etc

So, this will show that we have a powerful router, although not in the core.

I also remember, why the template helpers for links are not in the core of flow-router - @arunoda told us, they are not the router part. I fully agree now ;)

Analytics is a tricky one, if you want to use for example google analytics and to send the page title there - you will need to do it on a template level too, since you subscribe and fetch the title after receiving.

[stubailo]

@vladshcherbin the outline you just proposed, as far as I understand, is a guide about how to use Flow Router's API. I'm trying to build something which talks about different URL-related use cases, and happens to use Flow Router as an implementation. I think almost any reasonable person would expect to learn about how to create links in this article, even if it's not actually "part of the router".

[vladshcherbin]

@stubailo oh, this are just my thoughts on what should be told about (in examples, how to-s?, etc). It is not the outline, just the topics to cover. And most of them are already covered in the draft. I fully agree and support you.

[stubailo]

Ah OK, yes in that case you're right - we should at least mention all of those.

[deanrad]

@pauldowman can answer better about the okgrow:analytics package, cc'ing him here

[ctaloi]

Astronomer is kind of like a proxy or aggregator for multiple analytics products, including Google. Works well..
https://github.com/astronomerio/meteor-astronomer

[queso]

Tagging in @schnie since astronomer is being mentioned.

[stubailo]

I don't think we would want to recommend an aggregator service as the default solution, if there's a perfectly good package that sidesteps the aggregator, no? Or are there some benefits I'm missing?

[SachaG]

I think Analytics should be a separate thread. There's a lot of analytics stuff that is not router-related (events for example).

[stubailo]

Yeah there's also a section about it in the running production apps article. I don't know if it's worth having a whole article about it, I bet you could explain most analytics stuff in like a page or two?

[ryw]

Tricky where to put this analytics stuff — a subsection of Routing is probably best place, if you don't want a standalone Analytics page. Happy to contribute if the decision is to make a standalone page, though.

@stubailo I agree okgrow:analytics should be default. We've talked to @pauldowman about adding Astronomer as to that package, just need to find time :)

And to clear up misconceptions — our astronomerio:core is a standalone analytics package, does a few more things (tracking Meteor.method calls, for example). We continue to put effort into making it the best overall analytics experience for Meteor devs, and the service is free for < 1M events/mo. So I'd hope we at least get a mention in the guide.

[SachaG]

Can I vote against okgrow:analytics? I don't think it makes sense to include a 200k JS file when all most people need are the 10 lines of the Google Analytics snippet.

[zimme]

How about just showing the analytics in routing over here with just a small google analytics snippet or some other small snippet or package and then in the analytics chapter we can have a routing section where we show more routing level analytics with other packages and stuff like that, we should have a link to that section from the analytics section here in the routing page.

Other than that, I think things look good enough. One of my first thoughts was that the level on the guide seemed a bit on the beginner side of things, but my sight might be off because of the fact that I've been using Meteor full-time since 0.6 and that I came into Meteor from doing previous client side apps with backbone/marionette.

Edit:
I haven't read every part in detail yet, I'll go over the examples using my package making sure it's up to date.

[vladshcherbin]

@stubailo we should have a separate page for Analytics, 100%.

As I said, if we want to show in analytics the page title and the title is stored in database - you can't do this from router. This will be done in the template level. You can also add events, when you click something, happened something, etc - there should be info about that too. And this info is not the part of the router guide. We should stop putting everything in router. This is not Iron Router and everything is different here. I have no analytics in router at all, template level everywhere.

We shouldn't also tell everyone - use okgrow as it is HUGE as mentioned above and most of devs don't need this beast. I use datariot:ganalytics for google analytics and I'm happy with it. So we should probably have sections with recommendations on different services (google analytics, yandex metrics, etc). Minified for production:

fresh install - 115 kb
fresh install + okgrow - 162 kb
fresh install + datariot - 116 kb

[alanning]

Regarding FlowRouter A&A, I just submitted a PR which adds examples of template-based authorization to the guide in the Further Reading section. The examples can be found here: https://github.com/alanning/meteor-roles/tree/master/examples

I also did a presentation on Auth + FlowRouter at our first NY DevShop which may be of interest. Video is not online yet but slides can be seen here: http://slides.com/alanning55/a-pattern-for-flowrouter-auth#/

[stubailo]

Hey guys!

Really great feedback in this thread. I think it's clear to me that this guide needs to be rebuilt from the ground up with a much better process, hopefully this will make it easier to arrive at a consensus.

Now there's a PR with a totally new outline: #69

This way, I won't sink effort into writing the wrong thing, like I did with the initial draft. But I think that draft will be useful to learn about possible formatting requirements for a hypothetical guide article.

[pauldowman]

@SachaG I do understand striving for minimal file sizes on the client, but personally I think the convenience that it provides makes the larger js file worth it. (I did remove support for lots of unused services and took about 100k off the file size though, I'd been meaning to do that and your comment here pushed me to get around to it.)

Here's what okgrow:analytics provides, which I think makes it worthwhile:

1. Automatically track all page views with multiple services
2. Easily log events to all services with a single call to analytics.track("event-name")
3. Automatically identify with all services using the email address that we find from the user, or from the social profiles that provide it.

Those things can be done custom of course, but it takes some work, and people tend to get a lot of those things wrong or forget them because things like "identify" can be hard to understand.

And details like making sure tracking and identify calls don't get run multiple times due to reactivity, or getting the current user's email address from multiple different places in the user object and making it available client-side for the identify() call aren't totally trivial.

[stubailo]

@pauldowman is it possible to split out the things in the list you mentioned from the individual services? So you would add okgrow:analytics and then like okgrow:analytics-google or something? Similar to how accounts-base and accounts-facebook work.

[SachaG]

@stubailo yeah I think that's how it should work. Have a base package that does all the tracking and exposes hooks. And then add-on package that use the hooks to propagate events to the third-party service of your choice (or even store them in your local DB if you prefer).

I've been meaning to add something like this to Telescope for a while. Here's a few early thoughts around that: https://github.com/TelescopeJS/meteor-events

@pauldowman I have nothing against convenience, but I don't really see the point in including code for third-party services that will never be used if there's a way around it through a plugin system. The other features are great though :)

[pauldowman]

@stubailo @SachaG Yes I definitely agree. I opened an issue to do that here: okgrow/analytics#70.

Note that analytics.js itself adds some overhead, but I think it's worth it. It unifies the interface to all the services so you can easily switch between them, and takes care of awkward details with identify(). Without it we wouldn't be able to support more than the two services we use.