Is Bower documentation needed? (Can I help?)

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 @ben 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: javascript - What does "./" (dot slash) refer to in terms of an HTML file path location? - Stack Overflow

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!