From b841e64e551811295060e3b5af4a9fd3c433cd1e Mon Sep 17 00:00:00 2001 From: samuelreichor Date: Wed, 30 Oct 2024 17:40:51 +0100 Subject: [PATCH] Add more detailed readme and changelog --- CHANGELOG.md | 7 +++- README.md | 115 ++++++++++++++++++++++++++++++++++++++++++++------- 2 files changed, 106 insertions(+), 16 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index 7d7a6db..caff6ee 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -1,7 +1,10 @@ # Release Notes for CraftQuery API -## 1.0.0 +## 1.0.0 - 2024-10.30 - Initial release -## 1.0.1 +## 1.0.1 - 2024-10.30 - Add icon to plugin and more information in the readme. + +## 1.0.2 - 2024-10.30 +- Add more information to the readme. Change Changelog format diff --git a/README.md b/README.md index 5df6d29..76e642c 100644 --- a/README.md +++ b/README.md @@ -1,33 +1,120 @@ -# CraftQuery API +
+ + Craft Query API + +
+
+

The Query API for Craft CMS

+

+ Craft Query API is a Craft CMS plugin to use the loved query builder in your favorite js-framework. +

+
+
+ +

+ + + + + + + + + + + + +

-A plugin that speeds up development in headless mode with custom fetch queries. > [!WARNING] -> This plugin is still in her early days and important features may change. +> This npm package is still in production and important features may change. + +## Features +- API to query addresses, assets, entries and users based on url parameters. +- API for query all urls of every active page with template for prerendering. +- Automatic detection of imagerx transforms. +- Automatic detection of native and custom fields on all elementTypes. ## Requirements This plugin requires Craft CMS 5.0.0 or later, and PHP 8.2 or later. -## Installation +## Qick start + +1. Set up a craft project by using that guide: https://craftcms.com/docs/getting-started-tutorial/install/ +2. Install the Craft Query API Plugin using that command: + ```bash + composer require samuelreichoer/craft-query-api && php craft plugin/install craft-query-api + ``` +3. Add following config to prevent cors origin errors in that file `config/app.web.php` + ```php + [ + 'class' => \craft\filters\Cors::class, + + // Add your origins here + 'cors' => [ + 'Origin' => [ + 'http://localhost:3000', + 'http://localhost:5173', + ], + 'Access-Control-Request-Method' => ['GET'], + 'Access-Control-Request-Headers' => ['*'], + 'Access-Control-Allow-Credentials' => true, + 'Access-Control-Max-Age' => 86400, + 'Access-Control-Expose-Headers' => [], + ], + ], + ]; + ``` -You can install this plugin from the Plugin Store or with Composer. +4. That's it you can test it by hitting that endpoint `${PRIMARY_SITE_URL}/v1/api/customQuery`. You should get an empty array as response. -#### From the Plugin Store +## Optional things to configure: -Go to the Plugin Store in your project’s Control Panel and search for “Craft Query API”. Then press “Install”. +### Set headless mode in your `config/general.php` to `true` -#### With Composer +Read more about the headless mode [here](https://craftcms.com/docs/getting-started-tutorial/more/graphql.html#optional-enable-headless-mode). -Open your terminal and run the following commands: +### Tell Craft where your frontend lives -```bash -# tell Composer to load the plugin -composer require samuel-reichoer/craft-query-api +This is important, to get previews of entries working. -# tell Craft to install the plugin -./craft plugin/install craft-query-api +Add a new env var: +``` +WEBSITE_URL="http://localhost:3000" +``` + +Add new alias in the config/general.php: +``` +->aliases([ + '@web' => getenv('PRIMARY_SITE_URL'), + '@websiteUrl' => getenv('WEBSITE_URL'), +]) ``` +And finally go to your control panel settings -> sites -> and change the base URL of your Site. + +### Configure ImagerX + +If you are using ImagerX (what I recommend) then you have to generate all transforms of the images before you can query them. Therefore you need a `imager-x-generate.php` File in your config folder with all named transforms in it. This can look like that: +```php + [ + 'images' => ['auto', 'square', 'landscape', 'portrait', 'dominantColor'], + ] +]; +``` + +The plugin will automatically detect the named transforms and widths defined in your `imager-x-transforms.php`. In the response, you'll get an object where the key is the name of the transform, and the value is a srcset of all defined transforms. + +### Configure SEO Matic + +Seo Matic has its own Endpoints. You can enable these in the plugin setting. ## Further Resources