This documentation file is automatically generated and kind of ugly. It will be more organized later.
This module creates the item type framework, and defines the core item types.
An AIMContactMethod is a ContactMethod that specifies an AIM screen name.
alias of AIMContactMethodVersion
An AddressContactMethod is a ContactMethod that specifies a physical address (or mailing address).
alias of AddressContactMethodVersion
This item type represents an agent that can “do” things. Often this will be a person (see the Person subclass), but actions can also be performed by other agents, such as bots and anonymous agents.
Agents are unique in the following ways:
alias of AgentVersion
This item type is the agent that users of Deme authenticate as by default.
Because every action must be associated with a responsible Agent (e.g., updating an item), we require that users are authenticated as some Agent at all times. So if a user never bothers logging in at the website, they will automatically be logged in as an AnonymousAgent, even if the website says “not logged in”.
There should be exactly one AnonymousAgent at all times.
alias of AnonymousAgentVersion
This item type represents an Agent’s credentials to login.
For example, there might be a AuthenticationMethod representing my Facebook account, a AuthenticationMethod representing my WebAuth account, and a AuthenticationMethod representing my OpenID account. Rather than storing the login credentials directly in a particular Agent, we allow agents to have multiple authentication methods, so that they can login different ways. In theory, AuthenticationMethods can also be used to sync profile information through APIs. There are subclasses of AuthenticationMethod for each different way of authenticating.
alias of AuthenticationMethodVersion
A Collection is an Item that represents an unordered set of other items.
Collections just use pointers from Memberships to represent their contents, so multiple Collections can point to the same contained items.
Collections “directly” contain items via Memberships, but they also “indirectly” contain items via chained Memberships (see the RecursiveMembership model). If Collection 1 directly contains Collection 2 which directly contains Item 3, then Collection 1 indirectly contains Item 3.
It is possible for there to be circular memberships. Collection 1 might contain Collection 2 and Collection 2 might contain Collection 1. This will not cause any errors: it simply means that Collection 1 indirectly contains itself.
alias of CollectionVersion
Return a QuerySet for all items that are either directly or indirectly contained by self (using RecursiveMembership).
If a recursive_filter is specified, use it to filter which RecursiveMemberships can be used to infer an item’s membership in this collection. Often, one will use a permission filter so that only those RecursiveMemberships that the Agent is allowed to view will be used.
A Comment is a unit of discussion about an Item.
Each comment specifies the commented item and version number. Like Document, Comment is meant to be abstract, so developers should always create subclasses rather than creating raw Comments.
Currently, users can only create TextComments.
alias of CommentVersion
Return the original comment at the top of this thread. If this already the topmost comment (i.e. it is a comment on a non-comment item), just return self.
For example, imagine self is comment A, and A is a reply to comment B, and B is a reply to non-comment item C. This method would return B. This method uses the RecursiveComment table.
A ContactMethod belongs to an Agent and contains details on how to contact them. ContactMethod is meant to be abstract, so developers should always create subclasses rather than creating raw ContactMethods.
alias of ContactMethodVersion
A CustomUrl is a ViewerRequest that represents a specific path.
Each CustomUrl has a parent ViewerRequest (it will be the Site if this CustomUrl is the first path component) and a string for the path component. So when a user visits http://example.com/abc/def/ghi, Deme looks for a CustomUrl with name “ghi” with a parent with name “def” with a parent with name “abc” with a parent Site with hostname “example.com”.
alias of CustomUrlVersion
This item type stores global settings for the Deme installation.
Each DemeSetting has a unique key and an arbitrary value. Since values are strings of limited size, settings that involve a lot of text (e.g., a default layout) should have a value pointing to an item that contains the data (e.g., the id of a document).
alias of DemeSettingVersion
Return the value of the DemeSetting with the specified key, or None if it is inactive or no such DemeSetting exists.
Set the DemeSetting with the specified key to the specified value, such that the agent is the creator. This may result in creating a new DemeSetting, updating an existing DemeSetting, or reactivating an inactive DemeSetting.
This item type is a TextDocument that stores Django template code. It can display a fully customized page on Deme. This is primarily useful for customizing the layout of some or all pages, but it can also be used to make pages that can display content not possible in other Documents.
alias of DjangoTemplateDocumentVersion
A Document is an Item that is meant can be a unit of collaborative work.
Document is meant to be abstract, so developers should always create subclasses rather than creating raw Documents.
alias of DocumentVersion
This table contains information on all items currently being edited. This allows us to lock items to prevent simultaneous editing.
An EmailContactMethod is a ContactMethod that specifies an email address.
alias of EmailContactMethodVersion
An Excerpt is an Item that refers to a portion of another Item (or an external resource, such as a webpage).
Excerpt is meant to be abstract, so developers should always create subclasses rather than creating raw Excerpts.
alias of ExcerptVersion
A FaxContactMethod is a ContactMethod that specifies a fax number.
alias of FaxContactMethodVersion
A FileDocument is a Document that stores a file on the filesystem (could be an MP3 or a Microsoft Word Document). It is intended for all binary data, which does not belong in a TextDocument (even though it is technically possible).
Subclasses of FileDocument may be able to understand various file formats and add metadata and extra functionality.
alias of FileDocumentVersion
A folio is a special collection that belongs to a group.
alias of FolioVersion
A group is a collection of Agents.
A group has a folio that is used for collaboration among members.
alias of GroupVersion
This item type is an Agent that acts on behalf of an entire group. It can’t do anything that other agents can’t do. Its significance is just symbolic: by being associated with a group, the actions taken by the group agent are seen as collective action of the group members. In general, permission to login_as the group agent will be limited to powerful members of the group.
There should be exactly one GroupAgent for every group.
alias of GroupAgentVersion
An HtmlDocument is a TextDocument that renders its body as HTML.
alias of HtmlDocumentVersion
An ImageDocument is a FileDocument that stores an image.
Right now, the only difference is that viewers know the file can be displayed as an image. In the future, this may add metadata like EXIF data and thumbnails.
alias of ImageDocumentVersion
Superclass of all item types.
Since everything is an item, this item type provides a unique id across all items. This item type also defines some important common structure to all items, such as name, description, and details about its creation and last update.
Every subclass should define the following attributes:
alias of ItemVersion
Return the actual item type for this item as a class (not a string).
For example, Item.objects.get(pk=1).actual_item_type() == Agent
Return all active Comments made directly or indirectly on self.
Return a frozenset of the names of all the fields that are immutable for this item type (recursively traverses through item type hierarchy).
Return a QuerySet including self and all direct and indirect parents in this thread. If self is a Comment, this will return self, the parent, the grandparent, so on up to (and including) the original item. If self is not a Comment, this should only self (unless include_parent_collections is True as explained below).
If include_parent_collections=True, also include all Collections containing self or parents in this thread, either through direct or indirect membership. If a recursive_filter is specified, use it to filter which RecursiveMemberships can be used to infer an item’s membership in this collection. Often, one will use a permission filter so that only those RecursiveMemberships that the Agent is allowed to view will be used.
Return all active Collections containing self directly or indirectly.
A Collection does not indirectly contain itself by default.
If a recursive_filter is specified, use it to filter which RecursiveMemberships can be used to infer self’s membership in a collection. Often, one will use a permission filter so that only those RecursiveMemberships that the Agent is allowed to view will be used.
Given a field_dict from field names to initial values, populate any other fields (in the dict) with values. For example, in a Subscription, given that the subscribed item is X, we might want to set the name of the subscription to “Subscription to X”. This is used when presenting a user with a form.
Item types that want to automatically populate field names based on other fields should override this method, making sure to put a call superclasses at the top, like: >> super(Subscription, cls).auto_populate_fields(item_type, field_dict, viewer)
This method returns False for special items that should never be deleted, such as the AnonymousAgent; and it returns True for ordinary items.
Item types that want to define special items should override this method.
Set the fields of self to what they were at the given version number. This method does not make any database writes.
Sets the fields of the itemversion from self’s fields. This method does not make any database writes.
This method may use self.version_number to calculate a delta (although it does not currently).
Deactivate the current Item (the specified agent was responsible with the given summary at the given time). This will call _after_deactivate if the item was previously active.
Nullify the fields of this item (the specified agent was responsible with the given summary at the given time) and delete all versions. The item must already be inactive and cannot have already been destroyed. This will call _after_destroy.
Return a friendly display name for the item.
If the item has a blank name field, return a string of the form “ItemType id” (like Agent 1). Otherwise, just return the value of the name field.
If can_view_name_field is False, only return the “ItemType id” form.
Perform any specialized configuration for a Django form. The is_new parameter is True if the form is creating a new item, and is False if the form is updating an existing item. The attrs parameter is the list of class attrs that are about to be passed into the forms.models.ModelFormMetaclass constructor.
This function should modify the attrs dictionary in order to configure the form.
Item types that want to configure the default Django form in a special way should override this method, making sure to put a call superclasses at the top, like: >> super(Membership, cls).do_specialized_form_configuration(item_type, is_new, attrs)
Return this item as an instance of the actual item type.
For example, if the current item is an Agent, this will return an Agent, even though self is an Item.
When the type of self is the actual item type, this returns self (not a copy); otherwise, this makes a single database query and returns an instance of the actual item type.
Return the name of the default viewer. If the default_viewer field is invalid, returns the item type’s default viewer.
Return true if this item is instantiated at the actual item type.
For example, if item 123 is an agent, then: Agent.get(pk=123).is_downcast() == true Item.get(pk=123).is_downcast() == false
Return the original item that was commented on in this thread. If this is not a Comment, just return self.
For example, if this is a reply to a reply to a comment on X, this method will return X. This method uses the RecursiveComment table.
Reactivate the current Item (the specified agent was responsible with the given summary at the given time). This will call _after_reactivate if the item was previously inactive.
Return a natural language representation of a RelationActionNotice with the given parameters, such that the from_item is self. The result will be in the form of a list of strings and items. The string representation can later be formed by concatenating the elements of the list, using the strings and relevant fields of the items. Remember to include spaces in the strings so that there is space around the item name. If field_name does not match any of the foreign keys for the item type, return None.
Save the current item (the specified agent was responsible with the given summary at the given time), making sure to keep track of versions.
Use this method instead of save() because it will keep things consistent with versions and special fields. This will set created_at to the current time (or action_time parameter) if this is a creation.
If first_agent=True, then this method assumes you are creating the first item (which should be an Agent). It is necessary to save the first item as an Agent in this way so that every Item has a valid creator pointer.
If the initial_permissions parameter is given, it should be a list of unsaved Permissions. After successfully saving self, this method will save these permissions (setting permission.target = self) before calling any callbacks.
This will call _after_create or _after_edit, depending on whether the item already existed.
Set the error message function for uniqueness constraint violations, so that when it is displayed, it links to the item it clashes with (and provides a quick link to overwrite it).
A Membership is a relationship between a collection and one of its items.
alias of MembershipVersion
A Person is an Agent that represents a person in real life.
alias of PersonVersion
A PhoneContactMethod is a ContactMethod that specifies a phone number.
alias of PhoneContactMethodVersion
This table contains all pairs (item, comment) such that comment is directly or indirectly a comment on item.
For example if A is an Item, B is a Comment on A, and C is a comment on B, then this table will contain (A,B) (B,C) and (A,C).
Update the table to reflect that the given comment was created.
Update the table to reflect that the given comment was destroyed.
This table contains all pairs (collection, item) such that item is directly or indirectly a member of collection.
Each RecursiveMembership row also contains a many-to-many set of Memberships (child_memberships) such that there exists an path of memberships from the child to the parent where the first membership in the path is in child_memberships.
When Collections or Memberships are deactivated, this table is updated as if the Collection or Membership did not exist.
For example if A is a Collection, and B is a Collection (which is a member of A), and C is an Item (which is a member of B), and D is an Item (which is a member of A and B), then the table will contain:
(A,B) child_memberships={(A,B)} (B,C) child_memberships={(B,C)} (A,C) child_memberships={(B,C)} (A,D) child_memberships={(A,D),(B,D))} (B,D) child_memberships={(B,D)}
The permission_enabled field is set to True if there exists at least one path of Memberships from parent to child, such that each membership in the path has permission_enabled=True.
Update the table to reflect that the given collection was created or reactivated.
Update the table to reflect that the given membership was created (or reactivated).
Update the table to reflect that the given collection was deactivated.
Update the table to reflect that child is no longer directly a member of parent.
A Site is a ViewerRequest that represents a logical website with URLs.
Multiple Sites on the same Deme installation share the same Items with the same unique ids, but they resolve URLs differently so each Site can have a different page for /mike. If you go to the base URL of a site (like http://example.com/), you see the ViewerRequest that this Site inherits from.
alias of SiteVersion
A Subscription is a relationship between an Item and a ContactMethod, indicating that all action notices on the item should be sent to the contact method as notifications.
If deep=True and the item is a Collection, then action notices on all items in the collection (direct or indirect) will be sent in addition to comments on the collection itself.
The subscribe_edit, subscribe_delete, subscribe_comments, and subscribe_relations fields determine what action notices will trigger this subscription.
alias of SubscriptionVersion
A TextComment is a Comment and a TextDocument combined. It is currently the only form of user-generated comments.
alias of TextCommentVersion
A TextDocument is a Document that has a body that stores arbitrary text.
alias of TextDocumentVersion
A TextDocumentExcerpt refers to a contiguous region of text in a version of another TextDocument in Deme.
The body field contains the excerpted region, and the start_index and length identify the character position of this region within the specified TextDocument.
alias of TextDocumentExcerptVersion
A Transclusion is an embedded reference from a location in a specific version of a TextDocument to another Item.
alias of TransclusionVersion
A ViewerRequest represents a particular action at a particular viewer (basically a URL, although its stored more explicitly). It specifies a viewer (just a string, since viewers are not Items), an action (like “view” or “edit”), an item that is referred to (or null for collection-wide actions), a query_string if you want to pass parameters to the viewer, and a format.
A ViewerRequest is supposed to be abstract, so users can only create Sites and CustomUrls.
alias of ViewerRequestVersion
Return a tuple (site, custom_urls) where custom_urls is a list.
A WebsiteContactMethod is a ContactMethod that specifies a website URL.
alias of WebsiteContactMethodVersion
Return a list of every item type (as a class).
Return the item type class with the given name (case-sensitive or not, as specified), or return None if there is no item type with the name.
An ActionNotice is a model (not a subclass of Item) that records an action happening in Deme. ActionNotice is meant to be abstract, so only subclasses should ever be created.
Return an EmailMessage with the notification that should be sent to the specified EmailContactMethod. If there is no Subscription, or the Agent with the subscription is not allowed to receive the notification, return None.
Return the item that comments created about this notice (via replying to a notification email for this notice) are replies to.
A RelationActionNotice is created on an item whenever another item (the “from item”) is created or modified so that one of its foreign-key fields now points to the item (when it didn’t before) or no longer points to the item (when it did before).
If relation_added is true, it means that the from item did not point before but now does; and if relation_added is false, it means that from item did point before but no longer does.
This method should be called whenever an item is created, edited, deactivated, or reactivated. It generates all relevant RelationActionNotices relevant to the action.
The flags existed_before and existed_after are used to indicate what the action did to the item. If the item was reactivated or created, existed_before would be false, otherwise it would be true. If the item was deactivated, existed_after would be false, otherwise it would be true.
In RelationActionNotices, when someone replies to a notification, it should be turned into a comment on from_item, not item.
For example, if we have a RelationActionNotice with from_item=membership and item=agent, the reply comment should go to membership, not agent.
A DeactivateActionNotice is generated whenever someone deactivates an item.
A ReactivateActionNotice is generated whenever someone reactivates an item.
A DestroyActionNotice is generated whenever someone destroys an item.
A CreateActionNotice is generated whenever someone creates an item.
An EditActionNotice is generated whenever someone edits an item.
This is a modified NullBooleanField that uses a checkbox-style FormField. This is used to replace BooleanFields that are normally not supposed to have a null options, but are allowed to have null options for the purpose of deleting items. Because Django SVN revision r10456 made it so BooleanFields cannot be null, we have to use this instead.
Returns a suitable description of this field for South.
This is a modified ForeignKey that specifies the abilities required to modify the field. The abilities must be had by the action agent on the pointee.
Returns a suitable description of this field for South.
Abstract superclass of all permissions.
Permissions from individual agents to individual items.
Permissions from individual agents to collections of items.
Permissions from individual agents to all items.
Permissions from collections of agents to individual items.
Permissions from collections of agents to collections of items.
Permissions from collections of agents to all items.
Permissions from all agents to individual items.
Permissions from all agents to collections of items.
Permissions from all agents to all items.
Return a friendly name string for the given ability, or None if not found.