Uploaded image for project: 'Moodle'
  1. Moodle
  2. MDL-59123

Compile SCSS files on the command-line

    XMLWordPrintable

    Details

    • Testing Instructions:
      Hide

      Glossary

      1. cache directory: this is the located as a sibling directory to you moodle install. For example if you had moodle installed in /opt/moodle/ then the cache directory would be /opt/moodledata/localcache/theme/<revision>/<theme_name>/css/all_<subrevision>.css
      2. theme revision: this is the global revision applicable to all themes. It is used in the local cache path as the parent directory for all themes, e.g. /opt/moodledata/localcache/theme/<revision>.
      3. theme sub revision: this is the revision specific to each theme. It is used in the file name of the local cache file, e.g. the cached file will be called all_<subrevision>.css where previously it was called all.css
      4. LTR css: the CSS generated for LTR languages (such as English). It is stored in a file named all_<subrevision>.css in the local cache.
      5. RTL css: the CSS generated for TRL languages (such as Arabic). It is stored in a file named all-rtl_<subrevision>.css in the local cache.
      6. chunked CSS files: theme/styles.php will generated “chunked” CSS files for compatibility with IE 9 and below which has a size limit on the CSS files it will accept. These files appear in local cache with names like all_<subrevision>.1.css and all_<subrevision>.2.css

      Prerequisites

      1. Make sure your Moodle site isn’t running in theme designer mode

      Test 1 - Build and replace single theme’s CSS

      1. Use the boost theme
      2. Purge the caches (to nuke the local cache)
      3. Load your moodle site in the browser
      4. Look in the local cache directory and note the revision number and sub revision number
      5. Edit theme/boost/scss/moodle/admin.scss and add

         body { background-color: black; } 

        to the end of the file

      6. Run the script to build boost: php admin/cli/build_theme_css.php --themes=boost --verbose
      7. Look in the local cache and confirm that the revision number has remained the same however the sub revision number for the boost theme has incremented. Both the LTR and RTL files have been generated for the boost theme. No other theme files are generated in the local cache.
      8. Reload the moodle page and confirm that the body background is set to black (this means the browser has fetched your newly created cache file)
      9. Revert your changes to admin.scss
      10. Log in as admin (if you aren’t already)
      11. Look in the cache directory and confirm that the revision and sub revision number is the same as above (i.e. it didn’t rebuild the cache on page load)
      12. Change the theme to Clean (site administration > appearance > theme selector)
      13. Look in the cache directory and confirm that the revision and sub number stayed the same for Boost
      14. Look in the cache directory and confirm files have been added for the Clean theme. They will also include the “chunked” CSS files because they were built by theme/styles.php. Note down the revision and sub revision for use in Test 2.

      Test 2 - Build only increments a single theme’s sub revision

      1. Continue on from Test 1
      2. Open the developer tools of your browser and select the network tab
      3. Change theme back to Boost. Your body background colour should still be black from Test 1 because the browser should still be serving it’s cached version of the CSS.
      4. Confirm in the network tab that the browser uses it’s own cached version of the Boost CSS that was generated in Test 1. On Chrome this is indicated by filtering to CSS requests only and looking for the “all” stylesheet and seeing that it says (from disk cache) in the Size column.
      5. Note down the URL the browser used to fetch the CSS. The URL should be something like http://<your_moodle>/theme/styles.php/boost/1497495112-1497495257/all.
      6. Build the Boost theme again using the build script
      7. Reload the page in your browser (with the dev tools still open)
      8. Confirm that the body background colour is no longer black
      9. Confirm that the URL used to fetch the CSS has now changed, the sub revision should have been incremented from the build. This means the second of the hyphen separated numbers (which is the sub revision) in the CSS URL should have changed while the first (which is the global revision) will have stayed the same
      10. Confirm that the browser was server CSS from Moodle’s local cache by checking the Size column in the dev tools and seeing that it no longer has (from disk cache) (or equivalent in your browser) there. Also the time to load the page should be milliseconds, rather than seconds, which indicates that the SCSS was not compiled as part of this request.
      11. Confirm that the revision and sub revision for the Clean theme have not been incremented in the local cache.

      Test 3 - Build all themes

      1. Run the script to generate all of the themes php admin/cli/build_theme_css.php --verbose
      2. Look in the local cache directory and note down the revision and sub revision numbers for each theme. Confirm that the css has been generated for all of the themes you have installed.
      3. Log in as admin
      4. Check the cache directory and confirm that the revision numbers haven’t changed
      5. Change to a different theme
      6. Check the cache directory and confirm that the revision numbers haven’t changed
      7. Install an RTL language and use it
      8. Reload the page and confirm that the RTL styling is applied

      Test 4

      1. Play around with the script.
        1. Try putting invalid arguments in
        2. Try compiling invalid SCSS and confirm you get an error telling you why it failed to compile
        3. Try compiling different combinations of LTR and RTL CSS and confirm that each is compiled correctly and any missing CSS files are generated on page load.
      Show
      Glossary cache directory : this is the located as a sibling directory to you moodle install. For example if you had moodle installed in /opt/moodle/ then the cache directory would be /opt/moodledata/localcache/theme/<revision>/<theme_name>/css/all_<subrevision>.css theme revision : this is the global revision applicable to all themes. It is used in the local cache path as the parent directory for all themes, e.g. /opt/moodledata/localcache/theme/<revision> . theme sub revision : this is the revision specific to each theme. It is used in the file name of the local cache file, e.g. the cached file will be called all_<subrevision>.css where previously it was called all.css LTR css : the CSS generated for LTR languages (such as English). It is stored in a file named all_<subrevision>.css in the local cache. RTL css : the CSS generated for TRL languages (such as Arabic). It is stored in a file named all-rtl_<subrevision>.css in the local cache. chunked CSS files : theme/styles.php will generated “chunked” CSS files for compatibility with IE 9 and below which has a size limit on the CSS files it will accept. These files appear in local cache with names like all_<subrevision>.1.css and all_<subrevision>.2.css Prerequisites Make sure your Moodle site isn’t running in theme designer mode Test 1 - Build and replace single theme’s CSS Use the boost theme Purge the caches (to nuke the local cache) Load your moodle site in the browser Look in the local cache directory and note the revision number and sub revision number Edit theme/boost/scss/moodle/admin.scss and add body { background-color: black; } to the end of the file Run the script to build boost: php admin/cli/build_theme_css.php --themes=boost --verbose Look in the local cache and confirm that the revision number has remained the same however the sub revision number for the boost theme has incremented. Both the LTR and RTL files have been generated for the boost theme. No other theme files are generated in the local cache. Reload the moodle page and confirm that the body background is set to black (this means the browser has fetched your newly created cache file) Revert your changes to admin.scss Log in as admin (if you aren’t already) Look in the cache directory and confirm that the revision and sub revision number is the same as above (i.e. it didn’t rebuild the cache on page load) Change the theme to Clean (site administration > appearance > theme selector) Look in the cache directory and confirm that the revision and sub number stayed the same for Boost Look in the cache directory and confirm files have been added for the Clean theme. They will also include the “chunked” CSS files because they were built by theme/styles.php. Note down the revision and sub revision for use in Test 2. Test 2 - Build only increments a single theme’s sub revision Continue on from Test 1 Open the developer tools of your browser and select the network tab Change theme back to Boost. Your body background colour should still be black from Test 1 because the browser should still be serving it’s cached version of the CSS. Confirm in the network tab that the browser uses it’s own cached version of the Boost CSS that was generated in Test 1. On Chrome this is indicated by filtering to CSS requests only and looking for the “all” stylesheet and seeing that it says (from disk cache) in the Size column. Note down the URL the browser used to fetch the CSS. The URL should be something like http://<your_moodle>/theme/styles.php/boost/1497495112-1497495257/all . Build the Boost theme again using the build script Reload the page in your browser (with the dev tools still open) Confirm that the body background colour is no longer black Confirm that the URL used to fetch the CSS has now changed, the sub revision should have been incremented from the build. This means the second of the hyphen separated numbers (which is the sub revision) in the CSS URL should have changed while the first (which is the global revision) will have stayed the same Confirm that the browser was server CSS from Moodle’s local cache by checking the Size column in the dev tools and seeing that it no longer has (from disk cache) (or equivalent in your browser) there. Also the time to load the page should be milliseconds, rather than seconds, which indicates that the SCSS was not compiled as part of this request. Confirm that the revision and sub revision for the Clean theme have not been incremented in the local cache. Test 3 - Build all themes Run the script to generate all of the themes php admin/cli/build_theme_css.php --verbose Look in the local cache directory and note down the revision and sub revision numbers for each theme. Confirm that the css has been generated for all of the themes you have installed. Log in as admin Check the cache directory and confirm that the revision numbers haven’t changed Change to a different theme Check the cache directory and confirm that the revision numbers haven’t changed Install an RTL language and use it Reload the page and confirm that the RTL styling is applied Test 4 Play around with the script. Try putting invalid arguments in Try compiling invalid SCSS and confirm you get an error telling you why it failed to compile Try compiling different combinations of LTR and RTL CSS and confirm that each is compiled correctly and any missing CSS files are generated on page load.
    • Affected Branches:
      MOODLE_33_STABLE, MOODLE_34_STABLE
    • Fixed Branches:
      MOODLE_34_STABLE
    • Pull Master Branch:
      MDL-59123-master-3

      Description

      Rather than delegating it to a user request in the browser (and involving loadbalancer/php timeouts and so on). There should be a way to at least have the scss compiled on the command line (ideally it would be part of the cli installer process too).

      As suggested by Paul Verrall in his blog post:
      http://blog.mrverrall.co.uk/2017/05/precaching-moodle-theme-css.html

        Attachments

          Issue Links

            Activity

              People

              • Votes:
                4 Vote for this issue
                Watchers:
                10 Start watching this issue

                Dates

                • Created:
                  Updated:
                  Resolved:
                  Fix Release Date:
                  13/Nov/17