You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
For the final release of Clearwater 1.0, I want the docs to be ready for people to jump in and start writing Clearwater apps confidently. This issue is the one issue to rule them all, and in the tracker bind them.
Since the docs app is a Clearwater app, all pages need to be components, but we can figure out the content here in the issues with Markdown to make it simple[1].
Here are the things I was thinking of documenting. There are a lot of things here, but most of them are individual methods to document, so a lot of them can be crossed off very quickly. As always, suggestions are most welcome:
Design
It looks kinda dumb. Any ideas to make it better?
Guides
The Ember JS site has a "Guides" and "API" section and I absolutely love that idea. That way we can separate high-level overviews from "here's how you need to define/call this method".
HTML5 tag names as shorthand methods to create virtual-DOM nodes. For example, div(properties, content) delegates to tag(:div, properties, content).
#tag(attributes={}, content=nil)
#call — re-render all Clearwater apps mounted in the registry
#params
DOMReference
Proxy for a Bowser::Element that gets populated on DOM render
Link
Link.new is nearly the same as Component#a. Only difference is that Link components have their click events trapped, but a tags are unmodified.
Router
#route(path_segment => target, &block)
#params
VirtualDOM
.node(type, attributes, content)
.create(virtual_node)
.diff(from, to)
.patch(dom_element, diff)
Bowser
Clearwater uses the bowser gem as its browser abstraction. Clearwater apps will need to interact with some of its objects, so we'll document them here since it's also a Clearwater project.
Bowser::Document
#body
#[]
#create_element
Bowser::Element
#inner_dom= — provided for compatibility with
#inner_html
#children
#empty?
#clear
#remove_child
#type
#append
#checked?
#files
#file
Document delegation to native element
Bowser::Event
#target
#prevent
#stop_propagation
#prevented?
meta? / alt? / ctrl? / shift?
#to_n — this is an Opal convention for "to native"
Bowser::File — An entry in a FileList
#name
#size
#type
#last_modified
#read
Bowser::FileList — the files property for an <input type="file" /> element
#[]
#length / #size
#to_a
Enumerable mixed in
Bowser::HTTP — AJAX support
#fetch(url, method: :get) — we should make this work just like ES6 fetch, but this is what it does atm.
For the final release of Clearwater 1.0, I want the docs to be ready for people to jump in and start writing Clearwater apps confidently. This issue is the one issue to rule them all, and in the tracker bind them.
Since the docs app is a Clearwater app, all pages need to be components, but we can figure out the content here in the issues with Markdown to make it simple[1].
Here are the things I was thinking of documenting. There are a lot of things here, but most of them are individual methods to document, so a lot of them can be crossed off very quickly. As always, suggestions are most welcome:
Clearwater::CachedRenderApplication(Application #4)#call(&block)— registers an app with the Clearwater app registry and renders it#render(&block)— re-renders an app#render_current_url(&block)— wires up components based on route, re-rendersBlackBoxNode#node— override to define the initial structure of the component#mount(element)— called by Clearwater just before this object is added to the DOM#update(previous, element)#unmount(element)CachedRender#should_render?(previous)Component(Component #5)div(properties, content)delegates totag(:div, properties, content).#tag(attributes={}, content=nil)#call— re-render all Clearwater apps mounted in the registry#paramsDOMReferenceBowser::Elementthat gets populated on DOM renderLinkLink.newis nearly the same asComponent#a. Only difference is thatLinkcomponents have theirclickevents trapped, butatags are unmodified.Router#route(path_segment => target, &block)#paramsVirtualDOM.node(type, attributes, content).create(virtual_node).diff(from, to).patch(dom_element, diff)bowsergem as its browser abstraction. Clearwater apps will need to interact with some of its objects, so we'll document them here since it's also a Clearwater project.Bowser::Document#body#[]#create_elementBowser::Element#inner_dom=— provided for compatibility with#inner_html#children#empty?#clear#remove_child#type#append#checked?#files#fileBowser::Event#target#prevent#stop_propagation#prevented?meta?/alt?/ctrl?/shift?#to_n— this is an Opal convention for "to native"Bowser::File— An entry in aFileList#name#size#type#last_modified#readBowser::FileList— thefilesproperty for an<input type="file" />element#[]#length/#size#to_aEnumerablemixed inBowser::HTTP— AJAX support#fetch(url, method: :get)— we should make this work just like ES6 fetch, but this is what it does atm.#upload(url, data, content_type: 'application/json', method: :post)#upload_files(url, files, key: 'files', suffix: '[]', method: :post)#upload_file(url, file, key: 'file', suffix: nil, method: :post)Bowser::WebSocket#initialize(url)#on(event_name, &block)#send_message(message)Bowser::Window.delay(seconds, &block).interval(seconds, &block).animation_frame(&block).scroll(x, y)[1] What would be awesome would be a pure-Ruby Markdown parser that could output Clearwater components rather than HTML, but we're not there yet. :-)
The text was updated successfully, but these errors were encountered: