Ngx-formly: Documentation

[aitboudad]

• [x] Getting started
• [x] Properties and Options #819
• [x] Custom Templates #795
• [x] Formly Expressions
  
  
  
  • [x] Expression Properties
  
  
  • [x] Conditional Rendering
  
  
• [x] Validation
  
  
  
  • [x] Custom Validation
  
  
  • [x] Validation Messaging
  
  
• [x] Custom Wrapper @thorgod
• [x] StackBlitz integration (https://github.com/angular/material.angular.io/tree/master/src/app/shared/stackblitz)
• [x] Add a searchable API (already done, just need to be improved and remove some internal api.

[aitboudad]

This is the only part that prevent the v2 release, any help is greatly appreciated :)
\cc @juristr @beeman @FritzHerbers @davidoween @jogelin @Pat-Lovelace @iustin-nita

[Pat-Lovelace]

Sure! @davidoween and me can collaborate. Just tell us what you need ;) If you need any specific format to follow. We'll try our best ;)

[aitboudad]

glad to hear that, there is no format to follow, just a simple doc that explain Formly features, I had done two part now #795 and #819.
You can take whatever you want from the above tasks :).
Thanks in advance

[Pat-Lovelace]

would you need, for instance, a google docs, .md, or simply html?

[aitboudad]

markdown

[juristr]

👍I'm in. I'm just having a workshop the next 2 days at a client (maybe we'll touch Formly as well 😉) . I'll return home on Saturday. Then I'll give it a look, as well as my upgrade PR which is still open.

[mohammedzamakhan]

@aitboudad the home page says Built by the Angular team to integrate seamlessly with Angular. 🤣

I think we should change it to Built by members of Amazing Angular Community to integrate seamlessly with Angular. 👍

[aitboudad]

@mohammedzamakhan I think it's true :laughing:, since it's mainly based on the material doc repo

[juristr]

Haha, I think he's right. Built "by the Angular team" could be misleading, like if it was an official package from them :)

[davidoween]

As @Pat-Lovelace says, we will help

[FritzHerbers]

I used formlyJS over a year ago. Four months ago I researched to migrate to angular 5. The biggest killer feature was to find a library like formly. Googling around I found two libraries. So the following question arised

• how mature are the libraries
  As i didn't find a statement, had to dig into the sources and issues.
  A statement for people who migrate would be, that ngx-formly (https://formly.dev/) evolved from formlyJS and that it offers the same functionality.
  When I would have read it is based on Angular Reactive Forms I would have been quicker convinced. I am not interested in a 'proprietary' library that could stop working with a newer Angular version.
  At that time I didn't associate Angular with Angular 2+, so explicitly mentioning it would have helped me. It is only mentioned at github. (I researched at that time the library name and URLs changed, adding more confusion)
  A list of features (for example Material and Bootstrap support) and extensibility.
  A blog telling what has been achieved and what will be implemented in the future (especially for those people who want to come back).
  When I google for formly the first results are for formlyJS. Ask for a link on formlyJS to ngx-formly.
  Ask to add ngx-formly at https://angular.io/resources.

• documentation
  The guides page is good to get some high level feeling.
  Add a searchable API
  A good example I found 9 months ago was https://ui-router.github.io/ng2/docs/latest/classes/core.uirouter.html (especially having links into the source for members is great).
  Or like angular.io

• behavior / semantics
  What i really missed is to take examples into plunker or stackblitz. This would also help to report issues (or at minimum provide a base stackblitz).
  Tried changing the github link to https://stackblitz.com/github but got errors.

With formlyJS and also with ngx-formly it was time consuming what the library does with my data and behaves on 'external' field/model changes. Add some examples, like the model/field change issues I reported recently.
Information like (in the style of a FAQ): when I have a field but no model member, the model member is only created upon data entered.
To discover behaviour or the usage of a library I always read closed issues. It would be great to find hints (cans/cannots/cannotyets) provided in the issues find their way in a FAQ (or as I saw several times in new examples).

• contrib section
  Links to as-is user provided stackblitz examples (remembering back to formlyJS these where the biggest source for me how to integrate other libraries i used).
  Provide information how to create and report those examples to be added.
  Be one source of knowledge.

The above 'positive' criticism/ideas can be taken/used for every library. Hope some will be addressed for ngx-formly.

[mohammedzamakhan]

@FritzHerbers Thanks for the suggestions.

I think it would be great to have StackBlitz integrated in the documentation. 👍

Lets add to the topic @aitboudad

[Pat-Lovelace]

• [x] Validation
  I tried to explain Validation section. I have included the custom validation function and message grouped by ways to declare them. I hope this helps! :)

Formly.zip

[aitboudad]

@Pat-Lovelace awesome work :+1: , do you want to make a PR or you would prefer that I'll take care of ?

[davidoween]

• [x ] Formly Expressions. Completed

Sorry if I explained wrong. My English is a little bad
I hope this helps! :)

ExpresionProperties.zip

[aitboudad]

@davidoween many thanks :heart_eyes:!!!

My English is a little bad

The same for me :), without trying you'll never improve it.

I'm going to include Validation + ExpresionProperties in the docs.

[Pat-Lovelace]

@aitboudad Sorry, I'm on vacation, but feel free to change or add whatever you want ;)

[aitboudad]

added edit in stackBlitz :tada: :tada:

any volunteer for Custom Wrapper ?

[FritzHerbers]

Stackblitz, great!
Found out this work has been done on the next branch. How do I access the next branch demo site. I have an issue, so it would be nice to try it.

[aitboudad]

see https://aitboudad.github.io/ngx-formly/

[FritzHerbers]

The following possibility of validation failed:
Declaring your validation function in a formly type and message within your FormlyModule config:

Adapt wording and terms suiting you.

validation_using_formly_type.zip

[thorgod]

@aitboudad I will see what I can do about creating a Custom Wrapper on stackblitz

[thorgod]

@aitboudad Looks like you already have a custom wrapper (https://aitboudad.github.io/ngx-formly/examples/other/nested-formly-forms) working stackblitlz what would like like to me to do?

[aitboudad]

@thorgod yes why not!

[thorgod]

(maybe something got lost in translation) I think you want me to create some documentation & examples for the features related to the recent Pull Requests I created? Is this correct?

[aitboudad]

@thorgod I'm looking to create some documentation for How to create a custom wrapper similar to How to create a custom template

[thorgod]

@aitboudad Sure you can assign that task to me. I will take care of that today or tomorrow.

[thorgod]

@aitboudad I started work on it. Didn't have much time today busy with work; however, I will add more tomorrow. See bellow if you wanted to take over.

https://github.com/thorgod/ngx-formly/blob/master/demo/src/app/guides/custom-wrapper.md

[thorgod]

@aitboudad OK finished, can you add this file (custom-wrapper.md) with your next PR for next branch? And add it to the (guides.component.ts) (My fork is outdated)

https://github.com/thorgod/ngx-formly/blob/master/demo/src/app/guides/custom-wrapper.md