Feature Proposal: Add a new function createTopic to Func

Motivation

More intuitive for novices starting to develop extensions

Description and Documentation

Much along the line of the createWeb function in lib/Foswiki/Func.pm there should also be a createTopic function. The current method of using saveTopic is confusing if you do not know about it.

This does not even need to be a function per-say other than a placeholder to inform the developer to use the saveTopic function.

Examples

---+++ createTopic()

See saveTopic function

If you want to create an empty topic simply set the text to empty as follows:

$text = '';

Impact

WhatDoesItAffect:

%WHATDOESITAFFECT%

edit

Implementation

-- Contributors: PadraigLennon - 24 Nov 2011

Discussion

At first blush, adding a new function that is the same as, and just refers to another function's docco feels like a net negative.

I'm presuming that you (er, and I) are likely to do a find in Func.pm so it should be pretty trivial to add some docco to saveTopic that would do the same thing as adding a new function call.

On the other hand Store2 is working in a similar direction - in that there are explicit calls to load(), create() - so I am clearly not sure.

-- SvenDowideit - 24 Nov 2011

Why not just add "if you were looking for createTopic, just use saveTopic" added to the saveTopic doc? Won't that achieve the same thing?

-- CrawfordCurrie - 25 Nov 2011

I'd also vote for more docs in this case. Especially as Sven is carefully considering the issues around this with Store2 which may or may not give us a create method.

-- JulianLevens - 25 Nov 2011

Crawford thats more or less along the lines of what I was suggesting. I'm just not sure what the correct way to do this is.. Do I just add a note to the Func.pm file? I'm thinking about how the http://www.foswiki.org/System/PerlDoc?module=Foswiki%3A%3AFunc works for example.. What format does it need to take?

I'm not suggesting any new code here at all..

-- PadraigLennon - 25 Nov 2011

I'm thinking that this would suffice.. though it would be useful for the novice user to know how to create an empty topic i.e. without reading in the contents of an existing topic first. Thoughts?

=begin TML

---+++ createTopic( )

See saveTopic()

=cut

-- PadraigLennon - 25 Nov 2011

Actually creating a topic from thin air, then attaching a form and populate it with stuff isnt that easy. Making this more plugin friendly would actually be nice. For now to add a new topic from thin air you'd have to construct a new Meta object and the use putKeyed(FORM) and friends to manually attach a form in the hope it matches the data form definition ... though this is more of data forms being a hassle on perl land rather than just a createTopic.

-- MichaelDaum - 25 Nov 2011

Right; but what you describe is more of a "build topic" function. For example, attachForm, populateForm would be a more appropriate API (c.f. addAttachment). After buildint meta this way, saveTopic is still the business.

-- CrawfordCurrie - 25 Nov 2011

No follow-up from proposer, so rejecting this proposal.

-- CrawfordCurrie - 17 Feb 2012

Commenting is disabled while not logged in