search

zeroasterisk / MeteorRider

PhoneGap/Cordova + Meteor integration approach "DOM hijacking", telling PhoneGap where to get content from, letting Meteor hijack your PhoneGap app's HTML/CSS/JS
MIT License
183 stars 28 forks source link

readme

DEPRECATION NOTICE

Meteor core now supports a better Meteor + Cordova integration approach.

This project was useful while that didn't exist, but Meteor's integration is great, use it.

MeteorRider

An approach for integrating PhoneGap/Cordova + Meteor.

Your Meteor web app (real time everything), inside a Cordova shell (native APIs) = awesome!

How it works

overview

It's Easy

It might sound a bit complex, but really it's pretty simple.

This approach is good for the following reasons

If you want an alternative, without the extra AJAX request try out

For more info, a comparison of approaches

Example Projects

Installation / Usage

NPM installer package under consideration see this npm package and this discussion

There are only a couple of files, and you can choose to manage them however you like...

Get the Code

cd tmp
git clone https://github.com/zeroasterisk/MeteorRider.git MeteorRider

On PhoneGap/Cordova - Setup

Option 1) Replace the whole index.html file

You do not have to replace the whole index.html file, but it's a reasonable "fast start".

cd pathtoyourphonegap/assets/www/
cp index.html index_old.html
cp /tmp/MeteorRider/www/index.html index.html
cp /tmp/MeteorRider/www/js/meteor-rider.js js/

Then edit index.html with the appropriate config (see Configuration)

Option 2) Edit the index.html file

There is very little that is "required" to fire up MeteorRider.

This is the minimum you want in your index.html

    <script type="text/javascript" src="https://github.com/zeroasterisk/MeteorRider/raw/master/js/meteor-rider.js"></script>
    <script type="text/javascript">
      document.addEventListener('deviceready', function() {
          MeteorRider.init("http://leaderboard.meteor.com/");
      }, false);
    </script>

You just need to call MeteorRider.init() when the deviceready Event is triggered.

MeteorRider.config

Here is the default config

config: {
  meteorUrl: '',
  currentPath: '',
  localStorage: true,
  // step 1) loading text
  doLoading: true,
  // step 2) AJAX request
  doRequest: true,
  // step 3) AJAX response (or cache) replacing DOM
  doReplace: true
},

If this is global variable is found, it sets the default config in MeteorRider

var __MeteorRiderConfig__ = {
  meteorUrl:  "http://leaderboard.meteor.com/",
  currentPath: "/",
  localStorage: true
};

You can pass any part of the config into MeteorRider.init() like so:

MeteorRider.init({ meteorUrl: "http://leaderboard.meteor.com/", localStorage: false });

You can also just pass in a string, and it will be treated like the meteorUrl (simplest config)

MeteorRider.init("http://leaderboard.meteor.com/");

MeteorRider.config.meteorUrl (required)

Set the meteorUrl property, it should be the full URL to your meteor app.

NOTE: full public URLs work best. Localhost or internal IPs probably wont work. If Cordova can't load it, it won't work.

On Meteor

You do not have to put anything in Meteor, but if you copy in this startup.js file, it will handle hot code pushes and reload inside PhoneGap/Cordova, without losing the phonegap context.

cd pathtoyourmeteorapp
cp /tmp/MeteorRider/meteor/startup.js startup.js

Obviously, the best bet is to look for the the Cordova APIs directly

if (_.isObject(device)) {
  console.log(device.cordova);
}

You can also look for the MeteorRider JS object inside your Meteor app and use it as a means of basic knowledge about the client, and status.

You can also force the localStorage to be the "loading" screen on the next pageload... (it should be the full HTML you want rendered)

MeteorRider.meteorHtml = '<!DOCTYPE html><html><head>' +
  '<link rel="stylesheet" href="http://leaderboard.meteor.com/6a545450449411b537bd96111c640ce7d7a1092e.css">' +
  '<script type="text/javascript" src="http://leaderboard.meteor.com/9ebe61ab3cb3e1d4bcd16191207b9f1eb692d512.js"></script>' +
  '</head><body>' +
    'My Cool Loading Content Here :)' +
  '</body></html>';

MeteorRider.replaceStoreHtml();

Meteor Packages for PhoneGap/Cordova

There are probably many more than this list, let me know about `em.

OAuth for Meteor + MeteorRider + PhoneGap/Cordova

Sadly this should "just work" out-of-the-box, but as of now, it is frought with peril.

Luckily there is an excellent project alive which is a very easy mrt add phonegap-oauth away.

Check it out here meteor-phonegap-oauth

Common Problems / Tips

PhoneGap/Cordova Issues? Plugin Issues?

  1. Stop MeteorRider (comment it out, or setup testing conditional bypass)
  2. Run whatever you're doing with just index.html and "on device" JS (without Meteor)
  3. Working locally but not with MeteorRider? Enable MeteorRider again and look for a namespace collision...

Not Loading Meteor?

  1. Check the URL, can Cordova get to it?
  2. Try loading a static file from your Meteor URL (from the /public/ folder) as the meteorUrl.

  3. Check the console from Cordova (Android, iOS, etc)

    MeteorRider requesting MeteorRider url: http://example.com MeteorRider response.status = 404

You can uncomment the lines in MeteorRider where it logs the meteorHtml (the HTML content from Meteor).

PhoneGap/Cordova needs to be setup to allow access to Meteor

In older PhoneGap installs or if you've restrictred <access>, may have to allow access to the Meteor app url/domain. Refer to the configuration documentation for your version of PhoneGap.

http://docs.phonegap.com/en/edge/guide_appdev_security_index.md.html#Security%20Guide

<access origin="*" />

In the Wild

Roadmap / Goals

The main goal is to provide a simple, fast, and standardized way to connect PhoneGap to Meteor.

The combination is very powerful, and I have high hope for the future.

Goals:

Tasks:

Authors / Acknowledgements

This is the "Option 3" approach I've been thinking about for a while.

Inspiration and collaboration from:

I'd like to thank all of them for communicating with me while figuring out what my options were and for collaboration on this project.

Background:

http://prezi.com/ig9gjm11mwsi/from-zero-to-mobile-web-app-in-sixty-minutes/

http://zeroasterisk.com/2013/08/22/meteor-phonegapcordova-roundup-fall-2013/