create new tag
, view all tags
DeleteMe - This is supersceeded by FuncDotPm

is part of TWikiPluginAPI documentation.

It is usefull to call existing functions of the TWiki core from within the plugins. This is to reduce coding time.

We need to document the functions that can be used safely. All undocumented functions should not be used because they have a higher probability that they change.

For a start, here are some "official" functions that can be used. (Uncomplete list; add as needed.)

Function: Parameters: Description
&TWiki::Prefs::getPreferencesFlag $theName Get TWiki preferences value. Use <name>PLUGIN_<prefs> name for plugin preferences.
... ... ...

-- PeterThoeny - 12 Mar 2001

Not a very popular page to fill in!

Rather than a page that list functions, how about having a proxy API e.g. Plugins.pm could have subs added to it that then call into the core. Plugins should only use these functions.

-- JohnTalintyre - 21 Jun 2001

When it comes to the modularization this will probably be a generic problem. Since say a Render plugin might need access to the Store module. What will probably happen is when the particular Plugin object is created its given a Plugin Proxy handler.

The question then is what is a sufficent list of functions/features to add to the 'stubs' for each part of TWiki.

-- NicholasLee - 21 Jun 2001

Lets do the subs in Plugins.pm because the code gets the documentation and we do not need to worry about out of synch documentation.

Good question, what should go in. Not too much (restricts us in the future when we restructure the core code); and not too little (restricts the Plugin writers). At least we need to offer the important read/write subs from TWiki::Store, get preferences. What else?

-- PeterThoeny - 23 Jun 2001

Well, rather than flatten all the APIs into one module, consider using Perl's export mechanism. The following is from an article included with HTML::Tree::AboutObjects.html :

Modules and Their Functional Interfaces

Modules are the main way that Perl provides for bundling up code for later use by yourself or others. As I'm sure you can't help noticing from reading The Perl Journal, CPAN (the Comprehensive Perl Archive Network) is the repository for modules (or groups of modules) that others have written, to do anything from composing music to accessing Web pages. A good deal of those modules even come with every installation of Perl.

One module that you may have used before, and which is fairly typical in its interface, is Text::Wrap. It comes with Perl, so you don't even need to install it from CPAN. You use it in a program of yours, by having your program code say early on:

use Text::Wrap;

and after that, you can access a function called wrap, which inserts line-breaks in text that you feed it, so that the text will be wrapped to seventy-two (or however many) columns.

The way this use Text::Wrap business works is that the module Text::Wrap exists as a file ``Text/Wrap.pm'' somewhere in one of your library directories. That file contains Perl code...

Footnote: And mixed in with the Perl code, there's documentation, which is what you read with ``perldoc Text::Wrap''. The perldoc program simply ignores the code and formats the documentation text, whereas ``use Text::Wrap'' loads and runs the code while ignoring the documentation.

...which, among other things, defines a function called Text::Wrap::wrap, and then exports that function, which means that when you say wrap after having said ``use Text::Wrap'', you'll be actually calling the Text::Wrap::wrap function. Some modules don't export their functions, so you have to call them by their full name, like Text::Wrap::wrap(...parameters...).

Regardless of whether the typical module exports the functions it provides, a module is basically just a container for chunks of code that do useful things. The way the module allows for you to interact with it, is its interface. And when, like with Text::Wrap, its interface consists of functions, the module is said to have a functional interface.

Footnote: the term ``function'' (and therefore ``functional'') has various senses. I'm using the term here in its broadest sense, to refer to routines -- bits of code that are called by some name and which take parameters and return some value.

Using modules with functional interfaces is straightforward -- instead of defining your own ``wrap'' function with sub wrap { ... }, you entrust ``use Text::Wrap'' to do that for you, along with whatever other functions its defines and exports, according to the module's documentation. Without too much bother, you can even write your own modules to contain your frequently used functions; I suggest having a look at the perlmod man page for more leads on doing this.

From http://www.perldoc.com/perl5.6/lib/Exporter.html

In module ModuleName.pm:

  package ModuleName;
  require Exporter;
  @ISA = qw(Exporter);
  @EXPORT = qw(...);            # symbols to export by default
  @EXPORT_OK = qw(...);         # symbols to export on request
  %EXPORT_TAGS = tag => [...];  # define names for sets of symbols

