eddev 0.2.26 → 0.2.29

package/docs_old/docs/graphql/2.query-hooks.md

@@ -1,238 +0,0 @@
-# Query Hooks
-
-Sometimes you might need to perform queries at runtime, rather than as part of views or blocks. This is particularly useful for things like searching and filtering.
-
-To do so, you can create `.graphql` files inside the `queries/` folder.
-
-React Hooks are automatically generated, based on the name of the query.
-
-### Naming Conventions
-
-For conventions sake, all `queries/*.graphql` files (except for `queries/fragments/*.graphql`) should be start with `use` (eg. `queries/UseLatestPosts.graphql`). Our dev tooling will actually complain if this isn't the case!
-
-Similarly, the name of your query file and query operation name should also match! Again, you'll get a nice error message if they don't asking you to rename either the operation name, or the file name.
-
-For example:
-
-```graphql title="queries/UseLatestPosts.graphql"
-query UseLatestPosts {
-  posts(first: 10) {
-    nodes {
-      id
-      title(format: RENDERED)
-    }
-  }
-}
-```
-
-### Using your hook
-
-Generated hooks are stored in `hooks/queries.ts`, and can be imported from there using the name of the query file.
-
-```tsx
-import { useLatestPosts } from "@hooks/queries"
-import { PostTile } from "@components/PostTile"
-
-export function LatestPosts() {
-  const results = useLatestPosts()
-
-  if (results.loading) {
-    return <p>Loading...</p>
-  }
-
-  if (results.errors) {
-    return <p>Error!</p>
-  }
-
-  return (
-    <div>
-      {results.data?.posts?.nodes?.map((post) => (
-        <PostTile key={post.id} post={post} />
-      ))}
-    </div>
-  )
-}
-```
-
-Easy as!
-
-### Types of hooks
-
-There are **three** types of hooks which are automatically generated.
-
-#### Regular hooks
-
-The `useLatestPosts` example above is a regular hook. The hook will return an object with the following properties:
-
-- `loading` (boolean) — whether the query is currently loading
-- `errors` (array of error objects) — an array of errors, or `undefined` if there are none. The errors may either be HTTP errors, or GraphQL errors.
-- `data` (object) — the data returned by the query, which should be statically typed already based on your GraphQL schema and query.
-- `refresh` (function) — a function you can call to re-run the query.
-
-#### Infinite hooks
-
-Infinite hooks are a special kind of hook which we've invented, which support infinite loading patterns, such as infinite scrolling and 'load more' buttons.
-
-Any query which has `Infinite` in the name (eg. `UseInfinitePosts`) will be automatically generated as an infinite hook. These hooks have a `loadMore` function, and make use of the `nodes` and `pageInfo` fields provided by WPGraphQL, and use 'cursor based' pagination.
-
-There are a few special requirements for infinite hooks, but we've configured the `dev` tooling to warn you if you're not following these conventions (on top of the usual naming convention requirements)
-
-- The query name must contain the word 'Infinite' (eg. `UseInfinitePosts`)
-- There must be a `$limit: Int` variable defined on the query, with a default value. This is the number of items to load per page.
-- There must be a `$cursor: String` variable defined on the query, with no default value. This is used for controlling pagination.
-- The `$cursor` variable must be used in the `after` field of the query.
-- The `$limit` variable must be used in the `first` field of the query.
-- Your query must select `nodes`
-- Your query must select the `endCursor` and `hasNextPage` fields from the `pageInfo` object
-
-Here's an example query which fits all of those requirements (it's pretty simple!):
-
-```graphql title="queries/UseInfinitePosts.graphql"
-query UseInfinitePosts($limit: Int = 2, $cursor: String) {
-  posts(first: $limit, after: $cursor) {
-    nodes {
-      title(format: RENDERED)
-    }
-    pageInfo {
-      endCursor
-      hasNextPage
-    }
-  }
-}
-```
-
-The return value of the hook will be an object with the following properties:
-
-- `loading` (boolean) — whether the hook is performing it's _first_ load
-- `loadingMore` (boolean) — whether the hook is loading additional entries, in response to `loadMore()`
-- `errors` (array of error objects) — an array of errors, or `undefined` if there are none. The errors may either be HTTP errors, or GraphQL errors.
-- `items` (array of objects) — an array of items, which are the result of the query, automatically extracted from the `nodes` field present in the query
-- `hasMore` (boolean) — whether or not there are more items which can be loaded
-- `loadMore` (function) — function which can be called to load more items.
-- `refresh` (function) — clears out all items, and re-runs the query.
-
-In essense, you can use `.items` to grab the current items, and `.loadMore()` to load more items when a button is clicked, or an `IntersectionObserver` intersects.
-
-Heres' an example component which uses the query above:
-
-```tsx title="components/LatestPosts.tsx"
-import { useInfinitePosts } from "@hooks/queries"
-
-function InfiniteExample() {
-  const posts = useInfinitePosts()
-
-  if (posts.loading) {
-    // The initial load is in progress, show some loading indicator
-    return <div>Loading...</div>
-  }
-
-  return (
-    <div>
-      {/* The list of items, which will grow as more items are loaded */}
-      <ul>
-        {posts.items?.map((item, key) => {
-          return <li key={key}>{item.title}</li>
-        })}
-      </ul>
-      {/* A 'Load more' button, which is disabled and shows 'Loading...' when more items are loading */}
-      {posts.hasMore && (
-        <button disabled={posts.loadingMore} onClick={() => posts.loadMore()}>
-          {posts.loadingMore ? "Loading..." : "Load more"}
-        </button>
-      )}
-    </div>
-  )
-}
-```
-
-It looks something like this:
-
-![Mutation Example](./img/infinite-example.gif)
-
-#### Mutation hooks
-
-Mutation hooks are hooks generated when your operation uses `mutation` in instead of `query`. Mutations are used in GraphQL when the query has some kind of side effect, such as creating a new comment, or submitting a form. Unlike `query` operations, mutations are never cached on the server.
-
-Mutation hooks return an object with the following properties:
-
-- `submitting` (boolean) — whether the mutation is currently running
-- `submitted` (boolean) — whether or not the last mutation which was submitted completed successfully
-- `errors` (array of error objects) — an array of errors, or `undefined` if there are none. The errors may either be HTTP errors, or GraphQL errors.
-- `data` (object) — the result of the last submitted mutation, if it was successful.
-- `submit(args)` (function) — the function which you must trigger to actually run the mutation. Pass in required parameters as an object.
-
-An example mutation operation looks like this:
-
-```graphql title="queries/UseCreateComment.graphql"
-mutation UseSubmitComment($input: CreateCommentInput!) {
-  createComment(input: $input) {
-    success
-  }
-}
-```
-
-Unlike query hooks, the query won't run automatically when using the hook — rather, it needs to be triggered manually using an event or an effect using the `submit` method, provided by the hook.
-
-```tsx title="components/CreateComment.tsx"
-import { useSubmitComment } from "@hooks/queries"
-import { useState } from "react"
-
-type Props = {
-  postID: number
-}
-
-export function CreateComment(props: Props) {
-  const [message, setMessage] = useState("")
-  const [authorName, setAuthorName] = useState("")
-  const comment = useSubmitComment()
-
-  return (
-    <form
-      onSubmit={(e) => {
-        e.preventDefault()
-        comment.submit({
-          input: {
-            commentOn: props.postID,
-            content: message,
-            approved: null,
-            author: authorName,
-            authorEmail: null,
-            authorUrl: null,
-            clientMutationId: null,
-            date: null,
-            parent: null,
-            type: null,
-          },
-        })
-      }}
-    >
-      {comment.errors && <div>ERROR: {comment.errors[0].message}</div>}
-      {comment.submitted && <div>Thanks for your comment!</div>}
-      <input
-        placeholder="Enter your name"
-        type="text"
-        value={authorName}
-        onChange={(e) => setAuthorName(e.currentTarget.value)}
-      />
-      <textarea placeholder="Enter your comment" value={message} onChange={(e) => setMessage(e.currentTarget.value)} />
-      <button disabled={comment.submitting} type="submit">
-        Submit comment
-      </button>
-    </form>
-  )
-}
-```
-
-It looks something like this:
-
-![Mutation Example](./img/mutation-example.gif)
-
-## Does this use the GraphQL endpoint?
-
-Nope it doesn't! It uses the WP-JSON REST endpoint, and the query file is loaded from the theme folder and executed by the server.
-
-For example, if you've got a GraphQL file called `queries/UseLatestPosts.graphql` in your theme folder, you'll can actually see it in action by accessing `http://my-site.local/wp-json/ed/v1/query/usePosts?params={%22limit%22:1}`, noting that variables are JSON encoded into the URL — this can be great for debugging GraphQL schema extensions. Use Chrome's Network tab to see the request and responses in action.
-
-The reason for this is so that the query results can be cached by Flywheel or CloudFlare, and also keeps our `/graphql` hidden from hackers who might want to DDoS the site, or otherwise attempt to scrape data directly from us. The result is that only the data we chose to make public is publicly accessible.
-
-Mutations also follow this pattern, however they use POST requests, so that data will never accidentally be cached.

