FireBrick Custom CSS: Difference between revisions

(13 intermediate revisions by 2 users not shown)

Line 54:

div.main, div.sidemenu div.menu a, div.topmenu, textarea

{

font-size: x -small

font-size: x-small

}

div.footer, div.footer *

div.footer

{

~~vertical-align~~: ~~top;~~

padding: 2px 10px 1px

~~padding-top: 2px;~~

}

div.footer *

padding-bottom: 1px

{

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].

⚫

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>.

'''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.

⚫

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, so effectively a patch, and so has intimate dependencies on ~~its~~ precise content. Also there are dependencies between the (X)HTML and the CSS, so changes to the pages’ content or structure can possibly cause problems.

⚫

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.

This simple example has certain defects: The vertical layout of the text within the footer is slightly off. The layout of the ‘Graphs’ page is quite a mess, so further work is needed.

⚫

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.

⚫

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].

=== CSS debugging tips ===

Line 80:

Line 82:

=== 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 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 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.

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 ===

Line 95:

Line 97:

* 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 ==

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.

⚫

If you are the web master of your chosen server, review the web server’s 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 to 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. Make sure that user agents are not forbidden from caching downloaded CSS files, and set long cache validity times for all CSS files. Using inappropriate short cache lifetimes, even zero, or disabling caching altogether is a fairly common and heinous practice. Cache validity times should be set specifically according to each kind of file extension (<code>.css</code>) and MIME type requested (<code>text/css</code>), and should be as long as possible. The maximum validity time value is the maximum delay you feel is acceptable before a Firebrick shows the effects of a change when you change the css file on the web server.

== Security implications ==

Line 108:

Line 112:

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.

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.

It is recommended 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 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.

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, line-breaks ~~may~~ be included for readability~~. These~~ must be removed and the whole string must be entered as a single line.

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>

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

Note the presence of the comma after <code>text/css</code>. This is essential in a <code>data</code> 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 '~~base64~~'. This is essential in a data URI, whether base64 is used or not.

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 '<code>data</code>'. 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.

Line 124:

Line 130:

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,~~QG1lZGlhIHNjcmVlbntkaXYubWFpbixkaXYuc2~~

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

bnUgZGl2Lm1lbnUgYSxkaXYudG9wbWVudSx0ZXh0YXJlYXtmb250LXNpemU6eC1zbWFsbH1kaXYuZm9vdGVye3

lkZW1lbnUgZGl2Lm1lbnUgYSxkaXYudG9wbWVudSx0ZXh0YXJlYXtmb250LXNpemU6eC1zbWFsbH1ka

BhZGRpbmc6MnB4IDEwcHggMXB4fWRpdi5mb290ZXIgKnt2ZXJ0aWNhbC1hbGlnbjp0b3B9fQ=="

XYuZm9vdGVyLGRpdi5mb290ZXIgKnt2ZXJ0aWNhbC1hbGlnbjp0b3A7cGFkZGluZy10b3A6MnB4O3BhZ

GRpbmctYm90dG9tOjFweH19"

</syntaxhighlight>