search

twbs / bootstrap

The most popular HTML, CSS, and JavaScript framework for developing responsive, mobile first projects on the web.
https://getbootstrap.com
MIT License
170.43k stars 78.82k forks source link

Utility API docs: Add @import functions, variables to the examples. #32557

Closed iatek closed 3 years ago

iatek commented 3 years ago

Utility API docs: Add @import functions, variables to the examples.

Since _utilities references, _variables, and _variables references _functions, in order to use the API you must import like..

@import "bootstrap/scss/functions";
@import "bootstrap/scss/variables";
@import "bootstrap/scss/utilities";

$utilities: map-merge(
  $utilities,
  (
    "cursor": (
      property: cursor,
      class: cursor,
      responsive: true,
      values: auto pointer grab,
    )
  )
);

Should this be mention in the Using the API section, perhaps explain in the text that says "Make sure our _utilities.scss is imported first,"? Or, simply add the correct @imports in each of the examples?

adro21 commented 3 years ago

@iatek Following the docs for v5 exactly I'm trying to add a cursor utility. I have _functions.scss, _variables.scss, and _utilities.scss loaded first and then I have this (as per the docs):

@import "bootstrap/scss/functions";
@import "bootstrap/scss/variables";
@import "bootstrap/scss/utilities";

    $utilities: map-merge(
      $utilities,
      (
        "cursor": (
          property: cursor,
          class: cursor
          responsive: true,
          values: auto pointer grab,
        )
      )
    );

I'm then adding this class to my element:

<a href="#" class="cursor-grab">Grab this</a>

However, the cursor-grab class I'm trying to add is nowhere to be found in the CSS output. Any idea what I'm doing wrong?

iatek commented 3 years ago

The docs don't currently show all the needed imports. But in your case, the class: cursor is missing the trailing comma as mentioned in #32542 which will be fixed beta 2.

adro21 commented 3 years ago

@iatek Sorry, I actually fixed that in my code...I noticed it was wrong in the docs. But that's not the issue. The issue is that I don't want to have to import the entire bootstrap.scss file. I'm currently doing it parts like this (for optimial load time):

// Required
@import "../node_modules/bootstrap/scss/functions";
@import "../node_modules/bootstrap/scss/variables";
@import "../node_modules/bootstrap/scss/mixins";
@import "../node_modules/bootstrap/scss/utilities";

$utilities: map-merge(
  $utilities,
  (
    "cursor": (
      property: cursor,
      class: cursor,
      state: hover,
      responsive: true,
      values: auto pointer grab,
    )
  )
); 

// Optional
@import "../node_modules/bootstrap/scss/alert";
@import "../node_modules/bootstrap/scss/badge";
@import "../node_modules/bootstrap/scss/breadcrumb";
@import "../node_modules/bootstrap/scss/button-group";
@import "../node_modules/bootstrap/scss/buttons";
@import "../node_modules/bootstrap/scss/card";
@import "../node_modules/bootstrap/scss/carousel";
@import "../node_modules/bootstrap/scss/close";
@import "../node_modules/bootstrap/scss/containers";
@import "../node_modules/bootstrap/scss/dropdown";
@import "../node_modules/bootstrap/scss/forms";
@import "../node_modules/bootstrap/scss/grid";
@import "../node_modules/bootstrap/scss/helpers";
@import "../node_modules/bootstrap/scss/images";
@import "../node_modules/bootstrap/scss/list-group";
@import "../node_modules/bootstrap/scss/modal";
@import "../node_modules/bootstrap/scss/nav";
@import "../node_modules/bootstrap/scss/navbar";
@import "../node_modules/bootstrap/scss/pagination";
@import "../node_modules/bootstrap/scss/popover";
@import "../node_modules/bootstrap/scss/progress";
@import "../node_modules/bootstrap/scss/reboot";
@import "../node_modules/bootstrap/scss/root";
@import "../node_modules/bootstrap/scss/spinners";
@import "../node_modules/bootstrap/scss/tables";
@import "../node_modules/bootstrap/scss/toasts";
@import "../node_modules/bootstrap/scss/tooltip";
@import "../node_modules/bootstrap/scss/transitions";
@import "../node_modules/bootstrap/scss/type";
@import "../node_modules/bootstrap/scss/bootstrap-grid";
@import "../node_modules/bootstrap/scss/bootstrap-reboot";
@import "../node_modules/bootstrap/scss/bootstrap-utilities";

// Helpers
@import "../node_modules/bootstrap/scss/helpers";

// Utilities
@import "../node_modules/bootstrap/scss/utilities/api";

Shouldn't this work? (I can confirm it currently does not) I can't imagine that the only way to add custom utilities is to be forced to always load the entire bootstrap.scss file...

iatek commented 3 years ago

It does work as I mentioned here: https://stackoverflow.com/a/65386748/171456 .. but why import all those files separately after the changes? .. just import bootstrap entirely.

adro21 commented 3 years ago

Importing the entire bootstrap scss file is not optimal for load time in a production environment. When my project is deployed to production, I plan to remove all the imports that I don't need. Bootstrap docs even recommend this: "When using Sass in your asset pipeline, make sure you optimize Bootstrap by only @importing the components you need."

I shouldn't have to import the entire bootstrap.scss file for this to work right?

iatek commented 3 years ago

Are you using all of Bootstrap? .. or just the Bootstrap utilities?

adro21 commented 3 years ago

I'm using various parts of bootstrap, but just for example, there's several parts like modals, breadcrumbs, etc. I won't need and plan to remove from the imports.

iatek commented 3 years ago

Then you would @import those other parts after the changes, and yes would work as long as you @import utilities after

adro21 commented 3 years ago

See my code above, I am making all my imports after the changes, except for:

@import "../node_modules/bootstrap/scss/functions";
@import "../node_modules/bootstrap/scss/variables";
@import "../node_modules/bootstrap/scss/utilities";

...which are being imported before.

And this still does not work.

iatek commented 3 years ago

For me it seems to work: https://codeply.com/p/m14Nzv3jVX

Make sure the paths are all correct and the SASS compiler has the correct includePaths. Also, is bootstrap.css being referenced/included outside of your SASS customization?

adro21 commented 3 years ago

My paths are correct and the output css file is being referenced correcty. If I remove all the parts except bootstrap-utlities like you have in your exmaple, then yes, cursor grab works.

But if I include all the other parts after (like in my example a few comments back), then 'cursor-grab' does not get compiled in my css file...

The only way I can now get it to work is if I move @import "../node_modules/bootstrap/scss/bootstrap-grid"; above the custom code with the others like this:

// Required
@import "../node_modules/bootstrap/scss/functions";
@import "../node_modules/bootstrap/scss/variables";
@import "../node_modules/bootstrap/scss/utilities";
@import "../node_modules/bootstrap/scss/bootstrap-grid";

That doesn't seem right...Why would bootstrap-grid need to be imported first in order to add a utility class?

iatek commented 3 years ago

@adro21 because if you just want to optionally add the grid classes you should only @import "../node_modules/bootstrap/scss/grid". bootstrap-grid is for building a grid/flexbox only version, and therefore also imports utilities which is resetting your utility overrides. It's all explained in the customize docs

It works: https://codeply.com/p/m14Nzv3jVX

iatek commented 3 years ago

Anyway, @XhmikosR I didn't intend for this issue to be hijacked with SASS debugging. If you think my aforementioned feature request (to mention the other required @imports) is legit I'd be happy to open a PR.

adro21 commented 3 years ago

@iatek Sorry, didn't mean to hijack the thread! Appreciate your help and the explanation, but anyway, your example still isn't working for me: https://d.pr/v/harXWd