Can someone provide me an example of how to use SCHEMA?

[blaasvaer]

I've spent days now trying to figure both the concept of SCHEMAS out, and how to actually use them. I've been through all examples code, and the sparse documentation on the matter, but none of these have made it any more clear how to use them, let alone understand the benefit of them.

Now, a thorough tutorial on this subject would be VERY nice ... as they seem very conceptual to me.

Unfortunately aubergine10 stopped the development of this wiki: https://github.com/totaljs/documentation/wiki/Schemas

Which actually seemed to be pretty much what you'd need to understand the concept and the use of SCHEMAS.

So, a shout out to @aubergine10 in the hope he'd continue his work.

[petersirka]

I'm closing this issue...

[blaasvaer]

Why? Three thumbs up. I can't be alone on this.

[molda]

Hi @blaasvaer documentation https://docs.totaljs.com/latest/en.html#api~SchemaBuilder

The main benefit of schemas is validation of incomming data. Schemas can also be sort of a middleware between front-end and database since you can define methods for CRUD operations. Workflows can be used to chain multiple calls to procces incomming data.

Once you understand how to use and even abuse Schemas you will realize they are most important part of any aplication that works with database.

Make sure to check the documentation and have a look at total.js apllications on github since they all use schemas which you can find in models directory ( i know it's probably a bit misleading though )

Schemas are usualy used in this way: Incomming request->route(with a flag *SchemaName)->controller(using schema methods like $get, $save, $query, $workflow etc.)->Schema(returning data to controller)->controller(responding with json or rendering a view)

I'll be happy to answer any questions you or @TemaSM or @webdesus may have, so feel free to post comments here.

[blaasvaer]

My general problem with understanding SchemaBuilder is; that first, I don't know what it is that I'm defining doing schema.define( ... ). Why do I do that, what are they used for in the the Schema.

Next, I see things like: schema.setSave(function () { ... }). What does it actually do internally ... my guess is, that it sets a method somewhere that I can access from the controller using instance.$save ... ... but I totally miss the binding and the logic, so I feel absolutely crippled trying to get creative with it in any way. As I'm basically working in the dark.

The documentation should be MUCH MORE explanatory about what is actually going on. This is more of an API documentation, not really explaining the concept and the idea behind the architecture. Therefore it's pretty hard to grasp.

[blaasvaer]

I'd claim that this:

The SchemaBuilder is very helpful for models. You can validate and prepare data according to the schema. The SchemaBuilder supports transformations, workflows, validations and standard CRUD operations (READ, SAVE, REMOVE, QUERY).

is more like marketing, than actual documentation.

I still think @aubergine10 was on to something. Why don't you guys continue from where he left off? It looked promising ... and I also wonder why he abandoned the project in the first place ... hmm.

[blaasvaer]

And just to let you know; I've been through all the examples ... and only ONE (1) place could I find $get and from there on guess that that was how to interact with the schema from the model ... the link between the controller and the scheme, and the schema and the DB should be explained in much more detaill – a real world scenario would be a proper solution.

[webdesus]

These questions so many. I started doing small project, but i very slow move ahead, cuz documentation not always clear from the first time. And i begin found examples, read source, but it's too slow for development. I don't wanta sit in chat and ask stupid questions, cuz i know that owener busy, and he can make more job if he not will be read my stupid question. I think about find time and begin write docs, but in right now i so busy.

A few questions

How i can make CRUD with validation(insert many, update many)? How i can use model inside model? (i don't remember, but i think i have problem with this)

It would be great if we have docs like @aubergine10 but not for only ScheameBuilder.

Or in current docs api add opportunity see part of code for selected api

[petersirka]

Yes documentation is not perfect, but it's good. Each method/property/delegate has own description. Everyone can improve this documentation. It's very complicated to describe some practices because Node offers a lot of modules and then the biggest problem are lazy developers.

The entire platform of Total.js makes only the one developer with help of some another developers like Martin, Denis, etc.. We don't have any money, no investment, no big names, no big companies so just look on it from my side what I do. You have everything still free and it still not enough. Please help, please improve documentation or write blogs. If you don't have any time for it just send some money (e.g. 5000 $) and I trust me I'll invest them for better docs and tutorials. Really I do what I can.

It's not a problem to test some funcionallity without web server, just run it in Node:

require('total.js');

NEWSCHEMA('User').make(function(schema) {
    schema.define('name', 'String(50)');

    schema.addWorkflow('test', function($) {
        console.log('I am here!');
        $.success();
    });
});

$WORKFLOW('User', 'test', console.log);

Really, is it so complicated? I don't think so. You can perform a lot of tests for understading like my example above.

[webdesus]

I think formed a misunderstanding. We do not demand anything (at least I'm). Simply there is a real problem of documentation, because of which many can not take the library and start using it in real projects, because it is difficult for the superiors to prove that this library is really good.

Closing the issue means that there is no problem, although it does exist. I suggest opening the issue mark with tag "help wanted" and perhaps somebody who comes in the project recently will write docs. Or you can open a fund-raising to solve this problem. But at the same time I think that the @petersirka should not write documentation, because he knows his project 100% and it is difficult for him to understand the problem areas. Will do more useful if he continues to bring new features to the project.

To sum up: We did not want to offend the author, the project and other people, we do not demand documentation, but talk about the feasibility of an open issue with the problem of documentation.

P.S Sorry @petersirka i I did not want to hurt you. You make good project and you are doing continues make amazing job.I sometime i don't understand how you so fast response any questions. I know how is hard .And i have was plan return in the this project docs as a reward for your works. But right now i don't have free time((( But may be, sometimes, i will do it. If somebody I will not be surpassed.

[webdesus]

P.S.S Ordinary things are really simple, difficulties begin when you make to step to the side. And there the possibilities of total.js do not end. But unfortunately in these possibilities it is not so easy to understand

[blaasvaer]

@petersirka

Really, is it so complicated? I don't think so. …

Yes, it is complicated. And of course you don't think so – you wrote the framework.

Now, I understand that you get frustrated by us – the people actually trying to use your framework (and paying for the premium products in an effort to actually support you) – because you really do work hard on the project. No one is really questioning that.

Documentation is for:

Making people conceptually understand how to apply the technology to the issue(s) they are trying to solve.

Now, examples are fine, as long as they support an actual explanation of what you're trying to achieve. Examples alone is of little use. You may as well go:

Read the damn code.

API documentation on the other hand, is for:

A more detailed technical understanding of a given specific method or the like ...

When people try out a framework, they usually don't start by reading the documentation end to end – I for sure don't. I usually try it out on a small project (a TODO or whatever). And then learn the framework bit by bit by applying my ideas using the framework. Now, if the documentation is not written with that in mind, but simply just a dump of the methods (API), then it's really hard to get your head around how to apply certain functionality to a given situation.

Take a look at this for instance:

Now, I would claim that the extra description doesn't really add any value to the name of the property itself. It's a fine name; it describes what it would actually tell you, and being a developer the is part also tells you that it's probably a boolean value. But expecting people to understand how authorization works within the framework, let alone apply it, would be pretty bold from that bit alone (no pun intended).

Well, this is getting a bit long ... but I hope you get my point.

And basically I agree with @webdesus:

But at the same time I think that the @petersirka should not write documentation, because he knows his project 100% and it is difficult for him to understand the problem areas.

I'd suggest you enabled wiki on the framework repository here on github, and open sourced the documentation ... so that we can all help out improving on it.

[blaasvaer]

If there's one thing we've learned over the decades from software projects, it's:

Bad documentation will kill ANY project.

[qoole]

I entirely agree with the points raised in this thread. The documentation and examples are pretty poor. NOWHERE can I find documentation as to what the arguments to 'setGet'/'setQuery'/'set*' actually are/mean.

model? helper? controller? what actually ARE they.

@petersirka - from the point of view of the developer it'll be 'obvious' because you know the ins and outs of the product you have written. From an outsider's point of view it really isn't clear, and the documentation does little to nothing to enlighten us.

I am on the verge of ditching this framework because I cannot find how to do even the most basic things.

So many of the 'examples' have bodged in little shards that show you what the results of doing something will be, but not proper examples of how to do things.

Take the models example for instance (https://github.com/totaljs/examples/tree/master/models) this shows NOTHING about how to use a model.... the 'model' that is included is just a shard with a function in it.

The workflow example (https://github.com/totaljs/examples/tree/master/workflows) it creates a load of workflows and transforms, etc. All they do is print something to the log. The example doesn't do anything meaningful to show how to actually USE workflows.

Do workflows only return a true/false (fail/succeed)? Can they pass data on to the next workflow/operation? If so how does that happen?

Searching the examples repo I can find 3 examples of 'setSave'. ONE of them does anything meaningful with the data and that is to just blind insert it into a NOSQL database. Same thing for 'setQuery', etc.

@blaasvaer summed it up pretty succinctly....

[petersirka]

I'll update section Schema this month in docs.

[qoole]

I would suggest re-opening this issue to demonstrate your willingness to improve the documentation.

[petersirka]

No, you can open issue here https://github.com/totaljs/documentation or you can improve docs too :-)

[blaasvaer]

But why spread the same issue over several threads?

[blaasvaer]

OK, so I finally decided to ditch this framework for the time being. I seem to be constantly revisiting the same issues over and over (RESTBuilder, NEWSCHEMA, HttpRouteOptionsFlags and what have you), without them sticking at all. The concepts of the framework are simply to 'magical' for me to actually understand what is going on. And to be sufficiently fluent in any framework, you at least have to 'understand' what is going on.

I've been fiddling (or actually trying to build a few real world applications) with totaljs since august last year, and nothing but the very basics seem to make any sense to me. Now, having been a web developer for more that 20 years, this is the first time I've actually been forced to ditch any framework to the simple fact of 'simply not getting it'.

You can undoubtedly build stuff with it, as proven by the apps you can download. But even with access to the source code of these, it's simply to hard to adapt any of that to your own projects (unless you do simple copy/paste – but that's not a way to build anything). Again, not understanding the framework is the reason for this.

Thanks to @petersirka for actually trying to help – please, don't encourage people who don't understand the framework to write or improve the docs as you do in this thread ; ). It'll probably just make things even worse.

Now, I've paid for a premium account until august. And I will check back in once in a while to see if things improve in any direction that I can wrap my head around. Meanwhile I'll go with Express.

Thank you for now, and all the best.

[BlueMagnificent]

having been a web developer for more that 20 years

@blaasvaer, your rants reactions actually say otherwise.

I'm not here to defend totaljs (or am I ?) but I don't understand how you can't find your way around this framework despite the wealth of resources available in the form of very good examples, documentation and the very fact that you can dive into the code yourself for deeper understanding. I've been able to go beyond the basics with totaljs just weeks after i picked it up and it was really easy to figure out what I needed and how the framework could provide them for me.

Well... all the best

[sersh88]

Same here. I was total newbee to nodejs and finished big project with totaljs just after one month. Of course I did some mistakes and now my understanding of the framework is much deeper, but I don't see any reasons not to understand it. Also Peter is very helpful and fixes any problems with framework very fast.

[blaasvaer]

I agree that @petersirka is very helpful and maybe fixes issues very fast (I don't know, he hasn't fixed mine ; ) ). But I'd actually prefer to be able to fix any problems or issues myself. But to be able to do that, I'd have to 'understand' the framework I'm using. Otherwise I'd only be guessing; and that's basically what it's felt like for the past many months. I'm not saying that I don't get ANY of the framework, but there's just too much that is 'hidden' behind a 'concept' that I simply don't get. And that simply cripples me in being free to 'do whatever I want' – I simply find myself staring at the screen way to often, trying to figure out how to do a specific thing. And that just proves to myself, that I have no clue of these 'concepts'. And unfortunately the docs haven't been able to clear any of those out.

Yes, I've built applications with totaljs. But the time spent building those, just make it a VERY bad ROI in my case. Spending waaaaay to much time fighting (or actually trying to understand) the framework, instead of it helping me.

Now, I've worked with a LOT of frameworks throughout the years, and have always been able to fairly quickly become comfortable enough to be able to know what to do in basically any situation – or at least find an answer in the docs. In totaljs it's unclear whether I should create a definition, a helper, use a RESTBuilder, a model ... maybe that's a good thing, freedom wise. But to me it's just plain confusing.

Well, some frameworks are just not for all I guess.

@BlueMagnificent this should not be seen as a rant. Maybe it'll just make another guy feel not alone if he faces the same issues.