[pmwiki-devel] Developing extensions questions

[Petko Yotov]

On 26/04/2024 05:27, Simon wrote:
> My recipes tend to have the following layout
> #----------------------------------------------------------
> // executable code run when the recipe file is included from
> config.php, consisting of:
> // this includes, but may not be limited to
> # initialisation, including:
> ## setting the recipe version
> ## calling the markup function to register the page markup and the
> recipe's markup processing function
> 
> return; # having finished the setup
> 
> // callable (non-executable) code, for example:
> # recipe's markup code processing function
> # ancillary functions supporting the recipe's markup processing
> function
> #-------------------------------------------------------
> 
> In the Extension Design an example is given of
> function MyExtensionInit($pagename) {...}
>  MyExtensionInit($pagename);
> 
> What is special about this and how does it differ from the executable
> code described in the recipe layout above?

Nothing special, not required.

In this case, when you are getting local recipe configuration, having it 
inside a function makes the config values local rather than global.

You don't normally need "return;" unless you have inline code that would 
otherwise be executed, see scripts/forms.php where we have at some 
point:

   if ($action != 'edit') return;

This is to skip processing of inline code that is only useful for the 
edit form.

> In one of the new extensions there is the line:
> $EnableBootstrapIcons = 1;
> 
> Is this special in some way, e.g. generic and used for extension
> management, or is it specific to the recipe?

It is specific to the recipe and not required. That one is used in the 
recipe configuration form where we have:

   (:if ! enabled EnableBootstrapIcons:)
   Enable the extension to activate the list.
   (:else:)
   (:biconlist:)
   (:if:)

If the recipe is not included for SiteAdmin.ExtensionHub, the 
(:biconlist:) directive in the form does not work. So there is a 
conditional to show a message in this case.

There is a similar conditional in the form for CodeHighlight, which 
needs to be enabled to scan the languages and styles directories, and to 
build the custom form fields.

We could possibly add a conditional to the Hub that can be used in the 
form of the currently configured extension (whichever it is).

> It's not clear to me where in the distribution an extension
> distributes or obtains initial values or configuration, e.g.
> 
> SDVA($MyExtDefaultConf, [
>   'var1' => 'value1',
>   'var2' => 5,
> ]);
> 
> or
> 
> SDV($MyExtDefaultConfVal, 'DefaultVal');

These can work the same way as for other recipes, define their initial 
values in your extension.

Use SDVA() which will make it possible for admins to re-define these in 
local configuration (in addition to the Hub configuration form).

I recommend to use one array variable with all or most of your 
initial/default configurations, rather than separate global variables, 
but this is not required or enforced.

You can allow admins to redefine some of the values in an extension 
configuration form. It may be wise to only include in the form the 
values that are most likely to be changed, while leaving more complex 
values like HTML snippets or multilevel nested arrays to be changeable 
in local PHP configuration.

> I surmise that there are two possibilities:
> 1) from a form exposed via the Extension Hub Page,
> 
> 2) from somewhere else.

The initial/default values can be set in your extension script, with 
SDVA().


> What I am looking for is the equivalent of a file of key value pairs.
> One use case is to provide an API key that I do not want exposed or
> visible to the world.
> This might have a format per line of (for SDV)
> key=ka val=vb
> or
> key=ka val=[vb,"v c"]
> or some other syntax: ka=va, ka=[vb,"v c"]
> 
> and for SDVA
> key=[ka,kb] val=vb
> or
> key=[ka,kb] val=[vb,"v c"]
> or some other syntax: [ka,kb]=[vb,"v c"]

The Hub extension configuration form will store the values posted by 
your form, and when you call extGetConfig() it will return an array of 
the stored key=value pairs. If you have a default array, you can have it 
merged it by passing it as argument: $conf = 
extGetConfig($MyDefaultConfig); or you can merge it yourself.

The configuration form has limited support for nested arrays, I have 
updated the documentation, but basically you can have fields like:

   (:input checkbox lang[] PHP "PHP":)
   (:input checkbox theme[mobile] 1 "Mobile theme":)

and then $conf['lang'] and $conf['theme'] would be arrays with the 
values the user checked.

Note, in case of checkboxes and the user hasn't checked any, the arrays 
will be undefined. You need to handle this case, or you may see warnings 
in PHP 8. Merging with a default array should take care of this.

You could also have "text" or "textarea" fields where admins type

   key1=val1 key2=val2

you then pass the string through ParseArgs().


> Lastly, I assume that the values of the directory and the extension
> php file name are case sensitive.

Yes.

> I ask this because I use windows, and also because directive names
> themselves are not case sensitive, and I observe that (almost all)
> recipe filenames are fully lower case.
> Yet for some reason it seems better to have a directory name (as shown
> in the example "MyCoolExtension") that is TitleCased.

File and directory names for extensions should be considered 
case-sensitive, even on Windows, and files should probably have 
lowercase extensions. In fact, most web servers are not on Windows and 
their filesystems are case-sensitive. Moreover, the filesystem inside 
compressed extensions is case-sensitive even on Windows.

The capitalization of the extension name is not required or enforced, 
i.e. lowercase extension directory and file names should work fine, as 
long as the base name is identical. If you publish an extension to the 
Cookbook, the first letter will be capitalized, and it may be good for 
the cookbook page name to be the same as the extension base name, this 
should make it more likely to work with RecipeCheck.

Petko