diff --git a/README.txt b/README.txt index 33037e2..e2228f2 100644 --- a/README.txt +++ b/README.txt @@ -9,7 +9,6 @@ https://github.com/VeriteCo/TimelineJS 3. Place Timeline JS libraries into sites/all/libraries/timeline - USAGE ===== @@ -20,12 +19,16 @@ fields which correspond to display elements on the timeline. When creating a TimelineJS view, you will need to map the following display elements: - * headline (for example, node title) [REQUIRED] - * bodytext [REQUIRED] - * media asset (image and link fields are supported out of the box) [REQUIRED] - * date element (post date, changed date, date_api fields supported out of the box) [REQUIRED] - * media caption (not required) - * media credit (not required) + + * Headline (required) - Plain text; a high level summary. + * Body text - Plain text; a paragraph or two of optional details. + * Start and End Date - Required start and optional end of an event; can be a + date field or timestamp. + * Media URL - Drupal core image fields and link fields are supported; must + contain a raw URL to an image or video. + * Media Credit - Byline naming the author or attributing the source. + * Media Caption - Brief explanation of the media content. + * Tag - Content tagging; maximum of 6 tags. Once a content type has the necessary fields, you can create your TimelineJS view using the Views interface. @@ -56,4 +59,4 @@ To see the TimelineJS display, access the block or page you just created. MAINTAINERS =========== * Juha Niemi -* Olli Erinko \ No newline at end of file +* Olli Erinko diff --git a/plugins/date_sources/date_field.inc b/plugins/date_sources/date_field.inc index 435a093..f23073c 100644 --- a/plugins/date_sources/date_field.inc +++ b/plugins/date_sources/date_field.inc @@ -12,14 +12,14 @@ $plugin = array( ); /** - * Converts different expected date formats to one global date format to be used in TimelineJS. - * Respects Drupals TZ handling. + * Converts date field formats, forces TimelineJS to ignore browser timezone. * - * @return - * date in defined output. + * Converts different expected date formats to one global date format to be used + * in TimelineJS. Uses Drupal's TZ, not field TZ. Adds Z to ISODate to force + * TimelineJS to ignore browser timezone. * - * Adds Z to ISODate to force TimelineJS to *not* use browser timezone. - * Does not use field timezone. Uses drupals global tz instead. + * @return string + * Formatted date. */ function views_timelinejs_date_source_date_field_conversion($date, $output_format, $options = array()) { $input_format = $options['field']['date_format']; @@ -33,17 +33,20 @@ function views_timelinejs_date_source_date_field_conversion($date, $output_forma $ret['value2'] = views_timelinejs_convert_to_iso($date['value2'], $input_format, $timezone, $db_timezone); } return $ret; + case 'gregorian': $ret['value'] = views_timelinejs_convert_to_gregorian($date['value'], $input_format, $timezone, $db_timezone); if (isset($date['value2'])) { $ret['value2'] = views_timelinejs_convert_to_gregorian($date['value2'], $input_format, $timezone, $db_timezone); } return $ret; + case 'timestamp': $ret['value'] = views_timelinejs_convert_to_timestamp($date['value'], $input_format, $timezone, $db_timezone); if (isset($date['value2'])) { $ret['value2'] = views_timelinejs_convert_to_timestamp($date['value2'], $input_format, $timezone, $db_timezone); } return $ret; + } } diff --git a/plugins/date_sources/date_iso_field.inc b/plugins/date_sources/date_iso_field.inc index 31d40a6..31ec42e 100644 --- a/plugins/date_sources/date_iso_field.inc +++ b/plugins/date_sources/date_iso_field.inc @@ -12,14 +12,14 @@ $plugin = array( ); /** - * Converts different expected date formats to one global date format to be used in TimelineJS. - * Respects Drupals TZ handling. + * Converts ISO date field formats, forces TimelineJS to ignore browser TZ. * - * @return - * date in defined output. + * Converts different expected date formats to one global date format to be used + * in TimelineJS. Uses Drupal's TZ, not field TZ. Adds Z to ISODate to force + * TimelineJS to ignore browser timezone. * - * Adds Z to ISODate to force TimelineJS to *not* use browser timezone. - * Does not use field timezone. Uses drupals global tz instead. + * @return string + * Formatted date. */ function views_timelinejs_date_iso_source_date_field_conversion($date, $output_format, $options = array()) { $input_format = $options['field']['date_format']; @@ -33,17 +33,20 @@ function views_timelinejs_date_iso_source_date_field_conversion($date, $output_f $ret['value2'] = views_timelinejs_convert_to_iso($date['value2'], $input_format, $timezone, $db_timezone); } return $ret; + case 'gregorian': $ret['value'] = views_timelinejs_convert_to_gregorian($date['value'], $input_format, $timezone, $db_timezone); if (isset($date['value2'])) { $ret['value2'] = views_timelinejs_convert_to_gregorian($date['value2'], $input_format, $timezone, $db_timezone); } return $ret; + case 'timestamp': $ret['value'] = views_timelinejs_convert_to_timestamp($date['value'], $input_format, $timezone, $db_timezone); if (isset($date['value2'])) { $ret['value2'] = views_timelinejs_convert_to_timestamp($date['value2'], $input_format, $timezone, $db_timezone); } return $ret; + } } diff --git a/plugins/date_sources/date_stamp_field.inc b/plugins/date_sources/date_stamp_field.inc index 9abf587..a63e1ed 100644 --- a/plugins/date_sources/date_stamp_field.inc +++ b/plugins/date_sources/date_stamp_field.inc @@ -12,14 +12,14 @@ $plugin = array( ); /** - * Converts different expected date formats to one global date format to be used in TimelineJS. - * Respects Drupals TZ handling. + * Converts date stamp field formats, forces TimelineJS to ignore browser TZ. * - * @return - * date in defined output. + * Converts different expected date formats to one global date format to be used + * in TimelineJS. Uses Drupal's TZ, not field TZ. Adds Z to ISODate to force + * TimelineJS to ignore browser timezone. * - * Adds Z to ISODate to force TimelineJS to *not* use browser timezone. - * Does not use field timezone. Uses drupals global tz instead. + * @return string + * Formatted date. */ function views_timelinejs_date_stamp_source_date_field_conversion($date, $output_format, $options = array()) { $input_format = $options['field']['date_format']; @@ -33,17 +33,20 @@ function views_timelinejs_date_stamp_source_date_field_conversion($date, $output $ret['value2'] = views_timelinejs_convert_to_iso($date['value2'], $input_format, $timezone, $db_timezone); } return $ret; + case 'gregorian': $ret['value'] = views_timelinejs_convert_to_gregorian($date['value'], $input_format, $timezone, $db_timezone); if (isset($date['value2'])) { $ret['value2'] = views_timelinejs_convert_to_gregorian($date['value2'], $input_format, $timezone, $db_timezone); } return $ret; + case 'timestamp': $ret['value'] = views_timelinejs_convert_to_timestamp($date['value'], $input_format, $timezone, $db_timezone); if (isset($date['value2'])) { $ret['value2'] = views_timelinejs_convert_to_timestamp($date['value2'], $input_format, $timezone, $db_timezone); } return $ret; + } } diff --git a/plugins/date_sources/post_date.inc b/plugins/date_sources/post_date.inc index 047fa91..28808bd 100644 --- a/plugins/date_sources/post_date.inc +++ b/plugins/date_sources/post_date.inc @@ -3,6 +3,7 @@ * @file * Implementation of post_date (created, changed) as date source for TimelineJS. */ + $plugin = array( 'name' => t('Post Date'), 'callback' => 'views_timelinejs_date_source_post_date_conversion', @@ -11,14 +12,14 @@ $plugin = array( ); /** - * Converts different expected date formats to one global date format to be used in TimelineJS. - * Respects Drupals TZ handling. + * Converts post date formats, forces TimelineJS to ignore browser TZ. * - * @return - * date in defined output. + * Converts different expected date formats to one global date format to be used + * in TimelineJS. Uses Drupal's TZ, not field TZ. Adds Z to ISODate to force + * TimelineJS to ignore browser timezone. * - * Adds Z to ISODate to force TimelineJS to *not* use browser timezone. - * Does not use field timezone. Uses drupals global tz instead. + * @return string + * Formatted date. */ function views_timelinejs_date_source_post_date_conversion($date, $output_format, $options = array()) { $input_format = 'timestamp'; @@ -27,9 +28,12 @@ function views_timelinejs_date_source_post_date_conversion($date, $output_format switch ($output_format) { case 'iso8601': return views_timelinejs_convert_to_iso($date, $input_format, $timezone, $db_timezone); + case 'gregorian': return views_timelinejs_convert_to_gregorian($date, $input_format, $timezone, $db_timezone); + case 'timestamp': return views_timelinejs_convert_to_timestamp($date, $input_format, $timezone, $db_timezone); + } } diff --git a/plugins/media_sources/file_field.inc b/plugins/media_sources/file_field.inc index 3171e69..06880a5 100644 --- a/plugins/media_sources/file_field.inc +++ b/plugins/media_sources/file_field.inc @@ -1,7 +1,7 @@ 'views_timelinejs_media_source_link_field_preparation', ); +/** + * Parses link field to be passed as URL to TimelineJS. + * + * @param array $value + * Link field value. + * @param array $options + * Optional configuration; not used. + * + * @return string|boolean + * String containing full URL to file or boolean FALSE + */ function views_timelinejs_media_source_link_field_preparation($value, $options = array()) { if (is_array($value) && isset($value['url'])) { return $value['url']; diff --git a/plugins/tag_sources/taxonomy_term_reference_field.inc b/plugins/tag_sources/taxonomy_term_reference_field.inc index a0407ef..c0a676c 100644 --- a/plugins/tag_sources/taxonomy_term_reference_field.inc +++ b/plugins/tag_sources/taxonomy_term_reference_field.inc @@ -1,7 +1,7 @@ 'views_timelinejs_taxonomy_term_reference_tag', ); +/** + * Parses taxonomy term reference and returns name as tag. + * + * @param array $value + * Taxonomy term reference value. + * @param array $options + * Optional configuration; not used. + * + * @return string|boolean + * String containing tag or boolean FALSE if not found. + */ function views_timelinejs_taxonomy_term_reference_tag($value, $options = array()) { if (isset($value['tid']) && $value['tid'] != '') { $tid = $value['tid']; $term = taxonomy_term_load($tid); - return $term->name; } else { - return false; + return FALSE; } } diff --git a/plugins/tag_sources/text_field.inc b/plugins/tag_sources/text_field.inc index 4f35404..46cf749 100644 --- a/plugins/tag_sources/text_field.inc +++ b/plugins/tag_sources/text_field.inc @@ -1,7 +1,7 @@ 'views_timelinejs_text_tag', ); +/** + * Parses text fields and returns value as tag. + * + * @param array $value + * Text field value. + * @param array $options + * Optional configuration; not used. + * + * @return string|boolean + * String containing tag or boolean FALSE if not found. + */ function views_timelinejs_text_tag($value, $options = array()) { - if (isset($value) && $value != "") { + if (isset($value) && $value != '') { return $value['value']; } else { diff --git a/plugins/tag_sources/text_long_field.inc b/plugins/tag_sources/text_long_field.inc index 3403326..8187ba6 100644 --- a/plugins/tag_sources/text_long_field.inc +++ b/plugins/tag_sources/text_long_field.inc @@ -1,7 +1,7 @@ 'views_timelinejs_text_long_tag', ); +/** + * Parses long text fields and returns full value as tag. + * + * @param array $value + * Long text field value. + * @param array $options + * Optional configuration; not used. + * + * @return string|boolean + * String containing tag or boolean FALSE if not found. + */ function views_timelinejs_text_long_tag($value, $options = array()) { - if (isset($value) && $value != "") { + if (isset($value) && $value != '') { return $value['value']; } else { diff --git a/theme/views-timelinejs.tpl.php b/theme/views-timelinejs.tpl.php index 1f4ceb7..82c6756 100644 --- a/theme/views-timelinejs.tpl.php +++ b/theme/views-timelinejs.tpl.php @@ -1,8 +1,7 @@ -
-
+
diff --git a/theme/views_timelinejs.theme.inc b/theme/views_timelinejs.theme.inc index ac16e2c..40fbce7 100644 --- a/theme/views_timelinejs.theme.inc +++ b/theme/views_timelinejs.theme.inc @@ -1,28 +1,35 @@ $language->language, 'processed' => FALSE, ); - // Include inline javascript + + // Include inline javascript. drupal_add_js(array('timelineJS' => array($settings)), 'setting'); drupal_add_js(drupal_get_path('module', 'views_timelinejs') . '/js/views_timelinejs.js'); - } /** - * Theme function to add Read more link after timeline entry bodytext + * Add "read more" link after event body text. */ function theme_views_timelinejs_link_to_entity($vars) { return '

