Pimp docs with good/bad practice section

[maberer]

Create a "good/bad practice" section in the docs

Please use this issue to add stuff that should be placed in that section.

[maberer]

Good practice In most cases, a handler method is for a single event source Bad practice: The same handler used from different event sources; even worse: from a DOM and custom event source.

[maberer]

Good practice: always put event.preventDefault() for DOM events at the end of the handler. This ensures graceful degradation in case the handler is broken

[maberer]

About having a central store (app architecture...)

Good practice: I think the right thing to do is for only the top-level UI component to connect directly with application state, but there is nothing stopping you from having nested UI components listen directly to a central store. Add 1: Personally, I think it is okay if multiple UI components share the same state as long as the shared state was derived from the same input. Add 2: If you can divide up your UI into multiple and independent parts so that each part is backed by a separate data store then I think that would be beneficial, but that will vary by application

[philidem]

We should cover the directory structure as a best practice.

For components: src/components/**

For pages: src/pages/**

[philidem]

Also, file naming:

• index.js
• renderer.js
• widget.js
• style.less, style.css, etc.
• template.marko

[patrick-steele-idem]

One UI component per directory. Only one w-bind attribute should be used in a template. See: https://github.com/marko-js/marko-widgets/issues/95

[patrick-steele-idem]

Declarative event binding > JavaScript event binding

[maberer]

Create a section "Marko/Marko-Widgets" in production. List all prerequisite / important details that are helpful when somebody wants to launch a site in production.

Statement @patrick-steele-idem : Answer to Question: I suspect that on the production machine the node_modules were all flattened and that that broke some of the relative paths that were generated on your development machine.

If you are sure that the project structure is exactly the same between the deployment machine and the production machine then it is better to precompile since there is a cost to compiling templates at runtime (reading from disk, parsing HTML, etc.). However, in most cases you won't notice the compilation cost at runtime since a template is compiled once at startup.