david/therinaldos.com
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

migrate therinaldos.com data
Build & Deploy to DigitalOcean Space / build (push) Failing after 2m38s
Details

Browse Source
This commit is contained in:
david
2024-05-05 15:50:45 -04:00
commit ef1ff240d4
23182 changed files with 3801898 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files
wedding-pics/apps/activity/docs/create.md
+38
View File
@@ -0,0 +1,38 @@
# Creating a new event
To create and publish an event to the activity app, a new `IEvent` should be fetched from the activity manager and afterwards be passed to the `publish()` method:
```php
// The activity manager should be automatically injected
// by the type hint OCP\Activity\IManager, when inside a class.
// When you have a plain file without a class, you can use
// \OC::$server->getActivityManager() instead.
$event = $this->activityManager->generateEvent();
...
$this->activityManager->publish($event);
```
The following values **must** be set before publishing an event:
* `setApp()`
* `setType()` - this must match an `\OCP\Activity\ISetting::getIdentifier()`
* `setAffectedUser()`
* `setSubject()`
* `setObject()`
Additionally these values **can** be set:
* `setAuthor()` - if no author is set, the current user will be used
* `setTimestamp()` - if no time is set, the current time will be used
* `setMessage()`
* `setLink()` - should be done in `IProvider::parse()`
* `setIcon()` - should be done in `IProvider::parse()`
The following values **should not** be set on publishing (are not saved), instead they should be set in `IProvider::parse()`:
* `setParsedSubject()`
* `setRichSubject()`
* `setParsedMessage()`
* `setRichMessage()`
* `setChildEvent()`
wedding-pics/apps/activity/docs/endpoint-v2.md
+163
View File
@@ -0,0 +1,163 @@
# Endpoint documentation
## Capabilities
```xml
GET /ocs/v2.php/cloud/capabilities
...
<activity>
<apiv2>
<element>filters</element>
<element>previews</element>
<element>rich-strings</element>
</apiv2>
</activity>
...
```
## Request URL
```
GET /ocs/v2.php/apps/activity/api/v2/activity
```
With type filter
```
GET /ocs/v2.php/apps/activity/api/v2/activity/{filter}
```
Supported type filters can be obtained from:
```
GET /ocs/v2.php/apps/activity/api/v2/activity/filters
```
Additionally, filtering based on `object_type` and `object_id` (see below) is only valid when supplying `filter` as the type filter. Filtering results based on `object_type` and `object_id` parameters is not supported when using any other type filter.
## Parameters
Name | Type | Description
---- | ---- | -----------
`since` | int (Optional) | The integer ID of the last activity that you’ve seen.
`limit` | int (Optional) | How many activities should be returned (Default: `50`)
`object_type` | string (Optional) | Allows to filter the activities to a given object. May only appear together with `object_id` and the `filter` type filter
`object_id` | string (Optional) | Allows to filter the activities to a given object. May only appear together with `object_type` and the `filter` type filter
`sort` | string - `asc` or `desc` | Should activities be given ascending or descending (from the `since`) (Default: `desc`)
## HTTP Status
Status Code | Description
----------- | -----------
`200 OK` | Activities
`204 No Content` | The user has selected no activities to be listed in the stream
`304 Not Modified` | ETag/If-None-Match are the same or the end of the activity list was reached
`403 Forbidden` | The offset activity belongs to a different user
`403 Forbidden` | The user is not logged in
`404 Not Found` | The filter is unknown
## Headers
### Link for the next request
Already includes all parameters
```
Link: <http(s)://localhost/ocs/v2.php/apps/activity/api/v2/activity/all?since=364>; rel="next"
```
### First known activity
In case the `since` parameter was not known, the header gives the first known activity ID
```
X-Activity-First-Known: 370
```
### Last given activity
Id that should be used as `since` parameter for the next request
```
X-Activity-Last-Given: 370
```
## Activity element
Field name | Type | Value description
---------- | ---- | -----------------
`activity_id` | int | Autoincrement value from the database
`datetime` | string | ISO 8601 date of the activity (e.g. `2015-11-20T12:49:31+00:00`)
`app` | string | App that created the activity (e.g. `'files'`, `'files_sharing'`, etc.)
`type` | string | For most files related activities this is the action that was performed on the file/folder (e.g. `'file_changed'`, `'file_created'` (same is used for both, file and folder)), other apps use other strings (e.g. `'announcementcenter'`)
`user` | string (Optional) | User ID of the user that triggered/created this activity (can also be empty in case of public link/remote share action)
`subject` | string | Translated simple subject without markup, ready for use (e.g. `'You created hello.jpg'`)
`subject_rich` | array (Optional) | `0` is the string subject including placeholders, `1` is an array with the placeholders. See [this issue](https://github.com/nextcloud/server/issues/1706) for more information
`message` | string (Optional) | Translated simple message without markup, ready for use (longer text, unused by core apps)
`message_rich` | array (Optional) | See `subject_rich`
`icon` | string (Optional) | A full URL to an icon for the activity
`link` | string (Optional) | A full URL pointing to a suitable location (e.g. `'http://localhost/cloud/master/core/index.php/apps/files/?dir=%2Ffolder'` in case the folder got created)
`object_type` | string (Optional) | Type of the object this activity is about (e.g. `'files'` is used for files and folders)
`object_id` | int (Optional) | ID of the object this activity is about (e.g. ID in the file cache is used for files and folders)
`object_name` | string (Optional) | Name of the object this activity is about (e.g. for files it's the relative path to the user's root: `'/folder/.travis.yml'`)
`objects` | object (Optional) | In activities that reference multiple objects (e.g. an activity detailing several files edited in the same folder), this field holds the objects referenced in this activity. They are stored in `objects` as key-value pairs of the `object_id` and the `object_name`: `{ object_id: object_name}`
`previews` | array (Optional) | A list of potential previews (currently only available for file activities). See `Preview element` for more information
### Preview element
Field name | Type | Value description
---------- | ---- | -----------------
`source` | string | Full URL of the image to be displayed
`link` | string | Full URL the preview should be wrapped in
`mimeType` | string | The mime type of the file (not the preview)
`fileId` | int | The if of the actual file
`view` | string | The view where the file can be found (either `files` or `trashbin`)
`isMimeTypeIcon` | bool | True if `source` points to a mime type icon instead of a real preview
`filename` | string | The filename of the file the preview is for
In case the endpoint returns more fields, they should be ignored and are deprecated (only for backwards compatibility usage) or internal.
### Example
```json
{
"activity_id": 1,
"timestamp": 1446137950,
"app": "files",
"type": "file_created",
"user": "test1",
"affecteduser": "admin",
"subject": "test1 created hello.txt",
"subject_rich": {
"0": "test1 created {file1}",
"1": {
"file1": {
"type": "file",
"id": 23,
"name": "hello.txt",
"path": "\/test\/hello.txt"
}
}
},
"message": null,
"message_rich": {
"0": "",
"1": []
},
"icon": "https:\/\/localhost\/apps\/files\/img\/add-color.svg",
"link": "",
"object_type": "files",
"object_id": 23,
"object_name": "\/test\/hello.txt",
"previews": [
{
"link": "https:\/\/localhost\/index.php\/apps\/files\/?dir=\/test&scrollto=hello.txt",
"source": "https:\/\/localhost\/index.php\/core\/preview.png?file=\/hello.txt&x=150&y=150",
"mimeType": "text/plain",
"view": "files",
"fileId": 23,
"isMimeTypeIcon": false,
"filename": "hello.txt"
}
]
}
```
wedding-pics/apps/activity/docs/filter.md
+56
View File
@@ -0,0 +1,56 @@
# Adding a filter
In order to add a new filter to the sidebar and allow to restrict the activity stream, the `OCP\Activity\IFilter` interface needs to be implemented and registered in `appinfo/info.xml`. An example can be seen in the [comments app](https://github.com/nextcloud/server/blob/8105ba99297222b7db97b556a55f306c3f7cabc0/apps/comments/appinfo/info.xml#L22-L24)
```xml
<?xml version="1.0"?>
<info>
...
<activity>
...
<filters>
<filter>OCA\Comments\Activity\Filter</filter>
</filters>
</activity>
</info>
```
The `filter` value is the fully namespaced class name of the `IFilter` implementation.
## Identifier
The identifier is used in the URL and as a HTML ID, therefor only lowercase a-z and underscores are allowed.
## Name
The name **must** already be translated and in best case only consist of 1-3 short words. It is also the label which is used by the link in the filter list of the web UI.
## Icon
The icon **must** be an absolute URL. The chosen icon should be 32*32 pixels and when possible a SVG.
## Priority
Priority should technically be a value between 0-100, where 0 means it's listed first and 100 last. 70 should be seen as a decent default value, while values lower then 10 should not be used. These are reserved for special filters like the "All activies", "By you", "By others", etc.
## Filter apps
With the `allowedApps()` method specify a list of apps. Only activities which belong to one of the given apps are then returned by the filter. E.g. the [comments app](https://github.com/nextcloud/server/blob/8105ba99297222b7db97b556a55f306c3f7cabc0/apps/comments/lib/Activity/Filter.php#L88-L88) only returns `return ['comments'];` here.
To return events of all apps, an empty array should be returned.
## Filter types
With the `filterTypes()` method the list of activities can be limited even more. This is used for example in the [dav app](https://github.com/nextcloud/server/blob/253a75e5aef409ca5ac412f3d8d3ccd06a9f4a86/apps/dav/lib/CalDAV/Activity/Filter/Todo.php#L82-L82) to have a filter where only the todo/task events are shown:
```php
return array_intersect(['calendar_todo'], $types);
```
Calendar/event related activities are also part of the dav app, but are handled in a second filter.
The types this method deals with are the identifiers of the `OCP\Activity\ISetting` implementations.
If no restriction is to be performed, the parameter should be returned directly:
```php
return $types;
```
wedding-pics/apps/activity/docs/provider.md
+113
View File
@@ -0,0 +1,113 @@
# Adding a provider
Providers are used to parse, translate and beautify activities. They need to implement the `OCP\Activity\IProvider` interface and are registered in `appinfo/info.xml`. An example can be seen in the [files app](https://github.com/nextcloud/server/blob/8baf986d3bf6efb4d81fb18eac07592932467b8e/apps/files/appinfo/info.xml#L35-L38)
```xml
<?xml version="1.0"?>
<info>
...
<activity>
...
<providers>
...
<provider>OCA\Files\Activity\FavoriteProvider</provider>
</providers>
</activity>
</info>
```
The `provider` value is the fully namespaced class name of the `IProvider` implementation.
## Parse
The provider interface only contains one single `parse()` method. But it makes sense to split the logic up into multiple methods and the [favorite provider](https://github.com/nextcloud/server/blob/8baf986d3bf6efb4d81fb18eac07592932467b8e/apps/files/lib/Activity/FavoriteProvider.php) can serve as a good example for that. So the methods of this class will be explained here as an example.
As a quick summary, when the given event is known by the provider, the following method **must** be called:
* `setParsedSubject()`: Translated simple subject without markup, ready for use (e.g. `'You added hello.jpg to your favorites'`)
Additionally the following methods *should* be called, in order to beautify the activity:
* `setIcon()`: A full URL to an icon for the activity, e.g. `$this->url->getAbsoluteURL($this->url->imagePath('core', 'actions/starred.svg'))`
* `setRichSubject()`: String subject including placeholders and the array of placeholders. See [this issue](https://github.com/nextcloud/server/issues/1706) for more information. Available object types are bound to the server version and can be found in the [`OCP\RichObjectStrings\Definitions`](https://github.com/nextcloud/server/blob/01f4c7550538a30311597d4eb9b889fbb04c4d67/lib/public/RichObjectStrings/Definitions.php) class. Note that starting with Nextcloud 26, you do not need to call `setParsedSubject` if you call `setRichSubject`, a parsed version will be computed automatically.
### Check responsibility
The first thing the provider should do, is to check whether the `IEvent` is one it cares about. A simple check for the app and maybe additionally the type, if the app has more then one provider, should be enough:
```php
if ($event->getApp() !== 'files' || $event->getType() !== 'favorite') {
throw new \InvalidArgumentException();
}
```
Whenever a provider throws an `\InvalidArgumentException` the activity app will continue and pass the event to the next provider, so this should always be thrown when the event is unknown.
### Short translation
All file related activities are available with a short version e.g. "Added to favorites" (shown in the sidebar of the filelist) and a long version e.g. "You added hello.jpg to your favorites" (shown in the stream and mails). Whether or not it is applicable to use a short version can be checked via [`OCP\Activity\Manager::isFormattingFilteredObject()`](https://github.com/nextcloud/server/blob/8baf986d3bf6efb4d81fb18eac07592932467b8e/apps/files/lib/Activity/FavoriteProvider.php#L80-L80).
This allows to skip the file name in the sidebar, since it would just be repeated all the time while adding no value to the stream.
The favorite provider makes use of this and the activities don't have additional placeholders, so only the parsed subject is set.
### Long translations with "rich object" string
In the long version for the normal activity stream contains the filename. Objects like users, files and more can be highlighted in the "rich subject", which allows the app to show an avatar next to the name, link the file name to the file list and many more things.
The `IEvent::setRichSubject()` method has two arguments:
1. The already translated string with placeholders
2. The list of placeholders, in the case of the favorite provider it's the file that was marked as a favorite
```php
$event->setRichSubject(
$this->l->t('You added {file} to your favorites')
['file' => [
'type' => 'file',
'id' => $event->getObjectId(),
'name' => basename($event->getObjectName()),
'path' => $event->getObjectName(),
]]
);
```
The list of required keys for each object can be found in the [`OCP\RichObjectStrings\Definitions`](https://github.com/nextcloud/server/blob/01f4c7550538a30311597d4eb9b889fbb04c4d67/lib/public/RichObjectStrings/Definitions.php) class.
### Merging activities
It is also possible to merge activities. E.g. when a user favorites two files, those can be combined to the following:
```php
$event->setRichSubject(
$this->l->t('You added {file1} and {file2} to your favorites')
[
'file1' => [
'type' => 'file',
'id' => 23,
'name' => 'file1.txt',
'path' => 'path1/to1/file1.txt',
],
'file1' => [
'type' => 'file',
'id' => 42,
'name' => 'file2.txt',
'path' => 'path2/to2/file2.txt',
],
]
);
```
Merging two events is fairly easy. Afterwards the child needs to be set, to avoid the previous event from showing up in the stream additionally `$event->setChildEvent($previousEvent)`.
But this should not be done manually! Instead dependency injection should be used to get `OCP\Activity\IEventMerger`. This helper automatically merges events, when the following requirements are met:
* Both events need to have the same `getApp()`
* Both events must not have a message `getMessage()`
* Both events need to have the same subject `getSubject()`
* Both events need to have the same object type `getObjectType()`
* The time difference between both events must not be bigger then 3 hours
* Only up to 5 events can be merged.
* All parameters apart from such starting with `$mergeParameter` must be the same for both events.
Activities should also **not be merged manually** if those requirements are not met.
wedding-pics/apps/activity/docs/setting.md
+46
View File
@@ -0,0 +1,46 @@
# Adding a setting
*Note:* settings are what types used to be in the old `OCP\Activity\IExtension` interface.
In order to add a new setting to the personal page and make it possible to store events with this type, the `OCP\Activity\ISetting` interface needs to be implemented and registered in `appinfo/info.xml`. An example can be seen in the [comments app](https://github.com/nextcloud/server/blob/8105ba99297222b7db97b556a55f306c3f7cabc0/apps/comments/appinfo/info.xml#L18-L20)
```xml
<?xml version="1.0"?>
<info>
...
<activity>
...
<settings>
<setting>OCA\Comments\Activity\Setting</setting>
</settings>
</activity>
</info>
```
The `setting` value is the fully namespaced class name of the `ISetting` implementation.
## Identifier
The identifier is also used as a HTML ID, therefor only lowercase a-z and underscores are allowed.
**Note:** This must also match the value that is used in the `IEvent::setType()` of the event, otherwise the event will not be visible.
## Name
The name **must** already be translated and should be a short and descriptive sentence. One or two important words can also be highlighted using the `<strong>` HTML tag, to allow easier recognition of the setting.
## Icon
The icon **must** be an absolute URL. The chosen icon should be 32*32 pixels and when possible a SVG.
## Priority
Priority should technically be a value between 0-100, where 0 means it's listed first and 100 last. 70 should be seen as a decent default value, while values lower then 10 should not be used. These are reserved for special settings of the activity app itself.
## Is default enabled stream / mail
The two "is default enabled x" booleans specify whether the setting is enabled or disabled by default for the stream or mail. Once a user changed their setting, the default is not used for them anymore. Changing the default is therefore not "retro active".
## Can change stream / mail
When the "can change x" boolean is set to `false`, users can not change this setting on the personal page. When both "can change x" booleans are false, the setting is not listed on the personal page at all.