search

aurelia / documentation

The documentation for Aurelia.
MIT License
105 stars 110 forks source link

Documentation Needs #181

Open plwalters opened 8 years ago

plwalters commented 8 years ago

Docs Plan

A Web Developer

JeroenVinke commented 8 years ago

I would like to see more about custom DOM events, and the differences between delegate and trigger and why bubble must be enabled when raising a CustomEvent.

EisenbergEffect commented 8 years ago

@JeroenVinke Good feedback. I believe that would be great content for "Binding: Basics"

EisenbergEffect commented 8 years ago

In the article "Templating: Dynamic UI Composition" we not only need to cover things like compose but we need to talk in depth about how to use the compiler directly to do more customized, dynamic UIs.

EisenbergEffect commented 8 years ago

In the article "Binding: Basics" we need to make sure to include information about when ref binding values become available. Previously they weren't available until the attached lifecycle callback, but as of the Beta they are now available earlier in the bind lifecycle callback.

EisenbergEffect commented 8 years ago

In the article "Templating: HTML Behaviors Introduction" we need to cover a bit about the general mechanism that underlies both Custom Elements and Custom Attributes. As part of that we need to talk about bindable. We should be sure to cover how that works when used as a field decorator and make sure to include examples of supplying options in that case.

jdanyow commented 8 years ago

binding basics: delegate vs trigger cc @JeroenVinke

EisenbergEffect commented 8 years ago

We should include your SO answer direction in "Binding: Basics"

adriatic commented 8 years ago
EisenbergEffect commented 8 years ago

For "Binding: Basics" be sure to demonstrate how contextual properties work, particularly in the case of call bindings.

EisenbergEffect commented 8 years ago

@adriatic Are you referring to using our docs technology to document 3rd party Aurelia plugins and us providing docs on how to do that?

adriatic commented 8 years ago

Are you referring to using our docs technology to ...

Yes - as we are about to finish the document set for http://aurelia-ui-toolkits.github.io/demo-kendo first preview and would love not to continue rolling our own

stevies commented 8 years ago

It would be useful if the documentation was searchable. And if the section headings were linkable.

EisenbergEffect commented 8 years ago

That's in development. Search will take a bit longer but section linking is coming very soon.

ostyn commented 8 years ago

A lot of questions in gitter are centered around the transfer of data in/out of custom elements and in/out to the parent element. There are several different ways to do this(singleton service injection, passing in callbacks, injecting the parent into the child, getting the parent element and getting the view model off of that, message passing, etc.) and it's not clear when to use which, or even which options are available.

Should there be a portion of documentation for best practices for this and other commonly asked questions?

EisenbergEffect commented 8 years ago

@ostyn What if we added a topic on "Cross Component Collaboration" and covered different techniques and practices?

adriatic commented 8 years ago

What if we added a topic on "Cross Component Collaboration" and covered different techniques and practices?

A very strong vote of support for this proposal

stevies commented 8 years ago

@ostyn @EisenbergEffect - that would be great. This is something I have been wrestling with recently - combining simple custom elements into more specialised composed elements. I can get things working, but really not sure of best practice here - then there are not too many good examples to copy.

ostyn commented 8 years ago

@EisenbergEffect That would be excellent. I'm glad that others agree.

EisenbergEffect commented 8 years ago

I've added it to the topic list above.

egeland commented 8 years ago

Something I think should be in the Web Developer section: "how to start an aurelia app from scratch", i.e. from "I have npm installed" to "aurelia starts up and can be used".

Basically, it'd be about "how we built the skeleton app".

I'm sure it's not just me who are interested in exactly how things fit together but find tearing the skeleton down tedious and would rather see how to build it up from nothing..

adriatic commented 8 years ago

@egeland - you can find this information (and a lot more) in the Aurelia Guides - website that hosts all accumulated Aurelia Community authored articles.

Note that all these articles are pre-beta and would need to be refreshed, assuming that there is any interest in that data

smolinari commented 8 years ago

Here are a couple more suggestions.

Please get the contributor section done first, so others can join in and follow the rules properly to help build up and get this huge...chore..um....job... :smile:...done. If I knew what the contribution process was, I'd also like to help, where I can.

Sorry, this means more work, but add an API reference section explaining the different services/ options/ interfaces etc. offered in Aurelia. I am not even sure those are the right terms, but as a good example of what I mean, please see VueJS' API page. http://vuejs.org/api/

Add a Tutorials section, where contributors can go through certain steps to make something real with Aurelia. These could also be posted as guest blogs on the site too (as added incentive). If you want to take this even further, have a look at Laravel's Laracasts for a good example. https://laracasts.com/ Laravel isn't the best framework, but it is very good and even better, they do a great marketing job and thus, Laravel is the most popular PHP framework by far currently.

And an extra suggestion not really part of this thread, but more a general marketing kind of issue. It would be befitting to the whole project to get the blogs onto the aurelia.io site. :smile:

Scott

activebiz commented 8 years ago

+1 for search option.

Thanood commented 8 years ago

I'd like to read an article about component styling, also regarding ShadowDOM and style encapsulation (if that's possible).

Also I'm very interested in the contributor section. :smile:

Cortrah commented 8 years ago

Hi Folk,

Thanks for asking for our input. You guys are really doing great work.

In the architecture section, I think the "building on web standards" section is particularly important. Especially with Es6 Modules and Web Components (nice to see that web components repo show up recently). Following Aurelia through gitter and the blog has been like following a test case for the state of modern javascript. If you can pull together that story into a small section that always expresses the current state of things, I think it will provide a nice window for folk to approach the framework. Much of this information appears in gitter and blogs, but gets stale fast and the overall picture gets fragmented. Having one spot that summarizes things and is always up to date might require a lot of work, but would be very valuable.

In terms of technical content, offline data storage and sync is, I think, one of the main reasons for using a client side framework. I'd put a section on it right after http with fetch.

Right after the two of them and before binding might be a small section on where to put, or how to structure one's data. Aurelia seems pretty agnostic on this, focusing on just being flexible, which is fine, but a reference to skeleton navigation that maybe adds structure to maintain the state of both the router and one child component locally would tie things together nicely before getting into the details of templating.

For what it's worth. Thanks again for asking.

EisenbergEffect commented 8 years ago

I've added some additional topics and created a new section

Using Aurelia Components as Web Components How to Build the Skeleton from Scratch Binding Engine Architecture and Extensibility Templating Engine Architecture and Extensibility Router Architecture and Extensibility Structuring and Organizing Your App

Cortrah commented 8 years ago

PS I love the cheat sheet

And it looks like the docs repo is being done with gitbook, if I could download a version every so often to put on my kindle for when I'm walking the dog that would be awesome.

thanks again for all

bischofb commented 8 years ago

I was struggling with how to call call $('.form').validate() when the page loads b/c activate() is called before the view model is built and DOM elements are undefined. I finally found an obscure comment about an attach() hook being called after activate() and tried that. Works! It would be REALLY NICE to have more page lifecycle hooks documented better b/c the only hooks discussed are canActivate() and activate(). It took me forever to discover the attach() hook being mentioned on a random post.

smolinari commented 8 years ago

Correction on my part. I failed to find this section of the docs. http://aurelia.io/docs.html#/api/home

So, one less suggestion to worry about. :smile:

Scott

EisenbergEffect commented 8 years ago

We have those docs here: http://aurelia.io/docs.html#/aurelia/framework/1.0.0-beta.1.0.7/doc/article/creating-components But perhaps it's worthwhile to create a separate doc that lists all possible events for both components and router and explain what does and does not happen, when, etc. I'll add a topic for this.

bischofb commented 8 years ago

Thanks for the link. I was looking at the cheatsheet under "Screen Activation Lifecycle" which only listed a few hooks. Might be good to reference that it has the same hooks as components or copy/paste them to the Screen Activation Lifecycle section as well. :-)

gheoan commented 8 years ago

I suggest renaming App Configuration and Startup to Configuration and Startup.

giovannicandido commented 8 years ago

I would like to see a article about testing components, attributes, etc.. with and without dom. Unit test is simplified by the dependency injection, we can mock the objects and test the units methods in isolation, the trick part is to test behaviour that depends on DOM using karma, and almost all custom components and attributes manipulate DOM elements.

danlourenco commented 8 years ago

@giovannicandido +1

tvld commented 8 years ago

Excellent work. Wish it was all here today;) I just wish there was some Doc about the Server and Database side of it as well. While it may be outside Aurelia scope, we do need to write real Apps and a standard server side approach is essential for both newbies as well as a common testing understanding...

Svenskunganka commented 8 years ago

@tvld There isn't much to the server- & database-side of Aurelia right now (until the planned SSR is available). You can use the fetch-client or http-client to consume a simple CRUD RESTful API, and there's not much more to it as of now. It's just like how you would write apps with jQuery's $.ajax method.

Although it's probably a good point to add some examples for how fetch-client could work with a simple CRUD RESTful API.

tvld commented 8 years ago

@Svenskunganka Thank you. I think yes, some pointers and examples of DB&Server framework could still be helpful. New people with a blank sheet like to choose the "common denominator" in a new eco-system. We would like an increased chance others might be able to help when stuck and more coherent testing.

That said, it seems on this I am on my own in Aurelia and might need to adopt child on my own ;)

vegarringdal commented 8 years ago

Suggestions, but might be covered in the other topics A Plugin Author

How to do it and not what to do. The docs plan looks great btw, cant wait for it all

Thanood commented 8 years ago

I'd love to see a good explanation of nesting templates/elements correctly. I've just run into this trap: https://github.com/aurelia/framework/issues/250

:smile:

adriatic commented 8 years ago

You are tempting the "adventurer" in me - but I am firmly following my decision to finish the on-line help documents for the pending KendoUI bridge 0.3.0 release

gheoan commented 8 years ago

Events emitted by Aurelia should be documented (ex: aurelia-composed).

ajoslin103 commented 8 years ago

Nowhere are there examples of how to log at the different levels - in the entire docs I could find only two usages of console.log

How do you use the logging capabilities of the framework?

Thanood commented 8 years ago

In my opinion it would be useful to have a guide on how to implement a custom observer, since that seems to be best practice in cases where dirty checking would kick in, at least if @computedFrom doesn't fit the case. Just as an example: "how to observe a ImmutableJs collection". Unfortunately I tried and failed to do something like this. :smile:

Or more general: "How to prevent dirty checking".

EisenbergEffect commented 8 years ago

@Thanood That sounds like a great idea. @jdanyow I was hoping you could write two more binding articles. We have "Binding: Basics" listed above and now I've added "Binding: Advanced Scenarios" which I think would be a good place to discuss that @Thanood is talking about and possible a number of other recurring scenarios.

jdanyow commented 8 years ago

sounds good- will get started on these

ckotzbauer commented 8 years ago

Until when the documentation for the Durandal migration is planned? Perhaps in conjunction with Knockout?

EisenbergEffect commented 8 years ago

We have a preliminary document here: https://github.com/aurelia/documentation/blob/master/old/English/durandal-to-aurelia.md We would love PRs on that document to flesh out the content.

niieani commented 8 years ago

@EisenbergEffect I'd add one more article on advanced repeater usage, including stuff like using matchers to optimize array view replacement. I can try to write that at some point in the future.

kabaehr commented 7 years ago

Hey, I would wish for some guidance on how to write a binding behavior. I tried to do it with some older examples from @jdanyow but it was quite hard and I gave up.

avrahamcool commented 6 years ago

I recently have tried to implement animations between pages in my app using swap-order on the router-view, and I found the current docs to be insufficient.

we have a few words on this in the routing section - but the way from there to a simple working demo was not possible without intimate knowledge of how aurelia works based on year of experience, new aurelia developers on my team would never be able to accomplish that task on their own.

the missing key part was "If there is no animation defined, then swap-order has no visible impact." I could not find an example of how to define such animation.

in this issue I can see that the section Animation: Basics is still not covered, and I would like to create it and update the docs.

I thought of splitting it to fragments (I've checked the parts that I'll be covering):

there are 2 animation plugins available.

that can be later expanded to also include explanation regarding aurelia-animator-velocity and the missing parts.

@EisenbergEffect where is the correct place to put this new fragment of documentation?