Tutorial

Tutorial

Back to Snip <-- Previous Change | Next Change -->

Diff Summary
Title
Date	2008-04-19 11:23:09	2012-03-17 18:36:50
Editor	Herbert Poul	Herbert Poul
Tags

	2008-04-19 11:23:09 by Herbert Poul			2012-03-17 18:36:50 by Herbert Poul
n	1	**If you want to get started with SCT quickly, ple	n	1	This is a simple tutorial what it needs to configu
	>	ase use the CommunityDraft project instead.*		>	re a simple Forum and Wiki for your website. It wa
	>	*		>	lks you through creating a new project and than ad
				>	ding the necessary confugration changes to integra
				>	te Forum and Wiki. These should be quite the same
				>	steps required to add it to your own website or an
				>	existing project.
	2			2
	3			3
n	4	This describes what is needed to start a new proje	n	4	# Creating a new simple Django project
	>	ct from scratch which uses the Board and Wiki of S
	>	CT.
	5			5
n	6	It actually contains just a couple of notes i wrot	n	6	You should already know how to do this, it's just
	>	e down while creating the communitytools/examples/		>	a standard django setup, but i'll still walk throu
	>	simpleproject - project ;) (See SimpleProject)		>	gh all steps. I am using Django 1.4 here. (Django
				>	1.4 has a significantly different default project
				>	setup)
	7			7
n	8	To get a full featured website see CommunityDraft	n	8	## Create a new project
	>	which should work out of the box.
	9			9
n	10	# Prerequisites	n	10	$ django-admin.py startproject simpleproject
	11
	12	Make sure you've done everything mentioned in the
	>	INSTALLATION section of the README or on the [Docu
	>	mentation] site.
	13			11
	14			12
n	15	# Creating a new project	n	13	## Configuring project to get it up and running
	16			14
n	17	Good, this was easy ;)	n	15	First of all, since i don't want to commit my data
				>	base settings into subversion i'll create a simple
				>	project/settings_local.py and include it at the en
				>	d of my simpleproject/settings.py:
				16
				17	# settings_local overwrites a few settings fro
				>	m here, and has to define SECRET_KEY
				18	from simpleproject.settings_local import *
	18			19
n	19	kahless@localhost ~/dev/python-new/communityto	n	20	my simpleproject/settings_local.py contains:
	>	ols/examples $ django-admin.py startproject simple
	>	project
	20	kahless@localhost ~/dev/python-new/communityto
	>	ols/examples $
	21			21
	22			22
n	23	# Configuring project to get it up and running	n	23	DATABASES = {
				24	'default': {
				25	'ENGINE': 'django.db.backends.sqlite3'
				>	, # Add 'postgresql_psycopg2', 'mysql', 'sqlite3'
				>	or 'oracle'.
				26	'NAME': 'test.sqlite',
				>	# Or path to database file if using sqlite3.
				>
				27	'USER': '', # Not
				>	used with sqlite3.
				28	'PASSWORD': '', # Not
				>	used with sqlite3.
				29	'HOST': '', # Set
				>	to empty string for localhost. Not used with sqli
				>	te3.
				30	'PORT': '', # Set
				>	to empty string for default. Not used with sqlite
				>	3.
				31	}
				32	}
	24			33
n	25	First of all, since i don't want to commit my data	n	34	now you can run syncdb:
	>	base settings into subversion i'll create a settin
	>	gs_local.py ...
	26	This needs two things..
	27			35
