- Buildpack + Buildpack source
- Build and layout optimization tooling for Magento PWA projects. + Project source code for the build and layout optimization tooling for Magento PWA projects.
- Peregrine + Peregrine source
- A collection of UI components for the Magento PWA projects. + Project source code for the collection of UI components for the Magento PWA projects.
- Venia Theme (Concept)
+ Venia Theme source
- A conceptual PWA theme for Magento 2 built using the Peregrine component library and Buildpack tools.
+ Project source code for a conceptual and customizable PWA theme for Magento 2.
+ It is built using the Peregrine component library and Buildpack tools.
diff --git a/packages/pwa-devdocs/src/technologies/basic-concepts/graphql/index.md b/packages/pwa-devdocs/src/technologies/basic-concepts/graphql/index.md
index c403a826b7..f25684b20d 100644
--- a/packages/pwa-devdocs/src/technologies/basic-concepts/graphql/index.md
+++ b/packages/pwa-devdocs/src/technologies/basic-concepts/graphql/index.md
@@ -1,5 +1,307 @@
---
-title:
+Title: GraphQL
+contributors: Jstein19
---
-{% include content-not-available.md issue=10 %}
+## What is GraphQL
+
+[GraphQL][] is a language for querying and manipulating data.
+It is widely viewed as more powerful, flexible, and efficient than REST.
+
+## Benefits provided by GraphQL
+
+### Predictable results from your queries
+
+A GraphQL query returns only data the user asks for in their query.
+
+### Single request for many results
+
+A single request made through GraphQL can return any number of resources and their fields by following references between them as defined in the typed schema.
+
+### Organized data with a typed schema
+
+A single schema defines how users access data using GraphQL.
+These schemas, formatted as JSON objects, let users know exactly how to get the data they need.
+
+The following is an example of a schema that defines a `Species` type with `name` and `origin` fields:
+
+``` graphql
+type Species {
+ name: String
+ origin: Planet
+}
+type Planet {
+ name: String
+}
+```
+
+{: .bs-callout .bs-callout-info}
+_**Note:** The `origin` field is a `Planet` type, which also has a `name` field._
+
+## Why use GraphQL over REST
+
+While GraphQL and REST are both specifications for constructing and querying APIs, GraphQL has some significant advantages over REST.
+
+### No versioning
+
+REST APIs typically have multiple versions, such as v1, v2, etc.
+This is because updating endpoints in REST will often impact existing queries.
+
+With GraphQL, there is no need for versioning, since new types and fields can be added to the schema without impacting existing queries.
+
+Removing fields is done through deprecation instead of deleting them from the schema.
+If an old query tries to read a deprecated field, GraphQL displays a customized warning.
+
+```
+type ExampleType {
+ firstName: String
+ lastName: String
+ name: String @deprecated(reason: "Split this field into two. Use `firstName` and `lastName`")
+}
+```
+
+This prevents old queries from throwing confusing errors when trying to read outdated fields, lending to code maintainability.
+
+### Faster and more efficient
+
+REST APIs typically require loading from multiple URLs.
+Imagine a REST API designed to get users and their forum posts.
+`users/` would return information like `name` and `user//posts` would have to be queried separately to return the user's `comments`.
+
+With GraphQL, these `types` and their `fields` are returned using one query, which saves calls to the API.
+
+In the following schema example, a `User` type contains a `posts` field, which is an array of `Post` types:
+
+``` graphql
+type Query {
+ user(id: Int): User
+ # This is our resolver; our entry into the query
+ # It lets us query `user` with an argument `id`
+ # And Expects to return a type `User`
+ # Yes, you can leave comments in schemas!
+}
+
+type User {
+ id: Int!
+ name: String
+ posts: [Post]
+}
+
+type Post {
+ id: Int!
+ title: String
+ author: User
+}
+```
+
+{: .bs-callout .bs-callout-info}
+_**Note:** The exclamation mark (!) next to a field in the schema indicates it is `non-nullable`, which means the GraphQL service promises to always return a value for this field on a query._
+
+A query for this schema that requests the name and all the post titles for a specific user would look like the following:
+
+``` graphql
+{
+ user(id: 12345) {
+ name
+ posts {
+ title
+ }
+ }
+}
+```
+
+The data response for the query would look like the following:
+
+```
+{
+ "data": {
+ "user": {
+ "name": "Jane Doe"
+ "posts": [
+ {
+ title: "Hello World"
+ },
+ {
+ title: "I Love GraphQL"
+ }
+ ]
+ }
+ }
+}
+```
+
+## Sample queries
+
+### Simple query
+
+Imagine a database that simply contains an object `User`, with the fields `name`, `email`, and `phone`.
+
+``` graphql
+type Query {
+ user: User
+}
+
+type User {
+ name: String
+ email: String
+ phone: String
+}
+```
+
+A simple query requesting this data would look like the following:
+
+ ``` graphql
+ {
+ user {
+ name
+ email
+ phone
+ }
+ }
+ ```
+
+The response to this query would look like the following:
+
+```
+{
+ "data": {
+ "user": {
+ "name": "Jane Doe"
+ "email": "JaneDoe@example.com"
+ "phone": "012-345-6789"
+ }
+ }
+}
+```
+
+### Custom data query
+
+What if you don't need the `phone` number from `User`?
+The previous query can be rewritten to return specific fields:
+
+``` graphql
+{
+ user {
+ name
+ email
+ }
+}
+```
+
+The response only provides the data requested:
+
+```
+{
+ "data": {
+ "user": {
+ "name": "Jane Doe"
+ "email": "JaneDoe@example.com"
+ }
+ }
+}
+```
+
+
+### Arguments in a query
+
+Now, what if you had multiple users and needed to grab a specific one using its `id`?
+Well, with GraphQL you can pass arguments into the query:
+
+```
+{
+ user(id: 12345) {
+ id
+ name
+ email
+ }
+}
+```
+
+The response would look like the following:
+
+```
+{
+ "data": {
+ "user": {
+ "id": "12345"
+ "name": "Jane Doe"
+ "email": "JaneDoe@example.com"
+ }
+ }
+}
+```
+
+{: .bs-callout .bs-callout-info}
+_**Note:** The `id` field is requested in the response in this example, but this is optional. It is used here to demonstrate that the correct user is returned._
+
+### Query connected resources
+
+In this example, imagine that in our database a `User` is associated with multiple hobbies.
+The schema would look like the following:
+
+``` graphql
+type Query {
+ user: User
+}
+
+type User {
+ name: String
+ email: String
+ phone: String
+ hobbies: [Hobby]
+}
+
+type Hobby {
+ name: String
+ frequency: String
+}
+```
+
+The following query requests the hobbies associated with a specific user:
+
+```
+{
+ user(id: 12345) {
+ name
+ email
+ phone
+ hobbies {
+ name
+ frequency
+ }
+ }
+}
+```
+
+The response would look like the following:
+
+```
+{
+ "data": {
+ "user": {
+ "name": "Jane Doe"
+ "email": "JaneDoe@example.com"
+ "phone": "012-345-6789"
+ "hobbies": [
+ {
+ "name": "painting",
+ "frequency": "weekly"
+ },
+ {
+ "name": "video games",
+ "frequency": "daily"
+ }
+ ]
+ }
+ }
+}
+```
+
+Notice how the user's `hobbies` are returned in an `array` as defined in the schema.
+
+## Learn more
+
+This topic just covers the basics of GraphQL.
+To learn more, visit the [GraphQL][] website.
+
+[GraphQL]: https://graphql.org/
\ No newline at end of file
diff --git a/packages/pwa-devdocs/src/venia-pwa-concept/setup/index.md b/packages/pwa-devdocs/src/venia-pwa-concept/setup/index.md
index 7c89e37dd0..579852046d 100644
--- a/packages/pwa-devdocs/src/venia-pwa-concept/setup/index.md
+++ b/packages/pwa-devdocs/src/venia-pwa-concept/setup/index.md
@@ -1,19 +1,29 @@
---
-title: Setup
+title: Venia theme setup
---
-Follow the instructions on this page to setup the [Venia PWA concept theme] for Magento 2.
-At the end of this tutorial, you will have the Venia theme project installed in Magento 2 and a local development environment set up.
+Venia is a PWA theme that runs on top of an existing Magento 2 backend.
+Follow the instructions on this page to setup and install the [Venia PWA concept theme][] in your Magento 2 instance.
-If you experience problems with the project setup, see [Troubleshooting] in the PWA Buildpack section.
+At the end of this tutorial, you will have a working copy of the Venia theme installed and running on top of Magento.
+Use this setup to explore or develop Magento PWA components and themes.
+
+If you experience problems with the project setup, see [Troubleshooting][] in the PWA Buildpack section.
## Prerequisites
-* A local development instance of Magento 2.3 or above.
-* [Node Package Manager] (NPM)
-* [NodeJS 8.x LTS]
+* [NodeJS 8.x LTS][]
+* [Node Package Manager][] (NPM)
+* A [local development instance][] of Magento 2.3 or above.
+
+ The steps outline in this tutorial have been verified and are known to work with the following setups:
+
+ * Magento 2 installed using [valet-plus][]
+ * [Vagrant Box for Magento 2 developers][]
+
+
-## Clone repository
+## Step 1. Clone repository
Clone the [PWA Studio] repository into your development environment.
@@ -25,11 +35,11 @@ git clone https://github.com/magento-research/pwa-studio.git
**Note:**
For this tutorial, the project location is the `/Users/magedev/pwa-studio` directory.
-### Vagrant Box instructions
+### Special instructions for virtual machine installations
If you are using a virtual machine, make sure it can access the new project directory and runs Magento 2.3.
-For example, if you are using the [Vagrant Box for Magento 2 developers], use the following steps to add a synced folder to the virtual machine and configure it to use Magento 2.3.
+For example, if you are using the [Vagrant Box for Magento 2 developers][], use the following steps to add a synced folder to the virtual machine and configure it to use Magento 2.3.
Show steps
@@ -80,7 +90,7 @@ If you clone the PWA Studio project repo into the `magento2ce` directory of the
```
-## Install PWA Studio dependencies
+## Step 2. Install PWA Studio dependencies
In the PWA Studio project's root directory, run the following command to install the project dependencies:
@@ -88,7 +98,7 @@ In the PWA Studio project's root directory, run the following command to install
npm install
```
-## Link module
+## Step 3. Link and install module
Navigate to your Magento installation's `app/code/Magento` directory and create a `Pwa` symlink folder linking to the project's `module` directory.
@@ -114,7 +124,7 @@ Install the module using the following command:
bin/magento setup:upgrade
```
-## Link theme directory
+## Step 4. Link theme directory
Navigate to your Magento installation's `app/design/frontend/Magento` directory and create a `venia` symlink folder linking to the project's `theme-frontend-venia` directory.
@@ -123,12 +133,12 @@ Navigate to your Magento installation's `app/design/frontend/Magento` directory
ln -s /Users/magedev/pwa-studio/packages/venia-concept venia
```
-## Activate the Venia theme
+## Step 5. Activate the Venia theme
Browse to the Admin section of your Magento store and configure it to use the **Magento Venia** theme.
You can find this configuration using the **Configuration** link in the **Content** tab.
-## Set environment variables
+## Step 6. Set environment variables
Under the Venia project's `theme-frontend-venia` directory, copy `.env.dist` into a new `.env` file and update the variables with the URL to your Magento development store.
@@ -140,16 +150,17 @@ cd /Users/magedev/pwa-studio/packages/venia-concept
cp .env.dist .env
```
-## Start the development server
+## Step 7. Start the development server
Use the following command to start the development server:
``` sh
npm start
```
+
{: .bs-callout .bs-callout-info}
**Note:**
-Some users have reported using `sudo npm start` works due to permissions.
+Some users have reported using `sudo npm start` to get around permissions.
After the development server is up and running, look for a similar line in the terminal output (the port will differ for your instance):
@@ -161,10 +172,6 @@ This is the new address for your PWA frontend.
You can still use the old address to access the Admin section of Magento, but
for PWA development on the frontend, use this new address.
-{: .bs-callout .bs-callout-info}
-**Note:**
-This project is still in development and only supports the `/home` route.
-
Congratulations! You have set up your development environment for the Venia theme project.
[Venia PWA concept theme]: https://github.com/magento-research/pwa-studio/tree/master/packages/venia-concept
@@ -173,3 +180,5 @@ Congratulations! You have set up your development environment for the Venia them
[Vagrant Box for Magento 2 developers]: https://github.com/paliarush/magento2-vagrant-for-developers
[Troubleshooting]: {{ site.baseurl }}{% link pwa-buildpack/troubleshooting/index.md %}
[PWA Studio]: https://github.com/magento-research/pwa-studio
+[local development instance]: https://devdocs.magento.com/guides/v2.3/install-gde/bk-install-guide.html
+[valet-plus]: https://github.com/weprovide/valet-plus
\ No newline at end of file
diff --git a/packages/venia-concept/package-lock.json b/packages/venia-concept/package-lock.json
index b3f312a1f7..f5d4c54869 100644
--- a/packages/venia-concept/package-lock.json
+++ b/packages/venia-concept/package-lock.json
@@ -7404,9 +7404,9 @@
}
},
"react": {
- "version": "16.3.2",
- "resolved": "https://registry.npmjs.org/react/-/react-16.3.2.tgz",
- "integrity": "sha512-o5GPdkhciQ3cEph6qgvYB7LTOHw/GB0qRI6ZFNugj49qJCFfgHwVNjZ5u+b7nif4vOeMIOuYj3CeYe2IBD74lg==",
+ "version": "16.4.2",
+ "resolved": "https://registry.npmjs.org/react/-/react-16.4.2.tgz",
+ "integrity": "sha512-dMv7YrbxO4y2aqnvA7f/ik9ibeLSHQJTI6TrYAenPSaQ6OXfb+Oti+oJiy8WBxgRzlKatYqtCjphTgDSCEiWFg==",
"requires": {
"fbjs": "^0.8.16",
"loose-envify": "^1.1.0",
@@ -7434,9 +7434,9 @@
}
},
"react-dom": {
- "version": "16.3.2",
- "resolved": "https://registry.npmjs.org/react-dom/-/react-dom-16.3.2.tgz",
- "integrity": "sha512-MMPko3zYncNrz/7gG17wJWUREZDvskZHXOwbttzl0F0L3wDmToyuETuo/r8Y5yvDejwYcRyWI1lvVBjLJWFwKA==",
+ "version": "16.4.2",
+ "resolved": "https://registry.npmjs.org/react-dom/-/react-dom-16.4.2.tgz",
+ "integrity": "sha512-Usl73nQqzvmJN+89r97zmeUpQDKDlh58eX6Hbs/ERdDHzeBzWy+ENk7fsGQ+5KxArV1iOFPT46/VneklK9zoWw==",
"requires": {
"fbjs": "^0.8.16",
"loose-envify": "^1.1.0",
diff --git a/packages/venia-concept/src/RootComponents/Category/category.js b/packages/venia-concept/src/RootComponents/Category/category.js
index 402de61aa8..e78c1f9b85 100644
--- a/packages/venia-concept/src/RootComponents/Category/category.js
+++ b/packages/venia-concept/src/RootComponents/Category/category.js
@@ -18,6 +18,7 @@ const categoryQuery = gql`
id
name
small_image
+ url_key
price {
regularPrice {
amount {
diff --git a/packages/venia-concept/src/__mocks__/@magento/peregrine.js b/packages/venia-concept/src/__mocks__/@magento/peregrine.js
new file mode 100644
index 0000000000..a9c6b0f3c1
--- /dev/null
+++ b/packages/venia-concept/src/__mocks__/@magento/peregrine.js
@@ -0,0 +1,8 @@
+import { createElement } from 'react';
+
+/**
+ * the Price component from @magento/peregrine
+ * has browser-specific functionality and cannot
+ * currently by rendered in the test environment
+ */
+export const Price = () => ;
diff --git a/packages/venia-concept/src/components/CategoryList/categoryList.js b/packages/venia-concept/src/components/CategoryList/categoryList.js
index 4f5e427783..19dd3494a8 100644
--- a/packages/venia-concept/src/components/CategoryList/categoryList.js
+++ b/packages/venia-concept/src/components/CategoryList/categoryList.js
@@ -1,5 +1,6 @@
import { Component, createElement } from 'react';
import { string, number, shape } from 'prop-types';
+import { Link } from 'react-router-dom';
import { Query } from 'react-apollo';
import gql from 'graphql-tag';
import classify from 'src/classify';
@@ -66,9 +67,9 @@ class CategoryList extends Component {
return (
{data.category.children.map((item, index) => (
-
{item.name}
-
+
))}
);
diff --git a/packages/venia-concept/src/components/Gallery/__tests__/item.spec.js b/packages/venia-concept/src/components/Gallery/__tests__/item.spec.js
index e1c4e36717..9fb6c72e70 100644
--- a/packages/venia-concept/src/components/Gallery/__tests__/item.spec.js
+++ b/packages/venia-concept/src/components/Gallery/__tests__/item.spec.js
@@ -1,6 +1,7 @@
import { createElement } from 'react';
-import { configure, shallow } from 'enzyme';
+import { configure, mount, shallow } from 'enzyme';
import Adapter from 'enzyme-adapter-react-16';
+import { BrowserRouter } from 'react-router-dom';
import Item from '../item';
@@ -25,6 +26,7 @@ const validItem = {
id: 1,
name: 'Test Product',
small_image: '/foo/bar/pic.png',
+ url_key: 'strive-shoulder-pack',
price: {
regularPrice: {
amount: {
@@ -57,6 +59,24 @@ test('passes classnames to the placeholder item', () => {
expect(wrapper.hasClass(classes.root_pending));
});
+test('renders Anchor elements for navigating to a PDP', () => {
+ const wrapper = mount(
+
+
+ );
+ const expectedSelector = `a[href="/${validItem.url_key}.html"]`;
+ const imageLink = wrapper
+ .find({ className: classes.images })
+ .find(expectedSelector);
+ const nameLink = wrapper
+ .find({ className: classes.name })
+ .find(expectedSelector);
+
+ expect(imageLink).toHaveLength(1);
+ expect(nameLink).toHaveLength(1);
+});
+
/**
* STATE 1: awaiting showImage flag
* `item` is a valid data object
diff --git a/packages/venia-concept/src/components/Gallery/item.js b/packages/venia-concept/src/components/Gallery/item.js
index fa8d0be818..6a7b9cba08 100644
--- a/packages/venia-concept/src/components/Gallery/item.js
+++ b/packages/venia-concept/src/components/Gallery/item.js
@@ -1,6 +1,7 @@
import { Component, createElement } from 'react';
import { string, number, shape, func, bool } from 'prop-types';
import { Price } from '@magento/peregrine';
+import { Link } from 'react-router-dom';
import classify from 'src/classify';
import { transparentPlaceholder } from 'src/shared/images';
import { makeProductMediaPath } from 'src/util/makeMediaPath';
@@ -17,6 +18,9 @@ const ItemPlaceholder = ({ children, classes }) => (
);
+// TODO: get productUrlSuffix from graphql when it is ready
+const productUrlSuffix = '.html';
+
class GalleryItem extends Component {
static propTypes = {
classes: shape({
@@ -37,6 +41,7 @@ class GalleryItem extends Component {
id: number.isRequired,
name: string.isRequired,
small_image: string.isRequired,
+ url_key: string.isRequired,
price: shape({
regularPrice: shape({
amount: shape({
@@ -67,17 +72,18 @@ class GalleryItem extends Component {
);
}
- const { name, price } = item;
+ const { name, price, url_key } = item;
+ const productLink = `/${url_key}${productUrlSuffix}`;
return (
-
+
{this.renderImagePlaceholder()}
{this.renderImage()}
-
-
+
+
{name}
-
+
- 
+
+
+
- Venia Theme (Concept) + Venia Theme source
- A conceptual PWA theme for Magento 2 built using the Peregrine component library and Buildpack tools. + Project source code for a conceptual and customizable PWA theme for Magento 2. + It is built using the Peregrine component library and Buildpack tools.
Show steps
@@ -80,7 +90,7 @@ If you clone the PWA Studio project repo into the `magento2ce` directory of the ```
{data.category.children.map((item, index) => (
-
{item.name}
-
+
))}
);
diff --git a/packages/venia-concept/src/components/Gallery/__tests__/item.spec.js b/packages/venia-concept/src/components/Gallery/__tests__/item.spec.js
index e1c4e36717..9fb6c72e70 100644
--- a/packages/venia-concept/src/components/Gallery/__tests__/item.spec.js
+++ b/packages/venia-concept/src/components/Gallery/__tests__/item.spec.js
@@ -1,6 +1,7 @@
import { createElement } from 'react';
-import { configure, shallow } from 'enzyme';
+import { configure, mount, shallow } from 'enzyme';
import Adapter from 'enzyme-adapter-react-16';
+import { BrowserRouter } from 'react-router-dom';
import Item from '../item';
@@ -25,6 +26,7 @@ const validItem = {
id: 1,
name: 'Test Product',
small_image: '/foo/bar/pic.png',
+ url_key: 'strive-shoulder-pack',
price: {
regularPrice: {
amount: {
@@ -57,6 +59,24 @@ test('passes classnames to the placeholder item', () => {
expect(wrapper.hasClass(classes.root_pending));
});
+test('renders Anchor elements for navigating to a PDP', () => {
+ const wrapper = mount(
+
-
+
{this.renderImagePlaceholder()}
{this.renderImage()}
-
-
+
+
{name}
-
+
-
+
+
+