lib/amd/src/user_date.js

  1. // This file is part of Moodle - http://moodle.org/
  2. //
  3. // Moodle is free software: you can redistribute it and/or modify
  4. // it under the terms of the GNU General Public License as published by
  5. // the Free Software Foundation, either version 3 of the License, or
  6. // (at your option) any later version.
  7. //
  8. // Moodle is distributed in the hope that it will be useful,
  9. // but WITHOUT ANY WARRANTY; without even the implied warranty of
  10. // MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  11. // GNU General Public License for more details.
  12. //
  13. // You should have received a copy of the GNU General Public License
  14. // along with Moodle.  If not, see <http://www.gnu.org/licenses/>.
  16. /**
  17.  * Fetch and render dates from timestamps.
  18.  *
  19.  * @module     core/user_date
  20.  * @copyright  2017 Ryan Wyllie <ryan@moodle.com>
  21.  * @license    http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
  22.  */
  23. define(['jquery', 'core/ajax', 'core/sessionstorage', 'core/config'],
  24.         function($, Ajax, Storage, Config) {
  26.     var SECONDS_IN_DAY = 86400;
  28.     /** @var {object} promisesCache Store all promises we've seen so far. */
  29.     var promisesCache = {};
  31.     /**
  32.      * Generate a cache key for the given request. The request should
  33.      * have a timestamp and format key.
  34.      *
  35.      * @param {object} request
  36.      * @return {string}
  37.      */
  38.     var getKey = function(request) {
  39.         return 'core_user_date/' +
  40.                Config.language + '/' +
  41.                Config.usertimezone + '/' +
  42.                request.timestamp + '/' +
  43.                request.format;
  44.     };
  46.     /**
  47.      * Retrieve a transformed date from the browser's storage.
  48.      *
  49.      * @param {string} key
  50.      * @return {string}
  51.      */
  52.     var getFromLocalStorage = function(key) {
  53.         return Storage.get(key);
  54.     };
  56.     /**
  57.      * Save the transformed date in the browser's storage.
  58.      *
  59.      * @param {string} key
  60.      * @param {string} value
  61.      */
  62.     var addToLocalStorage = function(key, value) {
  63.         Storage.set(key, value);
  64.     };
  66.     /**
  67.      * Check if a key is in the module's cache.
  68.      *
  69.      * @param {string} key
  70.      * @return {bool}
  71.      */
  72.     var inPromisesCache = function(key) {
  73.         return (typeof promisesCache[key] !== 'undefined');
  74.     };
  76.     /**
  77.      * Retrieve a promise from the module's cache.
  78.      *
  79.      * @param {string} key
  80.      * @return {object} jQuery promise
  81.      */
  82.     var getFromPromisesCache = function(key) {
  83.         return promisesCache[key];
  84.     };
  86.     /**
  87.      * Save the given promise in the module's cache.
  88.      *
  89.      * @param {string} key
  90.      * @param {object} promise
  91.      */
  92.     var addToPromisesCache = function(key, promise) {
  93.         promisesCache[key] = promise;
  94.     };
  96.     /**
  97.      * Send a request to the server for each of the required timestamp
  98.      * and format combinations.
  99.      *
  100.      * Resolves the date's deferred with the values returned from the
  101.      * server and saves the value in local storage.
  102.      *
  103.      * @param {array} dates
  104.      * @return {object} jQuery promise
  105.      */
  106.     var loadDatesFromServer = function(dates) {
  107.         var args = dates.map(function(data) {
  108.             var fixDay = data.hasOwnProperty('fixday') ? data.fixday : 1;
  109.             var fixHour = data.hasOwnProperty('fixhour') ? data.fixhour : 1;
  110.             return {
  111.                 timestamp: data.timestamp,
  112.                 format: data.format,
  113.                 type: data.type || null,
  114.                 fixday: fixDay,
  115.                 fixhour: fixHour
  116.             };
  117.         });
  119.         var request = {
  120.             methodname: 'core_get_user_dates',
  121.             args: {
  122.                 contextid: Config.contextid,
  123.                 timestamps: args
  124.             }
  125.         };
  127.         return Ajax.call([request], true, true)[0].then(function(results) {
  128.             results.dates.forEach(function(value, index) {
  129.                 var date = dates[index];
  130.                 var key = getKey(date);
  132.                 addToLocalStorage(key, value);
  133.                 date.deferred.resolve(value);
  134.             });
  135.             return;
  136.         })
  137.         .catch(function(ex) {
  138.             // If we failed to retrieve the dates then reject the date's
  139.             // deferred objects to make sure they don't hang.
  140.             dates.forEach(function(date) {
  141.                 date.deferred.reject(ex);
  142.             });
  143.         });
  144.     };
  146.     /**
  147.      * Takes an array of request objects and returns a promise that
  148.      * is resolved with an array of formatted dates.
  149.      *
  150.      * The values in the returned array will be ordered the same as
  151.      * the request array.
  152.      *
  153.      * This function will check both the module's static promises cache
  154.      * and the browser's session storage to see if the user dates have
  155.      * already been loaded in order to avoid sending a network request
  156.      * if possible.
  157.      *
  158.      * Only dates not found in either cache will be sent to the server
  159.      * for transforming.
  160.      *
  161.      * A request object must have a timestamp key and a format key and
  162.      * optionally may have a type key.
  163.      *
  164.      * E.g.
  165.      * var request = [
  166.      *     {
  167.      *         timestamp: 1293876000,
  168.      *         format: '%d %B %Y'
  169.      *     },
  170.      *     {
  171.      *         timestamp: 1293876000,
  172.      *         format: '%A, %d %B %Y, %I:%M %p',
  173.      *         type: 'gregorian',
  174.      *         fixday: false,
  175.      *         fixhour: false
  176.      *     }
  177.      * ];
  178.      *
  179.      * UserDate.get(request).done(function(dates) {
  180.      *     console.log(dates[0]); // prints "1 January 2011".
  181.      *     console.log(dates[1]); // prints "Saturday, 1 January 2011, 10:00 AM".
  182.      * });
  183.      *
  184.      * @param {array} requests
  185.      * @return {object} jQuery promise
  186.      */
  187.     var get = function(requests) {
  188.         var ajaxRequests = [];
  189.         var promises = [];
  191.         // Loop over each of the requested timestamp/format combos
  192.         // and add a promise to the promises array for them.
  193.         requests.forEach(function(request) {
  194.             var key = getKey(request);
  196.             // If we've already got a promise then use it.
  197.             if (inPromisesCache(key)) {
  198.                 promises.push(getFromPromisesCache(key));
  199.             } else {
  200.                 var deferred = $.Deferred();
  201.                 var cached = getFromLocalStorage(key);
  203.                 if (cached) {
  204.                     // If we were able to get the value from session storage
  205.                     // then we can resolve the deferred with that value. No
  206.                     // need to ask the server to transform it for us.
  207.                     deferred.resolve(cached);
  208.                 } else {
  209.                     // Add this request to the list of ones we need to load
  210.                     // from the server. Include the deferred so that it can
  211.                     // be resolved when the server has responded with the
  212.                     // transformed values.
  213.                     request.deferred = deferred;
  214.                     ajaxRequests.push(request);
  215.                 }
  217.                 // Remember this promise for next time so that we can
  218.                 // bail out early if it is requested again.
  219.                 addToPromisesCache(key, deferred.promise());
  220.                 promises.push(deferred.promise());
  221.             }
  222.         });
  224.         // If we have any requests that we couldn't resolve from the caches
  225.         // then let's ask the server to get them for us.
  226.         if (ajaxRequests.length) {
  227.             loadDatesFromServer(ajaxRequests);
  228.         }
  230.         // Wait for all of the promises to resolve. Some of them may be waiting
  231.         // for a response from the server.
  232.         return $.when.apply($, promises).then(function() {
  233.             // This looks complicated but it's just converting an unknown
  234.             // length of arguments into an array for the promise to resolve
  235.             // with.
  236.             return arguments.length === 1 ? [arguments[0]] : Array.apply(null, arguments);
  237.         });
  238.     };
  241.     /**
  242.      * For a given timestamp get the midnight value in the user's timezone.
  243.      *
  244.      * The calculation is performed relative to the user's midnight timestamp
  245.      * for today to ensure that timezones are preserved.
  246.      *
  247.      * E.g.
  248.      * Input:
  249.      * timestamp: 1514836800 (01/01/2018 8pm GMT)(02/01/2018 4am GMT+8)
  250.      * midnight: 1514851200 (02/01/2018 midnight GMT)
  251.      * Output:
  252.      * 1514764800 (01/01/2018 midnight GMT)
  253.      *
  254.      * Input:
  255.      * timestamp: 1514836800 (01/01/2018 8pm GMT)(02/01/2018 4am GMT+8)
  256.      * midnight: 1514822400 (02/01/2018 midnight GMT+8)
  257.      * Output:
  258.      * 1514822400 (02/01/2018 midnight GMT+8)
  259.      *
  260.      * @param {Number} timestamp The timestamp to calculate from
  261.      * @param {Number} todayMidnight The user's midnight timestamp
  262.      * @return {Number} The midnight value of the user's timestamp
  263.      */
  264.     var getUserMidnightForTimestamp = function(timestamp, todayMidnight) {
  265.         var future = timestamp > todayMidnight;
  266.         var diffSeconds = Math.abs(timestamp - todayMidnight);
  267.         var diffDays = future ? Math.floor(diffSeconds / SECONDS_IN_DAY) : Math.ceil(diffSeconds / SECONDS_IN_DAY);
  268.         var diffDaysInSeconds = diffDays * SECONDS_IN_DAY;
  269.         // Is the timestamp in the future or past?
  270.         var dayTimestamp = future ? todayMidnight + diffDaysInSeconds : todayMidnight - diffDaysInSeconds;
  271.         return dayTimestamp;
  272.     };
  274.     return {
  275.         get: get,
  276.         getUserMidnightForTimestamp: getUserMidnightForTimestamp
  277.     };
  278. });