From a5d79bd6f9ba9ac1f3a75161e5e5057fc9275887 Mon Sep 17 00:00:00 2001 From: veltrup Date: Fri, 19 Jan 2024 11:27:05 +0100 Subject: [PATCH] docs: add components and bundle documentations --- docs/develop/bundles/citygov.md | 19 +++++ docs/develop/bundles/graphql-search.md | 19 +++++ docs/develop/bundles/index.md | 19 +++++ docs/develop/bundles/security.md | 21 +++++ docs/develop/components/index.md | 3 +- docs/develop/components/resource.md | 4 +- docs/develop/components/search.md | 83 +++++++++++++++++++ docs/develop/graphql/getting-started.md | 8 +- docs/develop/graphql/index.md | 4 +- docs/develop/graphql/search/resolve-teaser.md | 4 +- mkdocs.yml | 6 ++ 11 files changed, 179 insertions(+), 11 deletions(-) create mode 100644 docs/develop/bundles/citygov.md create mode 100644 docs/develop/bundles/graphql-search.md create mode 100644 docs/develop/bundles/index.md create mode 100644 docs/develop/bundles/security.md create mode 100644 docs/develop/components/search.md diff --git a/docs/develop/bundles/citygov.md b/docs/develop/bundles/citygov.md new file mode 100644 index 0000000..eac38c8 --- /dev/null +++ b/docs/develop/bundles/citygov.md @@ -0,0 +1,19 @@ +# CityGov Bundle + +CityGov is a product of Sitepark. The main areas of application of CityGov are the Internet presences of municipalities and district administrations as well as their employee portals on the intranet. + +## Sources + +The sources can be accessed via the GibHub project [https://github.com/sitepark/atoolo-citygov-bundle](https://github.com/sitepark/atoolo-citygov-bundle){:target="\_blank"}. + +## Installation + +Use [Composer](https://getcomposer.org/){:target="\_blank"} to install this component in your PHP project: + +```sh +composer require atoolo/citygov-bundle +``` + +## Extended indexing + +The bundle contains [Document Enricher](../components/search.md#custom-document-enricher), which extends the full-text index for the search with CityGov-specific fields. This allows CityGov-specific searches to be created. diff --git a/docs/develop/bundles/graphql-search.md b/docs/develop/bundles/graphql-search.md new file mode 100644 index 0000000..ae7e7e5 --- /dev/null +++ b/docs/develop/bundles/graphql-search.md @@ -0,0 +1,19 @@ +--- +status: draft +--- + +# GraphQL Search Bundle + +The GraphQL Search Bundle uses the functionalities of the [Search component](../components/search.md) and extends the GraphQL interface with the ability to perform searches. + +## Sources + +The sources can be accessed via the GibHub project [https://github.com/sitepark/atoolo-graphql-search-bundle](https://github.com/sitepark/atoolo-graphql-search-bundle){:target="\_blank"}. + +## Installation + +Use [Composer](https://getcomposer.org/){:target="\_blank"} to install this component in your PHP project: + +```sh +composer require atoolo/graphql-search-bundle +``` diff --git a/docs/develop/bundles/index.md b/docs/develop/bundles/index.md new file mode 100644 index 0000000..517f205 --- /dev/null +++ b/docs/develop/bundles/index.md @@ -0,0 +1,19 @@ +# Atoolo Bundles + +Atoolo Bundles are [Symfony Bundles](https://symfony.com/doc/current/bundles.html){:target="\_blank"} that extend Symfony projects with certain Atoolo functionalities. + +## Installation + +Use [Composer](https://getcomposer.org/){:target="\_blank"} to install any of the Atoolo Bundles in your PHP project. +Further information on the installation of Symfony bundles can be found [here](https://symfony.com/doc/current/setup.html#installing-packages){:target="\_blank"}. + +```sh +composer require atoolo/[bundle] +``` + +## All Atoolo Bundles + +|
Name
| Description | +| --------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| [`atoolo/graphql-search-bundle`](graphql-search.md) | This bundle extends the GraphQL interface with a [search](../graphql/search/index.md). | +| [`atoolo/citygov-bundle`](citygov.md) | CityGov is a product of Sitepark. The main areas of application of CityGov are the Internet presences of municipalities and district administrations as well as their employee portals on the intranet. | diff --git a/docs/develop/bundles/security.md b/docs/develop/bundles/security.md new file mode 100644 index 0000000..f586609 --- /dev/null +++ b/docs/develop/bundles/security.md @@ -0,0 +1,21 @@ +--- +status: draft +--- + +# Security Bundle + +The Atoolo Security Bundle is based on the [Security Bundle](https://symfony.com/components/Security%20Bundle){:target="\_blank"} and contains Atoolo-specific configurations and extensions for a role and user management system that can be maintained via the CMS IES. + +If necessary, it contains the necessary settings to secure individual queries of the GraphQL interface. + +## Sources + +The sources can be accessed via the GibHub project [https://github.com/sitepark/atoolo-security-bundle](https://github.com/sitepark/atoolo-security-bundle){:target="\_blank"}. + +## Installation + +Use [Composer](https://getcomposer.org/){:target="\_blank"} to install this component in your PHP project: + +```sh +composer require atoolo/security-bundle +``` diff --git a/docs/develop/components/index.md b/docs/develop/components/index.md index 3654705..b41b113 100644 --- a/docs/develop/components/index.md +++ b/docs/develop/components/index.md @@ -4,7 +4,7 @@ Atoolo components are individual, preferably independent libraries that cover a ## Installation -Use [Composer](https://getcomposer.org/) to install any of the Atoolo Components in your PHP project: +Use [Composer](https://getcomposer.org/){:target="\_blank"} to install any of the Atoolo Components in your PHP project: ```sh composer require atoolo/[component] @@ -15,3 +15,4 @@ composer require atoolo/[component] |
Name
| Description | | ---------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------- | | [`atoolo/resource`](resource.md) | In the Atoolo context, resources from IES (Sitepark's content management system) are aggregated data that can be handled through this library. | +| [`atoolo/search`](search.md) | Provides services with which a Solr index can be filled and searched for [resources](resource.md) via this index. | diff --git a/docs/develop/components/resource.md b/docs/develop/components/resource.md index c7cb16d..d2b9736 100644 --- a/docs/develop/components/resource.md +++ b/docs/develop/components/resource.md @@ -6,11 +6,11 @@ There can be different formats in which the resource is aggregated by the CMS. T ## Sources -The sources can be accessed via the GibHub project [https://github.com/sitepark/atoolo-resource](https://github.com/sitepark/atoolo-resource). +The sources can be accessed via the GibHub project [https://github.com/sitepark/atoolo-resource](https://github.com/sitepark/atoolo-resource){:target="\_blank"}. ## Installation -Use [Composer](https://getcomposer.org/) to install this component in your PHP project: +Use [Composer](https://getcomposer.org/){:target="\_blank"} to install this component in your PHP project: ```sh composer require atoolo/resource diff --git a/docs/develop/components/search.md b/docs/develop/components/search.md new file mode 100644 index 0000000..b3fc570 --- /dev/null +++ b/docs/develop/components/search.md @@ -0,0 +1,83 @@ +--- +status: draft +--- + +# Search Component + +Provides services with which a Solr index can be filled and searched for [resources](resource.md) via this index. + +## Sources + +The sources can be accessed via the GibHub project [https://github.com/sitepark/atoolo-search](https://github.com/sitepark/atoolo-search){:target="\_blank"}. + +## Installation + +Use [Composer](https://getcomposer.org/){:target="\_blank"} to install this component in your PHP project: + +```sh +composer require atoolo/search +``` + +## Indexing + +### Custom Document Enricher + +Document Enricher allow the document that is passed to Solr for indexing to be enriched with the desired fields. Here it is possible to react to product or customer-specific object types and to set the document according to requirements. + +The document to be filled must adhere to the schema stored in Solr. Only the fields that are known in the schema can be set. Currently the schema `2.1` is used. The implementation `IndexSchema2xDocument` of the `IndexDocument` interface is available for this purpose. The document enricher must implement the interface `DocumentEnricher`. + +```php + + */ +class CustomDocumentEnricher implements DocumentEnricher +{ + public function isIndexable(Resource $resource): bool + { + return true; + } + + public function enrichDocument( + Resource $resource, + IndexDocument $doc, + string $processId + ): IndexDocument { + if ( + $resource->getObjectType() !== 'myObjectType' + ) { + return $doc; + } + + // ... enrich document + + return $doc; + } +} +``` + +The document enricher is required, for example, in the [GraphQL Search Bundle](../bundles/graphql-search.md). This offers a mutation that is also used by the CMS IES to trigger indexing. See also [GraphQl Indexing](../graphql/search/indexing.md). So that your own document enricher can be used, it must be registered as [tagged Symfony service](https://symfony.com/doc/current/service_container/tags.html){:target="\_blank"}. + +`services.yaml` + +```yaml +services: + Atoolo\Examples\Search\Indexer\Enricher\CustomDocumentEnricher: + tags: + - { + name: "atoolo.search.indexer.documentEnricher.schema2x", + priority: 10, + } +``` + +## Searching diff --git a/docs/develop/graphql/getting-started.md b/docs/develop/graphql/getting-started.md index 047449d..c6bd6e0 100644 --- a/docs/develop/graphql/getting-started.md +++ b/docs/develop/graphql/getting-started.md @@ -8,9 +8,9 @@ A Symfony 6.4 project with Symfony-Flex is required. In this project the GraphQL ## Install -For GraphQl integration the [`overblog/GraphQLBundle`](https://github.com/overblog/GraphQLBundle) Symfony bundle is used. +For GraphQl integration the [`overblog/GraphQLBundle`](https://github.com/overblog/GraphQLBundle){:target="\_blank"} Symfony bundle is used. -It is integrated via the [Symfony Flex installation](https://github.com/overblog/GraphQLBundle/blob/master/docs/index.md#symfony-flex-installation). +It is integrated via the [Symfony Flex installation](https://github.com/overblog/GraphQLBundle/blob/master/docs/index.md#symfony-flex-installation){:target="\_blank"}. The Symfony Flex Recipes from Sitepark must be used to ensure that the configurations are created correctly. @@ -44,7 +44,7 @@ composer require --dev overblog/graphiql-bundle ### Basics -To learn the basics of GraphQL, ["Introduction to GraphQL"](https://graphql.org/learn/) is a good place to start. +To learn the basics of GraphQL, ["Introduction to GraphQL"](https://graphql.org/learn/){:target="\_blank"} is a good place to start. ### Commandline @@ -63,7 +63,7 @@ curl "https://www.example.com/api/graphql/" --fail \ Because GraphQL is a communication pattern, there are many tools to help you get started working which support GraphQL in all sorts of languages. -E.g. for JavaScript clients see [here](https://graphql.org/code/#javascript-client) +E.g. for JavaScript clients see [here](https://graphql.org/code/#javascript-client){:target="\_blank"} ### GraphiQL diff --git a/docs/develop/graphql/index.md b/docs/develop/graphql/index.md index 04442bb..0e459eb 100644 --- a/docs/develop/graphql/index.md +++ b/docs/develop/graphql/index.md @@ -10,7 +10,7 @@ You can view the available resources in the GraphQL API reference. The reference The GraphQL API endpoint is located at `/api/graphql`. -The [GraphQL Schema Language Cheat Sheet](https://raw.githubusercontent.com/sogko/graphql-shorthand-notation-cheat-sheet/master/graphql-shorthand-notation-cheat-sheet.png) is also helpful. +The [GraphQL Schema Language Cheat Sheet](https://raw.githubusercontent.com/sogko/graphql-shorthand-notation-cheat-sheet/master/graphql-shorthand-notation-cheat-sheet.png){:target="\_blank"} is also helpful. ## GraphiQL @@ -24,6 +24,6 @@ The documentation of the GraphQL API resources is automatically generated based ## Breaking changes -The GraphQL API is [versionless](https://graphql.org/learn/best-practices/#versioning) and changes to the API are primarily backward-compatible. +The GraphQL API is [versionless](https://graphql.org/learn/best-practices/#versioning){:target="\_blank"} and changes to the API are primarily backward-compatible. Should the GraphQL API change in a way that is not backward compatible, these changes are called "Breaking Changes" and may involve removing or renaming fields, arguments, or other parts of the schema. When a Breaking Change is created, there will be a transition period where the old from will continue to be supported and marked deprecated. Until a time when the parts marked as deprecated are removed. diff --git a/docs/develop/graphql/search/resolve-teaser.md b/docs/develop/graphql/search/resolve-teaser.md index 43d2ce3..eb1d996 100644 --- a/docs/develop/graphql/search/resolve-teaser.md +++ b/docs/develop/graphql/search/resolve-teaser.md @@ -27,7 +27,7 @@ The 'teaser' field is used to determine the teaser of a resource. In this case, `__typename` and `url` are the only fields that are available for all teaser types. All other fields must be queried individually depending on the teaser type. -This is solved in GraphQL with [Inline Fragments](https://graphql.org/learn/queries/#inline-fragments). +This is solved in GraphQL with [Inline Fragments](https://graphql.org/learn/queries/#inline-fragments){:target="\_blank"}. ```graphql { @@ -53,7 +53,7 @@ This is solved in GraphQL with [Inline Fragments](https://graphql.org/learn/quer The article teaser is the classic teaser that can contain a headline, a text and possibly an asset (e.g. an image). -In the following example, the fields of the article teaser are read out and [Fragments](https://graphql.org/learn/queries/#fragments) is also used. +In the following example, the fields of the article teaser are read out and [Fragments](https://graphql.org/learn/queries/#fragments){:target="\_blank"} is also used. See also in the [reference](../reference.md#articleteaser). diff --git a/mkdocs.yml b/mkdocs.yml index afb4389..33f7e72 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -8,6 +8,12 @@ nav: - Components: - develop/components/index.md - Resource: develop/components/resource.md + - Search: develop/components/search.md + - Bundle: + - develop/bundles/index.md + - Security: develop/bundles/security.md + - GraphQL Search: develop/bundles/graphql-search.md + - CityGov: develop/bundles/citygov.md - GraphQL API: - develop/graphql/index.md - Getting started: develop/graphql/getting-started.md