Quickstart adon

Previously on eliosin...

Nutshell

An adon adds and removes a class to a tagName based on simple user event. The name of the class should be camel formatted 'adon' + Name, e.g. adonFullName.

  1. Create the file js/adon/adonFullName.js

  2. Write your logic - basically like this, but cleverer:

// NB: Twinned with /stylesheets/adon/adonFullName.css
// NB: Tested by /test/adon/adonFullName.js
jQuery.fn.extend({
   adonFullName: function() {
       return $(this).toggleClass('adonFullName')
   }
});
  1. Create the file stylesheets/adon/adonFullName.scss

  2. Make the adonName the className in the scss, e.g.

adonFullName {
   // get sassy in here
}
  1. Import the adonName into #{$container} on stylesheets/theme.scss

  2. Edit js/main.js

$(document).ready(function() {
   $('nav').adonFullName(true);
});
  1. Ensure tagName is in the correct prong in stylesheets/settings.scss

Do steps 1 to 6 in one go:

yo sin:adon

Exercise 1 HideOnScrollDown An adon which hides tagNames when the page scrolls down

We're going to create an adon which can be used to hide things when the page is scrolling down. You can then add this adon on to any tagNames which you want to hide or show depending on the scrolling behaviour of the user.

Create and edit js/adon/adonHideOnScrollDown.js, adding this code:

// NB: Twinned with /stylesheets/adon/adonHideOnScrollDown.scss
// NB: Tested by /test/adon/adonHideOnScrollDown.js
jQuery.fn.extend({
  adonHideOnScrollDown: function () {
    var tags = $(this)
    var position = $(window).scrollTop()
    $(window).scroll(function () {
      tags.each(function () {
        var tag = $(this)
        if ($(window).scrollTop() > position) {
          tag.addClass("adonHideOnScrollDown")
        } else {
          tag.removeClass("adonHideOnScrollDown")
        }
      })
      // reset the position after hiding all tags
      position = $(window).scrollTop()
    })
  },
})

While the page scrolls, all the tags connected to this adon will be given a new class adonHideOnScrollDown. When the page starts scrolling up, the class is removed.

What we learnt

  1. That the adon's javascript is adding and removing classes based on user interaction.

  2. How to write an adon which responds to the window scrolling.

Exercise 2 Styling adonName classes

Create and edit stylesheets/adon/adonHideOnScrollDown.scss, adding this code:

// DEBUG: Twinned with /js/adon/adonHideOnScrollDown.js
.adonHideOnScrollDown {
  transition: visibility 0s linear $transition, all 0s;
  transition-timing-function: ease;
  visibility: hidden;
}

As the page is scrolling, remember, all the tags connected to this adon will temporarily has the class name adonHideOnScrollDown. This short snippet of scss sets the visibility: hidden; of the .adonHideOnScrollDown style, with a transition effect timed by the $transition setting.

Finally, import adon/adonHideOnScrollDown.scss into stylesheets/theme.js:

  ...
  @import 'adon/adonHideOnScrollDown';
}

What we learnt

  1. A adon's functionality is handled using css.

  2. There's nothing to stop you writing $(this).hide() in an adon, but the elioWay would be to have visibility: hidden; in the adon's activated class.

  3. Apparently, there's a $transition setting!

Exercise 3 Pluging in adons into tagNames.

To plug your adon into a tagName, simply add them as lines in your js/main.js file:

// js/main.js
$(document).ready(function () {
  $("nav").adonHideOnScrollDown(true)
  $("blockquote").adonHideOnScrollDown(true)
})

This will attach your adon to the tagNames aside and blockquote.

What we learnt

  1. How to plug an adon into a tagName.

Exercise 4 FullScreenOnClick An adon which makes an tag full screen on click.

This time we will use elioGod's yeoman generator, generator-sin by calling yo sin:adon. This will quickly scaffold all the files needed for your adon, including the beginnings of a test. Enter FullScreenOnClick as your adonName.

yo sin:adon

What yo sin:adon makes

Respond to the questions, especially choosing an adonName.

This quickstart will assume you chose the name FullScreenOnClick.

What yeoman generator produces follows adon's pattern which is as follows:

project
│   ...
│
└───js
│   │   main.js
│   │   ...
│   │
│   └───adon
│       │   adonFullScreenOnClick.js
│       │   ...
│
└───stylesheets
│   │
│   └───adon
│       │   adonFullScreenOnClick.scss
│       │   ...
│
└───test
    │
    └───adon
        │-- adonFullScreenOnClick.js
        │   ...

What we learnt

Exercise 5 adons are about style

Start off by deleting js/adon/adonFullScreenOnClick.js. We won't need it.

Instead we will use one I prepared earlier, adonClick which features in the adonEvent jscript, provided in the adon package. In @elioway/adon/js/adon/adonEvent.js there are adons to toggleClass any given adonName in response to common event handlers. adonClick looks like this:

