WebCreatorPlugin

Flexible way to create new webs

Description

This plugin extends the basic way of the Foswiki core to create webs, while circumventing some of the more arcane features that are more of a burden than useful:

1. support for AUTOINC for webs similar to topics
2. ease way to create subwebs
3. configure web access rights as part of the web creation process
4. populate meta data of WebHome, i.e. set formfield values
5. allow to copy a template web into an already existing web
6. patch WebPreferences instead of just appending more preferences to it
7. perl api to register plugin handlers to be called before and after a web has been created
8. directly redirect to the newly created web
9. jsonrpc interfaces to script creating webs

JSON-RPC API

The basic functionality of %TOPIC% is made available using a JSON-RPC handler called WebCreatorPlugin.create.

Parameter	Description	Default
newweb	name of the target web
parentweb	name of the parent web which the target web is a subweb of
templateweb	name of the template web	_default
overwrite	boolean flag to optionally override an already existing target web	off
dry	boolean flag to simulate web creation; if enabled no actual web is created	off
<web-preference-name>	WebPreference settings may be specified using all upper case parameters, such as WEBSUMMARY, ALLOWWEBVIEW, DENYWEBVIEW, SOMESETTING and the like
<formfield-name>	any additional parameter provided may be used to populate the DataForm attached to the WebHome topic.

Plugin API

The %TOPIC% allows third party plugins to hook into the web creation process by registering an approriate handler.

• Foswiki::Plugins::WebCreatorPlugin::registerBeforeCreateWebHandler: handlers are called before the new web is created
• Foswiki::Plugins::WebCreatorPlugin::registerAfterCreateWebHandler: handlers are called after the new web has been created

Handlers will be called with the $parameter hash of all settings provided to the json-rpc call.

Skin integration

When using https://foswiki.org/Extensions/PatternSkin you might use the newweb template to render an appropriate dialog.

NatSkin comes with a modal dialog of its own available in the Admin dropdown menu at the top of the page.

Note that both of these interfaces only provide access to the standard features creating webs in Foswiki. The more advanced ones must be implemented as a derivation of the newweb.tmpl template. The form may be extended by defining the newweb::moresettingsstep definition or by extending the newweb::start or newweb::end definitions.

<verbatim class='tml tmplInclude'>%TMPL:INCLUDE{"newwweb"}%</verbatim>
<verbatim class='tml tmplDef'>%TMPL:DEF{"moresetingsstep"}%
<input type="hidden" name="MOREWEBPREFERENCES1" value="..." />
<input type="hidden" name="MOREWEBPREFERENCES2" value="..." />
<input type="hidden" name="MOREWEBPREFERENCES3" value="..." />
...
<input type="hidden" name="ALLOWWEBVIEW" value="..." />
<input type="hidden" name="DENYWEBVIEW" value="..." />
...
<input type="hidden" name="FormFieldName1" value="..." />
<input type="hidden" name="FormFieldName2" value="..." />
<input type="hidden" name="FormFieldName3" value="..." />
...
%END%
%TMPL:END%</verbatim>

Low-level form structure

Sometimes you might want to implement a new web form yourself instead of using the newweb.tmpl template directly. The basic form structure looks like this:

