feature 2999 : documentation of include/functions_calendar.inc.php and Calendar classes

git-svn-id: http://piwigo.org/svn/trunk@25507 68402e56-0260-453c-a942-63ccdbb3a9ee

5 files changed, 528 insertions, 453 deletions

diff --git a/include/calendar_base.class.php b/include/calendar_base.class.php
index b61dc41c8..f79b46800 100644
--- a/include/calendar_base.class.php
+++ b/include/calendar_base.class.php
@@ -22,20 +22,41 @@
 // +-----------------------------------------------------------------------+
 
 /**
+ * @package functions\calendar
+ */
+
+
+/**
  * Base class for monthly and weekly calendar styles
  */
-class CalendarBase
+abstract class CalendarBase
 {
-  // db column on which this calendar works
+  /** db column on which this calendar works */
   var $date_field;
-  // used for queries (INNER JOIN or normal)
+  /** used for queries (INNER JOIN or normal) */
   var $inner_sql;
-  //
+  /** used to store db fields */
   var $calendar_levels;
 
   /**
-   * Initialize the calendar
-   * @param string inner_sql used for queries (INNER JOIN or normal)
+   * Generate navigation bars for category page.
+   *
+   * @return boolean false indicates that thumbnails where not included
+   */
+  abstract function generate_category_content();
+
+  /**
+   * Returns a sql WHERE subquery for the date field.
+   *
+   * @param int $max_levels (e.g. 2=only year and month)
+   * @return string
+   */
+  abstract function get_date_where($max_levels);
+
+  /**
+   * Initialize the calendar.
+   *
+   * @param string $inner_sql
    */
   function initialize($inner_sql)
   {
@@ -51,6 +72,11 @@ class CalendarBase
     $this->inner_sql = $inner_sql;
   }
 
+  /**
+   * Returns the calendar title (with HTML).
+   *
+   * @return string
+   */
   function get_display_name()
   {
     global $conf, $page;
@@ -82,11 +108,12 @@ class CalendarBase
     return $res;
   }
 
-//--------------------------------------------------------- private members ---
   /**
-   * Returns a display name for a date component optionally using labels
-  */
-  function get_date_component_label($level, $date_component)
+   * Returns a display name for a date component optionally using labels.
+   *
+   * @return string
+   */
+  protected function get_date_component_label($level, $date_component)
   {
     $label = $date_component;
     if (isset($this->calendar_levels[$level]['labels'][$date_component]))
@@ -101,9 +128,12 @@ class CalendarBase
   }
 
   /**
-   * Gets a nice display name for a date to be shown in previos/next links.
+   * Gets a nice display name for a date to be shown in previous/next links
+   *
+   * @param string $date
+   * @return string
    */
-  function get_date_nice_name($date)
+  protected function get_date_nice_name($date)
   {
     $date_components = explode('-', $date);
     $res = '';
@@ -125,14 +155,14 @@ class CalendarBase
   /**
    * Creates a calendar navigation bar.
    *
-   * @param array date_components
-   * @param array items - hash of items to put in the bar (e.g. 2005,2006)
-   * @param bool show_any - adds any link to the end of the bar
-   * @param bool show_empty - shows all labels even those without items
-   * @param array labels - optional labels for items (e.g. Jan,Feb,...)
-   * @return string the navigation bar
+   * @param array $date_components
+   * @param array $items - hash of items to put in the bar (e.g. 2005,2006)
+   * @param bool $show_any - adds any link to the end of the bar
+   * @param bool $show_empty - shows all labels even those without items
+   * @param array $labels - optional labels for items (e.g. Jan,Feb,...)
+   * @return string
    */
-  function get_nav_bar_from_items($date_components, $items,
+  protected function get_nav_bar_from_items($date_components, $items,
                                   $show_any,
                                   $show_empty=false, $labels=null)
   {
@@ -203,10 +233,9 @@ class CalendarBase
   /**
    * Creates a calendar navigation bar for a given level.
    *
-   * @param int level - the level (0-year,1-month/week,2-day)
-   * @return void
+   * @param int $level - 0-year, 1-month/week, 2-day
    */
-  function build_nav_bar($level, $labels=null)
+  protected function build_nav_bar($level, $labels=null)
   {
     global $template, $conf, $page;
 
@@ -261,7 +290,7 @@ $this->get_date_where($level).'
    * Assigns the next/previous link to the template with regards to
    * the currently choosen date.
    */
-  function build_next_prev()
+  protected function build_next_prev()
   {
     global $template, $page;
 
@@ -343,4 +372,5 @@ GROUP BY period';
     }
   }
 }
+
 ?>
\ No newline at end of file
diff --git a/include/calendar_monthly.class.php b/include/calendar_monthly.class.php
index 091d78884..c8f2d5b3e 100644
--- a/include/calendar_monthly.class.php
+++ b/include/calendar_monthly.class.php
@@ -21,21 +21,28 @@
 // | USA.                                                                  |
 // +-----------------------------------------------------------------------+
 
+/**
+ * @package functions\calendar
+ */
+
 include_once(PHPWG_ROOT_PATH.'include/calendar_base.class.php');
 
-define ('CYEAR',  0);
-define ('CMONTH', 1);
-define ('CDAY',   2);
+/** level of year view */
+define('CYEAR',  0);
+/** level of month view */
+define('CMONTH', 1);
+/** level of day view */
+define('CDAY',   2);
+
 
 /**
  * Monthly calendar style (composed of years/months and days)
  */
 class Calendar extends CalendarBase
 {
-
   /**
-   * Initialize the calendar
-   * @param string inner_sql used for queries (INNER JOIN or normal)
+   * Initialize the calendar.
+   * @param string $inner_sql
    */
   function initialize($inner_sql)
   {
@@ -57,113 +64,126 @@ class Calendar extends CalendarBase
      );
   }
 
-/**
- * Generate navigation bars for category page
- * @return boolean false to indicate that thumbnails
- * where not included here, true otherwise
- */
-function generate_category_content()
-{
-  global $conf, $page;
-
-  $view_type = $page['chronology_view'];
-  if ($view_type==CAL_VIEW_CALENDAR)
+  /**
+   * Generate navigation bars for category page.
+   *
+   * @return boolean false indicates that thumbnails where not included
+   */
+  function generate_category_content()
   {
-    global $template;
-    $tpl_var = array();
-    if ( count($page['chronology_date'])==0 )
-    {//case A: no year given - display all years+months
-      if ($this->build_global_calendar($tpl_var))
-      {
-        $template->assign('chronology_calendar', $tpl_var);
+    global $conf, $page;
+
+    $view_type = $page['chronology_view'];
+    if ($view_type==CAL_VIEW_CALENDAR)
+    {
+      global $template;
+      $tpl_var = array();
+      if ( count($page['chronology_date'])==0 )
+      {//case A: no year given - display all years+months
+        if ($this->build_global_calendar($tpl_var))
+        {
+          $template->assign('chronology_calendar', $tpl_var);
+          return true;
+        }
+      }
+
+      if ( count($page['chronology_date'])==1 )
+      {//case B: year given - display all days in given year
+        if ($this->build_year_calendar($tpl_var))
+        {
+          $template->assign('chronology_calendar', $tpl_var);
+          $this->build_nav_bar(CYEAR); // years
+          return true;
+        }
+      }
+
+      if ( count($page['chronology_date'])==2 )
+      {//case C: year+month given - display a nice month calendar
+        if ( $this->build_month_calendar($tpl_var) )
+        {
+          $template->assign('chronology_calendar', $tpl_var);
+        }
+        $this->build_next_prev();
         return true;
       }
     }
 
-    if ( count($page['chronology_date'])==1 )
-    {//case B: year given - display all days in given year
-      if ($this->build_year_calendar($tpl_var))
+    if ($view_type==CAL_VIEW_LIST or count($page['chronology_date'])==3)
+    {
+      if ( count($page['chronology_date'])==0 )
       {
-        $template->assign('chronology_calendar', $tpl_var);
         $this->build_nav_bar(CYEAR); // years
-        return true;
       }
-    }
-
-    if ( count($page['chronology_date'])==2 )
-    {//case C: year+month given - display a nice month calendar
-      if ( $this->build_month_calendar($tpl_var) )
+      if ( count($page['chronology_date'])==1)
+      {
+        $this->build_nav_bar(CMONTH); // month
+      }
+      if ( count($page['chronology_date'])==2 )
       {
-        $template->assign('chronology_calendar', $tpl_var);
+        $day_labels = range( 1, $this->get_all_days_in_month(
+                $page['chronology_date'][CYEAR] ,$page['chronology_date'][CMONTH] ) );
+        array_unshift($day_labels, 0);
+        unset( $day_labels[0] );
+        $this->build_nav_bar( CDAY, $day_labels ); // days
       }
       $this->build_next_prev();
-      return true;
     }
+    return false;
   }
 
-  if ($view_type==CAL_VIEW_LIST or count($page['chronology_date'])==3)
+  /**
+   * Returns a sql WHERE subquery for the date field.
+   *
+   * @param int $max_levels (e.g. 2=only year and month)
+   * @return string
+   */
+  function get_date_where($max_levels=3)
   {
-    if ( count($page['chronology_date'])==0 )
-    {
-      $this->build_nav_bar(CYEAR); // years
-    }
-    if ( count($page['chronology_date'])==1)
-    {
-      $this->build_nav_bar(CMONTH); // month
-    }
-    if ( count($page['chronology_date'])==2 )
+    global $page;
+
+    $date = $page['chronology_date'];
+    while (count($date)>$max_levels)
     {
-      $day_labels = range( 1, $this->get_all_days_in_month(
-              $page['chronology_date'][CYEAR] ,$page['chronology_date'][CMONTH] ) );
-      array_unshift($day_labels, 0);
-      unset( $day_labels[0] );
-      $this->build_nav_bar( CDAY, $day_labels ); // days
+      array_pop($date);
     }
-    $this->build_next_prev();
-  }
-  return false;
-}
-
-
-/**
- * Returns a sql where subquery for the date field
- * @param int max_levels return the where up to this level
- * (e.g. 2=only year and month)
- * @return string
- */
-function get_date_where($max_levels=3)
-{
-  global $page;
-
-  $date = $page['chronology_date'];
-  while (count($date)>$max_levels)
-  {
-    array_pop($date);
-  }
-  $res = '';
-  if (isset($date[CYEAR]) and $date[CYEAR]!=='any')
-  {
-    $b = $date[CYEAR] . '-';
-    $e = $date[CYEAR] . '-';
-    if (isset($date[CMONTH]) and $date[CMONTH]!=='any')
+    $res = '';
+    if (isset($date[CYEAR]) and $date[CYEAR]!=='any')
     {
-      $b .= sprintf('%02d-', $date[CMONTH]);
-      $e .= sprintf('%02d-', $date[CMONTH]);
-      if (isset($date[CDAY]) and $date[CDAY]!=='any')
+      $b = $date[CYEAR] . '-';
+      $e = $date[CYEAR] . '-';
+      if (isset($date[CMONTH]) and $date[CMONTH]!=='any')
       {
-        $b .= sprintf('%02d', $date[CDAY]);
-        $e .= sprintf('%02d', $date[CDAY]);
+        $b .= sprintf('%02d-', $date[CMONTH]);
+        $e .= sprintf('%02d-', $date[CMONTH]);
+        if (isset($date[CDAY]) and $date[CDAY]!=='any')
+        {
+          $b .= sprintf('%02d', $date[CDAY]);
+          $e .= sprintf('%02d', $date[CDAY]);
+        }
+        else
+        {
+          $b .= '01';
+          $e .= $this->get_all_days_in_month($date[CYEAR], $date[CMONTH]);
+        }
       }
       else
       {
-        $b .= '01';
-        $e .= $this->get_all_days_in_month($date[CYEAR], $date[CMONTH]);
+        $b .= '01-01';
+        $e .= '12-31';
+        if (isset($date[CMONTH]) and $date[CMONTH]!=='any')
+        {
+          $res .= ' AND '.$this->calendar_levels[CMONTH]['sql'].'='.$date[CMONTH];
+        }
+        if (isset($date[CDAY]) and $date[CDAY]!=='any')
+        {
+          $res .= ' AND '.$this->calendar_levels[CDAY]['sql'].'='.$date[CDAY];
+        }
       }
+      $res = " AND $this->date_field BETWEEN '$b' AND '$e 23:59:59'" . $res;
     }
     else
     {
-      $b .= '01-01';
-      $e .= '12-31';
+      $res = ' AND '.$this->date_field.' IS NOT NULL';
       if (isset($date[CMONTH]) and $date[CMONTH]!=='any')
       {
         $res .= ' AND '.$this->calendar_levels[CMONTH]['sql'].'='.$date[CMONTH];
@@ -173,344 +193,351 @@ function get_date_where($max_levels=3)
         $res .= ' AND '.$this->calendar_levels[CDAY]['sql'].'='.$date[CDAY];
       }
     }
-    $res = " AND $this->date_field BETWEEN '$b' AND '$e 23:59:59'" . $res;
+    return $res;
   }
-  else
+
+  /**
+   * Returns an array with all the days in a given month.
+   *
+   * @param int $year
+   * @param int $month
+   * @return int[]
+   */
+  protected function get_all_days_in_month($year, $month)
   {
-    $res = ' AND '.$this->date_field.' IS NOT NULL';
-    if (isset($date[CMONTH]) and $date[CMONTH]!=='any')
+    $md= array(1=>31,28,31,30,31,30,31,31,30,31,30,31);
+
+    if ( is_numeric($year) and $month==2)
+    {
+      $nb_days = $md[2];
+      if ( ($year%4==0)  and ( ($year%100!=0) or ($year%400!=0) ) )
+      {
+        $nb_days++;
+      }
+    }
+    elseif ( is_numeric($month) )
     {
-      $res .= ' AND '.$this->calendar_levels[CMONTH]['sql'].'='.$date[CMONTH];
+      $nb_days = $md[ $month ];
     }
-    if (isset($date[CDAY]) and $date[CDAY]!=='any')
+    else
     {
-      $res .= ' AND '.$this->calendar_levels[CDAY]['sql'].'='.$date[CDAY];
+      $nb_days = 31;
     }
+    return $nb_days;
   }
-  return $res;
-}
-
-
 
-//--------------------------------------------------------- private members ---
+  /**
+   * Build global calendar and assign the result in _$tpl_var_
+   *
+   * @param array $tpl_var
+   * @return bool
+   */
+  protected function build_global_calendar(&$tpl_var)
+  {
+    global $page;
 
-// returns an array with all the days in a given month
-function get_all_days_in_month($year, $month)
-{
-  $md= array(1=>31,28,31,30,31,30,31,31,30,31,30,31);
+    assert( count($page['chronology_date']) == 0 );
+    $query='
+  SELECT '.pwg_db_get_date_YYYYMM($this->date_field).' as period,
+    COUNT(distinct id) as count';
+    $query.= $this->inner_sql;
+    $query.= $this->get_date_where();
+    $query.= '
+    GROUP BY period
+    ORDER BY '.pwg_db_get_year($this->date_field).' DESC, '.pwg_db_get_month($this->date_field).' ASC';
 
-  if ( is_numeric($year) and $month==2)
-  {
-    $nb_days = $md[2];
-    if ( ($year%4==0)  and ( ($year%100!=0) or ($year%400!=0) ) )
+    $result = pwg_query($query);
+    $items=array();
+    while ($row = pwg_db_fetch_assoc($result))
     {
-      $nb_days++;
+      $y = substr($row['period'], 0, 4);
+      $m = (int)substr($row['period'], 4, 2);
+      if ( ! isset($items[$y]) )
+      {
+        $items[$y] = array('nb_images'=>0, 'children'=>array() );
+      }
+      $items[$y]['children'][$m] = $row['count'];
+      $items[$y]['nb_images'] += $row['count'];
+    }
+    //echo ('<pre>'. var_export($items, true) . '</pre>');
+    if (count($items)==1)
+    {// only one year exists so bail out to year view
+      list($y) = array_keys($items);
+      $page['chronology_date'][CYEAR] = $y;
+      return false;
     }
-  }
-  elseif ( is_numeric($month) )
-  {
-    $nb_days = $md[ $month ];
-  }
-  else
-  {
-    $nb_days = 31;
-  }
-  return $nb_days;
-}
 
-function build_global_calendar(&$tpl_var)
-{
-  global $page;
-
-  assert( count($page['chronology_date']) == 0 );
-  $query='
-SELECT '.pwg_db_get_date_YYYYMM($this->date_field).' as period,
-  COUNT(distinct id) as count';
-  $query.= $this->inner_sql;
-  $query.= $this->get_date_where();
-  $query.= '
-  GROUP BY period
-  ORDER BY '.pwg_db_get_year($this->date_field).' DESC, '.pwg_db_get_month($this->date_field).' ASC';
-
-  $result = pwg_query($query);
-  $items=array();
-  while ($row = pwg_db_fetch_assoc($result))
-  {
-    $y = substr($row['period'], 0, 4);
-    $m = (int)substr($row['period'], 4, 2);
-    if ( ! isset($items[$y]) )
+    global $lang;
+    foreach ( $items as $year=>$year_data)
     {
-      $items[$y] = array('nb_images'=>0, 'children'=>array() );
-    }
-    $items[$y]['children'][$m] = $row['count'];
-    $items[$y]['nb_images'] += $row['count'];
-  }
-  //echo ('<pre>'. var_export($items, true) . '</pre>');
-  if (count($items)==1)
-  {// only one year exists so bail out to year view
-    list($y) = array_keys($items);
-    $page['chronology_date'][CYEAR] = $y;
-    return false;
-  }
+      $chronology_date = array( $year );
+      $url = duplicate_index_url( array('chronology_date'=>$chronology_date) );
 
-  global $lang;
-  foreach ( $items as $year=>$year_data)
-  {
-    $chronology_date = array( $year );
-    $url = duplicate_index_url( array('chronology_date'=>$chronology_date) );
+      $nav_bar = $this->get_nav_bar_from_items( $chronology_date,
+              $year_data['children'], false, false, $lang['month'] );
 
-    $nav_bar = $this->get_nav_bar_from_items( $chronology_date,
-            $year_data['children'], false, false, $lang['month'] );
+      $tpl_var['calendar_bars'][] =
+        array(
+          'U_HEAD'  => $url,
+          'NB_IMAGES' => $year_data['nb_images'],
+          'HEAD_LABEL' => $year,
+          'items' => $nav_bar,
+        );
+    }
 
-    $tpl_var['calendar_bars'][] =
-      array(
-        'U_HEAD'  => $url,
-        'NB_IMAGES' => $year_data['nb_images'],
-        'HEAD_LABEL' => $year,
-        'items' => $nav_bar,
-      );
+    return true;
   }
-  return true;
-}
 
-function build_year_calendar(&$tpl_var)
-{
-  global $page;
-
-  assert( count($page['chronology_date']) == 1 );
-  $query='SELECT '.pwg_db_get_date_MMDD($this->date_field).' as period,
-            COUNT(DISTINCT id) as count';
-  $query.= $this->inner_sql;
-  $query.= $this->get_date_where();
-  $query.= '
-  GROUP BY period
-  ORDER BY period ASC';
-
-  $result = pwg_query($query);
-  $items=array();
-  while ($row = pwg_db_fetch_assoc($result))
+  /**
+   * Build year calendar and assign the result in _$tpl_var_
+   *
+   * @param array $tpl_var
+   * @return bool
+   */
+  protected function build_year_calendar(&$tpl_var)
   {
-    $m = (int)substr($row['period'], 0, 2);
-    $d = substr($row['period'], 2, 2);
-    if ( ! isset($items[$m]) )
+    global $page;
+
+    assert( count($page['chronology_date']) == 1 );
+    $query='SELECT '.pwg_db_get_date_MMDD($this->date_field).' as period,
+              COUNT(DISTINCT id) as count';
+    $query.= $this->inner_sql;
+    $query.= $this->get_date_where();
+    $query.= '
+    GROUP BY period
+    ORDER BY period ASC';
+
+    $result = pwg_query($query);
+    $items=array();
+    while ($row = pwg_db_fetch_assoc($result))
     {
-      $items[$m] = array('nb_images'=>0, 'children'=>array() );
+      $m = (int)substr($row['period'], 0, 2);
+      $d = substr($row['period'], 2, 2);
+      if ( ! isset($items[$m]) )
+      {
+        $items[$m] = array('nb_images'=>0, 'children'=>array() );
+      }
+      $items[$m]['children'][$d] = $row['count'];
+      $items[$m]['nb_images'] += $row['count'];
     }
-    $items[$m]['children'][$d] = $row['count'];
-    $items[$m]['nb_images'] += $row['count'];
-  }
-  if (count($items)==1)
-  { // only one month exists so bail out to month view
-    list($m) = array_keys($items);
-    $page['chronology_date'][CMONTH] = $m;
-    return false;
-  }
-  global $lang;
-  foreach ( $items as $month=>$month_data)
-  {
-    $chronology_date = array( $page['chronology_date'][CYEAR], $month );
-    $url = duplicate_index_url( array('chronology_date'=>$chronology_date) );
-
-    $nav_bar = $this->get_nav_bar_from_items( $chronology_date,
-                     $month_data['children'], false );
+    if (count($items)==1)
+    { // only one month exists so bail out to month view
+      list($m) = array_keys($items);
+      $page['chronology_date'][CMONTH] = $m;
+      return false;
+    }
+    global $lang;
+    foreach ( $items as $month=>$month_data)
+    {
+      $chronology_date = array( $page['chronology_date'][CYEAR], $month );
+      $url = duplicate_index_url( array('chronology_date'=>$chronology_date) );
 
-    $tpl_var['calendar_bars'][] =
-      array(
-        'U_HEAD'  => $url,
-        'NB_IMAGES' => $month_data['nb_images'],
-        'HEAD_LABEL' => $lang['month'][$month],
-        'items' => $nav_bar,
-      );
-  }
-  return true;
+      $nav_bar = $this->get_nav_bar_from_items( $chronology_date,
+                       $month_data['children'], false );
 
-}
+      $tpl_var['calendar_bars'][] =
+        array(
+          'U_HEAD'  => $url,
+          'NB_IMAGES' => $month_data['nb_images'],
+          'HEAD_LABEL' => $lang['month'][$month],
+          'items' => $nav_bar,
+        );
+    }
 
-function build_month_calendar(&$tpl_var)
-{
-  global $page, $lang, $conf;
-
-  $query='SELECT '.pwg_db_get_dayofmonth($this->date_field).' as period,
-            COUNT(DISTINCT id) as count';
-  $query.= $this->inner_sql;
-  $query.= $this->get_date_where();
-  $query.= '
-  GROUP BY period
-  ORDER BY period ASC';
-
-  $items=array();
-  $result = pwg_query($query);
-  while ($row = pwg_db_fetch_assoc($result))
-  {
-    $d = (int)$row['period'];
-    $items[$d] = array('nb_images'=>$row['count']);
+    return true;
   }
 
-  foreach ( $items as $day=>$data)
+  /**
+   * Build month calendar and assign the result in _$tpl_var_
+   *
+   * @param array $tpl_var
+   * @return bool
+   */
+  protected function build_month_calendar(&$tpl_var)
   {
-    $page['chronology_date'][CDAY]=$day;
-    $query = '
-SELECT id, file,representative_ext,path,width,height,rotation, '.pwg_db_get_dayofweek($this->date_field).'-1 as dow';
+    global $page, $lang, $conf;
+
+    $query='SELECT '.pwg_db_get_dayofmonth($this->date_field).' as period,
+              COUNT(DISTINCT id) as count';
     $query.= $this->inner_sql;
     $query.= $this->get_date_where();
     $query.= '
-  ORDER BY '.DB_RANDOM_FUNCTION.'()
-  LIMIT 1';
-    unset ( $page['chronology_date'][CDAY] );
-
-    $row = pwg_db_fetch_assoc(pwg_query($query));
-    $derivative = new DerivativeImage(IMG_SQUARE, new SrcImage($row));
-    $items[$day]['derivative'] = $derivative;
-    $items[$day]['file'] = $row['file'];
-    $items[$day]['dow'] = $row['dow'];
-  }
+    GROUP BY period
+    ORDER BY period ASC';
 
-  if ( !empty($items) )
-  {
-    list($known_day) = array_keys($items);
-    $known_dow = $items[$known_day]['dow'];
-    $first_day_dow = ($known_dow-($known_day-1))%7;
-    if ($first_day_dow<0)
+    $items=array();
+    $result = pwg_query($query);
+    while ($row = pwg_db_fetch_assoc($result))
     {
-      $first_day_dow += 7;
+      $d = (int)$row['period'];
+      $items[$d] = array('nb_images'=>$row['count']);
     }
-    //first_day_dow = week day corresponding to the first day of this month
-    $wday_labels = $lang['day'];
 
-    if ('monday' == $conf['week_starts_on'])
+    foreach ( $items as $day=>$data)
     {
-      if ($first_day_dow==0)
-      {
-        $first_day_dow = 6;
-      }
-      else
-      {
-        $first_day_dow -= 1;
-      }
-
-      $wday_labels[] = array_shift($wday_labels);
+      $page['chronology_date'][CDAY]=$day;
+      $query = '
+  SELECT id, file,representative_ext,path,width,height,rotation, '.pwg_db_get_dayofweek($this->date_field).'-1 as dow';
+      $query.= $this->inner_sql;
+      $query.= $this->get_date_where();
+      $query.= '
+    ORDER BY '.DB_RANDOM_FUNCTION.'()
+    LIMIT 1';
+      unset ( $page['chronology_date'][CDAY] );
+
+      $row = pwg_db_fetch_assoc(pwg_query($query));
+      $derivative = new DerivativeImage(IMG_SQUARE, new SrcImage($row));
+      $items[$day]['derivative'] = $derivative;
+      $items[$day]['file'] = $row['file'];
+      $items[$day]['dow'] = $row['dow'];
     }
 
-    list($cell_width, $cell_height) = ImageStdParams::get_by_type(IMG_SQUARE)->sizing->ideal_size;
-    if ($cell_width>120)
+    if ( !empty($items) )
     {
-      $cell_width = $cell_height = 120;
-    }
+      list($known_day) = array_keys($items);
+      $known_dow = $items[$known_day]['dow'];
+      $first_day_dow = ($known_dow-($known_day-1))%7;
+      if ($first_day_dow<0)
+      {
+        $first_day_dow += 7;
+      }
+      //first_day_dow = week day corresponding to the first day of this month
+      $wday_labels = $lang['day'];
 
-    $tpl_weeks    = array();
-    $tpl_crt_week = array();
+      if ('monday' == $conf['week_starts_on'])
+      {
+        if ($first_day_dow==0)
+        {
+          $first_day_dow = 6;
+        }
+        else
+        {
+          $first_day_dow -= 1;
+        }
 
-    //fill the empty days in the week before first day of this month
-    for ($i=0; $i<$first_day_dow; $i++)
-    {
-      $tpl_crt_week[] = array();
-    }
+        $wday_labels[] = array_shift($wday_labels);
+      }
 
-    for ( $day = 1;
-          $day <= $this->get_all_days_in_month(
-            $page['chronology_date'][CYEAR], $page['chronology_date'][CMONTH]
-              );
-          $day++)
-    {
-      $dow = ($first_day_dow + $day-1)%7;
-      if ($dow==0 and $day!=1)
+      list($cell_width, $cell_height) = ImageStdParams::get_by_type(IMG_SQUARE)->sizing->ideal_size;
+      if ($cell_width>120)
       {
-        $tpl_weeks[]    = $tpl_crt_week; // add finished week to week list
-        $tpl_crt_week   = array(); // start new week
+        $cell_width = $cell_height = 120;
       }
 
-      if ( !isset($items[$day]) )
-      {// empty day
-        $tpl_crt_week[]   =
-          array(
-              'DAY' => $day
-            );
+      $tpl_weeks    = array();
+      $tpl_crt_week = array();
+
+      //fill the empty days in the week before first day of this month
+      for ($i=0; $i<$first_day_dow; $i++)
+      {
+        $tpl_crt_week[] = array();
       }
-      else
+
+      for ( $day = 1;
+            $day <= $this->get_all_days_in_month(
+              $page['chronology_date'][CYEAR], $page['chronology_date'][CMONTH]
+                );
+            $day++)
       {
-        list($tn_width,$tn_height) = $items[$day]['derivative']->get_size();
-
-        // now need to fit the thumbnail of size tn_size within
-        // a cell of size cell_size by playing with CSS position (left/top)
-        // and the width and height of <img>.
-        $ratio_w = $tn_width/$cell_width;
-        $ratio_h = $tn_height/$cell_height;
-
-        $pos_top=$pos_left=0;
-        $css_style = '';
-
-        if ( $ratio_w>1 and $ratio_h>1)
-        {// cell completely smaller than the thumbnail so we will let the browser
-         // resize the thumbnail
-          if ($ratio_w > $ratio_h )
-          {// thumbnail ratio compared to cell -> wide format
-            $css_style = 'height:'.$cell_height.'px;';
-            $browser_img_width = $cell_height*$tn_width/$tn_height;
-            $pos_left = ($browser_img_width-$cell_width)/2;
-          }
-          else
-          {
-            $css_style = 'width:'.$cell_width.'px;';
-            $browser_img_height = $cell_width*$tn_height/$tn_width;
-            $pos_top = ($browser_img_height-$cell_height)/2;
-          }
-        }
-        else
+        $dow = ($first_day_dow + $day-1)%7;
+        if ($dow==0 and $day!=1)
         {
-          $pos_left = ($tn_width-$cell_width)/2;
-          $pos_top = ($tn_height-$cell_height)/2;
+          $tpl_weeks[]    = $tpl_crt_week; // add finished week to week list
+          $tpl_crt_week   = array(); // start new week
         }
 
-        if ( round($pos_left)!=0)
-        {
-          $css_style.='left:'.round(-$pos_left).'px;';
+        if ( !isset($items[$day]) )
+        {// empty day
+          $tpl_crt_week[]   =
+            array(
+                'DAY' => $day
+              );
         }
-        if ( round($pos_top)!=0)
+        else
         {
-          $css_style.='top:'.round(-$pos_top).'px;';
-        }
-        $url = duplicate_index_url(
+          list($tn_width,$tn_height) = $items[$day]['derivative']->get_size();
+
+          // now need to fit the thumbnail of size tn_size within
+          // a cell of size cell_size by playing with CSS position (left/top)
+          // and the width and height of <img>.
+          $ratio_w = $tn_width/$cell_width;
+          $ratio_h = $tn_height/$cell_height;
+
+          $pos_top=$pos_left=0;
+          $css_style = '';
+
+          if ( $ratio_w>1 and $ratio_h>1)
+          {// cell completely smaller than the thumbnail so we will let the browser
+           // resize the thumbnail
+            if ($ratio_w > $ratio_h )
+            {// thumbnail ratio compared to cell -> wide format
+              $css_style = 'height:'.$cell_height.'px;';
+              $browser_img_width = $cell_height*$tn_width/$tn_height;
+              $pos_left = ($browser_img_width-$cell_width)/2;
+            }
+            else
+            {
+              $css_style = 'width:'.$cell_width.'px;';
+              $browser_img_height = $cell_width*$tn_height/$tn_width;
+              $pos_top = ($browser_img_height-$cell_height)/2;
+            }
+          }
+          else
+          {
+            $pos_left = ($tn_width-$cell_width)/2;
+            $pos_top = ($tn_height-$cell_height)/2;
+          }
+
+          if ( round($pos_left)!=0)
+          {
+            $css_style.='left:'.round(-$pos_left).'px;';
+          }
+          if ( round($pos_top)!=0)
+          {
+            $css_style.='top:'.round(-$pos_top).'px;';
+          }
+          $url = duplicate_index_url(
+              array(
+                'chronology_date' =>
+                  array(
+                    $page['chronology_date'][CYEAR],
+                    $page['chronology_date'][CMONTH],
+                    $day
+                  )
+              )
+            );
+
+          $tpl_crt_week[]   =
             array(
-              'chronology_date' =>
-                array(
-                  $page['chronology_date'][CYEAR],
-                  $page['chronology_date'][CMONTH],
-                  $day
-                )
-            )
-          );
-
-        $tpl_crt_week[]   =
+                'DAY'         => $day,
+                'DOW'         => $dow,
+                'NB_ELEMENTS' => $items[$day]['nb_images'],
+                'IMAGE'       => $items[$day]['derivative']->get_url(),
+                'U_IMG_LINK'  => $url,
+                'IMAGE_STYLE' => $css_style,
+                'IMAGE_ALT'   => $items[$day]['file'],
+              );
+        }
+      }
+      //fill the empty days in the week after the last day of this month
+      while ( $dow<6 )
+      {
+        $tpl_crt_week[] = array();
+        $dow++;
+      }
+      $tpl_weeks[]    = $tpl_crt_week;
+
+      $tpl_var['month_view'] =
           array(
-              'DAY'         => $day,
-              'DOW'         => $dow,
-              'NB_ELEMENTS' => $items[$day]['nb_images'],
-              'IMAGE'       => $items[$day]['derivative']->get_url(),
-              'U_IMG_LINK'  => $url,
-              'IMAGE_STYLE' => $css_style,
-              'IMAGE_ALT'   => $items[$day]['file'],
+             'CELL_WIDTH'   => $cell_width,
+             'CELL_HEIGHT' => $cell_height,
+             'wday_labels' => $wday_labels,
+             'weeks' => $tpl_weeks,
             );
-      }
     }
-    //fill the empty days in the week after the last day of this month
-    while ( $dow<6 )
-    {
-      $tpl_crt_week[] = array();
-      $dow++;
-    }
-    $tpl_weeks[]    = $tpl_crt_week;
 
-    $tpl_var['month_view'] =
-        array(
-           'CELL_WIDTH'   => $cell_width,
-           'CELL_HEIGHT' => $cell_height,
-           'wday_labels' => $wday_labels,
-           'weeks' => $tpl_weeks,
-          );
+    return true;
   }
-
-  return true;
 }
 
-}
 ?>
\ No newline at end of file
diff --git a/include/calendar_weekly.class.php b/include/calendar_weekly.class.php
index 0bd133284..9072dc82d 100644
--- a/include/calendar_weekly.class.php
+++ b/include/calendar_weekly.class.php
@@ -21,21 +21,28 @@
 // | USA.                                                                  |
 // +-----------------------------------------------------------------------+
 
+/**
+ * @package functions\calendar
+ */
+
 include_once(PHPWG_ROOT_PATH.'include/calendar_base.class.php');
 
-define ('CYEAR', 0);
-define ('CWEEK', 1);
-define ('CDAY',  2);
+/** level of year view */
+define('CYEAR', 0);
+/** level of week view */
+define('CWEEK', 1);
+/** level of day view */
+define('CDAY',  2);
+
 
 /**
  * Weekly calendar style (composed of years/week in years and days in week)
  */
 class Calendar extends CalendarBase
 {
-
   /**
    * Initialize the calendar
-   * @param string inner_sql used for queries (INNER JOIN or normal)
+   * @param string $inner_sql
    */
   function initialize($inner_sql)
   {
@@ -72,67 +79,66 @@ class Calendar extends CalendarBase
     }
   }
 
-/**
- * Generate navigation bars for category page
- * @return boolean false to indicate that thumbnails where not included here
- */
-function generate_category_content()
-{
-  global $conf, $page;
-
-  if ( count($page['chronology_date'])==0 )
-  {
-    $this->build_nav_bar(CYEAR); // years
-  }
-  if ( count($page['chronology_date'])==1 )
-  {
-    $this->build_nav_bar(CWEEK, array()); // week nav bar 1-53
-  }
-  if ( count($page['chronology_date'])==2 )
+  /**
+   * Generate navigation bars for category page.
+   *
+   * @return boolean false indicates that thumbnails where not included
+   */
+  function generate_category_content()
   {
-    $this->build_nav_bar(CDAY); // days nav bar Mon-Sun
-  }
-  $this->build_next_prev();
-  return false;
-}
-
+    global $conf, $page;
 
-/**
- * Returns a sql where subquery for the date field
- * @param int max_levels return the where up to this level
- * (e.g. 2=only year and week in year)
- * @return string
- */
-function get_date_where($max_levels=3)
-{
-  global $page;
-  $date = $page['chronology_date'];
-  while (count($date)>$max_levels)
-  {
-    array_pop($date);
-  }
-  $res = '';
-  if (isset($date[CYEAR]) and $date[CYEAR]!=='any')
-  {
-    $y = $date[CYEAR];
-    $res = " AND $this->date_field BETWEEN '$y-01-01' AND '$y-12-31 23:59:59'";
+    if ( count($page['chronology_date'])==0 )
+    {
+      $this->build_nav_bar(CYEAR); // years
+    }
+    if ( count($page['chronology_date'])==1 )
+    {
+      $this->build_nav_bar(CWEEK, array()); // week nav bar 1-53
+    }
+    if ( count($page['chronology_date'])==2 )
+    {
+      $this->build_nav_bar(CDAY); // days nav bar Mon-Sun
+    }
+    $this->build_next_prev();
+    return false;
   }
 
-  if (isset($date[CWEEK]) and $date[CWEEK]!=='any')
-  {
-    $res .= ' AND '.$this->calendar_levels[CWEEK]['sql'].'='.$date[CWEEK];
-  }
-  if (isset($date[CDAY]) and $date[CDAY]!=='any')
-  {
-    $res .= ' AND '.$this->calendar_levels[CDAY]['sql'].'='.$date[CDAY];
-  }
-  if (empty($res))
+  /**
+   * Returns a sql WHERE subquery for the date field.
+   *
+   * @param int $max_levels (e.g. 2=only year and month)
+   * @return string
+   */
+  function get_date_where($max_levels=3)
   {
-    $res = ' AND '.$this->date_field.' IS NOT NULL';
-  }
-  return $res;
-}
+    global $page;
+    $date = $page['chronology_date'];
+    while (count($date)>$max_levels)
+    {
+      array_pop($date);
+    }
+    $res = '';
+    if (isset($date[CYEAR]) and $date[CYEAR]!=='any')
+    {
+      $y = $date[CYEAR];
+      $res = " AND $this->date_field BETWEEN '$y-01-01' AND '$y-12-31 23:59:59'";
+    }
 
+    if (isset($date[CWEEK]) and $date[CWEEK]!=='any')
+    {
+      $res .= ' AND '.$this->calendar_levels[CWEEK]['sql'].'='.$date[CWEEK];
+    }
+    if (isset($date[CDAY]) and $date[CDAY]!=='any')
+    {
+      $res .= ' AND '.$this->calendar_levels[CDAY]['sql'].'='.$date[CDAY];
+    }
+    if (empty($res))
+    {
+      $res = ' AND '.$this->date_field.' IS NOT NULL';
+    }
+    return $res;
+  }
 }
 
-?>
+?>
\ No newline at end of file
diff --git a/include/functions.inc.php b/include/functions.inc.php
index 2f0b37c69..40f8810e5 100644
--- a/include/functions.inc.php
+++ b/include/functions.inc.php
@@ -935,7 +935,7 @@ function original_to_representative($path, $representative_ext)
  * get the full path of an image
  *
  * @param array $element_info element information from db (at least 'path')
- * @return strinf
+ * @return string
  */
 function get_element_path($element_info)
 {
diff --git a/include/functions_calendar.inc.php b/include/functions_calendar.inc.php
index b8ad3d0fa..09e9942de 100644
--- a/include/functions_calendar.inc.php
+++ b/include/functions_calendar.inc.php
@@ -21,9 +21,19 @@
 // | USA.                                                                  |
 // +-----------------------------------------------------------------------+
 
+/**
+ * @package functions\calendar
+ */
+
+/** URL keyword for list view */
 define('CAL_VIEW_LIST',     'list');
+/** URL keyword for calendar view */
 define('CAL_VIEW_CALENDAR', 'calendar');
 
+
+/**
+ * Initialize _$page_ and _$template_ vars for calendar view.
+ */
 function initialize_calendar()
 {
   global $page, $conf, $user, $template, $filter;
@@ -124,7 +134,8 @@ WHERE id IN (' . implode(',',$page['items']) .')';
   }
   $cal_style = $page['chronology_style'];
   include(PHPWG_ROOT_PATH.'include/'. $styles[$cal_style]['include']);
-  $calendar = new Calendar();
+  // TODO : class name overlap, rename them in CalendarMonth and CalendarWeek
+  $calendar = new Calendar(); 
 
   // Retrieve view
 
@@ -289,4 +300,5 @@ WHERE id IN (' . implode(',',$page['items']) .')';
   }
   pwg_debug('end initialize_calendar');
 }
+
 ?>
\ No newline at end of file