README.md 3.87 KB
Newer Older
Sylvain Le Bon's avatar
Sylvain Le Bon committed
1 2 3 4 5 6 7 8 9 10 11
## Synopsis

This module is an add-on for Django REST Framework that serves a django model respecting the Linked Data Platform convention.

It aims at enabling people with little development skills to serve their own data, to be used with a LDP application.

## Requirements

* Django (known to work with django 1.11)
* Django Rest Framework
* pyld
12 13
* django-guardian
* djangorestframework-guardian
Sylvain Le Bon's avatar
Sylvain Le Bon committed
14 15 16

## Installation

Benoit Alessandroni's avatar
Benoit Alessandroni committed
17
1. Install this module and all its dependencies
Sylvain Le Bon's avatar
Sylvain Le Bon committed
18 19 20 21 22

```
pip install djangoldp
```

Benoit Alessandroni's avatar
Benoit Alessandroni committed
23
2. Create a django project
Sylvain Le Bon's avatar
Sylvain Le Bon committed
24 25 26 27 28
 
```
django-admin startproject myldpserver
```

Benoit Alessandroni's avatar
Benoit Alessandroni committed
29
3. Create your django model inside a file myldpserver/myldpserver/models.py
Sylvain Le Bon's avatar
Sylvain Le Bon committed
30 31 32 33 34 35 36 37 38 39

```
from django.db import models

class Todo(models.Model):
    name = models.CharField(max_length=255)
    deadline = models.DateTimeField()

```

Benoit Alessandroni's avatar
Benoit Alessandroni committed
40
3.1. Configure field visibility (optional) 
41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56
Note that at this stage you can limit access to certain fields of models using

```
<Model>._meta.serializer_fields (<>list of field names to show>)
```

 For example, if you have a model with a related field with type **django.contrib.auth.models.User** you don't want to show personal details or password hashes.

E.g.

```
from django.contrib.auth.models import User

User._meta.serializer_fields  = ('username','first_name','last_name')
```

57 58
Note that this will be overridden if you explicitly set the fields= parameter as an argument to LDPViewSet.urls(), and filtered if you set the excludes= parameter.

Benoit Alessandroni's avatar
Benoit Alessandroni committed
59
4. Add a url in your urls.py:
Alexandre's avatar
Alexandre committed
60

Sylvain Le Bon's avatar
Sylvain Le Bon committed
61
```
Sylvain Le Bon's avatar
Sylvain Le Bon committed
62 63
from django.conf.urls import url
from django.contrib import admin
Sylvain Le Bon's avatar
Sylvain Le Bon committed
64
from djangoldp.views import LDPViewSet
Sylvain Le Bon's avatar
Sylvain Le Bon committed
65
from .models import Todo
Sylvain Le Bon's avatar
Sylvain Le Bon committed
66 67

urlpatterns = [
Sylvain Le Bon's avatar
Sylvain Le Bon committed
68
    url(r'^todos/', LDPViewSet.urls(model=Todo)),
Sylvain Le Bon's avatar
Sylvain Le Bon committed
69 70 71
    url(r'^admin/', admin.site.urls),
]
```
Alexandre's avatar
Alexandre committed
72

Sylvain Le Bon's avatar
Sylvain Le Bon committed
73 74
This creates 2 routes, one for the list, and one with an ID listing the detail of an object.

Benoit Alessandroni's avatar
Benoit Alessandroni committed
75
5. In the settings.py file, add your application name at the beginning of the application list, and add the following lines
Sylvain Le Bon's avatar
Sylvain Le Bon committed
76 77 78 79 80 81

```
STATIC_ROOT = os.path.join(os.path.dirname(BASE_DIR), 'static')
LDP_RDF_CONTEXT = 'https://cdn.happy-dev.fr/owl/hdcontext.jsonld'
```

Benoit Alessandroni's avatar
Benoit Alessandroni committed
82
6. You can also register your model for the django administration site
Sylvain Le Bon's avatar
Sylvain Le Bon committed
83 84 85 86 87 88 89 90

```
from django.contrib import admin
from .models import Todo

admin.site.register(Todo)
```

Benoit Alessandroni's avatar
Benoit Alessandroni committed
91
7. You then need to have your WSGI server pointing on myldpserver/myldpserver/wsgi.py
Sylvain Le Bon's avatar
Sylvain Le Bon committed
92

Benoit Alessandroni's avatar
Benoit Alessandroni committed
93
8. You will probably need to create a super user
Alexandre's avatar
Alexandre committed
94 95 96 97
```
./manage.py createsuperuser
```

Benoit Alessandroni's avatar
Benoit Alessandroni committed
98
9. If you have no CSS on the admin screens : 
Alexandre's avatar
Alexandre committed
99 100 101 102
```
./manage.py collectstatic
```

Alexandre's avatar
Alexandre committed
103 104 105 106 107 108
## Execution
To start the server, `cd` to the root of your Django project and run :
```
python3 manage.py runserver
```

Sylvain Le Bon's avatar
Sylvain Le Bon committed
109
## Custom Parameters to LDPViewSet
Sylvain Le Bon's avatar
Sylvain Le Bon committed
110

Sylvain Le Bon's avatar
Sylvain Le Bon committed
111 112 113 114 115 116 117 118 119 120 121 122 123 124
### lookup_field
Can be used to use a slug in the url instead of the primary key.
```
LDPViewSet.urls(model=User, lookup_field='username')
```

### nested_fields
list of ForeignKey, ManyToManyField, OneToOneField and their reverse relations. When a field is listed in this parameter, a container will be created inside each single element of the container.

In the following example, besides the urls `/members/` and `/members/<pk>/`, two other will be added to serve a container of the skills of the member: `/members/<pk>/skills/` and `/members/<pk>/skills/<pk>/` 
```
    url(r'^members/', LDPViewSet.urls(model=Member, nested_fields=("skills",))),
```

Benoit Alessandroni's avatar
Benoit Alessandroni committed
125 126 127 128 129 130 131
From the 0.5 we added permissions check by default on every route, so you may encounter 400 errors code on your POST requests. You can disable those checks by specifying the permission_classes as an empty array in our URLs files.


```
url(r'^posts/', LDPViewSet.urls(model=Post, permission_classes=(), filter_backends = ())),
```

132 133 134 135
## Custom Meta options on models

### rdf_type
### auto_author
Alexandre's avatar
Alexandre committed
136 137
This property allows to associate a model with the logged in user.

Alexandre's avatar
Alexandre committed
138
```python
Alexandre's avatar
Alexandre committed
139 140 141 142
class MyModel(models.Model):
    author_user = models.ForeignKey(settings.AUTH_USER_MODEL)
    class Meta:
        auto_author = 'author_user'
Alexandre's avatar
Alexandre committed
143
```
144

Sylvain Le Bon's avatar
Sylvain Le Bon committed
145 146 147
## License

Licence MIT