From 799057fcea6ce9418b64928dbbc6db8b80d66396 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Thomas=20K=C3=B6rner?= Date: Sun, 29 Oct 2023 22:55:16 +0100 Subject: [PATCH] rework readme, some last cleanup --- README.md | 279 ++++++++--------------------------- config/services.yml | 2 +- config/twig.yml | 9 -- src/ContaoManager/Plugin.php | 1 - 4 files changed, 66 insertions(+), 225 deletions(-) delete mode 100644 config/twig.yml diff --git a/README.md b/README.md index dc5666a3..0d883555 100644 --- a/README.md +++ b/README.md @@ -30,243 +30,94 @@ In addition, there are DcaField helpers, the Entity finder command and some nice ### Utils service -### Dca Fields - -### Entity Finder - -### Twig Filters - - - - -# OLD STUFF - - - -> We're currently in a process moving all services into the Utils namespace and make them all accessible from a new Utils service. - -This Bundle is a collection of utils to solve recurring tasks. See the [API Documentation](https://heimrichhannot.github.io/contao-utils-bundle/) to see all util-classes and -methods. - -The default way to access the util methods is the `Utils`-service (currently not all services are available there yet). The utils service is best used with dependency injection, but is also available from the service container as public service for usage in legacy code. - - ```php - use HeimrichHannot\UtilsBundle\Util\Utils; +The Utils service is the core functionality of this bundle. It provides access to a lot of util functions help solving recurring tasks. +It's build as one service from which you can access all utils services. +The utils service is best used with dependency injection, but is also available from the service container as public service for usage in legacy code. +You can check the [API Documentation](https://heimrichhannot.github.io/contao-utils-bundle/namespaces/heimrichhannot-utilsbundle-util.html) to see all available functions. + +```php +use HeimrichHannot\UtilsBundle\Util\Utils; + +/** + * A class containing examples usage of utils services. Please don't expect it to be useful :) + */ +class MyClass{ + /** @var Utils */ + protected $utils; + + public function __construct(Utils $utils) { + $this->utils = $utils; + } - class MyClass{ - /** @var Utils */ - protected $utils; + public function someActions(): bool { + $dcaFields = $this->utils->dca()->getDcaFields('tl_content'); + $this->utils->array()->removeValue('headline', $dcaFields); + foreach ($dcaFields as $dcaField) { + echo $this->utils->string()->camelCaseToDashed($dcaField); + } - public function __construct(Utils $utils) { - $this->utils = $utils; - } - - public function someActions(): bool { - return $this->utils->string()->startsWith('Lorem ipsum dolor sit amet', 'Lorem'); - } - } - ``` - -To access services that are not available through the `Utils`-service, inject or call them directly. - -> Keep in mind that all services are about to be moved to the Utils namespace and will be deprecated (and removed in version 3.0) in the future. - - -Available [Service](src/Resources/config/services.yml) (as of version 2.131): - -``` -huh.utils.accordion -huh.utils.anonymizer -huh.utils.array -huh.utils.cache.database -huh.utils.cache.database_tree -huh.utils.cache.file -huh.utils.cache.remote_image_cache -huh.utils.choice.data_container -huh.utils.choice.field -huh.utils.choice.message -huh.utils.choice.model_instance -huh.utils.choice.twig_template -huh.utils.class -huh.utils.code -huh.utils.comparison -huh.utils.container -huh.utils.database -huh.utils.date -huh.utils.dca -huh.utils.encryption -huh.utils.file -huh.utils.file_archive -huh.utils.folder -huh.utils.form -huh.utils.image -huh.utils.location -huh.utils.member -huh.utils.model -huh.utils.module -huh.utils.pdf.preview -huh.utils.request.curl -huh.utils.routing -huh.utils.salutation -huh.utils.string -huh.utils.template -huh.utils.url -huh.utils.user -``` - -## Documentation - -[API Documentation](https://heimrichhannot.github.io/contao-utils-bundle/) - -### Utils - -[~~PdfCreator~~](docs/utils/pdf/pdfcreator.md) - ~~High-level API to create pdf files with PHP~~ (PDFCreator was moved into it's [own library](https://github.com/heimrichhannot/pdf-creator)) - -### Using with Webpack/Encore - -The bundle assets (js) are prepared to be used with webpack/encore. If you don't use [Foxy](https://github.com/fxpio/foxy), you need to add `"@hundh/contao-utils-bundle": "^1.5.0"` to your project package.json. - -See [package Repository](https://github.com/heimrichhannot-contao-components/contao-utils-bundle) for documentation. - -### JavaScript Utils - -#### Ajax Util -This util offers a shorthand for POST- and GET-ajax-requests. - -``` -static post(url, data, config) {...} -# or -static get(url, data, config) {...} -``` -Both take the following parameters - -name | description -| --- | --- | -| url | The url the request will be send to. | -| data | The data that is used for the request. It has to be passed as JSON. | -| config | An object that can hold the onSuccess-, onError-, beforeSubmit-, afterSubmit-callback and the request headers | - - -Parameters of config - -name | description -| --- | --- | -| onSuccess | Is called when the request was successfull. The request is passed as parameter. | -| onError | Is called when the request had an error. The request is passed as parameter. | -| beforeSubmit | Is called before the request is submitted. The url, data and config are passed as parameters. | -| afterSubmit | Is called before the request is submitted. The url, data and config are passed as parameters. | -| headers | The headers will be set when the request is initialized. | - -The contents of the config parameter are all optional. If you pass an empty config to the ajaxUtil a silent request will be processed. -The data will be transformed in the fitting format accordion wether you use a POST- or a GET-request. - -To use the shorthands import the utilsBundle into your script. After that just call the method an pass the needed parameters. - + $rootPageModel = $this->utils->request()->getCurrentRootPageModel(); + echo $this->utils->anonymize()->anonymizeEmail($rootPageModel->adminEmail); + + $groupUsers = $this->utils->user()->findActiveUsersByGroup([1,2]); + $this->utils->url()->addQueryStringParameterToUrl('user='.$groupUsers[0]->username, 'https://example.org'); + + if ($this->utils->container()->isBackend()) { + $where = $this->utils->database()->createWhereForSerializedBlob('dumbData', ['foo', 'bar']); + $model = $this->utils->model()->findOneModelInstanceBy('tl_content', [$where->createAndWhere()], [$where->values]); + echo '
utils->html()->generateAttributeString($model->getHtmlAttributes()).'>
'; + } +} ``` -import "@hundh/contao-utils-bundle"; -... -utilsBundle.ajax.get(url, data, config); -# or -utilsBundle.ajax.post(url, data, config); -``` - -### Configuration +### Dca Fields -Following configuration parameter can be overridden: +The bundle provides some common dca fields that can be used in your dca files. -```yaml -# Default configuration for extension with alias: "huh_utils" -huh_utils: - tmp_folder: files/tmp/huh_utils_bundle +#### Author field - # Default folder where to store pdf preview images. - pdfPreviewFolder: null - cache: +Add an author field to your dca. It will be initialized with the current backend user. On copy, it will be set to the current user. - # Enable database tree cache is generated on cache warmup. - enable_generate_database_tree_cache: false +```php +# contao/dca/tl_example.php +use HeimrichHannot\UtilsBundle\Dca\AuthorField; - # Load utils bundle assets. Default value will be changed to false in next major version. - enable_load_assets: true +AuthorField::register('tl_example'); ``` -## Twig Extensions +You can pass additional options to adjust the field: -These bundle add server twig filters: - -Filter | Parameter | Description ------------------ | --------- | ----------- -autolink | array options | Create a link if string is an url. -anonymize_email | - | Returns an anonymized email address. max.muster@example.org will be max.****@example.org -deserialize | bool force_array = false | Deserialize an serialized array (using `\Contao\StringUtil`) -download | download = true, data = [], template = "@HeimrichHannotContaoUtils\/download.html.twig" | -download_data | data = [] | -download_link | data = [] | -download_path | data = [] | -download_title | data = [] | -file_data | data = [], jsonSerializeOptions = [] -file_path | | -image | size = null, data = [], template = "image.html.twig" | -image_caption | | -image_data | size = null, data = [] | -image_gallery | template = "image_gallery.html.twig" -image_size | | -image_width | | -localized_date | format = null | -replace_inserttag | bool cache = true | Replace contao inserttag in twig string. - - -### Image Extension - -Use the image extension to resize contao images inside your twig template. +```php +# contao/dca/tl_example.php +use HeimrichHannot\UtilsBundle\Dca\AuthorField; +AuthorField::register('tl_example') + ->setType(AuthorField::TYPE_MEMBER) // can be one of TYPE_USER (default) or TYPE_MEMBER. Use TYPE_MEMBER to set a frontend member instead of a backend user + ->setFieldNamePrefix('example') // custom prefix for the field name + ->setUseDefaultLabel(false) // set to false to disable the default label and set a custom label in your dca translations + ->setExclude(false) // set the dca field exclude option + ->setSearch(false) // set the dca field search option + ->setFilter(false) // set the dca field filter option +; ``` -{% for box in boxes %} - {{ box.image|image([0,0,6],{'href' : box.url, 'linkTitle' : 'vmd.content.more.default'|trans})|raw }} -{% endfor %} -``` - -#### Arguments -- size: array containing width, height or image size config id (`Theme image size id`) -- data: additional image data like css class, linkTitle or href - -### Download Extension -Use the download extension to render download elements, get download links, download path or download data. -``` -{% set downloadData = singleSRC|download_data %} {#get download data #} -{{ singleSRC|download(true,{'link': 'customLinkTitleHtml'}, '@HeimrichHannotContaoUtils/download.html.twig') {#render as download link and send file to browser link #} -{{ singleSRC|download(false,{'link': 'customLinkTitleHtml'}, '@HeimrichHannotContaoUtils/download.html.twig') {#render as download link and open download in news window #} -{{ singleSRC|download_link) {#get send file to browser download link #} -{{ singleSRC|download_path) {#get download file path #} -{{ singleSRC|download_title) {#get download title for link title attribute e.g. #} -``` +### Entity Finder -## Insert tags +The entity finder is a command to search for any contao entities in your database. -| Insert tag | Description | -|---|---| -| {{twig::*}} | This tag will be replaced with the rendered output of a given twig template, that can be sourced in `bundle/src/Resources/views` or contao root `/templates` directory (replace 1st * with template name e.g. `svg_logo_company` and 2nd * with serialized parameters that should be passed to the template) | +**[Entity finder](docs/commands/entity_finder.md)** -## Commands -**[Entity finder](docs/commands/entity_finder.md)** - A command to search for any contao entities in your database. +### Twig Filters -**Image size creator** - Creates image size items for a given image size entity. +This bundle contains currently one twig filter: -``` -Description: - Creates image size items for a given image size entity. Image size entities with existing image size items will be skipped. +### anonymize_email -Usage: - huh:utils:create-image-size-items [ []] +Returns an anonymized email address. max.muster@example.org will be max.****@example.org -Arguments: - image-size-ids The comma separated ids of the image size. Skip the parameter in order to create image size items for all image size entities. - breakpoints The comma separated breakpoints as pixel amounts (defaults to "576,768,992,1200,1400"). [default: "576,768,992,1200,1400"] - -Example: - huh:utils:create-image-size-items 1,2 +```twig +{{ user.email|anonymize_email }} ``` \ No newline at end of file diff --git a/config/services.yml b/config/services.yml index 16e13129..8191054d 100644 --- a/config/services.yml +++ b/config/services.yml @@ -10,7 +10,7 @@ services: autoconfigure: true HeimrichHannot\UtilsBundle\: - resource: '../src/{Command,EntityFinder,EventListener,Util}/*' + resource: '../src/{Command,EntityFinder,EventListener,Twig,Util}/*' exclude: '../src/Util/Utils.php' autowire: true autoconfigure: true diff --git a/config/twig.yml b/config/twig.yml deleted file mode 100644 index 5d1f5996..00000000 --- a/config/twig.yml +++ /dev/null @@ -1,9 +0,0 @@ -services: - _defaults: - autowire: true - - _instanceof: - Twig\Extension\AbstractExtension: - tags: [twig.extension] - - HeimrichHannot\UtilsBundle\Twig\StringExtension: ~ \ No newline at end of file diff --git a/src/ContaoManager/Plugin.php b/src/ContaoManager/Plugin.php index 6b973e5b..e1882554 100644 --- a/src/ContaoManager/Plugin.php +++ b/src/ContaoManager/Plugin.php @@ -36,6 +36,5 @@ public function getBundles(ParserInterface $parser) public function registerContainerConfiguration(LoaderInterface $loader, array $managerConfig) { $loader->load('@HeimrichHannotUtilsBundle/config/services.yml'); - $loader->load('@HeimrichHannotUtilsBundle/config/twig.yml'); } }