Page

1. Class methods

self.find(id, dry_run: false) →
🧱
Page

[PARAM] id page_id (String)

[PARAM(optional)] dry_run: true if you want to create a verification script

[EXCEPTION] StandardError: throw StandardError when the page is not found.

Page.find(id) creates a Page object with retrieving page API. The created object has page information generated from the JSON response.


page = Page.find "c01166c6-13ae-45cb-b968-18b4ef2f5a77"# Notion API call
# => #<NotionRubyMapping::Page:...> # retrieved Page object

Page.find(id, dry_run: true) creates a shell script using Retrieve a page API for verification.


page = Page.find "c01166c6-13ae-45cb-b968-18b4ef2f5a77", dry_run: true
# => 
# #!/bin/sh
# curl  'https://api.notion.com/v1/pages/c01166c6-13ae-45cb-b968-18b4ef2f5a77' \
#   -H 'Notion-Version: 2022-02-22' \
#   -H 'Authorization: Bearer '"$NOTION_API_KEY"'' \
#   -H 'Content-Type: application/json'

2. Instance methods

append_block_children(*blocks, dry_run: false) → Array<Block>, String

[PARAM] blocks array of blocks

[PARAM(optional)] dry_run: true if you want to create a verification script

append_block_children method of an existing page appends some block objects. Some blocks allow child blocks to be set up at the same time. However, due to API limitations, grandchild blocks cannot be created at once. There are many types of blocks, so check the page(

🧪

Append block children sample) to see how to create blocks.


parent_page = Page.find "206ffaa277744a99baf593e28730240c"
parent_page.append_block_children CodeBlock.new("% ls -l", caption: "List files")
# => 
# #<NotionRubyMapping::Block:0x00000001064431d8

append_block_children(blocks, dry_run: true) creates a shell script using Append block children API for verification.


parent_page.append_block_children(Block.new.code("% ls -l", caption: "List files"), dry_run: true)
# => "#!/bin/sh\ncurl -X PATCH 'https://api.notion.com/v1/blocks/206ffaa277744a99baf593e28730240c/children' \\\n  -H 'Notion-Version: 2022-02-22' \\\n  -H 'Authorization: Bearer '\"$NOTION_API_KEY\"'' \\\n  -H 'Content-Type: application/json' \\\n  --data '{\"children\":[{\"type\":\"code\",\"object\":\"block\",\"code\":{\"rich_text\":[{\"type\":\"text\",\"text\":{\"content\":\"% ls -l\",\"link\":null},\"plain_text\":\"% ls -l\",\"href\":null}],\"caption\":[{\"type\":\"text\",\"text\":{\"content\":\"List files\",\"link\":null},\"plain_text\":\"List files\",\"href\":null}],\"language\":\"shell\"}}]}'"

build_child_database(title, *assigns) { |d, pc| ... } →
🧱
Database

[PARAM] title Database title

[PARAM] assigns variable-length array of property class and property name pairs

build_child_database method of an existing page creates a child database object. Some properties of the database can be arrange the option. if a block is provided, the method will yield the new Database object(d) and the properties (PropertyCache object pc) to that block for initialization. After setting some properties, please call db.save to send database information to Notion. If you can set properties in the block, please use create_child_database instead of build_child_database + save. Here is a sample script for creating a database that set all types of properties.


parent_page = Page.find "206ffaa277744a99baf593e28730240c"
db = parent_page.build_child_database "New database title",
                                      CheckboxProperty, "Checkbox",
                                      CreatedByProperty, "CreatedBy",
                                      CreatedTimeProperty, "CreatedTime",
                                      DateProperty, "Date",
                                      EmailProperty, "Email",
                                      FilesProperty, "Files",
                                      FormulaProperty, "Formula",
                                      LastEditedByProperty, "LastEditedBy",
                                      LastEditedTimeProperty, "LastEditedTime",
                                      MultiSelectProperty, "MultiSelect",
                                      NumberProperty, "Number",
                                      PeopleProperty, "People",
                                      PhoneNumberProperty, "PhoneNumber",
                                      RelationProperty, "Relation",
                                      RollupProperty, "Rollup",
                                      RichTextProperty, "RichText",
                                      SelectProperty, "Select",
                                      TitleProperty, "Title",
                                      UrlProperty, "Url" do |d, pc|
  fp, msp, np, rp, rup, sp = pc.values_at "Formula", "MultiSelect", "Number", "Relation", "Rollup", "Select"
  fp.formula_expression = "now()"
  msp.add_multi_select_options name: "MS1", color: "orange"
  msp.add_multi_select_options name: "MS2", color: "green"
  np.format = "yen"
  rp.replace_relation_database database_id: TestConnection::DATABASE_ID
  rup.relation_property_name = "Relation"
  rup.rollup_property_name = "NumberTitle"
  rup.function = "sum"
  sp.add_select_options name: "S1", color: "yellow"
  sp.add_select_options name: "S2", color: "default"
  d.set_icon emoji: "🎉"
