Issue #3316212: Update Readme

# Href Lang Exchange

CONTENTS OF THIS FILE

---------------------

## Installation

* Introduction

* Permissions

* Requirements

* Recommended modules

* Installation

* Configuration

* Usage

* Notes

* Maintainers

INTRODUCTION

------------

First of all the modules on which it depends must be installed:

The Module Collection has two Entity types.

- Country - https://www.drupal.org/project/country

- Languagefield - https://www.drupal.org/project/languagefield

```

composer require 'drupal/languagefield:^1.8' composer require 'drupal/country:^1.0'

```

Install this modules like any other Drupal modules.

It consists of 3 modules.

### href_lang_exchange

- dependencies:

    - field

    - jsonapi

From the href_lang_exchange_href module the ```site_entity``` which can be accessed via the

```/admin/structure/site_entity/settings``` can be extended.

### href_lang_entity_manager

- dependencies:

    - field

    - jsonapi

    - href_lang_exchange

    - views

### href_lang_exchange_href

- dependencies:

    - field

    - href_lang_exchange

    - country

    - languagefield

### href_lang_exchange_lang_country_override

- dependencies:

    - field

    - href_lang_exchange

    - country

    - languagefield

## Configuration

The Module Collection has 2 Entity Types.

From the href_lang_exchange_href module the site_entity which can be accessed via the

/admin/structure/site_entity/settings can be extended.

The creation of these site entities is only done on the master.

The administration page can be found under /admin/structure/site_entity.

Furthermore there is a Settings Form (/admin/structure/site_entity/basic_settings) which is not available for the Site Editor.

is meant to be. There you can set the configuration for the authentication and the url for the master server.

The administration page can be found under ```/admin/structure/site_entity```.

Furthermore, there is a Settings Form (/admin/structure/site_entity/basic_settings) which is not available for the Site Editor.

There you can set the configuration for the authentication and the url for the master server.

The second entity type is the href_lang_item which is present in the base module href_lang_exchange.

this is used to exchange the href lang information and is unintresting for the end user. To

debug or administrate can the module href_lang_entity_manager be activated it provides a view which

The second entity type is the ```href_lang_item which``` is present in the base module ```href_lang_exchange```.

this is used to exchange the href lang information and is uninteresting for the end user. To

debug or administrate can the module ```href_lang_entity_manager``` be activated it provides a view which

gives an overview of all href lang items.

## Usage

To use this module, a field of type 'Href lang exchange item' must be added to the entity.

On the master site the site entities must be created.

and now you can used the module.

## Berechtigungen

PERMISSIONS

-----------

### Permission List:

- add site entity entities:

- administer href_lang_item entity:

- administer href-lang exchange:

### Usage

### Permission usage:

For the admin menu toolbar you need the following permissions.

- Use the administration toolbar

- Administer menus and menu items

- Use the administration pages and help

------------------

For the /href_lang_item/list and all href_lang_item things

For the ```/href_lang_item/list and all href_lang_item``` things

- View the administration theme:

  - To see the theme

- Administer href-lang exchange:

  - To edit/update href_lang_items

- delete href_lang_item entity:

  - To delete href_lang_items

------------------

For the Management of Site entieties (Administration Only)

For the Management of Site entities (Administration Only)

Create new Site entities

- Delete Site entities

- View all Site revisions

- View published Site entities

- View unpublished Site entities

------------------

For real admin stuff you need this permission

- list site entity entities

## Notes

IMPORTANT: Setting the region

URL: /admin/config/regional/settings

REQUIREMENTS

------------

IMPORTANT: JSON:API need CRUD Permissions

URL: admin/config/services/jsonapi

First of, all the modules on which it depends might be installed:

- Country - https://www.drupal.org/project/country

- Languagefield - https://www.drupal.org/project/languagefield

IMPORTANT: If you are on a monolingual site, please use the "default_href_lang_exchange".

The setting is under

admin/config/search/simplesitemap/variants. The following must be entered in the text field:

```

  default | default_href_lang_exchange | default

composer require 'drupal/languagefield:^1.8' composer require 'drupal/country:^1.0'

```

IMPORTANT: The following patch is required to edit the languagefield:

https://www.drupal.org/files/issues/2019-12-12/3100546-options.patch

## External Dependencies

The module collection has the following dependencies that need to be added in the composer.json so or more specifically:

If you are NOT using composer, you would need to download the modules under ```web/modules/contrib```

        "drupal/country": "*",

        "lasserafn/php-initial-avatar-generator": "^4.0",

        "drupal/languagefield": "*",

RECOMMENDED MODULES

-------------------

## Simple install :

No recommended modules.

The following extensions must be installed first

INSTALLATION

------------

