How should the public API be? We want your feedback

[tonivj5]

With the last PR (#57), the public API is going to change and it would be good opinions and way of to do this.

At the moment, the public API is something like this:
All events return an ExternalEvent (exported as InlineEvent) ->

{ 
  event?: Event, 
  state: { value: any, empty: boolean,  editing: boolean, disabled: boolean } // it's an InlineState
}

An state is the state of input when this one changed (the new state), for example: if I click an input, its state will change from editing: false to editing: true, and if I type 'a', its state will change from value: '' to value: 'a'. These states are in hot, until I do click on save, this changes will not reflect in the model (ngModel) and I will receive it using the events ((onChange)="todoSomething($event)", etc.).

• Events bindable
  • onSave
  • onEdit
  • onCancel
  • onError // This one returns an InlineError | InlineError[] -> { type: string, message: string }
  • onChange
  • onKeyPress
  • onEnter
  • onEscape
  • onFocus
  • onBlur
• Public methods (API) (with these methods you can change the state of input)
  • save( { event: Event, state: InlineState }: ExternalEvent )
  • saveAndClose( { event: Event, state: InlineState }: ExternalEvent )
  • edit( { editing: boolean, doFocus: boolean } )
  • cancel( { event: Event, state: InlineState }: ExternalEvent )
  • getHotState(): InlineState // This returns state from input (no saved)

Are the methods user friendly? is this the correct approach? Please, give us your feedback 👍

[KeithGillette]

Very excited to see these enhancements, @xxxTonixxx! The new inputs and event bindings are extremely useful.

We are trying to understand how to invoke methods in the API but I don't see any examples to follow nor documentation of the API. How does one get a reference to a given <inline-editor> instance to invoke the public methods?

[Caballerog]

@KeithGillette you would use the events the following way:

<inline-editor (onSave)="yourHandleSave">
<inline-editor (onError)="yourHandleError">
<inline-editor (onChange)="yourHandleChange">

[KeithGillette]

Thanks for the fast response, @Caballerog. I understand how to invoke my methods upon a given event from the inline-editor as you have shown. My question is how to put a given <inline-editor> instance into a given state using the public API methods (save(), saveAndClose(), edit(), cancel(), getHotState()) referenced above.

[tonivj5]

Thanks @KeithGillette for your interest! 😄

The actual documentation (the README) is outdated, so in this moment there is not any documentation or examples... It is the next step we want to do!

If you want to get an instance of InlineEditorComponent you should use the @ViewChild() decorator or defining the reference into the template and pass it like a function parameter (ex: <inline-editor #myInlineEditor (onBlur)="doSomethingUsingPublicAPI(myInlineEditor)"></inline-editor>

Here you have a complete code-example:

import { Component, ViewChild, AfterViewInit } from '@angular/core';
import { InlineEditorComponent, InlineEditorEvent } from '@qontu/ngx-inline-editor';
import { InputTextConfig } from '@qontu/ngx-inline-editor/configs';

@Component({
  selector: 'app-root',
  template: `
  <inline-editor #myInlineEditorInstance [(ngModel)]="test" [config]="config"></inline-editor>
  <inline-editor #myInlineEditorRefFromTemplate [(ngModel)]="test" [config]="config"></inline-editor>
  
  <button (click)="myInlineEditorRefFromTemplate.edit({editing: true, event: $event})">
    Edit the 2º inline-editor without create the property into class
  </button>

  <button (click)="myInlineEditorRefFromTemplate.cancel()">
    Remove  the editable state from the 2º inline-editor without create the property into class
  </button>

  <button (click)="logg(myInlineEditorRefFromTemplate)">
    Console.log of inline-editor's value passing editor by parameter to function
  </button>
  `,
})
export class AppComponent implements AfterViewInit {

  test = 'hi';
  
  // The input instance, it is available on AfterViewInit hook
  @ViewChild('myInlineEditorInstance') myInlineEditorInstance: InlineEditorComponent;

  config: InputTextConfig = {
    type: 'text',
  };

  ngAfterViewInit(): void {
    // the input became to editable and focused when the page load
    setTimeout(
      () => this.myInlineEditorInstance.edit({ editing: true, doFocus: true }),
    );
  }

  logg(inlineEditor: InlineEditorComponent) {
    const { value } = inlineEditor.state.getState();
    console.log(`This is the value of inline-editor getting the inline-editor instance from parameter: ${value}`);
  }

}

We would appreciate a lot your feedback! 👍

[KeithGillette]

This is outstanding. Thanks for the fast response and detailed example, @xxxTonixxx!

My use-case is a bit more complex, but I think I just figured out a solution.

Within the template for my component, we have dynamically generated InlineEditorComponent instances (inside of a treeview). I can dynamically assign each a unique id in the name property: <inline-editor [name]="node.id">, where node.id is a uniquely defined value within the parent element for each InlineEditorComponent instance. I can then also access an array of all InlineEditorComponents in the populated template in my controller:

@ViewChildren(InlineEditorComponent) private inlineEditorViewChildren: QueryList<InlineEditorComponent>;

In my methods, I can then perform a find on the QueryList to identify the correct InlineEditorComponent on which to invoke the public API calls:

public editNode(nodeId): void {
  const inlineEditorToInvoke = 
    this.inlineEditorViewChildren.find((inlineEditorComponent: InlineEditorComponent) => {
      return inlineEditorComponent.name === nodeId;
    });
inlineEditorToInvoke.edit({editing: true, doFocus: true});
}

[KeithGillette]

First, thank you, @xxxTonixxx and @Caballerog for this useful component and these recent API enhancements which have made it much more versatile.

Since you're requesting feedback on these changes, here are a couple of suggestions that have occurred to me in using the new API in my project:

Select on Edit

Add select boolean parameter to the edit method to select the value of the input:

.edit( { editing: boolean, focus: boolean, select: boolean } )

(I know the current property is doFocus, but I think just focus might be preferable. If you keep doSelect, then the new property should be called doSelect for consistency.)

Pass ExternalEvent on all event bindings

In my testing with the text inline editor, the bindable events pass different arguments to the bound methods. onEdit, onSave, onBlur, onEnter, onKeyPress, onChange pass the input value while onCancel passes the ExternalEvent object. The latter is much more useful, so I recommend using it as the argument passed for all event bindings. (With the original event, I could call select() on the srcElement in an onEdit handler, obviating the need for the first suggested change.)

Thanks for considering!

[tonivj5]

By order:

• Select on edit is a so good option to add and I think focus/select is better too 👍
• Really, you have discovered a bug (it should call the emit method, which returns the value or object ) 😅 We considered that approach, so we added a config option (onlyValue) and its value is true by default to maintain compatibility with the actual API. Here is used. If you set onlyValue to false, all events emit the ExternalEvent object 😉

And thanks a lot for your feedback, it make me so happy! 😄

[jesussegado]

Hi @KeithGillette @xxxTonixxx

I have added the select feature and fixed bug in cancel method
#65
#66

[KeithGillette]

Another bit of feedback on this extremely useful component:

I have discovered that one can pass additional arguments to the controller methods invoked by the public API from the template bindings, such as (onEnter)=onInlineEditorEnter($event, node) where node is some locally defined template variable. I am not sure whether this behavior is by design or accident, but I have found it critical to have when dealing with automatically generated inline-editor instances embedded in a component, so please keep it!