You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Copy file name to clipboardExpand all lines: docs/topics/browsable-api.md
+40-22Lines changed: 40 additions & 22 deletions
Original file line number
Diff line number
Diff line change
@@ -11,69 +11,85 @@ API may stand for Application *Programming* Interface, but humans have to be abl
11
11
12
12
If you include fully-qualified URLs in your resource output, they will be 'urlized' and made clickable for easy browsing by humans. The `rest_framework` package includes a [`reverse`][drfreverse] helper for this purpose.
13
13
14
-
15
14
## Formats
16
15
17
16
By default, the API will return the format specified by the headers, which in the case of the browser is HTML. The format can be specified using `?format=` in the request, so you can look at the raw JSON response in a browser by adding `?format=json` to the URL. There are helpful extensions for viewing JSON in [Firefox][ffjsonview] and [Chrome][chromejsonview].
18
17
19
-
20
18
## Customizing
21
19
22
-
To customize the look-and-feel, create a template called `api.html` and add it to your project, eg: `templates/rest_framework/api.html`, that extends the `rest_framework/base.html` template.
20
+
The browsable API is built with [Twitter's Bootstrap][bootstrap] (v 2.1.1), making it easy to customize the look-and-feel.
21
+
22
+
To customize the default style, create a template called `rest_framework/api.html` that extends from `rest_framework/base.html`. For example:
23
23
24
-
The included browsable API template is built with [Bootstrap (2.1.1)][bootstrap], making it easy to customize the look-and-feel.
24
+
**templates/rest_framework/api.html**
25
+
26
+
{% extends "rest_framework/base.html" %}
27
+
28
+
... # Override blocks with required customizations
25
29
26
-
### Theme
30
+
### Overriding the default theme
27
31
28
-
To replace the theme wholesale, add a `bootstrap_theme` block to your `api.html` and insert a `link` to the desired Bootstrap theme css file. This will completely replace the included theme.
32
+
To replace the default theme, add a `bootstrap_theme` block to your `api.html` and insert a `link` to the desired Bootstrap theme css file. This will completely replace the included theme.
A suitable replacement theme can be generated using Bootstrap's [Customize Tool][bcustomize]. Also, there are pre-made themes available at [Bootswatch][bswatch]. To use any of the Bootswatch themes, simply download the theme's `bootstrap.min.css` file, add it to your project, and replace the default one as described above.
38
+
A suitable replacement theme can be generated using Bootstrap's [Customize Tool][bcustomize]. There are also pre-made themes available at [Bootswatch][bswatch]. To use any of the Bootswatch themes, simply download the theme's `bootstrap.min.css` file, add it to your project, and replace the default one as described above.
35
39
36
40
You can also change the navbar variant, which by default is `navbar-inverse`, using the `bootstrap_navbar_variant` block. The empty `{% block bootstrap_navbar_variant %}{% endblock %}` will use the original Bootstrap navbar style.
For more specific CSS tweaks than simply overriding the default bootstrap theme you can override the `style` block.
53
+
54
+
---
55
+
56
+
![Cerulean theme][cerulean]
57
+
58
+
*Screenshot of the bootswatch 'Cerulean' theme*
59
+
60
+
---
61
+
62
+
![Slate theme][slate]
48
63
49
-
For more specific CSS tweaks, use the `style` block instead.
64
+
*Screenshot of the bootswatch 'Slate' theme*
50
65
66
+
---
51
67
52
68
### Blocks
53
69
54
70
All of the blocks available in the browsable API base template that can be used in your `api.html`.
55
71
56
-
*`bodyclass` - (empty) class attribute for the `<body>`
57
-
*`bootstrap_theme` - CSS for the Bootstrap theme
58
-
*`bootstrap_navbar_variant` - CSS class for the navbar
59
-
*`branding` - section of the navbar, see [Bootstrap components][bcomponentsnav]
72
+
*`bodyclass` - Class attribute for the `<body>` tag, empty by default.
73
+
*`bootstrap_theme` - CSS for the Bootstrap theme.
74
+
*`bootstrap_navbar_variant` - CSS class for the navbar.
75
+
*`branding` - Branding section of the navbar, see [Bootstrap components][bcomponentsnav].
60
76
*`breadcrumbs` - Links showing resource nesting, allowing the user to go back up the resources. It's recommended to preserve these, but they can be overridden using the breadcrumbs block.
61
-
*`footer` - Any copyright notices or similar footer materials can go here (by default right-aligned)
62
-
*`style` - CSS stylesheets for the page
63
-
*`title` - title of the page
64
-
*`userlinks` - This is a list of links on the right of the header, by default containing login/logout links. To add links instead of replace, use {{ block.super }} to preserve the authentication links.
77
+
*`footer` - Any copyright notices or similar footer materials can go here (by default right-aligned).
78
+
*`style` - CSS stylesheets for the page.
79
+
*`title` - Title of the page.
80
+
*`userlinks` - This is a list of links on the right of the header, by default containing login/logout links. To add links instead of replace, use `{{ block.super }}` to preserve the authentication links.
65
81
66
82
#### Components
67
83
68
-
All of the [Bootstrap components][bcomponents] are available.
84
+
All of the standard [Bootstrap components][bcomponents] are available.
69
85
70
-
#####Tooltips
86
+
#### Tooltips
71
87
72
-
The browsable API makes use of the Bootstrap tooltips component. Any element with the `js-tooltip` class and a `title` attribute has that title content displayed in a tooltip on hover after a 1000ms delay.
88
+
The browsable API makes use of the Bootstrap tooltips component. Any element with the `js-tooltip` class and a `title` attribute has that title content will display a tooltip on hover events.
73
89
74
90
### Login Template
75
91
76
-
To add branding and customize the look-and-feel of the auth login template, create a template called `login.html` and add it to your project, eg: `templates/rest_framework/login.html`, that extends the `rest_framework/base_login.html` template.
92
+
To add branding and customize the look-and-feel of the login template, create a template called `login.html` and add it to your project, eg: `templates/rest_framework/login.html`. The template should extend from `rest_framework/base_login.html`.
77
93
78
94
You can add your site name or branding by including the branding block:
79
95
@@ -114,6 +130,8 @@ For more advanced customization, such as not having a Bootstrap basis or tighter
0 commit comments