From 95e1a60bf6491ba32ebf6ad6e98f561ec9957cac Mon Sep 17 00:00:00 2001
From: Michael Lenahan <michael.lenahan@gmail.com>
Date: Wed, 12 Feb 2025 16:28:09 +0100
Subject: [PATCH 1/7] Review home page and concept index page
---
docs/eca/concepts/index.md | 67 +++++++++++++++++++++++++++++++++--
docs/index.md | 72 ++++++++++++++++++--------------------
2 files changed, 99 insertions(+), 40 deletions(-)
diff --git a/docs/eca/concepts/index.md b/docs/eca/concepts/index.md
index 81f11d37..19a40e09 100644
--- a/docs/eca/concepts/index.md
+++ b/docs/eca/concepts/index.md
@@ -1,6 +1,67 @@
---
-title: Concepts
+title: ECA concepts
---
-# Concepts
-In this section you'll find basic ECA concepts that are important to understand when building models.
+# Understanding ECA concepts
+
+ECA (Events - Conditions - Actions) models help you automate business processes in Drupal by responding to events that happen on your site. Think of ECA as a watchful assistant that can detect when something happens, check if certain conditions apply, and then take appropriate actions.
+
+## Core components
+
+### Events
+
+Events are triggers that start an ECA process. These could be things like:
+
+- A user logging in
+- Content being created or updated
+- A form being submitted
+- A scheduled time arriving
+- A custom event you define
+
+When an event occurs, ECA checks if any models are listening for that event and runs them if so.
+
+### Conditions
+
+Conditions are checks that determine whether actions should run. They act as filters or guards, ensuring actions only happen when appropriate. For example, you might want to:
+
+- Check if a user has a specific role
+- Verify content has certain field values
+- Ensure a threshold has been met
+- Compare dates or times
+- Combine multiple conditions with AND/OR logic
+
+### Actions
+
+Actions are the tasks ECA performs when an event occurs and conditions are met. Actions can:
+
+- Create or update content
+- Send notifications
+- Modify user accounts
+- Interact with external systems
+- Trigger other events
+- Perform custom operations
+
+## How components work together
+
+Let's look at a common example: sending a welcome email to new users in a specific role.
+
+1. **Event**: User account is created
+2. **Condition**: User has the "member" role
+3. **Action**: Send customized welcome email
+
+ECA processes this flow by:
+
+1. Detecting the account creation event
+2. Checking the user's roles
+3. Sending the email if the condition is met
+
+## Next steps
+
+Learn more about specific concepts:
+
+- [Working with custom events](custom_events.md)
+- [Understanding tokens](tokens.md)
+- [Using loops](loops.md)
+- [Managing permissions](permissions.md)
+
+For practical examples, visit our [model library](../../library/index.md).
diff --git a/docs/index.md b/docs/index.md
index d6df4836..80137073 100644
--- a/docs/index.md
+++ b/docs/index.md
@@ -3,59 +3,57 @@ title: Drupal ECA Documentation
---
# Welcome to Drupal ECA
-ECA stands for **Events - Conditions - Actions**.
+This document explains how to use the Events - Conditions - Actions (ECA) module for Drupal.
-It's a [Drupal](https://www.drupal.org) module and has its own [project page](https://www.drupal.org/project/eca). This
-**ECA Guide** is provided by the ECA maintainers, you can contact them on their user profile on drupal.org or in the
-[ECA Slack Channel](https://drupal.slack.com/archives/C0287U62CSG).
+## What is ECA?
-## The 5 sections of this guide
+ECA (Events - Conditions - Actions) is a Drupal module that processes business process models based on Drupal events. The module integrates with Drupal core components and provides plugin management for:
-### ECA
+* [Events](eca/concepts/index.md#events)
+* [Conditions](eca/concepts/index.md#conditions)
+* [Actions](eca/concepts/index.md#actions)
-[All about the ECA](/index.md) module, [how to install](eca/install.md) it, [important concepts](eca/concepts/index.md) to understand
-how ECA works and instructions on [how to extend ECA](eca/extend/index.md).
+!!! note
-Important building blocks of ECA are the plugins for events, conditions and actions. Those are contained in their own
-section for [plugins](#plugins)
+ ECA does not include a built-in user interface. Instead, it provides a modeller plugin manager that integrates with existing tools. If a modeller supports templates, ECA provides them for all plugins available on your Drupal site.
-The ECA module is the heart of the module suite. Whenever a Drupal event
-occurs, it processes any (business process) model defined for that event.
+## Contents
-ECA leverages existing components of Drupal core, i.e. events and actions,
-and provides its own plugin manager for conditions. Hence all 3 components
-(events, conditions, actions) are implemented as plugins and may be easily
-extended by other modules.
+* [Installation guide](eca/install.md)
+* [Key concepts](eca/concepts/index.md)
+* [Extension guide](eca/extend/index.md)
+* [Plugin documentation](plugins/index.md)
+* [Available modellers](modeller/index.md)
+* [Example models](library/index.md)
+* [Additional resources](#additional-resources)
-!!! attention
+## Additional resources
- The ECA module does not provide any user interface to define models. Instead,
- it provides a modeller plugin manager to easily integrate existing tools.
- If a modeller supports templates for events, conditions and actions,
- ECA will provide them for all the plugins that are available on a Drupal site.
+You can find articles, tutorials, videos and other learning materials in the Resources section.
-### Modellers
+## Get support
-[Modellers](modeller/index.md) are the UI for ECA. They are described in this chapter.
+Contact the ECA maintainers through:
-### Plugins
+* Their Drupal.org user profiles
+* The [ECA Slack channel](https://drupal.slack.com/archives/C0287U62CSG)
-Each event, each condition and each action is available as a [plugin](plugins/index.md). This chapter contains documentation
-for each of them and how they can be configured.
+## Contribute
-### Library
+We welcome contributions including:
-This is where you can find [example ECA models](library/index.md).
+* Bug reports and feature requests
+* Documentation improvements
+* Example models
+* Custom plugins
+* General feedback
-### Resources
+To contribute:
-Articles, blog posts, tutorials, videos and so much more - all learning resources in one place.
+1. Create an account on [ECA Guide GitLab](https://gitlab.lakedrops.com)
+2. Visit the [ECA Guide Project](https://gitlab.lakedrops.com/drupal/documentation/eca)
+3. Open an issue or create a merge request
-## How to contribute
+This documentation uses British English.
-Found a typo? Want to write some chapters for this guide? Have an example model you want to publish? Wrote your own ECA
-plugins? Or you just want to provide feedback? This is all very welcome. To do so, please create an account in the
-[ECA Guide GitLab](https://gitlab.lakedrops.com) and then go to the [ECA Guide Project](https://gitlab.lakedrops.com/drupal/documentation/eca)
-where you can either open an issue or fork the project and then create a merge request.
-
-We use British English in this guide.
+For more information about ECA, visit the [project page](https://www.drupal.org/project/eca).
--
GitLab
From a30f40545786836dc611dd4e408f4c236a840d95 Mon Sep 17 00:00:00 2001
From: Michael Lenahan <michael.lenahan@gmail.com>
Date: Wed, 12 Feb 2025 16:49:55 +0100
Subject: [PATCH 2/7] Fix link to library
---
docs/eca/concepts/index.md | 2 +-
1 file changed, 1 insertion(+), 1 deletion(-)
diff --git a/docs/eca/concepts/index.md b/docs/eca/concepts/index.md
index 19a40e09..36b747d1 100644
--- a/docs/eca/concepts/index.md
+++ b/docs/eca/concepts/index.md
@@ -64,4 +64,4 @@ Learn more about specific concepts:
- [Using loops](loops.md)
- [Managing permissions](permissions.md)
-For practical examples, visit our [model library](../../library/index.md).
+For practical examples, visit our [model library](/library).
--
GitLab
From 2e3c467a50c0783ad7a521535f9cb66fc088a12b Mon Sep 17 00:00:00 2001
From: Michael Lenahan <michael.lenahan@gmail.com>
Date: Wed, 12 Feb 2025 16:50:29 +0100
Subject: [PATCH 3/7] Update instructions on how to contribute to documentation
---
docs/index.md | 4 ++--
1 file changed, 2 insertions(+), 2 deletions(-)
diff --git a/docs/index.md b/docs/index.md
index 80137073..28422ee0 100644
--- a/docs/index.md
+++ b/docs/index.md
@@ -29,7 +29,7 @@ ECA (Events - Conditions - Actions) is a Drupal module that processes business p
## Additional resources
-You can find articles, tutorials, videos and other learning materials in the Resources section.
+You can find articles, tutorials, videos, and other learning materials in the Resources section.
## Get support
@@ -50,7 +50,7 @@ We welcome contributions including:
To contribute:
-1. Create an account on [ECA Guide GitLab](https://gitlab.lakedrops.com)
+1. Request an account on the [ECA Guide GitLab](https://gitlab.lakedrops.com). Contact the ECA maintainers on the [ECA Slack channel](https://drupal.slack.com/archives/C0287U62CSG), and provide an email address for the account.
2. Visit the [ECA Guide Project](https://gitlab.lakedrops.com/drupal/documentation/eca)
3. Open an issue or create a merge request
--
GitLab
From 1571cfe9ba61bb83e3892d318af617952f1d0bba Mon Sep 17 00:00:00 2001
From: jurgenhaas <juergen.haas@lakedrops.com>
Date: Thu, 13 Feb 2025 09:18:30 +0100
Subject: [PATCH 4/7] Ensure destination directory for MR deployments exists
---
.gitlab-ci.yml | 1 +
1 file changed, 1 insertion(+)
diff --git a/.gitlab-ci.yml b/.gitlab-ci.yml
index 72a18da9..29731beb 100644
--- a/.gitlab-ci.yml
+++ b/.gitlab-ci.yml
@@ -41,6 +41,7 @@ DeployMR:
variables:
GIT_STRATEGY: none
script:
+ - a -m file -a "dest=/var/www/docs/eca-mr/${CI_MERGE_REQUEST_SOURCE_BRANCH_NAME} state=directory" --limit=bsdevop1
- a -m synchronize -a "src=${PWD}/site/ dest=/var/www/docs/eca-mr/${CI_MERGE_REQUEST_SOURCE_BRANCH_NAME} delete=yes" --limit=bsdevop1
environment:
name: review/$CI_COMMIT_REF_SLUG
--
GitLab
From 32c0b8b7e293f1a4981113f8719d4a409e5fc90d Mon Sep 17 00:00:00 2001
From: Michael Lenahan <michael.lenahan@gmail.com>
Date: Thu, 13 Feb 2025 09:20:11 +0100
Subject: [PATCH 5/7] Set "next steps" order to be the same as in lhs nav
---
docs/eca/concepts/index.md | 4 ++--
1 file changed, 2 insertions(+), 2 deletions(-)
diff --git a/docs/eca/concepts/index.md b/docs/eca/concepts/index.md
index 36b747d1..37d12313 100644
--- a/docs/eca/concepts/index.md
+++ b/docs/eca/concepts/index.md
@@ -59,9 +59,9 @@ ECA processes this flow by:
Learn more about specific concepts:
-- [Working with custom events](custom_events.md)
+- [Managing permissions](permissions.md)
- [Understanding tokens](tokens.md)
- [Using loops](loops.md)
-- [Managing permissions](permissions.md)
+- [Working with custom events](custom_events.md)
For practical examples, visit our [model library](/library).
--
GitLab
From d65db0dcd1ac481a15646225b9c91bc80621761e Mon Sep 17 00:00:00 2001
From: jurgenhaas <juergen.haas@lakedrops.com>
Date: Thu, 13 Feb 2025 09:46:40 +0100
Subject: [PATCH 6/7] Remove gitlab CI file which is now defined in a protected
space
---
.gitlab-ci.yml | 71 --------------------------------------------------
1 file changed, 71 deletions(-)
delete mode 100644 .gitlab-ci.yml
diff --git a/.gitlab-ci.yml b/.gitlab-ci.yml
deleted file mode 100644
index 29731beb..00000000
--- a/.gitlab-ci.yml
+++ /dev/null
@@ -1,71 +0,0 @@
-stages:
- - build
- - deploy
-
-Build:
- stage: build
- tags:
- - default
- script:
- - export WORKDIR=$(php /usr/local/bin/volume.php | cut -d":" -f 1)/drupal/documentation/eca
- - echo "WorkDir is ${WORKDIR}"
- - docker-compose up -d
- - sleep 20
- - docker-compose exec -T --workdir=/mkdocs mkdocs mkdocs build
- - docker-compose down
- artifacts:
- name: build
- when: always
- paths:
- - site/
- only:
- - main
- - merge_requests
-
-Deploy:
- stage: deploy
- tags:
- - ansible
- variables:
- GIT_STRATEGY: none
- script:
- - a -m synchronize -a "src=${PWD}/site/ dest=/var/www/docs/eca delete=yes" --limit=bsdevop1
- cache: {}
- only:
- - main
-
-DeployMR:
- stage: deploy
- tags:
- - ansible
- variables:
- GIT_STRATEGY: none
- script:
- - a -m file -a "dest=/var/www/docs/eca-mr/${CI_MERGE_REQUEST_SOURCE_BRANCH_NAME} state=directory" --limit=bsdevop1
- - a -m synchronize -a "src=${PWD}/site/ dest=/var/www/docs/eca-mr/${CI_MERGE_REQUEST_SOURCE_BRANCH_NAME} delete=yes" --limit=bsdevop1
- environment:
- name: review/$CI_COMMIT_REF_SLUG
- url: https://ecaguide.org/MR/$CI_MERGE_REQUEST_SOURCE_BRANCH_NAME
- on_stop: CleanupDeployMR
- cache: {}
- only:
- - merge_requests
-
-CleanupDeployMR:
- stage: deploy
- tags:
- - ansible
- variables:
- GIT_STRATEGY: none
- script:
- - a -m file -a "path=/var/www/docs/eca-mr/${CI_MERGE_REQUEST_SOURCE_BRANCH_NAME} state=absent" --limit=bsdevop1
- environment:
- name: review/$CI_COMMIT_REF_SLUG
- action: stop
- cache: {}
- rules:
- - if: '$CI_MERGE_REQUEST_SOURCE_BRANCH_NAME == "develop"'
- when: never
- - if: '$CI_MERGE_REQUEST_ID || $CI_PIPELINE_SOURCE == "pipeline"|| $CI_PIPELINE_SOURCE == "trigger"'
- allow_failure: true
- when: manual
--
GitLab
From d4e3234263214ecf0b7e95812c310c88cf06cfef Mon Sep 17 00:00:00 2001
From: jurgenhaas <juergen.haas@lakedrops.com>
Date: Thu, 13 Feb 2025 08:57:30 +0000
Subject: [PATCH 7/7] Feature/eca set field value
---
.../plugins/eca_content/action/eca_set_field_value/method.md | 2 +-
1 file changed, 1 insertion(+), 1 deletion(-)
diff --git a/include/plugins/eca_content/action/eca_set_field_value/method.md b/include/plugins/eca_content/action/eca_set_field_value/method.md
index 7ab0cc3a..b1a967f4 100644
--- a/include/plugins/eca_content/action/eca_set_field_value/method.md
+++ b/include/plugins/eca_content/action/eca_set_field_value/method.md
@@ -8,4 +8,4 @@ Available options:
- **Prepend when not full yet**: If the field allows multiple values, the given value will be inserted as the first item, if the max. cardinality is not reached yet. Otherwise, this action will be skipped.
- **Prepend and drop first when full**: Same as above, but if the max cardinality has been reached, the first value will be removed and the new value inserted at the beginning to the list.
- **Prepend and drop last when full**: Same as above, but instead of dropping the first, this will drop the last item before inserting the new value at the beginning of the list.
-- **Remove value instead of adding it**: Remove the value from a multi-value field, if it's caontained in the list of existing items.
+- **Remove value instead of adding it**: Remove the value from a field, if it's contained in the list of existing items. If this removes the last remaining value of the field, then the field will be empty (for an example of this, see [this issue](https://www.drupal.org/project/eca/issues/3504388)).
--
GitLab