notion_ruby_mapping 0.2.3 → 0.3.2
Sign up to get free protection for your applications and to get access to all the features.
- checksums.yaml +4 -4
- data/README.md +434 -135
- data/env.yml.sample +1 -0
- data/examples/change_title.md +26 -0
- data/examples/renumbering_pages.md +20 -0
- data/examples/set_icon_to_all_icon_unsettled_pages.md +30 -0
- data/lib/notion_ruby_mapping/base.rb +129 -71
- data/lib/notion_ruby_mapping/checkbox_property.rb +27 -12
- data/lib/notion_ruby_mapping/created_by_property.rb +22 -10
- data/lib/notion_ruby_mapping/created_time_property.rb +16 -14
- data/lib/notion_ruby_mapping/database.rb +75 -10
- data/lib/notion_ruby_mapping/date_property.rb +67 -42
- data/lib/notion_ruby_mapping/email_property.rb +26 -16
- data/lib/notion_ruby_mapping/files_property.rb +40 -24
- data/lib/notion_ruby_mapping/formula_property.rb +51 -10
- data/lib/notion_ruby_mapping/last_edited_by_property.rb +22 -9
- data/lib/notion_ruby_mapping/last_edited_time_property.rb +16 -14
- data/lib/notion_ruby_mapping/list.rb +3 -0
- data/lib/notion_ruby_mapping/multi_select_property.rb +83 -21
- data/lib/notion_ruby_mapping/notion_cache.rb +17 -13
- data/lib/notion_ruby_mapping/number_property.rb +71 -10
- data/lib/notion_ruby_mapping/page.rb +32 -10
- data/lib/notion_ruby_mapping/payload.rb +21 -3
- data/lib/notion_ruby_mapping/people_property.rb +47 -19
- data/lib/notion_ruby_mapping/phone_number_property.rb +26 -15
- data/lib/notion_ruby_mapping/property.rb +142 -49
- data/lib/notion_ruby_mapping/property_cache.rb +31 -3
- data/lib/notion_ruby_mapping/query.rb +10 -0
- data/lib/notion_ruby_mapping/relation_property.rb +74 -21
- data/lib/notion_ruby_mapping/rich_text_array.rb +81 -0
- data/lib/notion_ruby_mapping/rich_text_object.rb +1 -0
- data/lib/notion_ruby_mapping/rich_text_property.rb +12 -1
- data/lib/notion_ruby_mapping/rollup_property.rb +82 -10
- data/lib/notion_ruby_mapping/select_property.rb +88 -13
- data/lib/notion_ruby_mapping/text_object.rb +0 -2
- data/lib/notion_ruby_mapping/text_property.rb +19 -45
- data/lib/notion_ruby_mapping/title_property.rb +12 -1
- data/lib/notion_ruby_mapping/url_property.rb +26 -15
- data/lib/notion_ruby_mapping/user_object.rb +4 -4
- data/lib/notion_ruby_mapping/version.rb +1 -1
- data/lib/notion_ruby_mapping.rb +2 -1
- metadata +6 -2
data/README.md
CHANGED
@@ -10,11 +10,6 @@ Development note is here. → [Idea note of "notion_ruby_mapping"](https://www.n
|
|
10
10
|
- [Table of Contents](#table-of-contents)
|
11
11
|
- [1. Installation](#1-installation)
|
12
12
|
- [2. Example code](#2-example-code)
|
13
|
-
- [2.1 Set icon to all icon unsettled pages](#21-set-icon-to-all-icon-unsettled-pages)
|
14
|
-
- [2.2 Renumbering pages](#22-renumbering-pages)
|
15
|
-
- [2.3 Change title](#23-change-title)
|
16
|
-
- [Pattern 1 (replace existing text partially)](#pattern-1-replace-existing-text-partially)
|
17
|
-
- [Pattern 2 (replace all text)](#pattern-2-replace-all-text)
|
18
13
|
- [3. Preparation](#3-preparation)
|
19
14
|
- [3.1 Create a New Integration](#31-create-a-new-integration)
|
20
15
|
- [3.2 Create client](#32-create-client)
|
@@ -29,8 +24,14 @@ Development note is here. → [Idea note of "notion_ruby_mapping"](https://www.n
|
|
29
24
|
- [4.2.2 Query a database](#422-query-a-database)
|
30
25
|
- [4.2.2.1 Complex conditions](#4221-complex-conditions)
|
31
26
|
- [4.2.2.2 Sort criteria](#4222-sort-criteria)
|
27
|
+
- [4.2.2.3 Dry run sample](#4223-dry-run-sample)
|
32
28
|
- [4.2.3 Create child page](#423-create-child-page)
|
33
|
-
- [4.2.4
|
29
|
+
- [4.2.4 Create database](#424-create-database)
|
30
|
+
- [4.2.5 Update database properties](#425-update-database-properties)
|
31
|
+
- [4.2.6 Add a database property](#426-add-a-database-property)
|
32
|
+
- [4.2.7 Rename a database property](#427-rename-a-database-property)
|
33
|
+
- [4.2.8 Remove database properties](#428-remove-database-properties)
|
34
|
+
- [4.2.9 other methods](#429-other-methods)
|
34
35
|
- [4.3 List class](#43-list-class)
|
35
36
|
- [4.4 Block class](#44-block-class)
|
36
37
|
- [4.5 Property classes](#45-property-classes)
|
@@ -47,14 +48,30 @@ Development note is here. → [Idea note of "notion_ruby_mapping"](https://www.n
|
|
47
48
|
- [4.5.3.7 PeopleProperty](#4537-peopleproperty)
|
48
49
|
- [4.5.3.8 TitleProperty, RichTextProperty](#4538-titleproperty-richtextproperty)
|
49
50
|
- [4.5.3.9 CheckboxProperty](#4539-checkboxproperty)
|
50
|
-
- [4.5.3.10
|
51
|
-
- [4.5.3.11
|
52
|
-
|
53
|
-
|
51
|
+
- [4.5.3.10 FilesProperty](#45310-filesproperty)
|
52
|
+
- [4.5.3.11 RelationProperty](#45311-relationproperty)
|
53
|
+
- [4.5.4 create or update values for Database properties](#454-create-or-update-values-for-database-properties)
|
54
|
+
- [4.5.4.1 NumberProperty](#4541-numberproperty)
|
55
|
+
- [4.5.4.2 SelectProperty](#4542-selectproperty)
|
56
|
+
- [4.5.4.3 MultiSelectProperty](#4543-multiselectproperty)
|
57
|
+
- [4.5.4.4 DateProperty](#4544-dateproperty)
|
58
|
+
- [4.5.4.4 UrlProperty](#4544-urlproperty)
|
59
|
+
- [4.5.4.5 EmailProperty](#4545-emailproperty)
|
60
|
+
- [4.5.4.6 PhoneNumberProperty](#4546-phonenumberproperty)
|
61
|
+
- [4.5.4.7 PeopleProperty](#4547-peopleproperty)
|
62
|
+
- [4.5.4.8 TitleProperty, RichTextProperty](#4548-titleproperty-richtextproperty)
|
63
|
+
- [4.5.4.9 CheckboxProperty](#4549-checkboxproperty)
|
64
|
+
- [4.5.4.10 FilesProperty](#45410-filesproperty)
|
65
|
+
- [4.5.4.11 RelationProperty](#45411-relationproperty)
|
66
|
+
- [4.5.4.12 RollupProperty](#45412-rollupproperty)
|
67
|
+
- [5. XXXObjects and RichTextArray](#5-xxxobjects-and-richtextarray)
|
54
68
|
- [5.1 RichTextObject](#51-richtextobject)
|
55
69
|
- [5.2 TextObject](#52-textobject)
|
56
70
|
- [5.3 MentionObject](#53-mentionobject)
|
57
71
|
- [5.4 UserObject](#54-userobject)
|
72
|
+
- [5.5 RichTextArray](#55-richtextarray)
|
73
|
+
- [5.5.1 Constructor for RichTextArray](#551-constructor-for-richtextarray)
|
74
|
+
- [5.5.2 Instance methods](#552-instance-methods)
|
58
75
|
- [6. ChangeLog](#6-changelog)
|
59
76
|
- [7. Contributing](#7-contributing)
|
60
77
|
- [8. License](#8-license)
|
@@ -83,76 +100,9 @@ gem install notion_ruby_mapping
|
|
83
100
|
|
84
101
|
## 2. Example code
|
85
102
|
|
86
|
-
|
87
|
-
|
88
|
-
|
89
|
-
|
90
|
-
```Ruby
|
91
|
-
require "notion_ruby_mapping"
|
92
|
-
|
93
|
-
include NotionRubyMapping
|
94
|
-
|
95
|
-
token = ENV["NOTION_API_TOKEN"]
|
96
|
-
database_id = ENV["DATABASE_ID"]
|
97
|
-
|
98
|
-
NotionCache.instance.create_client token
|
99
|
-
|
100
|
-
db = Database.new id: database_id
|
101
|
-
db.query_database.each do |page|
|
102
|
-
unless page.icon
|
103
|
-
page.set_icon(emoji: "💿")
|
104
|
-
page.save
|
105
|
-
p page.id
|
106
|
-
end
|
107
|
-
end
|
108
|
-
```
|
109
|
-
|
110
|
-
|Before execution|After execution|
|
111
|
-
|---|---|
|
112
|
-
|![Before execution](images/pre_set_icon.png)|![After execution](images/post_set_icon.png)|
|
113
|
-
|
114
|
-
### 2.2 Renumbering pages
|
115
|
-
|
116
|
-
The following code sets serial numbers to the pages whose title is not empty in ascending order of titles.
|
117
|
-
|
118
|
-
```Ruby
|
119
|
-
db = Database.new id: database_id, assign: [RichTextProperty, "TextTitle"]
|
120
|
-
tp = db.properties["TextTitle"]
|
121
|
-
query = tp.filter_is_not_empty.ascending(tp)
|
122
|
-
db.query_database(tp.filter_is_not_empty.ascending(tp)).each.with_index(1) do |page, index|
|
123
|
-
page.properties["NumberTitle"].number = index
|
124
|
-
page.save
|
125
|
-
end
|
126
|
-
```
|
127
|
-
|
128
|
-
| After execution |
|
129
|
-
|-----------------------------------------------|
|
130
|
-
| ![After exuecution](images/serial_number.png) |
|
131
|
-
|
132
|
-
### 2.3 Change title
|
133
|
-
|
134
|
-
The following code update the page title.
|
135
|
-
|
136
|
-
#### Pattern 1 (replace existing text partially)
|
137
|
-
|
138
|
-
```Ruby
|
139
|
-
page = Page.find page_id # API access
|
140
|
-
print page.title # -> ABC\nDEF
|
141
|
-
tp = page.properties["Title"]
|
142
|
-
tp[1].text = "GHI"
|
143
|
-
page.save # API access
|
144
|
-
print page.title # -> ABC\nGHI
|
145
|
-
```
|
146
|
-
|
147
|
-
#### Pattern 2 (replace all text)
|
148
|
-
|
149
|
-
```Ruby
|
150
|
-
page = Page.new id: page_id, assign: [TitleProperty, "Title"]
|
151
|
-
tp = page.properties["Title"]
|
152
|
-
tp << TextObject.new("JKL")
|
153
|
-
page.save # API access
|
154
|
-
print page.title # -> JKL
|
155
|
-
```
|
103
|
+
1. [Set icon to all icon unsettled pages](examples/set_icon_to_all_icon_unsettled_pages.md)
|
104
|
+
1. [Renumbering pages](examples/renumbering_pages.md)
|
105
|
+
1. [Change title](examples/change_title.md)
|
156
106
|
|
157
107
|
## 3. Preparation
|
158
108
|
|
@@ -165,24 +115,35 @@ Please check [Notion documentation](https://developers.notion.com/docs#getting-s
|
|
165
115
|
Please create a client (notion-ruby-client) before you use the following class.
|
166
116
|
|
167
117
|
```Ruby
|
168
|
-
NotionCache.instance.create_client
|
118
|
+
NotionCache.instance.create_client "Secret_XXXXXXXXXXXXXXXXXXXX" # write directly
|
119
|
+
NotionCache.instance.create_client ENV["NOTION_API_TOKEN"] # from environment
|
169
120
|
```
|
170
121
|
|
171
122
|
## 4. Usage
|
172
123
|
|
124
|
+
From v0.3.0, `find`, `save` and `query_database` methods can set `dry_run: true` option. When this option is set, these methods create create a shell script for verification instead of calling the Notion API. Some sample codes show the results of dry_run in order to make it easy to understand what the method runs.
|
125
|
+
|
173
126
|
### 4.1 Page
|
174
127
|
|
175
128
|
#### 4.1.1 Retrieve a page
|
176
129
|
|
177
|
-
`Page.find(id)` creates a Page object with `retrieving page API`.
|
178
|
-
The created object has page information generated from the JSON response.
|
130
|
+
`Page.find(id)` creates a Page object with `retrieving page API`. The created object has page information generated from the JSON response.
|
179
131
|
|
180
132
|
```Ruby
|
181
133
|
page = Page.find "c01166c6-13ae-45cb-b968-18b4ef2f5a77" # Notion API call
|
182
134
|
```
|
183
135
|
|
184
|
-
|
185
|
-
|
136
|
+
- result of dry run
|
137
|
+
|
138
|
+
```bash
|
139
|
+
#!/bin/sh
|
140
|
+
curl 'https://api.notion.com/v1/pages/c01166c6-13ae-45cb-b968-18b4ef2f5a77' \
|
141
|
+
-H 'Notion-Version: 2022-02-22' \
|
142
|
+
-H 'Authorization: Bearer '"$NOTION_API_KEY"'' \
|
143
|
+
-H 'Content-Type: application/json'
|
144
|
+
```
|
145
|
+
|
146
|
+
`Page.new(id)` creates a Page object without the Notion API. Since Page.new does not acquire property information, so you need to assign yourself.
|
186
147
|
|
187
148
|
```Ruby
|
188
149
|
# Assign some properties for update manually
|
@@ -193,17 +154,14 @@ page = Page.new id: "c01166c6-13ae-45cb-b968-18b4ef2f5a77",
|
|
193
154
|
|
194
155
|
#### 4.1.2 Update page properties
|
195
156
|
|
196
|
-
Page properties with values can be obtained from the retrieved page using `find`.
|
197
|
-
On the other hand, Page properties without values can be obtained from the property assigned page.
|
157
|
+
Page properties with values can be obtained from the retrieved page using `find`. On the other hand, Page properties without values can be obtained from the property assigned page.
|
198
158
|
|
199
159
|
```Ruby
|
200
160
|
tp = page.properties["Title"] # TitleProperty
|
201
161
|
np = page.properties["Number"] # NumberProperty
|
202
162
|
```
|
203
163
|
|
204
|
-
Each property object can change values using corresponded methods.
|
205
|
-
After changing value, `will_update` flag of the property object also set to true.
|
206
|
-
These methods are explained in the section of each property object class.
|
164
|
+
Each property object can change values using corresponded methods. After changing value, `will_update` flag of the property object also set to true. These methods are explained in the section of each property object class.
|
207
165
|
|
208
166
|
```Ruby
|
209
167
|
to = tp[1] # TitleProperty has Array of TextObject
|
@@ -211,21 +169,20 @@ to.text = "ABC" # TextObject can set text by ".text="
|
|
211
169
|
# or tp[1].text = "ABC"
|
212
170
|
|
213
171
|
np.number = 3.14159
|
214
|
-
page.save # Notion API call
|
215
172
|
```
|
216
173
|
|
217
174
|
After update some properties, `page.save` method sends `Notion API` and replace the page information using the response of API.
|
218
175
|
|
219
176
|
```Ruby
|
220
|
-
page.
|
177
|
+
page.save # Notion API call
|
221
178
|
```
|
222
179
|
|
223
180
|
#### 4.1.3 Update other page information
|
224
181
|
|
225
182
|
`page.set_icon` can change the page icon using emoji or external url.
|
226
183
|
|
227
|
-
[Breaking change on v0.2.2]
|
228
|
-
Please use `page.save` after `page.set_icon` if you want to update or create the page.
|
184
|
+
[Breaking change on v0.2.2]
|
185
|
+
`page.set_icon` has no longer calling the Notion API. Please use `page.save` after `page.set_icon` if you want to update or create the page.
|
229
186
|
|
230
187
|
```Ruby
|
231
188
|
# both methods call Notion API
|
@@ -238,7 +195,9 @@ obj.save
|
|
238
195
|
|
239
196
|
#### 4.1.4 other methods
|
240
197
|
|
198
|
+
- `Page.find id, dry_run: true` create shell script for verification.
|
241
199
|
- `page.save` call Notion API, and so on and replace object information.
|
200
|
+
- `page.save dry_run: true` create shell script for verification.
|
242
201
|
- `page.new_record?` returns true if the page was generated by `create_child_page`.
|
243
202
|
- `page.title` returns plain_text string of `Title`.
|
244
203
|
- `page.icon` returns JSON hash for the page icon.
|
@@ -248,15 +207,22 @@ obj.save
|
|
248
207
|
|
249
208
|
#### 4.2.1 Retrieve a database
|
250
209
|
|
251
|
-
`Database.find(id)` creates a Database object with `retrieving database API`.
|
252
|
-
The created object has database information generated from the JSON response.
|
210
|
+
`Database.find(id)` creates a Database object with `retrieving database API`. The created object has database information generated from the JSON response.
|
253
211
|
|
254
212
|
```Ruby
|
255
|
-
db = Database.find
|
213
|
+
db = Database.find "c37a2c66-e3aa-4a0d-a447-73de3b80c253" # Notion API call
|
214
|
+
```
|
215
|
+
|
216
|
+
```bash
|
217
|
+
# result of dry run
|
218
|
+
#!/bin/sh
|
219
|
+
curl 'https://api.notion.com/v1/databases/c37a2c66-e3aa-4a0d-a447-73de3b80c253'\
|
220
|
+
-H 'Notion-Version: 2022-02-22'\
|
221
|
+
-H 'Authorization: Bearer '"$NOTION_API_KEY"''\
|
222
|
+
-H 'Content-Type: application/json'
|
256
223
|
```
|
257
224
|
|
258
|
-
`Database.new(id)` creates a Database object without the Notion API.
|
259
|
-
Since Database.new does not acquire property information, so you need to assign yourself.
|
225
|
+
`Database.new(id)` creates a Database object without the Notion API. Since Database.new does not acquire property information, so you need to assign yourself.
|
260
226
|
|
261
227
|
```Ruby
|
262
228
|
# assign some properties for update manually
|
@@ -266,8 +232,7 @@ db = Database.new id: "c37a2c66-e3aa-4a0d-a447-73de3b80c253",
|
|
266
232
|
|
267
233
|
#### 4.2.2 Query a database
|
268
234
|
|
269
|
-
`db.query_database` obtains a List object with Page objects contained in the database.
|
270
|
-
You can obtain filtered and ordered pages using Query object.
|
235
|
+
`db.query_database` obtains a List object with Page objects contained in the database. You can obtain filtered and ordered pages using Query object.
|
271
236
|
|
272
237
|
```Ruby
|
273
238
|
# query_database method calls Notion API
|
@@ -275,11 +240,9 @@ db.query_database # retrieves all pages (no filter, no sort)
|
|
275
240
|
db.query_database query # retrieves using query
|
276
241
|
```
|
277
242
|
|
278
|
-
The query object can be generated from the Property objects included in the database object.
|
279
|
-
The Property object can be obtained from the retrieved or assigned database object like as the Page object.
|
243
|
+
The query object can be generated from the Property objects included in the database object. The Property object can be obtained from the retrieved or assigned database object like as the Page object.
|
280
244
|
|
281
|
-
`filter_xxxx` methods of the property objects generates a query object.
|
282
|
-
These methods are explained in the section of each property object class.
|
245
|
+
`filter_xxxx` methods of the property objects generates a query object. These methods are explained in the section of each property object class.
|
283
246
|
|
284
247
|
```Ruby
|
285
248
|
tp = db.properties["Title"]
|
@@ -289,8 +252,7 @@ pages = db.query_database query
|
|
289
252
|
|
290
253
|
##### 4.2.2.1 Complex conditions
|
291
254
|
|
292
|
-
Complex filters can be generated `and` / `or` methods of the Query object.
|
293
|
-
Here are some sample scripts and the json parameters created from them.
|
255
|
+
Complex filters can be generated `and` / `or` methods of the Query object. Here are some sample scripts and the json parameters created from them.
|
294
256
|
|
295
257
|
```Ruby
|
296
258
|
# Prepare some sample properties
|
@@ -500,8 +462,7 @@ query7 = np.filter_greater_than(100).and(np.filter_less_than(200))
|
|
500
462
|
|
501
463
|
##### 4.2.2.2 Sort criteria
|
502
464
|
|
503
|
-
Sort criteria can be appended to an existing query object.
|
504
|
-
If you don't use the previous filters, you can generate by `Query.new`.
|
465
|
+
Sort criteria can be appended to an existing query object. If you don't use the previous filters, you can generate by `Query.new`.
|
505
466
|
|
506
467
|
- sort criteria only
|
507
468
|
|
@@ -543,20 +504,183 @@ query13 = tp.filter_starts_with("A").ascending(tp)
|
|
543
504
|
[{"property" => "tp", "direction" => "ascending"}]
|
544
505
|
```
|
545
506
|
|
507
|
+
##### 4.2.2.3 Dry run sample
|
508
|
+
|
509
|
+
This is a sample script for query database. If dry_run flag is set, you can see the verification shell script.
|
510
|
+
|
511
|
+
```Ruby
|
512
|
+
db = Database.new id: tc.database_id, assign: [NumberProperty, "NumberTitle", UrlProperty, "UrlTitle"]
|
513
|
+
np, up = target.properties.values_at "NumberTitle", "UrlTitle"
|
514
|
+
query = np.filter_greater_than(100).and(up.filter_starts_with("https")).ascending(np)
|
515
|
+
print db.query_database query, dry_run: true
|
516
|
+
# => Result
|
517
|
+
# #!/bin/sh
|
518
|
+
# curl -X POST 'https://api.notion.com/v1/databases/XXXXX/query'\
|
519
|
+
# -H 'Notion-Version: 2022-02-22'\
|
520
|
+
# -H 'Authorization: Bearer '"$NOTION_API_KEY"''\
|
521
|
+
# -H 'Content-Type: application/json'\
|
522
|
+
# --data '{"filter":{"and":[{"property":"NumberTitle","number":{"greater_than":100}},{"property":"UrlTitle","url":{"starts_with":"https"}}]},"sorts":[{"property":"NumberTitle","direction":"ascending"}],"page_size":100}'⏎
|
523
|
+
|
524
|
+
|
525
|
+
```
|
526
|
+
|
546
527
|
#### 4.2.3 Create child page
|
547
528
|
|
548
|
-
`create_child_page` creates a child page object of the database.
|
549
|
-
After setting some properties, please call `page.save` to send page information to Notion.
|
529
|
+
`create_child_page` creates a child page object of the database. After setting some properties, please call `page.save` to send page information to Notion. Properties of the created child page are automatically assigned using the parent database.
|
550
530
|
|
551
531
|
```Ruby
|
552
|
-
page = db.create_child_page
|
532
|
+
page = db.create_child_page
|
553
533
|
page.properties["Name"] << "New Page"
|
554
534
|
page.save
|
555
535
|
```
|
556
536
|
|
557
|
-
|
537
|
+
- result of dry run
|
558
538
|
|
559
|
-
|
539
|
+
```bash
|
540
|
+
#!/bin/sh
|
541
|
+
curl -X POST 'https://api.notion.com/v1/pages'\
|
542
|
+
-H 'Notion-Version: 2022-02-22'\
|
543
|
+
-H 'Authorization: Bearer '"$NOTION_API_KEY"''\
|
544
|
+
-H 'Content-Type: application/json'\
|
545
|
+
--data '{"properties":{"Name":{"type":"title","title":[{"type":"text","text":{"content":"New Page","link":null},"plain_text":"New Page","href":null}]}},"parent":{"database_id":"c37a2c66e3aa4a0da44773de3b80c253"}}'⏎
|
546
|
+
```
|
547
|
+
|
548
|
+
#### 4.2.4 Create database
|
549
|
+
|
550
|
+
`create_child_database` method of an existing page creates a child database object. Some properties of the database can be arrange the option. Here is a sample script for creating a database that set all types of properties.
|
551
|
+
|
552
|
+
```Ruby
|
553
|
+
page = Page.find "a sample page id"
|
554
|
+
db = parent_page.create_child_database "New database title",
|
555
|
+
CheckboxProperty, "Checkbox",
|
556
|
+
CreatedByProperty, "CreatedBy",
|
557
|
+
CreatedTimeProperty, "CreatedTime",
|
558
|
+
DateProperty, "Date",
|
559
|
+
EmailProperty, "Email",
|
560
|
+
FilesProperty, "Files",
|
561
|
+
FormulaProperty, "Formula",
|
562
|
+
LastEditedByProperty, "LastEditedBy",
|
563
|
+
LastEditedTimeProperty, "LastEditedTime",
|
564
|
+
MultiSelectProperty, "MultiSelect",
|
565
|
+
NumberProperty, "Number",
|
566
|
+
PeopleProperty, "People",
|
567
|
+
PhoneNumberProperty, "PhoneNumber",
|
568
|
+
RelationProperty, "Relation",
|
569
|
+
RollupProperty, "Rollup",
|
570
|
+
RichTextProperty, "RichText",
|
571
|
+
SelectProperty, "Select",
|
572
|
+
TitleProperty, "Title",
|
573
|
+
UrlProperty, "Url"
|
574
|
+
fp, msp, np, rp, rup, sp = db.properties.values_at "Formula", "MultiSelect", "Number", "Relation", "Rollup", "Select"
|
575
|
+
fp.formula_expression = "now()"
|
576
|
+
msp.add_multi_select_options name: "MS1", color: "orange"
|
577
|
+
msp.add_multi_select_options name: "MS2", color: "green"
|
578
|
+
np.format = "yen"
|
579
|
+
rp.replace_relation_database database_id: tc.database_id
|
580
|
+
rup.relation_property_name = "Relation"
|
581
|
+
rup.rollup_property_name = "NumberTitle"
|
582
|
+
rup.function = "sum"
|
583
|
+
sp.add_select_options name: "S1", color: "yellow"
|
584
|
+
sp.add_select_options name: "S2", color: "default"
|
585
|
+
db.set_icon emoji: "🎉"
|
586
|
+
db.save
|
587
|
+
```
|
588
|
+
|
589
|
+
#### 4.2.5 Update database properties
|
590
|
+
|
591
|
+
`save` method updates existing database properties. The database needs to be retrieved using `find` to prevent existing settings from disappearing.
|
592
|
+
|
593
|
+
```Ruby
|
594
|
+
db = Database.find "c7697137d49f49c2bbcdd6a665c4f921"
|
595
|
+
fp, msp, np, rp, rup, sp = db.properties.values_at "Formula", "MultiSelect", "Number", "Relation", "Rollup", "Select"
|
596
|
+
fp.formula_expression = "pi"
|
597
|
+
msp.add_multi_select_options name: "MS3", color: "blue"
|
598
|
+
np.format = "percent"
|
599
|
+
rp.replace_relation_database database_id: tc.database_id, synced_property_name: "Renamed table"
|
600
|
+
rup.function = "average"
|
601
|
+
sp.add_select_options name: "S3", color: "red"
|
602
|
+
db.set_icon emoji: "🎉"
|
603
|
+
db.database_title << "(Added)"
|
604
|
+
db.save
|
605
|
+
```
|
606
|
+
|
607
|
+
#### 4.2.6 Add a database property
|
608
|
+
|
609
|
+
`add_property` can add a database property.
|
610
|
+
|
611
|
+
```Ruby
|
612
|
+
db = Database.find "c7697137d49f49c2bbcdd6a665c4f921"
|
613
|
+
db.add_property NumberProperty, "added number property" do |np|
|
614
|
+
np.format = "euro" # arrange option
|
615
|
+
end
|
616
|
+
db.add_property UrlProperty, "added url property" # UrlProperty has no option
|
617
|
+
db.save
|
618
|
+
```
|
619
|
+
|
620
|
+
- result of dry run
|
621
|
+
|
622
|
+
```bash
|
623
|
+
#!/bin/sh
|
624
|
+
curl -X PATCH 'https://api.notion.com/v1/databases/c7697137d49f49c2bbcdd6a665c4f921'\
|
625
|
+
-H 'Notion-Version: 2022-02-22'\
|
626
|
+
-H 'Authorization: Bearer '"$NOTION_API_KEY"''\
|
627
|
+
-H 'Content-Type: application/json'\
|
628
|
+
--data '{"properties":{"added number property":{"number":{"format":"euro"}},"added url property":{"url":{}}}}'⏎
|
629
|
+
```
|
630
|
+
|
631
|
+
#### 4.2.7 Rename a database property
|
632
|
+
|
633
|
+
`rename_property` can rename a database property.
|
634
|
+
|
635
|
+
```Ruby
|
636
|
+
properties = db.properties
|
637
|
+
properties["added number property"].new_name = "renamed number property"
|
638
|
+
properties["added url property"].new_name = "renamed url property"
|
639
|
+
db.save
|
640
|
+
```
|
641
|
+
|
642
|
+
- result of dry run
|
643
|
+
|
644
|
+
```bash
|
645
|
+
#!/bin/sh
|
646
|
+
curl -X PATCH 'https://api.notion.com/v1/databases/c7697137d49f49c2bbcdd6a665c4f921'\
|
647
|
+
-H 'Notion-Version: 2022-02-22'\
|
648
|
+
-H 'Authorization: Bearer '"$NOTION_API_KEY"''\
|
649
|
+
-H 'Content-Type: application/json'\
|
650
|
+
--data '{"properties":{"added number property":{"name":"renamed number property"},"added url property":{"name":"renamed url property"}}}'
|
651
|
+
```
|
652
|
+
|
653
|
+
#### 4.2.8 Remove database properties
|
654
|
+
|
655
|
+
`remove_properties' can remove some database properties.
|
656
|
+
|
657
|
+
```Ruby
|
658
|
+
db.remove_property "renamed number property", "renamed url property"
|
659
|
+
```
|
660
|
+
|
661
|
+
- result of dry run
|
662
|
+
|
663
|
+
```bash
|
664
|
+
#!/bin/sh
|
665
|
+
curl -X PATCH 'https://api.notion.com/v1/databases/c7697137d49f49c2bbcdd6a665c4f921'\
|
666
|
+
-H 'Notion-Version: 2022-02-22'\
|
667
|
+
-H 'Authorization: Bearer '"$NOTION_API_KEY"''\
|
668
|
+
-H 'Content-Type: application/json'\
|
669
|
+
--data '{"properties":{"renamed number property":null,"renamed url property":null}}'
|
670
|
+
```
|
671
|
+
|
672
|
+
#### 4.2.9 other methods
|
673
|
+
|
674
|
+
- `Database.find id, dry_run: true` create shell script for verification.
|
675
|
+
- `db.save` call Notion API, and so on and replace object information.
|
676
|
+
- `db.save dry_run: true` create shell script for verification.
|
677
|
+
- `db.new_record?` returns true if the database was generated by `create_child_database`.
|
678
|
+
- `db.database_title` returns plain_text string of `Database`.
|
679
|
+
- `db.title` returns plain_text string of `TitleProperty`.
|
680
|
+
- `db.icon` returns JSON hash for the page icon.
|
681
|
+
- `db[key]` returns a hash or an array object except "properties".
|
682
|
+
- `db.created_time` returns CreatedTimeProperty for filter
|
683
|
+
- `db.last_edited_time` returns LastEditedTimeProperty for filter
|
560
684
|
|
561
685
|
### 4.3 List class
|
562
686
|
|
@@ -614,9 +738,11 @@ xp = page.properties["property_name"]
|
|
614
738
|
xp, yp = page.properties.values_at "xp_name", "yp_name"
|
615
739
|
```
|
616
740
|
|
741
|
+
Page properties and database properties are objects of the same class, but there are methods for page properties and methods for database properties.
|
742
|
+
|
617
743
|
#### 4.5.2 Query object generator of property objects
|
618
744
|
|
619
|
-
The following methods for the Property objects generate a query object.
|
745
|
+
The following methods for the Property objects generate a query object. These methods can be used for page properties and database properties.
|
620
746
|
|
621
747
|
- TitleProperty, RichTextProperty, UrlProperty, EmailProperty, PhoneNumberProperty
|
622
748
|
- filter_equals(value)
|
@@ -691,11 +817,9 @@ The following methods for the Property objects generate a query object.
|
|
691
817
|
|
692
818
|
#### 4.5.3 create or update values for Page properties
|
693
819
|
|
694
|
-
Retrieving Page object has XXXProperties with values.
|
695
|
-
On the other hand, Assigned Page object has also XXXProperties, but they don't have any information for pages.
|
820
|
+
Retrieving Page object with `find` method has page properties of XXXProperties with values. On the other hand, Assigned Page object has also XXXProperties, but they don't have any information for pages.
|
696
821
|
|
697
|
-
XXXProperties can change property values by setter methods.
|
698
|
-
Since the setter method is different for each class, it will be explained separately.
|
822
|
+
XXXProperties can change property values by setter methods. Since the setter method is different for each class, it will be explained separately.
|
699
823
|
|
700
824
|
##### 4.5.3.1 NumberProperty
|
701
825
|
|
@@ -710,7 +834,7 @@ p np.property_values_json
|
|
710
834
|
|
711
835
|
##### 4.5.3.2 SelectProperty
|
712
836
|
|
713
|
-
|
837
|
+
SelectProperty can set a select name by `.select=`.
|
714
838
|
|
715
839
|
```Ruby
|
716
840
|
sp = page.properties["SelectTitle"]
|
@@ -869,7 +993,7 @@ p tp.property_values_json
|
|
869
993
|
|
870
994
|
##### 4.5.3.9 CheckboxProperty
|
871
995
|
|
872
|
-
|
996
|
+
CheckboxProperty can set a boolean value by `.checkbox=`.
|
873
997
|
|
874
998
|
```Ruby
|
875
999
|
cp = page.properties["CheckboxTitle"]
|
@@ -878,18 +1002,7 @@ p cp.property_values_json
|
|
878
1002
|
# result => {"cp"=>{"checkbox"=>true, "type"=>"checkbox"}}
|
879
1003
|
```
|
880
1004
|
|
881
|
-
##### 4.5.3.10
|
882
|
-
|
883
|
-
EmailProperty can set an email address by `.email=`.
|
884
|
-
|
885
|
-
```Ruby
|
886
|
-
ep = page.properties["MailTitle"]
|
887
|
-
ep.email = "hkobhkob@gmail.com"
|
888
|
-
p ep.property_values_json
|
889
|
-
# result => {"ep"=>{"email"=>"hkobhkob@gmail.com", "type"=>"email"}}
|
890
|
-
```
|
891
|
-
|
892
|
-
##### 4.5.3.11 FilesProperty
|
1005
|
+
##### 4.5.3.10 FilesProperty
|
893
1006
|
|
894
1007
|
FilesProperty can set an external url or Array of external urls by `.files=`.
|
895
1008
|
|
@@ -904,7 +1017,7 @@ p fp.property_values_json
|
|
904
1017
|
# Result => {"fp"=>{"files"=>[{"name"=>"F2", "type"=>"external", "external"=>{"url"=>"F2"}}, {"name"=>"F3", "type"=>"external", "external"=>{"url"=>"F3"}}], "type"=>"files"}}
|
905
1018
|
```
|
906
1019
|
|
907
|
-
##### 4.5.3.
|
1020
|
+
##### 4.5.3.11 RelationProperty
|
908
1021
|
|
909
1022
|
RelationProperty can set an relation's page_id or Array of relation's page_ids by `.relation=`.
|
910
1023
|
|
@@ -919,7 +1032,167 @@ p rp.property_values_json
|
|
919
1032
|
# Result => {"rp"=>{"type"=>"relation", "relation"=>[{"id"=>"R2"}, {"id"=>"R3"}]}}
|
920
1033
|
```
|
921
1034
|
|
922
|
-
|
1035
|
+
#### 4.5.4 create or update values for Database properties
|
1036
|
+
|
1037
|
+
Retrieving Database object with `find` method has database properties of XXXProperties with values. On the other hand, Assigned Database object has also XXXProperties, but they don't have any information for databases.
|
1038
|
+
|
1039
|
+
XXXProperties can change property values by setter methods. Since the setter method is different for each class, it will be explained separately.
|
1040
|
+
|
1041
|
+
##### 4.5.4.1 NumberProperty
|
1042
|
+
|
1043
|
+
NumberProperty can set a format by `.format=`.
|
1044
|
+
|
1045
|
+
```Ruby
|
1046
|
+
np = db.properties["NumberTitle"]
|
1047
|
+
np.format = "percent"
|
1048
|
+
print np.property_schema_json
|
1049
|
+
# Result => {"NumberTitle"=>{"number"=>{"format"=>"percent"}}}
|
1050
|
+
```
|
1051
|
+
|
1052
|
+
##### 4.5.4.2 SelectProperty
|
1053
|
+
|
1054
|
+
SelectProperty can add a new option by `.add_select_options`.
|
1055
|
+
|
1056
|
+
```Ruby
|
1057
|
+
sp = db.properties["SelectTitle"]
|
1058
|
+
sp.add_select_options name: "S3", color: "red"
|
1059
|
+
print sp.property_schema_json
|
1060
|
+
# Result => {"Select"=>{"select"=>{"options"=>[{"id"=>"56a526e1-0cec-4b85-b9db-fc68d00e50c6", "name"=>"S1", "color"=>"yellow"}, {"id"=>"6ead7aee-d7f0-40ba-aa5e-59bccf6c50c8", "name"=>"S2", "color"=>"default"}, {"name"=>"S3", "color"=>"red"}]}}}
|
1061
|
+
```
|
1062
|
+
|
1063
|
+
If you want to edit existing values, you should access `edit_select_options` array. It sets `will_update` flag to true.
|
1064
|
+
|
1065
|
+
```Ruby
|
1066
|
+
sp.edit_select_options[0]["name"] = "new S1"
|
1067
|
+
p sp.property_values_json
|
1068
|
+
# Result => {"Select"=>{"select"=>{"options"=>[{"id"=>"56a526e1-0cec-4b85-b9db-fc68d00e50c6", "name"=>"new S1", "color"=>"yellow"}, {"id"=>"6ead7aee-d7f0-40ba-aa5e-59bccf6c50c8", "name"=>"S2", "color"=>"default"}]}}}⏎
|
1069
|
+
```
|
1070
|
+
|
1071
|
+
##### 4.5.4.3 MultiSelectProperty
|
1072
|
+
|
1073
|
+
MultiSelectProperty can add a new option by `.add_multi_select_options`.
|
1074
|
+
|
1075
|
+
```Ruby
|
1076
|
+
msp = db.properties["MultiSelectTitle"]
|
1077
|
+
msp.add_multi_select_options name: "MS3", color: "blue"
|
1078
|
+
print msp.property_schema_json
|
1079
|
+
# Result => {"MultiSelectTitle"=>{"multi_select"=>{"options"=>[{"id"=>"98aaa1c0-4634-47e2-bfae-d739a8c5e564", "name"=>"MS1", "color"=>"orange"}, {"id"=>"71756a93-cfd8-4675-b508-facb1c31af2c", "name"=>"MS2", "color"=>"green"}, {"name"=>"MS3", "color"=>"blue"}]}}}
|
1080
|
+
```
|
1081
|
+
|
1082
|
+
If you want to edit existing values, you should access `edit_multi_select_options` array. It sets `will_update` flag to true.
|
1083
|
+
|
1084
|
+
```Ruby
|
1085
|
+
msp.edit_multi_select_options[0]["name"] = "new MS1"
|
1086
|
+
p msp.property_values_json
|
1087
|
+
# Result => {"MultiSelectTitle"=>{"multi_select"=>{"options"=>[{"id"=>"98aaa1c0-4634-47e2-bfae-d739a8c5e564", "name"=>"new MS1", "color"=>"orange"}, {"id"=>"71756a93-cfd8-4675-b508-facb1c31af2c", "name"=>"MS2", "color"=>"green"}]}}}⏎
|
1088
|
+
```
|
1089
|
+
|
1090
|
+
##### 4.5.4.4 DateProperty
|
1091
|
+
|
1092
|
+
DateProperty has no option.
|
1093
|
+
|
1094
|
+
```Ruby
|
1095
|
+
dp = db.properties["DateTitle"]
|
1096
|
+
print dp.property_schema_json
|
1097
|
+
# Result => {"DateTitle"=>{"date"=>{}}}
|
1098
|
+
```
|
1099
|
+
|
1100
|
+
##### 4.5.4.4 UrlProperty
|
1101
|
+
|
1102
|
+
UrlProperty has no option.
|
1103
|
+
|
1104
|
+
```Ruby
|
1105
|
+
up = db.properties["UrlTitle"]
|
1106
|
+
print up.property_schema_json
|
1107
|
+
# Result => {"UrlTitle"=>{"url"=>{}}}
|
1108
|
+
```
|
1109
|
+
|
1110
|
+
##### 4.5.4.5 EmailProperty
|
1111
|
+
|
1112
|
+
EmailProperty has no option.
|
1113
|
+
|
1114
|
+
```Ruby
|
1115
|
+
ep = db.properties["MailTitle"]
|
1116
|
+
print ep.property_schema_json
|
1117
|
+
# Result => {"MailTitle"=>{"email"=>{}}}
|
1118
|
+
```
|
1119
|
+
|
1120
|
+
##### 4.5.4.6 PhoneNumberProperty
|
1121
|
+
|
1122
|
+
PhoneNumberProperty has no option.
|
1123
|
+
|
1124
|
+
```Ruby
|
1125
|
+
pp = db.properties["TelTitle"]
|
1126
|
+
print ep.property_schema_json
|
1127
|
+
# Result => {"TelTitle"=>{"phone_number"=>{}}}
|
1128
|
+
```
|
1129
|
+
|
1130
|
+
##### 4.5.4.7 PeopleProperty
|
1131
|
+
|
1132
|
+
PeopleProperty has no option.
|
1133
|
+
|
1134
|
+
```Ruby
|
1135
|
+
usp = db.properties["UserTitle"]
|
1136
|
+
print usp.property_schema_json
|
1137
|
+
# Result => {"UserTitle"=>{"people"=>{}}}
|
1138
|
+
```
|
1139
|
+
|
1140
|
+
##### 4.5.4.8 TitleProperty, RichTextProperty
|
1141
|
+
|
1142
|
+
TitleProperty and RichTextProperty have no option.
|
1143
|
+
|
1144
|
+
```Ruby
|
1145
|
+
tp, rtp = db.properties.values_at "Title", "TextTitle"
|
1146
|
+
print tp.property_schema_json
|
1147
|
+
# Result => {"Title"=>{"title"=>{}}}
|
1148
|
+
print rtp.property_schema_json
|
1149
|
+
# Result => {"TextTitle"=>{"rich_text"=>{}}}
|
1150
|
+
```
|
1151
|
+
|
1152
|
+
##### 4.5.4.9 CheckboxProperty
|
1153
|
+
|
1154
|
+
CheckboxProperty has no option.
|
1155
|
+
|
1156
|
+
```Ruby
|
1157
|
+
cp = db.properties["CheckboxTitle"]
|
1158
|
+
print cp.property_schema_json
|
1159
|
+
# Result => {"CheckboxTitle"=>{"checkbox"=>{}}}
|
1160
|
+
```
|
1161
|
+
|
1162
|
+
##### 4.5.4.10 FilesProperty
|
1163
|
+
|
1164
|
+
FilesProperty has no option.
|
1165
|
+
|
1166
|
+
```Ruby
|
1167
|
+
fp = db.properties["FilesTitle"]
|
1168
|
+
print fp.property_schema_json
|
1169
|
+
# Result => {"FilesTitle"=>{"files"=>{}}}
|
1170
|
+
```
|
1171
|
+
|
1172
|
+
##### 4.5.4.11 RelationProperty
|
1173
|
+
|
1174
|
+
RelationProperty can set an relation's database_id by `.replace_relation_database`.
|
1175
|
+
|
1176
|
+
```Ruby
|
1177
|
+
rp = db.properties["RelationTitle"]
|
1178
|
+
rp.replace_relation_database database_id: "new database id"
|
1179
|
+
p rp.property_values_json
|
1180
|
+
# Result => {"Relation"=>{"relation"=>{"database_id"=>"new database id"}}}
|
1181
|
+
```
|
1182
|
+
|
1183
|
+
##### 4.5.4.12 RollupProperty
|
1184
|
+
|
1185
|
+
RollupProperty can set rollup property name, relation property name and function by `.rollup_property_name=`, `relation_property_name=` and `function=`, respectively.
|
1186
|
+
|
1187
|
+
```Ruby
|
1188
|
+
rup = db.properties["RollupTitle"]
|
1189
|
+
rup.relation_property_name = "new relation property name"
|
1190
|
+
rup.rollup_property_name = "new rollup property name"
|
1191
|
+
rup.function = "average"
|
1192
|
+
# Result => {"Rollup"=>{"rollup"=>{"function"=>"average", "relation_property_name"=>"new relation property name", "rollup_property_name"=>"new rollup property name"}}}
|
1193
|
+
```
|
1194
|
+
|
1195
|
+
## 5. XXXObjects and RichTextArray
|
923
1196
|
|
924
1197
|
### 5.1 RichTextObject
|
925
1198
|
|
@@ -969,8 +1242,34 @@ UserObject is a class for users.
|
|
969
1242
|
u = User.new id: "user_id"
|
970
1243
|
```
|
971
1244
|
|
1245
|
+
### 5.5 RichTextArray
|
1246
|
+
|
1247
|
+
Some properties and Database title have an array of RichTextObject. `RichTextArray` is the delegate class for the array of RichTextObject.
|
1248
|
+
Moreover, some methods of TitleProperty, RichTextProperty and Database.title delegate to the included RichTextArray.
|
1249
|
+
|
1250
|
+
#### 5.5.1 Constructor for RichTextArray
|
1251
|
+
|
1252
|
+
RichTextArray can be created by a String, some Strings, a RichTextObject and some RichTextObjects. String values will convert to simple TextObjects.
|
1253
|
+
|
1254
|
+
```Ruby
|
1255
|
+
nullString = RichTextArray.new "title"
|
1256
|
+
aString = RichTextArray.new "title", text_objects: "A string"
|
1257
|
+
twoStrings = RichTextArray.new "title", text_objects: %W[ABC\n DEF]
|
1258
|
+
aTextObject = RichTextArray.new "title", text_objects: TextObject.new "A TextObject"
|
1259
|
+
textMentionObjects = RichTextArray.new "title", [TextObject.new("A TextObject"), MentionObject.new(user_id: "ABC")]
|
1260
|
+
```
|
1261
|
+
|
1262
|
+
#### 5.5.2 Instance methods
|
1263
|
+
|
1264
|
+
- `rto << text_or_text_object`: append a text or RichTextObject
|
1265
|
+
- `rto[0]`: obtain the object specified by the index
|
1266
|
+
- `delete_at 0`: obtain the object specified by the index and delete from the array
|
1267
|
+
- `full_text`: obtain joined plain text
|
1268
|
+
|
972
1269
|
## 6. ChangeLog
|
973
1270
|
|
1271
|
+
- 2022/3/27 properties of a created child page are automatically assigned using the parent database.
|
1272
|
+
- 2022/3/25 added create_child_database, update_database, add_property, rename_property and remove_property
|
974
1273
|
- 2022/3/17 added template_mention objects, tools/an command
|
975
1274
|
- 2022/3/16 added database.create_child_page and base.save instead of base.update/create
|
976
1275
|
- 2022/3/15 Fixed not to reload from API when all contents are loaded
|