feat: Make ion-input counter formatter more beginner-friendly

[johannesvollmer]

Prerequisites

• I have read the Contributing Guidelines.
• I agree to follow the Code of Conduct.
• I have searched for existing issues that already include this feature request, without success.

Describe the Feature Request

We suggest that the counterFormatter attribute on ion-input can be passed an interface, in addition to a callback. This will avoid a potential pitfall, thus making ionic more beginner friendly.

We added internationalization to our ion input counter formatter. But the current design is inconvenient, as it requires the use of bind or an unidiomatic arrow function in the class.

Describe the Use Case

The example in the documentation is error-prone:

<ion-input
  [counter]="true"
  maxlength="20"
  [counterFormatter]="customCounterFormatter"
></ion-input>

@Component(...)
export class ExampleComponent {
  customCounterFormatter(inputLength: number, maxLength: number) {
    return `${maxLength - inputLength} characters remaining`;
  }
}

As soon as you add a class member, the code breaks, as the function looses the this context. It's not beginner friendly, and results in combersome code.

For example, when adding internationalization:

export class ExampleComponent {
  translated: string = "characters remaining" // probably injected dynamically

  customCounterFormatter(inputLength: number, maxLength: number) {
    return `${maxLength - inputLength} {this.translated}`;
  }
}

This now results in an error: Exception in provided 'counterFormatter', as this is not bound when ionic calls the formatter callback.

Describe Preferred Solution

Introduce an

interface CounterFormatter {
    format(current: number, limit: number): string
}

It should be possible to pass an object of type CounterFormatter to the counterFormatter attribute on the ion-input.
We prefer this solution because it is the most explicit one.

Describe Alternatives

Either

• callback.bind(component) to the component before calling the callback inside the ion-input (100% backwards compatible, but not as explicit)
• change the example to include a call bind or an arrow function

Related Code

No response

Additional Information

This change can also be applied to all callbacks, for example PinFormatter on ion-range, or ion-textarea.

[hakimio]

Another possibility could be to use <ng-template>:

<ion-input
  [counter]="true"
  maxlength="20"
>
    <ng-template 
        counterFormatter 
        let-maxLength="maxLength" 
        let-currentLength="currentLength"
    >
        <b>{{ maxLength - currentLength }}</b> {{ translated }}
    </ng-template>
</ion-input>

[liamdebeasi]

Thanks for the report. Can you please provide a reproduction of the original issues you are seeing? In particular, I'd like to see what happens when you do not use bind.

[hakimio]

https://stackblitz.com/edit/angular-zvtvh7?file=src%2Fapp%2Fexample.component.ts

[liamdebeasi]

Thanks for the additional information. While I understand this behavior is not desired, Ionic is working correctly here. The customCounterFormatter is being called in a difference scope outside of ExampleComponent, so it will not have access to the ExampleComponent scope by default. This is how this works in JavaScript.

I recommend reading https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Operators/this as it has a lot of helpful information regarding this behavior. In particular:

When a function is passed as a callback, the value of this depends on how the callback is called, which is determined by the implementor of the API.

Setting .bind(this) will work here as you are binding the value of this which will be ExampleComponent. Arrow functions also work because a new this binding is not created.

[johannesvollmer]

Sorry if the issue is not formulated clear enough. We understand how this works. This is not a bug in the ionic code, you're right with that. Instead it's a pitfall that everyone using ionic must account for, instead of it 'just working'.

When a function is passed as a callback, the value of this depends on how the callback is called, which is determined by the implementor of the API.

The one calling the callback is the ionic framework. Therefore it is the responsibility of ionic to call the callback with the appropriate this value. Currently, ionic does not set this on the callback.

One of the proposed solutions is that ionic binds the component to the callback. This would make the code above work automatically.

in ionic, some code is calling the user-provided callback:

ionic-framework/core/src/components/input/input.tsx

Lines 617 to 624 in 516b844

	private renderCounter() {
	const { counter, maxlength, counterFormatter, value } = this;
	if (counter !== true || maxlength === undefined) {
	return;
	}
	return <div class="counter">{getCounterText(value, maxlength, counterFormatter)}</div>;
	}

instead, ionic should bind the appropriate this value:

getCounterText(value, maxlength, counterFormatter?.bind(componentModel))

Because the official ionic docs show us that the formatter should be located in the component model, it only makes sense to bind that component model as the callback's this. Most likely, the bind call should already happen when the callback is first retrieved from the element attributes. This way, ionic doesn't need to carry around a reference to the element.

If this is not possible, the interface could accept an interface instead of a contextless function, which would automatically use the correct this value. And if this is not possible, at least the documentation can be changed to point out this behaviour.
Example:

<ion-input label="Default counter" labelPlacement="floating" [counter]="true" maxlength="20"></ion-input>

<ion-input
  id="custom-input"
  label="Custom Counter Format"
  labelPlacement="floating"
  [counter]="true"
  maxlength="20"
  [counterFormatter]="customCounterFormatter.bind(this)"
></ion-input>

Can you re-open the issue or should we create a new one?

[liamdebeasi]

When a function is passed as a callback, the value of this depends on how the callback is called, which is determined by the implementor of the API.

The one calling the callback is the ionic framework. Therefore it is the responsibility of ionic to call the callback with the appropriate this value. Currently, ionic does not set this on the callback.

How the callback is called is determined by the implementer of the API, not the callback caller. I'll use the MDN example to clarify:

function logThis() {
  "use strict";
  console.log(this);
}

[1, 2, 3].forEach(logThis); // undefined, undefined, undefined

The API is forEach, and the implementer is the person writing the code and passing logThis. That person would be responsible for setting .bind(this) (or using an arrow function). All forEach does is call the function that it was passed.

In the context of Ionic, the API is counterFormatter, and the implementer is the application developer. All counterFormatter does is call the function that it was passed. Ionic has no way of knowing about the calling context (the Angular component's class) unless it's provided by the developer. Doing counterFormatter?.bind(this) inside of ion-input would cause this to refer to the ion-input class, not the Angular component's class.

---

In any event, I think it's worth updating the documentation to clarify this behavior. I can work on getting a PR up to note this.

[johannesvollmer]

I just think it's stupid that Angular forces you to use classes, but at the same time doesn't bind instance methods automatically.

In this angular code:

<ion-input
[counterFormatter]="customCounterFormatter"
></ion-input>

@Component(...)
export class ExampleComponent {
  customCounterFormatter(...) { ... }
}

The custom counter formatter is looked up from the typescript component - but it's not automatically bound to the component. This seems stupid to me, because Angular does look into our ExampleComponent instance either way, but then doesn't go all the way.

If Angular worked like this: formatter="this.formatter", then it would be obvious that the caller needs to bind manually.

I see it's the fault of Angular, and I understand if ionic doesn't want to fix their issues.