diff --git a/Documentation/00_Index.md b/Documentation/00_Index.md new file mode 100644 index 0000000..46ae39c --- /dev/null +++ b/Documentation/00_Index.md @@ -0,0 +1,3 @@ +1. [User Interface](./Documentation/01_UserInterface.md) +2. [Building Blocks: Objects, Agents and Tasks](./Documentation/02_BuildingBlocks.md) +2. [Writing Custom Tasks](./Documentation/03_CustomTasks.md) diff --git a/Documentation/01_UserInterface.md b/Documentation/01_UserInterface.md new file mode 100644 index 0000000..daae443 --- /dev/null +++ b/Documentation/01_UserInterface.md @@ -0,0 +1,58 @@ +
+ Index +    |    + 2. Building Blocks > +
+ +--- + +# 1. The User Interface + +Bitzer comes with several user interface components: +1. Mixin node types to assign agents or intervals for automatic task creation +2. The task reminder overlay on login into the backend +3. The task overview module for editors to keep track of their work +4. The task management module for administrators to manage task lifecycles + +> Hint: Additionally, there is a command controller available for task handling. +> See ./flow help | grep bitzer + +## Scheduling tasks + +> Hint: For concrete examples, please see https://github.com/sitegeist/bitzer-review + +The default way of scheduling tasks is to configure a node type to use one of Bitzer's mixins. +This way, individual nodes can be assigned to agents to perform tasks like review or translation +in a certain interval. + +![Screenshot of Inspector Editor](inspector.png) + +Which tasks are to be scheduled is up to the concrete task implementations that Bitzer itself is the framework for. + +## The Task Reminder + +Upon login to the Neos backend, if there are scheduled tasks for the current user (as actor), +an overlay is displayed that shows the open tasks and links to the task management module. + +![Screenshot of task reminder](screenshot.png) + +The most important function of PresentationObjects is to enforce the interface between domain and presentation layer. + +For a single component that interface is represented by an actual PHP interface. So let's start with that: + +## The Task Management Module + +All tasks to be performed are listed in the task management module. +Here they can either be started or marked as complete. What happens when starting a task +is up to the concrete task's implementation. A review task might just open the node for review +while a translate task might create a variant of the node and display it. + +![Screenshot of task management module](module.png) + +--- + +
+ Index +    |    + 2. Building Blocks > +
diff --git a/Documentation/02_BuildingBlocks.md b/Documentation/02_BuildingBlocks.md new file mode 100644 index 0000000..b21b179 --- /dev/null +++ b/Documentation/02_BuildingBlocks.md @@ -0,0 +1,67 @@ +
+< 1. User Interface +    |    + Index +    |    + 2. Writing custom tasks > +
+ +--- + +# 2. Building Blocks + +The Bitzer building blocks are modeled using schema.org. The main entities are +* Object (refers to a content repository node by its address) +* Agent (can be a user or user group) +* Task (https://schema.org/ScheduleAction) + +## Object + +Objects refer to nodes in the content repository, or rather their addresses to be precise. +The node address concept is borrowed from the new event-sourced content repository +and enables Bitzer to address nodes that do not yet exist. +For example, a translation task can refer to creating a node variant that is still to be created via translation. +> Hint: For custom development purposes, there is an object repository available. + +## Agent + +Agents can be all of Neos' backend users having Bitzer's agent role, as well as all roles that extend it. +Thus, tasks can be assigned to a single user or a user group. +> Hint: A data source for agents is available and used in the Setting.Agent mixin node type. +> For custom development purposes, there is also an agent repository available. + +## Task + +Each task can be described by its properties: +* it is scheduled for a certain **scheduledTime** +* it has a certain **status**, e.g. active or completed (see https://schema.org/ActionStatusType) +* it is to performed by a certain **agent** +* it is about a certain **object**, in our case a node address +* it has a **target** URI, which directs the agent to their user interface to perform the task + +Additionally, tasks have metadata: +* a font awesome icon as an **image** +* a **description** +* arbitrary **properties** that might be relevant to the concrete task implementations + +> Hint: For custom development purposes, there is a task repository named "Schedule" available. + +Tasks themselves also have a lifecycle. They can be +* initially scheduled +* rescheduled to a different date +* reassigned to a different agent +* activated by an agent +* completed by an agent +* cancelled + +These actions are modelled as commands that are handed over to Bitzer, the central application service. + +--- + +
+< 1. User Interface +    |    + Index +    |    + 2. Writing custom tasks > +
diff --git a/Documentation/03_CustomTasks.md b/Documentation/03_CustomTasks.md new file mode 100644 index 0000000..9f20cec --- /dev/null +++ b/Documentation/03_CustomTasks.md @@ -0,0 +1,60 @@ +
+ < 2. Building Blocks > + | + Index +
+ +--- + +# 3. Custom Tasks + +While some generic tasks like review or translation will be provided by Bitzer's own plugin packages, +it is designed to allow for arbitrary tasks to be handled. There are a few steps to be taken for creating custom tasks. + +> Hint: To see custom tasks in action, please refer to https://github.com/sitegeist/bitzer-review + +## The task interface + +Each task must implement the provided `Sitegeist\Bitzer\Domain\Task\TaskInterface`. +While most properties are just members passed on by the schedule, some are useful for customization. +* getShortType should return a unique short name for the task +* getImage should return a font awesome icon name that can be used by the Neos UI +* getDescription can return a custom description, e.g. using the task's the properties array +* getTarget should return the custom URI of the location the agent can perform the task + +## The task factories + +Each type of task can define its own factory. Those must implement `Sitegeist\Bitzer\Domain\Task\TaskFactoryInterface` and must be registered via config: +```yaml +Sitegeist: + Bitzer: + factories: + 'Acme\Package\Domain\Task\MyTask\MyTask': 'Acme\Package\Domain\Task\MyTask\MyTaskFactory' +``` +If no custom factory is required, Bitzer's `GenericTaskFactory` is used. + +## Handling tasks + +The life cycle of custom tasks is to be implemented by the respective package. +Bitzer provides the same-named application service, repositories for tasks, objects and agents +and the signal `taskActionStatusUpdated` emitted by the `Schedule`. +What system events trigger automatic task generation is up to the specific use case. +For manually managing tasks there is a backend module available as well as a command controller. + +## Testing + +Bitzer provides feature traits for Flow's behavioral test framework based on Behat. +They can be used to +* create and simulate testing agents +* create testing objects +* perform commands on tasks + +to enable custom implementations with ample testing capabilities + +--- + +
+ < 2. Building Blocks > + | + Index +
diff --git a/Documentation/inspector.png b/Documentation/inspector.png new file mode 100644 index 0000000..40a8e3b Binary files /dev/null and b/Documentation/inspector.png differ diff --git a/Documentation/module.png b/Documentation/module.png new file mode 100644 index 0000000..6e35ece Binary files /dev/null and b/Documentation/module.png differ diff --git a/Docs/screenshot.png b/Documentation/screenshot.png similarity index 100% rename from Docs/screenshot.png rename to Documentation/screenshot.png diff --git a/README.md b/README.md index 5e67459..a5a07d9 100644 --- a/README.md +++ b/README.md @@ -2,6 +2,27 @@ > A content lifecycle task manager for Neos CMS -![Screenshot of Task Reminder](./Docs/screenshot.png) +![Screenshot of Task Reminder](./Documentation/screenshot.png) -## Nothing to see here yet (except for the screenshot)! \ No newline at end of file +## The content life cycle + +From their initial creation until their final deletion, content repository nodes +pass different stages of maturity. A news article might be first published as an abstract +and then later on enriched with arbitrary media, then translated into a different language, +updated with references to other articles and so on. If these changes are to be implemented +in a planned way, we may model them as tasks. +Bitzer provides a task model, an overview for editors for tasks assigned to them +and an automation mechanism to generate new tasks, e.g. by defining a review date for a published news article. + + +## Installation + +``` +composer require sitegeist/bitzer +``` + +## Documentation + +1. [User Interface](./Documentation/01_UserInterface.md) +2. [Building Blocks: Objects, Agents and Tasks](./Documentation/02_BuildingBlocks.md) +2. [Writing Custom Tasks](./Documentation/03_CustomTasks.md)