Skip to content

Commit

Permalink
Merge pull request #103 from AlexaCRM/updateTwig
Browse files Browse the repository at this point in the history 
to discuss twig
  • Loading branch information
@georged
georged authored Jan 8, 2025
2 parents ef6e8e5 + 849a5fa commit 1ccc4a5
Show file tree
Hide file tree
Showing 8 changed files with 209 additions and 182 deletions.
34 changes: 34 additions & 0 deletions datapress/Forms/custom-forms.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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 `<recaptcha>` 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 %}
<form>
<div class="form-group">
<label>
Account Name:
<input class="form-control" name="name" value="{{ record["name"] }}">
</label>
</div>
<div class="form-group">
<label>
Date Only field:
<input class="vdatetime" name="cr1d1_dateonly" value="{{ record["cr1d1_dateonly"] }}">
</label>
</div>
<div class="form-group">
<label>
Date Time field:
<input class="vdatetime" name="cr1d1_datetime" value="{{ record["cr1d1_datetime"] }}">
</label>
</div>
<div class="form-group">
<button type="submit" class="btn btn-primary">Send</button>
</div>
</form>
{% 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.
Expand Down
4 changes: 2 additions & 2 deletions datapress/binding/table-binding.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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.

Expand Down Expand Up @@ -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)
1 change: 1 addition & 0 deletions datapress/knowledge_base/devInfo/retrieve.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -46,3 +46,4 @@ expand:"ownerid"
<li><b>ID:</b> {{record1["accountid"]}} <b>Name: </b>{{record1["name"]}} |{{record1["ownerid"].Name}}</li>
```

For more information about function see [Filters and function](/datapress/using-twig/filters_and_function.md)
7 changes: 7 additions & 0 deletions datapress/using-twig/_category_.json
View file
Original file line number Diff line number Diff line change
@@ -0,0 +1,7 @@
{
"label": "Using Twig",
"position": 4,
"link": {
"type": "generated-index"
}
}
53 changes: 53 additions & 0 deletions datapress/using-twig/filters_and_function.md
View file
Original file line number Diff line number Diff line change
@@ -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.
200 changes: 21 additions & 179 deletions datapress/twig.md → datapress/using-twig/twig_introduction.md
View file
Original file line number Diff line number Diff line change
@@ -1,7 +1,7 @@
---
sidebar_position: 4
sidebar_position: 1
title: Using Twig
slug: /twig
slug: /twig/introduction
tags:
- Twig
- DataPress
Expand All @@ -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 %}<br/>
isChrome: {% if isChrome %} Yes! {% else %} No! {% endif %}<br/>
isFirefox: {% if isFirefox %} Yes! {% else %} No! {% endif %}<br/>
```

:::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.
Expand Down Expand Up @@ -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 %}
<form>
<div class="form-group">
<label>
Account Name:
<input class="form-control" name="name" value="{{ currentRecord["name"] }}">
</label>
</div>
<div class="form-group">
<label>
Email:
<input class="form-control" name="emailaddress1" value="{{ record["emailaddress1"] }}">
</label>
</div>
<div class="form-group">
<label>
Last Date Included in Campaign:
<input class="vdatetime" name="lastusedincampaign" value="{{ currentRecord["lastusedincampaign"] }}">
</label>
</div>
<div class="form-group">
<button type="submit" class="btn btn-primary">Send</button>
</div>
</form>
{% 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 %}
<div class="row">
<div class="col-6 {% if 'firstname' in form.errors|keys %}has-danger{% endif %}">
<input type="text" name="firstname" placeholder="Client First Name" class="form-control form-control-danger" value="{{ attribute(record, 'firstname') ?? formDefaults['firstname'] }}" {% if firstnameDisabled %}readonly="readonly"{% endif %}>
{% if 'firstname' in form.errors|keys %}
{% for errorMessage in form.errors['firstname'] %}
<div class="form-control-feedback">{{ errorMessage }}</div>
{% endfor %}
{% endif %}
</div>
<div class="col-6 {% if 'lastname' in form.errors|keys %}has-danger{% endif %}">
<input type="text" name="lastname" placeholder="Client Last Name" class="form-control" value="{{ attribute(record, 'lastname') ?? formDefaults['lastname'] }}" {% if lastnameDisabled %}readonly="readonly"{% endif %}>
{% if 'lastname' in form.errors|keys %}
{% for errorMessage in form.errors['lastname'] %}
<div class="form-control-feedback">{{ errorMessage }}</div>
{% endfor %}
{% endif %}
</div>
</div>
```

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 %}
<form>
<div class="form-group">
<label>
Account Name:
<input class="form-control" name="name" value="{{ record["name"] }}">
</label>
</div>
<div class="form-group">
<label>
Date Only field:
<input class="vdatetime" name="cr1d1_dateonly" value="{{ record["cr1d1_dateonly"] }}">
</label>
</div>
<div class="form-group">
<label>
Date Time field:
<input class="vdatetime" name="cr1d1_datetime" value="{{ record["cr1d1_datetime"] }}">
</label>
</div>
<div class="form-group">
<button type="submit" class="btn btn-primary">Send</button>
</div>
</form>
{% 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 %}<br/>
isChrome: {% if isChrome %} Yes! {% else %} No! {% endif %}<br/>
isFirefox: {% if isFirefox %} Yes! {% else %} No! {% endif %}<br/>
```

:::tip Intellisense

Intellisense for working with the mobile detection methods is available in the `Dataverse Twig` block after typing `{{`.

:::
Loading

0 comments on commit 1ccc4a5

Please sign in to comment.