1
|
|
|
<?php |
2
|
|
|
|
3
|
|
|
/** |
4
|
|
|
* (c) Kitodo. Key to digital objects e.V. <[email protected]> |
5
|
|
|
* |
6
|
|
|
* This file is part of the Kitodo and TYPO3 projects. |
7
|
|
|
* |
8
|
|
|
* @license GNU General Public License version 3 or later. |
9
|
|
|
* For the full copyright and license information, please read the |
10
|
|
|
* LICENSE.txt file that was distributed with this source code. |
11
|
|
|
*/ |
12
|
|
|
|
13
|
|
|
namespace Kitodo\Dlf\Plugin; |
14
|
|
|
|
15
|
|
|
use Kitodo\Dlf\Common\Helper; |
16
|
|
|
use Kitodo\Dlf\Common\IiifManifest; |
17
|
|
|
use Ubl\Iiif\Presentation\Common\Model\Resources\ManifestInterface; |
18
|
|
|
use Ubl\Iiif\Presentation\Common\Vocabulary\Motivation; |
19
|
|
|
|
20
|
|
|
/** |
21
|
|
|
* Plugin 'Page View' for the 'dlf' extension |
22
|
|
|
* |
23
|
|
|
* @author Sebastian Meyer <[email protected]> |
24
|
|
|
* @package TYPO3 |
25
|
|
|
* @subpackage dlf |
26
|
|
|
* @access public |
27
|
|
|
*/ |
28
|
|
|
class PageView extends \Kitodo\Dlf\Common\AbstractPlugin |
29
|
|
|
{ |
30
|
|
|
public $scriptRelPath = 'Classes/Plugin/PageView.php'; |
31
|
|
|
|
32
|
|
|
/** |
33
|
|
|
* Holds the controls to add to the map |
34
|
|
|
* |
35
|
|
|
* @var array |
36
|
|
|
* @access protected |
37
|
|
|
*/ |
38
|
|
|
protected $controls = []; |
39
|
|
|
|
40
|
|
|
/** |
41
|
|
|
* Holds the current images' URLs and MIME types |
42
|
|
|
* |
43
|
|
|
* @var array |
44
|
|
|
* @access protected |
45
|
|
|
*/ |
46
|
|
|
protected $images = []; |
47
|
|
|
|
48
|
|
|
/** |
49
|
|
|
* Holds the current fulltexts' URLs |
50
|
|
|
* |
51
|
|
|
* @var array |
52
|
|
|
* @access protected |
53
|
|
|
*/ |
54
|
|
|
protected $fulltexts = []; |
55
|
|
|
|
56
|
|
|
/** |
57
|
|
|
* Holds the current AnnotationLists / AnnotationPages |
58
|
|
|
* |
59
|
|
|
* @var array |
60
|
|
|
* @access protected |
61
|
|
|
*/ |
62
|
|
|
protected $annotationContainers = []; |
63
|
|
|
|
64
|
|
|
/** |
65
|
|
|
* Adds Viewer javascript |
66
|
|
|
* |
67
|
|
|
* @access protected |
68
|
|
|
* |
69
|
|
|
* @return void |
70
|
|
|
*/ |
71
|
|
|
protected function addViewerJS() |
72
|
|
|
{ |
73
|
|
|
|
74
|
|
|
$pageRenderer = \TYPO3\CMS\Core\Utility\GeneralUtility::makeInstance(\TYPO3\CMS\Core\Page\PageRenderer::class); |
75
|
|
|
// Add OpenLayers library. |
76
|
|
|
$pageRenderer->addCssFile(\TYPO3\CMS\Core\Utility\ExtensionManagementUtility::siteRelPath($this->extKey) . 'Resources/Public/Javascript/OpenLayers/ol3.css'); |
|
|
|
|
77
|
|
|
$pageRenderer->addJsFooterFile(\TYPO3\CMS\Core\Utility\ExtensionManagementUtility::siteRelPath($this->extKey) . 'Resources/Public/Javascript/OpenLayers/glif.min.js'); |
|
|
|
|
78
|
|
|
$pageRenderer->addJsFooterFile(\TYPO3\CMS\Core\Utility\ExtensionManagementUtility::siteRelPath($this->extKey) . 'Resources/Public/Javascript/OpenLayers/ol3-dlf.js'); |
|
|
|
|
79
|
|
|
// Add viewer library. |
80
|
|
|
$pageRenderer->addJsFooterFile(\TYPO3\CMS\Core\Utility\ExtensionManagementUtility::siteRelPath($this->extKey) . 'Resources/Public/Javascript/PageView/Utility.js'); |
|
|
|
|
81
|
|
|
$pageRenderer->addJsFooterFile(\TYPO3\CMS\Core\Utility\ExtensionManagementUtility::siteRelPath($this->extKey) . 'Resources/Public/Javascript/PageView/OL3.js'); |
|
|
|
|
82
|
|
|
$pageRenderer->addJsFooterFile(\TYPO3\CMS\Core\Utility\ExtensionManagementUtility::siteRelPath($this->extKey) . 'Resources/Public/Javascript/PageView/OL3Styles.js'); |
|
|
|
|
83
|
|
|
$pageRenderer->addJsFooterFile(\TYPO3\CMS\Core\Utility\ExtensionManagementUtility::siteRelPath($this->extKey) . 'Resources/Public/Javascript/PageView/OL3Sources.js'); |
|
|
|
|
84
|
|
|
$pageRenderer->addJsFooterFile(\TYPO3\CMS\Core\Utility\ExtensionManagementUtility::siteRelPath($this->extKey) . 'Resources/Public/Javascript/PageView/AltoParser.js'); |
|
|
|
|
85
|
|
|
$pageRenderer->addJsFooterFile(\TYPO3\CMS\Core\Utility\ExtensionManagementUtility::siteRelPath($this->extKey) . 'Resources/Public/Javascript/PageView/ImageManipulationControl.js'); |
|
|
|
|
86
|
|
|
$pageRenderer->addJsFooterFile(\TYPO3\CMS\Core\Utility\ExtensionManagementUtility::siteRelPath($this->extKey) . 'Resources/Public/Javascript/PageView/FulltextControl.js'); |
|
|
|
|
87
|
|
|
if ($this->doc instanceof IiifManifest) { |
88
|
|
|
$pageRenderer->addJsFooterFile(\TYPO3\CMS\Core\Utility\ExtensionManagementUtility::siteRelPath($this->extKey) . 'Resources/Public/Javascript/PageView/AnnotationParser.js'); |
|
|
|
|
89
|
|
|
$pageRenderer->addJsFooterFile(\TYPO3\CMS\Core\Utility\ExtensionManagementUtility::siteRelPath($this->extKey) . 'Resources/Public/Javascript/PageView/AnnotationControl.js'); |
|
|
|
|
90
|
|
|
} |
91
|
|
|
$pageRenderer->addJsFooterFile(\TYPO3\CMS\Core\Utility\ExtensionManagementUtility::siteRelPath($this->extKey) . 'Resources/Public/Javascript/PageView/PageView.js'); |
|
|
|
|
92
|
|
|
// Add viewer configuration. |
93
|
|
|
$viewerConfiguration = ' |
94
|
|
|
$(document).ready(function() { |
95
|
|
|
if (dlfUtils.exists(dlfViewer)) { |
96
|
|
|
tx_dlf_viewer = new dlfViewer({ |
97
|
|
|
controls: ["' . implode('", "', $this->controls) . '"], |
98
|
|
|
div: "' . $this->conf['elementId'] . '", |
99
|
|
|
images: ' . json_encode($this->images) . ', |
100
|
|
|
fulltexts: ' . json_encode($this->fulltexts) . ', |
101
|
|
|
annotationContainers: ' . json_encode($this->annotationContainers) . ', |
102
|
|
|
useInternalProxy: ' . ($this->conf['useInternalProxy'] ? 1 : 0) . ' |
103
|
|
|
}); |
104
|
|
|
} |
105
|
|
|
}); |
106
|
|
|
'; |
107
|
|
|
$pageRenderer->addJsFooterInlineCode('kitodo-pageview-configuration', $viewerConfiguration); |
108
|
|
|
} |
109
|
|
|
|
110
|
|
|
/** |
111
|
|
|
* Adds pageview interaction (crop, magnifier and rotation) |
112
|
|
|
* |
113
|
|
|
* @access protected |
114
|
|
|
* |
115
|
|
|
* @return array Marker array |
116
|
|
|
*/ |
117
|
|
|
protected function addInteraction() |
118
|
|
|
{ |
119
|
|
|
$markerArray = []; |
120
|
|
|
if ($this->piVars['id']) { |
121
|
|
|
if ($this->conf['crop']) { |
122
|
|
|
$markerArray['###EDITBUTTON###'] = '<a href="javascript: tx_dlf_viewer.activateSelection();" title="' . $this->pi_getLL('editMode', '', true) . '">' . $this->pi_getLL('editMode', '', true) . '</a>'; |
123
|
|
|
$markerArray['###EDITREMOVE###'] = '<a href="javascript: tx_dlf_viewer.resetCropSelection();" title="' . $this->pi_getLL('editRemove', '', true) . '">' . $this->pi_getLL('editRemove', '', true) . '</a>'; |
124
|
|
|
} else { |
125
|
|
|
$markerArray['###EDITBUTTON###'] = ''; |
126
|
|
|
$markerArray['###EDITREMOVE###'] = ''; |
127
|
|
|
} |
128
|
|
|
if ($this->conf['magnifier']) { |
129
|
|
|
$markerArray['###MAGNIFIER###'] = '<a href="javascript: tx_dlf_viewer.activateMagnifier();" title="' . $this->pi_getLL('magnifier', '', true) . '">' . $this->pi_getLL('magnifier', '', true) . '</a>'; |
130
|
|
|
} else { |
131
|
|
|
$markerArray['###MAGNIFIER###'] = ''; |
132
|
|
|
} |
133
|
|
|
} |
134
|
|
|
return $markerArray; |
135
|
|
|
} |
136
|
|
|
|
137
|
|
|
/** |
138
|
|
|
* Adds form to save cropping data to basket |
139
|
|
|
* |
140
|
|
|
* @access protected |
141
|
|
|
* |
142
|
|
|
* @return array Marker array |
143
|
|
|
*/ |
144
|
|
|
protected function addBasketForm() |
145
|
|
|
{ |
146
|
|
|
$markerArray = []; |
147
|
|
|
// Add basket button |
148
|
|
|
if ($this->conf['basketButton'] && $this->conf['targetBasket'] && $this->piVars['id']) { |
149
|
|
|
$label = $this->pi_getLL('addBasket', '', true); |
150
|
|
|
$params = [ |
151
|
|
|
'id' => $this->piVars['id'], |
152
|
|
|
'addToBasket' => true |
153
|
|
|
]; |
154
|
|
|
if (empty($this->piVars['page'])) { |
155
|
|
|
$params['page'] = 1; |
156
|
|
|
} |
157
|
|
|
$basketConf = [ |
158
|
|
|
'parameter' => $this->conf['targetBasket'], |
159
|
|
|
'forceAbsoluteUrl' => !empty($this->conf['forceAbsoluteUrl']) ? 1 : 0, |
160
|
|
|
'forceAbsoluteUrl.' => ['scheme' => !empty($this->conf['forceAbsoluteUrl']) && !empty($this->conf['forceAbsoluteUrlHttps']) ? 'https' : 'http'], |
161
|
|
|
'additionalParams' => \TYPO3\CMS\Core\Utility\GeneralUtility::implodeArrayForUrl($this->prefixId, $params, '', true, false), |
162
|
|
|
'title' => $label |
163
|
|
|
]; |
164
|
|
|
$output = '<form id="addToBasketForm" action="' . $this->cObj->typoLink_URL($basketConf) . '" method="post">'; |
165
|
|
|
$output .= '<input type="hidden" name="tx_dlf[startpage]" id="startpage" value="' . $this->piVars['page'] . '">'; |
166
|
|
|
$output .= '<input type="hidden" name="tx_dlf[endpage]" id="endpage" value="' . $this->piVars['page'] . '">'; |
167
|
|
|
$output .= '<input type="hidden" name="tx_dlf[startX]" id="startX">'; |
168
|
|
|
$output .= '<input type="hidden" name="tx_dlf[startY]" id="startY">'; |
169
|
|
|
$output .= '<input type="hidden" name="tx_dlf[endX]" id="endX">'; |
170
|
|
|
$output .= '<input type="hidden" name="tx_dlf[endY]" id="endY">'; |
171
|
|
|
$output .= '<input type="hidden" name="tx_dlf[rotation]" id="rotation">'; |
172
|
|
|
$output .= '<button id="submitBasketForm" onclick="this.form.submit()">' . $label . '</button>'; |
173
|
|
|
$output .= '</form>'; |
174
|
|
|
$output .= '<script>'; |
175
|
|
|
$output .= '$(document).ready(function() { $("#submitBasketForm").click(function() { $("#addToBasketForm").submit(); }); });'; |
176
|
|
|
$output .= '</script>'; |
177
|
|
|
$markerArray['###BASKETBUTTON###'] = $output; |
178
|
|
|
} else { |
179
|
|
|
$markerArray['###BASKETBUTTON###'] = ''; |
180
|
|
|
} |
181
|
|
|
return $markerArray; |
182
|
|
|
} |
183
|
|
|
|
184
|
|
|
/** |
185
|
|
|
* Get image's URL and MIME type |
186
|
|
|
* |
187
|
|
|
* @access protected |
188
|
|
|
* |
189
|
|
|
* @param int $page: Page number |
190
|
|
|
* |
191
|
|
|
* @return array URL and MIME type of image file |
192
|
|
|
*/ |
193
|
|
|
protected function getImage($page) |
194
|
|
|
{ |
195
|
|
|
$image = []; |
196
|
|
|
// Get @USE value of METS fileGrp. |
197
|
|
|
$fileGrps = \TYPO3\CMS\Core\Utility\GeneralUtility::trimExplode(',', $this->conf['fileGrps']); |
198
|
|
|
while ($fileGrp = @array_pop($fileGrps)) { |
199
|
|
|
// Get image link. |
200
|
|
|
if (!empty($this->doc->physicalStructureInfo[$this->doc->physicalStructure[$page]]['files'][$fileGrp])) { |
201
|
|
|
$image['url'] = $this->doc->getFileLocation($this->doc->physicalStructureInfo[$this->doc->physicalStructure[$page]]['files'][$fileGrp]); |
202
|
|
|
if ($this->conf['useInternalProxy']) { |
203
|
|
|
// Configure @action URL for form. |
204
|
|
|
$linkConf = [ |
205
|
|
|
'parameter' => $GLOBALS['TSFE']->id, |
206
|
|
|
'forceAbsoluteUrl' => !empty($this->conf['forceAbsoluteUrl']) ? 1 : 0, |
207
|
|
|
'forceAbsoluteUrl.' => ['scheme' => !empty($this->conf['forceAbsoluteUrl']) && !empty($this->conf['forceAbsoluteUrlHttps']) ? 'https' : 'http'], |
208
|
|
|
'additionalParams' => '&eID=tx_dlf_pageview_proxy&url=' . urlencode($image['url']), |
209
|
|
|
]; |
210
|
|
|
$image['url'] = $this->cObj->typoLink_URL($linkConf); |
211
|
|
|
} |
212
|
|
|
$image['mimetype'] = $this->doc->getFileMimeType($this->doc->physicalStructureInfo[$this->doc->physicalStructure[$page]]['files'][$fileGrp]); |
213
|
|
|
break; |
214
|
|
|
} else { |
215
|
|
|
Helper::devLog('File not found in fileGrp "' . $fileGrp . '"', DEVLOG_SEVERITY_WARNING); |
216
|
|
|
} |
217
|
|
|
} |
218
|
|
|
return $image; |
219
|
|
|
} |
220
|
|
|
|
221
|
|
|
/** |
222
|
|
|
* Get fulltext URL and MIME type |
223
|
|
|
* |
224
|
|
|
* @access protected |
225
|
|
|
* |
226
|
|
|
* @param int $page: Page number |
227
|
|
|
* |
228
|
|
|
* @return array URL and MIME type of fulltext file |
229
|
|
|
*/ |
230
|
|
|
protected function getFulltext($page) |
231
|
|
|
{ |
232
|
|
|
$fulltext = []; |
233
|
|
|
// Get fulltext link. |
234
|
|
|
if (!empty($this->doc->physicalStructureInfo[$this->doc->physicalStructure[$page]]['files'][$this->conf['fileGrpFulltext']])) { |
235
|
|
|
$fulltext['url'] = $this->doc->getFileLocation($this->doc->physicalStructureInfo[$this->doc->physicalStructure[$page]]['files'][$this->conf['fileGrpFulltext']]); |
236
|
|
|
if ($this->conf['useInternalProxy']) { |
237
|
|
|
// Configure @action URL for form. |
238
|
|
|
$linkConf = [ |
239
|
|
|
'parameter' => $GLOBALS['TSFE']->id, |
240
|
|
|
'forceAbsoluteUrl' => !empty($this->conf['forceAbsoluteUrl']) ? 1 : 0, |
241
|
|
|
'forceAbsoluteUrl.' => ['scheme' => !empty($this->conf['forceAbsoluteUrl']) && !empty($this->conf['forceAbsoluteUrlHttps']) ? 'https' : 'http'], |
242
|
|
|
'additionalParams' => '&eID=tx_dlf_pageview_proxy&url=' . urlencode($fulltext['url']), |
243
|
|
|
]; |
244
|
|
|
$fulltext['url'] = $this->cObj->typoLink_URL($linkConf); |
245
|
|
|
} |
246
|
|
|
$fulltext['mimetype'] = $this->doc->getFileMimeType($this->doc->physicalStructureInfo[$this->doc->physicalStructure[$page]]['files'][$this->conf['fileGrpFulltext']]); |
247
|
|
|
} else { |
248
|
|
|
Helper::devLog('File not found in fileGrp "' . $this->conf['fileGrpFulltext'] . '"', DEVLOG_SEVERITY_WARNING); |
249
|
|
|
} |
250
|
|
|
return $fulltext; |
251
|
|
|
} |
252
|
|
|
|
253
|
|
|
/** |
254
|
|
|
* Get all AnnotationPages / AnnotationLists that contain text Annotations with motivation "painting" |
255
|
|
|
* |
256
|
|
|
* @access protected |
257
|
|
|
* |
258
|
|
|
* @param int $page: Page number |
259
|
|
|
* @return array An array containing the IRIs of the AnnotationLists / AnnotationPages as well as |
260
|
|
|
* some information about the canvas. |
261
|
|
|
*/ |
262
|
|
|
protected function getAnnotationContainers($page) |
263
|
|
|
{ |
264
|
|
|
if ($this->doc instanceof IiifManifest) { |
265
|
|
|
$canvasId = $this->doc->physicalStructure[$page]; |
266
|
|
|
$iiif = $this->doc->getIiif(); |
267
|
|
|
if ($iiif instanceof ManifestInterface) { |
|
|
|
|
268
|
|
|
$canvas = $iiif->getContainedResourceById($canvasId); |
269
|
|
|
/* @var $canvas \Ubl\Iiif\Presentation\Common\Model\Resources\CanvasInterface */ |
270
|
|
|
if ($canvas != null && !empty($canvas->getPossibleTextAnnotationContainers(Motivation::PAINTING))) { |
271
|
|
|
$annotationContainers = []; |
272
|
|
|
/* |
273
|
|
|
* TODO Analyzing the annotations on the server side requires loading the annotation lists / pages |
274
|
|
|
* just to determine wether they contain text annotations for painting. This will take time and lead to a bad user experience. |
275
|
|
|
* It would be better to link every annotation and analyze the data on the client side. |
276
|
|
|
* |
277
|
|
|
* On the other hand, server connections are potentially better than client connections. Downloading annotation lists |
278
|
|
|
*/ |
279
|
|
|
foreach ($canvas->getPossibleTextAnnotationContainers(Motivation::PAINTING) as $annotationContainer) { |
280
|
|
|
if (($textAnnotations = $annotationContainer->getTextAnnotations(Motivation::PAINTING)) != null) { |
281
|
|
|
foreach ($textAnnotations as $annotation) { |
282
|
|
|
if ( |
283
|
|
|
$annotation->getBody()->getFormat() == 'text/plain' |
284
|
|
|
&& $annotation->getBody()->getChars() != null |
285
|
|
|
) { |
286
|
|
|
$annotationListData = []; |
287
|
|
|
$annotationListData['uri'] = $annotationContainer->getId(); |
288
|
|
|
$annotationListData['label'] = $annotationContainer->getLabelForDisplay(); |
289
|
|
|
$annotationContainers[] = $annotationListData; |
290
|
|
|
break; |
291
|
|
|
} |
292
|
|
|
} |
293
|
|
|
} |
294
|
|
|
} |
295
|
|
|
$result = [ |
296
|
|
|
'canvas' => [ |
297
|
|
|
'id' => $canvas->getId(), |
298
|
|
|
'width' => $canvas->getWidth(), |
299
|
|
|
'height' => $canvas->getHeight(), |
300
|
|
|
], |
301
|
|
|
'annotationContainers' => $annotationContainers |
302
|
|
|
]; |
303
|
|
|
return $result; |
304
|
|
|
} |
305
|
|
|
} |
306
|
|
|
} |
307
|
|
|
return []; |
308
|
|
|
} |
309
|
|
|
|
310
|
|
|
/** |
311
|
|
|
* The main method of the PlugIn |
312
|
|
|
* |
313
|
|
|
* @access public |
314
|
|
|
* |
315
|
|
|
* @param string $content: The PlugIn content |
316
|
|
|
* @param array $conf: The PlugIn configuration |
317
|
|
|
* |
318
|
|
|
* @return string The content that is displayed on the website |
319
|
|
|
*/ |
320
|
|
|
public function main($content, $conf) |
321
|
|
|
{ |
322
|
|
|
$this->init($conf); |
323
|
|
|
// Load current document. |
324
|
|
|
$this->loadDocument(); |
325
|
|
|
if ( |
326
|
|
|
$this->doc === null |
327
|
|
|
|| $this->doc->numPages < 1 |
328
|
|
|
) { |
329
|
|
|
// Quit without doing anything if required variables are not set. |
330
|
|
|
return $content; |
331
|
|
|
} else { |
332
|
|
|
if (!empty($this->piVars['logicalPage'])) { |
333
|
|
|
$this->piVars['page'] = $this->doc->getPhysicalPage($this->piVars['logicalPage']); |
|
|
|
|
334
|
|
|
// The logical page parameter should not appear again |
335
|
|
|
unset($this->piVars['logicalPage']); |
336
|
|
|
} |
337
|
|
|
// Set default values if not set. |
338
|
|
|
// $this->piVars['page'] may be integer or string (physical structure @ID) |
339
|
|
|
if ((int) $this->piVars['page'] > 0 || empty($this->piVars['page'])) { |
340
|
|
|
$this->piVars['page'] = \TYPO3\CMS\Core\Utility\MathUtility::forceIntegerInRange((int) $this->piVars['page'], 1, $this->doc->numPages, 1); |
341
|
|
|
} else { |
342
|
|
|
$this->piVars['page'] = array_search($this->piVars['page'], $this->doc->physicalStructure); |
343
|
|
|
} |
344
|
|
|
$this->piVars['double'] = \TYPO3\CMS\Core\Utility\MathUtility::forceIntegerInRange($this->piVars['double'], 0, 1, 0); |
345
|
|
|
} |
346
|
|
|
// Load template file. |
347
|
|
|
$this->getTemplate(); |
348
|
|
|
// Get image data. |
349
|
|
|
$this->images[0] = $this->getImage($this->piVars['page']); |
350
|
|
|
$this->fulltexts[0] = $this->getFulltext($this->piVars['page']); |
351
|
|
|
$this->annotationContainers[0] = $this->getAnnotationContainers($this->piVars['page']); |
352
|
|
|
if ($this->piVars['double'] && $this->piVars['page'] < $this->doc->numPages) { |
353
|
|
|
$this->images[1] = $this->getImage($this->piVars['page'] + 1); |
354
|
|
|
$this->fulltexts[1] = $this->getFulltext($this->piVars['page'] + 1); |
355
|
|
|
$this->annotationContainers[1] = $this->getAnnotationContainers($this->piVars['page'] + 1); |
356
|
|
|
} |
357
|
|
|
// Get the controls for the map. |
358
|
|
|
$this->controls = explode(',', $this->conf['features']); |
359
|
|
|
// Fill in the template markers. |
360
|
|
|
$this->addViewerJS(); |
361
|
|
|
$markerArray = array_merge($this->addInteraction(), $this->addBasketForm()); |
362
|
|
|
$content .= $this->templateService->substituteMarkerArray($this->template, $markerArray); |
363
|
|
|
return $this->pi_wrapInBaseClass($content); |
364
|
|
|
} |
365
|
|
|
} |
366
|
|
|
|
This function has been deprecated. The supplier of the function has supplied an explanatory message.
The explanatory message should give you some clue as to whether and when the function will be removed and what other function to use instead.