bridgetown-prismic 0.1.2 → 0.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 5527c934765e18198f16674eacd9443f5676aba706b9d58327c1ebe49c378234
-  data.tar.gz: fc37b56802422b8dbba4f4a5686891cd7db5466f7ee3b904d265446c4e645e5a
+  metadata.gz: c9490120f332e574829b9e86bb4e5cd8e116cc5d56459deaa6d008918d1259e7
+  data.tar.gz: 429b14738f5b6d15cee42b023085b71aa27ce69fcb9a108398efcabccc4aca33
 SHA512:
-  metadata.gz: cf5848a62d57b3fd43d501c36e7448cf2ae04600f9683a5faba03940f684c8ad7045218724bc9969b290c20e57b02061f7bf025ed1792d1a26743bc139b778ff
-  data.tar.gz: 6c4a1f4d5afeab66b929033f5a716a9c5d16e67305f80a71ff25534117276838ec8efed8845d849b434d7c1bb6cc371bf9d07edd7822a71413899b081a50f630
+  metadata.gz: 847aebd7f01e975dead3b109ff69d65171da42d1f2a163b1ebf2fc26ffffc5b54db23949ab7027687b20d5b02da6266a1bcb6c90191343658ddfe138d1be1e52
+  data.tar.gz: 1d3cde2d78fcd09a22fa26b67caec953a8f9074b101079ead246f74f6e1c19936b405c9e3857c56c9d97eb7612f3f9d459c4dadabe62800b24fbc42ed6920df9

data/CHANGELOG.md

@@ -9,6 +9,10 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ...
 
+## 0.2.0
+
+- Automatically paginate through results sets
+
 ## 0.1.2
 
 - Add hash option to `provide_data`

data/LICENSE.txt

@@ -1,6 +1,6 @@
 The MIT License (MIT)
 
-Copyright (c) 2020-present
+Copyright (c) 2021-present Jared White & Bridgetown contributors
 
 Permission is hereby granted, free of charge, to any person obtaining
 a copy of this software and associated documentation files (the

data/README.md

@@ -1,61 +1,297 @@
-# Sample plugin for Bridgetown
+# Bridgetown Prismic CMS Plugin
 
-_NOTE: This isn't a real plugin! Copy this sample code and use it to create your own Ruby gem! [Help guide here…](https://www.bridgetownrb.com/docs/plugins)_ 😃
+The [Bridgetown](https://edge.bridgetownrb.com) Prismic plugin allows you to pull content directly out of your [Prismic CMS](https://prismic.io) repository and generate resources you can use in all of your templates and plugins the same as if they were files saved directly in your site's `src` folder. Posts, pages, and any custom collections you want to set up are fully supported.
 
-_Starting with Bridgetown v0.15, you can run_ `bridgetown plugins new` _to easily set up a customized verison of this starter repo._
+In addition, this plugin allows you to set up draft previews so you can see how your content will look before it's published and deployed as a static site. This will require you to host a preview site on a platform which supports Ruby Rack-based applications. We recommend [Render](https://render.com), but you can use Heroku or most other platforms which support Ruby (Rails, etc.).
 
-A Bridgetown plugin to [fill in the blank]…
+This plugin requires Ruby 3 and the latest alpha version of [Bridgetown 1.0](https://edge.bridgetownrb.com).
 
 ## Installation
 
-Run this command to add this plugin to your site's Gemfile:
+Add the gem to your Gemfile and set up initial configuration by running the automation script:
 
-```shell
-$ bundle add my-awesome-plugin -g bridgetown_plugins
+```sh
+$ bin/bridgetown apply https://github.com/bridgetownrb/bridgetown-prismic
 ```
 
-Or if there's a `bridgetown.automation.rb` automation script, you can run that instead for guided setup:
+This will add a `prismic_repository` setting to your `bridgetown.config.yml` file. Replace that with the subdomain of your Prismic repo.
+
+It will also set up a `models` folder where you will add the Bridgetown models corresponding to your Prismic custom types. More details on that below.
+
+### Draft Previews
+
+To set up previews using your Bridgetown Roda backend, modify your `server/roda_app.rb` file by adding:
+
+```ruby
+require "bridgetown-prismic/roda/previews"
+```
+
+to the top of the file, and then adding:
+
+```ruby
+include BridgetownPrismic::Roda::Previews
+```
+
+right underneath `class RodaApp < Bridgetown::Rack::Roda`.
+
+Also ensure you have the Bridgetown SSR plugin installed (aka `plugin :bridgetown_ssr` is somewhere above your `route do |r|` block).
+
+Your file should end up looking something like this:
+
+```ruby
+require "bridgetown-prismic/roda/previews"
+
+class RodaApp < Bridgetown::Rack::Roda
+  include BridgetownPrismic::Roda::Previews
+
+  plugin :bridgetown_ssr
+
+  route do |r|
+    Bridgetown::Rack::Routes.start! self
+  end
+end
+```
+
+Next, create a `server/routes/preview.rb` route file:
+
+```ruby
+class Routes::Preview < Bridgetown::Rack::Routes
+  route do |r|
+    r.on "preview" do
+      # Route hit by the Prismic preview flow
+      # route: /preview
+      r.is do
+        unless prismic_preview_token
+          response.status = 403
+          next prismic_token_error_msg
+        end
+
+        r.redirect prismic_preview_redirect_url
+      end
+
+      # Rendering pathway to preview a page
+      # route: /preview/:custom_type/:id
+      r.is String, String do |custom_type, id|
+        unless prismic_preview_token
+          response.status = 403
+          next prismic_token_error_msg
+        end
+
+        save_prismic_preview_token
+
+        Bridgetown::Model::Base
+          .find("prismic://#{custom_type}/#{id}")
+          .render_as_resource
+          .output
+      end
+    end
+  end
+end
+```
+
+This file handles two routes: `/preview` and `/preview/:custom_type/:id`. Upon clicking the preview icon in the Prismic editing interface, Prismic will hit your `/preview` route first with an access token. That saves a cookie, which is then used after the redirect to the `/preview/:custom_type/:id` route (which in practice will look something like `/page/YYsenhEAACIADwbi`). As long as you've set up your models correctly, Bridgetown will automatically know how to render the resource for the preview.
+
+## Setting Up Your Content Models
+
+This is where all the magic happens. ✨
+
+By creating a content model class for each custom type in Prismic, you establish a 1:1 mapping between a piece of content in Prismic and a piece of content your site will use to build resources. The automation script installed an example of a **Post** content model. Let's take a closer look.
+
+At the top of the file are a series of configuration options:
+
+```ruby
+class << self
+  def collection_name = :posts
+  def prismic_custom_type = :blog_post
+  def prismic_slug(doc) = doc.slug
+  def prismic_url(doc)
+    doc_date = doc["blog_post.optional_publish_datetime"]&.value&.localtime || doc.first_publication_date
+    ymd = "#{doc_date.strftime("%Y")}/#{doc_date.strftime("%m")}/#{doc_date.strftime("%d")}"
+    "/#{ymd}/#{prismic_slug(doc)}/"
+  end
+end
+```
+
+* `collection_name`: this can be a built-in collection such as `posts` or `pages`, or it can be a custom collection you've configured in `bridgetown.config.yml`.
+* `prismic_custom_type`: this will be the "API ID" of the custom type in Prismic.
+* `prismic_slug`: this should return the "slug" (aka `my-document-title`) of a Prismic document. In this example the slug Prismic chose is being used verbatim, but you can make alterations as you see fit.
+* `prismic_url`: this should return the full URL of the final destination for the content. It should match the permalink settings of your collection. This is used by the "link resolver"—aka anywhere in a Prismic document where you've added a link to another Prismic document, the URL for that link to resolved using this return value for the custom type.
+
+All right, with those options out of the way, on to the main event:
+
+```ruby
+def self.process_prismic_document(doc)
+  provide_data do
+    # Variable        # Prismic Field                 # Formatting
+    id                doc.id
+    slug from: ->     { prismic_slug(doc) }
+    type              doc.type
+    created_at        doc.first_publication_date
+    date              doc["blog_post.optional_publish_datetime"]&.value&.localtime || created_at
+
+    title             doc["blog_post.title"]          .as_text
+    subtitle          doc["blog_post.subtitle"]       &.as_text
+    author            doc["blog_post.author_name"]    &.as_text
+    featured_image    doc["blog_post.featured_image"] &.url
+
+    content           doc["blog_post.post_body"]      &.as_html with_links
+  end
+end
+```
+
+This where you create the 1:1 mappings between the Prismic fields and the "front matter" (aka data) + content of your model/resource. Any time you access the resource in templates by writing `resource.data.title` or `resource.content`, it will be pulling those values from these mappings.
+
+Within the `provide_data` block, you use a special Ruby DSL in a spreadsheet-like manner to set up the mappings. On the left-hand "column", you specify the name of the front matter variable (or content). In the middle column, you use Prismic's Ruby API to get a field value or metadata. On the right-hand column, you "coerce" the value into the type of data you'r looking for. Note that any field which the author hasn't filled in has a `nil` value, so you can see this is using Ruby's safe navigation operator `&` (whimsically known as the "lonely operator") most of the time so nil values won't crash the import process.
+
+You can [read more about Prismic's Ruby Document API here](https://prismic.io/docs/technologies/the-document-object-ruby) for information on when to use `value` or `as_text` or `url`, etc.
+
+A few notes on the Ruby DSL:
+
+* Any time you see `from: -> { ... }`, that's a lambda which is evaluated directly in the model object scope. Essentially it's a way to "escape" the DSL.
+* You can nest values using a block, for example:
+  ```ruby
+  attachment do
+    name            doc["bulletin.name"]            .value.downcase
+    pdf_url         doc["bulletin.pdf_file"]        .url
+  end
+  ```
+  which would let you access the data like so:
+  ```ruby
+  resource.data.attachment.name
+  resource.data.attachment.pdf_url
+  ```
+* You can call `provide_data` from within a `from:` lambda, which is very useful when looping through Prismic slices and generating nested content. For example:
+  ```ruby
+  tiles from: -> {
+    doc["homepage.body"].slices.map do |slice|
+      case slice.slice_type
+      when "homepage_tile"
+        slice.repeat.group_documents.map do |tile|
+          provide_data do
+            backdrop      tile["backdrop"]   &.url
+            heading       tile["heading"]    &.as_text
+            description   tile["description"]&.as_html with_links
+          end
+        end
+      end
+    end.flatten.compact
+  }
+  ```
+  This would result in a `resource.data.tiles` array with one or more hashes including `backdrop`, `heading`, and `description` keys.
+
+The Ruby DSL is pretty nifty, but you may occasionally run into a conflict between your variable name and an existing Ruby method. For example, you couldn't add something like `method  doc["page.method"]  .as_text` because `method` is an existing Ruby object method. Instead, use `set` like so:
 
 ```ruby
-$ bundle exec bridgetown apply https://github.com/username/my-awesome-plugin
+set :method, doc["page.method"].as_text
+```
+
+Finally, if you decide to need to bail and want to provide a standard hash instead of using the Ruby DSL, you can do that too!
+
+```ruby
+def self.process_prismic_document(doc)
+  provide_data({
+    # Variable        # Prismic Field                 # Formatting
+    id:               doc.id,
+    slug:             prismic_slug(doc),
+    type:             doc.type,
+    created_at:       doc.first_publication_date,
+
+    title:            doc["test_page.title"]          .as_text,
+
+    content:          doc["test_page.body"]           &.as_html(with_links),
+  })
+end
+```
+
+Just remember to put all your colons, commas, and parentheses in the right places! 😅
+
+### Trying Out Your Models
+
+The Bridgetown console is a good place to inspect your content. Just run `bin/bridgetown console` or `c` and then you can poke through your collections and see what's what.
+
+```
+irb> resource = site.collections.pages.resources.find { |page| page.data.slug == "my-page" }
+
+irb> resource.data
+
+irb> resource.content
+
+irb> resource.model.prismic_doc # access the original Prismic Document object
 ```
 
-## Usage
+## Indicating Previews in Your Site's Layout
 
-The plugin will…
+When previewing content, it's helpful to know at a glance that you're looking at a preview, not a piece of published content. You can add a conditional block to the top of your layout's `<body>` which will detect the presense of a preview token and display a preview notice at the top of the page.
 
-### Optional configuration options
+Example for a Liquid layout:
 
-The plugin will automatically use any of the following metadata variables if they are present in your site's `_data/site_metadata.yml` file.
+```liquid
+{% if site.prismic_preview_token %}
+  <p class="text-center" style="padding:7px; background:rgb(255, 230, 0); border-bottom:2px solid #333; margin:0; font-family:sans-serif; font-weight:bold; font-size:110%">
+    PREVIEW
+  </p>
+{% endif %}
+```
+
+or an ERB layout:
+
+```erb
+<% if site.data.prismic_preview_token %>
+  <p class="text-center" style="padding:7px; background:rgb(255, 230, 0); border-bottom:2px solid #333; margin:0; font-family:sans-serif; font-weight:bold; font-size:110%">
+    PREVIEW
+  </p>
+<% end %>
+```
+
+## Deploying on Render
+
+You can easily deploy your preview site on [Render](https://render.com) and use it for previewing draft content. For modest website deployments, your preview site could also serve as your public site (with the public only seeing the "static" published content), but generally we recommend a second static site deployment for the public to access (which Render also supports—you can run `bin/bridgetown configure render` to set up a static site config).
+
+The starter plan (US $7/month as of the time of this writing) is recommended. Simply add (or edit) a `render.yaml` file in the root of your site repo:
+
+```yaml
+services:
+  - type: web
+    name: your-site-name-here
+    env: ruby
+    repo: https://github.com/username/your-site-name-here
+    buildCommand: bundle install && yarn install && bin/bridgetown frontend:build
+    startCommand: bin/bridgetown start
+    envVars:
+      - key: BRIDGETOWN_ENV
+        value: production
+```
+
+Once your repo is checked into GitHub, you can access it in Render and it will be configured and deployed "automagically." 😁
+
+After that, in your Prismic CMS settings under "Previews", you can create a new preview with the following settings:
 
-…
+* Site Name: Preview
+* Domain: https://your-site-name-here.onrender.com
+* Link Resolver: /preview
 
-## Testing
+In addition, you'll want to set up a webhook so any published content will trigger a rebuild of your preview and public sites.
+
+Go to the "Webhooks" settings page and add a new webook:
+
+* Name of the webhook: Preview Site (or Public Site)
+* URL: (you will need to obtain this from your [Render site's deploy hook config (see documentation)](https://render.com/docs/deploy-hooks)
+* Secret: (leave this blank)
+
+## Questions? Feedback?
+
+Please submit an issue to this GitHub repo and we'll address your concerns as soon as possible. In addition, [you can get in touch with the Bridgetown core team and community members](https://www.bridgetownrb.com/docs/community) through the usual channels.
+
+## Testing This Gem
 
 * Run `bundle exec rake test` to run the test suite
 * Or run `script/cibuild` to validate with Rubocop and Minitest together.
 
 ## Contributing
 
-1. Fork it (https://github.com/username/my-awesome-plugin/fork)
+1. Fork it (https://github.com/bridgetownrb/bridgetown-prismic/fork)
 2. Clone the fork using `git clone` to your local development machine.
 3. Create your feature branch (`git checkout -b my-new-feature`)
 4. Commit your changes (`git commit -am 'Add some feature'`)
 5. Push to the branch (`git push origin my-new-feature`)
 6. Create a new Pull Request
-
-----
-
-## Releasing (you can delete this section in your own plugin repo)
-
-To release a new version of the plugin, simply bump up the version number in both `version.rb` and
-`package.json`, and then run `script/release`. This will require you to have a registered account
-with both the [RubyGems.org](https://rubygems.org) and [NPM](https://www.npmjs.com) registries.
-You can optionally remove the `package.json` and `frontend` folder if you don't need to package frontend
-assets for Webpack.
-
-If you run into any problems or need further guidance, please check out our [Bridgetown community resources](https://www.bridgetownrb.com/docs/community)
-where friendly folks are standing by to help you build and release your plugin or theme.
-
-**NOTE:** make sure you add the `bridgetown-plugin` [topic](https://github.com/topics/bridgetown-plugin) to your
-plugin's GitHub repo so the plugin or theme will show up on [Bridgetown's official Plugin Directory](https://www.bridgetownrb.com/plugins)! (There may be a day or so delay before you see it appear.)

data/bridgetown.automation.rb

@@ -1,8 +1,11 @@
+say_status :prismic, "Installing the bridgetown-prismic plugin..."
+
 add_bridgetown_plugin("bridgetown-prismic")
 
 append_to_file "bridgetown.config.yml" do
   <<~YAML
 
+
     # Prismic config:
     prismic_repository: repo_name_here
     autoload_paths:
@@ -11,4 +14,8 @@ append_to_file "bridgetown.config.yml" do
   YAML
 end
 
-create_file "models/post.rb", File.read(File.join(__dir__, "test", "fixtures", "models", "post.rb")
+get "https://raw.githubusercontent.com/bridgetownrb/bridgetown-prismic/main/test/fixtures/models/post.rb",
+    "models/post.rb"
+
+say_status :prismic, "All set! Double-check your Prismic settings and model files and review docs at"
+say_status :prismic, "https://github.com/bridgetownrb/bridgetown-prismic"

data/lib/bridgetown-prismic/api.rb

@@ -20,10 +20,27 @@ module BridgetownPrismic
     def query_prismic(custom_type, options = {})
       Bridgetown.logger.info "Prismic API:", "Loading #{custom_type.to_s.green}..."
 
-      BridgetownPrismic
-        .api
-        .query(Prismic::Predicates.at("document.type", custom_type.to_s), options)
-        .results
+      results = []
+      page = 1
+      finalpage = false
+      options["pageSize"] ||= 100 # pull in as much data as possible for a single request
+
+      until finalpage
+        options["page"] = page
+
+        response = BridgetownPrismic
+          .api
+          .query(Prismic::Predicates.at("document.type", custom_type.to_s), options)
+
+        results += response.results
+        if response.total_pages > page
+          page += 1
+        else
+          finalpage = true
+        end
+      end
+
+      results
     end
 
     def query_prismic_and_generate_resources_for(klass)

data/lib/bridgetown-prismic/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module BridgetownPrismic
-  VERSION = "0.1.2"
+  VERSION = "0.2.0"
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: bridgetown-prismic
 version: !ruby/object:Gem::Version
-  version: 0.1.2
+  version: 0.2.0
 platform: ruby
 authors:
 - Bridgetown Team
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2021-11-10 00:00:00.000000000 Z
+date: 2021-11-22 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: bridgetown