Skip to content

Latest commit

 

History

History
248 lines (187 loc) · 10.2 KB

README.md

File metadata and controls

248 lines (187 loc) · 10.2 KB
Raw

Django Base Theme

Table of Contents

  • Components & Standards
  • CSS Guidelines & Architecture
  • Browser Support
  • Performance
  • SASS/SCSS Integration
  • Using Gulp to automate your front-end workflow
  • Modifying Settings.py
    • Adding Directories
    • Adding Installed Apps
  • PIP installation
  • Updating Base-Theme
  • Adding custom stylesheets/javascript
  • Custom templates and other static files
    • Example directory structure
    • Example of base.html file
    • Example of extending your app's base file
    • Examples of different template layout options
  • Utilizing the Django Block System
    • A list of blocks available with base-theme
  • Adding Django Debug Toolbar
  • Example View & URL Dispatcher
  • List of Contributors

Components & Standards:

CSS Guidelines & Architecture

We use the following guides:

Browser Support

At present, we officially aim to support the following browsers:

  • IE10, IE11, MS Edge
  • The latest version of Chrome, Firefox, Safari & Opera
  • The latest version of Safari & Chrome for iOS
  • The latest version of Chrome for Android
  • Find out if you are using the most up-to-date browser at http://whatbrowser.org or http://browsehappy.com.

This is not to say that Django Base Theme cannot be used in browsers older than those reflected, but that the best experience and our development focus will be on those browsers listed above.

Performance

Base Theme strives for fast page load times. Not including server configuration enhancements, Base Theme's default template scores a grade of "A" in every category via YSlow's web page analyzer. Our median Web Page Test scores for the default template have a Speed Index of ~1450 (we are working on getting it down to ~1000, which is ideal).

SASS/SCSS Integration

This project uses the CSS extension language SASS. SASS adds power and organization to your stylesheets.

SCSS/SASS outputs to CSS via compilers like Compass, LibSass, CodeKit or Gulp. Learn more about SASS/SCSS.

Some helpful SASS Mixins included in this theme are:

  • Flexbox
  • Breakpoints
  • REM to PX fallback & Viewport to REM to PX fallback
  • SVG Background-images with PNG and retina fallBack
  • RGBA Background, Vertical Align, Horizontal Align, etc.
  • You can see a full list of mixins, variables and other SASS helpers here.

Using Gulp to automate your front-end workflow

Included in this repo is an example gulpfile (based on: RevSys' Front-end Guide). If you use Gulp, you will need to manually add it to your root directory and customize it to your project's needs. For more info on how to use Gulp go here: http://gulpjs.com.

Modifying Settings.py

Add the following to your settings.py file:

STATIC_ROOT = os.path.join(BASE_DIR, "static")

STATICFILES_DIRS = (
    os.path.join(BASE_DIR, "static_dev"), 
    #### You can also call this assets or whatever name you want
)

TEMPLATES = [
    {
        'BACKEND': 'django.template.backends.django.DjangoTemplates',
        'DIRS': ['templates'], #### template directory goes here
        'APP_DIRS': True,
        'OPTIONS': {
            'context_processors': [
                'django.template.context_processors.debug',
                'django.template.context_processors.request',
                'django.contrib.auth.context_processors.auth',
                'django.contrib.messages.context_processors.messages',
            ],
        },
    },
]

Add the following to the 'Installed_Apps' section:

'bootstrap3',
'base_theme',
'fontawesome',

PIP installation

pip install git+https://github.com/wharton/Django-Base-Theme
pip install django-bootstrap3
pip install django-fontawesome

Getting the latest Base-Theme Updates

To get the latest updates to the base theme, just run the following command:

pip install git+https://github.com/wharton/Django-Base-Theme --upgrade

Add custom stylesheets or javascript

1.) Create a new folder in your project directory called "assets." You can also call this "static_dev" or whatever name you want.

2.) Create your custom stylesheets and/or javascript files in the assets folder.

3.) Include a link to your custom styles/js. Here is an example.

Custom templates and other static files:

1.) Create a new folder in your project directory called "templates."

2.) Create a directory within "templates" for your app and call it the name of your app. So, if your app is "polls," your folder would be called "polls."

3.) Within that app folder, create a template called "base.html." You must have this file in your app directory.

4.) Example directory structure:

project/
		manage.py
project/
		settings.py
		urls.py
your-app/
		models.py
		views.py
assets/
		 styles.css #### Your custom styles here.
		 scripts.js #### Your custom js here.
templates/
     your-app/ #### same name as your app
           base.html #### Your base extends one of the layout templates.
           	i.e. {% extends "left_sidebar.html" %}
           list.html #### Your other templates can extend from your app's base template
           	i.e. {% extends "your-app/base.html" %}
           detail.html

5.) Note: The layouts (left, right, both, full) extend the original base.html. The original base.html will be in your site-packages directory after you pip install it.

6.) Here is an example of what would go into your app's base.html.

7.) If you wanted to extend your app's base.html into, say, your app's list.html template, you would just need to make sure your extends path is pointing to your app's base template, like this:

{% extends "your-app/base.html" %}

8.) You can find different layouts for your app here.

Utilizing the Django Block System

The official Django docs do a good job of explaining how template inheritance works and how to utilize the block system.

The following is a list of blocks included in the Django Base Theme that you can use to customize your own template as needed. You can also find them listed in the original base.html template here.

- {% block site_title %} 
- {% block extra_head_top %}
- {% block fast_fonts %}
- {% block head_css %}
- {% block font_awesome %}
- {% block extra_head_bottom %}
- {% block header_wrapper %}
- {% block header %}
- {% block banner_wrapper %}
- {% block banner_logo %}
- {% block banner_title %}
- {% block main_nav_wrapper %}
- {% block main_nav %}
- {% block mobile_sidebar_nav %}
- {% block breadcrumb_wrapper %}
- {% block breadcrumb %}
- {% block content_wrapper %}
- {% block content %}
- {% block inner_content %}
- {% block left_sidebar %}
- {% block right_sidebar %}
- {% block footer_wrapper %}
- {% block footer %}
- {% block footer_app_link %}
- {% block footer_js %}
- {% block extra_footer_js %}

Adding the Django Debug Toolbar

The official Django docs do a good job of explaining how to integrate the toolbar.

Initial Test View & Url Configuration

And to your views

from django.views.generic import TemplateView

class BaseView(TemplateView):
    template_name = "your_app/base.html"

URL Dispatcher

from project.views import BaseView
urlpatterns = [
    url(r'^$', BaseView.as_view(), name='home'),
    url(r'^admin/', include(admin.site.urls)),
]

Contributors

Thank you to our contributors!