-- MartinCleaver - 24 Jun 2001

An interesting idea from Martin, but one advantage of proxying is that changes to core functions can (potentially) be hidden from plugin authors.

I think the best way of getting the required subroutines added is to work with existing plugins. New plugins highlight any requirements on TWiki subs, and these would then be considered on TWiki.org for inclusion. This suggests that plugins should have a status that indicates if any TWiki subs are used. I follows that Plugins.pm may well change a fair bit and that a given plugin is likely to need a specific version of this more than a specific version of TWiki.

-- JohnTalintyre - 25 Jun 2001

Exporting is fine, although you still need to have a central registery once the number of functions potentially exported gets large to prevent namespace conflicts.

IMHO, it's probably better to use the proper object interface and perls AUTOLOAD mechanism. Anyway a nice very generic solution is probably a little tricky to determine (for myself) until a modularisation effort is complete. Until its probably better to have a simple mechanism that is easily improved at a later stage.

-- NicholasLee - 25 Jun 2001

Lets go for KISS since we are shortly before the code freeze (finally!), we can change that in the future if needed:

Create proxy funtions in TWiki::Plugins of all official funtions the plugins might use. All existing plugins should be changed accordingly.

-- PeterThoeny - 26 Jun 2001

Instead of adding the proxy functions to TWiki::Plugins where they can be confused with Plugin internal functions I created a new module TWiki::Func that contains all official functions the plugins may use. With this approach we can change the internal structure of TWiki without affecting the plugins (hopefully!).

Please have a look at TWiki::Func and let us know if something is missing, http://cvs.sourceforge.net/cgi-bin/viewcvs.cgi/twiki/twiki/lib/TWiki/Func.pm?rev=1.1&content-type=text/vnd.viewcvs-markup

Do we need to proxy some variables in TWiki as well?

-- PeterThoeny - 14 Jul 2001

Here is what we currently use that are not yet in Func.pm...

  • &TWiki::internalLink( 1, 2, 3, 4, 5, 6 )
  • &TWiki::getScriptUrl( $web, "", "search" )
  • &TWiki::getRenderedVersion( $pivot, $web );
  • &TWiki::wikiToUserName( $wiki )
  • &TWiki::userToWikiName( $uid )
  • &TWiki::formatGmTime( $epSecs )
  • &TWiki::handleIncludeFile( name , $topic, $web )
  • &TWiki::Store::getSubWebs() (could this use lists of webs through macros?)
  • &TWiki::Store::getRevisionNumber( web, topic )
  • &TWiki::Access::permissionsSet( web )
  • &TWiki::Access::checkAccessPermission( action, user, 3, topic, web )
  • &TWiki::Form::getFormDefinition( $formDef );
  • &TWiki::Search::searchWeb( "1", $web, $searchVal, "", ...)

  • $TWiki::wikiToolName
  • $TWiki::wikiUserName
  • $TWiki::defaultUserName
  • $TWiki::urlHost (is this the same as viewUrl?)
  • $TWiki::defaultUrlHost
  • $TWiki::scriptUrlPath
  • $TWiki::mainWebname
  • $TWiki::twikiWebname
  • $TWiki::numberOfRevisions

Sorry to be the bearer of bad news! (Let me know if you would like me to code these up in Func.pm). BTW is it expected that each item in Func.pm has an equivalent in TWiki.pm - or is Func.pm allowed talk to Store.pm, Access.pm directly?

-- SteveRoe - 20 Jul 2001

All the above are now included in the attached version of Func.pm...hopefully this will save a bit of grunt coding.

-- SteveRoe - 26 Jul 2001

Edit | Attach | Watch | Print version | History: r16 < r15 < r14 < r13 < r12 | Backlinks | Raw View | Raw edit | More topic actions
Topic revision: r16 - 2004-02-13 - SvenDowideit
  • Learn about TWiki  
  • Download TWiki
This site is powered by the TWiki collaboration platform Powered by Perl Hosted by OICcam.com Ideas, requests, problems regarding TWiki? Send feedback. Ask community in the support forum.
Copyright © 1999-2017 by the contributing authors. All material on this collaboration platform is the property of the contributing authors.