http://cdn-a.com'.", $format_variables),
- t("@format-extensions is an optional
- setting to limit which file types should be served from a CDN. E.g.:
- '.css .jpg .jpeg .png'.", $format_variables),
- );
- $example_list_items = array(
- t('This would serve all files from a single CDN:
- http://cdn-a.comhttp://cdn-a.com|.css .jpg .jpeg .png\nhttp://cdn-b.com|.zip\nhttp://cdn-c.com." . implode(", .", explode("\n", $farfuture_extensions)) . "",
- '!extensions-compressed' => "." . implode(", .", explode("\n", CDN_BASIC_FARFUTURE_GZIP_EXTENSIONS)) . "",
- );
$form['settings'][CDN_BASIC_FARFUTURE_VARIABLE] = array(
'#type' => 'checkbox',
'#title' => t('Far Future expiration'),
- '#description' => t('Recommended for maximum performance boost!
- Expires,
- Cache-Control,
- Last-Modified, Vary, for
- files with one of the following extensions: !extensions
- and of these extensions, some will also be
- automatically compressed: !extensions-compressed.', $farfuture_variables
- ),
+ '#description' => t('Mark all files served from the CDN to expire in the far future — improves client-side cacheability.') . ' ' . theme('advanced_help_topic', 'cdn', 'admin-details-mode-pull-far-future'),
'#default_value' => variable_get(CDN_BASIC_FARFUTURE_VARIABLE, CDN_BASIC_FARFUTURE_DEFAULT),
'#process' => array('ctools_dependent_process'),
'#dependency' => array('radio:' . CDN_MODE_VARIABLE => array(CDN_MODE_BASIC)),
@@ -229,59 +151,12 @@ function cdn_admin_details_form(&$form_state) {
. ' (' . $ufi['machine_name'] . '): '
. $ufi['description'];
}
- $format_variables['!format-available-unique-identifier-methods'] = theme('item_list', $methods);
- // '@format-available-unique-identifier-methods'
-
-
- $format_explanation_list_items = array(
- t("@format-directory is the directory (may include
- wildcards) to which a unique identifier method will be applied. Multiple
- directories may be listed, separated with semi-colons
- (:). E.g.:
- 'sites/*/modules/*:sites/*/themes/*'.", $format_variables),
- t("@format-extensions is an optional
- setting to limit which file types should use this unique identifier
- method. E.g.:
- '.css .jpg .jpeg .png'.", $format_variables),
- t("@format-unique-identifier-method sets the unique
- identifier method that should be applied to the aforementioned
- directories, and only to (optionally) the listed file types. Available
- methods are: !format-available-unique-identifier-methods.",
- $format_variables),
- );
- $example_list_items = array(
- t("This would generate a unique identifier for Drupal core files based on
- the Drupal core version, files in the site directory would get unique
- identifiers based on the last time they were modified and movie files
- would not receive a unique identifier (they're so large browser can't
- cache them anyway):
- misc/*:modules/*:themes/*|drupal_version\nsites/*|mtime\nsites/*|.avi .m4v .mov .mp4 .wmv .flv|perpetualCDN_DEPLOYMENT_ID constant
- somewhere in its codebase. This constant changes whenever a module or
- theme changes. This is therefor far more efficient. See the last line:
- misc/*:modules/*:themes/*|drupal_version\nsites/*|mtime\nsites/*|.avi .m4v .mov .mp4 .wmv .flv|perpetual\nsites/*/modules/*:sites/*/themes/*|deployment_id- Note that if no unique file identifier generation - method is specified for a file because none of the - above rules apply to it, the CDN module will fall - back to the !default-ufi-method method. -
- Sample mappings: - !example-list", $format_variables + array( - '!format-explanation-list' => theme('item_list', $format_explanation_list_items), - '!example-list' => theme('item_list', $example_list_items), - '!default-ufi-method' => '' . CDN_BASIC_FARFUTURE_UNIQUE_IDENTIFIER_DEFAULT . '',
- )),
+ '#description' => theme('advanced_help_topic', 'cdn', 'admin-details-mode-pull-ufi') . ' ' . t('Define how unique file identifiers (UFIs) are generated.'),
'#size' => 35,
'#default_value' => variable_get(CDN_BASIC_FARFUTURE_UNIQUE_IDENTIFIER_MAPPING_VARIABLE, CDN_BASIC_FARFUTURE_UNIQUE_IDENTIFIER_MAPPING_DEFAULT),
'#process' => array('ctools_dependent_process'),
@@ -290,15 +165,38 @@ function cdn_admin_details_form(&$form_state) {
'#dependency_count' => 2,
);
+ $form['settings']['ufis'] = array(
+ '#type' => 'fieldset',
+ '#collapsible' => TRUE,
+ '#collapsed' => TRUE,
+ '#title' => t('Available UFI methods'),
+ '#input' => true,
+ '#id' => 'ufi-fs-id',
+ '#prefix' => '' . t('Note that if no UFI method is specified for a file + (because no rule matches), the CDN module will fall + back to the mtime method.') . '
', + '#prefix' => '$servers_for_file is
- available to you (which is an array of servers),
- you should return one of them (or return an empty
- array if you do not want any of them to be used).
- $servers_for_file looks
- like this:
- $servers_for_file[0] = array(\'url\' => \'http://cdn1.com/image.jpg\', \'server\' => \'cdn1.com\');
-$servers_for_file[1] = array(\'url\' => \'http://cdn2.net/image.jpg\', \'server\' => \'cdn2.net\');return $servers_for_file[$some_index];After a file has been synced, File Conveyor stores the "absolute file path" to "URL of the file on the CDN" mapping in a SQLite database. The CDN module then uses this database to replace file URLs with their corresponding CDN URLs.
+ +This file usually lives in the same directory as File Conveyor itself. By default, it's called synced_files.db.
diff --git a/help/admin-details-mode-fc-pid.html b/help/admin-details-mode-fc-pid.html new file mode 100644 index 0000000..40287bd --- /dev/null +++ b/help/admin-details-mode-fc-pid.html @@ -0,0 +1,3 @@ +The CDN module uses File Conveyor's "PID file" (Process ID file) to know whether File Conveyor is up & running or not.
+ +This file usually lives at ~/.fileconveyor.pid. Thus it is dependent on which user of the system executes File Conveyor.
diff --git a/help/admin-details-mode-fc.html b/help/admin-details-mode-fc.html new file mode 100644 index 0000000..06fcfd8 --- /dev/null +++ b/help/admin-details-mode-fc.html @@ -0,0 +1,3 @@ +File Conveyor mode uses the File Conveyor daemon to synchronize files and can be used with both Origin Pull and Push CDNs. If you're using an Origin Pull CDN and want to optimize files before they're synced to the CDN, it is also recommended to use this mode.
+ +Note that this requires a fair amount of server administration knowledge. It is powerful, but that power comes with the price of a more complex configuration.
\ No newline at end of file diff --git a/help/admin-details-mode-pull-cdn-mapping.html b/help/admin-details-mode-pull-cdn-mapping.html new file mode 100644 index 0000000..51735ad --- /dev/null +++ b/help/admin-details-mode-pull-cdn-mapping.html @@ -0,0 +1,16 @@ +Enter one mapping per line, in the format <URL>[|<extensions>]:
+http://cdn-a.com.css .jpg .jpeg .pnghttp://cdn-a.com
http://cdn-a.com|.css .jpg .jpeg .png +http://cdn-b.com|.zip +http://cdn-c.com
Recommended for maximum performance boost!
+Mark all files served from the CDN to expire in the far future (decades from now). This is the same as telling browsers to always use the cached files. This can significantly speed up page loads. Files are also automatically compressed (when the browser supports it), to speed up page loads even further.
+Of course, you still want visitors to immediately get new versions of files when they change. That is why unique filenames are generated automatically.
+For the experts: the following HTTP headers are set: Expires, Cache-Control, Last-Modified, Vary, for files with one of the following extensions: !extensions and of these extensions, some will also be automatically compressed: !extensions-compressed.
\ No newline at end of file diff --git a/help/admin-details-mode-pull-ufi.html b/help/admin-details-mode-pull-ufi.html new file mode 100644 index 0000000..27a0c6d --- /dev/null +++ b/help/admin-details-mode-pull-ufi.html @@ -0,0 +1,28 @@ +To be able to use Far Future expiration, we need to make sure that the URL of a file changes whenever the file changes. Otherwise, visitors will continue to use the old version of the file, that they've cached.
+Depending on the type of file, it is usually better to use a different unique file identifier (UFI) method. Overall, you will want to minimize the number of times that the file system needs to be accessed.
That's why the perpetual, drupal_version and deployment_id methods are the most efficient: they don't touch the file system at all. However, perpetual will never detect file changes, so only use that if you're absolutely certain a file will never change (e.g. for video files). drupal_version should only be used for Drupal core files. And deployment_id should probably only be used for files that are managed through version control.
+ +Enter one rule per line, in the format <directory>[|<extensions>]|<unique file identifier (UFI) method>:
+sites/*/modules/*:sites/*/themes/*
.css .jpg .jpeg .png
Note: To see which UFI methods are available, please consult the UI — this help system only allows for static content.
+ + +This would generate a unique identifier for Drupal core files based on the Drupal core version, files in the site directory would get unique identifiers based on the last time they were modified and movie files would not receive a unique identifier (they're so large browser can't cache them anyway):
+misc/*:modules/*:themes/*|drupal_version +sites/*|mtime +sites/*|.avi .m4v .mov .mp4 .wmv .flv|perpetual+
In this second example, we're dealing with a more high-traffic website, where it is too costly to access the filesystem for every served file. Therefor, this site defines a CDN_DEPLOYMENT_ID constant somewhere in its codebase. This constant changes whenever a module or theme changes. This is therefor far more efficient. See the last line:
+misc/*:modules/*:themes/*|drupal_version +sites/*|mtime +sites/*|.avi .m4v .mov .mp4 .wmv .flv|perpetual +sites/*/modules/*:sites/*/themes/*|deployment_id\ No newline at end of file diff --git a/help/admin-details-mode-pull.html b/help/admin-details-mode-pull.html new file mode 100644 index 0000000..2d7d4fd --- /dev/null +++ b/help/admin-details-mode-pull.html @@ -0,0 +1 @@ +
Origin Pull mode replaces your domain name with the Origin Pull CDN's domain name in the file URL.
\ No newline at end of file diff --git a/help/admin-details-mode.html b/help/admin-details-mode.html new file mode 100644 index 0000000..6e0a517 --- /dev/null +++ b/help/admin-details-mode.html @@ -0,0 +1,6 @@ +It is essential that you understand the key properties of a CDN, most importantly the differences between an Origin Pull CDN and a Push CDN. If you understand that, continue to make a choice between the two supported modes:
+ +Here, you can configure the details of your CDN set-up. Click through +to other help topics to learn more about the implications of every setting.
\ No newline at end of file diff --git a/help/admin-other-cdn-pick-server.html b/help/admin-other-cdn-pick-server.html new file mode 100644 index 0000000..cd1758c --- /dev/null +++ b/help/admin-other-cdn-pick-server.html @@ -0,0 +1,26 @@ +The parameter $servers_for_file is available to you (which is an array of servers), you should return one of them (or return an empty array if you do not want any of them to be used).
+
Internally, $servers_for_file looks like this:
+$servers_for_file[0] = array('url' => 'http://cdn1.com/image.jpg', 'server' => 'cdn1.com');
+$servers_for_file[1] = array('url' => 'http://cdn2.net/image.jpg', 'server' => 'cdn2.net');
+Eventually, you should always end your code with something like:
+return $servers_for_file[$some_index];+ +
Note: it's also possible to define a cdn_pick_server() function in a module. Because, yes, if you use the UI to implement this, PHP's eval() will be used.
+ + +Default behavior (pick the first server found — note that multiple servers can only be found if you're using File Conveyor), one would write: +
return $servers_for_file[0];+
+$filename = basename($servers_for_file[0]['url']); +$unique_file_id = hexdec(substr(md5($filename), 0, 5)); +return $servers_for_file[$unique_file_id % count($servers_for_file)]; ++
By default, some (mostly JavaScript) files are excluded. This is necessary to ensure a painless out-of-the-box experience. For maximum performance, you should only exclude problematic JavaScript files.
+Finally, when any of the pages of the Drupal back-end (admin section) are used, CDN integration is disabled by default.
It's necessary prevent any possible cross-domain AJAX requests, which would violate the same origin policy of browsers. Such violations potentially result in broken functionality. Note that even requests to subdomains such as cdn.yourdomain.com count as cross-domain requests!
+You can opt-in to including JavaScript files by default and then exclude problematic ones, but then you should carefully note which JavaScript files perform AJAX requests. You can prevent all potential problems by using JSONP, which is a work-around to allow for cross-domain AJAX requests.
+ + +A user-configurable blacklist.
+ +The CDN module blacklists the following files by default: +
Note: If you develop a module that ships with JavaScript files that should not be served from a CDN, you can implement the hook_cdn_blacklist() hook to automatically blacklist those files.
+ + +Drupal core JavaScript files are whitelisted.
+ + +A user-configurable blacklist of Drupal paths on which no files should be served from a CDN. This blacklist applies to all users
+ +Similar to "Drupal path", but only applied to authenticated users.
+By default, all Drupal back-end (admin*) pages are blacklisted and will thus not use any files from a CDN.
diff --git a/help/admin-other-https.html b/help/admin-other-https.html new file mode 100644 index 0000000..25cae4f --- /dev/null +++ b/help/admin-other-https.html @@ -0,0 +1,2 @@ +When a page is being served via HTTPS and the CDN does not support HTTPS, then the file will not be served from the CDN, because it would make the visit insecure.
+If your CDN does support HTTPS, and if you are not masking the original URL's domain with another (sub)domain (using a CNAME record), enable the corresponding setting below, and your CDN will also be used on HTTPS pages.
\ No newline at end of file diff --git a/help/admin-other.html b/help/admin-other.html new file mode 100644 index 0000000..637c6bc --- /dev/null +++ b/help/admin-other.html @@ -0,0 +1 @@ +Here are the settings you usually don't need to touch. Make sure you know what you're doing!
\ No newline at end of file diff --git a/help/cdn.help.ini b/help/cdn.help.ini new file mode 100644 index 0000000..74c39b8 --- /dev/null +++ b/help/cdn.help.ini @@ -0,0 +1,72 @@ +[admin-details] +title = "Admin: Details" +weight = 1 + +[admin-details-mode] +title = "Mode" +parent = admin-details +weight = 1 + + + + +[admin-details-mode-pull] +title = "Origin Pull" +parent = admin-details-mode +weight = 1 + +[admin-details-mode-pull-cdn-mapping] +title = "CDN mapping" +parent = admin-details-mode-pull +weight = 1 + +[admin-details-mode-pull-far-future] +title = "Far Future expiration" +parent = admin-details-mode-pull +weight = 2 + +[admin-details-mode-pull-ufi] +title = "Unique file identifier generation" +parent = admin-details-mode-pull +weight = 3 + + + + +[admin-details-mode-fc] +title = "File Conveyor" +parent = admin-details-mode +weight = 2 + +[admin-details-mode-fc-pid] +title = "PID file" +parent = admin-details-mode-fc +weight = 1 + +[admin-details-mode-fc-db] +title = "Synced files database" +parent = admin-details-mode-fc +weight = 2 + + + + + +[admin-other] +title = "Admin: Other" +weight = 2 + +[admin-other-https] +title = "HTTPS" +parent = admin-other +weight = 1 + +[admin-other-exceptions] +title = "Exceptions" +parent = admin-other +weight = 2 + +[admin-other-cdn-pick-server] +title = "cdn_pick_server()" +parent = admin-other +weight = 3