|
| 1 | +## Example: Blocks |
| 2 | + |
| 3 | +This example shows how to use blocks in HTML templates (views), CSS and JS files. |
| 4 | + |
| 5 | +Features covered by this example: |
| 6 | + |
| 7 | +* `@{BLOCK}` and `@{END}` tags in CSS, JS and HTML files |
| 8 | +* `@{if}`, `@{fi}`, `@{else}` and `@{import}` tags in HTML files |
| 9 | +* `F.map()` method - clone files, enable blocks, merging files |
| 10 | + |
| 11 | +### Overview |
| 12 | + |
| 13 | +Blocks are conditional statements that can be used in views (HTML templates), CSS and JS files. Combined with some API functions, this feature allows you to minimise the number of files that you need to maintain, and the minimise the size of files delivered to the client device for a given scenario, particularly in cases where files for different scenarios contain mostly the same information. |
| 14 | + |
| 15 | +First, let's take a look at how the blocks are defined in the files, then at the end we'll see how to choose the desired blocks in the output to the browser. |
| 16 | + |
| 17 | +### Javascript blocks |
| 18 | + |
| 19 | +If you have a `.js` script that contains some common code, some admin-only code and some user-only code, you could either clone the file and maintain two versions - one for admins, one for users - or you could use blocks like so: |
| 20 | + |
| 21 | +```javascript |
| 22 | +alert( 'ADMINS AND USERS' ); |
| 23 | + |
| 24 | +// @{BLOCK admin} |
| 25 | +alert( 'ADMIN ONLY' ); |
| 26 | +// @{END} |
| 27 | + |
| 28 | +// @{BLOCK users} |
| 29 | +alert( 'USERS ONLY' ); |
| 30 | +// @{END} |
| 31 | +``` |
| 32 | + |
| 33 | +If the file is output without specifying blocks, you'd get: |
| 34 | + |
| 35 | +```javascript |
| 36 | +alert( 'ADMINS AND USERS' ); |
| 37 | +``` |
| 38 | + |
| 39 | +If it's output with the `admin` blocks, you'd get: |
| 40 | + |
| 41 | +```javascript |
| 42 | +alert( 'ADMINS AND USERS' ); |
| 43 | + |
| 44 | +alert( 'ADMIN ONLY' ); |
| 45 | +``` |
| 46 | + |
| 47 | +And if it's output with `users` blocks you'd get: |
| 48 | + |
| 49 | +```javascript |
| 50 | +alert( 'ADMINS AND USERS' ); |
| 51 | + |
| 52 | +alert( 'USERS ONLY' ); |
| 53 | +``` |
| 54 | + |
| 55 | +You can see an example script in `/public/js/script.js`. |
| 56 | + |
| 57 | + |
| 58 | +It's also possible to specify multiple conditions per block, for example: |
| 59 | + |
| 60 | +```javascript |
| 61 | +// @{BLOCK admin, users, visitors} |
| 62 | +alert('ADMINS OR USERS OR VISITORS'); |
| 63 | +// @{END} |
| 64 | +``` |
| 65 | + |
| 66 | +### CSS files |
| 67 | + |
| 68 | +CSS file blocks work in a similar manner, but note you can only use `/* ... */` block comments in a CSS file. |
| 69 | + |
| 70 | +```css |
| 71 | +/* |
| 72 | + * @{BLOCK admin} |
| 73 | + */ |
| 74 | +div { background-color: red; } |
| 75 | +/* |
| 76 | + * @{END} |
| 77 | + */ |
| 78 | +``` |
| 79 | + |
| 80 | +You can see an example in `/public/css/style.css`. |
| 81 | + |
| 82 | +### HTML templates (views) |
| 83 | + |
| 84 | +```html |
| 85 | +<!-- @{BLOCK users} --> |
| 86 | +<p>USERS ONLY</p> |
| 87 | +<!-- @{END} --> |
| 88 | +``` |
| 89 | + |
| 90 | +### Notes |
| 91 | + |
| 92 | +Regardless of file format, the `@{BLOCK}` and `@{END}` tags must be on separate lines. |
| 93 | + |
| 94 | +### Block selection |
| 95 | + |
| 96 | +To generate alternate versions of a file with one or more blocks enabled, simply use the framework `.map()` method as shown below: |
| 97 | + |
| 98 | +```javascript |
| 99 | +// JS |
| 100 | +F.map('/js/admin.js', '/js/script.js#admin'); // --> `admin` block enabled |
| 101 | + |
| 102 | +// CSS |
| 103 | +F.map('/css/admin.css', '/css/style.css#admin,moderator'); // --> `admin` and `moderator` blocks enabled |
| 104 | +``` |
| 105 | + |
| 106 | +You can see an example in `/definitions/blocks.js`. |
| 107 | + |
| 108 | +In the example above, `script.js` will be cloned to a new file `admin.js` which has the `admin` block enabled. Likewise, the `style.css` file will be cloned to a new file `admin.css` that has the `admin` and `moderator` blocks enabled. |
| 109 | + |
| 110 | +You can apply the same approach to HTML files, although it can make your templates somewhat opaque. |
| 111 | + |
| 112 | +An alternate approach might be: |
| 113 | + |
| 114 | +```html |
| 115 | +@{if url === '/admin/'} |
| 116 | + @{import('admin.css', 'admin.js')} |
| 117 | +@{else} |
| 118 | + @{import('style.css', 'script.js')} |
| 119 | +@{fi} |
| 120 | +``` |
| 121 | + |
| 122 | +You can see an example in `views/index.html`. |
| 123 | + |
| 124 | +In the example above, if the route that caused the template to be rendered was `/admin/`, it will use the `admin.css` and `admin.js` files, otherwise it will the `style.css` and `script.js` files. |
0 commit comments