The “new Getting Started” is untangled. Looking forward the remaining part.😀

How should an ident for a singleton look like? E.g. a session data? Should I just pretend there may be multiple of them, invent some meaningless key, have ident return something like [:session/by_id :_] and let untangled normalize it to {:session/by_id {:_ { ... data ...}}}even though there never will be more than one? Or is there some trick/convention for situations like this? The “fake key” should work just fine, it just feels odd.

@bbktsk You can take a look at how it's in the untangled template. https://goo.gl/l7Vc6S

@bbktsk There is query notation for pulling something from root, so that it can just be at the root

[ {[:keyword '_] (om/get-query Session)} ]

The underscore (which has to be quoted to keep the compiler from whining) means “singleton at the root”

when used in an ident

The join isn’t necessary if there isn’t nested normalized state there

Exactly what I needed, thanks.

you could just say: [ [:keyword '_] ] and that will give you the opaque thing at root

when you use these link queries to root, you’ll get :keyword in props, so destructuring is easy

if you join on a real ident, the thing you’ll get in props will be (of course) keyed by that ident.

which of course is how you could pull a specific item from a table: [ {[:person/by-id 1] (om/get-query Person)} ]

@bbktsk One word of warning. If a component queries for nothing but a thing from root, then you still must include some initial state for that component (or the query won’t even try to walk to that node)

just an empty map is enough

@eric.shao Thanks. working on it now, actually.

OK, the new Getting Started Guide is nearly complete. I’d love any proofreading feedback. REST stuff is still coming.

https://github.com/awkay/untangled/blob/develop/GettingStarted.adoc

Stuck again, this time on routing. Is it possible to have a single router with some routes that have a parameter and some that do not? The example in https://untangled-web.github.io/untangled/guide.html#!/untangled_devguide.M15_Routing_UI has top_router with all routes without param and report-router with all routes with a param. Also, how’d I pass multiple params to a route? :route-params in route-to takes a map, but route-instructions takes an ident and there’s place for only one param… Also, I do not understand the role of ident method of a router. A router has the map of keyword->component, so what does it need the ident for?

ok, let’s start with the ident question

You’re routing over various sub-components, each which needs an ident, and query

the router, however, uses what’s called a Union query, so that only one component’s query is processed (for speed): the one that is on-screen

it figures that our from the TABLE (type) of the ident that is pointing to the current thing on the screen

So, the router (union query component) gets the ident function

and it must work for all sub-screens

and furthermore it must generate the correct first-element of the ident (one of the keywords that names you screen)

It’s a lot of little gotcha’s, but such is the price of performance on the queries in a large UI 🙂

The params are intended to become the “ID” of the ident (generally), thus potentially routing you to specific instances of screens

Ofcourse, your mutation that triggers the route, should also make sure the newly-targeted screen data exists

It is expected that a given router (route instruction) will be setting one and only one ident in the app state (pointing to that particular UI switch in the routing tree)…so there is no place for another param to go

The implication is that an HTML5 route of /accounts/4/child/5 would map to a tree that has an account and child router. The account router would receive 4 as a parameter, and child 5.

so, two routers to switch, two routing instructions, but ONE event trigger to do the routing

so route-to is meant to switch multiple routers at once, via your routing tree.

which is why it needs possibly multiple parameters

I see. So yes, I can mix parameter-less and parameter-having routes in a single router, but it’s ident must be smart enough to generate correct value depending on current route?

correct

(defrouter X :x (ident ...) :screen-1 Screen1 :screen-2 Screen2)

the ident better generate idents of the form [:screen-1 ???] or [:screen-2 ???]

the ??? are up to you @bbktsk

and your state of Screen1 and 2 better have some way of letting the ident function figure that out

Anyone trying out the getting started: I refer to the developer’s guide. I have not updated the dev guide to the latest cleanup of the lib yet, so names may be wrong.

OK, the REST example is in the GettingStarted.adoc guide now.

https://github.com/awkay/untangled/blob/develop/GettingStarted.adoc#using-a-legacy-rest-api