Publications — Django-CV 0.0.1 documentation

# Publications

Publications are the central component of Django-CV since publications are the key element of CVs. Django-CV includes four types of publications: books, articles, chapters, and reports.

## Common Features

Publications, regardless of type, all have some common traits such as titles and lists of authors. Django-CV defines a number of common features across the four different types of publications. Internally, Django-CV does this by defining a series of abstract classes. The different publication models inherit from the `VitaePublicationModel` abstract model.

### Common Fields

The following fields are common across the four types of publications:

`title`
  The title of the publication (required).
`short_title`

  A shortened title of the publication with a maximum length of 80 characters (required).

  This can be the “running head” of a publication. Django-CV uses the slugified version of the short title to construct URLs for the item.

`slug`

  A slugified version of the short-title to use in URLs (required).

  The slugs are automatically constructed from the `short_title` in `admin`.

`status`

  The point in the publication process where the publication currently rests (required).

  All publication models include an `status` field, which represents the where in publication process the publication currently exists. Django-CV implements the `status` field by using an `IntegerField` with the `choices` parameter defined in `cv.constants.PUBLICATION_STATUS`:

  Integer | Status
  --- | ---
  0 | In preparation
  1 | Working paper
  20 | Submitted
  30 | Revision for resubmission invited
  35 | Resubmitted
  40 | Conditionally accepted
  50 | Forthcoming
  55 | In press
  60 | Published
  99 | “Resting”

`pub_date`
  The date that the publication was published in final form.
`primary_discipline`

  The discipline to which the publication contributes most directly.

  A `ForeignKey` relationship to a `cv.models.Discipline` object. Can be useful for researchers who work in multiple disciplines to separate their CV into sections for each discipline.

`other_disciplines`

  Disciplines other than the primary discipline to which the publication contributes.

  A `ManyToManyField` relationship to `cv.models.Discipline` objects.

### Ordering

The publication models order model instances by `status` in ascending order then by `pub_date` in descending order. This places the publications with the highest probability of changing at the top of sorted lists.

Note

The publication models do not use `pub_date` field to identify published articles and the built-in templates do not print the `pub_date` field. Therefore, users can use the `pub_date` field to order unpublished manuscripts in a convenient order.

### Common Managers

For all types of publications, users may access instances of publication models using four custom managers (in addition to the default manager using `objects`) that will return all objects:

`displayable` : default
  uses `cv.models.DisplayableManager` that returns only articles for which `display==True`.

`published`
  uses `cv.models.PublishedManager` that returns all articles that have been accepted for publication or published (forthcoming, in press, and published).

`inprep`
  uses `cv.models.InprepManager` that returns all articles being prepared for publication.

`revise`
  uses `cv.models.ReviseManager` that returns all articles that are in the process of submission or revision (submitted, under revision for resubmission, resubmitted, or conditionally accepted).

The custom managers the include multiple statuses retain the default ordering of the model (that is, they are ordered by `status`, then `pub_date`, then `submission_date`).

## Authorship Sets

Publication types also share the common trait of having authors. More precisely, publications have _authorships_ since a list of authors contains information, such as the order of authorship.

For all publication type models, Django-CV includes an `authorship` attribute that returns a `QuerySet` of authorships, e.g.:

    >>> from cv.models import Article
    >>> article = Article.objects.all().first()
    >>> article.authorship.all()
    <QuerySet [<ArticleAuthorship: Kahneman, Daniel>,
       <ArticleAuthorship: Tversky, Amos]>]

Internally, the authorship attributes are implemented as a `django.db.models.ManyToManyField`s that relate an instance of the publication type (e.g., :class:`Article`, `Book`, etc.) to `Collaborator` through a third model.

Authorship models for all publication types have three common fields:

`display_order`
  Integer that classifies the position of the author in the list of authors (required)
`print_middle`
  Boolean that indicates whether the author’s middle initials should be printed in list of authors (default=True)
