Roots Discourse

Is Bower documentation needed? (Can I help?)

Dr. Roots team,

On a previous thread I threw my rattle out the pram complaining about Sage (once Roots became Sage) because suddenly I had to use Bower and couldn’t do simple things so I threw my rattle out the pram.

After a lot of pain and trial and error I absolutely love it but before making other Devs use Sage I make them use my own “fork” of Sage (Sage but with a few commented out code examples!)

I’ve just had another scan through the documentation and it seems the only examples on what to do with Bower are Austin’s Asset Builder documentation - this is a guy who on a Wordpress podcast would happily talk about the Cartesian product and the like (hey, I’M interested but this is WORDPRESS :smile:

So like this is how I install Owl Carousel

  1. I type in bower search owl to a console (because http://bower.io/search/ just never really returns results)

  2. I pick “owl-carousel2” (after verifying the URL that it’s the correct package)

  3. I type bower install --save owl-carousel2

  4. (the hard part) I then add this to Sage’s bower.json

    "owl-carousel2":{
      "main": [
        "dist/owl.carousel.js",
        "src/scss/owl.carousel.scss",
        "src/scss/owl.autoheight.scss",
        "src/scss/owl.animate.scss",
        "src/scss/owl.theme.default.scss"
      ]
    }

(correct me as I’m probably wrong) - this overrides everything, but checking that Bower package I then pull all the needed SCSS which Sage automatically injects and now I have a styled and working OWL Carousel

HOW AWESOME IS LIFE WHEN THIS WORKS

This helped me do things like this with Waypoints - pull in sticky.js as well

"overrides": {
  ...,
  "waypoints": {
    "main": [
      "./lib/jquery.waypoints.js",
      "./lib/shortcuts/sticky.js"
     ]
   }
}

(EDIT by @JulienMelissas to include “overrides” because people were still confused)

I am now the king of Bower!

Hey @buswell,

That all seems like one way to do it, although some packages have a main argument already defined (https://github.com/imakewebthings/waypoints/blob/master/bower.json#L3). I think the strength of the Sage workflow is that it’s that flexible. You can do almost anything you need with it.

In my opinion, all that stuff you’re doing is documented. Right above where you added those, there’s an example of how to add JS and CSS with Bootstrap. But if you think there’s somewhere where the documentation could be improved, PRs are always welcome.

I’ll add an “example” tag to this thread though, so someone can see how this might work.

Cheers Julian for your reply!

Just my “two cents worth” (as I believe is the American expression).

Yes I agree that from looking at the bootstrap code it all looks obvious now, pero español es super facil para mi ahora que puedo hablarlo, but a few years ago I didn’t even understand how to leave the airport :smile:

I just remember struggling on these bits and seemed to have problems with ALL the common libraries - OWL Carousel, BXslider, magnific popup, scrollto.

Yes you’re right they all have main.json - but looking at the Waypoints one, that by default pulls in the noframework JS. Really Sage devs will want the jQuery one. Like unless you know how to override files, Bower is really not very useful.

TL:DR;
Essentially I was mainly feeling guilty that I watch all your talks, listen to all your podcasts and (most importantly) make $$$ from all your hard work so I was just thinking how I could help out.

I could see loads of threads with people asking pretty similar questions about bower all with similar levels of desperation, and you complained in a talk “I spend way too long in the forum”

I’ll try and come up with some other way to help out, unfortunately I can’t see myself being as useful as you and Austin any time soon!

Cheers

This is where the process is described: https://roots.io/sage/docs/theme-development-and-building/

I believe it goes over everything, and does link to the examples in asset builder.

I think we can all sympathize with the frustration that can come from learning a new tool, we’ve all been there multiple times. However we do have to take that into consideration when writing the documentation as well. It’s pretty difficult to cover every use case and potential issue that will arise, and that’s where a place like this forum helps

Of course, if there is anything that’s missed, or something that can be clarified or revised, we would love to know and have some suggestions. Like you said, it’s common knowledge for me now so I don’t always spot issues.

Documentation is one of the hardest parts of any open source project. It’s probably the most scrutinized and used, but the least amount of PR’s made for it, so generally it lands square on the owners and maintainers. So yes, definitely if your have ideas, suggestions, want to help, get on Github and make some PR’s and start a discussion :slight_smile:

2 Likes

@buswell I’m trying to get waypoints working. I need the same combination of using the sticky shortcuts. To clarify your bower code :

"waypoints":{
      "main": [
        "lib/jquery.waypoints.js",
        "lib/shortcuts/sticky.js"
        ]
    }, 

This goes in the waypoints bower.json, NOT in Sage’s one (for anyone not clear about this). This all works fine in gulp watch etc. but, I can’t get it to actually activate a class in the page. One question is: where are you including your actually function? i.e.:

    var sticky = new Waypoint.Sticky({
      element: $('.basic-sticky-example')[0]

})

for example? I tried this in main.js, but get the error:

Uncaught TypeError: t(…).waypoint is not a function

I assume because it needs to come after the sticky.js load?

It’s not clear to me (despite reading and re-reading the documentation and forums) exactly where I should be adding this.

1 Like

No, nononononono - never edit any files in the bower_components directory. Also this is getting way off topic.

1 Like

If I’m doing this wrong, then it’s the result of gaps in documentation and answers the post question - Yes, WAY better documentation is needed.

I’ve spent two days trying to do this the ‘right’ way. This has necessitated a lot of experimentation because the documentation isn’t as clear as it could be and the forum help on this is sketchy too. I’ve read you book, visited this forum and the bower site.

I’ll make a separate post, but back ON topic, the documentation for using bower based libraries, and adding related scripts is really hard to understand from the way it is currently written. Better documentation is definitely needed. I am happy to help rewrite this, but as yet, I still can’t make it work via the documentation methods.

1 Like

Yep, it could totally be the fact that this project needs more documentation, it could also just be you not understanding (which is OK and why we have a forum). Plenty of people have successfully figured it out themselves.

We’re trying as hard as we can. I don’t think that the team member’s posts are sketchy most of the time. Many of the frequent users also provide good info regularly. While we don’t have time to comment on every thread, we get a notification in our Slack when someone makes a new thread and try to get to it.

Like I said above, PRs, accepted.

<rant>This is Open Source work. I spent over 45 minutes this morning on the Roots forum answering your other question (in a non-sketchy way), one other, and doing come cleanup. That’s about $70 of billable time at my hourly rate, and I didn’t ask for a penny. Before you go complaining about things, please take a second to remember it’s Open Source, and we’re writing the software, supporting it, as well as doing all the work we do in order to keep food on the table. If you don’t like the job this team is doing, the beauty is that you don’t have to use anything, OR you can write a PR and make things better. Seriously tho, Open Source work sometimes reminds me of how I was treated when I used to wait tables… And I got out of waiting tables for a reason.</rant>

2 Likes

I’m not complaining! I think you’ve misunderstood my tone. I’m here to ask questions and add to the project! My comments were only to inform that I HAD already searched the forums thoroughly before asking these questions. I’ve really struggled with this part of Sage/Bower etc. and I’m still trying to learn it. Once I’ve got this working, I can provide valuable insight for newbies (like myself) in one post. I’m looking forward to doing this. It is definitely my intention to write this bit, but I need a little help from those who understand it better so I can compile this into one post. This would be my contribution back to the forum and Sage users stuck on this too. To be fair, I’ve spent two days trying to add a couple of scripts to a Sage project. This is precisely why I want to write such a post to prevent anyone else having to go through this. :smile:

Hey Blitz, I definitely feel your pain! You can see a similar post from me where I cried all over the forums. Two days of debugging such things really brings the worst out of people!!

Just wait until you get Bower working. Suddenly you’ll become the biggest Roots fan boi ever to the point where (like me) saying this to your boss becomes the norm

“IF I CAN’T USE THE ROOTS STARTER THEME THEN I WILL NO LONGER WORK FOR YOU. THERE IS NO DISCUSSION HERE”

On a lighter note, how did I start off my post as "Dr. Roots team, "

Of course that was meant to be Dear!

@buswell I’m definitely with you and can see the benefits. I’m a designer and front end developer and it’s just the set up and working practices I’m still getting to grips with. I’ve been working with web for a long time, but most of this stuff is like an alien planet - hence asking questions about where I am and what to do!

I’m still stuck with the above example. I can see where I’ve misread/misunderstood where to add the override (thanks @benword for the clarity).

It looks like your example has too many closing brackets to me and I get a syntax error in terminal. So, for the purpose of clarity (I will make a brand new post specific to this, I promise!), here’s the whole sage override boilerplate (with flexboxgrid and waypoint dependencies auto included - managed that bit!):

{
  "name": "sage",
  "homepage": "https://roots.io/sage/",
  "authors": [
    "Ben Word <ben@benword.com>"
  ],
  "license": "MIT",
  "private": true,
  "dependencies": {
    "animate.less": "*",
    "bootstrap-sass": "3.3.5",
    "flexboxgrid": "~6.3.0",
    "waypoints": "~4.0.0"
  },
  "overrides": {
    "bootstrap-sass": {
      "main": [
        "./assets/stylesheets/_bootstrap.scss",
        "./assets/javascripts/bootstrap/transition.js",
        "./assets/javascripts/bootstrap/alert.js",
        "./assets/javascripts/bootstrap/button.js",
        "./assets/javascripts/bootstrap/carousel.js",
        "./assets/javascripts/bootstrap/collapse.js",
        "./assets/javascripts/bootstrap/dropdown.js",
        "./assets/javascripts/bootstrap/modal.js",
        "./assets/javascripts/bootstrap/tooltip.js",
        "./assets/javascripts/bootstrap/popover.js",
        "./assets/javascripts/bootstrap/scrollspy.js",
        "./assets/javascripts/bootstrap/tab.js",
        "./assets/javascripts/bootstrap/affix.js",
        "./assets/fonts/bootstrap/glyphicons-halflings-regular.eot",
        "./assets/fonts/bootstrap/glyphicons-halflings-regular.svg",
        "./assets/fonts/bootstrap/glyphicons-halflings-regular.ttf",
        "./assets/fonts/bootstrap/glyphicons-halflings-regular.woff",
        "./assets/fonts/bootstrap/glyphicons-halflings-regular.woff2"
      ]
    }
  }
}

Would someone kindly show me how it would look with the the above waypoints code?

{
  "name": "sage",
  "homepage": "https://roots.io/sage/",
  "authors": [
    "Ben Word <ben@benword.com>"
  ],
  "license": "MIT",
  "private": true,
  "dependencies": {
    "modernizr": "2.8.2",
    "bootstrap-sass-official": "3.3.5",
    "owl-carousel2": "~2.0.0-beta.3",
    "waypoints": "jquery-waypoints#~4.0.0"
  },
  "overrides": {
    "modernizr": {
      "main": "./modernizr.js"
    },
    "bootstrap-sass-official": {
      "main": [
        "./assets/stylesheets/_bootstrap.scss",
        "./assets/javascripts/bootstrap/transition.js",
        "./assets/javascripts/bootstrap/alert.js",
        "./assets/javascripts/bootstrap/button.js",
        "./assets/javascripts/bootstrap/carousel.js",
        "./assets/javascripts/bootstrap/collapse.js",
        "./assets/javascripts/bootstrap/dropdown.js",
        "./assets/javascripts/bootstrap/modal.js",
        "./assets/javascripts/bootstrap/tooltip.js",
        "./assets/javascripts/bootstrap/popover.js",
        "./assets/javascripts/bootstrap/scrollspy.js",
        "./assets/javascripts/bootstrap/tab.js",
        "./assets/javascripts/bootstrap/affix.js",
        "./assets/fonts/bootstrap/glyphicons-halflings-regular.eot",
        "./assets/fonts/bootstrap/glyphicons-halflings-regular.svg",
        "./assets/fonts/bootstrap/glyphicons-halflings-regular.ttf",
        "./assets/fonts/bootstrap/glyphicons-halflings-regular.woff",
        "./assets/fonts/bootstrap/glyphicons-halflings-regular.woff2"
      ]
    },
    "owl-carousel2": {
      "main": [
        "dist/owl.carousel.js",
        "src/scss/owl.carousel.scss",
        "src/scss/owl.autoheight.scss",
        "src/scss/owl.animate.scss",
        "src/scss/owl.theme.default.scss"
      ]
    },
    "waypoints": {
      "main": [
          "lib/jquery.waypoints.js",
          "lib/shortcuts/sticky.js"
      ]
    }
  }
}

This is off a working project i’m looking at right now with a sticky menu

I’m on Sublime Text 3 with the SublimeLinter-JSON package installed which definitely helps with highlighting any syntax errors!

Gulp doesn’t seem to throw any errors for me if stuff is entered wrong which really makes working this out difficult. Multiple points of failure and all that!

Ah cool… right, that works - no errors!

I have noticed that some examples have a period before the path and some don’t: ".lib/ … " and "lib/ … "

I’ve used your no period example above. So… is this supposed to now compile to the main.js?

1 Like

Please continue discussion about waypoints here: Adding javascript files (Waypoints) (that’s my post which should solve it for you, thank you @buswell for helping). Let’s keep this to Bower documentation.

On that note, I have proposed a blog post to help people with wrapping their heads around how all of this works, because we get far too many of the “how do I add js/css/this-library/that-library” threads. I will try to get to that ASAP.

3 Likes

Yeah I myself have also noticed that!!! Both seem to work

The default Sage bower.json has the dots, the bower.json the comes in the Waypoints package doesn’t.

Exactly these waypoints libraries now should all be brought into your main.js (they work for me!!)

Honestly I swear once you get this working you’ll hate projects where you don’t use Bower. Believe it or not it’s actually much quicker to use Bower as you run one line in your console then copy and paste in the same bits into Sage’s bower.json

Watch out in my example I’ve got owl-carousel there so don’t just copy and paste mine in i’ve no idea what will happen

hate to take it off topic (again), but they’re not the same thing: http://stackoverflow.com/questions/7591240/what-does-dot-slash-refer-to-in-terms-of-an-html-file-path-location

no slash or dot is just relative

1 Like

@JulienMelissas - thanks for the clarity. Seems there is no preferred usage of either for uniformity. I think I’ll stick with NOT using the period as it’s minutely less code!

Hi guys,

this is my bower.json:

{
  "name": "sage",
  "homepage": "https://roots.io/sage/",
  "authors": [
    "Ben Word <ben@benword.com>"
  ],
  "license": "MIT",
  "private": true,
  "dependencies": {
    "bootstrap-sass": "3.3.5",
    "font-awesome": "fontawesome#~4.5.0",
    "owl.carousel": "owl-carousel2#~2.0.0-beta.3"
  },
  "overrides": {
    "bootstrap-sass": {
      "main": [
        "./assets/stylesheets/_bootstrap.scss",
        "./assets/javascripts/bootstrap/transition.js",
        "./assets/javascripts/bootstrap/alert.js",
        "./assets/javascripts/bootstrap/button.js",
        "./assets/javascripts/bootstrap/carousel.js",
        "./assets/javascripts/bootstrap/collapse.js",
        "./assets/javascripts/bootstrap/dropdown.js",
        "./assets/javascripts/bootstrap/modal.js",
        "./assets/javascripts/bootstrap/tooltip.js",
        "./assets/javascripts/bootstrap/popover.js",
        "./assets/javascripts/bootstrap/scrollspy.js",
        "./assets/javascripts/bootstrap/tab.js",
        "./assets/javascripts/bootstrap/affix.js",
        "./assets/fonts/bootstrap/glyphicons-halflings-regular.eot",
        "./assets/fonts/bootstrap/glyphicons-halflings-regular.svg",
        "./assets/fonts/bootstrap/glyphicons-halflings-regular.ttf",
        "./assets/fonts/bootstrap/glyphicons-halflings-regular.woff",
        "./assets/fonts/bootstrap/glyphicons-halflings-regular.woff2"
      ]
    },
    "owl-carousel2":{
      "main": [
        "dist/owl.carousel.js",
        "src/scss/owl.carousel.scss",
        "src/scss/owl.autoheight.scss",
        "src/scss/owl.animate.scss",
        "src/scss/owl.theme.default.scss"
      ]
    }
  }
}

How can I modify the owl .scss files? Actually the script works with the css files inside

dist/assets

how can I replace them? The owl-carousel has an issue: in my html there isn’t owl-theme class and nav dots are invisible. I need to correct this bug manually.

Thank you in advance.

Just only import OWL’s JS and then you can just copy and paste their Scss files your (Sage’s) Scss files.

That’s what I was doing for ages until I worked out this proper way of doing it!