simplify saveTiddler API method

[FND]

TiddlyWiki.prototype.saveTiddler is often used wrongly due to its inconvenient function signature and lack of comprehensive documentation.

It should be considered how this method could be simplified, e.g. by providing default values for certain arguments (esp. defaulCustomFields) and combining such arguments in an optional object passed into the function.

[EricShulman]

It should be considered how this method could be simplified, e.g. by providing default values for certain arguments

The current API takes these arguments:

saveTiddler(oldTitle,newTitle,text,who,when,tags,fields,created,clearChangeCount)

One fairly common use-case is when you retrieve an existing tiddler object in order to modify it and save it back to the store. In this case, it would be *much* simpler to just alter the fields in the tiddler object and then pass that object back to saveTiddler(). In other words, something like this:

var t=store.getTiddler(...)
t.tags.pushUnique('someNewTag');
store.saveTiddler(t);

instead of

...
store.saveTiddler(t.title,t.title,t.text,t.modifier,t.modified,t.tags,t.fields);

To achieve this, the saveTiddler() function would need to have a little bit of code added at the top to detect and 'unpack' the values from the tiddler object instead of fetching the tiddler based on the oldTitle and setting the values from the passed in arguments, like this:

TiddlyWiki.prototype.saveTiddler = function(title,newTitle,newBody,modifier,modified,tags,fields,clearChangeCount,created)
{
	if (typeof title != 'string') {
		// unpack params from saveTiddler(tiddler,clearChangeCount)
		var tiddler=title;
		var clearChangeCount=newTitle;
		var newTitle=tiddler.title;
		var newBody=tiddler.text;
		var modifier=tiddler.modifier;
		var modified=tiddler.modified;
		var tags=tidddler.tags;
		var fields=tiddler.fields;
		var created=tiddler.created;
	} else {
		var tiddler = this.fetchTiddler(title);
	}
	... the rest of the function remains the same ...

[FND]

As an additional feature, it should be considered to make saveTiddler trigger autoSaveChanges (perhaps controlled via an optional suppressAutoSave argument).

[EricShulman]

Replying to FND:

As an additional feature, it should be considered to make saveTiddler trigger autoSaveChanges (perhaps controlled via an optional suppressAutoSave argument).

There are numerous plugins that currently use store.saveTiddler() with the assumption that it does *not* trigger a save action, even when 'auto save' is enabled.

This permits the plugin code to write multiple tiddlers (perhaps hundreds) without invoking a costly "save to file" (or "save to TiddlyWeb") action for each one (which could bring the plugin processing to a near standstill). Then, *after* writing all the tiddlers it needs to, the plugin can explicitly invoke saveChanges() if it is appropriate, and only if config.options.chkAutoSave is set, of course.

Clearly, at first look, invoking saveChanges() from inside saveTiddler() *seems* sensible... as long as it can be overridden as needed... and, if this was a new function that had no existing usage to worry about, including a 'suppress' flag in the function call would be a suitable approach. However, because this is already a widely-used function, changing the *default* behavior will create many serious problems for current documents that are using existing plugins.

Please do *not* make saveTiddler() invoke saveChanges() automatically. It *must* be left up to the plugin author to determine when (or even *if*) it is appropriate for any given call to saveTiddler() to also be followed by a call to saveChanges().

[FND]

FWIW, a simpler version is currently being tested with TiddlySpace?:  http://github.com/TiddlySpace/tiddlyspace/commit/b82f257b2bde2c5bb44c9c486d052b0d5e695a46

[MartinBudden]

Milestone 2.6.2 deleted

[FND]

This should be done in a  minor rather than a patch release.

[MartinBudden]

Fixed in changeset:12419