There are a few simple customizations that don't require re-rendering HTCondor View's HTML. Because you aren't modifying the underlying HTML templates, these modifications are not permanent.
To switch out the logo which appears in the top left corner of each page (on the navbar), simply replace
view/static/navbar_logo.svg with your own SVG logo.
To fully customize HTCondor View, you'll need to:
Although the Javascript that renders the graphs is difficult to customize, the surrounding HTML and CSS is easy to replace with your own, custom work. Any changes you make will be permanent and will not be overwritten by future updates to the defaults.
The HTML for HTCondor View is generated by rendering HTML templates using
Jinja2.
Which templates are rendered into actual pages is determined by the file
html/sitemap.json,
which specifies a hierarchical structure for the resulting website.
The default HTML templates and static files are stored in
html/default/, and your custom files are stored in
html/custom/, which you should create if it doesn't exist.
The descriptions of Jinja2 and Bootstrap given here are necessarily brief - both are huge subjects, and their own websites and tutorials do a much better job of explaining them than we can do here. Instead this page focuses on how we use Jinja2 and Bootstrap in HTCondor View.
The sitemap, store in
html/sitemap.json, determines the structure of the HTCondor View website.
Each key should be the name of a link, or the name of a group of links.
The value for each link should be the name (not the path) of the HTML template for that page.
Keys with a
# prefix are "hidden": they are rendered, but not placed in the navigation bar (navbar) at the top of the site.
You can still link to these pages manually.
# html/sitemap.json
{
"Overview": "index.html",
"Submitters": {
"Job Status": "job_status.html",
"Cluster Usage": "cluster_usage.html"
},
"Slots": {
"Multicore Utilization": "multicore_utilization.html"
},
"Operations": {
"CPU and Memory": "cpu_and_memory.html",
"Memory Efficiency": "memory_efficiency.html"
},
"Help": {
"Query Syntax": "syntax.html",
"Glossary": "glossary.html",
"Customization": "customization.html"
},
"#fullscreen": "fullscreen.html",
"#edit": "edit.html"
}Jinja2 is an HTML templating language. It allows you to render a finished HTML file from HTML template files written using a combination of raw HTML and special commands that insert variables or evaluate expressions.
The main thing you need to know about Jinja2 is template inheritance. A template can inherit "blocks" of HTML from another template, similar to how class inheritance works in many object-oriented programming languages. Blocks from the inherited template can be individually overridden or extended by the inheriting template.
Bootstrap is a collection of pre-made CSS and minimal Javascript tools that can help you quickly build websites. The main features that HTCondor View uses from Bootstrap are a few CSS classes and the grid layout system.
Because of the flexibility of HTML/CSS, you don't need to use Bootstrap when writing your own HTCondor View pages - but you'll probably want to, because it makes a lot of very hard things easy.
The table below describes the blocks in the base HTML template (html/base.html).
Any custom templates you write should inherit from this template and override (or inherit) these blocks.
| Block | Description |
|---|---|
| title | This block contains the page title (i.e., the text that goes in the tab name in the browser). |
| favicon |
This contains the <link> tag for the site's favicon.
|
| stylesheets |
This contains the
<link> tags for HTCondor View's default CSS, as well as Bootstrap.
You should probably use the
{{ super() }}
expression if you override this block so that you preserve the existing CSS
(unless you really do want to replace - if so, more power to you!).
|
| js |
This block contains the default Javascript
<script> tags for HTCondor View.
You should probably use the
{{ super() }}
expression if you override this block so that you preserve the existing Javascript
(unless you really do want to replace - if so, more power to you!).
|
| style |
This is an initially-empty block to put any additional page-specific
<script> in.
The <script> tag itself is not included.
Note that if you have a lot of CSS to add, you should probably make a custom CSS file in
html/custom/static and link to it from the stylesheets tag.
|
| head |
This is an initially-empty block to put any additional HTML into the
<head> tag of the HTML.
|
| navbar | This block contains the default navigation bar, built using Bootstrap. |
| navbar_logo |
This block contains the default <img> tag that links to the navbar logo.
Note that this block is inside the
navbar block, so overriding both at once may produce unexpected results.
|
| body |
This initially-empty block is where you should place anything that you want to go into the
<body>
tag of the resulting HTML.
|
The table below describes the context variables that are passed to the template from Python.
They are available for interpolation via {{ variable }}.
Note that Javascript does not obey <base>, so whenever you write an URL inside a
<script> tag you'll need to manually insert {{ base }} as the prefix
for it to resolve correctly.
This is also true for internal links to id's (like the ones that connect the sidebar links on this page to the headers).
| Variable | Description |
|---|---|
| base |
This variable is the string that goes in the href target of the HTML
<base> tag.
This ensures that relative links are correctly routed when HTCondor View is not served from the base URL of a website.
|
| linkmap |
The
linkmap is a nested dictionary that describes the mapping between the directory-like structure of the navbar
and the actual (relative) links to the pages.
|
| current_page | This variable is the string giving the (relative) link to the current page. |