Skip to content

Ease code inclusion #3169

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
adriendupuis merged 10 commits into from
Apr 29, 2026
Merged

Ease code inclusion #3169

Show file tree
Hide file tree
Changes from 9 commits
Commits
Show all changes
10 commits
Select commit Hold shift + click to select a range
1e32544
main.py: Add include_code function
adriendupuis Apr 28, 2026
3f920d1
include_file VS include_code
adriendupuis Apr 28, 2026
fee654d
Remove include_file from converted example
adriendupuis Apr 28, 2026
3fa8a8a
image_twig_functions.md: include_code
adriendupuis Apr 28, 2026
8d54540
code_samples_usage.php: Update for include_code
adriendupuis Apr 28, 2026
934ddc4
search_api.md: Rearrange ellipsis for code_samples_usage.php test
adriendupuis Apr 28, 2026
980e3a6
code_samples_usage.php: handle named parameters
adriendupuis Apr 28, 2026
e16019a
code_samples_usage.php: handle remove_indent
adriendupuis Apr 28, 2026
bdad3cd
code_samples_usage.php: remove quotes around `glue` value
adriendupuis Apr 28, 2026
a9391ca
main.py: Docstrings
adriendupuis Apr 29, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
16 changes: 8 additions & 8 deletions docs/administration/recent_activity/recent_activity.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -83,7 +83,7 @@ In the following example, log groups that contain at least one creation of a Con
It uses the default `admin` user that has a [permission](#permission-and-security) to list everyone's entries.

```php hl_lines="34-38"
[[= include_file('code_samples/recent_activity/src/Command/MonitorRecentContentCreationCommand.php') =]]
[[= include_code('code_samples/recent_activity/src/Command/MonitorRecentContentCreationCommand.php') =]]
```

```console
Expand Down Expand Up @@ -143,7 +143,7 @@ In the following example, an event subscriber is subscribing to an event dispatc
This event has the information needed by a log entry (see details after the example).

```php
[[= include_file('code_samples/recent_activity/src/EventSubscriber/MyFeatureEventSubscriber.php') =]]
[[= include_code('code_samples/recent_activity/src/EventSubscriber/MyFeatureEventSubscriber.php') =]]
```

`ActivityLogService::build()` function returns an `Ibexa\Contracts\ActivityLog\Values\CreateActivityLogStruct` which can then be passed to `ActivityLogService::save`.
Expand Down Expand Up @@ -190,7 +190,7 @@ In the following example, several actions are logged into one context group, eve
- `complete`

``` php
[[= include_file('code_samples/recent_activity/src/Command/ActivityLogContextTestCommand.php', 46, 66, remove_indent=True) =]]
[[= include_code('code_samples/recent_activity/src/Command/ActivityLogContextTestCommand.php', 47, 66, remove_indent=True) =]]
```

Context groups can't be nested.
Expand Down Expand Up @@ -227,13 +227,13 @@ First, follow an example of a default template overriding the one from the bundl
It can be used during development as a fallback for classes that aren't mapped yet.

``` twig
[[= include_file('code_samples/recent_activity/templates/themes/admin/activity_log/ui/default.html.twig') =]]
[[= include_code('code_samples/recent_activity/templates/themes/admin/activity_log/ui/default.html.twig') =]]
```

Here is an example of a `ClassNameMapperInterface` associating the class `App\MyFeature\MyFeature` with the identifier `my_feature`:

``` php
[[= include_file('code_samples/recent_activity/src/ActivityLog/ClassNameMapper/MyFeatureNameMapper.php') =]]
[[= include_code('code_samples/recent_activity/src/ActivityLog/ClassNameMapper/MyFeatureNameMapper.php') =]]
```

This mapper also provides a translation for the class name in the **Filters** menu.
Expand All @@ -242,21 +242,21 @@ This translation can be extracted with `php bin/console jms:translation:extract
To be taken into account, this mapper must be registered as a service:

``` yaml
[[= include_file('code_samples/recent_activity/config/append_to_services.yaml') =]]
[[= include_code('code_samples/recent_activity/config/append_to_services.yaml') =]]
```

Here is an example of a `PostActivityListLoadEvent` subscriber which loads the related object when it's an `App\MyFeature\MyFeature`, and attaches it to the log entry:

``` php
[[= include_file('code_samples/recent_activity/src/EventSubscriber/MyFeaturePostActivityListLoadEventSubscriber.php') =]]
[[= include_code('code_samples/recent_activity/src/EventSubscriber/MyFeaturePostActivityListLoadEventSubscriber.php') =]]
```

The following template is made to display the object of `App\MyFeature\MyFeature` (now identified as `my_feature`) when the action is `simulate`,
so, it's named in `templates/themes/admin/activity_log/ui/my_feature/simulate.html.twig`.
Thanks to the previous subscriber, the related object is available at display time:

``` twig
[[= include_file('code_samples/recent_activity/templates/themes/admin/activity_log/ui/my_feature/simulate.html.twig') =]]
[[= include_code('code_samples/recent_activity/templates/themes/admin/activity_log/ui/my_feature/simulate.html.twig') =]]
```

## REST API
Expand Down
4 changes: 2 additions & 2 deletions docs/api/rest_api/rest_api_usage/rest_requests.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -169,13 +169,13 @@ This script:
=== "XML"

``` php
[[= include_file('code_samples/api/rest_api/create_image.xml.php', 0, None, ' ') =]]
[[= include_code('code_samples/api/rest_api/create_image.xml.php', 1, None, 1) =]]
```

=== "JSON"

``` php
[[= include_file('code_samples/api/rest_api/create_image.json.php', 0, None, ' ') =]]
[[= include_code('code_samples/api/rest_api/create_image.json.php', indent_level=1) =]]
```

### Search (`/views`)
Expand Down
69 changes: 40 additions & 29 deletions docs/search/search_api.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -29,10 +29,12 @@ The following command takes the content type identifier as an argument and lists

``` php hl_lines="14 16"
// ...
[[= include_file('code_samples/api/public_php_api/src/Command/FindContentCommand.php', 4, 7) =]]// ...
[[= include_file('code_samples/api/public_php_api/src/Command/FindContentCommand.php', 17, 19) =]] // ...
[[= include_file('code_samples/api/public_php_api/src/Command/FindContentCommand.php', 32, 48) =]]
[[= include_file('code_samples/api/public_php_api/src/Command/FindContentCommand.php', 48, 49) =]]
[[= include_code('code_samples/api/public_php_api/src/Command/FindContentCommand.php', 5, 7) =]]
// ...
[[= include_code('code_samples/api/public_php_api/src/Command/FindContentCommand.php', 18, 19) =]]
// ...
[[= include_code('code_samples/api/public_php_api/src/Command/FindContentCommand.php', 33, 48) =]]
[[= include_code('code_samples/api/public_php_api/src/Command/FindContentCommand.php', 49, 49) =]]
```

[`SearchService::findContentInfo`](/api/php_api/php_api_reference/classes/Ibexa-Contracts-Core-Repository-SearchService.html#method_findContentInfo) (line 16)
Expand Down Expand Up @@ -120,18 +122,22 @@ For example, the following command lists all content items under the specified p

``` php hl_lines="15-18"
// ...
[[= include_file('code_samples/api/public_php_api/src/Command/FilterCommand.php', 4, 9) =]]
// ...
[[= include_file('code_samples/api/public_php_api/src/Command/FilterCommand.php', 19, 21) =]][[= include_file('code_samples/api/public_php_api/src/Command/FilterCommand.php', 33, 53) =]]
[[= include_code('code_samples/api/public_php_api/src/Command/FilterCommand.php', 5, 9) =]]

[[= include_code('code_samples/api/public_php_api/src/Command/FilterCommand.php', 20, 21) =]]
// ...
[[= include_code('code_samples/api/public_php_api/src/Command/FilterCommand.php', 34, 53) =]]
```

The same Filter can be applied to find locations instead of content items, for example:

``` php hl_lines="20"
// ...
[[= include_file('code_samples/api/public_php_api/src/Command/FilterLocationCommand.php', 4, 9) =]]
[[= include_file('code_samples/api/public_php_api/src/Command/FilterCommand.php', 19, 21) =]]// ...
[[= include_file('code_samples/api/public_php_api/src/Command/FilterLocationCommand.php', 33, 53) =]]
[[= include_code('code_samples/api/public_php_api/src/Command/FilterLocationCommand.php', 5, 9) =]]

[[= include_code('code_samples/api/public_php_api/src/Command/FilterCommand.php', 20, 21) =]]
// ...
[[= include_code('code_samples/api/public_php_api/src/Command/FilterLocationCommand.php', 34, 53) =]]
```

!!! caution
Expand Down Expand Up @@ -183,8 +189,9 @@ For example, in the code below, `locationId` is provided to list all children of

``` php hl_lines="22-24"
// ...
[[= include_file('code_samples/api/public_php_api/src/Controller/CustomController.php', 4, 12) =]] // ...
[[= include_file('code_samples/api/public_php_api/src/Controller/CustomController.php', 16, 32) =]]
[[= include_code('code_samples/api/public_php_api/src/Controller/CustomController.php', 5, 12) =]]
// ...
[[= include_code('code_samples/api/public_php_api/src/Controller/CustomController.php', 17, 32) =]]
```

The rendering of results is then relegated to [templates](templates.md) (lines 22-24).
Expand All @@ -193,8 +200,9 @@ When using Repository filtering, provide the results of `ContentService::find()`

``` php hl_lines="19"
// ...
[[= include_file('code_samples/api/public_php_api/src/Controller/CustomFilterController.php', 4, 12) =]] // ...
[[= include_file('code_samples/api/public_php_api/src/Controller/CustomFilterController.php', 16, 31) =]]
[[= include_code('code_samples/api/public_php_api/src/Controller/CustomFilterController.php', 5, 12) =]]
// ...
[[= include_code('code_samples/api/public_php_api/src/Controller/CustomFilterController.php', 17, 31) =]]
```

### Paginate search results
Expand All @@ -203,14 +211,15 @@ To paginate search or filtering results, it's recommended to use the [Pagerfanta

``` php
// ...
[[= include_file('code_samples/api/public_php_api/src/Controller/PaginationController.php', 8, 15) =]] // ...
[[= include_file('code_samples/api/public_php_api/src/Controller/PaginationController.php', 19, 39) =]]
[[= include_code('code_samples/api/public_php_api/src/Controller/PaginationController.php', 9, 15) =]]
// ...
[[= include_code('code_samples/api/public_php_api/src/Controller/PaginationController.php', 20, 39) =]]
```

Pagination can then be rendered for example using the following template:

``` html+twig
[[= include_file('code_samples/api/public_php_api/templates/themes/standard/full/custom_pagination.html.twig') =]]
[[= include_code('code_samples/api/public_php_api/templates/themes/standard/full/custom_pagination.html.twig') =]]
```

For more information and examples, see [PagerFanta documentation](https://www.babdev.com/open-source/packages/pagerfanta/docs/2.x/usage).
Expand Down Expand Up @@ -241,9 +250,10 @@ For more complex searches, you need to combine multiple Criteria.
You can do it using logical operators: `LogicalAnd`, `LogicalOr`, and `LogicalNot`.

``` php
[[= include_file('code_samples/api/public_php_api/src/Command/FindComplexCommand.php', 44, 49) =]][[= include_file('code_samples/api/public_php_api/src/Command/FindComplexCommand.php', 53, 54) =]]
[[= include_file('code_samples/api/public_php_api/src/Command/FindComplexCommand.php', 60, 65) =]]
[[= include_code('code_samples/api/public_php_api/src/Command/FindComplexCommand.php', 45, 49) =]]
[[= include_code('code_samples/api/public_php_api/src/Command/FindComplexCommand.php', 54, 54) =]]

[[= include_code('code_samples/api/public_php_api/src/Command/FindComplexCommand.php', 61, 65) =]]
```

This example takes three parameters from a command — `$text`, `$contentTypeId`, and `$locationId`.
Expand All @@ -257,7 +267,7 @@ The example below uses the `LogicalNot` operator to search for all content conta
that doesn't belong to the provided Section:

``` php
[[= include_file('code_samples/api/public_php_api/src/Command/FindComplexCommand.php', 46, 54) =]]
[[= include_code('code_samples/api/public_php_api/src/Command/FindComplexCommand.php', 47, 54) =]]
```

### Combine independent Criteria
Expand Down Expand Up @@ -290,7 +300,7 @@ To sort the results of a query, use one of more [Sort Clauses](sort_clause_refer
For example, to order search results by their publication date, from oldest to newest, and then alphabetically by content name, add the following Sort Clauses to the query:

``` php
[[= include_file('code_samples/api/public_php_api/src/Command/FindComplexCommand.php', 55, 59) =]]
[[= include_code('code_samples/api/public_php_api/src/Command/FindComplexCommand.php', 56, 59) =]]
```

!!! tip
Expand All @@ -308,21 +318,21 @@ With aggregations you can find the count of search results or other result infor
To do this, you use of the query's `$aggregations` property:

``` php
[[= include_file('code_samples/api/public_php_api/src/Command/FindWithAggregationCommand.php', 30, 35) =]]
[[= include_code('code_samples/api/public_php_api/src/Command/FindWithAggregationCommand.php', 31, 35) =]]
```

The name of the aggregation must be unique in the given query.

Access the results by using the `get()` method of the aggregation:

``` php
[[= include_file('code_samples/api/public_php_api/src/Command/FindWithAggregationCommand.php', 39, 40) =]]
[[= include_code('code_samples/api/public_php_api/src/Command/FindWithAggregationCommand.php', 40, 40) =]]
```

Aggregation results contain the name of the result and the count of found items:

``` php
[[= include_file('code_samples/api/public_php_api/src/Command/FindWithAggregationCommand.php', 42, 45) =]]
[[= include_code('code_samples/api/public_php_api/src/Command/FindWithAggregationCommand.php', 43, 45) =]]
```

With field aggregations you can group search results according to the value of a specific field.
Expand All @@ -331,14 +341,14 @@ In this case the aggregation takes the content type identifier and the field ide
The following example creates an aggregation named `selection` that groups results according to the value of the `topic` field in the `article` content type:

``` php
[[= include_file('code_samples/api/public_php_api/src/Command/FindWithAggregationCommand.php', 35, 36) =]]
[[= include_code('code_samples/api/public_php_api/src/Command/FindWithAggregationCommand.php', 36, 36) =]]
```

With term aggregation you can define additional limits to the results.
The following example limits the number of terms returned to 5 and only considers terms that have 10 or more results:

``` php
[[= include_file('code_samples/api/public_php_api/src/Command/FindWithAggregationCommand.php', 30, 33) =]]
[[= include_code('code_samples/api/public_php_api/src/Command/FindWithAggregationCommand.php', 31, 33) =]]
```

To use a range aggregation, you must provide a `ranges` array containing a set of `Range` objects that define the borders of the specific range sets.
Expand Down Expand Up @@ -394,7 +404,7 @@ You build an `EmbeddingQuery` instance by using a builder and pass it to the sea
This example shows a minimal embedding query executed directly through the search service:

``` php hl_lines="38-39 41-47 49"
[[= include_file('code_samples/api/public_php_api/src/Command/FindByTaxonomyEmbeddingCommand.php') =]]
[[= include_code('code_samples/api/public_php_api/src/Command/FindByTaxonomyEmbeddingCommand.php') =]]
```

For more information, see [Embeddings reference](embeddings_reference.md).
Expand All @@ -411,8 +421,9 @@ For a list of supported Criteria and Sort Clauses, see [Search in trash referenc
Searching through the trashed content items operates directly on the database, therefore you cannot use external search engines, such as Solr or Elasticsearch, and it's impossible to reindex the data.

``` php
[[= include_file('code_samples/api/public_php_api/src/Command/FindInTrashCommand.php', 4, 6) =]]//...
[[= include_file('code_samples/api/public_php_api/src/Command/FindInTrashCommand.php', 35, 42) =]]
[[= include_code('code_samples/api/public_php_api/src/Command/FindInTrashCommand.php', 5, 6) =]]
//...
[[= include_code('code_samples/api/public_php_api/src/Command/FindInTrashCommand.php', 36, 42, remove_indent=True) =]]
```

!!! caution
Expand Down
2 changes: 1 addition & 1 deletion docs/templating/twig_function_reference/image_twig_functions.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -13,7 +13,7 @@ page_type: reference
To render images, use the [`ibexa_render_field()`](field_twig_functions.md#ibexa_render_field) Twig function with the variation name passed as an argument, for example:

``` html+twig
[[= include_file('docs/templating/twig_function_reference/field_twig_functions.md', 40, 48) =]]
[[= include_code('docs/templating/twig_function_reference/field_twig_functions.md', 42, 48) =]]
```

## Image information
Expand Down
4 changes: 4 additions & 0 deletions main.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -52,6 +52,10 @@ def include_file(filename, start_line=0, end_line=None, glue='', remove_indent=F

return glue.join(line_range)

@env.macro
def include_code(filename, start_line=1, end_line=None, indent_level=0, remove_indent=False):

@mnocon mnocon Apr 28, 2026

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Can you add docstring doc to include_file and mention that's it's deprecated/replaced by include_code - so that Copilot won't try to use that

And maybe docstring doc here as well, for the 🤖 to deal with it better 😄

@adriendupuis adriendupuis Apr 29, 2026 •
edited
Loading

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Done in a9391ca
I also renamed the first argument from filename to file_path to better match the expected value.

return include_file(filename, start_line-1, end_line, ' ' * indent_level, remove_indent).rstrip()

@env.macro
def cards(pages, columns=1, style="cards", force_version=False):
current_page = env.variables.page
Expand Down
Loading
Loading