The Extension Mechanism of the Reader Application of the dLibra System

Since version

Mechanizm rozszerzeń aplikacji czytelnika systemu dLibra

Od wersji 5.0 systemu dLibra wprowadzono mechanizm rozszerzeń prezentacji treści publikacji. Niektóre formaty dokumentów wymagają od użytkownika instalacji odpowiednich rozszerzeń dla przeglądarki np. format DjVu. W aplikacji czytelnika systemu dLibra istnieją mechanizmy pozwalające na prezentacje niektórych typów plików w formie przyjaznej dla użytkowników. Mechanizmy te bazują na oprogramowaniu kompatybilnym z HTML oraz na domyślnych rozwiązaniach przeglądarek internetowych.

Image Removed

Aplikacja czytelnika na podstawie typu i nazwy głównego pliku publikacji określa czy dostępne są rozszerzenia sposobu prezentacji dla danej publikacji. Jeżeli tak, przed wyświetleniem treści prezentuje użytkownikowi listę dostępnych rozszerzeń (por. rysunek). Użytkownik może skorzystać z odtwarzacza wbudowanego w dLibrę lub pozostawić obsługę przeglądarce (jeżeli posiada już zainstalowaną wtyczkę).

Budowa i sposób działania rozszerzeń prezentacji treści.

, the dLibra system has had an extension mechanism for presenting publication content. For some document formats (for example, for the DjVu format), the reader must install appropriate browser extensions. In the Reader Application of the dLibra system, there are mechanisms for presenting some file types in a user-friendly form. The mechanisms are based on software compatible with HTML and on the default solutions of Internet browsers.

.

Image Added

On the basis of the type and name of the main publication file, the Reader Application determines if extensions for the manner of content presentation are available for the given publication. If they are, the application displays the list of the available extensions to the reader (see the figure above), before displaying the content. The user can use the player built into the dLibra system or leave the handling to the browser (if the plugin is already installed).

The Structure and Operation of Content Presentation Extensions

Every extension used for presenting content consists of two parts: files visible through the WWW, for example, JavaScript files or CSS sheets; those files are in the Każde z rozszerzeń używanych do prezentacji treści składa się z dwóch części. Plików widocznych przez WWW np. skryptów JavaScipt, arkuszy CSS. Pliki te znajdują się w katalogu dlibra-webapp-5.0/formats/nazwa-rozszerzenia. Plików z konfiguracją rozszerzeń np. ustawienia związane z tym jakie formaty dane rozszerzenie jest w stanie wyświetlać, szablony VTL używane do generowania kodu HTML rozszerzenia, tekst wyświetlanego ostrzeżenia. Pliki te znajdują się w katalogu extension-name catalog; and files with extension configuration, for example, settings of the data formats which the given extension can display, VTL templates for generating HTML code, or a warning text; those files are in the dlibra-webapp/WEB-INF/formats/nazwaextension-rozszerzenia.
Poniżej przedstawione zostanie rozszerzenie wykorzystywane do prezentacji obrazów w formacie Zoomify. Składa się on z następujących plikówname catalog.

Below, we describe the extension used for presenting objects in the Zoomify format. It consists of the following files:

• settings.xml - konfiguracja rozszerzenia. – extension configuration,
• message_pl.xml, message_en.xml - etykiety tekstowe wyświetlane w treści ostrzeżenia. – text labels displayed in the warning text, and
• content.vm, message.vm - szablony kodu HTML i szablon ostrzeżenia.
  Każde rozszerzenie prezentacji treści musi posiadać wymienione wyżej 5 plików, część widoczna od strony WWW jest opcjonalna. – HTML code templates and the warning template.

Every content presentation extension must contain the five files listed above. The part visible from the WWW is optional.

The settings.xml file contains the most important settings related to the functioning of the extension, such asPlik settings.xml zwiera najważniejsze ustawienia związane z działaniem rozszerzenia, są to między innymi:

• handled.mime.types - lista oddzielonych przecinkami typów MIME obsługiwanych przez dane rozszerzenie. W przypadku omawianego rozszerzenia jest to tylko jeden typ text/xml.
• handles.secured - parametr może mieć wartość true albo false. Jeżeli dane rozszerzenie potrafi zabezpieczyć treść publikacji przed kopiowaniem wartość tego parametru można ustawić na true, w przypadku rozszerzenia zoomify parametr ten ma wartość false.
• handles.normal - parametr może mieć wartość true albo false. Jeżeli dana publikacja obsługuje prezentacje normalnych (nie zabezpieczonych) publikacji parametr ten ma wartość true (tak jest w przypadku omawianego rozszerzenia).
• handled.filenames - parametr ten jest opcjonalny, należy tu podać oddzielone przecinkami dopuszczalne nazwy pliku głównego publikacji. Plik główny publikacji w formacie zoomify to prosty dokument XML aby odróżnić go od innych formatów, które również posiadają XML jako plik główny można wprowadzić wymóg zgodności nazwy pliku głównego. W omawianym przypadku wartość tego parametru to: ImageProperties.xml.

