Sorry for replying late. I haven’t been checking back the forum recently and for some reason the email notification isn’t working for me…
When writing the Readme I was expecting users to have at least got to know MDL on its official website so I didn’t explain things in greater detail. I would probably not try to introduce MDL in my Readme file because I might have a tough time catching up with Google’s pace as they are updating on a daily basis.
(Quick response to the second question: nope, add the package and you are good to use any MDL components you want. Read the full response at the end.)
I guess I’ll just explain it here and if it eventually makes sense to you then perhaps I would adopt some into the Readme.
So… MDL is basically an extensible collection of modules (or reusable widgets). At the core of the collection, is the (currently named)
componentHandler, which takes care of registering modules and applying them to the web page. Then the rest is just a bunch of modules you wouldn’t be using directly; when the code is loaded they have already yelled at
componentHandler and asked it to register them and
componentHandler is the babysitter you talk to. However it is important to note that all these registration happens before
document.load event. This is so that
componentHandler could use
document.load as a good timing to scan the webpage/DOM to “upgrade” things.
componentHandler needs to apply these tricks to the needed DOM elements. This process is called “upgrading”.
A module could do anything it wants but most modules in MDL (called components), when initialized, adds extra stuff to the webpage or even alters the structure of the webpage to implement the fancy features of Material Design so you don’t need to write that much code.
When a module registers it self to
componentHandler, it specifies what CSS names to associate with it and what functions to execute when initializing each widget instance. Then “upgrading” is just
componentHandler looking for the matching CSS names and run those functions.
At the moment, only one single full document upgrade happens on
So first conclusion: if you have dynamically added DOM elements, you would need
componentHandler at the very least.
Then it’s all about the issues integrating with Meteor.
Meteor is great in that Blaze messes with DOM so you don’t have to. But that also means you won’t be able to catch when elements are added and removed. This is a BIG trouble for MDL users.
At first, I thought I could use
template.onRendered to batch upgrade elements, but that only solves half (really is a tiny half) of the problem; if you have a portion of a template that changes based on some value, say something like this:
When this portion gets re-rendered by Blaze, there is no event provided by Meteor to catch.
So I had to go with the final solution of using “MutationObserver”, basically a function gets executed whenever ANYTHING of the DOM is changed, which solved the problem nicely but it’s not compatible with old browsers. Also there could be a performance issue when there are tons of changes happening and few of them are related to MDL. And I’m working to find ways to improve this.
I think I have finished explaining the issues.
zodiase:mdl, simply adding the package and you can start adding MDL components to your app. My package by default auto-detects changes and does upgrades for you. If you find there is a performance issue, it is possible to disable auto-upgrading by calling
MDl.envConfig.patchers.blaze.setUpgradeStyle('none'). The details of
MDl.envConfig.patchers.blaze.setUpgradeStyle is explained in Readme.
Also it’s noted in Readme that no MDL components should be used as a root element of any templates or there could be unexpected side-effects. The reason is that Blaze wants to know what is the root of a template so that it could manage things nicely. However some MDL components add parents to elements, which basically confuses Blaze about what should be removed when a template is no longer visible. Also some MDL components would move elements around which breaks the event listeners attached to them and therefore breaking Blaze’s template event maps.
I would suggest checking out the closed issues in my repo to see what issues other users have encountered and have been fixed.
I hope what I wrote here makes sense to you and thanks for being interested in my package.