Page Gallery for SilverStripe
This module makes creating pages in the CMS better. In like, every single way., (*1)
Installation
composer require unclecheese/silverstripe-page-gallery
, (*2)
cd silverstripe-page-gallery && npm install
, (*3)
OK, what does it do?
When adding a page in the CMS, the user is typically forced to parse a long list of ambiguous, developer-defined PHP class names in order to choose the page type that he or she wants. While the API offers configurations like $singular_name
and $description
, it can still be difficult to signal to a content editor exactly what a given page is used for., (*4)
I mean, really, ConferenceEventPricingCategoryHolder
? Don't do me like that, bro., (*5)
Stop the madness. Let's just use auto-generated screenshots., (*6)
Let's look
, (*7)
In addition to providing actual screenshots of each page type, the UI filters out page types that cannot be created in the section. Without this module, all of those page types are interpolated into the list, creating unnecessary visual noise and head-spinniness., (*8)
The magic
Just run the task:, (*9)
framework/sake dev/tasks/PageGalleryTask
, (*10)
A simple PhantomJS based library will take it from there., (*11)
Excluding pages
So you don't want that PlainTextPasswordPage
getting a screenshot? Just add it to the exclude
list., (*12)
UncleCheese\PageGallery\PageGalleryBuilder:
exclude:
- SomePage
Specifying the instances of pages you want to get screenshots
By default, the screenshot task will get the last edited instance of a SiteTree
object with ClassName
equal to the page type. For more granular control, use instance_map
., (*13)
UncleCheese\PageGallery\PageGalleryBuilder:
instance_map:
Page: 'about-us'
EventPage: 123
You can identify an instance by link or by ID., (*14)
Full configuration
Configure the task:, (*15)
UncleCheese\PageGallery\PageGalleryBuilder:
# width of the browser taking the screenshot
screen_width: 1200
# height of the browser taking the screenshot
screen_height: 800
# don't create screenshots for these pages.
exclude:
- VirtualPage
- RedirectorPage
# If you have a preference on what page gets the screenshot, map it to a link or ID
instance_map:
Page: 'about-us'
EventPage: 123
# Where the screenshots are saved. Recommend this is in source control
project_screenshot_dir: 'mysite/images/screenshots'
There are also a few settings you can throw at the CMS UI., (*16)
PageGalleryUI:
# width of the screenshot in the gallery
image_width: 300
# height of the screenshot in the gallery
image_height: 200
# When no screenshot exists, use this default image
default_image: 'silverstripe-page-gallery/images/default.png'
Requirements
- SilverStripe > 3.1
- npm
- The
node
binary must be in your PATH. (Hint: type node -v
to get the verdict on that. If you get bad news, it's exceedingly simple to rectify)
- The
unclecheese/silverstripe-image-optionset
module. It's new in town.
Open questions
Cause... talking to myself., (*17)
Where should these screenshots go?
I think it makes sense to put them in a source-controlled part of your project, e.g. mysite/images/screenshots
, but this raises a few questions, particularly around the write permissions on your mysite/
directory, and the consequences of writing to a source-controlled directory in a non-development environment. assets/
might make sense in that case, but that has the reverse problem of making it difficult for a developer to generate them locally and move them into staging and production assets/
directories, because they're typically controlled by the users., (*18)
The screenshot thingy should really be a pluggable service.
Indeed. It would make sense if a dev environment could inject a Node based screenshot grabber, and a staging environment could use a web service like url2png, or what have you. The only issue with using a web service is that staging sites are often behind HTTP Auth., (*19)
If a page doesn't exist in the tree, it kind of gets the shaft.
Potentially we could create a temporary one just for the screenshot, fill it with dummy content, then delete it?, (*20)
Tests
They exist., (*21)
Troubleshooting
Ring Uncle Cheese., (*22)