package/docs_old/docs/graphql/3.extending-wpgraphql.md

@@ -1,3 +0,0 @@
-# Extending the GraphQL Schema
-
-This needs writing, sorry!

package/docs_old/docs/graphql/_category_.json

@@ -1,4 +0,0 @@
-{
-  "label": "❄️ GraphQL",
-  "position": 5
-}

package/docs_old/docs/gutenberg/1.overview.md

@@ -1,25 +0,0 @@
-# Blocks Overview
-
-Blocks are primarily defined in a `.tsx` file inside the `blocks/` folder. Blocks should be organised within subfolders, depending on their purpose and context.
-
-For example:
-
-- `blocks/layout/section.tsx`
-- `blocks/projects/single-project-tile.tsx`
-- `blocks/content/button-row.tsx`
-
-## ACF Fields
-
-ACF fields can be attached to any block type. Use ACF fields for complex data.
-
-ACF fields are passed **directly** to blocks — rather the ACF fields must be selected using GraphQL files. This may seem like a bunch of work, but it actually gives us the opportunity to pull the exact data we need — for example, we can pull metadata for posts directly from 'Post Object' fields. It also allows us to have great TypeScript support for all ACF fields attached to a block, automatically.
-
-[Read more →](./block-acf)
-
-## GraphQL
-
-Each block can have a single `.graphql` file sitting alongside the `.tsx` file (eg. `/blocks/sections/newsletter.tsx` and `/blocks/sections/newsletter.graphql`)
-
-The GraphQL file can query any data from the CMS, as well as any ACF fields attached to the block.
-
-[Read more →](./block-graphql)

package/docs_old/docs/gutenberg/2.block-definition.md

@@ -1,37 +0,0 @@
-# Defining a Block
-
-Create a new block file, for example `blocks/layout/section.tsx`
-
-Copy and paste the code below, making sure to:
-
-- Replace the `TITLE` and `DESCRIPTION`
-- Replace `NAME` with the filename of your block (eg. `layouts/section`)
-- Run `yarn generate`, so that TypeScript knows what prop types to expect for your new block, and will also validate the name.
-
-```tsx title="/blocks/layouts/section.tsx"
-/**
- * Title: TITLE
- * Description: DESCRIPTION
- * Category: common
- * Icon: book-alt
- * Keywords: post
- * Types: page, post
- * Mode: preview
- * Supports multiple: true
- * Tags: root
- * Child tags: none
- */
-import { defineBlock } from "eddev/blocks"
-
-export default defineBlock("NAME", (props) => {
-  return <div>Hello!</div>
-})
-```
-
-:::tip
-Make sure `yarn dev` is running! It'll auto-generate TypeScript types for block when you create it, and it'll continue to update those types if you're using a GraphQL for your block (which you probably are).
-:::
-
-:::warning
-If you get a red squiggly next to the block name in the `defineBlock`, it means you're either not running `yarn dev`, or you may be using the wrong name for the current file.
-:::

