Package: django-ikari
Django Anchored Domains==========================django-ikari is an application for anchoring configurableurlconfs to user configurable subdomains or domains to usein software-as-a-service projects.Table of Contents=================1 Installation2 Settings3 Models3.1 Permissions4 Middleware5 Views6 URLs7 Templates8 License1 Installation~~~~~~~~~~~~~~Copy or symlink `ikari/' subdirectory to Python path (`setup.py'script for automated installation will be supplied later on). Modulecontents are available in the `domains' module.In order to use application, add `domains' to INSTALLED_APPS inDjango project `settings.py' file,`domains.middleware.DomainsMiddleware' to MIDDLEWARE_CLASSESafter `AuthenticationMiddleware', and configure application settingsdescribed in the next section.2 Settings~~~~~~~~~~Following Django settings are read by the application:- `DOMAINS_ACCOUNT_URLCONF' - if set, `request.urlconf' is set tothis value when Domain's domain is accessed.  This breaksdjango-debug-toolbar and misleads reverse URL resolver (mainurlconf is always used for reverse URL resolving).- `DOMAINS_DEFAULT_DOMAIN' - Default domain name, on which "main"(non-user) site is hosted.  Used to prevent redirection to`DOMAINS_DEFAULT_URL' when `DomainsMiddleware' is used bothon accounts' sites and main site.  Also used to construct defaultvalue of `DOMAINS_DEFAULT_URL' when it is not set.- `DOMAINS_DEFAULT_URL' - URL to redirect to when user agentrefers to site with an unknown domain (not registered in any ofaccounts).  When not set, a URL is constructed from`DOMAINS_DEFAULT_DOMAIN' or current Site object's domain and`DOMAINS_PORT'.- `DOMAINS_IP' - if set, value is used to verify custom domainsin `DomainForm'.  It can be set to a string (literal'aa.bb.cc.dd' value that is compared to `sockets.gethostbyname()'result), or, for more complex deployments, it can be a functionthat will receive IP as returned by `sockets.gethostbyname()'- `DOMAINS_PORT' - can be set to custom port that will be used inDomain site URLs.  This way, developer can successfully useDomains on e.g. 127.0.0.1:8000.- `DOMAINS_ROOT_DOMAIN' - root domain for subdomains (with orwithout leading dot).  Must be set.- `DOMAINS_SUBDOMAIN_STOPWORDS' - tuple of regular expressions([http://docs.python.org/library/re.html]) that cannot be used assubdomain names.  Default is `("^www$",)'.  Use this to stop usersfrom e.g. using reserved domain names or using profanities astheir domain name.  Expressions are tested using `re.search', not`re.match', so without using `^' anchor they can match anywhere inthe domain name.- `DOMAINS_THEMES' - a sequence of (codename, name) pairsindicating available themes for user sites.- `DOMAINS_USE_SSO' - use django-sso when redirecting user tonewly created site.  Default is True if django-sso is available,False otherwise.- `DOMAINS_USERSITE_URLCONF' - name of URLconf module for usersites.  This is used by Domain instances' get_absolute_url()method.3 Models~~~~~~~~Application defines one model, `Domain'.  Model has three fields:- `owner', OneToOneField reference to`django.contrib.auth.models.User' model, which holds user owningthe account;- `members', ManyToManyField reference to`django.contrib.auth.models.User' model, which holds accountmembers;- `domain', name of custom full domain for the site, changeable byuser;- `subdomain', a sub-domain of `DOMAINS_ROOT_DOMAIN', noteditable by user;- `is_public', boolean.  If True (default), DomainMiddleware willallow any `auth.User' to log in to Domain's account; if False,only users that are Domain members will be allowed;Class has one class attribute, `subdomain_root', which contains rootfor subdomains as in `DOMAINS_ROOT_DOMAIN' setting description,always with leading dot.  This attribute should not be written.Model defines `get_absolute_url(path = '/', args = (), kwargs = {})'method, which returns link to configured domain([http://subdomain.root_domain/path] if `domain' is None,[http://domain/path] otherwise).  Optional path can be either anabsolute path or, if `settings.DOMAINS_USERSITE_URLCONF' is set,a name, args and kwargs for reverse URL lookup.Two methods are defined, `add_member(user)' and`remove_member(user)' to respectively add or remove `user' from`members' and send out `domains.signals.add_member' or`domains.signals.remove_member' with additional `user'parameter.3.1 Permissions===============- `can_set_custom_domain' enables setting `is_subdomain' to `True'by the account owner.  If Domain owner does not have suchpermission, `account_detaul' view hides checkbox for`is_subdomain', and on form validation `is_subdomain' field isunconditionally set to `True';- `can_set_public_status' does the same for `is_public' field.4 Middleware~~~~~~~~~~~~`domains.middleware.DomainsMiddleware' looks at`request.META['HTTP_HOST']' and, if it matches any `Domain' modelinstance:- sets `request.domain' to that instance (it can be later used byviews and, with `request' context processor, in templates);- immediately logs out (and redirects to reverse URL lookup of`domains_not_a_member') any `auth.models.User' that is not thisaccount's owner or memeber, unless `request.domain.is_public'is true;- if `DOMAINS_ACCOUNT_URLCONF' setting is set, sets`request.urlconf' to its value, allowing single project to displaydifferent URL hierarchies for main site and account sites;*WARNING*: setting `request.urlconf' doesn't fit well with reverseURL lookups (those will still be made against root urlconf),django-debug-toolbar, and probably other things as well. Formaximum reliability, consider running two separate projects onsingle database: one for "main" site, other for account domains,or use single urlconf for both;- send signal `domains.signals.domain_request' and if anyreceiver returns an instance of `HttpResponse', returns thisresponse instead of actual page.  This can be used fore.g. displaying error message and not allowing to log into expiredaccounts.If current domain doesn't match any of existing Domain instancesand is not `DOMAINS_DEFAULT_DOMAIN', middleware redirects user to`DOMAINS_DEFAULT_DOMAIN'.5 Views~~~~~~~- `domains.views.create_account' - if logged in user does nothave a Domain, displays a form to create a new one or acceptsresults of this form.  After accepting form and creating newaccount, redirects user to that account, using django-sso ifavailable.  It is not configured in default `urls.py' and shouldbe added directly in main site's urlconf.- `domains.views.account_detail' - displays using`domains/account_detail.html' template and validates`domains.forms.DomainForm' form, which enables user toconfigure account's domain.  In supplied `urls.py' this view isnamed `domains_account_detail'.- `domains.views.claim_account' - if `domain.owner' is NULL,logged in user can "claim" the account, i.e. click a buttondirecting to this view, which will send an e-mail to`settings.MANAGERS'.  This view should be called with a POSTrequest.  In default `urls.py' this view is named`domains_claim_account'.- `domains.views.remove_member' - for Domain_owner, with`user_id' parameter set, this post will remove user with suppliedID from the member list.  This view should be called with a POSTrequest.  In default `urls.py' this view is called`domains.views.remove_member'.6 URLs~~~~~~In supplied urlconf, `domains.urls', one external URL isconfigured: root for `account_detail' view.  More URLs areconfigured for various POST actions.  This is intended to beincluded in the subdomain sites' urlconf.In main site a link to create account form should be used.  Accountis created by view `domains.views.create_account'.  Sampleurlconf line is:(r'^accounts/create-site/$', 'domains.views.create_account'),7 Templates~~~~~~~~~~~Application in default setup needs two templates:- `domains/account_detail.html' called by `account_detail' view.Receives two arguments:- `object' - edited Domain instance, and- `form' - DomainForm instance to display.- `domains/create_account.html' called by `create_account' view.Receives one argument, `form', holding an instance ofDomainCreateForm.- `domains/claim_account_subject.txt' and`domains/claim_account_email.txt' - these templates are used by`claim_account' view to create an e-mail to MANAGERS.  Thistemplates receive three arguments:- `user' - user that is sending the claim,- `domain' - an account that is claimed,- `site' - `sites.Site' object for current site.8 License~~~~~~~~~~This project is licensed on terms of GPL (GPL-LICENSE.txt) licenses.