<form class="jqAjaxForm" action="%SCRIPTURLPATH{"jsonrpc"}%/WebCreatorPlugin/create" method="post">
   *Web name*:
   <input name="newweb" class="foswikiInputField required" type="text" size="60" />

   *Summary*
   <input type="text" class="foswikiInputField" name="WEBSUMMARY" size="60" />  

   *Parent web*:
   <select name="parentweb" class="jqSelect2" data-width="27em" data-allow-clear="true" data-placeholder="%MAKETEXT{"none"}%" size="1">
      <option></option>
      %FLEXWEBLIST{ 
         format="<option $marker>$web</option>" 
         marker="selected"
         webs="public" 
         exclude="Applications.*"
         separator="$n"
      }%
  </select>

   *Template web*:
   <select name="templateweb" class="jqSelect2" data-width="27em">
      %FLEXWEBLIST{ 
         format="<option $marker>$name</option>" 
         marker="selected"
         webs="webtemplate" 
         include="_.*"
         exclude=".*/.*"
         separator="$n"
      }%
   </select>

   <!-- additional preferences, formfield values and acls -->
   <input type="hidden" name="MOREWEBPREFERENCES1" value="..." />
   <input type="hidden" name="MOREWEBPREFERENCES2" value="..." />
   <input type="hidden" name="MOREWEBPREFERENCES3" value="..." />
   <input type="hidden" name="ALLOWWEBVIEW" value="..." />
   <input type="hidden" name="DENYWEBVIEW" value="..." />
   <input type="hidden" name="FormFieldName1" value="..." />
   <input type="hidden" name="FormFieldName2" value="..." />
   <input type="hidden" name="FormFieldName3" value="..." />

  <input type="submit" class="foswikiSubmit" value="Submit" />
</form>%JQREQUIRE{"select2, ajaxform"}%

QMPlugin integration

WebCreatorPlugin adds a new workflow command createWeb to QMPlugin so that this command can be used in workflows. That is you may create a web as part of a transition in a web. Example:

---++ Edges
| *From* | *Action* | *To* | *Command* |
...
| approved | start project | running | createWeb("PAUTOINC001" template="_ProjectTemplate" parent="Projects") |
...

This will create P... webs under the Projects web called Projects.P001, Projects.P002, etc whenever the action "start project" is performed in the workflow passing from "approved" to "running".

Parameters are:

Parameters	Description	Default
"...", newweb="..."	the target web to be created, may contain the AUTOINC which is expanded as required creating counting web names (mandatory)
tempalte="...", templateweb="..."	a template web	_default
parent="....", =parentweb="..."	parent web, if undefined a root level web will be created
overwrite="on/off"	boolean parameter letting you overwrite any existing web (use with caution)	off
dry="on/off"	boolean to perform a "dry" operation if activated; this is useful for testing	off
redirect="on/off"	boolean if enabled will redirect to the newly created web	off
PARAMETER="value"	any (uppercase) parameter will be stored into the target web's WebPreferences
<FormfieldName>="value"	if the WebHome topic has got a form attached to it then any formfield values found in the query will be stored there

The newly created web will have access rights ALLOWWEBVIEW, ALLOWWEBCHANGE, ALLOWWEBRENAME and ALLOWTOPICCHANGE set to the user that created the web unless specified otherwise using parameters such as in:

createWeb("PAUTOINC001" 
  template="_ProjectTemplate" 
  parent="Projects" 
  ALLOWWEBVIEW="ProjectsGroup" 
  ALLOWWEBCHANGE="ProjectsGroup") 

(... line breaks added for clarity)

Installation Instructions

You do not need to install anything in the browser to use this extension. The following instructions are for the administrator who installs the extension on the server.

Open configure, and open the "Extensions" section. "Extensions Operation and Maintenance" Tab -> "Install, Update or Remove extensions" Tab. Click the "Search for Extensions" button. Enter part of the extension name or description and press search. Select the desired extension(s) and click install. If an extension is already installed, it will not show up in the search results.

You can also install from the shell by running the extension installer as the web server user: (Be sure to run as the webserver user, not as root!)

cd /path/to/foswiki
perl tools/extension_installer <NameOfExtension> install

If you have any problems, or if the extension isn't available in configure, then you can still install manually from the command-line. See https://foswiki.org/Support/ManuallyInstallingExtensions for more help.

Dependencies

Name	Version	Description
Foswiki::Contrib::JQAjaxFormContrib	>=1.00	Required

Change History

16 Nov 2022	don't hardcode defaults for web acls
24 May 2022	add command createWeb() into QMPlugin workflows
05 May 2022	add support for template webs with subwebs in it
15 Oct 2020	initial release