What's the usecase for ons.ready()?

Question

I'm trying to build an app using OnsenUI 2 (rc12 currently) and jQuery (3.0.0). There are many examples using the ons.ready() to do ... something. What confuses me is that Getting started example on their website uses the function. (Both examples are headers of the index.html)

<!doctype html>
<html lang="en">
  <head>
    <meta charset="utf-8">
    <link rel="stylesheet" href="lib/onsen/css/onsenui.css"/>
    <link rel="stylesheet" href="lib/onsen/css/onsen-css-components.css"/>
    <script src="lib/onsen/js/onsenui.js"></script>
    <script>
      ons.ready(function() {
        // Init code here
      });
    </script>
  </head>
  <body>
    <ons-navigator>
      <ons-page>
        Page 1
      </ons-page>
    </ons-navigator>
  </body>
</html>

Yet the templates in Visual Studio 2015 don't.

<!DOCTYPE html>
<html lang="en">
<head>
  <meta charset="utf-8" />
  <meta name="apple-mobile-web-app-capable" content="yes" />
  <meta name="mobile-web-app-capable" content="yes" />

  <!-- JS dependencies (order matters!) -->
  <script src="scripts/platformOverrides.js"></script>
  <script src="lib/onsen/js/onsenui.js"></script>

  <!-- CSS dependencies -->
  <link rel="stylesheet" href="lib/onsen/css/onsenui.css" />
  <link rel="stylesheet" href="lib/onsen/css/onsen-css-components-blue-basic-theme.css" />

  <title>Onsen UI Tabbar</title>

  <!-- App init -->
  <script>
    function alertMessage(){
        ons.notification.alert('Tapped!');
    }

    document.addEventListener('init', function(event) {
      var page = event.target;
      if(page.id === "home-page") {
        var i = 5,
          onsListContent = '',
          onsListItem = document.querySelector('#main-list').innerHTML;

        while(--i) {
          onsListContent += onsListItem;
        }

        document.getElementById('main-list').innerHTML = onsListContent;
      }

      if(page.id === "settings-page") {

      }
    });
  </script>

Yet, OnsenUI documentation for Tabbar (layout template; same as the one in the VS2015 example) does use it (doesn't show it in context though).

ons.ready(function() {
  var myTabbar = document.querySelector("ons-tabbar")
  myTabbar.addEventListener("prechange", function(e) {
    if (e.index == 1) {
      e.cancel();
    }
  })
})

And the OnsenUI interactive tutorials are the same. About half of them uses it and the other doesn't. When should I use it?

score 2 · Accepted Answer · edited May 23 '17 at 12:08

I guess the short answer is to just use it always - that way you will save yourself some trouble.

Basically it ensures that the function will be executed only after Onsen UI is ready. So trying to do something before that moment is a little risky. Basically when you start your app Onsen UI needs some time to initialise all of it's components (all the ons-xxx elements) as well as some other things.

Regarding your previous question - actually it also tries to be more universal so that you don't need the other 2 methods mentioned here.

Except waiting for its components it also waits for DOMContentLoaded in the browser and deviceready when used in a device with cordova/phonegap etc.

So basically when the function is executed you are ensured to have a proper dom tree, onsen ui methods on the loaded elements, as well as backbutton, pause etc events from cordova.

If you just want to add a simple event listener where you're not doing anything in particular with onsen you're free to not use it, but it's just safer and simpler if you do. In the demos I guess it's not really needed most of the time, but sometimes we just add it out of habit. My suggestion would be to use it in all initialisations of your apps.

And now another small note on your previous question: When using a page in a tabbar/navigator/splitter etc we don't ensure that the loading is synchronous since you also have the option of loading a page from the server instead.

Therefor you need to wait for the page itself to load (that happens after ons.ready most of the time). You've already found the init event. That is what you would need in most cases.

You can add a handler in either of the two ways:

// Pure JS
document.addEventListener('init', function(e){
    if (e.target.id === 'myPage') {
        // have fun
    }
});
// jQuery
$(document).on('init', function(e){
    if (e.target.id === 'myPage') {
        // have fun
    }
});

In jQuery you can add a selector as an additional argument, so in theory you should be able to also do something like

$(document).on('init', '#myPage', function(e){
    // have fun
});

Note that myPage must be the id of the page, not the template.

Bonus - if you want to execute something right after the page has been shown (some animation for example) you can use the show event instead.

Note to other readers: the mentioned question was closed as duplicate, but I don't think it was answered properly since it had some unique flavour. That's why it's answered here. The extensive use of jQuery is also due to the fact it was mentioned in that question. Even though this isn't a jQuery question I thought it would be useful to share some notes about it since that's what the OP will most likely use if its already being used in the project. — Ilia Yatchev, Jun 21 '16 at 13:52
Thanks a lot! As for my previous question, it was a little misguided by my lack of understanding (not I see the code in the doumentation, but I would have sworn it wasn't there before :), though the answer provided (the duplicate) wasn't of any use to me at the time (I didn't really understand it). Never the less, I finally got a working yesterday with the same code you just provided. Happy to know I'm doing it right. I will link this answer in my previous post too in case someone stumbles upon it (since it's answers it perfectly). — rancor1223, Jun 22 '16 at 05:30
And thanks for the ons.ready() explanation, I've edited my code accordingly :) — rancor1223, Jun 22 '16 at 05:31

What's the usecase for ons.ready()?

1 Answers1

Linked