Ideas for Documentation and Examples

neversettle commented 11 years ago

I love what you've done with Phreeze - amazing work! - and I can't get up to speed fast enough! :) I've watched the tutorials (probably need to again), looked through what there is of documentation, cruised through a bunch of these issues trying to glean nuggets, generated an app and played around with the code a bit. But I still think I learn faster by having examples in front of me.

Are there any other apps that you (or others) are able to share as examples? I'm particularly interested in the end result of adding custom functionality beyond the basic CRUD stuff, and I've never worked with backbone before. I want to preserve the ajax throughout and leverage the existing thought you've put into Phreeze (I don't want to brute force something the hard way when there's an elegant and faster way already). The types of things I'd love to have examples on:

Master / Detail - even chained so that that one master updates several details and cascaded so that a master updates a detail which then updates another detail off that
Adding actions inline with the data rows (like in action column/s, but currently the ajax intercepts and it just launches the modal form no matter what you put in there)
Using the modal form to launch creation of new records in related tables that auto-populate some fields from the row that was clicked
A full database authentication example (maybe the FB authentication example covers this? I still need to look at that code, and I could reconstruct something from all the conversations on authentication, but it would be nice to have a single working example as a starting point)
Additional pages that showcase different UI using backbone and more Phreeze specifics
Global search
etc.

I know it's way more tedious to produce, but I find the Documentation more useful than the Video tutorials (it's not always easy to see the code in the videos depending on quality / screen size). Then again, though, existing working examples would be even better than Documentation. Even diving a little deeper into the structure of the app I generated I'm seeing places that begin to hold answers to my own questions. But it would be great if there were more examples that would save me time without costing anyone else a lot of time - examples that already exist.

Anyway, thanks for this amazing tool. I can see the vast potential once I'm up to speed with the frameworks. Just hate the learning curve and want to fly with something as soon as I discover it :) All the best, Andrew

jasonhinkle commented 11 years ago

Fantastic - thanks for checking out Phreeze. It sounds like you are really interested in the relationships between the models, as am I. To be honest, I consider myself to be only slightly above average level with backbone. From what I have learning by looking through the code is that it actually doesn't deal with complex model relationships like a traditional ORM does. It doesn't know when you change one thing - that relates to another. It does it in a more simple way between models and collections. But it doesn't do that between models that are related through, say, a foreign key. But, I do think the backbone.js event system can be used to wire that up yourself though. I'm 100% sure that the code generated for Phreeze apps could be improved greatly and take more advantage of what bootstrap offers, so I will look forward to anything you find out about that.

That being said - there is code in Phreeze which is sitting there mostly unused which makes the collection respond instantly to changes in the model. If you look at view.js there is a parameter in the ModelView and CollectionView called "handleModelChange" which if you enable it - then you will see things become more responsive and interactive. That would be a good place to start looking and maybe customizing a bit.

The thing is with Phreeze I feel like it's not always clear that the generated code is just one possible, very basic app that uses the technologies. It has a lot of my own opinions in there and it isn't really intended to be a final app. Although, ironically, I think the generated app is pretty slick and so I understand why people see that it is pretty close to being usable as-is. But, the main purpose of the generated app is to be a starting point.

As far as examples - if you do setup and watch the Facebook tutorial, I think that is pretty advanced and goes into a lot of concepts. If you can get through it and understand everything - which I don't think is that difficult - you'll have a really good understanding of Phreeze and the auto-generated code.

neversettle commented 11 years ago

Thanks! I totally get the starting point concept with Phreeze and realize there are so many ways to achieve the same things. That's fantastic. It's also a pain when it's brand new though :) I'm still trying to wrap my mind around the whole structure. As a concrete example: using the basic built in authentication what would the easiest / fastest way be to secure an entire app? I tried adding

 $this->RequirePermission(ExampleUser::$PERMISSION_ADMIN,
                'SecureExample.LoginForm',
                'Login is required to access this app',
                'Admin permission is required to access this app');

in AppBaseController.Init(), but not surprisingly this resulted in an infinite loop as the LoginForm would also trigger that condition. I tried various conditions to then check if the LoginForm was being accessed to exclude that like this:

if ($this->GetRouter()->GetUri() == 'loginform') {

and that worked to reach the login form but I can't login (probably because another controller is hitting the RequirePermission before the user is logged in and added to the session).

I feel like I'm missing something totally obvious, but am spinning my wheels, and thinking this has to be a super simple answer. Thanks!

jasonhinkle commented 11 years ago

Gotcha. Well, I've done exactly what you've done as well - put the authorization in the base controller and then just exclude certain routes. In the example you would need to exclude three routes: LoginForm, Login and Logout. (in your code it looks like you may have excluded the login form, but not the route that is processing the login form)

Another thing that I do is I add the authentication on a per-controller basis instead of in the base controller. That way you can have public and private controllers. So, the home page, the login page, logout, etc can all be in a controller that is not locked down. The only danger of this is that you have to remember to put the authorization code in the Init method of each controller that you want to be private. But, I find this isn't too difficult to remember and gives you flexibility if the site is partially public and partially private. You can also use that to divide up sections that require different permissions (like a regular user vs an admin user)

Lastly you can do your authentication on a per-method basis, but I don't recommend this for large apps because obviously you have to remember with every new method. Although this does give you very granular control over authentication.

Hope that makes sense?

neversettle commented 11 years ago

Definitely makes sense!!! And thank you so much for providing so much help to folks getting started with this. I know what a time suck it is, believe me. I added login and logout to the router exceptions and I'm off to the races. I did consider doing this on a per-router basis, but this is a prototype app and especially while I'm destroying things in the process of learning I don't want / need any public / private sections - I just want to lock down the entire app even as I roll into beta with only specifically granted users having any access at all. Love the flexibility for later though.

Here's my final version in AppBaseController in case it will help anyone else:

protected function Init()
    {
        // TODO: add app-wide bootsrap code

        if (!($this->GetRouter()->GetUri() == 'loginform' ||
              $this->GetRouter()->GetUri() == 'login' ||
              $this->GetRouter()->GetUri() == 'logout')) {
            $this->RequirePermission(ExampleUser::$PERMISSION_ADMIN,
                'SecureExample.LoginForm',
                'Login is required to access this app',
                'Admin permission is required to access this app');
        }
        else {
            // let the request through for user functions
        }

    }

Thanks again! Might have to pick your brain here soon again, but this was a big hurdle holding me back, and now I just have a lot of playing and learning to do. I think this is going to be great.

Seems a little sluggish on my local machine for fairly simple queries on the refresh between routes, but not sure what all the factors might be there. Maybe I'm just impatient :)

jasonhinkle commented 11 years ago

awesome! i'm sure that will help some people.

as far as speed - it could be on the client side, loading the various javascripts. once your app is done you can minify everything into one script and speed it all up.

you can test to see if the queries are running slow by going directly to an api endpoint like, for example: localhost/cargo/api/customers (obviously putting in your own app and controller names). I really love the JSON View plugin for Chrome for checking out the api endpoints: https://chrome.google.com/webstore/detail/jsonview/chklaanhfefbnpoihckbnefhakgolnmc

jasonhinkle / phreeze

Ideas for Documentation and Examples #66