This repository has been merged into Meteor main repository. You can find it there.
meteor / guide Goto Github PK
View Code? Open in Web Editor NEW:book: Articles about Meteor best practices
Home Page: http://guide.meteor.com/
License: Other
:book: Articles about Meteor best practices
Home Page: http://guide.meteor.com/
License: Other
This repository has been merged into Meteor main repository. You can find it there.
(to be updated potentially for the Meteor 1.3 module world)
https://github.com/meteor/guide/blob/master/outlines/structure.md
https://github.com/meteor/guide/blob/master/outlines/build-tool.md
ecmascript
package, if you really want to you can use coffeescript
instead but all of our code samples will be against ES2015.meteorhacks:npm
and cosmos:browserify
are the best optionsBuild a wrapper around methods, of the form:
Todos.methods.insert = new Method({
name: '/todos/insert',
validator(doc) => { Todo.Schema.check(doc); },
permission(doc, userId) => {
if (!doc.ownerId == userId) {
throw new ForbiddenException("...");
}
},
body(doc) {
Todos.insert(doc);
}
});
Designing a standard error format, so that when you throw an error from a method, it's clear what kind of error it is, how it should be displayed to the user, whether it's related to a specific field, etc. This way different packages can show the same kinds of errors. I'd love to see some prior art on this - most validation libraries either throw terrible errors (like check) or have a super custom form integration (like simple-schema).
I think apart from the design here we need to make sure technically that the ddp stack supports throwing errors with objects attached (one way or another, see meteor/meteor#4202).
Atmosphere is great, but it's also a little hard to navigate sometimes. So I've been keeping track of useful packages on the side as well.
Note that the end goal for this list is to eventually publish it as a free eBook to give away on the Discover Meteor blog. But until that happens, I suppose there's no harm in discussing it here :)
https://github.com/meteor/guide/blob/master/outlines/mobile.md
https://github.com/meteor/guide/blob/master/outlines/ui-ux-outline.md
tap:i18n
is the best internationalization library for Meteor todayOld outline
We need to do this to get a feeling for what an app looks like when it follows all of these recommendations. Some apps we have built in the past are pretty close, but we need to make sure everything we say meshes well together and ends up with an app that feels good.
As far as official (MDG) documentation is concerned we currently have the docs, the wiki, a number of READMEs in packages, some of which are better than others and the Meteor Manual - does Maria still work at Meteor?
There is already an issue with overlaps (saying the same thing), contradictions (saying something different) and holes (not saying something).
A proportion of this project's time needs to be devoted to addressing the confusion surrounding all these disparate ways of presenting The Meteor Way.
@stubailo : I think you've already said the useful knowledge in the wiki will be absorbed into the guide?
I see the docs as the reference book - all methods, etc. are documented much as they are now, with links to the appropriate guide sections (and vice versa) - is that right?
I think the Meteor Manual should go the way of the dinosaur (think of it as a K/T meteoric extinction event 😉) - maybe it could be a permanent redirect to the guide.
The package READMEs should all be high quality and become the appropriate package reference section in the guide (imported as part of the guide's build process).
What do you think?
https://github.com/meteor/guide/blob/master/outlines/packages.md
Needed for #9.
Currently, to make insert
, update
, and remove
work on the client, every collection defines methods called /collection-name/insert
, /collection-name/update
, /collection-name/remove
. There's no way to remove them.
It would be reasonable for people to want to define methods called this, especially with the code style we are prescribing. Also, since we are recommending for people to avoid allow/deny, these methods are useless and would clutter any list of app methods.
The best option would be for these methods to simply not exist unless allow/deny is used. That leaves an open question about Meteor.users
, which has allow/deny rules defined by default, but if we removed the profile
field that would no longer be the case. I would be happy if a future release of Meteor made profile
opt-in.
I think this is a code ticket? I'm not quite sure what would be involved here. Do we need to work with the publisher of the CI integration?
I think it's pretty clear when you take a look at the application development landscape these days that people are pretty excited about reusable components. Blaze is a great templating system, but it doesn't quite give you everything you need to be able to reason about small parts of your app independently.
Mainly the issue is that it can be hard to look at a Blaze template and know how it will behave when used in different parts of your app. This involves a few issues:
Session
- partly because using Template.instance()
all the time is a lot of boilerplate$('.error')
@mitar, can you help me understand to what extent your Blaze Components package solves these issues? Unfortunately, you're right - I haven't had enough time to look at it in depth, but I would like to learn more now.
Copied below, the outline of the Blaze guide as proposed:
Write “HTML with holes” just like you're used to, and get a fast, fine-grained, reactively updating page with no sweat.
How about a short section on getting the most out of atmosphere?
Maybe this is a bit too basic for the intended audience, but given the number of forum questions which end up answered as "try adding package xxx:yyy", some guidance would appear to be useful.
Here's a thought: what about using Microscope as an example app, instead of to-dos? It's a little more complex, so it features a lot of concepts that are not present in To-Dos (for example, pagination). And it's also an app that many people are already familiar with.
https://github.com/meteor/guide/blob/master/outlines/routing.md
The only drawback of GitHub pages is the lack of support for versioning, but we don't need that to get started writing content.
gh-pages
branch and make that the default branchPerhaps this goes in UX, perhaps in testing.
@debergalis is excited about it, @tmeasday and @dominicnguyen have experience using such a system.
https://github.com/meteor/guide/blob/master/outlines/collections.md
simple-schema
for schemascollection2
for schema validation (just as an error checking mechanism, input validation is covered in the forms/methods article)percolate:migrations
for migrationsdburles:collection-helpers
to add "helpers" to your collection documents. Use this to handle relationsOld info:
Here are some decisions we need to make, and my ideas:
Basically simple-schema, right? I feel like this is a de-facto standard right now so it's what we should use. Are there any downsides to simple-schema? Are there any competitors? @aldeed what are your thoughts here?
We know there are certain limitations with DDP right now; for example the lack of nested diffing. This means it can actually be an advantage to have a more flat and normalized schema.
It makes sense to me to use the Meteor transform
option to turn objects retrieved from Mongo/Minimongo into model objects with getters/setters/etc that basically just call Meteor methods. Is this a good approach, or is it better to call methods directly? Do we lose something by not having the data that comes out of Mongo be a plain object? (for example, you can't reliably clone "smart" objects, they might have surprising reactivity, etc?)
We'll explain how to deal with collections across client and server. Then we'll reduce code repetition by extending database documents with model classes.
https://github.com/meteor/guide/blob/master/outlines/blaze.md
Previous proposed outline:
this.title
, instead post.title
(does the new iterator syntax help with this?)this.$
and event mapsTemplate.contentBlock
Designing a standard error format, so that when you throw an error from a method, it's clear what kind of error it is, how it should be displayed to the user, whether it's related to a specific field, etc. This way different packages can show the same kinds of errors. I'd love to see some prior art on this - most validation libraries either throw terrible errors (like check) or have a super custom form integration (like simple-schema).
I think apart from the design here we need to make sure technically that the ddp stack supports throwing errors with objects attached (one way or another, see meteor/meteor#4202).
Needed for #9.
<template name="a.b.c">
...
</template>
Should be accessible via:
Template.a.b.c.helpers({ ... });
It should also be OK to simultaneously have a template called a.b
and a.b.c
, so that you can do something like:
// Reusable list of widgets
Template.widgets.WidgetList
// Page tied to a specific URL/layout that does data loading (like a controller)
Template.widgets.WidgetList.Page
https://github.com/meteor/guide/blob/master/outlines/data-loading.md
publish-composite
Old outline:
https://github.com/meteor/guide/blob/master/outlines/testing-outline.md
Lots of new stuff needs to exist to make testing palatable in Meteor, but the outline lists the packages and approaches we want to promote now.
practicalmeteor:mocha
is the best package test runnerOld content below:
@samhatoum, I'd love to hear your ideas about what would go in an official Meteor testing guide. We've talked about this issue at length already, so you know a lot of my opinions on the issue. What do you think?
My proposed outline is below.
Write some extra code now to make sure you don't break your code when you add more code later. Add features and refactor your app with no fear.
Versioning has been mentioned en passant, but it needs some clear focus.
One of the great things about the current Meteor docs is you always get the latest version.
One of the bad things about the current Meteor docs is you always get the latest version. Well, to be more accurate you can't (easily) get to an older version.
So, as a minimum, I'd like to see an easy "release switcher" for the docs. For bonus points, in-doc flagging of differences between this and the previous release.
Originally opened by mitar with the title "Server side reactivity" with the description below. This ties into managing/publishing relational data.
I think a topic on server side reactivity would be great:
And how to keep denormalized documents in sync:
In general my observation is that people are trying to use too many relations in Meteor/MongoDB because they are not used to the idea that you should denormalize data and you can have embedded subdocuments in documents.
In MongoDB, the important idea is that you get in one document all the data you need to display that one view (or Meteor template) (which aligns really well with data context, which is also maybe why I am having less issues with data context being a way to pass data then those who anyway have to make multiple queries to get all the data to display in the template, like making additional local collections queries in template helpers). The issue is that people like to keep stuff separate in collections and then try to do joins. Which is really bad. And really hard to do well in a reactive way.
So the approach I think is better (and for which we made packages) is that you for relations which are inherit in the data you declare them declaratively and then Meteor embeds stuff and keeps them in sync. It is really great because you can then query on the subdocuments as well very efficiently.
And for joins which are not inherit on data (so not relations between data, but for example permission checks) you can use server-side reactivity because they are most often 1-to-many joins which work pretty well as a server-side reactivity (does the current user has access to this document I am about to publish).
(Obviously, disclaimer, I am involved with both projects.)
I assume we will all send in PR's to this repo. It would be nice to figure out how/when/why a PR should be accepted into the guide. This seems like the first major hurdle to developing trust with potential writers.
We suspect it's simple schema. If so, we should work with @aldeed to get it (the non-meteoric parts anyway) on NPM, and promote it as a cool thing that's come from the Meteor community.
One thing that @timbotnik and I noticed about it: it seems slower than it needs to be. Perhaps there are some simple optimizations that can be made?
While this is still in discussion, we can have a look, how similar is done in Laravel framework, which is deeply loved by a lot of php devs.
The documentation:
laravel xxx
- 99% you get to the docs.The website is also held in an open repository so that everyone can see, how it is build. It is also updated to the latest version of the framework.
My recollection from investigations a few years ago:
@SachaG - perhaps you have some thoughts here.
It should have examples of publications, methods, routes, components, and a good app structure. People have been asking for this for forever, now that we will have a recommended structure it's a good opportunity to build it in. It's not quite scaffolding, but it's on the way there.
Relevant issues on meteor/meteor:
The idea of this guide is to give some guidance about how to publish a package onto Atmosphere, to contribute and share with the community.
@tmeasday what do you think? I don't think this was in the original outline at all. What article would it go in? Probably not really routing, more like APIs or something.
Implementing internationalization in your app doesn't take that much work thanks to the aweseome tap:i18n, so I think it'd be worth mentioning it.
I wrote these articles for MDG some time ago.
https://meteor.hackpad.com/Meteor-Cookbook-Using-Dates-and-Times-qSQCGFc06gH
https://meteor.hackpad.com/Meteor-Cookbook-Reactive-D3-Visualizations-YUR9JT4mrm9
https://meteor.hackpad.com/Meteor-Cookbook-Filepicker.io-Uploads-and-Image-Conversion-hIpSwJQV3HJ
A couple more are less polished / still drafts here https://github.com/nate-strauser/meteor-cookbook
Do you think this type of content belongs in the guide? I'd be happy to help update these and get them ported over.
https://github.com/meteor/guide/blob/master/outlines/accounts.md
useraccounts:core
and friends are the best account UI availableprofile
. This is partially for DDP performance, partially to make security easier.This way users have a chance to start playing with examples/demos within seconds instead of having to set up an example manually or cloning a repo to get started.
https://github.com/meteor/guide/blob/master/outlines/security.md
Meteor.settings
https://github.com/meteor/guide/blob/master/outlines/forms.md
autoform
is the best Meteor form solution available today, we're going to make sure it integrates seamlessly with the method solution aboveCollectionFS
is the best file upload solutionOld info:
Related PR: #27
Today I got the chance to spend some time talking to @tmeasday, who's visiting from Australia! He's bringing his years of experience writing production apps as part of Percolate Studio and MDG, and his learnings from co-writing Discover Meteor, to the Meteor Guide project. Awesome!
Let's get into what we talked about regarding forms, methods, and user input in general.
The biggest requirement we identified here is a need for a standardized pattern for different kinds of input errors you might want to display to the user. Then we also came up with some ideas about the code that could be involved:
This suggests some idea of a "validated method" - a method that isn't just a single function, but perhaps several that can be run separately. Similar to @SachaG's two-tiered methods, except all of the tiers are conceptually part of the method, and there might be more than two of them.
Here's a diagram that represents the picture I have in my mind. Obviously it's not finished, but it outlines the shape of things that I see:
check
) or have a super custom form integration (like simple-schema
).check
package by bringing the best parts of that into simple-schema; in particular that means having a way to just do a one-shot check of an object against a schema without needing to first initialize a validation context. This way it will be much more natural to reuse the schema in the form and the server-side validation.Referencing this: https://github.com/meteor/guide/blob/master/content/routing.md
It says that for a route like /
, action
is not called. But that's not true, otherwise this wouldn't work:
FlowRouter.route('/', {
name: 'home',
action() {
ReactLayout.render(Layout, {content: <Home />});
}
});
We need to think about things like the 'voice' of the content, who the articles are written for, and what authors can and can't promote within their posts.
A declarative, efficient, and flexible JavaScript library for building user interfaces.
🖖 Vue.js is a progressive, incrementally-adoptable JavaScript framework for building UI on the web.
TypeScript is a superset of JavaScript that compiles to clean JavaScript output.
An Open Source Machine Learning Framework for Everyone
The Web framework for perfectionists with deadlines.
A PHP framework for web artisans
Bring data to life with SVG, Canvas and HTML. 📊📈🎉
JavaScript (JS) is a lightweight interpreted programming language with first-class functions.
Some thing interesting about web. New door for the world.
A server is a program made to process requests and deliver data to clients.
Machine learning is a way of modeling and interpreting data that allows a piece of software to respond intelligently.
Some thing interesting about visualization, use data art
Some thing interesting about game, make everyone happy.
We are working to build community through open source technology. NB: members must have two-factor auth.
Open source projects and samples from Microsoft.
Google ❤️ Open Source for everyone.
Alibaba Open Source for everyone
Data-Driven Documents codes.
China tencent open source team.