Permalink
Browse files

temporarily adding old docs

  • Loading branch information...
1 parent 7c29e85 commit c9eb79e4e655f3bd20ecc40eb12b586bf6a9efcd Daniele Procida committed Jun 19, 2011
Binary file not shown.
Binary file not shown.
@@ -0,0 +1,97 @@
+.. py:module:: contacts_and_people
+
+###################
+Contacts and People
+###################
+
+This application will help manage an institution's people, entities and addresses.
+
+It is in a very basic form, and needs to be made considerably more sophisticated, but it works and has useful functionality.
+
+It has four components:
+
+* Sites
+* Addresses
+* Entities
+* People
+
+Briefly, this is how they work.
+
+*****
+Site
+*****
+A site is a collection of Places.
+
+A university might be based at several campuses (sites) each with a number of buildings (Places), for example.
+
+At present, each site has a name, town and country.
+
+*********
+Building
+*********
+
+On each site, there will be one or more buildings, so each building is assigned to a site.
+
+A building has a name and/or number, a street name, an additional address line, and a postal code. Together with the Site, this adds up to the complete postal address for a building.
+
+******
+Entity
+******
+
+An entity is a part of an institution - a faculty, department, office, commitee, helpdesk, section, etc. Entities are arranged in a hierarchy (each entity has a parent until we get to the root of the hieararchy). The hierarchy is managed by MPTT.
+
+Some entities are just abstract entities, i.e. groups of actual entities. For example, we might have an entity called "Departments", the group of all departments.
+
+An entity can be connected to a Page in Django CMS. This way, a Page in CMS can pull in all kinds of information from other databases and publish it automatically.
+
+For example, if a page has been assigned to an entity, a templatetag in it can publish contact details, or lists of members, or appropriate news items, and so on.
+
+Entity names are also used to build the internal or institutional part of an address, for example:
+
+Complaints Department
+Customer Services
+Yoyodyne Corporation
+[...]
+
+An option for an entity is not to display its parent's name. This would be useful where an entity is not needed in to route mail or visitors. It is also useful in cases where we might find ourselves with a silly address like:
+
+[...]
+Department of Anaesthetics
+Cardiff University School of Medicine
+Cardiff University
+
+In such a case, Cardiff University School of Medicine obviously does not want its parent's address published.
+
+Entities can also be external to the institution.
+
+.. automodule:: contacts_and_people.models
+ :members:
+
+******
+Person
+******
+
+People share an abstract model for contact information with entities, and this is used to build the postal part of their address.
+
+In addition, a person has a Home entity, their base within the institution. Memebrship of an entity automatically gives a person membership of all its ancestors too.
+
+They can be added to other entities too, from different parts of the hierarchy. For example a person might belong to several different committees.
+
+A simple templatetag will generate a tree of the entities within the institution, showing only those nodes that a person belongs to.
+
+A person can have a another person assigned to them for contact purposes, so that the other person's contact details are published. This would be useful for when someone is away on leave, or prefers to have communications go through a secretary or assistant.
+
+Also important is the ability to override the person's entity for address purposes. For example, if a person is:
+
+Stanley Koteks
+Top Secret Project
+Research Labs
+Yoyodyne Corporation
+
+it might not be a good idea to publish all that information. Instead, we can override "Top Secret project" and choose something safer ("Research Labs", or even just "Yoyodyne Corporation").
+
+There are many ways in which this application can (and needs to) be developed. However it is ready to use and includes templates and templatetags demonstrating some useful functionality.
+
+Its output can be explored (when the server is up) by starting at:
+
+<http://w128.medcn.uwcm.ac.uk:8001/en/person/mr-daniele-procida/>
@@ -0,0 +1,87 @@
+.. Arkestra documentation master file, created by
+ sphinx-quickstart on Tue May 3 19:31:41 2011.
+ You can adapt this file completely to your liking, but it should at least
+ contain the root `toctree` directive.
+
+########
+Arkestra
+########
+
+This document refers to version |release|
+
+Arkestra is an intelligent, semantic web content management system for organisations and institutions.
+
+It is flexible, modular and extensible, and has a rich set of automated web publishing tools.
+
+Arkestra was developed at `Cardiff University School of Medicine <http://medicine.cardiff.ac.uk/>`_ to provide a platform for the School’s web presence.
+
+=================
+Design principles
+=================
+
+Arkestra has been designed around a number of key principles:
+
+* the system should provide a genuinely semantic framework for information representing the world and work of organisations
+* wherever possible, everything the system publishes should be informed by its semantic model
+* wherever possible, the system should act on information it holds, including implicit information, to minimise the work the web editor must do
+
+===========
+Key modules
+===========
+
+Contacts & people
+=================
+
+Arkestra is an institutional CMS. It maintains and publishes information about people and their relationships with the entities they belong to, and the relationships between institutions and their parts.
+
+News & events
+=============
+
+Arkestra holds information about what’s on, including information about how important news and events items are, and their relevance to different parts of the institution.
+
+The Semantic Presentation editor
+================================
+
+As well as maintaining semantic information rather than just mere data at the highest levels, Arkestra does the same at the level of content editing.
+
+Arkestra has a unique editor, based on the WYMEditor, that:
+
+* creates complex, flexible, multiple-column layouts
+* requires no knowledge of HTML/CSS
+* creates and enforces well-structured semantic HTML
+
+No other web editor can meet more than two of those criteria.
+
+==========
+Django CMS
+==========
+
+Arkestra integrates with the architecture of `Django CMS <http://django-cms.org/>`_.
+
+Arkestra requires Django CMS, and can be installed alongside an existing Django CMS project without affecting it in any way.
+
+====================
+Other Arkestra sites
+====================
+
+Other sites currently running on Arkestra include:
+
+* `The Laugharne Weekend <http://thelaugharneweekend.com/>`_, an annual festival of music and literature in Laugharne, west Wales
+* `Fudoshin Aikido Cardiff <http://aikidocardiff.com/>`_, a Cardiff-based Aikido club
+
+Contents:
+
+.. toctree::
+ :maxdepth: 2
+
+ what_arkestra_does
+ contacts_and_people
+
+
+Indices and tables
+==================
+
+* :ref:`genindex`
+* :ref:`modindex`
+* :ref:`search`
+
@@ -0,0 +1,44 @@
+############
+Installation
+############
+
+===============
+Getting started
+===============
+
+
+
+First, you need to have Django CMS 2 installed and working.
+And get django-widgetry (http://github.com/stefanfoulis/django-widgetry)
+
+
+Place contacts_and_people and news_and_events onto your PYTHONPATH.
+
+Add:
+
+ 'news_and_events',
+ 'contacts_and_people',
+
+to your INSTALLED_APPS.
+
+Add:
+
+ (r"^entity/(?P<slug>[-\w]+)/$", "contacts_and_people.views.entity"),
+ (r"^person/(?P<slug>[-\w]+)/$", "contacts_and_people.views.person"),
+ (r"^news/article/(?P<slug>[-\w]+)/$", "news_and_events.views.newsarticle"),
+ (r"^events/event/(?P<slug>[-\w]+)/$", "news_and_events.views.event"),
+
+ (r'^news/rss/', include('news_and_events.feeds_urls')),
+
+to your urlpatterns = patterns in urls.py.
+
+A syncdb will be required.
+
+
+these rss feeds are available:
+
+/news/rss/latest/ all news
+/news/rss/latest_by_entity/<entity-slug>/ all news entries for the entity
+/news/rss/latest_by_contact_person/<person-slug>/ all news entries where the person is the contact person
+/news/rss/latest_by_related_person/<person-slug>/ all news entries where the person is mentioned in related person
+
@@ -0,0 +1,62 @@
+Generic Links App
+
+The links app allows generic links between any models. You need to add a setting similar to this:
+
+To register specific models that they can be links, a link_schema.py module needs to be created in
+your app. The registry system is comparable with how django.contrib.admin works.
+Every linkable needs a certain list of attributes. Either defined on the model itself or provided with a wrapper.
+A list of the needed attributes is in `links.schema_registry.ATTRIBUTES`. Be aware that 'title' and 'description'
+are also used in the autocomplete widget.
+
+There a multiple ways how you can define a link/wrapper:
+
+`from links import schema
+from news_and_events import models
+from news_and_events import admin`
+
+1. Very simple case. Your model has all the needed attributes already
+
+`schema.register(models.Event, search_fields=admin.EventAdmin.search_fields)`
+
+
+2. The attributes on the model are named different:
+
+`schema.register(models.Event, search_fields=admin.EventADmin.search_fields,
+ title='name', description='some_foreign_key.title', heading='"Event"')`
+
+Each named argument after search_fields represents a attribute the wrapper will have.
+A string means the dot noted path will be used to traverse through object, starting from
+the linked object. `description='some_foreign_key.title'` will result in using
+`theobj.some_foreign_key.title` for the title. It does not matter if the attributes are properties
+or callable methods, both work.
+
+`heading='"Event"'` will use a static string for the heading. Both `"'foo'"` and `'"bar"'` work.
+
+3. You want to do some extra calculation.
+
+This works by providing a callable that takes one argument: the linked object
+It can be a lamda function or a external function
+
+`def some_very_complicated_function(obj):
+ r = []
+ for x in obj.something.all():
+ if x.y:
+ r.append(u"foo: %s" % x.bar)
+ else:
+ r.append(u"stuff: %s" % x.bar)
+ return "<br />".join(r)
+schema.register(models.Event, search_fields=admin.EventAdmin.search_fields,
+ title=lambda obj: u"%s (%s)" % (unicode(obj), obj.active_count),
+ description=some_very_complicated_function)`
+
+
+4. You have a quite complex wrapper: make you own Wrapper subclass
+
+`from links import LinkWrapper
+class MyEventLinkWrapper(LinkWrapper):
+ search_fields = admin.EventAdmin.search_fields
+ def title(self):
+ return self.obj.something(extra=' asdfsadf')
+ def description(self):
+ return "static description"
+schema.register_wrapper(Event, MyEventLinkWrapper)`
@@ -0,0 +1,40 @@
+News and Events for Django CMS
+
+<http://github.com/evildmp/Apps-for-Django-CMS/>
+
+This application will manage and publish news articles and events for an institution.
+
+It requires the Contacts and People application, <http://github.com/evildmp/Contacts-and-people/>.
+
+A News item or Event can be can be attached to one or more Entities of an institution, by setting its Publishing destinations. This way the author of an item can control its distribution across a website.
+
+For example, consider an institution with the following hierarchy of entities:
+
+University of Rummidge
+ Faculty of Humanities
+ Department of English
+ Department of Philosophy
+ [...]
+ [...]
+ Academic Exchange Office
+ [...]
+
+A minor item in the Philosophy Department should be published at the level of the Philosophy department (on its home page or its news/events page, perhaps) but it shouldn't appear outside that. (No-one else is very interested in minor items in the Philosophy department.)
+
+However, if the Department of English is involved in a high-profile academic exchange with Professor Morris Zapp from Euphoria State University, this should certainly go to the Department of English *and* the Academic Exchange Office, and if it's important enough, the Faculty of Humanities too.
+
+A simple templatetag on the home page for each entity can display recent news headlines and event titles; a news/events page for each entity can hold an archive of news/events for that entity.
+
+It is also possible to add metadata to items describing which pages, people and other items they are related to. Uses for this would include:
+
+* links on items directing readers to people mentioned or involved
+* links on news items referring to previous stories on the subject/related events
+* on a person's profile page, lists of news stories/events referring to them
+
+There are many ways in which this application can (and needs to) be
+developed. However it is ready to use and includes templates and
+templatetags demonstrating some useful functionality.
+
+Its output can be explored (when the server is up) by starting at:
+
+<http://w128.medcn.uwcm.ac.uk:8001/news/item/nixon-resigns/>
Oops, something went wrong. Retry.

0 comments on commit c9eb79e

Please sign in to comment.