`student_colleague`
  Choice field with possible values defined by CV_STUDENT_LEVELS_CHOICES setting; allows display of student collaborations

## Types of Publications

### Articles

Model field reference | `cv.models.Article`
Authorship set | `cv.models.ArticleAuthorship`

The `Article` model contains two non-editable fields managed internally that can be accessed for article instances:

- `abstract_html` that converts text entered in Markdown in `abstract` field
    to html, and
- `is_published` that indicates whether `status` field is one of
    “Forthcoming,” “In Press,” or “Published”.

The functions `get_previous_published()` and `get_next_published()` will get the next and previous published articles based on the `pub_date` field.

#### Article Views

Article List : `cv.views.ArticleListView`

  Context object | `{{article_objects}}`
  Template | `'cv/lists/article_list.html'`
  URL | `r'^articles/$'`
  URL name | `'article_object_list'`
  MIME type | `text/html`

  Returns context `{{article_objects}}` with four objects on the dot path:

  `total_articles`
    Integer of total number of article objects from all three status-based managers:
  `article_published_list`
    queryset of all published articles (uses the published manager <topics-pubs-published-manager>)
  `article_revise_list`
    queryset of all articles in the revision process (uses the revise manager <topics-pubs-revise-manager>)
  `article_inprep_list`
    queryset of all articles in preparation for submission (uses the inprep manager <topics-pubs-published-manager>)
Article Detail: `cv.views.ArticleDetailView`

  Context object | `{{article}}`
  Template | `'cv/details/article_detail.html'`
  URL | `'articles/<slug:slug>/`
  URL name | `'article_object_detail'`
  MIME type | `text/html`

  Returns context `{{article}}` that represents a single `Article` instance.

