coldbox-modules / quick

A ColdBox ORM Engine
https://quick.ortusbooks.com
MIT License
23 stars 19 forks source link

[GitBook] Create() Method Documentation Improvement #245

Open homestar9 opened 7 months ago

homestar9 commented 7 months ago

@elpete, I no longer have access to the Quick documentation on Gitbook for some reason, so I'm posting my suggestion here:

On the page: https://quick.ortusbooks.com/guide/getting-started/creating-new-entities#create It is critically important to let users know the create() method returns a brand new entity, and does not persist the current entity which may have called it.

Example:

prc.user = getInstance( "User" ).newEntity();

// danger Will Robinson! This will not update prc.user.
prc.user.create( {
 "firstName": "Dave"
} );

writeDump( prc.user.isLoaded() ); // <--- WILL BE FALSE!

If you want to use create, you must do this instead:

prc.user = getInstance( "User" ).newEntity();

// in order for this to work, you must replace the original variable.
prc.user = prc.user.create( {
 "firstName": "Dave"
} );

writeDump( prc.user.isLoaded() ); // <--- WILL BE TRUE