' . l($vars['link_text'], $vars['uri']) . '

'; -} \ No newline at end of file +} diff --git a/views_timelinejs.module b/views_timelinejs.module index 0d43a32..c53409a 100644 --- a/views_timelinejs.module +++ b/views_timelinejs.module @@ -1,5 +1,10 @@ 'theme/views_timelinejs.theme.inc'); @@ -26,10 +31,10 @@ function views_timelinejs_theme() { } /** - * Function to include TimelineJS libraries + * Include TimelineJS libraries. */ function views_timelinejs_load_libraries() { - // Include TimelineJS libraries (Libraries API 1.x) + // Libraries API 1.x. if ($path = libraries_get_path('timeline')) { drupal_add_css($path . '/compiled/css/timeline.css'); drupal_add_js($path . '/compiled/js/storyjs-embed.js'); @@ -40,7 +45,9 @@ function views_timelinejs_load_libraries() { } /** - * Implements hook_ctools_plugin_directory for plugin integration for date sources, image sources and timeline themes. + * Implements hook_ctools_plugin_directory(). + * + * Plugin integration for date sources, image sources and timeline themes. */ function views_timelinejs_ctools_plugin_directory($module, $plugin) { if ($module == 'views_timelinejs') { @@ -49,7 +56,7 @@ function views_timelinejs_ctools_plugin_directory($module, $plugin) { } /** - * Implements hook_ctools_plugin_type. + * Implements hook_ctools_plugin_type(). */ function views_timelinejs_ctools_plugin_type() { return array( @@ -61,7 +68,6 @@ function views_timelinejs_ctools_plugin_type() { } /** - * A helper function. * Returns the date conversion callback function name of a plugin. */ function views_timelinejs_get_callback($handler_name, $field_type, $plugin_type) { @@ -75,15 +81,36 @@ function views_timelinejs_get_callback($handler_name, $field_type, $plugin_type) } /** -* Returns the currently logged-in user's timezone. -* -* @return the name of a timezone -*/ + * Returns the currently logged-in user's timezone. + * + * @return string + * The name of the currently logged-in user's timezone. + */ function views_timelinejs_get_timezone() { global $user; - return (variable_get('configurable_timezones', 1) && $user->uid && drupal_strlen($user->timezone)) ? $user->timezone : variable_get('date_default_timezone', NULL); + if (variable_get('configurable_timezones', 1) && $user->uid && drupal_strlen($user->timezone)) { + return $user->timezone; + } + else { + return variable_get('date_default_timezone', NULL); + } } +/** + * Converts a given time and date into gregorian format with Drupal's timezone. + * + * @param string $value + * The date to be converted. + * @param string $date_format + * The format of the date. + * @param string $timezone + * The timezone of the date. + * @param string $db_timezone + * The Drupal timezone. + * + * @return string + * Gregorian formatted date. + */ function views_timelinejs_convert_to_gregorian($value, $date_format, $timezone, $db_timezone) { $timezone = new DateTimezone($timezone); $db_timezone = new DateTimezone($db_timezone); @@ -96,13 +123,28 @@ function views_timelinejs_convert_to_gregorian($value, $date_format, $timezone, break; default: - $date = new DateTime("$value", $db_timezone); + $date = new DateTime($value, $db_timezone); break; } $date->setTimezone($timezone); return $date->format('M d Y G:i:s'); } +/** + * Converts a given time and date into ISO format with Drupal's timezone. + * + * @param string $value + * The date to be converted. + * @param string $date_format + * The format of the date. + * @param string $timezone + * The timezone of the date. + * @param string $db_timezone + * The Drupal timezone. + * + * @return string + * ISO formatted date. + */ function views_timelinejs_convert_to_iso($value, $date_format, $timezone, $db_timezone) { $timezone = new DateTimezone($timezone); $db_timezone = new DateTimezone($db_timezone); @@ -115,13 +157,28 @@ function views_timelinejs_convert_to_iso($value, $date_format, $timezone, $db_ti break; default: - $date = new DateTime("$value", $db_timezone); + $date = new DateTime($value, $db_timezone); break; } $date->setTimezone($timezone); return $date->format('Y-m-d\TH:i:s\Z'); } +/** + * Converts a given time and date into timestamp with Drupal's timezone. + * + * @param string $value + * The date to be converted. + * @param string $date_format + * The format of the date. + * @param string $timezone + * The timezone of the date. + * @param string $db_timezone + * The Drupal timezone. + * + * @return string + * Timestamp. + */ function views_timelinejs_convert_to_timestamp($value, $date_format, $timezone, $db_timezone) { $timezone = new DateTimezone($timezone); $db_timezone = new DateTimezone($db_timezone); @@ -134,7 +191,7 @@ function views_timelinejs_convert_to_timestamp($value, $date_format, $timezone, break; default: - $date = new DateTime("$value", $db_timezone); + $date = new DateTime($value, $db_timezone); break; } $date->setTimezone($timezone); diff --git a/views_timelinejs_plugin_style_timelinejs.inc b/views_timelinejs_plugin_style_timelinejs.inc index 9e4ced5..c6bc42b 100644 --- a/views_timelinejs_plugin_style_timelinejs.inc +++ b/views_timelinejs_plugin_style_timelinejs.inc @@ -1,13 +1,17 @@ display->handler->get_handlers('field'); @@ -73,7 +80,7 @@ class views_timelinejs_plugin_style_timelinejs extends views_plugin_style { } // Check if field is a supported text source. - foreach($text_sources as $source) { + foreach ($text_sources as $source) { if (get_class($handler) == $source['handler_name']) { if ((isset($field_info['type']) && $field_info['type'] == $source['field_type']) || $field == 'title') { $text_fields[$field] = $field_names[$field]; @@ -100,7 +107,7 @@ class views_timelinejs_plugin_style_timelinejs extends views_plugin_style { } } - /** TIMELINE GENERAL CONFIGURATION **/ + // Timeline general configuration. $form['timeline_config'] = array( '#type' => 'fieldset', '#title' => t('General configuration'), @@ -152,6 +159,7 @@ class views_timelinejs_plugin_style_timelinejs extends views_plugin_style { '#default_value' => $this->options['timeline_config']['start_at_end'], ); + // Field mapping. $form['timeline_fields'] = array( '#type' => 'fieldset', '#title' => t('Field mappings'), @@ -213,7 +221,7 @@ class views_timelinejs_plugin_style_timelinejs extends views_plugin_style { } /** - * Render the display in this style. + * Render the display. */ function render() { $view = $this->view; @@ -380,7 +388,17 @@ class views_timelinejs_plugin_style_timelinejs extends views_plugin_style { } } - function getDefinedUsage($type) { + /** + * Helper function to determine alias, handler, and fieldname of a given type. + * + * @param string $type + * The type to be parsed. + * + * @return array|boolean + * An array containing the keys/values for: alias, handler, fieldname, + * field_type, date_format, and tz_handling. + */ + protected function getDefinedUsage($type) { $view = $this->view; $fieldname = ''; if ($fields = $view->style_options['timeline_fields']) { @@ -399,9 +417,9 @@ class views_timelinejs_plugin_style_timelinejs extends views_plugin_style { ); } if (!empty($view->field[$fieldname]->field_info)) { - $field_information['field_type'] = $view->field[$fieldname]->field_info['type']; - $field_information['date_format'] = $field_information['field_type']; - $field_information['tz_handling'] = 'site'; + $field_information['field_type'] = $view->field[$fieldname]->field_info['type']; + $field_information['date_format'] = $field_information['field_type']; + $field_information['tz_handling'] = 'site'; } if (!empty($field_information)) {