Skip to content

Latest commit

 

History

History
324 lines (223 loc) · 11.1 KB

README.md

File metadata and controls

324 lines (223 loc) · 11.1 KB
Raw

Synthesis is meteor + polymer

![Gitter](https://badges.gitter.im/Join Chat.svg)

About

Synthesis helps you use polymer inside meteor.

Under the hood

Synthesis uses parse5 which parses HTML the way the latest version of your browser does. Does not use any regex to parse html. :)

A version that uses cheerio instead of parse ⇒ synthesis-using-cheerio.

#####Main functions

  1. Handles html link imports which polymer uses to add dependency files.
  2. Handles external script files (script src)
  3. Handles external css files (link rel stylesheet)
  4. Handles template tags.
  5. Removes comments and unecessary whitespaces.
  6. Handles loading order of html and js inside the polymer files
  7. Adds components to document during runtime.

Installation

Remove blaze-html-templates (or remove the html compiler you are using).

meteor remove blaze-html-templates

If you want to use blaze along with synthesis use mwc:blaze-html-templating . demo - blaze+polymer

Install synthesis

meteor add mwc:synthesis #compiles html files
# synthesis-assets is optional. If you want to handle relative asset paths.
meteor add mwc:synthesis-assets #compiles assets for <img src="image.png"> to work.

synthesis is a meteor 1.3+ package. for 1.2 support use mwc:compiler

You can optionally use these packages from meteorwebcomponents

Usage

Polymer Settings

Create client/lib/settings.js

Why lib directory ? Settings code should run before anything else.

/* client/lib/settings.js */
window.Polymer = {
  //dom: 'shadow',
  lazyRegister: true
};

App Structure

Refer http://guide.meteor.com

Application Structure http://guide.meteor.com/structure.html.

Keep all your components in imports folder

You can import html using

  1. import './component.html'; from js files

  2. <link rel="import" href="./component.html"> from html files

Please note that import 'package/package.html;' imports from node_modules directory while <link rel="import" href="package/package.html"> is the same as import "./package/package.html";. This is kept like this to go through polymer components in which dependency files inside the same folder are imported as <link rel="import" href="dependency.html">.

If you want to import scripts/stylesheets/html from public use src="/path/to/my/file". src="path/to/my/file" is interpreted as import "./path/to/my/file".

Script

  1. <script>yourscript goes here</script>

  2. <script src="component.js"></script>

Css (its important follow these two methods to confine style inside the component.)

  1. <style>Your style goes here</style>

  2. <link rel="stylesheet" href="component.css">

Add bower_components to any folder inside imports directory.

Assume bower directory is imports/ui/bower_components

<!-- imports/ui/component/test-element.html -->

<link rel="import" href="test-element2.html"> <!-- imports/ui/component/test-element.html Gets imported -->
<link rel="import" href="../bower_components/paper-button/paper-button.html"> 
<script src="test-element.js"></script>
<dom-module id="test-element">
  <template>
  <link rel="stylesheet" href="test-element.css"> <!--converted to style tag. this style is restricted to elements inside the element-->
  <style> 
  #nndiv{color:blue}
  </style>
    <paper-button on-click="showNickName">
      Show nickname
    </paper-button>
    <p>
      Name : {{name}}
    </p>
    <div id="nnDiv" hidden="{{nndHidden}}">
      Nickname: {{ nickname }}
    </div>
  </template>
</dom-module>
/*imports/ui/component/test-element.css*/
paper-button{
color:red;
}
// imports/ui/component/test-element.js
import './test-element.html';

Polymer({
  is:"test-element",
  properties:{
    name:{
      type:String,
      value:"Arun Kumar"
    },
    nickname:{
      type:String,
      value:"tkay"
    },
    nndHidden:{
      type:Boolean,
      value:true
    }
  },
  showNickName: function () {
    this.nndHidden = false;
  }
})

<!-- client/index.html (you can use any filename) -->
<head>
  <title>Synthesis</title>

</head>

<body class="fullbleed">
  <h1>Synthesis is Meteor + Polymer!</h1>
  <test-element></test-element>
</body>
// client/index.js
import '../imports/ui/components/test-element.html';
  // include the webcomponents js file 
import "../imports/ui/bower_components/webcomponentsjs/webcomponents-lite.min.js";

//Remember to include a polymer component or polymer.html itself in any file

import "../imports/ui/bower_components/polymer/polymer.html";

Best practice is to reduce the number of files in the imports directory. Avoid adding unecessary components, helps in lowering the build time. Refer the FAQ

A sample bower.json (imports/ui/bower.json)