composer require drupal/country:1.0.0-beta5 drupal/languagefield:1.5.0 lasserafn/php-initial-avatar-generator:4.1.1

The following modules and its dependencies might be activated under ```/admin/modules```:

Afterwards, the following modules must be activated under /admin/modules:

Install the modules like any other Drupal module.

The Href Lang Base

The Site Entity Base

The Site Entity Custom Logo Extension

The Site Entity Language & Country Extension

### href_lang_exchange

- dependencies:

    - field

    - jsonapi

On all pages, the write operations of jsonapi must be allowed.

/admin/config/services/jsonapi

### href_lang_exchange_lang_country_override

- dependencies:

  - field

  - href_lang_exchange

  - country

  - languagefield

Set on every site a default country.

/admin/config/regional/settings

### href_lang_exchange_custom_logos

- dependencies:

  - field

  - href_lang_exchange

  - country

  - languagefield

  - href_lang_exchange_country_override

  - href_lang_exchange_href

### href_lang_exchange_entity_manager

- dependencies:

    - field

    - jsonapi

    - href_lang_exchange

    - views

Then the elements must be connected with each other.

### href_lang_exchange_href

- dependencies:

    - field

    - href_lang_exchange

    - country

    - languagefield

The settings for the connection can you find under

### href_lang_exchange_import_export

- dependencies:

  - href_lang_exchange

  - href_lang_exchange_entity_manager

  - href_lang_exchange_href

Structure -> Sites list -> Settings

CONFIGURATION

-------------

Here the url of the master must be entered e.g. https://master.bi.

This must be done on the master side as well as on the slave sides.

Once every required module has been installed, you would need to follow the next steps in order to configure the module:

In addition a password must be entered with which you can be authenticated.

(Must be the same on all pages)

This configuration would simulate a scenario with three sites, Master site (UK site) and two slaves (DE site and US site). The configuration needs to be done on each environment.

After that there are the options to queue the process. If these are not active, the system

1. Go to Configuration > Web services > JSON:API (/admin/config/services/jsonapi) and configure it to "Accept all JSON:API create, read, update, and delete operations".

2. Go to Configuration > Regional and language > Regional settings (/admin/config/regional/settings) and set the default country for each site.

3. Go to Structure > Site list > Settings (/admin/structure/site_entity/basic_settings) and configure the API endpoint url with the Master site url and an authentication key (it might be the same for each site), after that there are the options to queue the process. If these are not active, the system

   execute it directly which can cause performance problems with larger constructions.

4. Go to Structure > Site list (/admin/structure/site_entity) and add each site (UK, DE and US). The sites might be connected with each other.

(It runs something like this: a slave creates a new element and sends it to the master (does not save it itself).

 The master then distributes it to all slaves (including the base)

|Slave 1| -> |Master| -> |[Slave 1, Slave 2]|

On the Master Site must be under

Structure -> Sites list

USAGE (Example of simple scenario)

----------------------------------

All slaves are entered (the master can also act as slave).

Once the sites have been configured, everything is ready to start to use the functionality provided for the modules.

1. You would need to add field of type 'Href lang exchange item' to the entity where would you like to use it.

2. Once you create an entity using the 'href lang exchange item' field on any of the slave sites, this will be automatically reflected on the master site.

3. To check it, on the Master site go to  Structure > Href lang item List (/admin/structure/href_lang_item/list).

4. Finally, to have the option to switch between the different entities which are using the functionality, go to Structure > Block layout (/admin/structure/block) and place the href lang item language switcher to the section where would you like to show it.

After that everything is ready to send.

NOTES

-----

Afterwards a field of type "href lang exchange item" must be added to the entity/node.

Now simply create a content and you can connect it by the href lang.

#####Optional

If you want a group instead of the flags, you have to make a field form visible in the master :

/admin/structure/site_entity/settings

The short title needs to be visible. Afterwards under

IMPORTANT: If you are on a monolingual site, please use the "default_href_lang_exchange".

Structure -> Sites list

The setting is under ```admin/config/search/simplesitemap/variants``` 

Add the shortname.

The following might be entered in the text field:

```

  default | default_href_lang_exchange | default

```

MAINTAINERS

-----------

(For this, the options module should be activated, since it has a

 hidden dependency on the country module).

Current maintainers:

- David Galeano (gxleano) - https://www.drupal.org/u/gxleano

- Alvaro Hurtado (alvar0hurtad0) - https://www.drupal.org/u/alvar0hurtad0

- Alexander Dross (alexanderdross) - https://www.drupal.org/u/alexanderdross

- Shibin Das (D34dMan) - https://www.drupal.org/u/d34dman

- Volkan Jacobsen (muschpusch) - https://www.drupal.org/u/muschpusch

- Stephan Huber (stmh) - https://www.drupal.org/u/stmh