Skip to main content
Help the Python Software Foundation raise $60,000 USD by December 31st!  Building the PSF Q4 Fundraiser

Django application to add the Bulma CSS framework and its extensions

Project description

django-simple-bulma

Discord License Website

django-simple-bulma is a Django application that makes Bulma and Bulma-Extensions available to use in your Django project with as little setup as possible. The goal of this project is to make it as easy as possible to use Bulma with Django.

This project currently uses Bulma v0.9.1, and is automatically updated with every new release. If a new version has come out with features you'd like to make use of, please create an issue, and we will be happy to make a release to update it.

Installation

To get django-simple-bulma, up and running for your Django project, follow these simple steps:

  • Install it from PyPI with pip install django-simple-bulma (or add it to your Pipfile)

  • In your Django projects settings.py file:

    • Add django_simple_bulma to your INSTALLED_APPS
      INSTALLED_APPS = [
        #...
        'django_simple_bulma',
        #...
      ]
      
    • Add django_simple_bulma.finders.SimpleBulmaFinder to your STATICFILES_FINDERS. This normally holds two default handlers that you will probably want to keep, so unless you have any other custom Finders, it should look like this:
      STATICFILES_FINDERS = [
        # First add the two default Finders, since this will overwrite the default.
        'django.contrib.staticfiles.finders.FileSystemFinder',
        'django.contrib.staticfiles.finders.AppDirectoriesFinder',
      
        # Now add our custom SimpleBulma one.
        'django_simple_bulma.finders.SimpleBulmaFinder',
      ]
      
  • Run python manage.py collectstatic command in order to build Bulma and move it to your staticfiles folder. Please note that you will need to use this command every time you make a change to the configuration, as this is the only way to rebuild the Bulma css file. If you are not using collectstatic, read up on it and start using it.

    This app works fine with Whitenoise, which is a great way to serve static files without needing to mess with your webserver.

django-simple-bulma should now be working! In order to import it into your template, first load the app with {% load django_simple_bulma %}, and then use the {% bulma %} template tag. If you're planning on using icons, you might also want to import FontAwesome by using {% font_awesome %}.

  <head>
      <!-- ... -->
      {% load django_simple_bulma %}
      {% bulma %}
      {% font_awesome %}
      <!-- ... -->
  </head>
  • You're all set! Any Bulma classes you apply should now be working!

Customization

Bulma looks nice by default, but most users will want to customize its look and feel. For this, we've provided a super simple way to change the Bulma variables and to choose which Bulma extensions you want to load into your project.

In order to do this, we'll simply create a dictionary inside your settings.py called BULMA_SETTINGS, and configure it there. Here's an example of what that looks like:

# Custom settings for django-simple-bulma
BULMA_SETTINGS = {
    "extensions": [
        "bulma-collapsible",
        "bulma-calendar",
    ],
    "variables": {
        "primary": "#000000",
        "size-1": "6rem",
    },
    "alt_variables": {
        "primary": "#fff",
        "scheme-main": "#000",
    },
    "output_style": "compressed",
    "fontawesome_token": "e761a01be3",
}

You may here define any variable found on the Bulma variables page, and you may use any valid SASS or CSS as the value. For example, hsl(217, 71%, 53%) would be a valid value for a color variable, as would #ffff00. Please note that any syntactically incorrect values may prevent Bulma from building correctly, so be careful what you add here unless you know exactly what you're doing.

Multiple themes

If you want multiple different configurations of variables, then you should define them as separate themes. Define a new theme by providing a key that matches the regex \w+_variables (e.g. alt_variables or dark_variables), unique stylesheets will then be generated using the variables at that key.

To use these stylesheets in a template, pass the theme name to the {% bulma %} tag either as a string {% bulma 'alt' %} or as a template variable {% bulma theme %}.

Extensions

If the extensions key is not found, it will default to not loading any extensions. If you want all extensions, simply set it to the string "all".

