ractivejs / ractivejs.github.io Goto Github PK

From ractivejs/ractive#2909

The blog isn't that much. Two intro-like posts, two comparison posts. Both can be sections in the docs, the former being the "principles of Ractive" and the latter being "comparison to other frameworks".

Found them buried in the data binding section. Needs exposure like the rest.

Things like bubbling, mappings, vtree and those concepts are hard to explain textually. They end up being a wall of words at best. It might be a good idea to provide sketches and diagrams of the concepts to aid explanation.

Ascii art works too.

One of the highlights of Ractive which influenced the design of Vue is single-file components. However, it's mentioned... nowhere!

<div>My component markup</div>

<script>
component.exports = {
  // component definition
};
</script>

<style>
// scoped styles
</style>

The only places this is mentioned is in the component-spec repo and various loader tools. It would really be nice to put this in the spotlight to enforce the single-file, everything-in-one-place, component mentality.

Previously, there was a dropdown menu to select your Ractive version for documentation purposes. On the new website, that appears to be gone. I am working on a project that uses Ractive 0.4.0, and while we are planning on upgrading, it is useful to have the website provide that documentation in the meantime.

Any chance this can be brought back?

Because todo lists are too mainstream and are really very contrived examples. Need something that goes beyond 2-3 components and have a lot of data flowing through its veins. Suggestions are:

• Email client interface (architecture exercise)
• Hacker news front end (multi-component exercise)
• Live Twitter feed (data streaming exercise)

Because when we learn, we often start by just copy-pasting code, see if it works, then tweak from there onward. It would be beneficial to first-time users to make all example code written in this manner for ease of learning.

Recommended that we write in ES6 and constructors. Component files would have been great, but they need loaders to work, which doesn't go well with copy-pasting. ES6 is already widely supported, so it should be fine.

Something like:

const MyComponent = Ractive.extend({
  data: () =>({
    foo: 'bar' // Yep, a really nifty way to write function-style data.
  }),
  template: `
    <span>{{foo}}</span>
  `
});

new MyComponent({ el: 'body' });

• Explain how the csp option works.
• Explain the workflow for avoiding CSP warnings.
• csp docs mention serving the template on <script> but no example given.
• csp templates are not JSON-compatible. Explain how to serialize/unserialize.

Missing bind(this) on setTimeout callback. 😉

ractive.animate() map arguments no longer supported in 0.8 but this one got through without a deprecation warning and remained on the docs. Might be a good time to validate all APIs if they're all still valid and update the docs accordingly. This will be a huge effort testing each and every one, but one that needs to be done before 1.0 anyways.

_{This is a really good reason to merge docs into the lib repo like originally proposed. That way, any changes to the API will be accompanied with updates to the docs. But that's for another day. (Mkdocs is designed with that in mind btw 😉 . Notice how the docs is essentially just a docs dir, a mkdocs.yml, and nothing more? 🙂 ).}

Tracking items to be updated as they're pushed to dev.

Tutorials TODO:

1. Hello, World
2. Nested properties
3. Expressions
4. Events
5. Conditional sections
6. Iterative sections
7. Two-way binding
8. Partials
9. Triples
10. Components
11. Animation
12. SVG
13. Transitions
14. Decorators

API Docs TODO:

1. Update init options
2. Update static properties
3. Update static methods
4. Update instance properties
5. Update instance methods
6. Update helpers

Other TODO:

• Make the landing page a little less "this is just the docs site and not the homepage of the library".
• Rearrange the menus a bit to be less overwhelming
• Redirect http://www.ractivejs.org/ to https://ractive.js.org/
• Decommission old repos:
  • https://github.com/ractivejs/docs.ractivejs.org
  • https://github.com/ractivejs/ractivejs.org
  • https://github.com/ractivejs/cdn.ractivejs.org
  • https://github.com/ractivejs/blog.ractivejs.org
  • https://github.com/ractivejs/examples.ractivejs.org
  • https://github.com/ractivejs/learn.ractivejs.org

Hi,

Let's say something changed between v0.8 and v0.9. Where should I modify the doc?
Does it also have vN.N branches? Is dev corresponding to "edge" and master to "latest"?

That information should definitely be added in the Readme.md to avoid that people modify the wrong "version".

What I'm kind of missing from the old docs is the "edit this page" link on top. This was very handy and makes it easier for people to make a change. I tried to see if it can be done with mkdocs, but it only worked with the "readthedocs" theme, not with cinder nor mkdocs.

ractivejs/ractive#2938

It also seems magical really how Ractive "detects" data dependencies without being told explicitly, like in computed properties. And I've never encountered it on the docs either. Dependents does not speak of it https://ractive.js.org/concepts/data-binding/dependents/.

The bottom third of https://ractive.js.org/concepts/templates/references/ which explains the different keypath prefixes and special @ values should be moved to their own sectoins in APIs for visibility. Page should also be written similar to properties pages to take advantage of anchored links and the sidebar menu.

The references page should just link back to these new pages to avoid content duplication.

For the stuff found under Extend, the starter code under the Writing section is different for each kind of plugin. Would be nice to make the snippets consistent (register them all globally maybe?) and a bit more complete (add more options in the snippet for a quick copy-paste action).

Might be a good topic to cover in the concepts section. It's one of those buzzwordy things that get mentioned by frameworks but rarely discussed in documentation.

• What is the runloop?
• Why is the runloop needed?
• What role does it play in Ractive?
• What things get queued up in the runloop?
• How does execution get affected?
• How is it similar to Angular's digest cycle or Ember's runloop or React fiber.

I have a gut feeling that at least transitions and animations get queued up here, but I don't have the details at the moment to the entirety of the concept.

• https://ractive.js.org/Concepts/Rendering/Progressive%20Enhancement/
• https://ractive.js.org/Concepts/Rendering/Server-Side%20Rendering/
• https://ractive.js.org/Concepts/Security/CSP/

Not sure how to do this. But if we sunset the old site and remove the repos, how does it affect search engines? What's the best way to do this?

The playground isn't functional because of the new theme. Creating this issue for tracking purposes (read: someone is on it, don't worry. 😄 ).