end
db.save
# => #<NotionRubyMapping::Database:...> # created Database object

db.save(dry_run: true) creates a shell script using Create a database API for verification.


page = Page.new id: "206ffaa277744a99baf593e28730240c"
db = page.build_child_database "New database title",
                                TitleProperty, "test-title",
                                RichTextProperty, "test-text"
print db.save dry_run: true
# =>
# #!/bin/sh
# curl -X POST 'https://api.notion.com/v1/databases' \
#   -H 'Notion-Version: 2022-02-22' \
#   -H 'Authorization: Bearer '"$NOTION_API_KEY"'' \
#   -H 'Content-Type: application/json' \
#   --data '{"properties":{"test-title":{"title":{}},"test-text":{"rich_text":{}}},"title":[{"type":"text","text":{"content":"New database title","link":null},"plain_text":"New database title","href":null}],"parent":{"type":"page_id","page_id":"206ffaa277744a99baf593e28730240c"}}'

create_child_database(title, *assigns, dry_run: false) { |d, pc| ... } →
🧱
Database

💡

[Breaking change on v0.4.0] For compatibility with Rails, create_child_database is renamed to build_child_database. create_child_database calls build_child_database and save.

[PARAM] title Database title

[PARAM] assigns variable-length array of property class and property name pairs

[PARAM (optional)] dry_run: true if you want to create a verification script

create_child_database method of an existing page creates a child database object and send to Notion. Some properties of the database can be arrange the option. if a block is provided, the method will yield the new Database object(d) and the properties (PropertyCache object pc) to that block for initialization. Here is a sample script for creating a database that set all types of properties.


parent_page = Page.find "206ffaa277744a99baf593e28730240c"
db = parent_page.create_child_database "New database title",
                                       CheckboxProperty, "Checkbox",
                                       CreatedByProperty, "CreatedBy",
                                       CreatedTimeProperty, "CreatedTime",
                                       DateProperty, "Date",
                                       EmailProperty, "Email",
                                       FilesProperty, "Files",
                                       FormulaProperty, "Formula",
                                       LastEditedByProperty, "LastEditedBy",
                                       LastEditedTimeProperty, "LastEditedTime",
                                       MultiSelectProperty, "MultiSelect",
                                       NumberProperty, "Number",
                                       PeopleProperty, "People",
                                       PhoneNumberProperty, "PhoneNumber",
                                       RelationProperty, "Relation",
                                       RollupProperty, "Rollup",
                                       RichTextProperty, "RichText",
                                       SelectProperty, "Select",
                                       TitleProperty, "Title",
                                       UrlProperty, "Url" do |d, pc|
  fp, msp, np, rp, rup, sp = pc.values_at "Formula", "MultiSelect", "Number", "Relation", "Rollup", "Select"
  fp.formula_expression = "now()"
  msp.add_multi_select_options name: "MS1", color: "orange"
  msp.add_multi_select_options name: "MS2", color: "green"
  np.format = "yen"
  rp.replace_relation_database database_id: TestConnection::DATABASE_ID
  rup.relation_property_name = "Relation"
  rup.rollup_property_name = "NumberTitle"
  rup.function = "sum"
  sp.add_select_options name: "S1", color: "yellow"
  sp.add_select_options name: "S2", color: "default"
  d.set_icon emoji: "🎉"
end
# => #<NotionRubyMapping::Database:...> # created Database object

db.save(dry_run: true) creates a shell script using Create a database API for verification.


page = Page.new id: "206ffaa277744a99baf593e28730240c"
print page.create_child_database "New database title",
                                TitleProperty, "test-title",
                                RichTextProperty, "test-text",
                                dry_run: true
