Example is to complex

[pythoneer]

I really just started to take a look at the project today but had it on my TODO list for quite some time. I like the current backbone_app showing the various features. But unfortunately it is quite complex and a little bit intimidating. There is just to much stuff going on to really understand the basics. The reader has to comprehend to much features at the same time to make sense out of it and has to "jump" around to different places. I have the same critique for the README. It is a little bit unstructured and mixes between explanation/example/tutorial, project goals and motivation.

I am wondering what the best approach is to help improve the situation. Fortunately i am in the position to be an absolute noob in regard to the project and have the opportunity to write down what i find puzzling and what i would like the project to better explain to me.

I think it would be really helpful to have more simpler examples that are distilled down to one or two concepts at a time with a little deeper explanation. What i have in mind:

• [ ] Basic Routing. No guards, no views, no attributes except maybe #[default_route], no query etc. because – to be honest – i don't really know how this is working in the first place. How does router().current_route().view(model) even finds the right view function and how does e.g. in case of Login/Admin in your example calls the init function with the parameters from the enum?! So i think there is some naming convention and code generation in the RoutingModules derive macro going on that for every enum variant there needs to be a corresponding module with the right name for the router to call?! This example should make this mechanism clear.

  #[derive(Debug, PartialEq, Clone, RoutingModules)]
  pub enum Routes {
  #[default_route]
  Page1,
  Page2,
  Page3,
  }

• [ ] View and Guard Attributes. Just as an extension to Basic Routing and explain what exactly is happening with the syntax of the attributes. #[view = " => not_found"] is replacing the "default" behavior and invokes a custom function that gets the model and needs to return Node<Msg> (like your typical view function). Same with the #[guard = "logged_user => admin_guard => forbidden_user"] with a more elaborate explanation what the specific parts of the syntax are doing. <submodel> => <guard_function> => <negative_view> . I would also encourage to rename some functions in the examples. Seeds example are very strictly name every "view" function view_xyz. I guess its also a good idea to make the same with guard functions guard_xyz

struct Model { sub_model: i32, }

[derive(Debug, PartialEq, Clone, RoutingModules)]

pub enum Routes {

[default_route]

Page1,
#[guard = "sub_model => guard_admin => view_forbidden_user"]
Page2,
#[view = " => view_not_found"]
Page3,

}

//#[view = " => view_not_found"] the place is empty it gets the full Model fn view_notfound (: &Model) -> Node { ... }

// #[guard = "sub_model => guard_admin => view_forbidden_user"] it only gets a sub_model not the hole thing fn guard_admin(sub_model: Option) -> Option { ... }

//#[guard = "sub_model => guard_admin => view_forbidden_user"] it only gets a sub_model not the hole thing fn view_forbiddenuser (: &Model) -> Node { ... }

- [ ] Query and Parameters (maybe sub paths ... ). Basically what Login and Admin are doing in the existing example/readme. Show how the resulting paths should look like (maybe that has already been happening in the basic example) and how that is influencing the parameter list of the corresponding `init(...)` functions and that theses are passed to it.
```rust
#[derive(Debug, PartialEq, Clone, RoutingModules)]
pub enum Routes {
    page1 {
        query: IndexMap<String, String>, // -> http://localhost:8000/page1?name=JohnDoe
    },
    page2 { // -> /page2/:id/*
        id: String,
        children: pages::page2::Routes,
    },
}

... some more examples this is just a first rough list of how i see them ...

We could extend the list but this is the way i would imagine to create more and simpler examples. Each explains – in detail – what one or two features (or more if they are closely related) really do without cluttering the code with a dozen other things that would distract the reader. seed-routing has many features which are hard to grasp at first.

I would like to create those examples as a way to get myself familiar with the project but i would like to know if you think this is a good idea before extending the above "rough" shape of what that examples would entail.

[arn-the-long-beard]

Hi. Thank you for the feedback ! It is well appreciated to have the eyes from somebody who has more experience. I will take a look at your post more in detail tomorrow !

[arn-the-long-beard]

It is a little bit unstructured and mixes between explanation/example/tutorial, project goals and motivation.

Thank you for your input !

I would like to create those examples as a way to get myself familiar with the project but i would like to know if you think this is a good idea before extending the above "rough" shape of what that examples would entail.

Yes it is , let's fire a PR regarding the examples !

I can work on the Readme then and make it more structured as well :wink:

[Ben-PH]

Just came back to the project. I think these ideas are good. The idea I had was to build up the backbone app with a workshop, similar to the proc macro workshop.

Start by providing a basic skeleton. It has the CSS and html but not the functionality. Implement functionality 1 by one.

Another way, and this would be simpler to implement (so might be good to do this first), is to do a series of examples that start from nothing, working its way up to implementing the backbone app (or something similar).

I'll put the work up on a new branch as I go.

[arn-the-long-beard]

Yes, good start! Keep me updated, I think this process is very important, also for us as well in order to prevent over engineering the library.