- +
+
' . $string . '
'; } /** @@ -144,12 +146,14 @@ public function hookDefineAcl($args) $acl->addResource('NeatlineTime_Timelines'); // All everyone access to browse, show, and items. - $acl->allow(null, 'NeatlineTime_Timelines', array('show', 'browse', 'items')); - - $acl->allow('researcher', 'NeatlineTime_Timelines', 'showNotPublic'); - $acl->allow('contributor', 'NeatlineTime_Timelines', array('add', 'editSelf', 'querySelf', 'itemsSelf', 'deleteSelf', 'showNotPublic')); - $acl->allow(array('super', 'admin', 'contributor', 'researcher'), 'NeatlineTime_Timelines', array('edit', 'query', 'items', 'delete'), new Omeka_Acl_Assert_Ownership); - + $acl->allow(null, 'NeatlineTime_Timelines', + array('show', 'browse', 'items')); + $acl->allow('researcher', 'NeatlineTime_Timelines', + 'showNotPublic'); + $acl->allow('contributor', 'NeatlineTime_Timelines', + array('add', 'editSelf', 'querySelf', 'itemsSelf', 'deleteSelf', 'showNotPublic')); + $acl->allow(array('super', 'admin', 'contributor', 'researcher'), 'NeatlineTime_Timelines', + array('edit', 'query', 'items', 'delete'), new Omeka_Acl_Assert_Ownership); } /** @@ -164,102 +168,114 @@ public function hookDefineRoutes($args) new Zend_Controller_Router_Route( 'neatline-time/timelines/:action/:id', array( - 'module' => 'neatline-time', - 'controller' => 'timelines' - ), - array('id' => '\d+') - ) - ); + 'module' => 'neatline-time', + 'controller' => 'timelines' + ), + array('id' => '\d+') + ) + ); $router->addRoute( 'timelineDefaultRoute', new Zend_Controller_Router_Route( 'neatline-time/timelines/:action', array( - 'module' => 'neatline-time', - 'controller' => 'timelines' - ) + 'module' => 'neatline-time', + 'controller' => 'timelines' ) - ); + ) + ); $router->addRoute( 'timelineRedirectRoute', new Zend_Controller_Router_Route( 'neatline-time', array( - 'module' => 'neatline-time', - 'controller' => 'timelines', - 'action' => 'browse' - ) + 'module' => 'neatline-time', + 'controller' => 'timelines', + 'action' => 'browse' ) - ); + ) + ); $router->addRoute( 'timelinePaginationRoute', new Zend_Controller_Router_Route( 'neatline-time/timelines/:page', array( - 'module' => 'neatline-time', - 'controller' => 'timelines', - 'action' => 'browse', - 'page' => '1' - ), - array('page' => '\d+') - ) - ); - + 'module' => 'neatline-time', + 'controller' => 'timelines', + 'action' => 'browse', + 'page' => '1' + ), + array('page' => '\d+') + ) + ); } /** - * Timeline admin_append_to_plugin_uninstall_message hook + * Shows plugin configuration page. + * + * @return void */ - public function hookAdminAppendToPluginUninstallMessage() + public function hookConfigForm($args) { - $string = __('Warning: Uninstalling the Neatline Time plugin - will remove all custom Timeline records.'); - - echo ''.$string.'
'; - + $defaults = get_option('neatline_time_defaults'); + $defaults = json_decode($defaults, true); + $defaults = empty($defaults) + // Set default parameters. + ? $this->_options['neatline_time_defaults'] + // Add possible new default parameters to avoid a notice. + : array_merge($this->_options['neatline_time_defaults'], $defaults); + + $view = $args['view']; + echo $view->partial( + 'plugins/neatline-time-config-form.php', + array( + 'defaults' => $defaults, + )); } /** - * Filter the items_browse_sql to return only items that have a non-empty - * value for the DC:Date field, when using the neatlinetime-json context. - * Uses the ItemSearch model (models/ItemSearch.php) to add the check for - * a non-empty DC:Date. + * Processes the configuration form. * - * @param Omeka_Db_Select $select + * @return void */ - public function hookItemBrowseSql() + public function hookConfig($args) { - - $context = Zend_Controller_Action_HelperBroker::getStaticHelper('ContextSwitch')->getCurrentContext(); - if ($context == 'neatlinetime-json') { - $search = new ItemSearch($select); - $newParams[0]['element_id'] = neatlinetime_get_option('item_date'); - $newParams[0]['type'] = 'is not empty'; - $search->advanced($newParams); + $post = $args['post']; + foreach ($this->_options as $optionKey => $optionValue) { + if (isset($post[$optionKey])) { + if (is_array($optionValue)) { + $post[$optionKey] = json_encode($post[$optionKey]); + } + set_option($optionKey, $post[$optionKey]); + } } - } - /** - * Plugin configuration. - */ - public function hookConfig() + public function hookAdminHead($args) { - $options = $_POST; - unset($options['install_plugin']); - $options = serialize($options); - set_option('neatlinetime', $options); + $requestParams = Zend_Controller_Front::getInstance()->getRequest()->getParams(); + $module = isset($requestParams['module']) ? $requestParams['module'] : 'default'; + $controller = isset($requestParams['controller']) ? $requestParams['controller'] : 'index'; + $action = isset($requestParams['action']) ? $requestParams['action'] : 'index'; + if ($module != 'neatline-time' || $controller != 'timelines' || $action != 'show') { + return; + } + $this->_head($args); } - /** - * Plugin configuration form. - */ - public function hookConfigForm() + public function hookPublicHead($args) { - include 'config_form.php'; + $requestParams = Zend_Controller_Front::getInstance()->getRequest()->getParams(); + $module = isset($requestParams['module']) ? $requestParams['module'] : 'default'; + $controller = isset($requestParams['controller']) ? $requestParams['controller'] : 'index'; + $action = isset($requestParams['action']) ? $requestParams['action'] : 'index'; + if ($module != 'neatline-time' || $controller != 'timelines' || $action != 'show') { + return; + } + $this->_head($args); } /** @@ -268,9 +284,58 @@ public function hookConfigForm() public function hookExhibitBuilderPageHead($args) { if (array_key_exists('neatline-time', $args['layouts'])) { - queue_timeline_assets(); + $this->_head($args); } } + + /** + * Load all assets. + * + * Replace queue_timeline_assets() + * + * @return void + */ + private function _head($args) + { + $library = get_option('neatline_time_library'); + if ($library == 'knightlab') { + queue_css_url('//cdn.knightlab.com/libs/timeline3/latest/css/timeline.css'); + queue_js_url('//cdn.knightlab.com/libs/timeline3/latest/js/timeline.js'); + return; + } + + // Default simile library. + queue_css_file('neatlinetime-timeline'); + + queue_js_file('neatline-time-scripts'); + + $internalAssets = get_option('neatline_time_internal_assets'); + if ($internalAssets) { + $useInternalJs = true; + } else { + // Check useInternalJavascripts in config.ini. + $config = Zend_Registry::get('bootstrap')->getResource('Config'); + $useInternalJs = isset($config->theme->useInternalJavascripts) + ? (bool) $config->theme->useInternalJavascripts + : false; + $useInternalJs = isset($config->theme->useInternalAssets) + ? (bool) $config->theme->useInternalAssets + : $useInternalJs; + } + + if ($useInternalJs) { + $timelineVariables = 'Timeline_ajax_url="' . src('simile-ajax-api.js', 'javascripts/simile/ajax-api') . '"; + Timeline_urlPrefix="' . dirname(src('timeline-api.js', 'javascripts/simile/timeline-api')) . '/"; + Timeline_parameters="bundle=true";'; + queue_js_string($timelineVariables); + queue_js_file('timeline-api', 'javascripts/simile/timeline-api'); + queue_js_string('SimileAjax.History.enabled = false; // window.jQuery = SimileAjax.jQuery;'); + } else { + queue_js_url('//api.simile-widgets.org/timeline/2.3.1/timeline-api.js?bundle=true'); + queue_js_string('SimileAjax.History.enabled = false; window.jQuery = SimileAjax.jQuery;'); + } + } + /** * Timeline admin_navigation_main filter. * @@ -281,7 +346,6 @@ public function hookExhibitBuilderPageHead($args) */ public function filterAdminNavigationMain($nav) { - $nav[] = array( 'label' => __('Neatline Time'), 'uri' => url('neatline-time'), @@ -289,7 +353,6 @@ public function filterAdminNavigationMain($nav) 'privilege' => 'browse' ); return $nav; - } /** @@ -302,13 +365,35 @@ public function filterAdminNavigationMain($nav) */ public function filterPublicNavigationMain($nav) { - $nav[] = array( 'label' => __('Neatline Time'), 'uri' => url('neatline-time') ); return $nav; + } + public function filterPublicNavigationItems($navArray) + { + $linkToNav = get_option('neatline_time_link_to_nav'); + switch ($linkToNav) { + case 'browse': + $navArray['Browse Timeline'] = array( + 'label' => __('Browse Timelines'), + 'uri' => url('neatline-time'), + ); + break; + case 'main': + $linkToNavMain = get_option('neatline_time_link_to_nav_main'); + if ($linkToNavMain) { + $navArray['Browse Timeline'] = array( + 'label' => __('Browse Timeline'), + 'uri' => url('neatline-time/timelines/show/' . $linkToNavMain), + ); + } + break; + default: + } + return $navArray; } /** @@ -316,14 +401,11 @@ public function filterPublicNavigationMain($nav) */ public function filterResponseContexts($contexts) { - $contexts['neatlinetime-json'] = array( 'suffix' => 'neatlinetime-json', - 'headers' => array('Content-Type' => 'text/javascript') + 'headers' => array('Content-Type' => 'application/json') ); - return $contexts; - } /** @@ -332,13 +414,10 @@ public function filterResponseContexts($contexts) */ public function filterActionContexts($contexts, $args) { - if ($args['controller'] instanceof NeatlineTime_TimelinesController) { $contexts['items'][''] = 'neatlinetime-json'; } - return $contexts; - } /** @@ -356,18 +435,39 @@ public function filterExhibitLayouts($layouts) return $layouts; } - protected function setDefaultOptions() + /** + * Filter items browse params. + * + * @param array $params + * @return array + */ + public function filterItemsBrowseParams($params) { - $options = array(); - $fields = array('Title', 'Description', 'Date'); - - foreach ($fields as $field) { - $key = 'item_'.strtolower($field); - $element = $this->_db->getTable('Element')->findByElementSetNameAndElementName("Dublin Core", "$field"); - $options[$key] = $element->id; + // Filter the items to return only items that have a non-empty value for + // the DC:Date or the specified field when using the neatlinetime-json + // context. + $context = Zend_Controller_Action_HelperBroker::getStaticHelper('ContextSwitch')->getCurrentContext(); + if ($context != 'neatlinetime-json') { + return $params; } - - $options = serialize($options); - set_option('neatlinetime', $options); + // Check if this is a request (don't filter if this a background process). + $request = Zend_Controller_Front::getInstance()->getRequest(); + if (empty($request)) { + return $params; + } + $id = (integer) $request->getParam('id'); + if (empty($id)) { + return $params; + } + $timeline = $this->_db->getTable('NeatlineTime_Timeline')->find($id); + if (empty($timeline)) { + return $params; + } + $params['advanced'][] = array( + 'joiner' => 'and', + 'element_id' => $timeline->getProperty('item_date'), + 'type' =>'is not empty', + ); + return $params; } } diff --git a/README.md b/README.md index 97b39c1..26f6372 100644 --- a/README.md +++ b/README.md @@ -1,49 +1,79 @@ -# NeatlineTime plugin for Omeka +NeatlineTime (plugin for Omeka) +=============================== -[](http://travis-ci.org/scholarslab/NeatlineTime) +[](https://travis-ci.org/scholarslab/NeatlineTime) -The NeatlineTime plugin, by the [Scholars' Lab][scholarslab] at the University of Virginia Library, allows you to create timelines for the [Omeka][omeka] publishing platform. It uses the [SIMILE Timeline plugin][simile-timeline]. +The NeatlineTime plugin, by the [Scholars' Lab][scholarslab] at the University +of Virginia Library, allows you to create timelines for the [Omeka][omeka] +publishing platform. It uses the [SIMILE Timeline plugin][simile-timeline] or +the [Knightlab timeline]. -## Installation +This plugin is upgradable to [Omeka S] via the plugin [Upgrade to Omeka S], that +installs the module [Timeline for Omeka S]. -1. Upload the 'NeatlineTime' plugin directory to your Omeka installation's 'plugins' directory. See [Installing a Plugin][installing-a-plugin]. + +Installation +------------ + +1. Upload the 'NeatlineTime' plugin directory to your Omeka installation's +'plugins' directory. See [Installing a Plugin][installing-a-plugin]. 2. Activate the plugin from the Admin → Settings → Plugins page. 3. Configure the plugin to choose which fields you want the plugin to use on - the timeline. + the timeline by default. - * Item Date: The field you would like to use for item dates on the - timeline. The default is DC:Date. * Item Title: The field you would like displayed for the item's title in its information bubble. The default is DC:Title * Item Description: The field you would like displayed for the item's description in its information bubble. The default is DC:Description. + * Item Date: The field you would like to use for item dates on the + timeline. The default is DC:Date. + * Render Year: Date entered as a single number, like "1066", can be skipped, + plotted as a single event or marked as a full year. + * Center Date: The date that is displayed by the viewer when loaded. It can + be any date with the format (YYYY-MM-DD). An empty string means now, a + "0000-00-00" the earliest date and "9999-99-99" the latest date. + +All these parameters can be customized for each timeline. + +Note: If Omeka is https, if external assets are used, and if the Simile library +is used, the library will not load on recent browsers, because the online +library contains an url with unsecure http. In that case, you need to set the +option "Use Internal library for Simile". -## Usage +Usage +----- -Once installed, NeatlineTime will add a tab to the Omeka admin panel. From here, you can browse existing timelines, and add, edit, and delete timelines. +Once installed, NeatlineTime will add a tab to the Omeka admin panel. From here, +you can browse existing timelines, and add, edit, and delete timelines. -Uninstalling the plugin will only remove timelines added to your Omeka archive, not any items displayed on those timelines. +Uninstalling the plugin will only remove timelines added to your Omeka archive, +not any items displayed on those timelines. ### Add a Timeline Creating a timeline is a two-step process: -1. From the admin → NeatlineTime page, click the "Add New Timeline" button to begin creating a timeline. +1. From the admin → NeatlineTime page, click the "Add New Timeline" button to + begin creating a timeline.  -2. Give your timeline a title and description, and choose whether you wish to make the timeline public and featured. Save your changes. +2. Give your timeline a title and description, and choose whether you wish to + make the timeline public and featured. Save your changes.  -3. To choose which items appear on your timeline, click the "Edit Query" link beside your existing timeline. +3. To choose which items appear on your timeline, click the "Edit Query" link + beside your existing timeline.  -4. This will take you to a form similar to Omeka's advanced search form. From here, you can perform a search for any items in your archive, and if those items contain a valid date in their Dublin Core:Date field, they will be displayed on the timeline. +4. This will take you to a form similar to Omeka's advanced search form. From + here, you can perform a search for any items in your archive, and if those + items contain a valid date in their Dublin Core:Date field, they will be + displayed on the timeline.  @@ -51,9 +81,10 @@ Creating a timeline is a two-step process:  -#### Dates for Items +### Dates for Items -NeatlineTime will attempt to convert the value for a date string into an ISO-8601 date format. Some example date values you can use: +NeatlineTime will attempt to convert the value for a date string into an +ISO-8601 date format. Some example date values you can use: * January 1, 2012 * 2012-01-01 @@ -64,8 +95,6 @@ To denote spans of time, separate the start and end date with a '/': * January 1, 2012/February 1, 2012 -NeatlineTime doesn't accept just years (*1066*, for example) because it's not clear what that means. Should that translate to the range *January 1, 1066/December 31, 1066*? Should it be *January 1, 1066*? *June 31, 1066*? Instead of us picking an arbitrary point in the year or marking the entire year, we simply ask that you be more specific. - NeatlineTime handles dates with years shorter than 4 digits. For these you'll need to pad the years with enough zeros to make them have four digits. For example, `476` should be written `0476`. @@ -81,41 +110,138 @@ So here are some more examples of dates. * -0002-01-01 * -2013-01-01 +When a date is a single number, like "1066", a parameter in the config page +allows to choose its rendering: + + * skip the record (default) + * 1st January + * 1st July + * full year (range period) + +This parameter applies with a range of dates too, for example "1939/1945". + +In all cases, it's recommended to follow the standard [ISO 8601] as much as +possible and to be as specific as possible. + +### Parameters of the viewer + +Some parameters of the viewer may be customized for each timeline. Currently, +only the `CenterDate` and the `bandInfos` are managed for the Simile timeline. +The default is automatically included when the field is empty. + +```javascript +{ +bandInfos: + [ + { + width: "80%", + intervalUnit: Timeline.DateTime.MONTH, + intervalPixels: 100, + zoomIndex: 10, + zoomSteps: new Array( + {pixelsPerInterval: 280, unit: Timeline.DateTime.HOUR}, + {pixelsPerInterval: 140, unit: Timeline.DateTime.HOUR}, + {pixelsPerInterval: 70, unit: Timeline.DateTime.HOUR}, + {pixelsPerInterval: 35, unit: Timeline.DateTime.HOUR}, + {pixelsPerInterval: 400, unit: Timeline.DateTime.DAY}, + {pixelsPerInterval: 200, unit: Timeline.DateTime.DAY}, + {pixelsPerInterval: 100, unit: Timeline.DateTime.DAY}, + {pixelsPerInterval: 50, unit: Timeline.DateTime.DAY}, + {pixelsPerInterval: 400, unit: Timeline.DateTime.MONTH}, + {pixelsPerInterval: 200, unit: Timeline.DateTime.MONTH}, + {pixelsPerInterval: 100, unit: Timeline.DateTime.MONTH} // DEFAULT zoomIndex + ) + }, + { + overview: true, + width: "20%", + intervalUnit: Timeline.DateTime.YEAR, + intervalPixels: 200 + } + ] +} +``` + + ### Browsing timelines -You can browse existing timelines by clicking on the "Browse Timelines" from your public theme, or the "NeatlineTime" tab in the admin panel. +You can browse existing timelines by clicking on the "Browse Timelines" from +your public theme, or the "NeatlineTime" tab in the admin panel. ### Viewing specific timelines -You can always see your timeline by click the title of the timeline in the admin. The URL for your timelines will be 'neatline-time/timelines/show/[id]', where [id] is the ID number for your timeline. +You can always see your timeline by click the title of the timeline in the +admin. The URL for your timelines will be 'neatline-time/timelines/show/[id]', +where [id] is the ID number for your timeline.  ### Modifying theme templates for Neatline Time -Neatline Time contains theme templates that control how its various pages are displayed in your public theme. As with other Omeka plugins, you can override these using the instructions on the [Theming Plugin Pages][themeing-plugin-pages] codex page. +Neatline Time contains theme templates that control how its various pages are +displayed in your public theme. As with other Omeka plugins, you can override +these using the instructions on the [Theming Plugin Pages][themeing-plugin-pages] +codex page. The template files available in NeatlineTime include: * timelines/browse.php - The template for browsing existing timelines. * timelines/show.php - The template for showing a specific timeline. -## Contributing to the Project +### Modifying the viewer + +The template file used to load the timeline is `views/shared/javascripts/neatline-time-script.js`. + +You can copy it in your themes/my_theme/javascripts folder to customize it. The +same for the default css. See the main [wiki][simile-timeline], an [example of use] +with Neatline, and the [examples] of customization on the wiki. + + +Contributing to the Project +--------------------------- ### Feedback -We rely on the [Github issues tracker][issues] for feedback on issues and improvements. +We rely on the [Github issues tracker][issues] for feedback on issues and +improvements. ### Patches/Pull Requests * Fork the project. * Make your feature addition or bug fix. -* Add tests for it, and make sure all the tests pass. This is important so we don't unknowingly break your changes in a future release. If you're fixing a bug, it helps us to verify that your bug does in fact exist. Both NeatlineTime and Omeka use [PHPUnit][phpunit] to ensure the quality of the software. +* Add tests for it, and make sure all the tests pass. This is important so we + don't unknowingly break your changes in a future release. If you're fixing a + bug, it helps us to verify that your bug does in fact exist. Both NeatlineTime + and Omeka use [PHPUnit][phpunit] to ensure the quality of the software. * Commit your changes to your own fork. -* Send us a pull request, with a clear explanation of the changes. Bonus - points for topic branches. +* Send us a pull request, with a clear explanation of the changes. Bonus points + for topic branches. -## Credits + +Warning +------- + +Use it at your own risk. + +It’s always recommended to backup your files and your databases and to check +your archives regularly so you can roll back if needed. + + +Troubleshooting +--------------- + +See online issues on the plugin [issues] page on GitHub. + + +License +------- + +This plugin is published under [Apache licence v2]. +See [LICENSE][license] for more information. + + +Credits +------- ### Translations @@ -124,15 +250,32 @@ We rely on the [Github issues tracker][issues] for feedback on issues and improv * Oguljan Reyimbaeva (Russian) * Katina Rogers (French) -## Copyright +### Contact + +* Scholar's Lab (see [ScholarLab] on GitHub) +* Daniel Berthereau (see [Daniel-KM] on GitHub) + +### Copyright + +* Copyright (c) 2010–2012 The Board and Visitors of the University of Virginia. +* Copyright Daniel Berthereau, 2016-2018 -Copyright (c) 2010–2012 The Board and Visitors of the University of Virginia. See [LICENSE][license] for more information. -[scholarslab]: http://scholarslab.org/ +[scholarslab]: http://scholarslab.org [omeka]: http://omeka.org [simile-timeline]: http://www.simile-widgets.org/wiki/Timeline +[Knightlab timeline]: https://timeline.knightlab.com +[Omeka S]: https://omeka.org/s +[Upgrade to Omeka S]: https://github.com/Daniel-KM/Omeka-plugin-UpgradeToOmekaS +[Timeline for Omeka S]: https://github.com/Daniel-KM/Omeka-S-module-Timeline [installing-a-plugin]: http://omeka.org/codex/Installing_a_Plugin +[example of use]: https://docs.neatline.org/working-with-the-simile-timeline-widget.html +[examples]: http://www.simile-widgets.org/timeline/examples/index.html +[Apache licence v2]: https://www.apache.org/licenses/LICENSE-2.0.html [license]: http://www.apache.org/licenses/LICENSE-2.0.html "Apache License, Version 2.0" [issues]: http://github.com/scholarslab/NeatlineTime/issues/ "Issues for Neatline Time" [phpunit]: http://www.phpunit.de/manual/current/en/ "PHP Unit" +[ISO 8601]: http://www.iso.org/iso/home/standards/iso8601.htm [themeing-plugin-pages]: http://omeka.org/codex/Theming_Plugin_Pages "Theming Plugin Pages" +[ScholarLab]: https://github.com/scholarslab "Scholar's Lab" +[Daniel-KM]: https://github.com/Daniel-KM "Daniel Berthereau" diff --git a/Rakefile b/Rakefile index 838a5d7..cd8ba52 100644 --- a/Rakefile +++ b/Rakefile @@ -5,10 +5,23 @@ require 'tempfile' require 'inifile' task :default => [ - # 'php:unit', - # 'jasmine:ci', + 'php:unit', ] +namespace :php do + desc 'Run unit tests.' + task :unit, [:filter] do |t, args| + filter_by = args[:filter] + if filter_by.nil? then + filter_params = "" + else + filter_params = " --filter #{filter_by}" + end + + sh %{cd tests/ && phpunit --configuration phpunit.xml #{filter_params}} + end +end + class PackageTask < Rake::PackageTask def package_dir_path() "#{package_dir}/#{@name}" diff --git a/config_form.php b/config_form.php deleted file mode 100644 index 190cc17..0000000 --- a/config_form.php +++ /dev/null @@ -1,36 +0,0 @@ -- -
-- -
-- -
-'timelines primary', - 'title' => __('Neatline Time | %s', strip_formatting($timelineTitle)) - ); +$head = array( + 'bodyclass' => 'timelines primary', + 'title' => __('Neatline Time | %s', strip_formatting($timelineTitle)), +); echo head($head); +echo flash(); ?>
- +
+