Skip to content
Browse files

Troubleshooting section in installation.rst amplified: now features

sub-sections for template and javascript troubleshooting.
tutorial.rst modified in different places: additional installation
instructions covering pip & easy_install; additional section to
explain the CMS_MEDIA_URL and serving static media
  • Loading branch information...
1 parent 0ed94cd commit 70fa357022d130874d00d448976504a358359c33 @tercerojista tercerojista committed Nov 28, 2010
Showing with 126 additions and 57 deletions.
  1. +2 −0 .gitignore
  2. +35 −14 docs/installation.rst
  3. +89 −43 docs/tutorial.rst
View
2 .gitignore
@@ -27,3 +27,5 @@ eggs
parts
bin
/dist
+*.rst~
+/docs/*.html
View
49 docs/installation.rst
@@ -1,12 +1,13 @@
-Installation
-============
+==============
+ Installation
+==============
This document assumes that you are familiar with python and django.
A more beginner friendly tutorial can be found :doc:`here <tutorial>`.
Requirements
-------------
+============
* Python 2.5 (or a higher release of the 2.x). 2.4 might work, but is not
supported.
@@ -15,10 +16,10 @@ Requirements
* South 0.7 or higher
Apps
-----
+====
Required
-~~~~~~~~
+--------
* ``django.contrib.auth``
* ``django.contrib.contenttypes``
@@ -35,7 +36,7 @@ Required
the cms which is version 0.3-pre.
Optional
-~~~~~~~~
+--------
* ``cms.plugins.text``
* ``cms.plugins.picture``
@@ -47,7 +48,7 @@ Optional
Middlewares
------------
+===========
Note that the order is important:
@@ -64,7 +65,7 @@ Note that the order is important:
`cms.middleware.multilingual.MultilingualURLMiddleware` middleware.
Template Context Processors
----------------------------
+===========================
* ``django.core.context_processors.auth``
* ``django.core.context_processors.i18n``
@@ -73,36 +74,37 @@ Template Context Processors
* ``cms.context_processors.media``
Templates
----------
+=========
You have to define at least one template in ``CMS_TEMPLATES`` which should
contain at least one ``{% placeholder '<name>' %}`` tag.
urls.py
--------
+=======
Include ``cms.urls`` **at the very end** of your urlpatterns. It **must** be the
last pattern in the list!
Media Files
------------
+===========
Make sure your Django installation finds the cms media files, for this task we
recommend using django-appmedia which will create a symbolic link for you. If
for whatever reason you are unable to use it, copy the folder ``cms/media/cms``
into your main media folder.
South
------
+=====
To avoid issues with migrations during the installation process it is currently
recommended to use ``python manage.py syncdb --all`` and
``python manage.py migrate --fake`` for **new** projects. Note that the cms
migrations can not be supported on sqlite3.
-Troubleshooting
----------------
+=================
+ Troubleshooting
+=================
If you create a page and you don't see a page in the list view:
@@ -115,3 +117,22 @@ with plugins:
- Be sure your ``CMS_TEMPLATES`` setting is correct and that the templates
specified actually exist and have at least one ``{% placeholder %}``
templatetag in them template.
+
+Template errors
+===============
+If your placeholder content isn't being displayed when you view a CMS page, then change the CMS_MODERATOR variable in settings.py to False. This bug has been fixed, so upgrading to the latest version of Django CMS should resolve the issue. See:
+https://github.com/divio/django-cms/issues/issue/430
+
+Javascript errors
+=================
+If the plugins don't work (e.g. you try adding a text plugin, but you don't see the Javascript text editor on the page), you should use a Javascript inspector in your browser to investigate the issue (e.g. Firebug for Firefox, Web Inspector for Safari or Chrome). The Javascript inspector may report one of the following errors:
+
+- **TypeError: Result of expression 'jQuery' [undefined] is not a function.**
+
+If you see this, check the MEDIA_URL variable in your settings.py file. Your webserver (e.g. Apache) should be set up to serve the static media files from this URL.
+
+- **Unsafe JavaScript attempt to access frame with URL http://localhost/media/cms/wymeditor/iframe/default/wymiframe.html from frame with URL http://127.0.0.1:8000/admin/cms/page/1/edit-plugin/2/. Domains, protocols and ports must match.**
+
+This error is due to the Django test server running on a different port and URL to the main webserver. In your test environment, you can overcome this issue by adding a CMS_MEDIA_URL variable to your settings.py file, and adding a url rule in urls.py to make the Django development serve the Django CMS files from this location.
+
+
View
132 docs/tutorial.rst
@@ -4,60 +4,49 @@ Django CMS Tutorial
Installation
-------------
-I am working on Ubuntu 9.10 here, not windows or mac...sorry, although I don't
+This guide has been tested with Ubuntu 9.10 and Mac OS X Snow Leopard.
+
+<--I am working on Ubuntu 9.10 here, not windows or mac...sorry, although I don't
expect things will be much different for mac at least...if I get a chance i'll
run through this process on windows too and update the article but no
promises.
I'm assuming that Python, Django and sqlite3 are installed already. For
-reference, I am currently using Python 2.6.4 and Django (trunk version) 1.2.
+reference, I am currently using Python 2.6.4 and Django (trunk version) 1.2.-->
-Preparing the environment
-*************************
-
-If you don't already have one, create a new folder for your code to live in. My
-folder lives in my home directory and is named "django_apps". This will pop up
-throughout this guide so if you're following along and you call yours
-something else, remember to replace "django_apps" with the name of your own
-folder when the time comes.
+Installing Django CMS
+*********************
+Django CMS can be installed in different ways.
-In a terminal, move into your code directory::
-
- CD ~/django_apps
-
-Create a new Django project (call this whatever you like but remember to
-change it if you're following along and have called it something else)::
-
- django-admin.py startproject project-name
+You can use PIP::
-No harm in making sure that all is indeed well with Django at this early stage so::
+ $ pip install django-cms
- CD project-name
+You can use easy_install::
-And... ::
+ $ easy_install django-cms
- python manage.py runserver
+Or you can download a tarball or check out a specific version from github::
-Head on over to http://127.0.0.1:8000 and if you see the following "it worked" page then well, its working.
+ http://github.com/divio/django-cms/downloads
-|it-worked|
+If you opt for this method, then you then need to run the `setup.py` file in the root folder of the downloaded package::
-.. |it-worked| image:: images/it-worked.png
+ $ python setup.py install
-Here comes the science...
-*************************
+Alternatively, you can do everything by hand:
-If you dont happen to know your Python location then issue the following command::
+If you don't know your Python location, issue the following command::
- which python
+ $ which python
-(my one is "/usr/local/lib/python2.6" for example)
+(my path is "/usr/local/lib/python2.6" for example)
Go to your Python dist-packages directory "your-python-path/dist-packages"
Download the latest and greatest Django CMS from here: http://www.django-cms.org/en/downloads/
-Unzip the downloaded file into the "dist-packages" directory...you will need to do this as "sudo" unless you have your system set up wrongly ;)
+Unzip the downloaded file into the "dist-packages" directory...you will need to do this as the superuser.
Make copies of the following directories like so::
@@ -70,28 +59,62 @@ Do a bit of house cleaning to get rid of all the files you don't need::
sudo rm -rf divio-django-cms-c0288a1.zip
sudo rm -rf divio-django-cms-c0288a1/
-To ensure the cms is properly installed, invoke a python shell (just type ``python`` at the prompt), and ensure the following command returns without errors:
+To ensure the cms is properly installed, invoke a Python shell (just type ``python`` at the prompt), and ensure the following command returns without errors:
import cms
+If this works, then you’re ready to create and configure a new project!
Make a set of basic project files
*********************************
+Preparing the environment
+*************************
+
+If you don't already have one, create a new folder for your code to live in. My
+folder lives in my home directory and is named "django_apps". This will pop up
+throughout this guide so if you're following along and you call yours
+something else, remember to replace "django_apps" with the name of your own
+folder when the time comes.
+
+In a terminal, move into your code directory::
+
+ CD ~/django_apps
+
+Create a new Django project (call this whatever you like but remember to
+change it if you're following along and have called it something else)::
+
+ django-admin.py startproject project-name
+
+No harm in making sure that all is indeed well with Django at this early stage so::
+
+ CD project-name
+
+And... ::
+
+ python manage.py runserver
+
+Head on over to http://127.0.0.1:8000 and if you should see the "It worked!" page:
+
+|it-worked|
+
+.. |it-worked| image:: images/it-worked.png
+
Head back to the project you created previously::
cd ~/django_apps/project-name
-In your editor, edit "settings.py" like so:
+To use Django CMS as part of the project, you need to edit the "settings.py" file.
Insert the following before anything else in the file::
import os
gettext = lambda s: s
PROJECT_PATH = os.path.realpath(os.path.dirname(__file__))
+
+The gettext line allows us to use translatable strings in the settings.py file (see below).
-This will instruct Django to set the root of the project at "the location of settings.py".
-The gettext line is there for transaltion voodoo. Don't pay attention to it yet.
+The PROJECT_PATH line instructs Django to consider the location of your settings.py file to be the root of the project.
Set up the remainder of the file with the following changes/additions::
@@ -126,22 +149,22 @@ Set up the remainder of the file with the following changes/additions::
'cms.plugins.googlemap',
'mptt',
'publisher',
- 'menus',
+ 'menus',
)
MIDDLEWARE_CLASSES = (
- 'django.middleware.cache.UpdateCacheMiddleware',
+ 'django.middleware.cache.UpdateCacheMiddleware',
'django.contrib.sessions.middleware.SessionMiddleware',
'django.contrib.auth.middleware.AuthenticationMiddleware',
'django.middleware.common.CommonMiddleware',
'django.middleware.doc.XViewMiddleware',
'django.middleware.csrf.CsrfViewMiddleware',
'cms.middleware.page.CurrentPageMiddleware',
'cms.middleware.user.CurrentUserMiddleware',
- 'cms.middleware.toolbar.ToolbarMiddleware',
- 'cms.middleware.media.PlaceholderMediaMiddleware',
- 'django.middleware.cache.FetchFromCacheMiddleware',
+ 'cms.middleware.toolbar.ToolbarMiddleware',
+ 'cms.middleware.media.PlaceholderMediaMiddleware',
+ 'django.middleware.cache.FetchFromCacheMiddleware',
)
TEMPLATE_DIRS = os.path.join(PROJECT_PATH, 'templates')
@@ -166,6 +189,23 @@ Set up your available templates (don't worry that they don't actually exist yet)
('extra.html', gettext('Some extra fancy template')),
)
+The CMS_MEDIA_URL setting
+*************************
+
+Although the Django CMS media is located in the same folder as the rest of your media, you should set up a specific URL for just the Django CMS media. Then add a CMS_MEDIA_URL variable to settings.py, eg::
+
+ CMS_MEDIA_URL = 'http://127.0.0.1:8000/static_media/cms/'
+
+This configuration is necessary to overcome cross-site security issues relating to wymeditor, the Javascript utility used by Django CMS for the WYSIWYM text editor plugin. Although it is common to serve static files from a different domain, the Django CMS media must be served by the same domain that serves the dynamic Python files.
+
+In a development / test setting, the Django development server should be used to serve the Django CMS media files (see the "URLs configuration" section).
+
+In a production environment, a server alias should be created which sends requests for the Django CMS media files to a folder on the main server.
+
+
+URLs configuration
+******************
+
Next, Edit your ``urls.py`` file like this::
from django.conf.urls.defaults import *
@@ -180,16 +220,22 @@ Next, Edit your ``urls.py`` file like this::
if settings.DEBUG:
urlpatterns += patterns('',
- url(r'^media/(?P<path>.*)$', 'django.views.static.serve', {'document_root': settings.MEDIA_ROOT, 'show_indexes': True})
+ url(r'^static_media/cms/(?P<path>.*)$', 'django.views.static.serve', {'document_root': settings.MEDIA_ROOT, 'show_indexes': True})
)
urlpatterns += patterns('',
url(r'^', include('cms.urls')),
)
-Create a folder called 'media' in your project root (that's "project-name" for me), this means you create a symbolic link from the "cms/media/cms" folder in "dist-packages" to your new "media" folder::
+It is necessary to include the Django CMS media folder in the media folder of your Django project:
+
+1. Create a folder called 'media' in your project root (that's "project-name" for me).
+
+2. Create a symbolic link from the "cms/media/cms" folder in "dist-packages" to your new "media" folder, for example::
+
+ ln -s /usr/local/lib/python2.6/dist-packages/cms/media/cms cms
- ln -s /usr/local/lib/python2.6/dist-packages/cms/media/cms cms
+Make sure that read permissions are set on this folder. Now all of the static media files used by Django CMS can be served to your site.
Loading up on supplies: preparing the database

0 comments on commit 70fa357

Please sign in to comment.
Something went wrong with that request. Please try again.