Assigning to self because I believe in the rule of "You break it, you buy it" 😛

Currently trying out karma-benchmark when I wondered if a method call from a template is synchronous or asynchronous. If it is synchronous, that's fine. If it is async, I have to tell Benchmark.js that it is and I should resolve the benchmark deferred in the method.

Made me wonder what other things run sync or async. Methods that return Promises are obviously async, but there might be methods that return nothing, but run async.

It would be nice to document which ones and why they do it.

Because it's very handy. Beware of the indexing issue though mkdocs/mkdocs#859

Evident on pages that have a lot of headings:

• https://ractive.js.org/API/Initialization%20Options/
• https://ractive.js.org/API/Instance%20Methods/
• https://ractive.js.org/API/Helper%20Objects/Node%20Info/

It's a Cinder limitation, but I'd like to inform whoever is doing theming to be aware.

When the https://ractive.js.org/ battlestation is operational

• Redirect http://www.ractivejs.org/ to https://ractive.js.org/ for a certain period of time
• Remove and redirect the old repos to this repo to avoid confusion
  • https://github.com/ractivejs/docs.ractivejs.org
  • https://github.com/ractivejs/ractivejs.org
  • https://github.com/ractivejs/cdn.ractivejs.org
  • https://github.com/ractivejs/blog.ractivejs.org
  • https://github.com/ractivejs/examples.ractivejs.org
  • https://github.com/ractivejs/learn.ractivejs.org

learn.ractivejs.org will eventually become the "REPL" that will make ractivejs/ractive#2861 possible.

Whilst browsing https://ractive.js.org/concepts/data-binding/#observers, I noticed an issue with one of the statements:

"Ractive implements pub/sub with ractive.on(), ractive.off() and ractive.fire(), ractive.off() and ractive.fire - see Events for more info."

It's a minor issue, but unless I'm mistaken, it looks like part of the sentence has been duplicated? I think it should read "Ractive implements pub/sub with ractive.on(), ractive.off() and ractive.fire() - see Events for more info."...

ractivejs/ractive#2925

• What sections require explicit matching close (i.e. {{/if}}).
• What sections only require a simple closing mustache ({{/}}).
• What sections allow comments in the closing mustache.
• How closing mustache comments are handled.

They appear collapsed. Clicking on the link to open the nested dropdown will cause the browser to leave (reload the page) and you won't see the links at all.

• Avoiding CSP warnings by pre-compiling.
• Avoiding CSP warnings when doing SSR.
• Avoiding expensive computations.
• Avoiding destroying entire subtrees.
• moar stuff...

Hi,

IMHO the "new" documentation is fairly daunting. It feels overwhelming. 😯
Please don't take it as a critique, it's just sooo much content.
I've no silver bullet for that either.

🤔 🤔 🤔

Perhaps making it more "goals oriented" rather than a dry reference, and moving all the technical stuff a bit deeper.

Similar to Wikipedia. Wherever it feels right, link a key word in a page to the actual page that writes about it. That way, it's easy to get around the docs without looking for the term on the navigation (although the search does a pretty awesome job already).

From ractivejs/ractive-events-tap#22 (comment)

Not a user of the short @.* so I forgot about that. The array-style proxy is something I wasn't aware of.

I once brought up the issue that the component spec and template spec be brought into the docs. Might NOT make sense after all since they're... specs, must be versioned for historical purposes.

However, it would be nice to give a 1-page overview each how the component file structure and the template AST works, why it's done that way, why it came to be. The technical details can remain in their respective repos.

The Tools section would be a good place for it.

So there's a basic usage page that serves as a home page. Wondering if we still need the 60-second setup. If we do, then we should copy it over 😄 http://www.ractivejs.org/60-second-setup

