Skip to content

Commit a144e74

Browse files
dadishdadish
committed
Update Readme & seperate screencast.
1 parent 01638e4 commit a144e74

File tree

2 files changed

+144
-83
lines changed

2 files changed

+144
-83
lines changed

‎Readme.md‎

Lines changed: 120 additions & 83 deletions
Original file line numberDiff line numberDiff line change
@@ -1,94 +1,113 @@
11
ProcessGraphQL
22
==============
33

4-
A GraphQL for ProcessWire.
5-
6-
The module seamlessly integrates to your [ProcessWire][pw] web app and allowa you to
7-
serve the GraphQL api of your existing app. You don't need to apply changes to
8-
your content or it's structure.
4+
The GraphQL for ProcessWire.
5+
6+
## Table of Contents
7+
1. [About](#about-processgraphql)
8+
2. [Requirements](#requirements)
9+
3. [Installation](#nstallation)
10+
4. [Configuration](#configuration)
11+
5. [Access Control](#access-control)
12+
6. [API](#api)
13+
7. [Features](#features)
14+
15+
## About ProcessGraphQL
16+
ProcessGraphQL is a module for [ProcessWire][pw]. The module seamlessly integrates to your ProcessWire
17+
web app and allows you to serve the GraphQL api of your existing content. You don't need to apply
18+
changes to your content or it's structure. Just choose what you want to serve via GraphQL and your
19+
API is ready.
920

1021
Here is an example of ProcessGraphQL in action after installing it to
1122
[skyscrapers][pw-skyscrapers] profile.
1223

1324
![ProcessGraphQL Simple Query][img-query]
1425

15-
ProcessGraphQL supports filtering via [ProcessWire Selectors][pw-selectors].
16-
17-
![ProcessGraphQL Supports ProcessWire Selectors][img-filtering]
18-
19-
ProcessGraphQL supports complex fields like FieldtypeImage or FieldtypePage.
20-
21-
![ProcessGraphQL Supporting FieldtypeImage and FieldtypePage][img-fieldtypes]
22-
23-
Documentation for your api is easily accessible via GraphiQL interface.
24-
![ProcessGraphQL Schema Documentation][img-documentation]
26+
See more [demo here](https://github.com/dadish/ProcessGraphQL/blob/master/ScreenCast.md).
2527

2628
## Requirements
27-
- ProcessWire version 3.x.x and up. There are no plans to support the older versions.
28-
- PHP version 5.5 and up.
29+
- ProcessWire version >= 3.x
30+
- PHP version >= 5.5.x
2931

3032
> It would be very helpful if you open an issue when encounter errors regarding
3133
> environment incompatibilities.
3234
3335
## Installation
34-
To install the module, go to __Modules -> Install -> Add New__. Scroll down to get
35-
to the section __Add Module from URL__. Paste this URL into the __Module ZIP file URL__ field
36-
`https://github.com/dadish/ProcessGraphQL/archive/master.zip` then press __Download__.
37-
ProcessWire will download this module and place it at `/site/modules/` directory for you.
38-
After you did that, you should see __GraphQL__ module among others. Go ahead and press __Install__
39-
button next to it. Choose the templates and fields you want to access through your GaphQL api and
40-
you are good to go.
41-
42-
After you installed the ProcessGraphQL, you can go to `Setup -> GraphQL` in your
43-
admin panel and you will see the GraphiQL where you can perform queries to your
44-
GraphQL api.
45-
46-
## Configuration
47-
There are some options to configure the ProcessGraphQL module.
48-
49-
### MaxLimit
50-
The MaxLimit option allows you to set the ProcessWire's [limit][pw-api-selectors-limit] slelector. So that
51-
client is not able to more than that. While client can set values less than MaxLimit, if
52-
she requests more it will be overwritten and set to MaxLimit. Default is 100.
53-
#### Type
54-
`Integer`
55-
#### Api Property
56-
`maxLimit`
57-
#### Api Usage
58-
```php
59-
$ProcessGraphQL = $modules->get('ProcessGraphQL');
60-
$ProcessGraphQL->maxLimit = 50;
36+
To install the module, go to __Modules -> Install -> Add New__. Scroll down to get to the section
37+
__Add Module from URL__. Paste the below URL into the __Module ZIP file URL__ field and press __Download__.
6138
```
62-
63-
### Legal Templates
64-
Legal Templates are the templates that can be fetched via ProcessGraphQL. You have explicitly
65-
tell ProcessGraphQL which templates you wish to declare as public api.
66-
67-
Please note that making a template legal does not neccessarily mean it is open to everyone.
68-
The user permissions still apply. If you selected template __user__ as legal but the
69-
requesting user does not have permissions to view it. She won't be able to retrieve that data.
70-
#### Type
71-
`Array`
72-
#### Api Property
73-
`legalTemplates`
74-
#### Api Usage
75-
```php
76-
$ProcessGraphQL = $modules->get('ProcessGraphQL');
77-
$ProcessGraphQL->legalTemplates = array('skyscraper', 'city', 'architect', 'basic-page');
39+
https://github.com/dadish/ProcessGraphQL/archive/master.zip
7840
```
41+
ProcessWire will download this module and place it at `/site/modules/` directory for you. After you
42+
did that, you should see __GraphQL__ module among others. Go ahead and press __Install__ button next
43+
to it.
7944

80-
### Legal Fields
81-
Provides same functionality as for Legal Templates. Only the selected fields will be available
82-
via GraphQL api.
83-
#### Type
84-
`Array`
85-
#### Api Property
86-
`legalFields`
87-
#### Api Usage
88-
```php
89-
$ProcessGraphQL = $modules->get('ProcessGraphQL');
90-
$ProcessGraphQL->legalFields = array('title', 'year', 'height', 'floors');
91-
```
45+
After you installed the ProcessGraphQL, you will be taken to the module configuration page. Where you
46+
will have many options to setup the module the way you want. More on that in the section below.
47+
48+
## Configuration
49+
The ProcessGraphQL module will serve only the parts of your content which you explicitly ask for.
50+
The module configuration page provides you with exactly that. Here you should choose what parts of
51+
your website should be available via GraphQL API. The options are grouped into four sections.
52+
53+
#### Legal Templates
54+
In this section you choose the _templates_ that you want ProcessGraphQL to handle. The pages associated
55+
with the templates you choose here will be available to the _superuser_ immediately. You will see later
56+
how you can grant access to these template to other user roles as well.
57+
58+
> If some of your templates are disabled and you can't choose them. That means that their names are not
59+
> compatible with [GraphQL api naming rules][graphql-naming]. You will have to change the names of the template and/or
60+
> field so that it conforms those rules if you want ProcessGraphQL module to handle for you.
61+
62+
#### Legal Fields
63+
Here you should choose the fields that you want to be available via GraphQL API. These fields also
64+
will immediately be available to the _superuser_.
65+
66+
> Beware when you choose _system_ templates & fields as legal for ProcessGraphQL module. This could
67+
> potentially expose very sensitive information and undermine security of your website.
68+
69+
#### Legal Page Fields
70+
These are the built-in fields of the ProcessWire Page. You should choose only the ones you will certainly
71+
need in your API.
72+
73+
#### Legal PageFile Fields
74+
Built-in fields of the FieldtypeFile and FieldtypeImage.
75+
76+
Don't mind the __Advanced__ section for now. We will come to that later. After you have chosen all
77+
parts you need, submit the module configuration. Now you can go to _Setup -> GraphQL_ and you will see
78+
the GraphiQL GUI where you can query your GraphQL api. Go ahead and play with it.
79+
80+
## Access Control
81+
As mentioned earlier, the GraphQL API will be accessible only by _superuser_. To grant access to users
82+
with different roles, you need to use __Access__ settings in your templates and fields. Say you want
83+
user with role `skyscraper-editor` to be able to view pages with template `skyscraper`. Go to _Setup ->
84+
Templates -> skyscraper -> Access_, enable access settings, and make sure that `skyscraper-editor`
85+
role has `View Page` rule.
86+
87+
> The ProcessWire'a Access Control system is very flexible and allows you to fine tune your access rules
88+
> the way you want. You will use it to control your GraphQL API as well. Learn more about ProcessWire's
89+
> Access Control system [here][pw-access].
90+
91+
While the above configuration will allow the `skyscraper-editor` to view `skyscraper` pages' built-in
92+
fields that you have enabled, but that's not the end of it. If you want the `skyscraper-editor`
93+
user to view the template fields, like _title, headline, body_, you will need to make those fields
94+
viewable in their respective __Access__ settings.
95+
96+
You might say that this much restriction is too much. It is true, but no worries we got you covered.
97+
This is just the default behavior and set that way to ensure maximum security. If you don't want to
98+
go over fields' Access settings and setup rules for each of them manually, you can change the module's
99+
behavior in the __Advanced__ section of the module configuration page. There are two options you can
100+
enable.
101+
102+
#### Grant Template Access
103+
If you check this field, all the legal templates that do not have their Access settings enabled, will
104+
be available to everyone. But they will still conform to __Access__ settings when they are enabled.
105+
So you can restrict each template via their __Access__ settings.
106+
107+
#### Grant Field Access
108+
This works the same as the above. Grants access to all fields that do not have __Access__ settings
109+
enabled. This option could be useful in cases where you have 20 or something fields and you want
110+
all of them be accessible and add restrictions to only few via field's Access settings.
92111

93112
## API
94113
If you wish to expose your GraphQL api, you can do so by calling a single method on
@@ -118,33 +137,51 @@ By default the GraphiQL is pointed to your admin GraphQL server, which is
118137
`/processwire/setup/graphql/`. You might want to change that because ProcessWire
119138
will not allow guest users to access that url. You can point GraphiQL to whatever adress
120139
you want by a property `GraphQLServerUrl`. ProcessGraphQL will respect that property
121-
when exposing GraphiQL.
122-
Here is how you might do this in your template file.
140+
when exposing GraphiQL. Here is how you might do this in your template file.
123141
```php
142+
<?php
143+
124144
// /site/templates/graphiql.php
125145

126146
$ProcessGraphQL = $modules->get('ProcessGraphQL');
127147
$ProcessGraphQL->GraphQLServerUrl = '/graphql/';
128148
echo $ProcessGraphQL->executeGraphiQL();
129149
```
130-
131-
### Limitations
132-
At this stage the module only supports the `Query` schema. The support for `Mutation` will come
133-
soon.
134-
135-
### Permissions
136-
ProcessGraphQL respects the ProcessWire permissions on template level. It basicly does that
137-
via `$user->hasPermission('page-view', $template)`. So as long as the client does not have
138-
that permission she won't be able to query it.
150+
> Make sure the url is exactly where your GraphQL api is. E.g. it ends with slash.
151+
> See [here](https://github.com/dadish/ProcessGraphQL/issues/1) why it is important.
152+
153+
## Features
154+
### GraphQL Operations
155+
The module will eventually support all operations you need to build fully functioning SPA. For now
156+
you can perform most common operations.
157+
- Fetch pages, page fields, subfields. Including file and image fields.
158+
- Authenticate. You can login and logout with your GraphQL API.
159+
- Page creation. You can create pages via GraphQL API.
160+
- Language support. If your site uses ProcessWire's core LanguageSupport module, you can fetch data
161+
in your desired language.
162+
- `pages` field. _Experimental_. Allows you to fetch any page in your website, just like
163+
`$pages->find()`
164+
165+
### Compatible Fields
166+
At this moment ProcessGraphQL handles most of the ProcessWire's core fieldtypes. Those are:
167+
- FieldtypeCheckbox
168+
- FieldtypeDatetime
169+
- FieldtypeEmail
170+
- FieldtypeFile
171+
- FieldtypeFloat
172+
- Fieldtype
173+
All the core ProcessWire fields will eventually be supported.
139174

140175
## License
141176
[MIT](https://github.com/dadish/ProcessGraphQL/blob/master/LICENSE)
142177

143178
[graphql]: http://graphql.org/
179+
[graphql-naming]: http://facebook.github.io/graphql/#sec-Names
144180
[graphiql]: https://github.com/graphql/graphiql/
145181
[pw]: https://processwire.com
146182
[pw-skyscrapers]: http://demo.processwire.com/
147183
[pw-selectors]: https://processwire.com/api/selectors/
184+
[pw-access]: http://processwire.com/api/user-access/
148185
[pw-api-selectors-limit]: https://processwire.com/api/selectors#limit
149186
[img-query]: https://raw.githubusercontent.com/dadish/ProcessGraphQL/master/imgs/ProcessGraphQL-Query.gif
150187
[img-filtering]: https://raw.githubusercontent.com/dadish/ProcessGraphQL/master/imgs/ProcessGraphQL-Filtering.gif

‎ScreenCast.md‎

Lines changed: 24 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,24 @@
1+
## ProcessGraphQL ScreenCast
2+
3+
Query only what you need and how you need it.
4+
5+
![ProcessGraphQL Simple Query][img-query]
6+
7+
ProcessGraphQL supports filtering via [ProcessWire Selectors][pw-selectors].
8+
9+
![ProcessGraphQL Supports ProcessWire Selectors][img-filtering]
10+
11+
ProcessGraphQL supports complex fields like FieldtypeImage or FieldtypePage.
12+
13+
![ProcessGraphQL Supporting FieldtypeImage and FieldtypePage][img-fieldtypes]
14+
15+
Documentation for your api is easily accessible via GraphiQL interface.
16+
17+
![ProcessGraphQL Schema Documentation][img-documentation]
18+
19+
Learn more from the [documentation](https://github.com/dadish/processgraphql#processgraphql).
20+
21+
[img-query]: https://raw.githubusercontent.com/dadish/ProcessGraphQL/master/imgs/ProcessGraphQL-Query.gif
22+
[img-filtering]: https://raw.githubusercontent.com/dadish/ProcessGraphQL/master/imgs/ProcessGraphQL-Filtering.gif
23+
[img-fieldtypes]: https://raw.githubusercontent.com/dadish/ProcessGraphQL/master/imgs/ProcessGraphQL-Fieldtypes.gif
24+
[img-documentation]: https://raw.githubusercontent.com/dadish/ProcessGraphQL/master/imgs/ProcessGraphQL-Documentation.gif

0 commit comments

Comments
 (0)