From 39a1497d063eb0eb3f75cbfcc82d37eec8a5b938 Mon Sep 17 00:00:00 2001 From: Yuliya Pazniak Date: Tue, 31 Dec 2024 13:33:15 +0300 Subject: [PATCH 1/2] to discuss twig --- datapress/Forms/custom-forms.md | 34 +++ datapress/binding/table-binding.md | 4 +- datapress/knowledge_base/devInfo/retrieve.md | 1 + datapress/using-twig/_category_.json | 7 + datapress/using-twig/filters_and_function.md | 53 +++++ .../twig_introduction.md} | 200 ++---------------- datapress/using-twig/twig_template.md | 90 ++++++++ docusaurus.config.ts | 2 +- 8 files changed, 209 insertions(+), 182 deletions(-) create mode 100644 datapress/using-twig/_category_.json create mode 100644 datapress/using-twig/filters_and_function.md rename datapress/{twig.md => using-twig/twig_introduction.md} (53%) create mode 100644 datapress/using-twig/twig_template.md diff --git a/datapress/Forms/custom-forms.md b/datapress/Forms/custom-forms.md index d405867..e5dfab2 100644 --- a/datapress/Forms/custom-forms.md +++ b/datapress/Forms/custom-forms.md @@ -159,6 +159,40 @@ Custom forms allow creating new Dataverse / Dynamics 365 rows, as well as updati The `{% form %}` Twig tag lets you configure the form settings, such as target table, submission mode (create or update), etc. Form control `name` columns refer to the corresponding table columns, such as `firstname`, `lastname` and `emailaddress1`. Put the `` placeholder where you want to put reCAPTCHA control if you enable reCAPTCHA on your form. Before you use reCAPTCHA, please configure it in plugin settings. +## Date Time and Date Only fields in custom forms + +For example, you have several custom fields: `cr1d1_dateonly` - Date Only format, `cr1d1_datetime` - Date Time format. + +```php +{% form entity="contact" mode="create" record=record|to_entity_reference %} +
+
+ +
+
+ +
+
+ +
+
+ +
+
+{% endform %} +``` + +Then you view page with this template. To fill in this form you should type content in Date only field in `yyyy-mm-dd` or `yyyy/mm/dd` format (like `2023-01-20` or `2023/01/20`), Date Time field in `yyyy-mm-ddThh:mm` format (like `2023-01-20T12:30`). + ### Getting row GUID After the row has been successfully created, you can get the guid using the redirect setting with the %s parameter. diff --git a/datapress/binding/table-binding.md b/datapress/binding/table-binding.md index 2640169..d31643b 100644 --- a/datapress/binding/table-binding.md +++ b/datapress/binding/table-binding.md @@ -93,7 +93,7 @@ If you choose binding via custom code, you must implement two filter hooks. Enable conditional access by selecting the checkbox. Add a FetchXML query in the text area. -The query is virtually a [Twig template](/datapress/twig.md), and all the same Twig constructs, objects, filters and functions are available. Members of the `binding` object will reference the current record, and `user` object members will reference to the current user if [User Binding](/datapress/binding/user-binding.md) is implemented. +The query is virtually a [Twig template](/datapress/using-twig/twig_template.md), and all the same Twig constructs, objects, filters and functions are available. Members of the `binding` object will reference the current record, and `user` object members will reference to the current user if [User Binding](/datapress/binding/user-binding.md) is implemented. Sample FetchXML query that grants access only to users which are bound to contacts which in turn belong to the requested Account. @@ -139,4 +139,4 @@ You can manage page binding in WordPress Admin Area by navigating to Bindings -> Information retrieved via table binding is used to update a certain record(row) with a form. See [Forms documentation](/datapress/Forms/forms.md). -In Twig, the current row on a page is exposed via the global object `binding.record`. It contains an Table object of the current row, and you can access any column, e.g. `{{ binding.record["fullname"] }}`. For more information see [Twig documentation](/datapress/twig.md) +In Twig, the current row on a page is exposed via the global object `binding.record`. It contains an Table object of the current row, and you can access any column, e.g. `{{ binding.record["fullname"] }}`. For more information see [Twig documentation](/datapress/using-twig/twig_introduction.md) diff --git a/datapress/knowledge_base/devInfo/retrieve.md b/datapress/knowledge_base/devInfo/retrieve.md index e11c7a7..9452fe9 100644 --- a/datapress/knowledge_base/devInfo/retrieve.md +++ b/datapress/knowledge_base/devInfo/retrieve.md @@ -46,3 +46,4 @@ expand:"ownerid"
  • ID: {{record1["accountid"]}} Name: {{record1["name"]}} |{{record1["ownerid"].Name}}
    • ``` +For more information about function see [Filters and function](/datapress/using-twig/filters_and_function.md) \ No newline at end of file diff --git a/datapress/using-twig/_category_.json b/datapress/using-twig/_category_.json new file mode 100644 index 0000000..aa43f29 --- /dev/null +++ b/datapress/using-twig/_category_.json @@ -0,0 +1,7 @@ +{ + "label": "Using Twig", + "position": 4, + "link": { + "type": "generated-index" + } +} diff --git a/datapress/using-twig/filters_and_function.md b/datapress/using-twig/filters_and_function.md new file mode 100644 index 0000000..27835f4 --- /dev/null +++ b/datapress/using-twig/filters_and_function.md @@ -0,0 +1,53 @@ +--- +sidebar_position: 2 +title: Filters and function +slug: /twig/filters_and_function +tags: + - Twig + - DataPress +keywords: [DataPress twig] +--- + +## Filters + +DataPress (Dataverse Integration) provides several Dataverse-specific and general purpose Twig filters. + +- `formatted_value( attributeName )` -- returns the formatted value of the filtered entity record as reported by Dataverse. Returns the entity record attribute value if no formatted value available. + E.g. `record|formatted_value( "preferredappointmenttimecode" )` +- `to_entity_reference` -- converts an Entity object, or an EntityReference-like object to a strongly typed EntityReference object. For an EntityReference-like object, the filter expects `LogicalName` (required), `Id` and `Name` keys. + E.g. `record|to_entity_reference` or `{ "LogicalName": "contact", "Id": "00000000-0000-0000-0000-000000000000" }` +- `add_query( queryName, queryValue )` -- adds a GET query argument to the filtered URL, honors the already existing query string which allows piping. +- `wpautop` -- see [WordPress wpautop() docs](https://developer.wordpress.org/reference/functions/wpautop/). + +## Functions + +```twig +- image_url( + record, + column, + isThumb, + { + "Content-Disposition": "inline", + "Content-Type": "text/html; charset=utf-8", + "Cache-Control": "max-age=604800" + } +) +``` +-- returns URL to the image stored in the specified Dataverse image column. + +```twig +- file_url( + record, + column, + { + "Content-Disposition": "inline", + "Content-Type": "text/html; charset=utf-8", + "Cache-Control": "max-age=604800" + } +) +``` +-- returns download URL for the file stored in the specified Dataverse file column. + +- `last_error()` - returns last error generated by the Twig provider. + +- `entity_url( record, postId = null )` -- returns URL to the website page with the given entity record bound to it. Uses [Table Binding](/datapress/binding/table-binding.md) feature. If more than one WordPress post is bound to the table, you can pass post ID to link to a different page instead. diff --git a/datapress/twig.md b/datapress/using-twig/twig_introduction.md similarity index 53% rename from datapress/twig.md rename to datapress/using-twig/twig_introduction.md index 6eaaa48..a254ad9 100644 --- a/datapress/twig.md +++ b/datapress/using-twig/twig_introduction.md @@ -1,7 +1,7 @@ --- -sidebar_position: 4 +sidebar_position: 1 title: Using Twig -slug: /twig +slug: /twig/introduction tags: - Twig - DataPress @@ -27,6 +27,25 @@ Twig in DataPress (Dataverse Integration) supports debug mode and template cachi - Debug mode allows using `dump()` to print information about Twig objects using PHP `var_dump()`. It is enabled in [WordPress debug mode](https://wordpress.org/support/article/debugging-in-wordpress/) (`WP_DEBUG`) or if `ICDS_TWIG_DEBUG` is *true*. - Template caching enhances page rendering performance. Enabled if `ICDS_TWIG_CACHE` is *true*. +## Supporting Mobile-Detect + +The `MobileDetect` class contains various functions for detecting mobile devices and browsers. [Read more](https://github.com/serbanghita/Mobile-Detect) + +```twig +isMobile: {% if isMobile %} Yes! {% else %} No! {% endif %}
    + +isChrome: {% if isChrome %} Yes! {% else %} No! {% endif %}
    + +isFirefox: {% if isFirefox %} Yes! {% else %} No! {% endif %}
    +``` + +:::tip Intellisense + +Intellisense for working with the mobile detection methods is available in the `Dataverse Twig` block after typing `{{`. + +::: + + ## Global objects DataPress (Dataverse Integration) makes several new global objects available in the Twig environment. @@ -189,180 +208,3 @@ Global object `params` is the alias of `request.params`. ### Check if the website is connected to Dataverse `crm.connected` tells whether the website is configured to make connections to Dataverse. - -## Filters - -DataPress (Dataverse Integration) provides several Dataverse-specific and general purpose Twig filters. - -- `formatted_value( attributeName )` -- returns the formatted value of the filtered entity record as reported by Dataverse. Returns the entity record attribute value if no formatted value available. - E.g. `record|formatted_value( "preferredappointmenttimecode" )` -- `to_entity_reference` -- converts an Entity object, or an EntityReference-like object to a strongly typed EntityReference object. For an EntityReference-like object, the filter expects `LogicalName` (required), `Id` and `Name` keys. - E.g. `record|to_entity_reference` or `{ "LogicalName": "contact", "Id": "00000000-0000-0000-0000-000000000000" }` -- `add_query( queryName, queryValue )` -- adds a GET query argument to the filtered URL, honors the already existing query string which allows piping. -- `wpautop` -- see [WordPress wpautop() docs](https://developer.wordpress.org/reference/functions/wpautop/). - -## Functions - -```twig -- image_url( - record, - column, - isThumb, - { - "Content-Disposition": "inline", - "Content-Type": "text/html; charset=utf-8", - "Cache-Control": "max-age=604800" - } -) -``` --- returns URL to the image stored in the specified Dataverse image column. - -```twig -- file_url( - record, - column, - { - "Content-Disposition": "inline", - "Content-Type": "text/html; charset=utf-8", - "Cache-Control": "max-age=604800" - } -) -``` --- returns download URL for the file stored in the specified Dataverse file column. - -- `last_error()` - returns last error generated by the Twig provider. - -- `entity_url( record, postId = null )` -- returns URL to the website page with the given entity record bound to it. Uses [Table Binding](/datapress/binding/table-binding.md) feature. If more than one WordPress post is bound to the table, you can pass post ID to link to a different page instead. - -:::info - -Premium feature! - -::: - -## Templates usage - -DataPress (Dataverse Integration) gives you the ability to create reusable templates. To do this, you need to go to the plugin admin area and open the "Templates" tab. - -There you must enter the name of the template and the content of the template. The content could contain all the functions, statements and filters of Twig. - -To use templates in `Dataverse Twig Gutenberg` block, you need to use the `include` statement with the template name. For example: - -```twig -{% include 'name_of_your_template' %} -``` - - -If you want to create a template for updating record you can look at this example: - -```twig -{% set currentRecord=entities.account[params.id] %} -{% form entity="account" mode="update" record=currentRecord|to_entity_reference %} -
    -
    - -
    -
    - -
    -
    - -
    -
    - -
    -
    -{% endform %} -``` - -Then at the moment of page creation you need to use the `include` statement with the template name(previous example). And you need to configure binding for this page to have opportunity to update necessary record. [See how to configure binding.](/datapress/binding/table-binding.md) - -You can also use templates to replace the form template or individual form fields in form registration editor. For this purpose click `Render form based on twig template` on the creation form page. Then choose your template name from the form template dropdown. If you want to replace just some fields you should leave default value for the form template dropdown, but set value for `fields templates`. - -Also you can partially change behavior for some fields. For example, this code will change placeholders for first name and last name fields: - -```twig -{% set firstnameDisabled = control.disabled %} -{% set lastnameDisabled = control.disabled %} -
    -
    - - {% if 'firstname' in form.errors|keys %} - {% for errorMessage in form.errors['firstname'] %} - - {% endfor %} - {% endif %} -
    -
    - - {% if 'lastname' in form.errors|keys %} - {% for errorMessage in form.errors['lastname'] %} - - {% endfor %} - {% endif %} -
    -
    -``` - -To use this template at the moment of form creation set `Render form based on twig template` as `Yes` on the creation form page. Then set mapping between `Fullname` field and your template name as value. - -## Date Time and Date Only fields in twig templates - -For example, you have several custom fields: `cr1d1_dateonly` - Date Only format, `cr1d1_datetime` - Date Time format. Specify them in a twig template. - -```twig -{% form entity="contact" mode="create" record=record|to_entity_reference %} -
    -
    - -
    -
    - -
    -
    - -
    -
    - -
    -
    -{% endform %} -``` - -Then you view page with this template. To fill in this form you should type content in Date only field in `yyyy-mm-dd` or `yyyy/mm/dd` format (like `2023-01-20` or `2023/01/20`), Date Time field in `yyyy-mm-ddThh:mm` format (like `2023-01-20T12:30`). - -## Supporting Mobile-Detect - -The `MobileDetect` class contains various functions for detecting mobile devices and browsers. [Read more](https://github.com/serbanghita/Mobile-Detect) - -```twig -isMobile: {% if isMobile %} Yes! {% else %} No! {% endif %}
    - -isChrome: {% if isChrome %} Yes! {% else %} No! {% endif %}
    - -isFirefox: {% if isFirefox %} Yes! {% else %} No! {% endif %}
    -``` - -:::tip Intellisense - -Intellisense for working with the mobile detection methods is available in the `Dataverse Twig` block after typing `{{`. - -::: diff --git a/datapress/using-twig/twig_template.md b/datapress/using-twig/twig_template.md new file mode 100644 index 0000000..1b4d82a --- /dev/null +++ b/datapress/using-twig/twig_template.md @@ -0,0 +1,90 @@ +--- +sidebar_position: 3 +title: Twig template +slug: /twig/twig_template +tags: + - Twig + - DataPress +keywords: [DataPress twig] +--- + +:::info + +Premium feature! + +::: + +## Templates usage + +DataPress (Dataverse Integration) gives you the ability to create reusable templates. To do this, you need to go to the plugin admin area and open the "Templates" tab. + +There you must enter the name of the template and the content of the template. The content could contain all the functions, statements and filters of Twig. + +To use templates in `Dataverse Twig Gutenberg` block, you need to use the `include` statement with the template name. For example: + +```twig +{% include 'name_of_your_template' %} +``` + + +If you want to create a template for updating record you can look at this example: + +```php +{% set currentRecord=entities.account[params.id] %} +{% form entity="account" mode="update" record=currentRecord|to_entity_reference %} +
    +
    + +
    +
    + +
    +
    + +
    +
    + +
    +
    +{% endform %} +``` + +Then at the moment of page creation you need to use the `include` statement with the template name(previous example). And you need to configure binding for this page to have opportunity to update necessary record. [See how to configure binding.](/datapress/binding/table-binding.md) + +You can also use templates to replace the form template or individual form fields in form registration editor. For this purpose click `Render form based on twig template` on the creation form page. Then choose your template name from the form template dropdown. If you want to replace just some fields you should leave default value for the form template dropdown, but set value for `fields templates`. + +Also you can partially change behavior for some fields. For example, this code will change placeholders for first name and last name fields: + +```php +{% set firstnameDisabled = control.disabled %} +{% set lastnameDisabled = control.disabled %} +
    +
    + + {% if 'firstname' in form.errors|keys %} + {% for errorMessage in form.errors['firstname'] %} + + {% endfor %} + {% endif %} +
    +
    + + {% if 'lastname' in form.errors|keys %} + {% for errorMessage in form.errors['lastname'] %} + + {% endfor %} + {% endif %} +
    +
    +``` + +To use this template at the moment of form creation set `Render form based on twig template` as `Yes` on the creation form page. Then set mapping between `Fullname` field and your template name as value. diff --git a/docusaurus.config.ts b/docusaurus.config.ts index c154369..da8cff7 100644 --- a/docusaurus.config.ts +++ b/docusaurus.config.ts @@ -74,7 +74,7 @@ const config: Config = { }, { to: '/twig', - from: ['/integration-cds/twig'], + from: ['/integration-cds/twig/introduction'], }, { to: '/fetchxml', From 849a5faa05afca081aa86af696c2458c27753489 Mon Sep 17 00:00:00 2001 From: Yuliya Pazniak Date: Tue, 7 Jan 2025 15:21:16 +0300 Subject: [PATCH 2/2] fix redirect --- docusaurus.config.ts | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docusaurus.config.ts b/docusaurus.config.ts index da8cff7..78ddac7 100644 --- a/docusaurus.config.ts +++ b/docusaurus.config.ts @@ -73,8 +73,8 @@ const config: Config = { from: ['/integration-cds/views'], }, { - to: '/twig', - from: ['/integration-cds/twig/introduction'], + to: '/twig/introduction', + from: ['/integration-cds/twig'], }, { to: '/fetchxml',