# =>
# #!/bin/sh
# curl -X POST 'https://api.notion.com/v1/databases' \
#   -H 'Notion-Version: 2022-02-22' \
#   -H 'Authorization: Bearer '"$NOTION_API_KEY"'' \
#   -H 'Content-Type: application/json' \
#   --data '{"properties":{"test-title":{"title":{}},"test-text":{"rich_text":{}}},"title":[{"type":"text","text":{"content":"New database title","link":null},"plain_text":"New database title","href":null}],"parent":{"type":"page_id","page_id":"206ffaa277744a99baf593e28730240c"}}'

created_time → CreatedTimeProperty

created_time returns the CreatedTimeProperty object for querying database.


page.created_time
# => #<NotionRubyMapping::CreatedTimeProperty:...> # CreatedTimeProperty object

icon → Hash

icon returns JSON hash for the page icon.


page.icon
# =>
# {"type"=>"external",
#  "external"=>
#   {"url"=>"https://cdn.profile-image.st-hatena.com/users/hkob/profile.png"}}

last_edited_time → LastEditedTimeProperty

last_edited_time returns theLastEditedTimeProperty object for querying database.


db.last_edited_time
# => #<NotionRubyMapping::LastEditedTimeProperty:...> # LastEditedTimeProperty object

new_record? → Boolean, NilClass

new_record? returns true if the page is generated by create_child_page.


page.new_record?
# => nil

parent(dry_run: false) →
🧱
Page
🧱
Database
🧱
Block, String

parent returns a parent object.


page.parent dry_run: true
# => "#!/bin/sh\ncurl  'https://api.notion.com/v1/databases/c37a2c66-e3aa-4a0d-a447-73de3b80c253' \\\n  -H 'Notion-Version: 2022-06-28' \\\n  -H 'Authorization: Bearer '\"$NOTION_API_KEY\"''"

page.parent
# => NotionRubyMapping::Database-c37a2c66e3aa4a0da44773de3b80c253

properties → PropertyCache

properties returns a PropertyCache object. Each Page property object can be obtained from PropertyCache object by [] method.


page.properties
# => #<NotionRubyMapping::PropertyCache:...>

page.properties["title"]
# => #<NotionRubyMapping::TitleProperty:...>

save(dry_run: false) →
🧱
Page

[PARAM (optional)] dry_run: true if you want to create a verification script

Page properties with values can be obtained from the retrieved page using find.


tp = page.properties["TextTitle"] # RichTextProperty
np = page.properties["Number"] # NumberProperty

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.


to = tp[1] # RichTextProperty has a RichTextArray object.  Each TextObject can obtain by []. 
to.text = "ABC" # TextObject can set text by ".text="
np.number = 3.14159 # The value of NumberProperty can be changed by .number.

After update some properties, page.save method sends Notion API and replace the page information using the response of API.


page.save # Notion API call
# => #<NotionRubyMapping::Page:...> # updated Page object

save dry_run: true creates a shell script using Update page API for verification


page.save dry_run: true
# => 
# curl -X PATCH 'https://api.notion.com/v1/pages/206ffaa277744a99baf593e28730240c' \
#   -H 'Notion-Version: 2022-02-22' \                               
#   -H 'Authorization: Bearer '"$NOTION_API_KEY"'' \                
#   -H 'Content-Type: application/json' \                           
#   --data '{"properties":{"TextTitle":{"type":"rich_text","rich_text":[{"type":"text","text":{"content":"new text","link":null},"plain_text":"new text","href":null,"annotations":{"bold":false,"italic":false,"strikethrough":false,"underline":false,"code":false,"color":"default"}},{"type":"text","text":{"content":"ABC","link":null},"plain_text":"ABC","href":null}]},"NumberTitle":{"number":3.14159,"type":"number"}}}'=> nil

set_icon(emoji: a_emoji) set_icon(url: a_url)

[PARAM(optional)] emoji

emoji string (String)

set_icon can change the page icon using emoji or external url.


# both methods call Notion API
obj.set_icon emoji: "💿" # set emoji
obj.save

obj.set_icon url: "<https://cdn.profile-image.st-hatena.com/users/hkob/profile.png>" # set external url
obj.save

💡

[Breaking change on v0.2.2] 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.

title → String

page.title returns plain_text string of Title.


page.title
# => "notion_ruby_mapping_test_data"