PIXILAB Wiki

Differences

This shows you the differences between two versions of the page.

Link to this comparison view

Both sides previous revisionPrevious revision
Next revision		Previous revision
blocks:custom_styling [2021-03-05 12:29] – Added github link back in adminblocks:custom_styling [2026-01-19 09:47] (current) – Added note on non-latin fonts admin
Line 1: Line 1:
 ====== Custom Styling with CSS ====== ====== Custom Styling with CSS ======
-As everything in Blocks is based on standard HTML5 web technologies, you can use common techniques such as CSS and web fonts to change the look of buttons, panels and blocks in general. There’s a multitude of tutorials and documentation available on the web describing how CSS works, so here we will only look at how to incorporate such styling into Blocks, and give a few examples of what the results can look like.  There's also some examples of ready-made styles and associated test blocks found om our [[https://github.com/pixilab/blocks-css|github repository]]..+As everything in Blocks is based on standard HTML5 web technologies, you can use common techniques such as CSS and web fonts to change the look of buttons, panels and blocks in general. 
  
-To apply custom styling, first create a CSS file, placing it under the public directory mentioned above under “Server Configuration”. Make a separate directory inside the public directory for this purpose, named styles. Using a plain text editor, create a file inside that directory called “buttons.css”, with the following content:+There’s plenty of tutorials on the web on how CSS works, so here we will only look at how to incorporate such styling into Blocks, giving a few examples of what the result can look like. 
  
-<code> +{{ :blocks:css:cssdemo.png?nolink |}}
-/* A square button */ +
-.Button-ctl.square>div { +
- border-radius: 0; +
-} +
-</code>+
  