// jQuery protoType
jQuery.fn.extend({
  //protoType method name + parameter
  adonClick: function (adonName) {
    // The protoType is attached to a selector...
    return $(this).each(function () {
      // ... but we want to handle each tag.click event independently
      var tag = $(this)
      // Toggle the class when the tag is clicked.
      tag.click(function () {
        tag.toggleClass(adonName)
      })
    })
  },
})

We just need include the adonClick adon to our gulp build.

Open the gulpfile.js.

Add the path to the package to the js_watch list:

var js_watch = [
  "js/plugins.js",
  "js/adon/adon*.js",
  "./node_modules/@elioway/adon/js/adon/adonEvent.js",
]

Then add $('article').adonClick('adonFullScreenOnClick') the js/main.js file like this:

$(document).ready(function() {
  ...
  $('article').adonClick('adonFullScreenOnClick')
})

Now edit stylesheets/adon/adonFullScreenOnClick.scss:

.adonFullScreenOnClick {
  left: $personal-space;
  margin: 0 !important;
  position: absolute;
  right: $personal-space;
  z-index: 6000;
}

What we learnt

  1. The scss file is the most important feature of an adon. You might not even need the js.

  2. How to write an adon without an adonName script file.

Exercise 6 Testing your adon

Type npm run prettier at the command line. We expect 1 test to fail. This is the test yo sin:adon created in a previous execise.

You'll see something like this:

5 passing (61ms)
1 failing

1) jQuery.fn.extend.adonFullScreenOnClick
     removes class adonFullScreenOnClick from tag:
   TypeError: $(...).adofFullScreenOnClick is not a function
    at Context.done (test/adon/adonFullScreenOnClick.js:26:17)
    at Context.done (test/suites/adonTesterSuite.js:20:7)

The error 'TypeError: $(...).adofFullScreenOnClick is not a function' happens because we deleted the jscript file.

This is how we fix that test. Open test/adon/adonFullScreenOnClick.js.

Use an adon from the adon package

Change the line:

'../../js/adon/adonFullScreenOnClick.js',

to

'./node_modules/@elioway/adon/js/adon/adonEvent.js',

Whereever you see $(testTag).adonFullScreenOnClick(); change it to the same statement for activating it which we added to the js/main.js in the previous exercise.

$(testTag).adonClick('adonFullScreenOnClick');

Remove the following two lines:

$(testTag).adofFullScreenOnClick();
$(testTag)[0].should.not.have.class('adonFullScreenOnClick'); // no class

Now you should have this:

const suites = require('../suites/adonTesterSuite');

var testTag = 'h1'
var testML = `<${testTag}>PRETEST</${testTag}>`

suites.AdonTesterSuite(
  'jQuery.fn.extend.adonFullScreenOnClick',
  '../../js/adon/adonFullScreenOnClick.js',
  testML,
  function() {
    it('adonFullScreenOnClick adds class to tag', done => {
      $(testTag)[0].should.not.have.class('adonFullScreenOnClick');
      $(testTag).adonClick('adonFullScreenOnClick');
      $(testTag)[0].should.have.class('adonFullScreenOnClick'); // true class
      done();
    });

    it('adofFullScreenOnClick removes class from tag', done => {
      $(testTag).adonClick('adonFullScreenOnClick');
      $(testTag)[0].should.have.class('adonFullScreenOnClick');
      done();
    });
  }
);

Run mocha test/adon/adonFullScreenOnClick.js. The tests pass, but the testing isn't complete. We need to make sure the adon responds to the click event.

In the following code, we test the h1 tag in our test HTML; simulating a click event using jQuery code.

const suites = require('../suites/adonTesterSuite');

var testTag = 'h1'
var testML = `<${testTag}>PRETEST</${testTag}>`

suites.AdonTesterSuite(
  'jQuery.fn.extend.adonFullScreenOnClick',
  './node_modules/@elioway/adon/js/adon/adonEvent.js',
  testML,
  function() {
    it('has no class when activated', done => {
      $(testTag)[0].should.not.have.class('adonFullScreenOnClick');
      $(testTag).adonClick('adonFullScreenOnClick');
      $(testTag)[0].should.not.have.class('adonFullScreenOnClick'); // until clicked
      done();
    });

    it('if adon is not activated, click has no effect', done => {
      $(testTag)[0].should.not.have.class('adonFullScreenOnClick');
      $(testTag).click();
      $(testTag)[0].should.not.have.class('adonFullScreenOnClick'); // until activated
      done();
    });

    it('if adon is activated, click toggles the class adonFullScreenOnClick', done => {
      $(testTag)[0].should.not.have.class('adonFullScreenOnClick');
      $(testTag).adonClick('adonFullScreenOnClick');
      $(testTag).click();
      $(testTag)[0].should.have.class('adonFullScreenOnClick'); // when clicked
      $(testTag).click();
      $(testTag)[0].should.not.have.class('adonFullScreenOnClick'); // toggled when clicked
      done();
    });
  }
);

Now run the test again using npm run prettier.

``

What we learnt

  1. How to write a test for our adon which handles user interaction.

Tidy up

Next

Now you have seen how to write adons for your eliosin themes. This completes the eliosin quickstarts.

Go into the world and preach the gospel!