We currently support these extensions:

  • bulma-badge
  • bulma-calendar
  • bulma-carousel
  • bulma-collapsible
  • bulma-checkradio
  • bulma-divider
  • bulma-megamenu
  • bulma-pageloader
  • bulma-pricingtable
  • bulma-quickview
  • bulma-ribbon
  • bulma-slider
  • bulma-steps
  • bulma-switch
  • bulma-tagsinput
  • bulma-timeline
  • bulma-tooltip
  • bulma-coolcheckboxes (Cool-Checkboxes-for-Bulma.io)

If an extension you want to use is missing, feel free to create an issue and we will be happy to add it. Alternatively, add it yourself and create a pull request (see this pr for some context on how to go about doing that).

CSS style

The output_style parameter determines the style of the resulting CSS file. It can be any of "nested" (default), "expanded", "compact", and "compressed". It is recommended to use "compressed" in production as to reduce the final file size.

FontAwesome

The optional fontawesome_token parameter allows you to specify your personal FontAwesome kit, which is necessary for FontAwesome v6 and up. This should be set to the identifier part of your FontAwesome kit script src parameter. For example, if your FontAwesome kit looks like this:

<script src="https://kit.fontawesome.com/e761a01be3.js" crossorigin="anonymous"></script>

Then your fontawesome_token should be e761a01be3.

This is used by the {% font_awesome %} template tag to set up FontAwesome for you. If you don't specify a fontawesome_token, the template tag will still work, but will then use an older version of FontAwesome (v5.14.0).

Additional scripts

For your convenience, we also give you the option to add other quality of life improvements to your Bulma app. You may want to add these as well if they sound useful to you.

  • bulma-fileupload will handle displaying the filename in your file upload inputs.
  • bulma-navbar-burger will hook up your navbar-burgers and navbar-menus automatically, to provide a toggle for mobile users. We use a slightly updated version of the example from Bulma's documentation - simply add a data-target attribute to your navbar-burger that refers to the id of the navbar-menu that should be expanded and collapsed by the button.
  • bulma-notifications will allow you to close notifications by clicking on the X button.
  • bulma-dropdown will open/close dropdowns using the is-active class. It mimics how the dropdowns function on the documentation page.

Compiling additional SCSS

If you're writing custom SCSS for your application, django-simple-bulma does provide a very basic mechanism for compiling it for you. This is provided because, currently, django-simple-bulma will cause issues with current Django apps that exist to compile SCSS for you.

To use this feature, please specify the custom_css key when defining your BULMA_SETTINGS. This should be a list of strings, containing relative paths to .scss files to be compiled.

BULMA_SETTINGS = {
    "custom_scss": [
        "myapp/static/css/base/base.scss"
    ],
}

Please note: The default Django behavior when collecting static files is to keep the containing file structure for them when they're copied over to the final static files directory. We attempt to do the same thing by parsing the given path to your .scss file, using the following strategy:

  • If a containing path exists in the STATICFILES_DIRS setting, assume that this is the base path to use, and the directory structure below it will be used to contain the resulting .css file
  • Otherwise, if the path contains static/, assume that the base path ends there and use the rest of the path below it to contain the resulting .css file.

If both of these strategies fail to figure out what base path to use, an exception will be raised.

Troubleshooting

  • If you have the module sass installed, please note that it is incompatible with this project. There is a namespace conflict between sass and libsass which will make django-simple-bulma crash when you attempt to do a collectstatic. To solve this, just uninstall sass and use libsass instead.

If you run into any other problems with this app, please create an issue, and we will be happy to help you with it. Alternatively, head over to our discord server at https://discord.gg/python and we'll help you figure it out over chat.

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Files for django-simple-bulma, version 2.1.0
Filename, size File type Python version Upload date Hashes
Filename, size django_simple_bulma-2.1.0-py3-none-any.whl (368.3 kB) File type Wheel Python version py3 Upload date Hashes View
Filename, size django-simple-bulma-2.1.0.tar.gz (310.0 kB) File type Source Python version None Upload date Hashes View

Supported by

Pingdom Pingdom Monitoring Google Google Object Storage and Download Analytics Sentry Sentry Error logging AWS AWS Cloud computing DataDog DataDog Monitoring Fastly Fastly CDN DigiCert DigiCert EV certificate StatusPage StatusPage Status page