Introduction

This tutorial assumes you have knowledge in create sproutcore and django applications.

Step 1: Prepare the environment

sproutcore

django-sproutcore uses a custom server.js implementation in sproutcore. Copy the provided django_server.js to frameworks/sproutcore/server/django_server.js or make sure it gets loaded with some other mechanism. In your core.js define SC.DjangoServer like you would with any other server implementation: server: SC.DjangoServer.create({ prefix: ['MyApp'] });.
Setup your sproutcore server to proxy connections to your django development server. Assuming you are running both sc-server and ./manage.py runserver on localhost with the default ports, you can simply add proxy '/', :to => 'localhost:8000' in your sc-config. See the sproutcore wiki for details.

django

make sure django_sproutcore is somewhere in your pythonpath
add django_sproutcore to INSTALLED_APPS in settings.py
add the following pattern to your urls.py: (r'^sc/', include('django_sproutcore.urls'))

Step 2: django models

There is no need to set anything special in your models. This step is provided purely as common ground for this turorial.

from django.db import models

class Author(models.Model):
	first_name = models.CharField(max_length=255)
	last_name = models.CharField(max_length=255)
	

class Book(models.Model):
	title = models.CharField(max_length=255)
	description = models.TextField(null=False, blank=True, default='')
	author = models.ForeignKey(Author, related_name='books')

Step 3: sproutcore models

Now we mimic the django models in sproutcore

my_app/models/author.js

MyApp.Author = SC.Record.extend(
/** @scope MyApp.Author.prototype */ {

	dataSource: MyApp.server,
	resourceURL: '/sc/my_app/author',
	properties: ['firstName', 'lastName'],
	primaryKey: 'guid',
	
	books: SC.Record.hasMany('MyApp.Book', 'author')
}) ;

my_app/models/book.js

MyApp.Book = SC.Record.extend(
/** @scope MyApp.Book.prototype */ {

	dataSource: MyApp.server,
	resourceURL: '/sc/my_app/book',
	properties: ['title', 'description', 'author'],
	primaryKey: 'guid',
	
	authorType = 'MyApp.Author'
		
}) ;

In resourceURL the my_app part should be the name of your django application and the /sc part is configurable in urls.py. Field names are converted from camel case in sproutcore to underlines in django automatically.

Step 4: bringing it all toghether

Create a new python module with the name sc_models.py (or any other name) in your app directory and make sure it gets imported somewhere. A simple way is to just add import sc_models to the __init__.py of your django application.

my_project/my_app/sc_models.py

from django_sproutcore.sc_models import ScModel
from django_sproutcore import api

import models # your models.py

class Author(ScModel):
	class Meta:
		model = models.Author
api.register(Author)

class Book(ScModel):
	class Meta:
		model = models.Book
api.register(Book)

Thats it! Now for some testing :-)

Step 5: Testing

To perform the following tests you'll need Firebug installed in Firefox. Start sc-server and ./manage.py runserver.

In Firefox open http://localhost:4020 and open up the firebug javascipt console.

Add some books and authors to the database.

>>> MyApp.server.listFor({recordType: MyApp.Author});
REQUEST: get /sc/my_app/author/
>>> MyApp.server.listFor({recordType: MyApp.Book});
REQUEST: get /sc/my_app/book/

The above command will issue a query to the server and populate the local Store with all the records form the database.

>>> MyApp.Author.findAll()
MyApp.Author({ guid=1, firstName="Pascal", lastName="Gubler" }), MyApp.Author({ guid=2, firstName="Reto", lastName="Wolf" })
>>> MyApp.Book.findAll()
MyApp.Book({ guid=1, title="The Definitive Guide", description="alsdjflajsdf ", author= MyApp.Author({ guid=1, firstName="Pascal", lastName="Gubler" }) }), MyApp.Book({ guid=2, title="Other Book", description="alsdjkfasdf", author= MyApp.Author({ guid=2, firstName="Reto", lastName="Wolf" }) }), MyApp.Book({ guid=3, title="Another One", description="lkjkldjslfa", author= MyApp.Author({ guid=1, firstName="Pascal", lastName="Gubler" }) })
>>> book = MyApp.Book.find(1)
MyApp.Book({ guid=1, title="The Definitive Guide", description="alsdjflajsdf ", author= MyApp.Author({ guid=1, firstName="Pascal", lastName="Gubler" }) }) guid=1 _bindings=[0] _observers=[0]
>>> newbook = MyApp.Book.newRecord({title:'Yet Another Book', description:'not for dummies', author:MyApp.Author.find(2)})
MyApp.Book({ guid="@@92587", title="Yet Another Book", description="not for dummies", author=MyApp.Author({ guid=1, firstName="Pascal", lastName="Gubler" }) }) dataSource=SC.Object:@41 _bindings=[0]
>>> newbook.dataSource = MyApp.server
SC.DjangoServer:@101 prefix=Bookshelf _bindings=[0] _observers=[0]
>>> newbook.commit()
REQUEST: post /sc/my_app/book/

All the basic commands will work. book.refresh(), book.commit(), book.destroy(). Also the standard listFor filters will work: MyApp.server.listFor({recordType: MyApp.Author, order: ['first_name', '-last_name'], limit: 5, offset: 20, conditions: {last_name__startswith:'G' } } ) -- this will return all Authors with their last name starting with 'G', ordered ascending by first name and then descending by last name, beginning at an offset of 20 and limited to 5 records. Note that the field names for ordering and conditions are in the standard django form. We may change this into camel case sometime soon.