n	28	- add the current path to pythons lib search path	n	36	Herbys-i7:simpleproject herbert$ ./manage.py s
				>	yncdb
	29	- import all settings from the settings_local modu		37	Creating tables ...
	>	le
	30
	31	so at the end of settings.py add:
	32
	33	import os
	34	ROOT_PATH = os.path.dirname(os.path.abspath(__
	>	file__))
	35	LIB_PATH = os.path.join(ROOT_PATH, '..', '..',
	>	'sphenecoll')
	36	# import directory of settings.py
	37	import sys
	38	sys.path.append(ROOT_PATH)
	39
	40	# settings_local overwrites a few settings fro
	>	m here, and has to define SECRET_KEY
	41	from settings_local import *
	42
	43	Now simply create a settings_local.py in the same
	>	directory and configure all DATABASE_ settings.
	44
	45	And run syncdb:
	46
	47	kahless@localhost ~/dev/python-new/communityto
	>	ols/examples/simpleproject $ ./manage.py syncdb
	48	Creating table auth_message		38	Creating table auth_permission
				39	Creating table auth_group_permissions
	49	Creating table auth_group		40	Creating table auth_group
n			n	41	Creating table auth_user_user_permissions
				42	Creating table auth_user_groups
	50	Creating table auth_user		43	Creating table auth_user
n	51	Creating table auth_permission	n
	52	Creating table django_content_type		44	Creating table django_content_type
	53	Creating table django_session		45	Creating table django_session
	54	Creating table django_site		46	Creating table django_site
n	55		n	47
	56	You just installed Django's auth system, which		48	You just installed Django's auth system, which
	>	means you don't have any superusers defined.		>	means you don't have any superusers defined.
	57	Would you like to create one now? (yes/no): ye		49	Would you like to create one now? (yes/no): ye
	>	s		>	s
n	58	Username (Leave blank to use 'kahless'): kahle	n	50	Username (leave blank to use 'herbert'):
	>	ss
	59	E-mail address: herbert.poul@gmail.com		51	E-mail address: a@b.com
	60	Password:		52	Password:
	61	Password (again):		53	Password (again):
	62	Superuser created successfully.		54	Superuser created successfully.
n	63	Installing index for auth.Message model	n	55	Installing custom SQL ...
	64	Installing index for auth.Permission model		56	Installing indexes ...
	65	kahless@localhost ~/dev/python-new/communityto		57	Installed 0 object(s) from 0 fixture(s)
	>	ols/examples/simpleproject $
	66			58
n	67	So ... your default django project should already	n	59	Because i am on Mac OSX i got the "ValueError: unk
	>	run ....		>	nown locale: UTF-8" error, so i actually ran:
	68			60
n	69	kahless@localhost ~/dev/python-new/communityto	n	61	LC_CTYPE="en_US.UTF-8" ./manage.py syncdb
	>	ols/examples/simpleproject $ ./manage.py runserver
	>
				62
				63	but i don't think this should be necessary often..
				>
				64
				65	Ok, now after our syncdb the default django projec
				>	t should be stable and we can run it:
				66
				67
				68	Herbys-i7:simpleproject herbert$ ./manage.py r
				>	unserver
	70	Validating models...		69	Validating models...
n			n	70
	71	0 errors found.		71	0 errors found
	72
	73	Django version 0.96-pre, using settings 'simpl		72	Django version 1.4b1, using settings 'simplepr
	>	eproject.settings'		>	oject.settings'
	74	Development server is running at http://127.0.		73	Development server is running at http://127.0.
	>	0.1:8000/		>	0.1:8000/
	75	Quit the server with CONTROL-C.		74	Quit the server with CONTROL-C.
	76			75
n	77	Uh yeah .. not that new, is it ;)	n	76	I guess this was not too exciting for anyone, sinc
				>	e you already use django, so let's go ahead!
	78			77
n	79	# Adding 'Sphene Community Tools' Applications	n	78	# Sphene Community Tools
	80			79
n	81	So now it is time to add the SCT applications. Fir	n	80	## Installation
	>	st of all we need to add the python library path.
	>	You might want to configure it in your mod_python
	>	config, or where ever .. since i want to keep it s
	>	imple and i actually have my project under 'commun
	>	itytools' .. i can simply include ../../
	82			81
n	83	So let's add the following to settings.py right af	n	82	First of all you have to install SCT (the communit
	>	ter were we added sys.path.append(ROOT_PATH):		>	ytools project) - you can either download it and r
				>	un setup.py or use the GIT version from https://gi
				>	thub.com/hpoul/sct-communitytools
	84			83
