Material Frontend¶

Introduction¶

Material Frontend is the lightweight alternative to the django admin allows to build big modular websites.

Lightweight module extension of django application config
Ready to use theme build with MaterialzeCSS
Autocollected site navigation menu
Fast and smooth navigation with Turbolinks
CRUD scaffolding build with django class based views
Out of the box datatables integration.

Installation¶

Add material.frontend into INSTALLED_APPS settings

INSTALLED_APPS = (
     'material',
     'material.frontend',
     ...
)

Add frontend urls into global urlconf module at urls.py

from material.frontend import urls as frontend_urls

urlpatterns = [
    ...
    path('', include(frontend_urls)),
]

Quick start¶

If you are creating new django app, you can use ./manage.py startmodule <app_name> command.

The command is pretty similar to the ./manage.py startapp, but it scaffolds all files required for a material.frontend module.

To manually create a new module add ModuleMixin to the AppConfig definition in the apps.py file

from material.frontend.apps import ModuleMixin

class MyAppConfig(ModuleMixin, AppConfig):
    name = 'myapp'
    icon = '<i class="material-icons">flight_takeoff</i>'

The application have to have <app_module>/urls.py file, with a single no-parameterized url with name=’index’, ex

urlpatterns = [
        path('', generic.TemplateView.as_view(template_name="sales/index.html"), name="index"),
]

All AppConfigs urls will be included into material.frontend.urls automatically under /<app_label>/ prefix The AppConfig.label, used for the urls namespace.

The menu.html sample

<ul>
    <li><a href="{% url 'sales:index' %}">Dashboard</a></li>
    <li><a href="{% url 'sales:customers' %}">Customers</a></li>
    {% if perms.sales.can_add_lead %}<li><a href="{% url 'sales:leads' %}">Leads</a></li>{% endif %}
</ul>

Next, you need to add myapp.apps.MyAppConfig to the INSTALLED_APPS setting and run ./manange.py migrate to get module entry created.

Custom Components¶

django-material frontend build with Turbolinks and WebCompoments. All shims required to support WebComponents for old webrowsers aready included in the frontend js bundle. The best way to add a custom javascript to a frontend application is to create a new WebComponent.

There are plenty ways to manage javascript bundles with django. This pages describes how to quick start with webpack tool.

Let’s install required dependencies:

npm init -y
npm install --save-dev webpack webpack-cli
npm install --save-dev @babel/core @babel/preset-env @babel/register babel-loader

Add to package.json settings for javascript compiler

"babel": {
  "presets": [
    [
      "@babel/preset-env",
      {
        "targets": "> 0.25%, not dead"
      }
    ]
  ]
}

And create webpack.config.babel.js

import path from 'path';

const BABEL_LOADER_CONFIG = {
  test: /\.js$/,
  exclude: [path.resolve(__dirname, './node_modules')],
  loader: 'babel-loader',
};

const JAVASCRIPT_CONFIG = {
  entry: {
    'my-components': './components/my-components.js',
 },

  output: {
    filename: 'js/[name].min.js',
    path: path.resolve(__dirname, './static/'),
  },

  devtool: 'source-map',

  module: {
    rules: [
    BABEL_LOADER_CONFIG,
    ],
  },
};

export default [
  JAVASCRIPT_CONFIG,
];

This comfig takes componnents/my-components.js file and compiles it to static/ folder

Let’s create our first component in components/tabs/index.js

export default class MyTabs extends HTMLElement {
  connectedCallback() {
    this._tabs = M.Tabs.init(this.querySelector('.tabs'));
  }

  disconnectedCallback() {
    this._tabs.destroy();
  }
}

A browser would call required web component callback with any update to the DOM, regardless of whether it comes from a full page load, a Turbolinks page change, or an Ajax request.

Include and register at components/my-components.js

import MyTabs from './tabs';

window.addEventListener('load', () => {
  window.customElements.define('my-tabs', MyTabs);
});

To add custom js file to all module templates, create a sales/base_module.html

{% extends 'material/frontend/base_module.html' %}
{% load static %}

{% block extrahead %}
<script src="{% static 'js/my-components.min.js' %}"></script>
{% endblock %}

So now you can run webpack –mode=production to get compiled web component. Now you can wrap html tabs definition in <my-tabs>…</my-tabs> tag to get js code initialized.

You can check the full cookbook sample at https://github.com/viewflow/cookbook/tree/master/frontend

Examples¶

The live demo of the frontend is available at http://demo.viewflow.io/integration

Demo source code available at the Github

License¶

Material Frontend is distributed as part of django-material package under the terms of the BSD3 license