Drupal is a very popular and well-known CMS for educational websites. And it's very important that Drupal has tools to deal with bibliography and citations. For Drupal 7 (and earlier versions) there is the Bibliography Module aka Drupal Scholar aka the Biblio module available. Unfortunately, after some time that Drupal 8 had been released there still was no version of this module available for Drupal 8 and no related activity, so we started the development of the module which allows to deal with bibliography and citations in Drupal 8 and named it Bibliography & Citation aka BibCite.
As we could notice, users tried to resolve the Biblio and Drupal 8`s incompatibility issue even by requests to the Drupal community members on Twitter. This was the reason for creating a Twitter account for the Bibliography & Citation project. Except for tweets about major and minor changes and resolved issues we will tell you about the ways that users and organizations work with core and related modules, post the articles and other useful information. Subscribe and tap the bell icon to receive new tweets in time: twitter.com/BibCite.
Terms
The module solves quite specific tasks; to make the reading easier for you, we highlighted several important terms that we’re operating often in this case study.
Bibliography is a list of all of the sources you have used (whether referenced or not) in the process of researching your work. In general, the bibliography should include:
- authors' names
- titles of the works
- names and locations of the companies that published your copies of the sources
- dates your copies were published
- page numbers of your sources (if they are a part of multi-source volumes)
Citation is the way you tell your readers that certain material in your work came from another source. It can be a reference to a book, an article, a web page and so on. Giving credit to the original author by citing sources is the only way to use other people's work without plagiarizing. It's main but not the only reason to cite sources though.
Citation Style Language (CSL) is a popular open XML-based language to describe a formatting of citations and bibliographies. Official CSL style repository contains more than 8000 styles and is frequently updated. CSL is used by many commercial and open source products.
Assume you have a list of bibliography for your work and you need to display it somehow. Basically, your citations should satisfy some style guide. Citation styles (formats) can be broadly divided into the styles that are common to the Humanities and the Sciences. There is a number of widely used style guides, for example, The Chicago Manual of Style that has been coming out since 1906, which prescribes writing and citation styles, APA style, MLA Handbook and other. A number of organizations have created styles to fit their needs. Individual publishers often have their own in-house variations as well.
Bibliography and Citation
So why have we decided to build the module from the scratch? Why don't just join the maintainers of the Biblio module and release a Drupal 8 version? The first reason is continuity. By the time we started development, there were about 8000 usages of the Biblio module. Due to the module specifics, almost every usage is a rather deliberate choice so there was a big community of interested users. So changes in the data structure, in API, in UI, etc. have to be successive and evolutionary.
The second reason is the Biblio's legacy. Its history is very long and starts from Drupal 4.6. As a result, it has some technical and architecture issues:
- Data storage. In a few words, all data is stored in a special content type. There is a lot of custom code to reach it.
- Drupal integration. Custom code is required to integrate Biblio with some of the core's modules and popular contrib modules like Views, Rules, and others.
- Codebase and architecture problems. There are a lot of legacy code and code issues. Code was partly written in PHP 4+. Due to this fact, it is very hard to add new features and maintain the project.
- Lack of configuration management. It's hard to move configuration from one instance to another and re-use it on different sites.
We had a clear understanding that architecture and API need to be reconsidered and re-implemented to fit Drupal 8 well and eliminate legacy. With the new module, we had no boundaries in design and implementation.
So, what does the Bibliography & Citation module offer? First of all, it closely follows the Drupal way: implementation follows Drupal best practices and Drupal API is widely utilized. The basis is Drupal Entity API. The module utilizes Entity API as much as possible. Not only the main structures are made using entities, they are used for configurations, too. This approach allows to develop really flexible and extendable solutions. For example, it is easy to extend or alter current module’s features and it’s possible to develop add-ons. You will see this further. Standard Drupal UI elements are used so that it looks familiar to everyone.
The project consists of several submodules:
- Bibliography & Citation
- Bibliography & Citation - Entity
- Bibliography & Citation - Import
- Bibliography & Citation - Export
- Bibliography & Citation - Bibtex
- Bibliography & Citation - RIS
Let's examine each module in detail.
Bibliography and Citation
It is the core module that provides API for bibliographic citations rendering. CSL styles are used for rendering. It also provides the administration UI which allows to choose a processor (currently only citeproc PHP is available) and to choose a global CSL style.
You can also manage CSL styles from the administration UI - you can edit or delete a predefined style or install a new style manually or from .csl or xml files.
Bibliography and Citation - Entity
It provides a storage for bibliographic data in Drupal entities. It defines three types of entities:
- Reference
- Contributor
- Keyword
It also includes the basic functionality for rendering with the help of a display mode or the Views handler. Another important feature is mapping. For example, you can map BibTeX types into a Reference type (bundle) via the administration UI. And you can do the same with fields.
Let’s examine entity types in details.
Reference
Reference entities stores all bibliographic data. There are about 30 predefined types (bundles) e.g. artwork, book, etc. These bundles are configurable: you can add your own bundles via the administration UI. Bundles are fieldable. Also, you can customize the following properties:
- availability
- requirements
- labels
- descriptions
If a corresponding author entity exists in a system, the autocomplete feature will be activated.
If an author entity does not exist then a new author entity will be created.
It supports the human name parser feature so that you can just type a full name as a string and it will be automatically populated to appropriate fields.
Reference entities can be related to content via the Entity Reference field and rendered in a usual way: using display modes or Views.
Contributor
Contributor entities store info about authors. Authors may be assigned to a role and a category. You can manage a list of roles and categories via the administration UI. As I mentioned, it supports the human name parser feature. Also, in the administration UI, you can configure a pattern for displaying a full author name. Another important feature is deduplication. If you have duplicated author records, you can merge them into a single entity. It can be done manually (via administration views action) or automatically during the import process.
Import and Export
These modules provide an ability to import and export bibliographic data.
You can export all existing data or an exact piece. The same for import: you can import a single reference manually or in a bulk via file upload. The pre-fill feature is available so that you can edit data before saving the reference. There are two available formats for import/export for now: BibTeX and RIS. Those are the most important formats. The module is flexible and it is not a big deal to add new formats in future and, of course, some formats are already planned to be added in future releases of the module.
Contrib Additions
It's pretty clear that it's critical to have a migration path from the Biblio module to BibCite, to allow the users to move from older Drupal versions to the latest and greatest Drupal 8. This resulted in the Bibliography & Citation - Migrate module which provides migration paths from Drupal 6 and 7.
There is also a number of contrib modules which extend the Biblio module and provide some additions. Eventually, a number of additions to the BibCite module will appear to reflect the Biblio extensions' functionality. We implemented the Metatag Google Scholar module which provides a number of meta tags to help with the indexing of a scholarly content/articles in Google Scholar. Its functionality is general and doesn't depend on BibCite, but this combination is probably one of the main use cases.
Resources
Conclusion
We believe that our efforts resulted in the great module which fits Drupal 8 very well and allows the sites that deal with bibliographic data a lot to migrate to Drupal 8. The module is under active development and many cool features are planned. We received a noticeable amount of feedback, different bug reports, feature requests, patch and improvements suggestions. This is really great and strongly motivates us to continue the module's development and react to community needs. Feel free to submit your issues or feature requests.
Erlan Aytpaev
Anton Shubkin
Denis Usov