n	85	sys.path.append(LIB_PATH)	n	84	I usually prefer to have the GIT version, so i che
				>	cked it out into the same directory and added the
				>	'sct-communitytools/sphenecoll' path to the PYTHON
				>	_PATH.
	86			85
n	87	Now look for your INSTALLED_APPS setting and add t	n	86	## Project Configuration
	>	he default django admin application as well as the
	>	three SCT apps .. all in all it should look like:
	>
	88			87
n	89	INSTALLED_APPS = (	n	88	Add the following applications to your INSTALLED_A
				>	PPS:
	90	'django.contrib.auth',		89
	91	'django.contrib.contenttypes',
	92	'django.contrib.sessions',
	93	'django.contrib.sites',
	94
	95	'django.contrib.admin',
	96
	97	'sphene.community',		90	'sphene.community',
	98	'sphene.sphboard',		91	'sphene.sphboard',
	99	'sphene.sphwiki',		92	'sphene.sphwiki',
n	100	)	n
	101			93
n	102	# Adding MIDDLEWARE_CLASSES and TEMPLATE_CONTEXT_P	n	94	## Adding MIDDLEWARE_CLASSES and TEMPLATE_CONTEXT_
	>	ROCESSORS		>	PROCESSORS
	103			95
n	104	SCT (currently) needs at least two middleware clas	n
	>	ses and two template context processor .. All in a
	>	ll the two settings should look like the following
	>	in your settings.py:
	105			96
n	106	MIDDLEWARE_CLASSES = (	n	97	SCT (currently) needs at least two middleware clas
				>	ses and one template context processor. Add the fo
				>	llowing to middlewares to the TOP of your MIDDLEWA
				>	RE_CLASSES:
				98
	107	'sphene.community.middleware.ThreadLocals'		99	'sphene.community.middleware.ThreadLocals'
	>	,		>	,
	108	'sphene.community.middleware.GroupMiddlewa		100	'sphene.community.middleware.GroupMiddlewa
	>	re',		>	re',
n	109		n	101
	110	'django.middleware.common.CommonMiddleware		102	To add the template context processor you need to
	>	',		>	modify TEMPLATE_CONTEXT_PROCESSOR - this variable
				>	is by default not set in the generated settings.py
				>	- so if you don't have it yet in your settings.py
				>	you have to add it:
	111	'django.contrib.sessions.middleware.Sessio		103
	>	nMiddleware',
	112	'django.contrib.auth.middleware.Authentica		104
	>	tionMiddleware',
	113	'django.middleware.doc.XViewMiddleware',
	114	)
	115
	116	TEMPLATE_CONTEXT_PROCESSORS = (		105	TEMPLATE_CONTEXT_PROCESSORS = (
n	117	'django.core.context_processors.auth',	n	106	"django.contrib.auth.context_processors.au
				>	th",
	118	'django.core.context_processors.debug',		107	"django.core.context_processors.debug",
	119	'django.core.context_processors.i18n',		108	"django.core.context_processors.i18n",
	120	'django.core.context_processors.request',
	121	'django.core.context_processors.media',		109	"django.core.context_processors.media",
				110	"django.core.context_processors.static",
				111	"django.contrib.messages.context_processor
				>	s.messages",
	122	'sphene.community.context_processors.navig		112	'sphene.community.context_processors.navig
	>	ation',		>	ation',
	123	)		113	)
	124			114
n	125	# Validating template loaders	n	115	## Synchronizing tables
	126			116
