[pmwiki-devel] Developing extensions questions

[Petko Yotov]

I would add that except for the extension filename conventions, and if 
you ship CSS/JS resources, the use of $ExtPubDirUrl rather than 
$PubDirUrl, an extension could have the same PHP code as a classic 
PmWiki recipe.

You don't need an "init" function like MyExtensionInit(), you can get 
the local configuration directly from inside your Markup processing 
functions, like before.

Configuration formats of classic PmWiki recipes should work with 
extensions, from config.php, or from Group.php and Group.Page.php 
scripts.

While extension configuration forms and hub helper functions simplify 
for us development, and for wiki admins deployment, configuration, and 
updates, none of these are required in an extension.

Petko

On 26/04/2024 13:23, Petko Yotov wrote:
> 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