W momencie gdy użytkownik wybierze rozszerzenie jakiego chce użyć do prezentacji treści, aplikacja czytelnika generuje ostrzeżenie dotyczące formatu - renderowana jest zawartość pliku message.vm przy użyciu etykiet tekstowych z plików messages_pl.xml i messages_en.xml. Następnie użytkownik przechodzi do treści, aplikacja czytelnika wyświetla wyrenderowany szablon content.vm. W szablonie tym określone są odwołania do widocznych od strony WWW elementów rozszerzenia formatu prezentacji treści oraz do pliku z treścią publikacji. Z poziomu szablonu content.vm tworzący rozszerzenia prezentacji treści ma do dyspozycji dwie zmienne:

• – a list of the MIME types supported by the extension, separated by commas; in the case of the discussed extension, there is only one text/xml type;
• handles.secured – that parameter can have the “true” or “false” value; if the given extension can protect the publication content against copying, then the value of that parameter can be set to “true”; in the case of the Zoomify extension, the value of that parameter is “false”;
• handles.normal – that parameter can have the “true” or “false” value; If the given publication supports presenting normal (unprotected) publications, that parameter has the “true” value (that is the case for the discussed extension); and
• handled.filenames – that parameter is optional; the user should enter the admissible names for the main publication file here, separated with commas. In a publication in the Zoomify format, the main file is a simple XLM document. In order to be able to distinguish it from other file formats which also have an XML document as the main file, a requirement for consistency of the name of the main file can be introduced. In the discussed case, the value of that parameter is: ImageProperties.xml.

When the user has chosen an extension for presenting content, the Reader Extension generates a warning which pertains to* the format – the content of the message.vm file is rendered with the use of the text labels from the messages_pl.xml and messages_en.xml files. Next, the user goes to the content, and the Reader Application displays the rendered content.vm template. In that template, references to a) the elements of the extension for the manner of content presentation which are visible from the WWW and b) the file with the publication content. From the level of the content.vm template, two variables are available for the person creating extensions for presenting content:

1. ${completeContentUrl} – a complete link to the main publication file, and
2. ${pathToHandler} - – a website address which indicates the catalog of the given extension, for example,
3. ${completeContentUrl} - kompletny odnośnik do głównego pliku publikacji
4. ${pathToHandler} - adres WWW wskazujący na katalog danego rozszerzenia w przykładowo http://dlibra.psnc.pl/dlibra/formats/djvu_html5. W tym katalogu znajdują się skrypty danego rozszerzenia.htm!5. That catalog contains the scripts of the given extension.

In the case of the presented extension, zoomify, the page rendered while the publication content is being displayed contains the calling of the zoomifyViewer.swf script, where the arguments include the path to the main file of the publication. The box below contains the content of the content.vm template for the djvu_htm!5 extensionW przypadku prezentowanego rozszerzenia zoomify strona wyrenderowana podczas wyświetlania treści publikacji zawiera wywołanie skryptu zoomifyViewer.swf gdzie w argumentach podawana jest ścieżka do pliku głównego publikacji. Poniżej zawartość szablonu content.vm dla rozszerzenia djvu_html5:

<link type="text/css" rel="stylesheet" href="${pathToHandler}/Djvu_html5.css">
<script type="text/javascript" language="javascript"
	src="${pathToHandler}/djvu_html5/djvu_html5.nocache.js"></script>
<noscript>
	<div
		style="width: 22em; position: absolute; left: 50%; margin-left: -11em; color: red; background-color: white; border: 1px solid red; padding: 4px; font-family: sans-serif">
		Your web browser must have JavaScript enabled in order for this
		application to display correctly.</div>
</noscript>
<div id="djvuContainer" file="${completeContentUrl}"></div>
<script type="text/javascript">
var DJVU_CONTEXT = {
	parallelDownloads: 1,
};
</script>

Domyślny sposób prezentacji treści

The Default Manner of Content Presentation

There are three files W katalogu dlibra-webapp/WEB-INF/formats znajdują się trzy pliki (message_pl.xml, message_en.xml i settings.xml) jest to konfiguracja domyślnej obsługi prezentacji formatów. Wszelkie zmiany w tych plikach mogą spowodować, że aplikacja czytelnika nie będzie działać poprawnie.in the dlibra-webapp/WEB-INF/formats catalog. That is the configuration of the default handling of the manner of content presentation. Any changes in those files may prevent the Reader Application from functioning correctly