Article Citation: `cv.views.article_citation_view()`

  Context object | `{{article}}`
  Templates | `'cv/citations/article.ris'` `'cv/citations/article.bib'`
  URL | `'articles/<slug:slug>/citation/<str:format>/'`
  URL name | `'article_citation'`
  MIME type | `application/x-research-info-systems`

  Returns view to allow citation to be downloaded to citation management software.

  The `(?P<format>[w]+)` named parameter should be one of:

  `'ris'`
    will create downloadable citation using Reference Manager format specification (see http://endnote.com/sites/rm/files/m/direct_export_ris.pdf).
  `'bib'`
    will create downloadable citation using the BibTeX format specification (see http://www.bibtex.org/Format/)

### Books

The `Book` class stores instances of books. The `summary` field takes Markdown input and saves the converted HTML to the non-editable `summary_html` field.

The `Book` model can store information about different editions of book instances.

Model field reference | `cv.models.Book`
Authorship set | `cv.models.BookAuthorship`

#### Custom Methods

The `Book` class has two custom methods related to Book Editions:

> `add_edition`(dict)

>   Creates a new `BookEdition` instance with the referencing the `Book` instance on which the user calls the method.

>   - `dict`: a dictionary containing field/value pairs for `BookEdition` fields; `edition` must be one of the `dict` keys
> `get_editions`()

>   Convenience function to a `QuerySet` of all the `BookEdition` objects related to the `Book` instance

#### Book Views

Book List : `cv.views.BookListView`

> Context object | `{{book_objects}}`
> Template | `'cv/lists/book_list.html'`
> URL | `'books/'`
> URL name | `'book_object_list'`
> MIME type | `text/html`

> Returns context `{{book_objects}}` with four objects on the dot path:

> `total_books`
>   Integer of total number of books from all three managers:
> `books_published_list`
>   `QuerySet` of all published books (uses the published manager <topics-pubs-published-manager>)
> `books_revise_list`
>   queryset of all books in the revision process (uses the revise manager <topics-pubs-revise-manager>)
> `books_inprep_list`
>   queryset of all books in preparation for submission (uses the inprep manager <topics-pubs-published-manager>)

Book Detail: `cv.views.BookDetailView`

> Context object | `{{book}}`
> Template | `'cv/details/book_detail.html'`
> URL | `'books/<slug:slug>/'`
> URL name | `'book_object_detail'`
> MIME type | `text/html`

> Returns context `{{book}}` that represents a single `Book` instance.

Book Citation: `cv.views.book_citation_view()`

> Context object | `{{book}}`
> Templates | `'cv/citations/book.ris'` `'cv/citations/book.bib'`
> URL | `'books/<slug:slug>/citation/<str:format>/'`
> URL name | `'book_citation'`
> MIME types | `application/x-research-info-systems` `application/x-bibtex`

> Returns view to allow citation to be downloaded to citation management software.

> The `<str:format>` named parameter should be one of:

> `'ris'`
>   will create downloadable citation using Reference Manager format specification (see http://endnote.com/sites/rm/files/m/direct_export_ris.pdf).
> `'bib'`
>   will create downloadable citation using the BibTeX format specification (see http://www.bibtex.org/Format/)

#### Book Editions

Django-CV allows users to link multiple editions of a book with the `BookEdition` class. This is done through a ForeignKey relationship to the book. The `Book` model includes the `get_editions()` method to return all editions associated with the book in reverse chronological order (i.e., newest first).

If an edition has been related to a book, the default templates will use the publication information (publisher, place of publication, ISBN) of the edition instance, not the publication information defined for the book instance.

### Chapters

The `Chapter` class stores instances of chapters.

Like Articles, the `abstract` field takes Markdown input and saves the converted HTML to the (non-editable) `summary_html` field.

In addition to the `authorship` attribute that saves authorship information, the `Chapter` class also has an `editorship` attribute that contains information about editors of the volume in which the chapter appears. Like the `authorship` attribute, the `editorship` returns a foreign key `RelatedManager` (read more about related managers).

Model field reference | `cv.models.Chapter`
Authorship set | `cv.models.ChapterAuthorship`

Chapter List : `cv.views.ChapterListView`

> Context object | `{{chapter_objects}}`
> Template | `'cv/lists/chapter_list.html'`
> URL | `'chapters/'`
> URL name | `'chapter_object_list'`
> MIME type | `text/html`

> Returns context `{{chapter_objects}}` with four objects on the dot path:

> `total_chapters`
>   Integer of total number of chapters from all three managers:
> `chapters_published_list`
>   `QuerySet` of all published chapters (uses the published manager <topics-pubs-published-manager>)
> `chapters_revise_list`
>   `QuerySet` of all chapters in the revision process (uses the revise manager <topics-pubs-revise-manager>)
> `chapters_inprep_list`
>   `QuerySet` of all chapters in preparation for submission (uses the inprep manager <topics-pubs-published-manager>)

Chapter Detail: `cv.views.ChapterDetailView`

  Context object | `{{chapter}}`
  Template | `'cv/details/chapter_detail.html'`
  URL | `'chapters/<slug:slug>/'`
  URL name | `'chapter_object_detail'`
  MIME type | `text/html`

  Returns context `{{chapter}}` that represents a single `Chapter` instance.

Chapter Citation: `cv.views.book_citation_view()`

  Context object | `{{chapter}}`
  Templates | `'cv/citations/chapter.ris'` `'cv/citations/chapter.bib'`
  URL | `'chapter/<slug:slug>/citation/<str:format>/'`
  URL name | `'chapter_citation'`
  MIME types | `application/x-research-info-systems` `application/x-bibtex`

  Returns view to allow citation to be downloaded to citation management software.

  The `<str:format>` named parameter should be one of:

  `'ris'`
    will create downloadable citation using Reference Manager format specification (see http://endnote.com/sites/rm/files/m/direct_export_ris.pdf).
  `'bib'`
    will create downloadable citation using the BibTeX format specification (see http://www.bibtex.org/Format/)

### Reports