@walltowall/gatsby-theme-ww-slice-studio
v0.1.18
Published
Gatsby theme providing an interactive playground for Prismic slices.
Downloads
10
Readme
@walltowall/gatsby-theme-slice-studio
Gatsby theme that provides interactive client documentation for Wall-to-Wall Gatsby websites.
Install
yarn add @walltowall/gatsby-theme-ww-slice-studio
How to use
Configure Gatsby
Setup the consuming project's gatsby-config
as shown below:
// In your gatsby-config.js
plugins: [
{
resolve: '@walltowall/gatsby-theme-ww-slice-studio',
options: {
// Path to the project's root directory. This is required and should be set to __dirname.
root: __dirname,
// Name of the client for the site. Will appear throughout documentation.
siteTitle: 'Site Title',
// Provide an object of Prismic custom type JSON schemas to load into Gatsby.
schemas,
// Provide a list of layouts to show in the client documentation. Each named layout should have a corresponding
// .js file in `/studio/layouts`.
layouts: [
'about',
'design',
'home',
'project',
'services',
'recognition',
'team',
],
// Provide an object of Prismic custom types and slice zones. These keys should have corresponding entries
// from the provided `schemas` object.
sliceZones: {
page: {
description:
'Each page document in Prismic represents a unique and visitable page on your website.',
zones: {
body:
"Body slices comprise the majority of the content on it's respective page.",
},
},
},
},
},
]
Configure Netlify & Authentication
Once your gatsby-config
has been set-up, you'll need to configure a
netlify.toml
in your project root to serve the appropriate lambda functions
for authentication. Below is the absolute minimum you'll need to configure
lambda functionality.
[build]
functions = "node_modules/@walltowall/gatsby-theme-ww-slice-studio/src/lambda"
After setting up your .toml
file, ensure to add the appropriate environment
variables to your Netlify site's dashboard. See .env
for the values to enter.
Writing documentation
Layouts
As shown in the example gatsby-config
, every defined layout will need to have
a corresponding .js
file in your project's /studio/layouts
that follow the
following structure:
export const LAYOUT_NAME = {
// The display name for this layout.
name: 'Name',
// The custom type in Prismic this layout is available under.
customType: 'page',
// A short description for this layout.
description: 'Sample description',
// The list of slices to pre-populate the Prototyper when this layout is selected.
// Must be a list of tuples containing the full slice name and the example index to render.
example: [
['PageBodyHorizontalNavigation', 0],
['PageBodyFeaturedProjects', 0],
['PageBodyMixedSizedProjects', 0],
],
// A list of zones to render in the layout documentation.
// A zone can render any arbitrary JSX and label itself with a name and
// reasoning.
zones: [
{
// If you would like to render JSX without displaying any additional info,
// e.g. rendering a <Header /> or <Footer />, just omit the `name`, property.
render: () => <PageBodyHeader nextSharesBg={[true]} />,
},
{
// Heading for the zone.
name: 'Navigation',
// If a zone is from a "preset", designate it as one with the `preset` property.
// This will prevent this zone from being modified in the Prototyper tool.
preset: 'Horizontal Navigation',
// Client friendly reasoning as to why these slices were selected.
reasoning:
'Provides quick access to different project types for visitors.',
// The actual JSX to render for this zone.
render: () => (
<PageBodyHorizontalNavigation
title="design"
rootHref="/"
nextSharesBg={[true]}
>
<PageBodyHorizontalNavigation.Item href="/">
Hospitality + Leisure
</PageBodyHorizontalNavigation.Item>
<PageBodyHorizontalNavigation.Item href="/">
Interior Design
</PageBodyHorizontalNavigation.Item>
<PageBodyHorizontalNavigation.Item href="/">
Office + Healthcare
</PageBodyHorizontalNavigation.Item>
<PageBodyHorizontalNavigation.Item href="/">
Residential
</PageBodyHorizontalNavigation.Item>
<PageBodyHorizontalNavigation.Item href="/">
Retail + Restaurants
</PageBodyHorizontalNavigation.Item>
</PageBodyHorizontalNavigation>
),
},
{
name: 'Project Grid',
// If a zone is not a preset, include the exact list of slices used in the example.
slices: ['PageBodyFeaturedProjects', 'PageBodyBrandedCallout'],
// In addition to the exact list, also provide a list of recommended slices for this zone.
// In some designs, this may differ from `slices` since an example may not include every slice
// that would be appropriate.
recommendedSlices: [
'PageBodyFeaturedProjects',
'PageBodyMixedSizedProjects',
'PageBodySmallProjects',
'PageBodyBrandedCallout',
],
reasoning:
'Varied usage of the recommended slices helps give the layout a dynamic flow. The callout helps to provide a break in the list of projects.',
render: () => (
<>
<PageBodyFeaturedProjects nextSharesBg={[true]}>
<PageBodyFeaturedProjects.Project
variant="large"
imageURL="https://pvadev.cdn.prismic.io/pvadev/541704ba04a3f58caa4a37dd325d793d351dbd1d_0-flower-avenue.jpg"
imageAlt="Example."
location="Honolulu, Hawaii"
categoryUID="residential"
name="Flower Avenue"
href={true}
/>
</PageBodyFeaturedProjects>
<PageBodyBrandedCallout
variant="dark"
textHTML="<h1>Our team of architects and interior designers is both collaborative and visionary.</h1>"
buttonHref={true}
buttonText="Our approach"
nextSharesBg={[true]}
/>
<PageBodyFooter />
</>
),
},
],
}
Once you have written all of your required layouts, create
/studio/layouts/index.js
in your project and export all of your layouts as
named exports:
export { project } from './project'
export { otherLayout } from './otherLayout'
Slices
To write documentation for individual slices, create a docs
object property on
the slice component directly.
See below for an example:
export const PageBodyText = props => {
// ... implementation details
}
// At the end of the file, add the `docs` object to the component.
PageBodyText.docs = {
// The display name of the slice.
name: 'Text',
// List of examples of this slice. If a slice has variations of itself, each variant should be included.
examples: [
{
// Name of the example. This will show in the prototyper tool.
name: 'With Heading',
// Corresponding JSX for this example.
render: () => <PageBodyText />,
},
],
}
General Documentation
To write additional general documentation, you can create additional markdown
files in the /src/docs
directory of this theme.
Each markdown file should have generally follow the following frontmatter:
---
parent: General
title: Images
path: general/images
summary: >-
Short summary of article
---
List of Required Files
Due to the nature of aliased imports with webpack, below is a comprehensive list of required files that your project needs for this theme to function correctly:
src/index.css
: Your fonts and base styles to inject into each Studio Frame.src/slices/index.js
: ExportslicesMap
asPageBody
fromsrc/slices/PageBody
: so our theme has alias access to it./netlify.toml
: Must be configured to point to the theme's lambda folder. Ex:node_modules/@walltowall/gatsby-theme-ww-slice-studio/src/lambda
studio/layouts
: Must contain your layouts and the appropriateindex.js