diff options
author | yude <yudesleepy@gmail.com> | 2021-01-04 18:51:10 +0900 |
---|---|---|
committer | GitHub <noreply@github.com> | 2021-01-04 18:51:10 +0900 |
commit | e6754f2154a79abd8e5e64bd923f6984aa9ad44b (patch) | |
tree | f074119530bb59ef155938ea367f719f1e4b70f1 /doc/md/dev | |
parent | 5256b4287021342a9f8868967b2a77e481314331 (diff) | |
parent | ed4ee8f0297941ac83300389b7de6a293312d20e (diff) | |
download | Shaarli-e6754f2154a79abd8e5e64bd923f6984aa9ad44b.tar.gz Shaarli-e6754f2154a79abd8e5e64bd923f6984aa9ad44b.tar.zst Shaarli-e6754f2154a79abd8e5e64bd923f6984aa9ad44b.zip |
Merge pull request #2 from shaarli/master
Merge fork source
Diffstat (limited to 'doc/md/dev')
-rw-r--r-- | doc/md/dev/Development.md | 12 | ||||
-rw-r--r-- | doc/md/dev/Plugin-system.md | 25 | ||||
-rw-r--r-- | doc/md/dev/Release-Shaarli.md | 8 |
3 files changed, 40 insertions, 5 deletions
diff --git a/doc/md/dev/Development.md b/doc/md/dev/Development.md index 5c085e03..c42e8ffe 100644 --- a/doc/md/dev/Development.md +++ b/doc/md/dev/Development.md | |||
@@ -6,7 +6,7 @@ Please read [Contributing to Shaarli](https://github.com/shaarli/Shaarli/tree/ma | |||
6 | 6 | ||
7 | 7 | ||
8 | - [Unit tests](Unit-tests) | 8 | - [Unit tests](Unit-tests) |
9 | - Javascript linting - Shaarli uses [Airbnb JavaScript Style Guide](https://github.com/airbnb/javascript). | 9 | - Javascript linting - Shaarli uses [Airbnb JavaScript Style Guide](https://github.com/airbnb/javascript). |
10 | Run `make eslint` to check JS style. | 10 | Run `make eslint` to check JS style. |
11 | - [GnuPG signature](GnuPG-signature) for tags/releases | 11 | - [GnuPG signature](GnuPG-signature) for tags/releases |
12 | 12 | ||
@@ -51,12 +51,12 @@ PHP (managed through [`composer.json`](https://github.com/shaarli/Shaarli/blob/m | |||
51 | 51 | ||
52 | ## Link structure | 52 | ## Link structure |
53 | 53 | ||
54 | Every link available through the `LinkDB` object is represented as an array | 54 | Every link available through the `LinkDB` object is represented as an array |
55 | containing the following fields: | 55 | containing the following fields: |
56 | 56 | ||
57 | * `id` (integer): Unique identifier. | 57 | * `id` (integer): Unique identifier. |
58 | * `title` (string): Title of the link. | 58 | * `title` (string): Title of the link. |
59 | * `url` (string): URL of the link. Used for displayable links (without redirector, url encoding, etc.). | 59 | * `url` (string): URL of the link. Used for displayable links (without redirector, url encoding, etc.). |
60 | Can be absolute or relative for Notes. | 60 | Can be absolute or relative for Notes. |
61 | * `real_url` (string): Real destination URL, can be redirected, encoded, etc. | 61 | * `real_url` (string): Real destination URL, can be redirected, encoded, etc. |
62 | * `shorturl` (string): Permalink small hash. | 62 | * `shorturl` (string): Permalink small hash. |
@@ -66,7 +66,7 @@ containing the following fields: | |||
66 | * `thumbnail` (string|boolean): relative path of the thumbnail cache file, or false if there isn't any. | 66 | * `thumbnail` (string|boolean): relative path of the thumbnail cache file, or false if there isn't any. |
67 | * `created` (DateTime): link creation date time. | 67 | * `created` (DateTime): link creation date time. |
68 | * `updated` (DateTime): last modification date time. | 68 | * `updated` (DateTime): last modification date time. |
69 | 69 | ||
70 | Small hashes are used to make a link to an entry in Shaarli. They are unique: the date of the item (eg. `20110923_150523`) is hashed with CRC32, then converted to base64 and some characters are replaced. They are always 6 characters longs and use only `A-Z a-z 0-9 - _` and `@`. | 70 | Small hashes are used to make a link to an entry in Shaarli. They are unique: the date of the item (eg. `20110923_150523`) is hashed with CRC32, then converted to base64 and some characters are replaced. They are always 6 characters longs and use only `A-Z a-z 0-9 - _` and `@`. |
71 | 71 | ||
72 | 72 | ||
@@ -163,11 +163,13 @@ See [`.travis.yml`](https://github.com/shaarli/Shaarli/blob/master/.travis.yml). | |||
163 | 163 | ||
164 | ## Static analysis | 164 | ## Static analysis |
165 | 165 | ||
166 | Patches should try to stick to the [PHP Standard Recommendations](http://www.php-fig.org/psr/) (PSR), especially: | 166 | Patches should try to stick to the [PHP Standard Recommendations](http://www.php-fig.org/psr/) (PSR), and must follow: |
167 | 167 | ||
168 | - [PSR-1](http://www.php-fig.org/psr/psr-1/) - Basic Coding Standard | 168 | - [PSR-1](http://www.php-fig.org/psr/psr-1/) - Basic Coding Standard |
169 | - [PSR-2](http://www.php-fig.org/psr/psr-2/) - Coding Style Guide | 169 | - [PSR-2](http://www.php-fig.org/psr/psr-2/) - Coding Style Guide |
170 | - [PSR-12](http://www.php-fig.org/psr/psr-12/) - Extended Coding Style Guide | ||
170 | 171 | ||
172 | These are enforced on pull requests using our Continuous Integration tools. | ||
171 | 173 | ||
172 | **Work in progress:** Static analysis is currently being discussed here: in [#95 - Fix coding style (static analysis)](https://github.com/shaarli/Shaarli/issues/95), [#130 - Continuous Integration tools & features](https://github.com/shaarli/Shaarli/issues/130) | 174 | **Work in progress:** Static analysis is currently being discussed here: in [#95 - Fix coding style (static analysis)](https://github.com/shaarli/Shaarli/issues/95), [#130 - Continuous Integration tools & features](https://github.com/shaarli/Shaarli/issues/130) |
173 | 175 | ||
diff --git a/doc/md/dev/Plugin-system.md b/doc/md/dev/Plugin-system.md index f09fadc2..79654011 100644 --- a/doc/md/dev/Plugin-system.md +++ b/doc/md/dev/Plugin-system.md | |||
@@ -139,6 +139,31 @@ Each file contain two keys: | |||
139 | 139 | ||
140 | > Note: In PHP, `parse_ini_file()` seems to want strings to be between by quotes `"` in the ini file. | 140 | > Note: In PHP, `parse_ini_file()` seems to want strings to be between by quotes `"` in the ini file. |
141 | 141 | ||
142 | ### Register plugin's routes | ||
143 | |||
144 | Shaarli lets you register custom Slim routes for your plugin. | ||
145 | |||
146 | To register a route, the plugin must include a function called `function <plugin_name>_register_routes(): array`. | ||
147 | |||
148 | This method must return an array of routes, each entry must contain the following keys: | ||
149 | |||
150 | - `method`: HTTP method, `GET/POST/PUT/PATCH/DELETE` | ||
151 | - `route` (path): without prefix, e.g. `/up/{variable}` | ||
152 | It will be later prefixed by `/plugin/<plugin name>/`. | ||
153 | - `callable` string, function name or FQN class's method to execute, e.g. `demo_plugin_custom_controller`. | ||
154 | |||
155 | Callable functions or methods must have `Slim\Http\Request` and `Slim\Http\Response` parameters | ||
156 | and return a `Slim\Http\Response`. We recommend creating a dedicated class and extend either | ||
157 | `ShaarliVisitorController` or `ShaarliAdminController` to use helper functions they provide. | ||
158 | |||
159 | A dedicated plugin template is available for rendering content: `pluginscontent.html` using `content` placeholder. | ||
160 | |||
161 | > **Warning**: plugins are not able to use RainTPL template engine for their content due to technical restrictions. | ||
162 | > RainTPL does not allow to register multiple template folders, so all HTML rendering must be done within plugin | ||
163 | > custom controller. | ||
164 | |||
165 | Check out the `demo_plugin` for a live example: `GET <shaarli_url>/plugin/demo_plugin/custom`. | ||
166 | |||
142 | ### Understanding relative paths | 167 | ### Understanding relative paths |
143 | 168 | ||
144 | Because Shaarli is a self-hosted tool, an instance can either be installed at the root directory, or under a subfolder. | 169 | Because Shaarli is a self-hosted tool, an instance can either be installed at the root directory, or under a subfolder. |
diff --git a/doc/md/dev/Release-Shaarli.md b/doc/md/dev/Release-Shaarli.md index 2c772406..d79be9ce 100644 --- a/doc/md/dev/Release-Shaarli.md +++ b/doc/md/dev/Release-Shaarli.md | |||
@@ -64,6 +64,14 @@ git pull upstream master | |||
64 | 64 | ||
65 | # If releasing a new minor version, create a release branch | 65 | # If releasing a new minor version, create a release branch |
66 | $ git checkout -b v0.x | 66 | $ git checkout -b v0.x |
67 | # Otherwise just use the existing one | ||
68 | $ git checkout v0.x | ||
69 | |||
70 | # Get the latest changes | ||
71 | $ git merge master | ||
72 | |||
73 | # Check that everything went fine: | ||
74 | $ make test | ||
67 | 75 | ||
68 | # Bump shaarli_version.php from dev to 0.x.0, **without the v** | 76 | # Bump shaarli_version.php from dev to 0.x.0, **without the v** |
69 | $ vim shaarli_version.php | 77 | $ vim shaarli_version.php |