Add a FAQ section to the docs.

[patrick-steele-idem]

Please provide good candidate questions here!

[maberer]

Starting with this one - please change the questions if necessary...

• Is there a difference between reuse and preserve in the context of marko? Long version: The docs mention the terms "reuse" and "preserve". In the context of marko-widgets, their might be some subtle differences between these two - please explain/give examples, when to use one or the other.
• How far should a UI be "componentized"? Long version: Basically everything can be made into its own component (down to a single word/character) - now as we have the powerful tools to create components it would be nice to have a set of best practices that help to decide, when to stop.
• When should the body of a custom component be used? Long version: Marko template engine uses xhtml style standalone tags as a shorthand like <my-component/> . While this is great to write compact tags, it sometimes leads to confusion, when to use the body of a component. As basically everything can be put into a component by further "componentizing" the UI - there should be some rules/best practices that help to decide, when/what should be placed in the body of a component...
• Which component functions are invoked at what time - whats the order of invocation? Long version: There is e.g. init(), getInitialState(), getTemplateData() - which functions are called during first render, re-rendering etc... --> we might even be helpful to put something like that into the docs...

[patrick-steele-idem]

That's very helpful, @tindli. Thank you! Those are great questions and I'll definitely make sure the new docs address all of those questions. If you come up with any more questions please add them here.

[maberer]

• Marko-Widgets supports the batching of updates, but what does this mean to the developer? Long version: Describe, how multiple setState() are handled and what benefits this provides.
• What is a bad example of a component, that leaks its state? Long version: encapsulation and a well defined interface should be the goal when designing marko widgets. Please provide an anti-example, that demonstrates, when/how these goals are not met and what can be done to meet the requirement. What are signs that show that something is wrong?
• How do widgets communicate? Long version: Please provide best practices for inter-widget communication (events, calling functions from a parent in a child). Mention the global event bus (raptor-pubsub) and the solutions it is meant for.
• Why is state so important for marko-widgets? Long version: Please mention the core differences (from an architectural perspective) on the role of component state for marko-widgets compared to e.g. react. Component state is more than just a way to trigger the re-rendering of a component; it provides a way to detect, if a component needs to be re-rendered. Please mention shallow comparisons and the impact this has for developers (creating a new object instead of changing properties in case of nested javascript objects).
• How does re-rendering work and how to deal with widgets, that manage their own state? Long version: As the app-map component in the UI samples or simple html-inputs, some components require internal state that should not be lost when marko-widgets higher in the hierarchy re-render. Please provide the methods, that allow such a behaviour (w-preserve, ...)

[maberer]

• How is data management done with marko? Long version: Please describe the main differences between data layer architectures for comparable frameworks like react (like flux, relay...). While react has a top-down approach for data flow (giving data as props from parents to children, several levels down), I do not really see such a pattern in marko-widget hierarchies - it seems that widgets get/fetch their own state, at various levels in the component tree. For react, this is an anti-pattern; Please describe, why marko-widgets take this approach.

[patrick-steele-idem]

@tindli Can you please clarify the following?

What is a bad example of a component that leaks its state?

Also, I have added a partial FAQ based on some of your questions. Please take a look and provide any feedback: https://github.com/raptorjs/marko-widgets/blob/view-state/docs/faq.md

As soon as I get some more time I will add more of your questions.

Thanks again for providing these questions!

[maberer]

By leaking state I mean, that instead of an exposed function, a direct reference to the widget is used and the setState() call is performed from somewhere outside the widget that does not own the manipulated state...

If this is possible, we should avoid that... (right?)... In my understanding, only the exposed functions should be used to manipulate state (if this is required)...

[maberer]

I am really happy with the FAQ! Great job.

I only have one "concern" so far:

https://github.com/raptorjs/marko-widgets/blob/view-state/docs/faq.md#which-component-functions-are-invoked-at-what-time---whats-the-order-of-invocation

Additionally, I would add the information, which of the functions are invoked on the server too...

Keep up with the great stuff! Many thanks.

[maberer]

• What architectural layers (patterns) are applicable? Long version: Can be related to the data management statement above. Explain various types of architectural deviations an app might use. Please describe, why the todo example uses the "SAV Architecture", why it benefits from it and describe an example, where the SAV architecture would not be an obvious choice (e.g. blog or other app with lots of static data that should not go into state). Please make it clear, that marko/marko-widgets is agnostic towards any architectural pattern and implementation.