forked from jos3000/swift
-
Notifications
You must be signed in to change notification settings - Fork 1
/
README
52 lines (23 loc) · 4.9 KB
/
README
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
Swift
Inline scripts served as external
When using a using an HTML templating engine it is often convenient to include JavaScript code next to the HTML nodes that it works on. For performance this may not be the optimal choice for a number of reasons. Although an inline script is only used in one template it may appear on multiple URLs and a web client may have to download it multiple times as they visit different pages. Swift can remove the script and serve it as a separate file so that it is only downloaded once per client.
To serve an inline script as external give it an 'id' attribute and register that id as inline in the config. The id must be unique in your templates.
External scripts served inline
In other situations where a developer writes a script that only appears on one URL but would prefer to write the script in a separate file (e.g. for version control reasons). This would normally require an extra HTTP connection for the client when the page is loaded but Swift can be configured to read the contents of the JavaScript file and insert it inline.
To load an external linked script inline set the 'src' attribute to a value in the form 'swift://modulename#inline'.
Script deferment
When JavaScript is running it blocks anything else happening in the browser, so it makes sense to execute scripts as late as possible. Internet Explorer supports the 'defer' attribute for script tags which stops the script from executing after the page has loaded. Unfortunately 'defer' isn't supported in other browsers, so Swift emulates the behaviour by moving deferred script tags to the bottom of the page.
To defer a script add a 'defer' attribute.
Dependency management
It can be hard to manage dependencies for scripts which rely on JavaScript with modular libraries and custom extensions. It can sometimes be tempting just to include the kitchen sink on every page load, especially given the desire to reduce the number of HTTP connections to a minimum. Although it is easier to put everything needed by the site in the header of the default template, but this can lead to an very large initial load on the first page of the site, and unnecessarily large memory and parsing overhead for scripts that a browser may not ever use. Swift allows you to configure dependencies for each of the scripts you use so that they are automatically added to the page when needed and only when needed. Some JavaScript libraries can manage these dependencies but it can be inflexible and non-library modules can be difficult to include in the same scheme as native ones. Swift can automate dependencies to optimise with the whole site in mind rather than just one page.
Swift uses a config array which contains the names and dependencies for all of the scripts in a site. When Swift encounters references to any of the scripts it automatically adds the dependencies. To add dependencies to an inline script add a 'requires' attribute with a comma separated list of the modules you need to load.
CSS promotion
If CSS code is specific to a given template it can be useful to include the code inline, alongside the code that uses it. CSS works best when it included in the HEAD of an HTML file because the browser user will render the page correctly as soon as possible. If CSS is used in several URLs then it can be moved to linked files that can be cached and shared between page loads.
To move inline CSS to an external file give it an 'id' attribute and register that id as inline in the config. The id must be unique in your templates. All CSS is automatically moved to the top HEAD of the document.
Please note that since the HTML specification doesn't allow style or link tags in the body of a page this is the one swift function that causes you to have non-valid HTML in your templates.
Minify
Swift leverages Minify to combine and compress JavaScript and css files to reduce the number of HTTP connections a page makes and make each download as small as possible. In order to decide which files to combine and which ones to leave separate if uses a tweakable configuration - it combines by default, but if many URLs use the same base library with small page specific additional files it can mean the the library code is downloaded by the client multiple times. Swift can specify that certain script always be loaded together and that other groups of scripts only ever loaded individually. In order to group modules give them all the same 'group' property in their config.
Swift automatically combines consecutive external script and style tags into a single call to the Minify script according to the config.
Debug mode
Swift allows you to switch off the Minification and combining of script files so that JavaScript and CSS line numbers correspond to those in their source files. You can also choose to switch from the standard versions of included files to the debug versions where available.
modules are loaded by setting the src or href attribute to 'swift://modulename'