Saving
OK, we have defined entity, we have an instance of it, it's filled with data and now it's time to save it. Let's face it, there's nothing complicated about this in practice and it's done like this:
$article = new Content_Article();
if( $article->catchAddForm() ) {
$article->save();
//... ... ...
}
A simple call to the save() method, which is part of the Jet\DataModel class that all entities inherit from.
So in practice, it's not rocket science. But let's break it down a bit and see how it works and what aspects it has.
First of all, don't forget about events - this can often come in handy when saving, and by calling the save method you are also calling your eventual methods that will take care of what the save itself didn't take care of (for example, some file operations). An entity should ideally be created so that calling the save() method from the outside is enough and nothing more - all the logic should be taken care of internally to respect the encapsulation principle.
And recall also ID controllers. When used correctly, you don't have to worry about generating and especially not passing the main entity ID to the subentities. ID controllers, in conjunction with internal relations, will take care of that for you. That's a routine, annoying job - just the kind of thing that the platform is supposed to take care of itself, and it does. Thus, how you pass the generated autoincrement id to other subentities that make up, say, the goods in your e-store is not what you worry about.
It's also good to keep in mind that the entire save process is an SQL transaction (if backend can do it - but usually it can), which includes saving any subnets. The transaction is started automatically, terminated automatically, and the rollback on failure also occurs.
Am I forgetting something? Yes, I did. That the save() method determines whether it is saving a new record or editing an existing record. There are methods for this within the Jet\DataModel class.