252
edits
FireBrick Custom CSS: Difference between revisions
m
→Internal inline CSS - using data URIs
| (36 intermediate revisions by 2 users not shown) | |||
|
== Specifying custom CSS in the XML config file ==
[[File:2700-small.png|link=:Category:FireBrick]]▼
You can use custom CSS to override that used by the FireBrick’s own admin webpages to customise or enhance the UI to suit your particular needs or create your own look. A user's CSS override file is specified by a URI in the XML config in an attribute on the <code><http></code> element:
<syntaxhighlight lang=xml>
[[File:Firebrick-css.png|frame|Custom colour header by using css]]▼
</syntaxhighlight>
▲<div style="float:right; margin: -1em 0 1.5em 1.5em">[[File:2700-small.png|link=:Category:FireBrick]]</div>
▲ <http css-url="http://example.com/css/myfb.css">
Successfully implementing your own CSS customisations will involve studying the existing base CSS and XHTML files in your Firebrick. Be aware that because of CSS rules concerning specificity (see below) your own settings may sometimes not take precedence over the values given in the base CSS. To address this you will have to write rules that fit in with the existing structure of both the various CSS and XHTML files and add or successfully override property assignments. The latter is achieved by taking a close look at particular CSS selectors that are used in the base .css files. Detailed tips are given in later sections.
== Example - changing colours ==
For example, to change the header and footer bar from red to blue, create your myfb.css file as:
div.header {
background: -moz-linear-gradient( top, #000080 0px, #202080 100% );
▲ background-color: #000080;
-ms-filter:
}
div.footer {
background: -moz-linear-gradient( top, #000080 0px, #202080 100% );
▲ background-color: #000080;
background: -webkit-gradient( linear, left top, left
-ms-filter:
}
</syntaxhighlight>
▲[[File:Firebrick-css.png|frame|Custom colour header by using css]]
Image of the resulting header, showing colour change:
<hr style="clear:both;color:inherit;background-color:inherit;margin:0 0 -2em" />
== Example - changing font size ==
The following example fragment of CSS greatly reduces the font sizes in use in the Firebrick's web pages
<syntaxhighlight lang=css>
@media screen
{
div.main, div.sidemenu div.menu a, div.topmenu, textarea
{
font-size: x-small
}
div.footer
{
padding: 2px 10px 1px
}
div.footer *
{
vertical-align: top
}
}
</syntaxhighlight>
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 [https://www.w3.org/TR/CSS22/selector.html CSS selectors].
'''Note:''' The above brief example is known to currently produce certain '''defects''' in the webpages’ layout: A known minor issue is that the vertical layout of the objects within the footer is slightly off.
At the time of writing, the shipping CSS in the Firebrick FB2500 was v1.45.001 Ximenes, and the standard <code>font-size:</code> value in use was keyword <code>small</code>. This could possibly change in future.
To ''increase'' the text size, this example would require a rewrite and lots of testing trial and error. Unfortunately changing text sizes can have a lot of nasty knock-on effects on layout, which cascade out of control in ways that are hard to predict. Hacks such as the above are likely to fall apart if the base CSS changes or if other aspects of the design cause the layout to change. This is in part because this is an override on parts of the base CSS, effectively a patch, and the user CSS has intimate dependencies on the precise base CSS content. Also there are dependencies between the (X)HTML and the CSS, so changes to the pages’ content or structure can possibly cause problems.
=== CSS debugging tips ===
There are many powerful tools available for debugging CSS. When developing an ''override'' such as this, problems with the CSS [https://www.w3.org/TR/CSS22/cascade.html#specificity specificity rules] may mean that your property overrides do not take effect, as they do not ‘win’ over the specificity of the corresponding rules in the base CSS. Try copying a relevant base CSS selectors exactly, even if parts of the selector seem unnecessary. While this example was being put together, liberal use was initially made of the CSS <code>!important</code> qualifier and removed later on. Also, as a probe to see if changes were taking effect, text was temporarily set to an odd <span lang="en-US"><code>color</code></span>, or borders were enabled with distinctive odd properties. This latter basic technique can be a used if advanced tools are not available.
=== Using CSS @media ===
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.
=== Using CSS @import ===
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 e.g. <code>@import 'my_fb_print.css' print;</code>. This qualified import form is concise compared with using a <code>{ }</code> statement 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 additional http requests, some of which can not be parallelised, so this delay increases page rendering time, unless of course the CSS is already cached.
=== Pulling in multiple .css files ===
Using the CSS <code>@import</code> directive allows multiple .css files to be pulled in general, with or without media-type qualifiers. This 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 ==
There is a danger of making the Firebrick’s web UI completely unusable with mistakes in your custom CSS. To avoid this possibility, if you are using the
* 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 <code>curl</code> in Unix-like environments - to upload the good saved config file to the Firebrick. See the Firebrick manual for details on [http://www.firebrick.co.uk/fb6000/xml.php config uploading by http].
* Many web browsers have options that allow a
* Alternatively, depending on your chosen configuration options, you may be able to log in to the
== Performance degradation with external websites ==
If your custom CSS is located on an external web server, try to ensure that the web server of your choice is well-configured and has excellent availability in order to avoid the possibility of introducing unpleasant delays in the responsiveness of the Firebrick's web UI. (Perhaps consider testing what effect unavailability has on the behaviour of your Firebrick's UI - your Firebrick firmware release could exhibit a delay in response before a timeout if the link to the web server is broken, and as regards visual appearance if the custom CSS can not be fetched, then it could use previously cached CSS or defaults.)
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 <code>https.conf</code> or <code>.htaccess</code> 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
The extent of the potential outcomes that an attacker could achieve by succeeding in pulling in an evil .css file is an open question. Some versions of Microsoft Internet Explorer for Windows could cause code to be executed when ''triggered from within a mere .css file'' by the use of the powerful non standard <span lang="en-US"><code>behavior:</code></span> and <code>expression()</code> CSS features. See MSDN articles on <span lang="en-US">[https://msdn.microsoft.com/en-us/library/ms530723(v=vs.85).aspx CSS 'behavior:']</span> and [https://blogs.msdn.microsoft.com/ie/2008/10/16/ending-expressions/ CSS 'expression()'].
== Internal inline CSS - using data URIs ==
To avoid having to use an external website to store your custom CSS, you can employ a <code>data:</code> URI - see [https://tools.ietf.org/html/rfc2397 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.
Make sure that your text editor is set to output Unicode as UTF-8 as UTF-8 encoding is expected by the data URI example below. (Specifically, if you are using Microsoft Windows, do not use Microsoft Windows 1252 ‘ANSI/Latin 1’ or other IBM/Microsoft ‘code pages’ for text representation in editors.) If you do not follow this, all non-ASCII characters will not be represented correctly in your CSS, creating bugs. Examples of non-ASCII characters include: à é ü £ … “ ” ‘ ’ × ÷ ≡ ² ː Ω ∅ and vastly many more.
Example: straight, inline CSS. Exercise caution regarding prohibited characters if adapting. In the following example, any line-breaks which be included for readability must be removed and the whole string must be entered as a single line.
<syntaxhighlight lang=xml><http css-url="data:text/css,@media screen{div.main,div.sidemenu div.menu a,div.topmenu,textarea{font-size:x-small}div.footer{padding:2px 10px 1px}div.footer *{vertical-align:top}}" />
</syntaxhighlight>
Note the presence of the comma after <code>text/css</code>. This is essential in a <code>data</data> URI.
=== Base64-encoded data ===
You may use base64-encoded <code>data</code> 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 '
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.
<syntaxhighlight>
css-url="data:text/css;charset=UTF-8;base64,QG1lZGlhIHNjcmVlbntkaXYubWFpbixkaXYuc2lkZW1l
bnUgZGl2Lm1lbnUgYSxkaXYudG9wbWVudSx0ZXh0YXJlYXtmb250LXNpemU6eC1zbWFsbH1kaXYuZm9vdGVye3
BhZGRpbmc6MnB4IDEwcHggMXB4fWRpdi5mb290ZXIgKnt2ZXJ0aWNhbC1hbGlnbjp0b3B9fQ=="
</syntaxhighlight>
| |||