From fb7259238a1f9ba6df3e152f588797291b8071a2 Mon Sep 17 00:00:00 2001 From: Christian Wolf Date: Fri, 22 Sep 2023 17:45:08 +0200 Subject: [PATCH] Adding comments and restructuring documentation The goal is to have the code blocks at the end of each (sub-) section. Signed-off-by: Christian Wolf --- .../groupware/calendar_provider.rst | 252 ++++++++++++------ 1 file changed, 169 insertions(+), 83 deletions(-) diff --git a/developer_manual/digging_deeper/groupware/calendar_provider.rst b/developer_manual/digging_deeper/groupware/calendar_provider.rst index bca6e4941..723c2b09d 100644 --- a/developer_manual/digging_deeper/groupware/calendar_provider.rst +++ b/developer_manual/digging_deeper/groupware/calendar_provider.rst @@ -63,6 +63,12 @@ Basic event information -- INode There are some basic methods that need to be implemented on each calendar object instance. These are defined ``\Sabre\DAV\INode``. + +Removal of entries +!!!!!!!!!!!!!!!!!! + +Removal of calendar events is not allowed in this example. Otherwise, the backend needs to be updated. + .. code-block:: php name; } -The name of the event can be obtained using the ``getName`` method. Here, the saved name in the attributes is just returned. +Updating the name of an event +!!!!!!!!!!!!!!!!!!!!!!!!!!!!! + +Updating the name is not considered a good idea, thus it will be cancelled by a Exception. One could also update the backend if this should be possible. .. code-block:: php @@ -91,7 +103,12 @@ The name of the event can be obtained using the ``getName`` method. Here, the sa throw new \Sabre\DAV\Exception\Forbidden('This calendar-object is read-only'); } -Updating the name is not considered a good idea, thus it will be cancelled by a Exception. One could also update the backend if this should be possible. +Getting the last modification time stamp +!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! + +The method ``getLastModified`` must return a unix timestamp that represents the modification date of the event. This can be used by the client to selectively update whatever structure. + +Returning ``null`` is allowed to indicate that no modification time stamp can be obtained. .. code-block:: php @@ -101,15 +118,17 @@ Updating the name is not considered a good idea, thus it will be cancelled by a return time(); } -The method ``getLastModified`` must return a unix timestamp that represents the modified date. This can be used by the client to selectively update whatever structure. - -Returning ``null`` is allowed to indicate that no modification time stamp can be obtained. Event data -- IFile ~~~~~~~~~~~~~~~~~~~ The main data of a calendar object is stored in the ``\Sabre\DAV\IFile`` interface. There are a few additional methods that help during the usage. +Content size of the event +!!!!!!!!!!!!!!!!!!!!!!!!! + +One helper function is the ``getSize`` method to get the number of bytes that represent this calendar entry's representation. Nothing fancy is done in this method. + .. code-block:: php get()); } -One helper function is the ``getSize`` method to get the number of bytes that represent this calendar entry's representation. Nothing fancy is done in this method. - -.. code-block:: php - - get()) . '"'; - } +Get a unique tag for one event version +!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! The calculation of an E-Tag can be calculated using the ``getETag`` method. Note, that the returned E-Tag must have the double quotes as part of the returned string. One can also return ``null`` to indicate that the E-Tag cannot be calculated effectively. +.. code-block:: php + + get()) . '"'; + } + +.. _calendar-provider-content-type: + +Returning the content type +!!!!!!!!!!!!!!!!!!!!!!!!!! + +The content type of the calendar entry must be provided as well. + .. code-block:: php ` declared. See the `official documentation `_ on vcal calendars on the possible format as well. .. code-block:: php @@ -163,7 +193,12 @@ The content type of the calendar entry must be provided as well. EOF; } -The actual calendar entry can be obtained by the ``get`` method. This must for sure match the content type above. See the `official documentation `_ on vcal calendars on the possible format as well. +Updating the content of a calendar event +!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! + +It is possible that the client tries to update the event with the ``put`` method. + +In this example, we consider the event read-only, so we throw an exception if a client tries to update it. If you are planning to allow clients to update events, you need to implement the parsing, validation and saving of data. .. code-block:: php @@ -173,15 +208,18 @@ The actual calendar entry can be obtained by the ``get`` method. This must for s throw new \Sabre\DAV\Exception\Forbidden('This calendar-object is read-only'); } -It is possible that the client tries to update the event with the ``put`` method. - -In this example, we consider the event read- only, so we throw an exception if a client tries to update it. If you are planning to allow clients to update events, you need to implement the parsing, validation and saving of data. - Access restrictions -- IACL ~~~~~~~~~~~~~~~~~~~~~~~~~~~ The calendar entities are completed by a set of access rules. These allow a client to know if certain actions are to be allowed or not. +Ownership +!!!!!!!!! + +The owner and corresponding groups of the calendar entry can be specified as uris. If no owner or group is present, a ``null`` value should be returned. + +As typically the calendar belongs to a user and the individual entries to the calendar, the entries do not need a dedicated user set in our example. For more complex approaches see the official documentation of CalDAV. + .. code-block:: php calendar->getACL(); } -The real access rules can be obtained by ``getACL``. In this example, we assume that the ACLs are inherited from the calendar. Thus, we delegate the calculation to the calendar class. +Updating the calendar ACLs +!!!!!!!!!!!!!!!!!!!!!!!!!! + +Updating the ACLs could be handled with the ``setACL`` method. This example assumes constant ACLs, so it will be rejected with an exception been thrown. .. code-block:: php @@ -228,13 +273,16 @@ The real access rules can be obtained by ``getACL``. In this example, we assume throw new \Sabre\DAV\Exception\Forbidden('Setting ACL is not supported on this node'); } -Updating the ACLs could be handled with the ``setACL`` method. This example assumes constant ACLs, so it will be rejected with an exception been thrown. - The calendar class ------------------ A single calendar needs to be represented as its own class. As with the calendar entity class, you can choose any name for your class. Extend the ``OCA\DAV\CalDAV\Integration\ExternalCalendar`` class: +The basic constructor for the class and some attributes that are stored is shown below. We store some provided uris internally for later use. + +The parent constructor needs the name of the app as the first parameter. It is thus called explicitly in the first line of the constructor with the correct app name (``yourappname`` in this example). + +Some of the methods that need to be implemented are similar to the ones above for the calendar entity class. However, there are different implementations required, so all methods are revisited once in the next paragraphs. .. code-block:: php @@ -268,17 +316,18 @@ A single calendar needs to be represented as its own class. As with the calendar // The other methods come here ... } -This is the basic constructor for the class and some attributes that are stored. We store some provided uris internally for later use. -The parent constructor needs the name of the app as the first parameter. It is thus called explicitly in the first line of the constructor with the correct app name (``yourappname`` in this example). - -Some of the methods that need to be implemented are similar to the ones above for the calendar entity class. However, there are different implementations required, so all methods are revisited once in the next paragraphs. Basic Calendar information -- INode ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ The interface ``\Sabre\DAV\INode`` has two methods that need to be implemented by the app's code. The other methods in the interface are already implemented in the ``\OCA\DAV\CalDAV\Integration\ExternalCalendar`` class. +Removal of calendars +!!!!!!!!!!!!!!!!!!!! + +The calendar should not be removed by means of the CalDAV interface. Thus, nothing is done here. + .. code-block:: php principalUri; } -Get the principal's uri. Here the stored value provided in the constructor is used. +Get groups of calendar +!!!!!!!!!!!!!!!!!!!!!! + +Return all groups uris of the user, there is the ``getGroups`` method. Here, no groups are assumed. .. code-block:: php @@ -402,8 +475,18 @@ Get the principal's uri. Here the stored value provided in the constructor is us return []; } -Return all groups uris of the user. Here, no groups are assumed. +Fetching the access rules of the calendar +!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! +The ACL defined for this calendar must be returned by the method ``getACL``. For the exact definitions, see the documentation of Sabre. At the time of writing this was: + +============= =============================== ===================================================== +entry values description +============= =============================== ===================================================== +``principal`` uri of principal The role or person trying to access the calendar +``privilege`` ``{DAV:}read``, ``{DAV:}write`` Is the role allowed to read or to write +``protected`` ``true``, ``false`` if ``true``, this rule is not allowed to change +============= =============================== ===================================================== .. code-block:: php @@ -429,15 +512,10 @@ Return all groups uris of the user. Here, no groups are assumed. ]; } -The ACL defined for this calendar are returned. For the exact definitions, see the documentation of Sabre. At the time of writing this was: +Setting the access rules of the calendar +!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! -============= =============================== ===================================================== -entry values description -============= =============================== ===================================================== -``principal`` uri of principal The role or person trying to access the calendar -``privilege`` ``{DAV:}read``, ``{DAV:}write`` Is the role allowed to read or to write -``protected`` ``true``, ``false`` if ``true``, this rule is not allowed to change -============= =============================== ===================================================== +In this example, no updates of the ACL rules are allowed. Thus, an exception is thrown if the client tries to do so using the method ``setACL``. .. code-block:: php @@ -447,7 +525,10 @@ entry values description throw new \Sabre\DAV\Exception\Forbidden('Setting ACL is not supported on this node'); } -In this example, no updates of the ACL rules are allowed. Thus, an exception is thrown if the client tries to do so. +Getting the privileges associated with the calendar +!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! + +The supported privileges can be overwritten by implementing the method ``getSupportedPrivileges``. When returning ``null``, the Sabre default is used which is fine for many tasks. Please also take a look at the [Sabre Documentation](https://sabre.io/dav/acl/) for more information. .. code-block:: php @@ -457,13 +538,19 @@ In this example, no updates of the ACL rules are allowed. Thus, an exception is return null; } -The supported privileges can be overwritten by implementing this method. When returning ``null``, the Sabre default is used which is fine for many tasks. Please also take a look at the [Sabre Documentation](https://sabre.io/dav/acl/) for more information. Properties of the external calendar -- IProperties ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ You will be able to specify some calendar properties. The CalDAV interface allows for a rather generic interface. You will have to check the details of the CalDAV standard on what properties make sense for you. +Getting the properties +!!!!!!!!!!!!!!!!!!!!!! + +The properties are fetched with the method ``getProperties``. + +Here a basic stub of calendar properties are provided. It is a basic name, a color and the setting to allow both events (``VEVENT``) and tasks (``VTODO``) in the calendar. + .. code-block:: php -With all these steps done, you should be able to see the calender(s) in the calendar app and the CalDAV interface of the core. - Appendix: Registering the calendar with the PHP API interface -------------------------------------------------------------