This is a pre-production deployment of Warehouse, however changes made here WILL affect the production instance of PyPI.
Latest Version Dependencies status unknown Test status unknown Test coverage unknown
Project Description

A new generator for Pelican that replaces the default Page and Article generators, allowing the definition of arbitrary content types, aka, entity types (e.g: projects, events) and associated indices/direct templates.

Similar to nodes in Drupal.

Install

To install the library, you can use pip

$ pip install pelican-entities

Usage

  1. Update pelicanconf.py:

    1. Add entities to PLUGINS.
      PLUGINS = ['entities', ...]
      
    2. Disable default page and article generators:

      PAGE_PATHS = []
      ARTICLE_PATHS = []
      DIRECT_TEMPLATES = []
      PAGINATED_DIRECT_TEMPLATES = []
      
    3. Specify entity types to use in your site and their settings:

      ENTITY_TYPES = {
          <type1_name>: {
              PATHS: [<type1_path1>, <type1_path2>, ...],
              EXCLUDES: [...],
              <type1_name>_URL: "...",
              <type1_name>_SAVE_AS: "...",
              ...
          },
          <type2_name>: {
              ...
          }
      }
      
  2. Update theme to use new variables.

  3. Watch out for incompatible plugins (those that rely on the pages and article generator signals or on the existence of variables defined by them).

Settings

Settings defined at the ENTITY_TYPES level take precedence over global ones.

Changes from default

  • Settings for each entity type are defined as the value of the corresponding key in the ENTITY_TYPES dictionary.
  • PAGE_PATHS and ARTICLE_PATHS are replaced by PATHS.
  • PAGE_EXCLUDES and ARTICLE_EXCLUDES are replaced by EXCLUDES.
  • PAGE_URL, ARTICLE_URL, PAGE_SAVE_AS and ARTICLE_SAVE_AS replaced by generic <entity_name>_URL and <entity_name>_SAVE_AS.
  • ARTICLE_ORDER_BY and PAGE_ORDER_BY are removed in favour of SORTER.

New settings

  • DEFAULT_TEMPLATE: Template to use by default when generating pages for that entity type.
  • MANDATORY_PROPERTIES: List of properties that has to be defined for an entity to be considered valid (by default, just date).
  • SORTER: Function taking list of entities as argument and which is responsible for sorting it as desired. Default value is the result of a call to entities.attribute_list_sorter(["date"], reverse=True)
  • ARCHIVE_TEMPLATE: Template used for archive pages.
  • CATEGORY_TEMPLATE: Template used for category pages.
  • TAG_TEMPLATE: Template used for tag pages.
  • AUTHOR_TEMPLATE: Template used for author pages.
  • SUBGENERATOR_CLASS: Optionally define a custom subgenerator class. This should either be a callable matching the entities.EntityGenerator.EntitySubGenerator interface or an import path to such a callable which will be imported dynamically.

Context/Themes

New available variables

  • Global:
    • url: The url of the current page.
    • entity_type: Type of the entity associated with this page.
    • entity_types: Dict having all declared entity types as keys and their generators as values.
    • <entity_type_name>: For each declared entity type, an object is added to the context containing:
      • entities: All entities of that entity type.
      • translations: All translations of that entity type.
      • tags: All tags of that entity type.
      • categories: All categories of that entity type.
      • authors: All authors of that entity type.
      • drafts: All drafts of that entity type.
      • drafts_translations: All draft translations of that entity type.
  • Entity page:
    • entity: Contains the object describing an entity (replaces article or page).
  • Direct templates:
    • direct: Variable always equal to True when rendering a direct template.
  • Tag, category, author pages:
    • entities: Replaces articles.
    • all_entitites: Replaces all_articles.
  • Draft pages:
    • entity: Replaces article.
    • all_entities: Replaces all_articles.
  • Paginated pages (direct templates or tag, category, author pages):
    • entities_paginator: Replaces articles_paginator.
    • entities_page: Replaces articles_page.
    • entities_previous_page: Replaces articles_previous_page.
    • entities_next_page: Replaces articles_next_page.

Deleted variables

  • Entity page:
    • category: Access through entity.category.
  • Direct templates:
    • dates: If you want to iterate in the opposite order do it explicitly.

Example configuration

This is the configuration I’m using on my site:

ENTITY_TYPES = {
    "Page": {
        "PATHS": [""],
        "EXCLUDES": ["blog", "projects"],
        "PAGE_URL": "{slug}",
        "PAGE_SAVE_AS": "{slug}/index.html",
        "PATH_METADATA": r"(?P<slug>[^/]+)/.*",
        "DIRECT_TEMPLATES": ["search"],
        "SEARCH_SAVE_AS": "search/index.html"
    },
    "Article": {
        "PATHS": ["blog"],
        "ARTICLE_URL": "blog/{category}/{slug}/",
        "ARTICLE_SAVE_AS": "blog/{category}/{slug}/index.html",
        "PATH_METADATA": r".*/(?P<category>[^/]+)/(?P<date>\d{4}/\d{2}/\d{2})/(?P<slug>[^/]+)/.*",
        "DIRECT_TEMPLATES": ["blog"],
        "PAGINATED_DIRECT_TEMPLATES": ["blog"],
        "BLOG_SAVE_AS": "blog/index.html",
        "CATEGORY_TEMPLATE": "blog_category",
        "CATEGORY_URL": "blog/{slug}/",
        "CATEGORY_SAVE_AS": os.path.join("blog", "{slug}", "index.html"),
        "FEED_ATOM": os.path.join("blog", "feeds", "atom.xml"),
        "CATEGORY_FEED_ATOM": os.path.join("blog", "feeds", "%s.atom.xml")
    },
    "Project": {
        "PATHS": ["projects"],
        "SORTER": entities.attribute_list_sorter(["date", "project_start"], reverse=True),
        "PROJECT_URL": "projects/{category}/{slug}/",
        "PROJECT_SAVE_AS": "projects/{category}/{slug}/index.html",
        "PATH_METADATA": r".*/(?P<category>[^/]+)/(?P<slug>[^/]+)/.*",
        "DIRECT_TEMPLATES": ["projects"],
        "PAGINATED_DIRECT_TEMPLATES": ["projects"],
        "PROJECTS_SAVE_AS": "projects/index.html",
        "CATEGORY_TEMPLATE": "project_category",
        "CATEGORY_URL": 'projects/{slug}/',
        "CATEGORY_SAVE_AS": os.path.join('projects', '{slug}', 'index.html'),
        "FEED_ATOM": os.path.join("projects", "feeds", "atom.xml"),
        "CATEGORY_FEED_ATOM": os.path.join("projects", "feeds", "%s.atom.xml")
    }
}

For a working example check my site and my site’s source code.

Extending

Available signals

  • entity_generator_init: Initialization of the parent generator. This generator is responsible for creating the generators for each entity type.
  • entity_generator_finalized: End of context generation by the parent generator.
  • entity_writer_finalized: End of output generation by the parent generator.
  • entity_subgenerator_*: Signals for the generator of a particular entity type. These are the same signals used by the article generator.
Release History

Release History

0.2.0

This version

History Node

TODO: Figure out how to actually get changelog content.

Changelog content for this version goes here.

Donec et mollis dolor. Praesent et diam eget libero egestas mattis sit amet vitae augue. Nam tincidunt congue enim, ut porta lorem lacinia consectetur. Donec ut libero sed arcu vehicula ultricies a non tortor. Lorem ipsum dolor sit amet, consectetur adipiscing elit.

Show More

0.1.0

History Node

TODO: Figure out how to actually get changelog content.

Changelog content for this version goes here.

Donec et mollis dolor. Praesent et diam eget libero egestas mattis sit amet vitae augue. Nam tincidunt congue enim, ut porta lorem lacinia consectetur. Donec ut libero sed arcu vehicula ultricies a non tortor. Lorem ipsum dolor sit amet, consectetur adipiscing elit.

Show More

Download Files

Download Files

TODO: Brief introduction on what you do with files - including link to relevant help section.

File Name & Checksum SHA256 Checksum Help Version File Type Upload Date
pelican-entities-0.2.0.zip (20.0 kB) Copy SHA256 Checksum SHA256 Source Jul 29, 2016

Supported By

WebFaction WebFaction Technical Writing Elastic Elastic Search Pingdom Pingdom Monitoring Dyn Dyn DNS HPE HPE Development Sentry Sentry Error Logging CloudAMQP CloudAMQP RabbitMQ Heroku Heroku PaaS Kabu Creative Kabu Creative UX & Design Fastly Fastly CDN DigiCert DigiCert EV Certificate Rackspace Rackspace Cloud Servers DreamHost DreamHost Log Hosting