-:!: Avoid using a word processor or similar program to create this file, as it must be a plain text file. On MacOS you may want to use the free version of [[https://www.barebones.com/products/bbedit/download.html|BBEdit]], on Windows you can use [[https://notepad-plus-plus.org|Notepad++]].+{{ :blocks:css:cssdemo.zip |Here's a block}} demonstrating how to accomplisg the styling shown above. Download the ZIP and import it straight into Blocks using the "Import ZIP file" on the Block menu (do not unpack the ZIP before importing it).
  
-Save the file. Once this is done, you should have the following directory/file structure inside your Block server’s root directory:+Find some mode examples of ready-made styles, fonts and associated test blocks found om our [[https://github.com/pixilab/blocks-css|github repository]].
  
-<code> +To apply custom styling, first create a CSS file, placing it under the //public// directory mentioned above under “Server Configuration”. CSS may be referenced and loaded in three different ways:
-/public/styles/buttons.css +
-</code>+
  
-Activate this style using the “Custom CSS URL” field found at the top level of all blocks. Here, you must specify the path to the file with a leading forward slash, as you see in the illustration below.+  * Block-specific CSS. For use with a single block only. Can be embedded within the block itself, allowing it to be exported and imported with the block. 
 +  * General CSS, that can be used from multiple block when desired. 
 +  * Global CSS, automatically loaded onto all Spots in a system using the //defaultSpotCSS// setting in the [[blocks:server_configuration_file|server configuration file]].
  
-{{ :blocks:custom_styling_1.png?nolink |}}+General and global CSS can be placed anywhere under the //public// directory. Avoid using a word processor or similar program to create this file, as it must be a plain text file. On MacOS you may want to use the free version of [[https://www.barebones.com/products/bbedit/download.html|BBEdit]], on Windows you can use [[https://notepad-plus-plus.org|Notepad++]] but even better use a code editor such as [[blocks:drivers:tools#install_visual_studio_code|Microsoft's Visual Studio Code]].
  
-Add some buttons to the Composition, as shown above. The “invisible” button is placed on top of the logotype, so it precisely covers the logotype. Initially, they will all look like the “Plain” button. With the CSS  le in place, and activated using the “Custom CSS URL”, you can now change the shape of the “Square” button by selecting it then typing square into the “Custom CSS Classes” field, as shown below.+Block-specific CSS is placed inside a block's directory and referenced using a block-relative path beginning with a tilde character. The following //Custom CSS URL// will load a CSS file named styles.css in the block's directory:
  
-{{ :blocks:square_button.png?nolink |}}+<code> 
 +~/styles.css 
 +</code>
  
-The shape of the button will now be square, rather than rounded. The class name “square” in the “Custom CSS Classes” field activates the //CSS rule// inside the “buttons.css” file: +:!: **HINT**: Press the pen icon in the //Custom CSS URL// field at the top level of the block, or choose "Edit Block CSS" on the Edit menu while inside a block to create or edit such block-local CSS. 
 + 
 +===== Button Styling ===== 
 + 
 +To try this out, create a Composition Block then click the pen in the //Custom CSS URL// field and enter the following:
  
 <code> <code>
-.Button-ctl.square>div+/* A square button */ 
 +.Button-ctl.square>div { 
 + border-radius: 0; 
 +}
 </code> </code>
  
-Basically, this rule selector says; look for a button control (the “.Button-ctl” part) that also has the square class applied to it (the “.square” part). When found, change the shape of its immediate child element (the “div”) according to what’s stated inside the curly braces. You can read more about CSS selectors and CSS in general [[https://developer.mozilla.org/en-US/docs/Learn/CSS/Introduction_to_CSS/Selectors|here]].+Click OK to close the CSS editor. This updates the //Custom CSS URL// field with the block-local CSS just created. Add a button, then type //square// into its "Custom CSS Classes" field. It should now appear with square rather than the standard, rounded corners. 
 + 
 +{{ :blocks:square_button.png?nolink |}} 
 + 
 +The CSS rule shown above has a CSS selector (the first line after the comment delimited by /* and */) that says; look for a button control (the //.Button-ctl// part) that also has the //square// class applied to it (the “.square” part). When found, change the shape of its immediate child element (the “div” directly inside the //Button-ctl// element) according to what’s stated inside the curly braces. You can read more about CSS selectors and CSS in general [[https://developer.mozilla.org/en-US/docs/Learn/CSS/Introduction_to_CSS/Selectors|here]].
  
 ==== Invisible Button ==== ==== Invisible Button ====
Line 53: Line 61:
 </code> </code>
  
-Again, you can see how this selects the same “.Button-ctl” in order to only target buttons, but then states an “invisible” class name instead of “square” as in the previous example. Add the two rules above to your “buttons.css” file, save the file, and then activate this look by typing //invisible// into the “Custom CSS Classes” field with the desired button selected (the one on top of the logo). You need to refresh your browser in order to see the effect, since you changed the “buttons.css” file. The second rule above applies only while the invisible button is pressed, showing a white outline as feedback.+Again, you can see how this selects the same “.Button-ctl” in order to only target buttons, but then states an “invisible” class name instead of “square” as in the previous example. Add the two rules above to your CSS file, click OK, and then activate this look by typing //invisible// into the “Custom CSS Classes” field with the desired button selected (put atop the logo in the illustration shown above). The second rule above (the one that also specifies the //pressed// class) applies only while the invisible button is pressed, rendering a white outline as user feedback.
  
-==== Complex Styling====+==== Button States ==== 
 +You may want to style a button differently when pressed or while "on" (i.e., when the bound property is in its active state). This can be done using the //pressed// or //active// classes also applied to the button while in those states. You can see an example of how this is done for the invisible button above, where a solid white outline is shown while pressed to give some feedback. The //active// class can be used in a similar way to style a button in a specific way while "on". 
 + 
 +===== Complex Styling =====
  
 CSS rules can become quite complex, but they also provide a great deal of flexibility for styling things. The last example shown below is for the “glossy” button. Copy and paste the following into your “buttons.css” file: CSS rules can become quite complex, but they also provide a great deal of flexibility for styling things. The last example shown below is for the “glossy” button. Copy and paste the following into your “buttons.css” file:
Line 104: Line 115:
 </code> </code>
  
-Save the CSS file, reload your Blocks editor browser window, and activate this style by typing //glossy// into the “Custom CSS Classes” field. Open a second window to act as a Spot for interacting with this block (see “Adding a Display” and “Displaying a Block” in the Getting Started chapter for details). The result should look something like this:+Close the CSS editor and activate this style by typing //glossy// into the “Custom CSS Classes” field. Open a second window to act as a Spot for interacting with this block (see “Adding a Display” and “Displaying a Block” in the Getting Started chapter for details). The result should look something like this:
  
 {{ :blocks:cust_styling_result.png?nolink |}} {{ :blocks:cust_styling_result.png?nolink |}}
Line 110: Line 121:
 It is possible to apply multiple classes to a single control or other block. Just type all the desired class names into the “Custom CSS Classes” field, separated by a space. It is possible to apply multiple classes to a single control or other block. Just type all the desired class names into the “Custom CSS Classes” field, separated by a space.
  
-==== Finding the Selectors ====+===== Finding the Selectors =====
  
 CSS basically consists of two parts: CSS basically consists of two parts:
Line 130: Line 141:
  
 See [[https://github.com/pixilab/blocks-css|here]] for some more Blocks CSS code examples. See [[https://github.com/pixilab/blocks-css|here]] for some more Blocks CSS code examples.
 +
  
 ===== Styling Text ===== ===== Styling Text =====
Line 141: Line 153:
   * Change the style of //all// text blocks merely by overriding the .text-block class in your custom CSS. No extra CSS classes needed. This is useful when you want to override the basic look of text everywhere.   * Change the style of //all// text blocks merely by overriding the .text-block class in your custom CSS. No extra CSS classes needed. This is useful when you want to override the basic look of text everywhere.
   * Change the style of all text blocks inside another block, such as a Composition, by applying a class to the Composition rather than to each individual text block. See the .example-style-text [[https://github.com/pixilab/blocks-css/blob/master/style/example-style-text.css|here]].   * Change the style of all text blocks inside another block, such as a Composition, by applying a class to the Composition rather than to each individual text block. See the .example-style-text [[https://github.com/pixilab/blocks-css/blob/master/style/example-style-text.css|here]].
-  * Change the style of specific text items by applying a CSS class there. See the .text-block.font-georgia style [[https://github.com/pixilab/blocks-css/blob/master/style/example-style-text.css|here]].+  * Change the style of specific text items by applying a CSS class there. See the .text-block.font-georgia style [[https://github.com/pixilab/blocks-css/blob/655bfad7779560c1a6b07426c6a8a4b4ca3e3572/style/example-style-text.css#L44|here]]. 
 +  * To apply custom typefaces, first obtain the appropriate font file(s) and then load those in your CSS using a [[https://github.com/pixilab/blocks-css/blob/655bfad7779560c1a6b07426c6a8a4b4ca3e3572/style/example-style-text.css#L66|@font-face rule]].
   * Change the style of specific headings (H1, H2, etc) or style variations (bold or italics).   * Change the style of specific headings (H1, H2, etc) or style variations (bold or italics).
   * Loading custom fonts when called for, such as the Chicle font show in the example above.   * Loading custom fonts when called for, such as the Chicle font show in the example above.
  
-:!: Fonts are available in a variety of formats. The 'woff' format is recommended for use with Blocks.+:!: Fonts are available in a variety of formats. The 'woff' or 'woff2' formats are recommended for use with Blocks.
  
-You can only apply a single style file to a block. This is specified at the root level of the block. To use styles from multiple sources, combine them all into a single CSS file.+You can only apply a single style file to a block. This is specified at the root level of the block. To use styles from multiple sources, combine them all into a single CSS file. You can also apply a CSS file globally, making it available to all blocks without any additional effort. This is done using the //defaultSpotCSS// setting in the [[blocks:server_configuration_file|server configuration file]]. 
 + 
 +==== Using non-Latin Fonts ==== 
 +If your target audience speaks a language using non-latin characters, such as japanes or korean, you need to provide the relevant fonts containing those character sets. [[blocks:custom_styling:non-latin-fonts|This application note]] describes how that can be done in a way that makes such fonts usable everywhere in Blocks. 
 +===== Globally Applied Classes ===== 
 + 
 +A few CSS classes are applied by Blocks itself under certain conditions: 
 + 
 +  * **show-cursor** is applied while an interactive element, such as a button or a slider, is shown on screen. It is is used by Blocks to show any cursor on a regular desktop browser, allowing a mouse to be used to click those elements. 
 +  * Any class specified by a //class// [[blocks:api:query-parameters#spot_parameters|query parameter]]. 
 +  * **tag-XXX** will be applied based on all active tags. Tags can be set in a variety of ways – see the Blocks manual for details. 
 + 
 +:!: **NOTE**: On PIXILAB Player, the mouse cursor may be hidden permanently, in which case the //show-cursor// class has no effect. This is determined when the player is made, and should be set depending on whether you intend to use the player with a touch screen or a mouse. 
 + 
 + 
 +These classes are all applied to an outer element, so you would use those as part of a selector that looks like like this: 
 + 
 +<code> 
 +.tag-mytag .text-block { 
 +    color: blue; 
 +}  
 +</code>
  
 +Note the space between //.tag-mytag// and //.text-block//. This says "apply the following to any element with the class //text-block// found //anywhere// within an outer element with the class //tag-mytag//". The example above will make all text blue for as long as the "mytag" tag is set.
  
  
 ===== Other Custom Content ===== ===== Other Custom Content =====
  
-Just as you placed a custom CSS file under the public folder, you may place other web files, including fonts and complete HTML files. Use a Web block to display a complete HTML file placed under the public folder by specifying a URL for the Web block like this:+Just as you can place a custom CSS file under the server's /public folder, you may place other files to be publicly accessible there, including fonts and complete HTML files. Use a Web block to display a complete HTML file placed under the public folder by specifying a URL for the Web block like this:
  
 <code> <code>