Going through concepts, there are some parts that repeat what the API and Extend sections already discuss. It would be nice to draw the line which section explains what:

• APIs - Should talk about the API itself (the function/property, args, types).
• Extend - Authoring and usage of plugins.
• Integrations - Authoring and usage of tooling.
• Concepts - Underlying functionality and implementation details.

ractivejs/ractive#2921

It would be nice if the examples provided, aside from copy-paste-able and demo-able, reflect real-world use-cases for the concept being presented. I find that sometimes, library documentation (not specifically Ractive) can be very annoying if only very trivial scenarios are provided.

The menu collapses into this small box on top. Not much help on small screens. The pages are short (as intended) and the API is alphabetically sorted. So I'm not sure a side bar that appears on top would be of help.

Fairly straightforward but daunting task as there are a lot of pages. Migrate the old docs (0.3 - 0.8) to a directory in this repo and convert them to vanilla Markdown. Specifically, these are the things to do:

• Copy over docs from https://github.com/ractivejs/docs.ractivejs.org

• Remove the yaml header and convert the title into an <h1> title.

  ---
  title: Some title
  ...other stuff...
  ---
  
  to
  
  # Some title
  

• Remove \ from escaped {{ }}. This was to work around to prevent Handlebars from giving special treatment to {{ }} which our examples use a lot.

• Replace the {{ createLink }} helpers with Markdown links. Take note of the syntax of the helper and adjust accordingly.

• Merge the pages in the same way as the new docs (i.e. move methods in one file, move properties in one file, etc.) so we don't have to deal with a lot of pages.

The big goal is to make the docs portable by converting them to vanilla markdown. That way, should we hate the documentation generating tool or the workflow, we can easily move off to another tool that consumes markdown without reworking the contents. This also makes the files readable in plain text as well as on Github.

Since mkdocs is a potato and doesn't support versioning, there's no good way to reference the legacy docs in the current site. For now, we'll just stick everything in a legacy directory in the repo, forward everyone to it and have them read straight off of Github until we find a good approach.

Had a little time to play around with it. Wanted to keep Ractive's "green" theme going, but make it a little more vibrant and exciting... maybe too much? Not sure yet.

A laundry-list of missing apis and configs

• ondestruct
• ractive.once
• Args placeholders (see #64 (comment))
• Server-side rendering
• Migrations up to 0.7
• Ractive's CLI (at least an overview)
• arguments available on on-* expressions.
• Anchors (<# ... >)
• Which parts of Ractive are sync and async
• Document the existence of the regular build, the runtime build and the ES6 build.
• Interpolators (see: https://gitter.im/ractivejs/ractive?at=59720f084bcd78af56d165d7)
• CSP
• The allowExpressions init option.
• ractive.link()'s third argument.
• ractive.resetTemplate() ractivejs/v0.x#188
• Ractive.parse() missing options?
• Context object properties and methods (some appear to be missing?)
• Backticks argument syntax for transitions and decorators (and maybe more) ractivejs/ractive#3028
• Progressive enhancement
• The recently exposed static methods (findPlugin and friends)
• Document why css is component-only at the moment.
• Examples. Examples everywhere!

It seems that MkDocs doesn't officially support multiple versions in docs. I think we can probably sunset docs prior to 0.7, but we should probably keep edge and the previous two releases or two years of releases or something like that?

This and other links referenced as guidance in the actual warning provided by ractive are inaccessible.

Please restore them.

Stub pages are already present at docs/Get Started/Examples/. Just a matter of moving over the text from https://examples.ractivejs.org/ into the pages and formatting them. I also would like to keep the docs in vanilla markdown for exportability into PDF/epub formats.

So options are:

• Just link to an external demo. JSFiddle/JSBin/CodePen would be good candidates.
• Embed the external demo into the page. I'm not sure what's required to embed a Bin.

Scroll to the very bottom of http://www.ractivejs.org/

Come to think of it, I've never come across a page that explains how Ractive scopes CSS.

From ractivejs/v0.x#188

Per Gitter conversation, docs is:

• Perceivably too wordy.
• Too docs-like.
• Not as interactive as the old site.
• Other stuff (see convo starting at https://gitter.im/ractivejs/ractive?at=59034f22d32c6f2f094cb6ef)

Opinions are highly welcomed 😄

Since home pages are the most important one for a lib, we might want to consider:

• move the "rainbow chat/stat bar"in the middle of the page to the footer, or somewhere else?
• replace "About Ractive" with a "Why Ractive".

Why Ractive could mention that Ractive is a true template engine based on Mustache, and show a snippet comparing a Mustache template vs a "custom attribute" based one. To me this is the main selling point of Ractive and new users should be able to see if this is to their liking or not.

I don't know the landscape well enough to know what other "unique" features Ractive provides. Perhaps it is more dynamic? Dynamic components for example?

From ractivejs/ractive#2864