.. You may want to use the usual include line. Uncomment and adjust the path. .. include:: ../Includes.txt ========================= EXT: Publication database ========================= :Author: Christopher :Created: 2010-12-18T19:57:23 :Changed by: Johannes Kropf :Changed: 2014-01-15T22:32:37.295523120 :Classification: pubdb :Description: The keywords help with categorizing and tagging of the manuals. You can combine two or more keywords and add additional keywords yourself. Please use at least one keyword from both lists. If your manual is NOT in english, see next tab "language" ---- forEditors (use this for editors / german "Redakteure") forAdmins (use this for Administrators) forDevelopers (use this for Developers) forBeginners (manuals covering TYPO3 basics) forIntermediates (manuals going into more depth) forAdvanced (covering the most advanced TYPO3 topics) ---- :Keywords: forEditors, forAdmins, forIntermediates :Author: Johannes Kropf :Email: johannes@kropf.at :Language: en .. _img-1-img-2-EXT-Publication-database: |img-1| |img-2| EXT: Publication database ========================================= Extension Key: pubdb Language: en Version: 1.1.0 Keywords: forEditors, forAdmins, forIntermediates Copyright 2006-2014, Johannes Kropf This document is published under the Open Content License available from http://www.opencontent.org/opl.shtml The content of this document is related to TYPO3 \- a GNU/GPL CMS/Framework available from www.typo3.org .. _Table-of-Contents: Table of Contents ----------------- **`EXT: Publication database 1 <#__RefHeading__5708_1738894311>`_** **`Introduction 3 <#__RefHeading__5710_1738894311>`_** `What does it do? 3 <#__RefHeading__463_413120346>`_ `Screenshots 3 <#__RefHeading__465_413120346>`_ **`Users manual 5 <#__RefHeading__467_413120346>`_** `Create a publication category 5 <#__RefHeading__1423_1905651505>`_ `Create a publication item 6 <#__RefHeading__1425_1905651505>`_ `Create frontend pages 9 <#__RefHeading__1524_1905651505>`_ `FAQ 12 <#__RefHeading__31509_818911409>`_ **`Administration 13 <#__RefHeading__31511_818911409>`_** `Database administration 13 <#__RefHeading__974_2125359537>`_ `Configuring DOI settings for XML export 13 <#__RefHeading__976_2125359537>`_ `FAQ 14 <#__RefHeading__31513_818911409>`_ **`Configuration 15 <#__RefHeading__31515_818911409>`_** `Upgrade from an older version 15 <#__RefHeading__978_2125359537>`_ `If you upgrade an older version to the current release you will have to run the database update script, which should be performed automatically. 15 <#__RefHeading__1147_2125359537>`_ `To be sure check the “Database Update” tab in the Extension manager: 15 <#__RefHeading__1149_2125359537>`_ `FAQ 17 <#__RefHeading__31517_818911409>`_ `Reference 18 <#__RefHeading__31519_818911409>`_ **`Tutorial 20 <#__RefHeading__31523_818911409>`_** **`Known problems 21 <#__RefHeading__31525_818911409>`_** **`To-Do list 22 <#__RefHeading__477_413120346>`_** **`ChangeLog 23 <#__RefHeading__31623_818911409>`_** **`Added an update and database cleanup script 23 <#__RefHeading__1427_1905651505>`_** **`Improved manual 23 <#__RefHeading__1429_1905651505>`_** **`Improvement and review of code 23 <#__RefHeading__1431_1905651505>`_** **`Typo3 6.0 & 6.1 compatibility bugfix 23 <#__RefHeading__1433_1905651505>`_** .. _Introduction: Introduction ------------ .. _What-does-it-do: What does it do? ^^^^^^^^^^^^^^^^ - This extension (pubdb) gives support for managing mainly scientific publications on a typo3 website. - The views can be customized via templates and CSS styles similar to the well known tt\_news extension .. _Remark: Remark: """"""" Please feel free to send me bugs or ideas for future improvements to `johannes@kropf.at `_ or report it on the forge website http://forge.typo3.org/projects/extension-pubdb .. _The-following-features-are-implemented: The following features are implemented: """"""""""""""""""""""""""""""""""""""" - Publications can be related to categories - A publication can be offered as a file for downloading what can be allowed for special website user groups. - A search form is included - A form for ordering a hard copy of the publication is implemented - Export of CrossRef XML Files to upload to `www.crossref.org `_ DOI database - Support of various publication types - Linking publications to each other (e.g. journal to journal articles) .. _Screenshots: Screenshots ^^^^^^^^^^^ |img-3| *Figure 1: Example of a generated list of publications according to the AMS citation guidelines* |img-4| *Figure 2: Generated single view of a journal article including meta information of the journal it is in* .. _Users-manual: Users manual ------------ .. _Create-a-publication-category: Create a publication category ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ When the extension is installed and a storage folder for the publication data is created at least one publication category has to be created. This is done by adding a new item in the storage folder using the LIST module of typo3: |img-5| *Figure 3: TYPO3 backend list module for record editing* A category has only a few options: Hide: hide the recored Name: an arbitrary speaking name for the category Groups allowed to download: an optional list of website user (front end) groups which are allowed the files set in the publication record in the field “files with restricted access”.It provides access control for files related to a publication, e.g. a user needs to be logged in to access the full text pdf or the full text PDF should be available to a specific group only. |img-6| *Figure 4: Data mask for a publication category* .. _Create-a-publication-item: Create a publication item ^^^^^^^^^^^^^^^^^^^^^^^^^ Similar to the creation of categories choose “Pubdb Publication” in the list of possible new items in the list view: |img-7| *Figure 5: Part of the edit mask for a publication* The fist step in the creation of a new publication is the definition of the publication type. **NOTE:** Not all fields are visible for all publication types for a better understanding. **NOTE:** Some publication types show the DEPRECATED field Author/editor, it should NOT be used anymore for new records, use the “available contributors” section instead which holds the contributors in a separate table with more details and provides a reuse of contributors (authors) and therefore a database relation between publications and contributors. **Contributors:** The current version of the extension uses the IRRE (Inline Relational Record Editing) concept to edit records of two tables in one list. Contributors are stored now separately and linked to publications over the available contributors section in the publication edit mask: |img-8| *Figure 6: Inline contributor editing* Already stored contributors can be selected via the “SELECT” box (1), if the currently shown record shall be chosen click on “Create new relation” (2). A new contributor can be created by clicking on “Create new” (3). A newly created entry can be opened by clicking on the gray title bar (4). In the ROLE selection box (5) the role of the contributor for this specific publication can be defined. The role can be author, editor, chair or translator. The same contributor entry can have different roles at different publications. The data records (7) are self-explanatory and are different for another contributor type (6) which can be PERSON or ORGANISATION. The “Show in recored contributors list” (8) defines if the contributor shall be shown in the selector box (1) for re-use in other publications. This can be useful if there are many contributors which are unlikely for being reused. |img-9| *Figure 7: Contributor editing* The order of contributors can be re-arranged with the up and down arrows in the title bar (4). The most common publication types are explained in more details: **Publication type [JOURNAL]:** A JOURNAL defines a specific issue of a regularly published publication. The record hols only meta information of the issue and NOT any content. **Publication type [JOURNAL** **ARTICLE** **]:** A JOURNAL ARTICLE holds information about an article within a journal. Most of the records are self-explanatory, for some exist a context- sensitive help, which is not obvious in current typo3 versions ( *you need to move the cursor on the title of the record field* ) If there shall be stored many articles from many different authors, the journal article offers an alternative to the separate contributors table: **List of authors field** The list of authors field can be used INSTEAD of the contributors list but requires a correct input format (please refer also to the context sensitive help): Authors have to be separated by semicolon (;), surname and given name have to be separated by space if the order is given name(s) surname or by comma (,), if the order is surname(s), given name(s). The latter is especially usefull if the surname consists of more than one word. For example, correctly formatted entries would be: *Albert Einstein;* *Jakob Laub* *van der Marel, Roeland P.; Gerssen, Joris* or a mixed variant: van der Marel, Roeland P.; Joris Gerssen If you enter Roeland P. van der Marel, surname and given name will not be separated correctly in the frontend view or in the XML export. .. _Create-frontend-pages: Create frontend pages ^^^^^^^^^^^^^^^^^^^^^ Create a new content element on a page and choose “General plugin” as content type: |img-10| *Figure 8: Choose "General Plugin" as content type* Choose “pubdb” on the Plugin tab: |img-11| *Figure 9: Select the Pubdb plugin* In the “what to view” selection box you can define how the page should be rendered. |img-12| *Figure 10: Selector for the pubdb frontend view* The different options are described in more details below. .. _Create-page-for-single-view: Create page for single view """"""""""""""""""""""""""" If you put data to the abstract field of the publication a link the single view page will be shown. The single view page shows all information of the publication. Choose a record and define pubdb as plugin. At the “What to view” field choose “View single page”. Since a single view may link to the single view of other publications, e.g. the content list of a journal, the single page id, which is the same page in most cases MUST be set in the “Other settings” tab. To do so, just choose the single page with the page browser. The order page and the email are optional. **HINT:** In most cases the page providing the single view can be hidden in the menu. .. _Create-a-page-for-order-view: Create a page for order view """""""""""""""""""""""""""" If you mark “Show order link” in the publication record, a link to a order form is shown in the publication list as well as in the single view. With this option you offer the user to order a hard copy of the publication. The order will be send by email. The email address is defined in the plugin settings in the backend. If a user is logged in, its data will be taken and filled in automatically. .. _Create-a-list-view-page: Create a list view page """"""""""""""""""""""" Include the plugin on your page and choose “View publication list” and the categories of publications which should be shown. Optionally you can show also a search form. Results of search will be shown at the same page. If the publication offers more information as data in the abstract field, files to download or other publications it is linked to (e.g. a journal is linked to its articles) a “more” link will be shown. To get this work it is necessary to define “single page” in the “Other settings” tab! In the category section you can choose the categories of publications shall be shown. To lists can be defined and connected via AND or OR. Multiple categories selection with one field are as well connected by OR, in this case only the first field could be used also. .. _Provide-remote-access: Provide remote access """"""""""""""""""""" If you want to provide your database to a remote site, which is not necessarily a TYPO3 website, you can do it via that plugin option. The access is completely open like a usual website and provides your publication data as JSON String. .. _Show-records-from-a-remote-database: Show records from a remote database """"""""""""""""""""""""""""""""""" This option can be used to show a list of publications provided by an external TYPO3 site with a pubdb extension running. Doing so provide the URL in the URL field and enter the page id of the “Provide remote access”. This is not necessary if you can access the page via a static url pointing to the page providing remote access e.g. http://www.mysite.org/remotepubdb In the standard case one would use e.g. `http://www.mysite.org `_ and enter the page id as integer value in the field below. |img-13| *Figure 11: Remote record view settings* You get the id of your page providing remote access if you move your cursor on the page in the tree view in the TYPO3 backend: |img-14| *Figure 12: Retrieving the page ID* .. _FAQ: FAQ ^^^ Possible subsection: FAQ .. _Administration: Administration -------------- This section gives information about some administration features of the extension. .. _Database-administration: Database administration ^^^^^^^^^^^^^^^^^^^^^^^ The extension provides an update script to ensure data consistency. The script can be accessed via the extension page in the Extension Manager. For administrators mainly the third point *“* *Search duplicate contributors in the tx\_pubdb\_contributors table”* is relevant which searches for duplicate contributors and merges them. It does not only a string comparison, it fixes some formatting issues and compares given names also with initials, e.g. Mustermann, Max and Mustermann, M. would be detected to be the same and merged. Missing spaces e.g. between initials such as D.P. F. are corrected to D. P. F. .. _Configuring-DOI-settings-for-XML-export: Configuring DOI settings for XML export ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ In the configuration section of the extension in the Extension manager a few DOI related settings can be made. This parameters are only relevant for the CrossRef style XML export of publication data in the backend.Currently it is assumed that you have the extension realurl extension installed which maps parameters to URL parts of a static url. The other parameters refer to your account at www.crossref.org |img-15| *Figure 13: Extension configuration page* .. _FAQ: FAQ ^^^ Possible subsection: FAQ .. _Configuration: Configuration ------------- The installation of the extension is straight forward using the Extension Manager. No special configuration is needed to run pubdb. .. _Upgrade-from-an-older-version: Upgrade from an older version ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ If you upgrade an older version to the current release you will have to run the database update script, which should be performed automatically. To be sure check the “Database Update” tab in the Extension manager: |img-16| *Figure 14: Database update tab in Extension manager (TYPO3 4.x)* In TYPO3 6.x make a database check with the installer. If the database update is performed you should run the Update script, accessible also via the Extension Manager (Figure 15 and Figure 16). **NOTE: Please make a backup of the tables tx\_pubdb\_data, tx\_pubdb\_contributors and tx\_pubdb\_pub\_contributors before you run the script!** Currently, the update script fixes three issues: Updates publication type content\_item to book\_chapter which are redundant and therefor not necessary Removes author / editor entries (which is marked as DEPRECATED) in the publications and creates contributor entries for it in a separate table. Every contributor will be created only once.If the field contains the keywords “Editor”, Eds”, Editors” or “Hrsg”, the contributors in that field will get the role “Editor”, in the default case “Author”. The script tries to parse surname and given name out of the string, authors may be separated by “,” or “;”. Finally, a plausibility check is done and the script outputs what couldn't get parsed (see Figure 17). You should edit this entries manually and try again. Script 2 creates every contributor only once, but due to typing errors especially in the surnames you might notice afterwards that there are still duplicate entries not identified. You should correct the entries in the back end list module and run the script again to merge duplicates. **NOTE:** Do not manually delete duplicates, dead references in the relation table may lead to an unexpected behavior.You can run the update script again at any time. |img-17| *Figure 15: In TYPO3 4.x click on "Check update script"* |img-18| *Figure 16: In TYPO3 6.x click on the green arrow to run the update script* |img-19| *Figure 17: Result page of the update script* .. _FAQ: FAQ ^^^ Possible subsection: FAQ .. _Reference: Reference ^^^^^^^^^ .. _TypoScript-Options: TypoScript Options. """"""""""""""""""" .. ### BEGIN~OF~TABLE ### .. _plugin-tt-news-pubdb-singlePID: plugin.tt\_news.pubdb\_singlePID ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ .. container:: table-row Property plugin.tt\_news.pubdb\_singlePID Data type integer Description PageID for Link to publication single view from tt\_news entry Default .. _plugin-tx-pubdb-pi1-templateFile: plugin.tx\_pubdb\_pi1.templateFile ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ .. container:: table-row Property plugin.tx\_pubdb\_pi1.templateFile Data type string Description Location of the template file to be used. e.g. :: plugin.tx_pubdb_pi1.templateFile = fileadmin/myPubdbTempl.tmpl Additionally copy the CSS file setup.txt from pubdb/static/css/ to your fileadmin folder and include it with e.g. :: page.includeCSS{ cssfile1 = fileadmin/mypubdbstyles.css } **HINT:** if you do not copy the template files to your own folder your changes will be overwritten every time you update the extension Default Ext/pubdb/pi1/template.tmpl .. ###### END~OF~TABLE ###### .. _Tutorial: Tutorial -------- .. _Known-problems: Known problems -------------- Please report bugs and other issues on the forge project website: `Pubdb site on typo3 forge `_ .. _To-Do-list: To-Do list ---------- - Direct xml upload to crossref - Finalization of French translation - Make the extension compatible to TYPO3 6.2 Provide your wishes about new features on the project webpage; `Pubdb site on typo3 forge `_ . .. _ChangeLog: ChangeLog --------- .. ### BEGIN~OF~TABLE ### .. _1-1-2: 1.1.2 ^^^^^ .. container:: table-row Version 1.1.2 Changes bugfix: simulation mode in update script .. _1-1-1: 1.1.1 ^^^^^ .. container:: table-row Version 1.1.1 Changes - fixed bug: extension fe page not rendered - fixed bug: authors not correctly parsed by update script .. _1-1-0: 1.1.0 ^^^^^ .. container:: table-row Version 1.1.0 Changes - Added an update and database cleanup script - Improved manual - Improvement and review of code .. _1-0-2: 1.0.2 ^^^^^ .. container:: table-row Version 1.0.2 Changes Typo3 6.0 & 6.1 compatibility bugfix .. _1-0-1: 1.0.1 ^^^^^ .. container:: table-row Version 1.0.1 Changes PHP 5.3.0 compatibility .. _1-0-0: 1.0.0 ^^^^^ .. container:: table-row Version 1.0.0 Changes - Supporting Typo3 6.x - Providing remote access to other Typo3 Sites via web site and JSON data export - Providing export of Meta data to CrossRef XML files - Extended the database model to publication types, subtypes and a separate contributor table - Formatting references in list views following the AMS citation guideline .. _0-0-3: 0.0.3 ^^^^^ .. container:: table-row Version 0.0.3 Changes - Added search box which can be displayed on list page - Its possible not to show any publication on list (mainly for empty search box) - Added new fields in publications: location, show hard copy link, price - Added order form for ordering a hard copy when the concerning value is defined in the publication database entry .. ###### END~OF~TABLE ###### .. ######CUTTER_MARK_IMAGES###### .. |img-1| image:: img-1.png .. :align: left .. :border: 0 .. :height: 44 .. :id: graphics5 .. :name: graphics5 .. :vspace: 57 .. :width: 161 .. |img-2| image:: img-2.png .. :align: left .. |img-3| image:: img-3.png .. :align: left .. :border: 0 .. :id: graphics1 .. :name: graphics1 .. :width: 100% .. |img-4| image:: img-4.png .. :align: left .. :border: 0 .. :id: graphics6 .. :name: graphics6 .. :width: 100% .. |img-5| image:: img-5.png .. :align: left .. :border: 0 .. :id: graphics8 .. :name: graphics8 .. :width: 100% .. |img-6| image:: img-6.png .. :align: left .. :border: 0 .. :id: graphics7 .. :name: graphics7 .. :width: 100% .. |img-7| image:: img-7.png .. :align: left .. :border: 0 .. :id: graphics9 .. :name: graphics9 .. :width: 100% .. |img-8| image:: img-8.png .. :align: left .. :border: 0 .. :id: graphics10 .. :name: graphics10 .. :width: 100% .. |img-9| image:: img-9.png .. :align: left .. :border: 0 .. :id: graphics11 .. :name: graphics11 .. :width: 100% .. |img-10| image:: img-10.jpeg .. :align: left .. :border: 0 .. :id: graphics2 .. :name: graphics2 .. :width: 100% .. |img-11| image:: img-11.png .. :align: left .. :border: 0 .. :id: graphics12 .. :name: graphics12 .. :width: 100% .. |img-12| image:: img-12.png .. :align: left .. :border: 0 .. :id: graphics13 .. :name: graphics13 .. :width: 100% .. |img-13| image:: img-13.png .. :align: left .. :border: 0 .. :id: graphics14 .. :name: graphics14 .. :width: 100% .. |img-14| image:: img-14.png .. :align: left .. :border: 0 .. :id: graphics15 .. :name: graphics15 .. :width: 100% .. |img-15| image:: img-15.png .. :align: left .. :border: 0 .. :id: graphics3 .. :name: graphics3 .. :width: 100% .. |img-16| image:: img-16.png .. :align: left .. :border: 1 .. :id: graphics16 .. :name: graphics16 .. :width: 100% .. |img-17| image:: img-17.png .. :align: left .. :border: 0 .. :id: graphics18 .. :name: graphics18 .. :width: 100% .. |img-18| image:: img-18.png .. :align: left .. :border: 1 .. :id: graphics19 .. :name: graphics19 .. :width: 100% .. |img-19| image:: img-19.png .. :align: left .. :border: 0 .. :id: graphics17 .. :name: graphics17 .. :width: 100%