FireBrick Custom CSS: Difference between revisions

From AAISP Support Site
m (→‎Example - changing font size: explanation of @media use)
m (→‎Example - changing font size: I'm going mad - it's @import - ten years since I looked at this stuff)
Line 58: Line 58:
Note that there is no space after the dot in <code>div.main</code> etc. This is essential; adding white space at this point would alter the meaning - see CSS selectors.
Note that there is no space after the dot in <code>div.main</code> etc. This is essential; adding white space at this point would alter the meaning - see CSS selectors.


The <code>@media screen</code> qualifier over the given block is used in this case to restrict any preference change to only apply to the display of the Firebrick’s web pages on a screen and here the customisations do not apply when a page is printed. On the other hand, the <code>@media print</code> qualifier is often used to customise presentation when pages are printed, such as: getting rid of all colour, using serif fonts, changing the appearance of external links to show the actual URI, or simplifying content and hiding all unwanted or irrelevant material such as navigation lists, footers, branding. Completely separate 'print'- and 'screen' stylesheets can be maintained in separate .css files and these files can be conditionally included by reference in a master .css file using the CSS <code>@include</code> directive at the top of the file with a media-type qualifier within the directive. This qualified-include form is concise compared with using the block qualifier and in theory might minimise the size of an initial CSS download, depending on the browser. A general disadvantage of <code>@include</code> is the latency introduced by having additional http requests, some of which can not be parallelised, so this delays rendering time, unless of course the CSS is already cached.
The <code>@media screen</code> qualifier over the given block is used in this case to restrict any preference change to only apply to the display of the Firebrick’s web pages on a screen and here the customisations do not apply when a page is printed. On the other hand, the <code>@media print</code> qualifier is often used to customise presentation when pages are printed, such as: getting rid of all colour, using serif fonts, changing the appearance of external links to show the actual URI, or simplifying content and hiding all unwanted or irrelevant material such as navigation lists, footers, branding.


Completely separate 'print'- and 'screen' stylesheets can be maintained in separate .css files and these files can be conditionally included by reference in a master .css file using the CSS <code>@import</code> directive at the top of the file with a media-type qualifier within the directive eg <code>@import 'my_fb_print.css' print;</code>. This qualified import form is concise compared with using the block qualifier and in theory might minimise the size of an initial CSS download, depending on the browser. A general disadvantage of <code>@import</code> is the latency introduced by having additional http requests, some of which can not be parallelised, so this delays rendering time, unless of course the CSS is already cached.
In fact, using the CSS <code>@include</code> directive allows multiple .css files to be pulled in, which gets around the restriction of only being allowed to fetch a single .css file if only more than one URI value is not permitted in the single <code>css-url</code> attribute.

In fact, using the CSS <code>@import</code> directive allows multiple .css files to be pulled in, which gets around the restriction of only being allowed to fetch a single .css file if only more than one URI value is not permitted in the single <code>css-url</code> attribute.


== Testing - warning ==
== Testing - warning ==

Revision as of 07:43, 6 August 2017

2700-small.png

You can use custom css to override the css used on the FireBrick admin pages to create your own look.

Custom colour header by using css

The css file is set in the config in the <http section:

<http css-url="http://example.com/css/myfb.css">

For example, to change the header and footer bar from red to blue, create your myfb.css file as:

/* 
   Custom css to make my FireBrick visibly different to normal ones
*/