package/docs_old/docs/gutenberg/3.block-acf.md

@@ -1,13 +0,0 @@
-# Block ACF Fields
-
-Once you've created a `.tsx` file for your block, it'll automatically be registered with WordPress, and is available to be targetted by ACF field groups.
-
-- Create a new ACF Field Group
-- Make sure the block title starts with `Block: ` — this is just convention
-- Add any fields you like.
-
-![Adding an ACF Field Group for a Block](./img/create-acf-fields-for-block.png)
-
-:::tip
-We may add the ability to have [ACF Builder](https://github.com/StoutLogic/acf-builder) support for blocks at some point, however for now it's recommended that you use the ACF Interface to build fields for your blocks. ACF Builder is an advanced tool which requires that you have a deeper knowledge of ACF and all of it's configuration options, and may be harder to use for ACF newbies.
-:::

package/docs_old/docs/gutenberg/4.block-graphql.md

@@ -1,63 +0,0 @@
-# Block GraphQL Files
-
-## Naming
-
-A block named `/blocks/sections/newsletter.tsx` can have a single GraphQL query file named `/blocks/sections/newsletter.graphql`.
-
-Due to a limitation with GraphQL Codegen, each `.graphql` file must contain one uniquely-named.
-
-ACF fields attached to the block can be queried using the naming convention `folderName_blockName`, where the folder name and block name are automatically converted from `dash-case` to `camelCase`.
-
-## Execution
-
-Block queries are executed automatically by PHP code, so there is no need to call any functions to get the data, or handle any loading/error state. The result of the query is sent straight into the `props` of your block.
-
-## Querying ACF Fields
-
-GraphQL schemas for your blocks ACF Fields are automatically generated by PHP.
-
-Consider this block type:
-
-```tsx title="blocks/project/single-project-tile.tsx"
-/**
- * Title: Single Project Tile
- * Description: Displays a single project as a large tile.
- * Category: common
- * Icon: book-alt
- * Keywords: post
- * Types: page, post
- * Mode: preview
- * Supports multiple: true
- */
-import { defineBlock, EditableText, InnerBlocks } from "eddev/blocks"
-
-export default defineBlock("project/single-project-tile", (props) => {
-  return <div>...</div>
-})
-```
-
-With the following ACF field configuration:
-
-![Example block](./img/example-acf-single-project-tile.png)
-
-The ACF fields will be available under `block.project_singleProjectTile`
-
-```graphql title="blocks/project/single-project-tile.graphql"
-query SingleProjectTile {
-  block {
-    project_singleProjectTile {
-      project {
-        ... on Project {
-          id
-          title(format: RENDERED)
-          projectFields {
-            image {
-              ...BasicImage
-            }
-          }
-        }
-      }
-    }
-  }
-}
-```

package/docs_old/docs/gutenberg/5.inline-editing.md

@@ -1,33 +0,0 @@
-# Inline Editing
-
-It's trivial to add inline editing to your blocks. This is totally separate from ACF.
-
-## `<EditableText />`
-
-The most common inline editing function will of course be the ability to edit text in your block. The `<EditableText>` component does just this! Keep in mind, this can only be used on blocks, or components which are used within a block.
-
-```tsx
-<div>
-  <EditableText as="h2" id="title" placeholder="Enter a title" />
-</div>
-```
-
-When the above code runs in the WordPress editor, an author can click on that element and type into it directly.
-
-Note that you can have as many `<EditableText>` components as you want, however each `id` must be unique, since each value is stored as a key/value pair.
-
-The `as` prop is required, and can either be an element type (`p`, `h1`, `h2`, etc.) or a component.
-
-## `useInlineEditableValue`
-
-The `useInlineEditableValue` hook is the foundation of all inline editing in our system — it works a lot like `useState`, except that the content is saved to the block when saving the page, and restored again when the page is loaded.
-
-Much like `EditableText`, the hook requires a unique `id` to identify the value.
-
-You can store any kind of data, including objects and arrays.
-
-```tsx
-const [title, setTitle] = useInlineEditableValue('title');
-
-return <input type="text" value={title} onChange={e => setTitle(e.currentTarget.value)}>
-```

package/docs_old/docs/gutenberg/6.nested-blocks.md

@@ -1,80 +0,0 @@
-# Nested Blocks
-
-Nested blocks add a lot of power to Gutenberg — you can create blocks, which themselves contain more blocks.
-
-The `<InnerBlocks />` component acts as a container for child blocks.
-
-Note that you can only have ONE `InnerBlocks` per-block. This is a WordPress limitation.
-
-## Block Tagging
-
-Most of the time, we want to restrict where blocks can be used. For example, we might have a set of 'root' blocks which the user can only be added to the root of the page. Then, we might want some 'inline' blocks which can be added to some of those root blocks. We may also have specialised blocks, like a 'Button Row', which can only accept 'Button' blocks.
-
-To do this, we've invented a 'tags' system for blocks, which is defined in the comments section of a block.
-
-```tsx
-/*
- * ...
- * Tags: root
- * Child tags: inline
- */
-```
-
-Use 'Tags' to define the tags on this block, as a comma separated list if defining multiple tags. The `'root'` tag is special, in that any block tagged with it can be added to the root of the page.
-
-If the block has `InnerBlocks`, you can use `Child tags` to indirectly specify the allowed block types which can be added to this block.
-
-## Tagging core blocks
-
-You can also tag core blocks, which are blocks which are included by WordPress, using some PHP code.
-
-Note that you can tag core blocks multiple times with multiple tags.
-
-```php title="backend/blocks.php"
-<?php
-
-  ED()->tagCoreBlocks("wysiwyg", [
-    "core/paragraph",
-    "core/list",
-    "core/heading",
-  ]);
-
-?>
-```
-
-## Putting it all together
-
-For example, if you have a 'Section' block which accepts some WYSIWYG blocks like headings and paragraphs as well as a 'Button Row' block, and only want to allow 'Button' blocks to be added to the 'Button Row', you might have something like this:
-
-```tsx title="blocks/layout/section.tsx"
-/*
- * ...
- * Tags: root
- * Child tags: inline, wysiwyg
- */
-```
-
-```tsx title="blocks/buttons/button-row.tsx"
-/*
- * ...
- * Tags: inline
- * Child tags: buttons
- */
-```
-
-```tsx title="blocks/buttons/button.tsx"
-/*
- * ...
- * Tags: buttons
- */
-```
-
-```php title="backend/blocks.php"
-
-  ED()->tagCoreBlocks("wysiwyg", [
-    "core/paragraph",
-    "core/list",
-    "core/heading",
-  ]);
-
-```

package/docs_old/docs/gutenberg/7.restricting-to-post-types.md

@@ -1,38 +0,0 @@
-# Restricting to Post Types
-
-You can restrict an individual block type to only be used in certain post types.
-
-To do this, just update your block's `Types` property. You can have multiple types, separated by commas.
-
-```tsx
-/*
- * ...
- * Types: page, post
- * ...
- */
-```
-
-### Template Locking
-
-Taking this a step further, you can also specify required root blocks for a post type.
-
-For example, you might want to specify that when creating a new blog post, that only 'Blog Post Header' and 'Blog Post Content' blocks are added to root, and are automatically added when creating a new post, and also cannot be removed.
-
-This needs to be done in PHP:
-
-```php title="backend/blocks.php"
-<?php
-
-  ED()->templateLock([
-    'type' => 'post',
-    'content' => [
-      ['acf/blog-post-header'],
-      ['acf/blog-post-content'],
-    ]
-  ]);
-
-```
-
-:::warning
-Note that you need to use the internal ACF block name when working with template locks. For example, `blog/post-header` becomes `acf/blog-post-header`.
-:::

package/docs_old/docs/gutenberg/8.restricting-to-page-templates.md

@@ -1,26 +0,0 @@
-# Restricting to Page Templates
-
-You can restrict an individual block type to only be used in certain page templates
-
-To do this, just update your block's `Templates` property. You can have multiple templates, separated by commas.
-
-```tsx
-/*
- * ...
- * Types: page, post
- * Templates: templates/my-cool-template
- * ...
- */
-```
-
-:::tip
-Be sure to set `Types: page`, otherwise the block wont be available in the page template.
-:::
-
-:::warning
-Note that in above example, the block will be available on all `post`s, and all `page`s which have the template `views/templates/my-cool-template.tsx`.
-:::
-
-### Template Locking
-
-Unfortunately this isn't possible at the moment... mostly due to Gutenberg being a bit crap.

package/docs_old/docs/gutenberg/9.dynamic-blocks.md

@@ -1,21 +0,0 @@
-# Dynamic Blocks
-
-A "dynamic" block is a block that loads asynchronously, only when it's used for the first time. This is useful when a block has a large dependency (think, THREE.js or Swiper). This can drastically reduce the size of your bundle, while also improving the loading time of your site.
-
-The downside is that the block won't load until it's first use, which means that it'll be hidden for a moment while it loads. Because of this, it's recommended that you:
-
-- Perhaps don't use this feature if your block is likely to be used above-the-fold (maybe a good candidate for dynamic components or dynamic imports)
-- Do a fade in animation when the block is first mounted, so that it's not a jarring experience.
-
-It's super easy to enable this feature — just add `Dynamic: true` to your block header comment.
-
-```tsx title="/blocks/layouts/section.tsx"
-/**
- * Title: TITLE
- * Description: DESCRIPTION
- * ...etc
- * Dynamic: true
- */
-```
-
-You can read more about dynamic _components_, and other ways to reduce your bundle size here — [Bundle Size Tips →](../how-to/bundle-size)

package/docs_old/docs/gutenberg/_category_.json

@@ -1,4 +0,0 @@
-{
-  "label": "🧱 Gutenberg Blocks",
-  "position": 4
-}

package/docs_old/docs/how-to/1.new-site.md

@@ -1,36 +0,0 @@
-# Creating a new site
-
-### Initial Setup
-
-1. [Create a new repo on Github](https://github.com/new)
-   1. Set `Owner` to `ed-digital`, and name your repo like `some-client-name`.
-   2. Set `Repository Template` to `ed-digital/eddev-starter-theme`
-   3. Hit `Create repository`
-2. Create a new site in Local, on your computer.
-   1. Use the default settings
-   2. Be sure to use `ed_admin` as the username, and create a secure password using 1pass or similar, and the email address should be `web@ed.com.au`
-   3. Save the username and password to 1pass.
-3. Install the following plugins:
-   1. Advanced Custom Fields Pro ([download](https://www.advancedcustomfields.com/my-account/view-licenses/)
-   2. Add `b3JkZXJfaWQ9NDA3NDN8dHlwZT1kZXZlbG9wZXJ8ZGF0ZT0yMDE0LTA5LTI3IDA4OjUwOjIx` as the key for ACF Pro under 'Custom Fields > Updates'
-   3. Yoast SEO — install from plugins dashboard
-   4. Gutenberg — install from plugins dashboard
-   5. Nested Pages — install from plugins dashboard
-   6. Admin Menu Editor — install from plugins dashboard (use this to hide unused sidebar items, and tidy up the menu for clients.)
-4. Under Settings -> General, remove 'Just another WordPress Site' and set Timezone to Sydney.
-6. Make sure that all the installed plugins have been activated.
-7. Clone your newly created theme to `wp-content/themes/`, making sure that the repo name and the theme folder name are identical.
-8. Run the following commands inside the theme folder
-   1. `composer update`
-   2. `yarn`
-   3. `yarn add --dev eddev`
-   4. `yarn setup`
-9. Activate the theme under Appearance > Themes
-10. Run `yarn dev`
-
-### Initial Flywheel Setup
-
-1. [Create a new site on Flywheel](https://app.getflywheel.com/new-site)
-   1. Select 'My Organisation'
-   2. The username and password are irrelevant, as they'll soon be overridden with your locally created details.
-2. Once complete, restart Local, and do an initial push to the new site, deploying to 'Production' with 'Include Database' selected.