|
1 | 1 | # Boilerplate |
2 | 2 |
|
3 | | -With the plugin boilerplate you can easily create a new plugin and setup a docker |
4 | | -development environment that installs Baserow as a dependency. It includes linters and |
5 | | -it can easily be installed via cookiecutter. |
6 | | - |
7 | | -> The structure used for Baserow plugins is not yet finalized and might change to |
8 | | -> support installation of plugins via a market-place available in Baserow. |
9 | | -
|
10 | | -## Creating a plugin |
11 | | - |
12 | | -To use the plugin boilerplate you must first install |
13 | | -the [Cookiecutter](https://cookiecutter.readthedocs.io/en/stable/installation.html) |
14 | | -tool (`pip install cookiecutter`). |
15 | | - |
16 | | -Once you have installed Cookiecutter you can execute the following command to create a |
17 | | -new Baserow plugin from our template. In this guide we will name our plugin "My Baserow |
18 | | -Plugin", however you can choose your own plugin name when prompted to by Cookiecutter. |
19 | | - |
20 | | -> The python module depends on your chosen plugin name. If we for example go with |
21 | | -> "My Baserow Plugin" the Django app name should be my_baserow_plugin and the Nuxt module |
22 | | -> name will be my-baserow-plugin. |
23 | | -
|
24 | | -```bash |
25 | | -cookiecutter gl:baserow/baserow --directory plugin-boilerplate |
26 | | -project_name [My Baserow Plugin]: |
27 | | -project_slug [my-baserow-plugin]: |
28 | | -project_module [my_baserow_plugin]: |
29 | | -``` |
30 | | - |
31 | | -If you do not see any errors it means that your plugin has been created. |
32 | | - |
33 | | -## Starting the development environment |
34 | | - |
35 | | -Now to start your development environment please run the following commands: |
36 | | - |
37 | | -```bash |
38 | | -cd my-baserow-plugin |
39 | | -# Enable Docker buildkit |
40 | | -export COMPOSE_DOCKER_CLI_BUILD=1 |
41 | | -export DOCKER_BUILDKIT=1 |
42 | | -# Set these variables so the images are built and run with the same uid/gid as your |
43 | | -# user. This prevents permission issues when mounting your local source into |
44 | | -# the images. |
45 | | -export PLUGIN_BUILD_UID=$(id -u) |
46 | | -export PLUGIN_BUILD_GID=$(id -g) |
47 | | -# You can optionally `export COMPOSE_FILE=docker-compose.dev.yml` so you don't need to |
48 | | -# use the `-f docker-compose.dev.yml` flag each time. |
49 | | -docker-compose -f docker-compose.dev.yml up -d --build |
50 | | -docker-compose -f docker-compose.dev.yml logs -f |
51 | | -``` |
52 | | - |
53 | | -The development environment is now running and can be accessed at **http://localhost**. |
54 | | - |
55 | | -You can check the plugin is working by visiting the demo url **http://localhost/starting**. |
56 | | - |
57 | | -## First changes |
58 | | - |
59 | | -The most important part inside the `my-baserow-plugin` folder is the |
60 | | -`plugins/my_baserow_plugin` folder. Here you will find all the code of your plugin. For |
61 | | -example purposes we are going to add a simple endpoint which always returns the same |
62 | | -response, and we are going to show this text on a page in the web frontend. |
63 | | - |
64 | | -### Backend changes |
65 | | - |
66 | | -We want to expose an endpoint on the following url |
67 | | -**http://localhost/api/my-baserow-plugin/example/** that returns a JSON response |
68 | | -containing a title and some content. Create/Modify the following files: |
69 | | - |
70 | | -First open `plugins/my_baserow_plugin/backend/src/my_baserow_plugin/api/views.py` and |
71 | | -add your new view below the existing `StartingView`. |
72 | | - |
73 | | -```python |
74 | | -class ExampleView(APIView): |
75 | | - permission_classes = (AllowAny,) |
76 | | - |
77 | | - def get(self, request): |
78 | | - return Response({ |
79 | | - 'title': 'Example title', |
80 | | - 'content': 'Example text' |
81 | | - }) |
82 | | -``` |
83 | | - |
84 | | -Then modify `plugins/my_baserow_plugin/backend/src/my_baserow_plugin/api/urls.py` and |
85 | | -add your new view's url pattern. |
86 | | - |
87 | | -```python |
88 | | -from django.urls import re_path |
89 | | - |
90 | | -from .views import StartingView, ExampleView |
91 | | - |
92 | | -app_name = 'my_baserow_plugin.api' |
93 | | -urlpatterns = [ |
94 | | - re_path(r"starting/$", StartingView.as_view(), name="starting"), |
95 | | - re_path(r'example/$', ExampleView.as_view(), name='example'), |
96 | | -] |
97 | | -``` |
98 | | - |
99 | | -With these change you should be able to visit |
100 | | -the **http://localhost/api/my_baserow_plugin/example/** |
101 | | -endpoint which should return the desired content. |
102 | | - |
103 | | -### Web frontend changes |
104 | | - |
105 | | -Now that we have our endpoint we want to show the response on a page in the |
106 | | -web-frontend. Add/modify the following code. |
107 | | - |
108 | | -Modify `plugins/my_baserow_plugin/web-frontend/modules/my-baserow-plugin/routes.js` and |
109 | | -add your new route after the existing 'starting' route: |
110 | | - |
111 | | -```javascript |
112 | | -import path from 'path' |
113 | | - |
114 | | -export const routes = [ |
115 | | - { |
116 | | - name: 'starting', |
117 | | - path: '/starting', |
118 | | - component: path.resolve(__dirname, 'pages/starting.vue'), |
119 | | - }, |
120 | | - { |
121 | | - name: 'example', |
122 | | - path: '/example', |
123 | | - component: path.resolve(__dirname, 'pages/example.vue'), |
124 | | - }, |
125 | | -] |
126 | | -``` |
127 | | - |
128 | | -Add `plugins/my_baserow_plugin/web-frontend/modules/my-baserow-plugin/pages/example.vue` |
129 | | - |
130 | | -```vue |
131 | | -<template> |
132 | | - <div> |
133 | | - {{ content }} |
134 | | - </div> |
135 | | -</template> |
136 | | -
|
137 | | -<script> |
138 | | -export default { |
139 | | - async asyncData({app}) { |
140 | | - // TODO Make sure you change this url prefix to the underscore separated and |
141 | | - // lowercase name of your plugin. |
142 | | - const response = await app.$client.get('my_baserow_plugin/example/') |
143 | | - return response.data |
144 | | - }, |
145 | | - head() { |
146 | | - return { |
147 | | - title: this.title, |
148 | | - } |
149 | | - }, |
150 | | -} |
151 | | -</script> |
152 | | -``` |
153 | | - |
154 | | -Now you will need to restart the Nuxt development server because the routes have changes |
155 | | -and they are loaded by the module.js. |
156 | | -Run `docker-compose -f docker-compose.dev.yml restart` to do this. |
157 | | - |
158 | | -If you now visit http://localhost/example in your browser you should see a page |
159 | | -containing the title and content defined in the endpoint. |
160 | | - |
161 | | -You should now have a basic idea on how to make some changes to Baserow via the plugin |
162 | | -boilerplate. The changes we have discussed here are of course for example purposes and |
163 | | -are only for giving you an idea about how it works. |
164 | | - |
165 | | -## Linters |
166 | | - |
167 | | -After you have started the dev environment and the containers are all running you can |
168 | | -run the following commands to run the linters. |
169 | | - |
170 | | -* `docker-compose -f docker-compose.dev.yml exec my-baserow-plugin /baserow.sh backend-cmd bash -c bash` |
171 | | - * You are now in a shell inside your Baserow dev container. |
172 | | - * `cd /baserow/data/plugins/my_baserow_plugin/web-frontend/` |
173 | | - * Now you can run any commands you would like: |
174 | | - * `yarn run eslint --fix` |
175 | | - * `yarn run stylelint` |
176 | | - * `yarn add your_dependency` |
177 | | - * `cd /baserow/data/plugins/my_baserow_plugin/backend/` |
178 | | - * Now you can run any commands you would like: |
179 | | - * `black .` |
180 | | - * `flake8` |
181 | | -* To run pytest database tests in your dev container you need to ensure your database |
182 | | - user has the CREATEDB; permission. To do this you can run: |
183 | | - * `docker-compose -f docker-compose.dev.yml exec -T my-baserow-plugin /baserow/supervisor/docker-postgres-setup.sh run <<< "ALTER USER baserow CREATEDB;"` |
184 | | -* Now to run pytest database tests you can: |
185 | | - * `docker-compose -f docker-compose.dev.yml exec my-baserow-plugin /baserow.sh backend-cmd bash -c bash` |
186 | | - * `cd /baserow/data/plugins/my_baserow_plugin/backend/` |
187 | | - * `pytest` |
188 | | - |
189 | | -## Next Steps |
190 | | - |
191 | | -The [Creating a Plugin](./creation.md) guide contains further info on creating plugins. |
192 | | -Also see the README.md in the root of your plugin folder. |
| 3 | +The plugin boilerplate is outdated and only made for Baserow 2.0.6 and lower. Please |
| 4 | +take a look at the repository at https://github.com/baserow/plugin-boilerplate. |
0 commit comments