n	127	Make sure you have the application template loader	n	117	After adding the community projects, run syncdb ag
	>	in your TEMPLATE_LOADERS setting ('django.templat		>	ain which will create all necessary tables.
	>	e.loaders.app_directories.load_template_source')
	128			118
n	129	for example:	n	119	./manage.py syncb
	130			120
n	131	TEMPLATE_LOADERS = (	n	121	## Create base template
	132	'sphene.community.groupaware_templateloade		122
	>	r.load_template_source',
	133	'django.template.loaders.filesystem.load_t		123	SCT requires a template called base.html which has
	>	emplate_source',		>	at least a block called "content" and one called
				>	"head". To make this easier we will create a small
				>	community app which hosts only your template. If
				>	you are integrating SCT into your own project, yo
				>	u probably already have a base template.
	134	'django.template.loaders.app_directories.l		124
	>	oad_template_source',
	135	)		125	./manage.py startapp mysitecommunity
				126
				127	and add 'mysitecommunity' to INSTALLED_APPS in set
				>	tings.py
				128
				129	Now create a template directory and edit base.html
				>
				130
				131	Herbys-i7:simpleproject herbert$ mkdir mysitec
				>	ommunity/templates
				132	Herbys-i7:simpleproject herbert$ vi mysitecomm
				>	unity/templates/base.html
				133
				134	which looks like:
	136			135
	137			136
n	138	# Adding Template Directories	n
	139
	140	We need to add our template directories ..
	141
	142	- One for your site templates which are specific t
	>	o our new cool project
	143
	144	Therefore edit settings.py and after setting ROOT_
	>	PATH = os.path.dirname(..) we created previously a
	>	dd the following:
	145
	146	TEMPLATE_DIRS = (
	147	os.path.join(ROOT_PATH,'sitetemplates'),
	148	)
	149
	150	# Creating base template
	151
	152	SCT expects to find a 'base.html' template with a
	>	'content' block, so we need to create a simple tem
	>	plate. Therefore.. create the directory 'sitetempl
	>	ates' and a file called 'base.html' with (for exam
	>	ple) the following content:
	153			137
	154	<html>		138	<html>
	155	<head>		139	<head>
	156	<title>Example Project</title>		140	<title>Example Project</title>
n			n	141	{% block head %}
				142	{% endblock %}
	157	</head>		143	</head>
	158	<body>		144	<body>
	159	{% block content %}		145	{% block content %}
	160	{% endblock %}		146	{% endblock %}
	161	</body>		147	</body>
	162	</html>		148	</html>
	163			149
n	164	For a more complete example you can look into the	n	150	For a more complete example you can look into the
	>	[simpleproject example in the subversion repositor		>	[simpleproject example in the subversion repositor
	>	y](http://yourhell.com/svn/root/django/communityto		>	y](https://github.com/hpoul/sct-communitytools/blo
	>	ols/trunk/examples/simpleproject/sitetemplates/bas		>	b/master/examples/simpleproject/sitetemplates/base
	>	e.html).		>	.html).
	165			151
n			n	152	## And we are done
	166			153
n	167	# Running syncdb (again)	n	154	Now start your project with ./manage.py runserver
				>	and head over to http://127.0.0.1/board/ - You sho
				>	uld see a very simple forum application.
	168			155
n	169	Since we've now finished configuration (almost) ..	n	156	# Community Groups
	>	. run "./manage.py syncdb" again, which will creat
	>	e a couple of tables...
	170
	171	# Creating example Group
	172			157
	173	In SCT everything is based on 'Community Groups' -		158	In SCT everything is based on 'Community Groups' -
	>	every forum or wiki snip is part of a 'Group' - T		>	every forum or wiki snip is part of a 'Group' - T
	>	his Group has nothing to do with the user groups w		>	his Group has nothing to do with the user groups w
	>	hich is basically only for assigning permissions -		>	hich is basically only for assigning permissions -
	>	a community group is more similar to the concept		>	a community group is more similar to the concept
	>	of the [Sites Application](http://www.djangoprojec		>	of the [Sites Application](http://www.djangoprojec
	>	t.com/documentation/sites/) since every community		>	t.com/documentation/sites/) since every community
	>	Group has one URL assigned. The main difference is		>	Group has one URL assigned. The main difference is
	>	tough, that Community Groups are ment to be hoste		>	tough, that Community Groups are ment to be hoste
	>	d on the same django instance with the same config		>	d on the same django instance with the same config
	>	uration, while Sites have a different configuratio		>	uration, while Sites have a different configuratio
	>	n for each 'Site'.		>	n for each 'Site'.
