README

What is it?

Publications is a Xaraya Content Module responsible for the handling of generic and complex content structures.

The Publications is a synthesis of two successful Xaraya modules: Articles (by Michel Dalle) and Xarpages (by Jason Judge), as well as several additional concepts with the aim of making it a full fledged content management system within Xaraya.

It is fully based on dynamic data.
It is built with multilingual content in mind.
It supports functionality typical of web publications (keywords, page titles) directly, rather than relying on add ons.
It focusses on managing content from the UI as far as resonable, rather than through template editing.
It is designed to be simple to use while powerful in its application and easily extendable.

Why another content management module? Publications' predecessors each had their strong points. Articles module was the high end content publication module, while Xarpages was for simple content that could be visualized in a page tree and whose pages could be containers for different types of content. At the time of their writing however, Xaraya lacked a mature data management layer that is dynamic data in its present form. Both Articles and Xarages resorted to custom functionality to fill the holes.

In the meanime, the evolution of Xaraya has made it possible to incorporate more power with less code. The Publications module wants to take the good ideas of its predecessors and push them further.

Concepts

1. Publications

A publication, or page, is a web page generated by the Publications module. It can have

Several chunks of content (title, body, file upload widget, date, calendar etc.). The content makes use of dynamic data's dataproperties for input and display.
Configuration settings that influence the appearance of the content, such as time of publication, links to similar pages, custom templates for display etc.
Configuration settings that define the page's behavior in processes, such as its state or category.
Access settings that define who can read, edit, delete a page or add a new page.

Pages can be arranged in a tree structure and so support a natural navigation scheme in which one page is seen as a "child" of another. Such a structure may be more or less appropropriate for any given site, but it is in many cases a useful fallback.

Pages can alternatively be displayed by their publication type (see below.)

The way a page displays is largely dictated by its state. The publications module supports the following states:

active: the page is displayed to anyone with the proper access.
frontpage: the page is displayed on the "front page" of the site.
inactive: the page is not displayed to most users, but can be modified in the back end.
draft: the page can be "previewed" by selected users.
empty: the page is a placeholder for its children in the pages tree. It is present in navigation, but does not display any content of its own.
deleted: the page is only visible to site administrators. Note: pages are never physically deleted, but rather set to "deleted" state.

2. Publication types

Like its predecessors, the Publications module supports publication types. These represent different types of content to be published. In fact, the 11 preconfigured publication types correspond largely to those of the Articles module (news, documents, downloads etc.). The publications module can manage 'publications' of different types at the same time, for instance news publications, longer documents in different sections, frequently asked questions, and so on.

Each publication type defines a set of pages with common features. The publication type has its own configuration settings, which are inherited by its pages unless specifically overridden. The publication type in turn inherits some settngs, such as access rules, from the global settings of the publications module.

Publication types are fairly flexible. They can be interchanged (e.g. turning a news article type into a documention type) with the caveat that the content of the pages may change in certain cases as a result.

In particular, each publication type has default templates for:

input: the input form used to enter content when creating or modifying a page.
summary display: the display template used when a group of publications are displayed together, such as a listing of news articles.
detail display: the template used to display a single page.

Since publication types are in their core dynamic data objects, it is fairly easy to create new types. This involves cloning an existing type (usually the so called generic publication type), and its templates, and modifying appropriately.

3. Translations

The Publications module supports different locales/languages. These are not the locales supported by the Xaraya core, but rather can be defined independently by the languages dataproperty. This allows the module to include content in languages the site as a whole does not need to have defined.

Each page can have translations in as many different languages as are supported. A translation is simply another page of the same publication type that is a "child" of a given page, and usually contains the same content but in a different language.

Translations are ignored by the tree structure or list displays and only display when the parent page is modfieid. Which translation of a page will be displayed to the viewer depends as usual on the language chosen through the Roles languages block. If a translation is not available in a given language, the parent page is displayed.

4. Categories

Publications (of any type) can be organised into categories. You could use one or more common categories across different publication types, or use specific categories for each type of article, or any combination that you might prefer for your site.

Before you start specifying which article types will be using what categories, you should create the categorization you want via the Categories administration menu. A default set of categories has been defined for publications when you installed this module, as an example to get you started. (You can adapt the categories later on, of course.)

Once you have a set of categories you would like to use for your publications, you can go to Publications Configuration, and specify the number of categories that can be used for each publication type, and the 'base categories' to be used.

A 'base category' is any starting point somewhere in your tree of categories, below which you will have the actual list (or subtree) of categories people can choose from when they submit or view publications. For example, you could have a 'base category' called Topics, with a list of different topics relevant to your site below it, and another 'base category' called Cities, with a list of cities or places that you would provide regional news for.

One topic might be 'Good Restaurants', and one city might 'Brussels', so people would be able to browse through any publications about good restaurants in Brussels, for instance.

3. Submitting or adding publications

state = submitted, rejected, approved or on frontpage (for those pubtypes that use it !)

4. Managing the overview and display of publications per publication type

In Publications Configuration, set start view (list/browse), ## of columns and items, show category links + ## of comments (+ performance impact)

+ adapt specific templates!

5. Managing your 'front page'

cfr. frontpage state and ## of columns and items - needs to be extended

6. Adding counters, ratings, comments, smilies, bb-code etc.

cfr. hooks + special note on counters

7. Organising permissions

this really needs a permissions wizard

8. Short URL support

overall enable/disable in 'base' admin + specific enable/disable in 'publications' admin + use of module aliases

Module aliases seem to be disabled at the moment - uncomment the line in includes/xarServer.php if you want to try it out

Included Blocks

featured items
glossary
random
related
top items

Included Hooks

Search hook which provides the functionality to search your individual publications.

xaraya / publications

Maintainers

Details