Package: django-simple-bulma
django-simple-bulmadjango-simple-bulmais a Django application that makesBulmaandBulma-Extensionsavailable 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 usesBulma 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,
pleasecreate an issue, and we will be happy to make a
release to update it.InstallationTo getdjango-simple-bulma, up and running for your Django project, follow these simple steps:Install it from PyPI withpip install django-simple-bulma(or add it to
yourPipfile)In your Django projectssettings.pyfile:Adddjango_simple_bulmato yourINSTALLED_APPSINSTALLED_APPS=[# ...'django_simple_bulma',# ...]Adddjango_simple_bulma.finders.SimpleBulmaFinderto 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',]Runpython manage.py collectstaticcommand in order to build Bulma and move it to yourstaticfilesfolder. 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 itandstart using it.This app works fine withWhitenoise, which is a great way to serve static
files without needing to mess with your webserver.django-simple-bulmashould 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!CustomizationBulma 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 theBulma variablesand to choose
whichBulma extensionsyou want to load into your project.In order to do this, we'll simply create a dictionary inside yoursettings.pycalledBULMA_SETTINGS, and configure
it there. Here's an example of what that looks like:# Custom settings for django-simple-bulmaBULMA_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 theBulma variablespage, 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 themesIf 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_variablesordark_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 %}. When calling thebulmatemplate
more than once in the same document (for example for implementing a dark theme switch), you will want to passinclude_js=Falseto
at least one of these to prevent duplicate loading of JavaScript resources.ExtensionsIf theextensionskey 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-badgebulma-calendarbulma-carouselbulma-collapsiblebulma-checkradiobulma-dividerbulma-megamenubulma-pageloaderbulma-pricingtablebulma-quickviewbulma-ribbonbulma-sliderbulma-stepsbulma-switchbulma-tagsinputbulma-timelinebulma-tooltipbulma-coolcheckboxes (Cool-Checkboxes-for-Bulma.io)If an extension you want to use is missing, feel free
tocreate an issueand we will be happy to add it.
Alternatively, add it yourself and create a pull request (
seethis prfor some context on how to go about doing
that).CSS styleTheoutput_styleparameter 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.FontAwesomeThe optionalfontawesome_tokenparameter 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:<scriptsrc="https://kit.fontawesome.com/e761a01be3.js"crossorigin="anonymous"></script>Then yourfontawesome_tokenshould bee761a01be3.This is used by the{% font_awesome %}template tag to set up FontAwesome for you. If you don't specify
afontawesome_token,the template tag will still work, but will then use an older version of FontAwesome (v5.14.0)
.Additional scriptsFor 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-fileuploadwill handle displaying the filename in
yourfile upload inputs.bulma-navbar-burgerwill hook up yournavbar-burgers andnavbar-menus automatically, to provide a toggle for
mobile users. We use a slightly updated version
ofthe example from Bulma's documentation-
simply add adata-targetattribute to yournavbar-burgerthat refers to theidof thenavbar-menuthat should
be expanded and collapsed by the button.bulma-notificationswill allow you to closenotificationsby clicking on the X button.bulma-dropdownwill open/close dropdowns using theis-activeclass. It mimics how the dropdowns function on
thedocumentation page.bulma-modalwill handle opening and closing modals. Just assign themodal-buttonclass to a<button>, and make
sure it has adata-targetattribute that matches theidof the modal that you want to open.
Seethe example code from Bulma's documentationfor modal element
code.Compiling custom SCSSIf you're writing custom SCSS for your application,django-simple-bulmaprovides a mechanism for compiling it for you.
This is provided mainly becausedjango-simple-bulmamay cause conflicts and issues with other tools to compile SCSS
for you.To use this feature, please specify thecustom_csskey when defining yourBULMA_SETTINGS. This should be a list of
strings, containingrelative pathsto.scssfiles 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 containsstatic/, 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 yoursettings.pyto 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 aValueExceptionasking you to double-check the filepath.TroubleshootingIf you have the modulesassinstalled, please note that it is incompatible with this project. There is a namespace
conflict betweensassandlibsasswhich will makedjango-simple-bulmacrash when you attempt to do
acollectstatic. To solve this, just uninstallsassand uselibsassinstead.If you run into any other problems with this app,
pleasecreate an issue, and I'll will be happy to help
you with it. You can also find me on Discord aslemon#0001- either at#django-simple-bulma in the lemonsaurus discordor athttps://discord.gg/python.