Improvement in the way the package is presented

[steph643]

I have the feeling this package would get more users if the way it is presented was improved.

First, I think the name of the package and the name of the github repo should match. EDIT: and the name of the API entry point (currently ReactiveForms).

Second, I think the package should be renamed from 'templates:forms' to something more unique, like 'jonjamz:forms' or 'circus:forms' (use case: "I use the form package from aldeed, what form package do you use? I use xxxx").

Third, I think the documentation should emphasize more why people should use this package and how easy it is. I will post a draft here.

[jonjamz]

I think the best way to emphasize why people should use this package is to create a much better set of examples and, as you say, improve the docs.

For example, check out this screenshot from Virgin America's flight ordering process:

While I haven't built a replica of this using templates:forms, I'd imagine that building this element would be almost impossible with AutoForm, where it would be much easier with this package.

Why? Because templates:forms lets you do pretty much anything you want using the normal Blaze syntax and doesn't break. It also gives you flexibility with how you handle/transform events before data gets validated and saved in the form's data context.

And, you can add your own set of helpers onto any element or form block template and they'll stack with the ones this package provides--just like any Blaze template can have more than one call to Template.helpers.

A note on the real-time pricing in that screenshot:

I think I'd have to make the form data context reactive and easily accessible through a helper, but it's possible that providing real-time pricing information based on a user's selections is easily achievable, even now.

[jonjamz]

Thanks for thinking about this, and I look forward to seeing your ideas!

[steph643]

Here is the draft: https://github.com/steph643/meteor-issue-3194/blob/master/old/README2.md Please let me know your thoughts.

[jonjamz]

I think this is a great starting point for new docs. Very clear. I really like your examples. :+1:

[steph643]

Thanks. Please post here as soon as you make changes to the doc and I will be glad to proofread.

[steph643]

An additional note about examples and package marketing:

I am quite sure you alienate half of potential users if you have sample code in CoffeeScript.

See this typical discussion.

I think package authors who want to promote CoffeeScript without alienating anyone should go double-language.

[jonjamz]

Sure--but my examples are all JavaScript.

Unless you're talking about the live example, which indeed is CoffeeScript. I should fix that...

I have no problem going double-language, it just takes up a lot of space. Perhaps the new docs could also exist on a separate website where I could use the templates:tabs package for this.

[steph643]

Well, it was just long-term consideration and a precaution for new coming examples. I don't think it is urgent to fix the live example, and maybe it could stay as it is if more examples are provided. Regarding double-language, it is a lot of effort that might be best invested in revamped doc, new features and maybe changing the schema layer.

[BrooklynC]

If I could add my two cents here, as a compete novice...the new draft of the readme would help a lot. I'm learning how to write code as I build an app and have been relying heavily on SimpleSchema and Autoform to do so. Everything I have read elsewhere sounds like template:form is the easier way to go, but the current docs are pretty daunting (especially for my relatively simple use case). This new doc would make it much easier for me to get on board. Is the draft accurate for me to rely on?

[jonjamz]

Somewhat accurate, although some of the naming is off (for example, the package name is still templates:forms and basicFormModel is actually basicFormBlock.

I'm working on a pretty big update to the package this weekend so I'll adjust the docs too.

[ryandeussing]

Late to this discussion, but I here are my two cents:

• the live example that you link to should be an easily found-and-cloned repo, so new users can really kick the tires locally
• all example code (including the above) really should be javascript, as noted above

Thanks!

[jonjamz]

Now that this latest update is out, I'll spend some more time fixing up the docs and working on examples.

[jonjamz]

Check out the in-progress docs for v2.0.0 including many examples and guides. Feedback appreciated.

[steph643]

Wow, that looks great!

[priojk]

I find the new documentation excellent. Did not yet have time to look into all details, but it appears now really well structured and straight forward. Very good job!

[7ammer]

Hey @jonjamz any update on when documentation will be officially ready? I think the Meteor community would greatly benefit from it! I find this package to be a breath of fresh air compared to the overly verbose Autoforms package.

Let us know if you need any help :)

[jonjamz]

Basically all that's left before I put up the new docs is to make sure the API methods have the right names. I also need to test out the examples, particularly some of the more complex ones.

[7ammer]

Brilliant news! :) I just tested AdjustableNumberOfInputs. When changing a field value it seems to output this error: Uncaught RangeError: Maximum call stack size exceeded - module.js:705 I think the error is coming from validationValue but I'm not sure.

The field that it was using had a schema like this:

foo:{
   type:[Object],
}

[jonjamz]

@7immy thank you for helping with this! Let's continue this discussion in issue #92.

[7ammer]

:+1: