Documentation Needs

[plwalters]

Docs Plan

A Web Developer

• What is Aurelia?
• Getting Started
• A Production Setup
• Creating Components
• Dependency Injection: Basics
• Templating: Basics
• Binding: Basics
• Router: Basics
• Animation: Basics
• App Configuration and Startup
• HTTP Services
• Binding: Value Converters
• Binding: Binding Behaviors
• Binding: Advanced Scenarios
• Templating: HTML Behaviors Introduction
• Templating: Custom Attributes
• Templating: Custom Elements
• Templating: Dynamic UI Composition
• Templating: View Resources
• Dependency Injection: Customization
• Cross Component Communication
• Router: Customization
• Securing Your App
• Structuring and Organizing Your App
• Unit Testing
• End-to-End Testing
• Bundling Your App for Deploy
• Summary: Conventions
• Summary: Lifecycles
• Cheat Sheet
• Glossary
• Errors
• Getting Help

Deep Dive

• How to Build the Skeleton from Scratch
• Binding Engine Architecture and Extensibility
• Templating Engine Architecture and Extensibility
• Router Architecture and Extensibility

New To Web Development

• What is Aurelia?
• Modern JavaScript and TypeScript
• Modern Tooling
• The Modern DOM
• Getting Started
• Next Steps For New Web Developers
• Cheat Sheet
• Getting Help

A Manager/CTO

• What is Aurelia?
• Aurelia's Technical Benefits
• Aurelia's Team and Community
• Aurelia's Business Advantage
• Onboarding Your Developers

An Architect

• What is Aurelia?
• Aurelia's Technical Benefits
• Aurelia's Architecture
• Building on Web Standards
• Team Workflow
• Composite Applications
• Aurelia's Business Advantage
• Onboarding Your Developers

A Contributor

• Contribution Guidelines
• Your First Pull Request
• Creating or Editing Documentation
• Translating Documentation
• Testing Documentation

A Plugin Author

• Plugins: What and Why?
• Creating a Plugin
• Publishing a Plugin
• Adding Your Plugin Docs to Aurelia's Docs

Integrating with Other Technologies

• Integrating with jQuery
• Integrating with Polymer
• Using 3rd Party Web Components
• Using Aurelia Components as Web Components
• Integrating with CSS Frameworks
• Using RequireJS and Bower
• Building a Cordova/PhoneGap App
• Building an Electron App
• Building an NWJS App
• Building a Windows Universal App

A Migrator

• Migrating From Durandal
• Migrating From Angular 1
• Migrating From Angular 2
• Migrating From Caliburn.Micro

[JeroenVinke]

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]

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

[EisenbergEffect]

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]

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]

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]

binding basics: delegate vs trigger
cc @JeroenVinke

[EisenbergEffect]

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

[adriatic]

• Under Web Developer section
  Integrating Aurelia Help component with third party (Aurelia of course) applications
• Under Integrating with Other Technologies Identity Management (see Auth0-Angular as an example)

[EisenbergEffect]

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

[EisenbergEffect]

@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]

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]

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

[EisenbergEffect]

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

[ostyn]

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]

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

[adriatic]

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]

@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]

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

[EisenbergEffect]

I've added it to the topic list above.

[egeland]

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]

@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]

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... 😄...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. 😄

Scott

[activebiz]

+1 for search option.

[Thanood]

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. 😄

[Cortrah]

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]

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

[gheoan]

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

[giovannicandido]

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]

@giovannicandido +1

[tvld]

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]

@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]

@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]

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

• Adding css

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

[Thanood]

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

😄

[adriatic]

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]

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

[ajoslin103]

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]

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. 😄

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

[EisenbergEffect]

@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]

sounds good- will get started on these

[ckotzbauer]

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

[EisenbergEffect]

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]

@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]

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]

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):

• 1. install the animator plugin.
• 2. define animations that can be later hooked to your elements.
• 3. hook your animations to your views using the swap-order attribute.
• 4. hook your animations to arbitrary elements with arbitrary hooks.

there are 2 animation plugins available.

• 1. aurelia-animator-css
• 2. aurelia-animator-velocity

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?

[EisenbergEffect]

@avrahamcool This is very exciting. You've certainly identified an important missing piece from our docs. We apologize for the inconvenience and would absolutely love your help in improving this. Thank you for volunteering.

To make contribution easier, we've recently moved all our docs back to this repo. To add the new content, simply create a new Markdown file and add it under current/en-us/plugins. You'll need to name the file with a number, as this represents the ToC ordering. Once we merge the PR, we'll be able to publish it to the site shortly thereafter. That's all there is to it.

On animation in general, while we didn't have a doc article, we did have an old blog post which I recently thought I might update and transform into official docs. You may be able to use it to help you put together what you are working on. You can find it here: https://aurelia.io/blog/2015/07/17/animating-apps-with-aurelia-part-1

Do you have any further questions? Is there anything I can do to help you in this process?

[avrahamcool]

@EisenbergEffect
I'm trying to create a little demo in codesandbox.io, to demonstrate the basics of animation between views.

I need to have some css in place.
I didn't succeed in adding a regular css file and simply require-ing it in my template.
in the meantime I created a regular component (.html) with a <style> tag in it, it works as expected.
is there an other way to do this the right way?

[EisenbergEffect]

@avrahamcool CodeSandbox uses a custom, webpack-like but not webpack, bundler internally, so it can behave oddly sometimes. For CSS, I'd recommend just inlining it like you have above or you an create a CSS file in the public folder and just link it into the head of the index.html page. That's what we did for all our binding docs demos.

[avrahamcool]

@EisenbergEffect I've forked the documentation repo, and committed my changes there.
but I don't feel like it's ready to be merged.

I'ts the first time I try to document something, and when I read it back - it feels very clunky (I jump between thing that I need to explain, and its not well organized).
also: the github page is not rendered as the official docs will eventually be - so I'm hoping i didn't screw-up anything (as I don't have any way to test this, aside from comparing to other parts of the docs and try to mimic them)

I tried to copy the relevant parts of the blog post you have mentioned above, but he has a lot more details that I wanted to go to.
I feel like I've barely touched the capabilities of the animation plugin - I just demonstrated a simple use case of what it can do.

so maybe someone on the core-team can pass on the documentation that I created and make it better?
I added a working demo based on the TODO application from the aurelia home page - with all kinds of animations - feel free to make it better if you see fit.

[EisenbergEffect]

@avrahamcool If you want to go ahead and submit a pull request, I can take what you've done and polish it a bit and get it out in the next release.

[avrahamcool]

@EisenbergEffect done.
I've created a PR with wip, but i wasn't sure if you can merge it, so I changed it - but it's still need to be polished.

thanks you for all your time and kind replies.

[avrahamcool]

animation: basic can be checked now :) (in the list above)