div.header {
        background: inherit;

        background-color: #000080;
        background: -moz-linear-gradient(top, #000080 0px, #202080 100%);
        background: -webkit-gradient(linear, top, bottom, color-stop(0%,#000080), color-stop(100%,#202080));
        background: -webkit-linear-gradient(top, #000080 0%,#202080 100%);
        background: -o-linear-gradient(top, #000080 0%,#202080 100%);
        background: -ms-linear-gradient(top, #000080 0%,#202080 100%);
        background: linear-gradient(top, #000080 0%,#202080 100%);
        -ms-filter: "progid:DXImageTransform.Microsoft.gradient(startColorstr='#000080', endColorstr='#202080')";
}

div.footer {
        background: inherit;

        background-color: #000080;
        background: -moz-linear-gradient(top, #000080 0px, #202080 100%);
        background: -webkit-gradient(linear, left top, left bottom, color-stop(0%,#000080), color-stop(100%,#202080));
        background: -webkit-linear-gradient(top, #000080 0%,#202080 100%);
        background: -o-linear-gradient(top, #000080 0%,#202080 100%);
        background: -ms-linear-gradient(top, #000080 0%,#202080 100%);
        background: linear-gradient(top, #000080 0%,#202080 100%);
        -ms-filter: "progid:DXImageTransform.Microsoft.gradient(startColorstr='#000080', endColorstr='#202080')";
}

Example - changing font size

The following example CSS greatly reduces the font sizes in use in the Firebrick's web pages:

@media screen
    {
    div.main,  div.sidemenu div.menu a
        {
        font-size:x-small
        }
    }

Note that there is no space after the dot in div.main etc. This is essential; adding white space at this point would alter the meaning - see CSS selectors.

The @media screen qualifier over the given block is used in this case to restrict any preference change to only apply to the display of the Firebrick’s web pages on a screen and here the customisations do not apply when a page is printed. On the other hand, the @media print qualifier is often used to customise presentation when pages are printed, such as: getting rid of all colour, using serif fonts, changing the appearance of external links to show the actual URI, or simplifying content and hiding all unwanted or irrelevant material such as navigation lists, footers, branding.

Completely separate 'print'- and 'screen' stylesheets can be maintained in separate .css files and these files can be conditionally included by reference in a master .css file using the CSS @import directive at the top of the file with a media-type qualifier within the directive eg @import 'my_fb_print.css' print;. This qualified import form is concise compared with using the block qualifier and in theory might minimise the size of an initial CSS download, depending on the browser. A general disadvantage of @import is the latency introduced by having additional http requests, some of which can not be parallelised, so this delays rendering time, unless of course the CSS is already cached.

In fact, using the CSS @import directive allows multiple .css files to be pulled in, which gets around the restriction of only being allowed to fetch a single .css file if only more than one URI value is not permitted in the single css-url attribute.

Testing - warning

There is a danger of making the Firebrick’s web UI completely unusable with mistakes in your custom CSS. To avoid this, if you are using the Firebrick's XML config editor page, use the "Test" button rather than "Save" after making your edit, as this will roll back your change after a time limit if you are stuck.

  • In order to be prepared for recovery from a bad modification, first download a good reference copy of the XML config file in advance, and then use an http upload tool - such as curl in Unix-like environments - to upload the good saved config file to the Firebrick. See the Firebrick manual for details on config uploading by http.
  • Many web browsers have options that allow a webpage's CSS to be overridden, customised or ignored.
  • Alternatively, depending on your chosen configuration options, you may be able to log in to the Firebrick's command line even if you find the web UI unusable.

Performance degradation with external websites

To avoid introducing delays in the responsiveness of the Firebrick's web UI, choose a well-configured web server. If you are the web master of your chosen server, review the cache-friendliness settings. (Topics: 'cacheability', 'cache-control', 'ETags'.) Getting cacheability settings wrong could in theory at least mean that your Firebrick might possibly be compelled to refetch the custom CSS repeatedly. A number of excellent web-based tools are available that will check and diagnose cacheability issues of a website. If you are using the Apache web server, see the https.conf or .htaccess documentation relating to cache control options. Set long timeouts for cacheability of all CSS files and make sure that the Firebrick is not forbidden from caching the downloaded CSS. Using inappropriate short cache lifetimes, even zero, or disabling caching altogether is a fairly common and heinous practice.

Security implications

Pointing your Firebrick to CSS that is stored in a website on the public Internet might, in theory at least, have security implications. Certainly review security of that site in general, who might have access to the site's content, any FTP passwords, 'locking' features on FTP. Also consider attacks on the DNS to redirect requests to a bogus site. Man-in-the-middle attacks and ARP / ND attacks could achieve redirection at a lower level, however this is a much more general problem. Consider using TLS / SSL (i.e. a https: CSS URL) to prevent these possibilities.

Internal inline CSS - using data URIs

To avoid having to use an external website to store your custom CSS, you can employ a data: URI - see RFC 2397. Be aware that there may be a limit on the length of URIs however, and in any event see RFC 2397 section 2.

I recommend that you should not attempt to include newlines in the inline CSS of your data URI, as this may be forbidden by the URI scheme standard. Be aware of the risk of your inline CSS containing characters that are either prohibited in data URIs, illegal in quoted strings or in XML attributes. See both the RFC for the data URI scheme and also the XML standards. Just some examples of illegal characters are ", %, &, >, newlines and there are probably various others, The simple technique of including literal CSS straight, as below, is only usable if the particular fragment of CSS does not contain any problematic characters, otherwise see the next section for a general method.

Example, straight inline CSS (exercise caution if adapting):

<http css-url="data:text/css,@media screen{div.main,div.sidemenu div.menu a{font-size:x-small}}"  />

Note the presence of the comma after text/css. This is essential in a data URI.

Base64-encoded data

You may use base64-encoded data URIs for safety and complete flexibility as shown in the example below. Using base64-encoding removes any risks and problems with illegal characters completely. Note again the presence of the comma, now after the keyword 'base64'. This is essential in a data URI, whether base64 is used or not.

If you are using any non-ASCII characters in your CSS text, unless you have already CSS backslash-hex-encoded them, which avoids the issue, your CSS should be Unicode text and you must first UTF-8-encode your CSS into a byte stream, before then base64-encoding those bytes. You must then also declare that your original CSS text was UTF-8 as in the example below.

In the following example, line-breaks may be included for readability. These must be removed and the whole string must be entered as a single line.

css-url="data:text/css;charset=UTF-8;base64,QG1lZGlhIHNjcmVlbntka
XYubWFpbixkaXYuc2lkZW1lbnUgZGl2Lm1lbnUgYXtmb250LXNpemU6eC1zbWFsbH19"

If you are absolutely certain that your CSS will contain only ASCII characters (i.e. those below code-point 128), then the ;charset=UTF-8 declaration can be omitted.