django-simple-bulma
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.2, 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 yourINSTALLED_APPS
INSTALLED_APPS = [ # ... 'django_simple_bulma', # ... ]
- Add
django_simple_bulma.finders.SimpleBulmaFinder
to yourSTATICFILES_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', ]
- Add
-
Run
python manage.py collectstatic
command in order to build Bulma and move it to yourstaticfiles
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 usingcollectstatic
, 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 yournavbar-burger
s andnavbar-menu
s automatically, to provide a toggle for mobile users. We use a slightly updated version of the example from Bulma's documentation - simply add adata-target
attribute to yournavbar-burger
that refers to theid
of thenavbar-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 theis-active
class. It mimics how the dropdowns function on the documentation page.bulma-modal
will handle opening and closing modals. Just assign themodal-button
class to a<button>
, and make sure it has adata-target
attribute that matches theid
of the modal that you want to open. See the example code from Bulma's documentation for modal element code.
Compiling custom SCSS
If you're writing custom SCSS for your application, django-simple-bulma
provides a mechanism for compiling it for you. This is provided mainly because django-simple-bulma
may cause conflicts and issues with other tools 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": [
"css/base/base.scss", # This is okay
"my_app/static/css/base/base.scss", # This also is okay
"C:\Users\MainDawg\my_app\static\..." # Don't do this, though.
],
}
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 staticfiles directory. We do the same thing, so all directories and subdirectories will still be intact in your staticfiles folder after they've been collected.
Here's the strategy the finder uses:
- If your path contains
static/
, assume that the base path ends there and use the rest of the path as a relative path to the resource. - Use whatever Finders you have enabled in your
settings.py
to search for the file using that relative path. - If the path is found using one of these Finders, compile it to css and collect it.
- Otherwise, raise a
ValueException
asking you to double-check the filepath.
Troubleshooting
- If you have the module
sass
installed, please note that it is incompatible with this project. There is a namespace conflict betweensass
andlibsass
which will makedjango-simple-bulma
crash when you attempt to do acollectstatic
. To solve this, just uninstallsass
and uselibsass
instead.
If you run into any other problems with this app, please create an issue, and I'll will be happy to help you with it. You can also find me on Discord as lemon#0001
- either at #django-simple-bulma in the lemonsaurus discord or at https://discord.gg/python.
Intermittent "circular import" when starting Django app
Hi,
Thanks for a nice Python/Django package. It works fine, but sometimes I get this error on startup with this Django app installed (as described in the installation details):
Note that this only happens sometimes, which is both puzzling and annoying. It can also happen when making a change to any
.py
file in the project, i.e. when the apps are reloaded. Any ideas? Thanks in advance.Latest release seems to be overriding the Bulma default is-link color
Noticed that django-simple-bulma has changed the default "is-link" modifier color. The default used to be light blue, but with version 2.4.0, it has changed to a light purple (which is what I believe you use on your Python Dischord site). Haven't dug into the code yet, but I'm guessing maybe your site's css scheme might have been shipped.
Upgrade to Django 3.*
Looks like a least one change is needed to be make to django-simple-bulma work with for Django 3.*
django_simple_bulma.py uses 'from django.contrib.staticfiles.templatetags.staticfiles import static' in it's imports and it looks like it was depreciated in Django-2.1* for 'django.templatetags.static.static()'
https://docs.djangoproject.com/en/3.0/releases/2.1/#deprecated-features-2-1
If I get a few free cycles I'll look at working up a fix, and see if there are any other changes that need to be made.
Full path in js files
I have following problems with JS files loaded into template.
Your loader uses full path which in my case means that path contains site-packages and all that stuff
/lib/python3.6/site-packages/django_simple_bulma/js/bulma-tagsinput.js
Loading
css
works fine because it's done like thiscss = static("css/bulma.css")
instead of using full path.By modifying following code to use
filename.name
to construct path seems to work in my case.Now to my actual question. Is there something wrong on my end or is there actually small bug in code?
Thank you very much for your work with this and if there's anything I can do to help further just say a word.
Submodule bulma instead of keeping a copy.
Right now, we've got copies of specific versions of Bulma and Bulma-Extensions in this repo, which is license permissable but adds maintenance in that we have to manually update these files to in order to "update" to a new version.
Perhaps we could include bulma and bulma-extensions as submodules to ensure these stayed up to date, and that we did not need to manage these files ourselves?
Add extension submodules
Further work on #42 Closes #7
I didn't include some extensions because they were extremely out of date or simple not worth the time. Most of the extensions are made by the same guy, so their directory structure all match up, but others have wildly differing setups. I tried my best to have it figure out what files are relevant, meaning adding new extensions should only be a matter of running:
Since i removed the old extensions, this is definitely not backwards compatible, because of this I suggest that when this branch is merged we release it as v2 or at least v1.4. Also, the way I've been testing is with one big file with all the extensions, which is only a visual verification. I also haven't tested the custom variables some of the extensions use.
Add pep8-naming and more pre-commit hooks
Relevant Issues
python-discord/organisation#138 python-discord/organisation#153 Closes https://github.com/python-discord/django-simple-bulma/issues/40
Description
New hooks were added for pre-commit and they will run in CI too. pep8-naming was added as a flake8 plugin to ensure names comply with PEP 8.
Hooks added
A couple of these hooks automatically apply fixes. However, they still report failure and leave any changes they make uncommitted. Therefore, the user has to commit the automatic fixes.
check-merge-conflict
- Check for files that contain merge conflict strings.check-yaml
- Attempts to load all yaml files to verify syntax.end-of-file-fixer
- Makes sure files end in a newline and only a newline.mixed-line-ending
- Replaces mixed line endings with LF.trailing-whitespace
- Trims trailing whitespace.python-check-blanket-noqa
- Enforce thatnoqa
annotations always occur with specific codesReasoning
pip install -e .[dev]
.Additional Details
The pre-commit venv is cached. There should only be a cache miss if the
.pre-commit-config.yaml
file changes or if the location of the Python interpreter changes (more realistically, if the Python version changes). Maybe Azure wipes the cache sometimes too, but in that case pre-commit will simply re-create the environment.Github Release action for v2.2.0 failed
Looks like your Github action is using the depreciated legacy method. I believe if you update to a more recent gh action (like pypa/[email protected]) it should work.
Missing files in v2.0.0 release files
Updating to v2.0.0, and it looks like the submodules you're using now aren't included in the tarball. Since I get the following error when attempting to run django.
FileNotFoundError: [Errno 2] No such file or directory: '/home/bpepple/.local/share/virtualenvs/metron-UZX73b7p/lib/python3.6/site-packages/django_simple_bulma/bulma/sass'
Pulled the tarball down from the release page, and verified the bulma folder is empty.
New release: 1.2.0
For 1.2.0, we should add support for Django 2.2, Django 3.0 and Python 3.8.
So here's what needs to be done before we release the 1.2.0:
django-simple-bulma
inside a Django 3.0 app running Python 3.8, and verify that it still works as expected.setup.py
file and add Django 2.2, Django 3.0, Python 3.8 to the list of classifiers.setup.py
, bump the version ofdjango-simple-bulma
to 1.2.0Once this has been done, we can do a release to PyPI.
CompileError() with Powershell
Hi,
I'm getting the following error with Powershell. This is likely because of platform insensitive paths in the finder code.
Best, Oguzhan
Trouble running "python manage.py collectstatic" in Python 3.7.5 Django app
After successfully installing django-simple-bulma via pip I run collectstatic per instructions and get the following error:
I believe Python 3.7.5 does not like the := operator (apparently added in 3.8).
`_get_custom_css` results in `sass.CompileError` when `custom_scss` path is not found by finders
I have set Bulma settings to
I expect to see
ValueError: Unable to locate the SCSS file ...
. However I get an unhelpfulsass.CompileError
instead:It looks like this package has an helpful error that should be show, however
https://github.com/lemonsaurus/django-simple-bulma/blob/3e3eac809cb8f04ce2494a406ee375ea0dce63ae/django_simple_bulma/finders.py#L170
when this step is run, the value is an empty list
[]
, so the comparison toNone
is evaluated as false.Suggestion: Change expression to
if not absolute_path
(I can submit a PR with that if desired).Bulma Calendar widget shows incorrect value
Using the Bulma Calendar widget and notice that it's showing the incorrect date on a form.
Below screenshot shows the values it should be:
When updating the object the Bulma-Calendar widget shows the following:
It appears to be showing a day earlier than the value of the input:
Did a quick look at upstreams bugs and didn't see any for this bug, but when I get some free time I'll give a more thorough search.
New to django, how do i add the bulma calendar to my website?
Hi there, I'm new to django and ive followed your steps on installing the app and the extensions. Just one question: How do i add the calendar to my website? I'm completely lost and I cant find anything online to help me. Thanks!
Using multiple themes
Currently, I attempting to use this project's multiple themes functionality to create a dark and light mode.
While trying to do this am I facing issues with sending duplicate
.js
files, as the tag has been used twice. With this.js
being served twice, it is creating two event handlers for the navbar burger menu on the page and is causing it to stop working.Django template:
Firefox network tab when loading the page:
I am unsure how Django extensions work, but having a way to ensure that only one
.js
file is served would allow me to implement the functionality I want.This functionality for switching themes could be implemented into this package also, as it would be a nice to have for other users of
django-simple-bulma