{
  "dependencies": {
    "iron-pages": "PolymerElements/iron-pages#^1.0.0",
    "neon-animations": "PolymerElements/neon-animations#^1.0.0",
    "paper-button": "PolymerElements/paper-button#^1.0.5",
    "polymer": "Polymer/polymer#^1.0.0"
  },
  "name": "mwc-synthesis",
  "version": "0.0.1"
}

Using Polymer from npm instead of bower

Here is a working demo of using npm polymer package instead of bower.

https://github.com/meteorwebcomponents/synthesis-meteor-polymer-npm-demo

npm install --save @polymer/paper-button

Before everything else load webcomponents and polymer

import "webcomponents.js/webcomponents-lite.min.js";
import "@polymer/polymer/polymer.html";

Use it from js files as

import "@polymer/paper-button/paper-button.html";

Please note that the @polymer packages are still in testing stage. And the polymer version is an older one.

Assets

works inside html.

<!-- imports/ui/path/to/element.html -->
<img src="sample-image.png"> <!--Works!!-->
<iron-image src="sample-image.png"><iron-image> <!--Works!!-->
<any-element src="sample-image.png"><any-element> <!--Works!! src = imports/ui/path/to/sample-image.png -->
<any-element src="../sample-image.png"><any-element> <!--Works!! src = imports/ui/path/sample-image.png-->
<any-element src="[[image]]"><any-element> <!--Does not work!! if you want this to work use image = path/from/root/to/image.png -->
<any-element src="{{image}}"><any-element> <!--Does not work!! if you want this to work use image = path/from/root/to/image.png -->

<!-- assets in public/ folder -->
<any-element src="/sample-image.png"><any-element> <!--Works!! asset should be in public folder src = /sample-image.png -->

works inside css also.

/*imports/ui/path/to/element.html inside style tag  or  imports/ui/path/to/element.css */
background: url(path/to/image.png); /* Works!!. */
property: url(relative/path/to/image.png); /* Works!!. */
property: url(var(--url-var)); /* Does not work unless --url-var = absolute path imports/ui/path/to/image.png */
/* if you want to use variables use 
--url-var = url(path/to/url);
property: var(--url-var);
*/
property: url(/path/to/image.png); /* Works!!. if asset is in public folder */

File types we supports https://github.com/meteorwebcomponents/synthesis/blob/master/packages/synthesis-assets/plugin/synthesis-assets.js#L19.

Feel free to add pr's if you want to supports more file types.

Relevant code https://github.com/meteorwebcomponents/synthesis/blob/master/packages/synthesis-compiler/synthesis-compiler.js#L166-L176 .

Demo

#####Using Bower

Check out the Synthesis Demo

#####Using npm

Check out the synthesis-meteor-polymer-npm-demo

Kickstart Your Meteor Polymer projects

Kickstart a Meteor/Polymer project - FlowRouter with Synthesis.

KickStart Meteor/Polymer Project - Polymer App Route

synthesis1

Like it?

⭐ this repo

Found a bug?

Raise an issue!

TODO

Social

Gitter - meteorwebcomponents

Meteor forum - https://forums.meteor.com/t/polymer-meteor-support-with-meteor-webcomponents-packages/20536

NO NEED to use any VULCANIZING tools. Synthesis handles everything

FAQ

Q: When I tried to set window.Polymer = {lazyRegister:true,dom:"shadow"} it resulted in error.

Ans : Refer polymer settings

Q: When I added (a) bower component(s) build time became painstakingly high.

Ans : The component(s) you've added might have many js files. meteor ecmascripts gets frozen/takes a long time when the number of js files are very high. Refer the issue meteor/meteor#6859. In my testings with 300 html files synthesis ran pretty fast. Its the meteor js handlers which create this issue.

In console (pwd = /imports/ui)

find bower_components -name \*.js | wc -l

Try to find out which package contains large number of js files. Delete unecessary files and keep a local copy.

bower-installer can be used instead of bower to bring in just the files that you need for your project. Significantly lowers the build time.

Q: Is it possible to use npm instead of bower for loading polymer and components

Ans : Yes there is. Refer using npm instead of bower

Q: Can I use Polymer and blaze together?

Ans: You can. If you want to use blaze along with synthesis use mwc:blaze-html-templating . demo - blaze+polymer

Use blaze.html extension for blaze files.

But there are some compatibility issues https://forums.meteor.com/t/polymer-meteor-support-with-meteor-webcomponents-packages/20536/30?u=aruntk

Q: I love blaze's template level subscriptions and spacebars. I dont want to lose these features when I port my app to polymer. Any help?

Ans : In my experience I find nothing that polymer cannot do which blaze can. Polymer is very easy to learn and while porting your app you'll find yourself copy pasting most of your code. For every blaze function they have solutions in polymer. We have got you covered when it comes to meteor data and subscriptions (including template level subs) Refer mixin .