n			n	159
				160	When running syncdb SCT will by default create a '
				>	example' Community Groups which we have configured
				>	in our urls.py to use. You can configure or creat
				>	e more Community Groups in the Django Admin interf
				>	ace:
	174			161
	175	Anyway .. first of all ... we need to get into the		162	Anyway .. first of all ... we need to get into the
	>	admin web interface.. so we need to assign an URL		>	admin web interface.. so we need to assign an URL
	>	: open urls.py and uncomment the following line:		>	: open urls.py and uncomment the following line:
	176			163
	177	(r'^admin/', include('django.contrib.admin.ur		164	(r'^admin/', include('django.contrib.admin.ur
	>	ls')),		>	ls')),
	178			165
	183	- Name: example		170	- Name: example
	184	- Longname: Example Community Group		171	- Longname: Example Community Group
	185	- Baseurl: www.example.com		172	- Baseurl: www.example.com
	186			173
	187	The only important for now is the 'name' .. i assu		174	The only important for now is the 'name' .. i assu
	>	me below that we have a group called 'example' whi		>	me below that we have a group called 'example' whi
	>	ch .. will be the only one we want (for now) ...		>	ch .. will be the only one we want (for now) ...
t	188		t
	189	# Create url conf entries for SCT
	190
	191	Edit urls.py and modify it to look something like:
	>
	192
	193	from django.conf.urls.defaults import *
	194	from django.conf import settings
	195
	196	defaultdict = { 'groupName': 'example' }
	197
	198	urlpatterns = patterns('',
	199	(r'^community/', include('sphene.community
	>	.urls'), defaultdict),
	200	(r'^board/', include('sphene.sphboard.urls
	>	'), defaultdict),
	201	(r'^wiki/', include('sphene.sphwiki.urls')
	>	, defaultdict),
	202
	203	# Only for development
	204	(r'^static/sphene/(.*)$', 'django.views.st
	>	atic.serve', {'document_root': settings.ROOT_PATH
	>	+ '/../../static/sphene' }),
	205
	206	(r'^admin/', include('django.contrib.admin
	>	.urls')),
	207	)
	208
	209
	210	# Running the project - Wiki
	211
	212	So .. now .. run your project again using: "./mana
	>	ge.py runserver" and head over to http://127.0.0.1
	>	:8000/wiki/ which redirects you to http://127.0.0.
	>	1:8000/wiki/show/Start/
	213
	214	This is not that spectecular ... but .. you should
	>	already see something like:
	215
	216	Snip Start does not yet exist. Create It.
	217
	218	If you click on 'Create It' you can edit it .. and
	>	save it .. hopefully .. which should give you an
	>	idea on how to use the wiki ;)
	219
	220
	221	# Configuring the Board
	222
	223	The board is a little more complex, since it does
	>	not yet come with custom admin interface you have
	>	to use django's. So go back to http://127.0.0.1:80
	>	00/admin/ and in Sphboard -> Categorys click 'Add'
	>	and enter the following:
	224
	225	- Name: Example Category
	226	- Group: example
	227
	228	After Creating this entry you can head over to htt
	>	p://127.0.0.1:8000/board/ and have your first Cate
	>	gory where you can post your threads, polls & co ;
	>	)
	229
	230
	231	# Have Fun !
	232
	233	OK .. now .. i expect you've completed this "tutor
	>	ial" and everything worked, and you are completely
	>	happy with your life ..
	234
	235	Anyway, if you encounter any problems don't hesita
	>	te to contact me through the Board or directly by
	>	email: herbert.poul@gmail.com
	236

Sphene Community Tools

Community

Tutorial