LinkedResourceExtras

Summary: Linked resource helper functions and scripts for recipe writers
Version: 20070215
Status: Beta
Prerequisites:
Maintainer: Dfaure
Users: +1 (View / Edit)

Description

This recipe is more a set of ingredients for master chiefs aka recipe writers than a recipe by itself. ;)

extlinkedres.zipΔ is a set of extra functions and scripts helping cookbook recipe authors and custom markup developers to handles linked resources (i.e. attachment files and external urls), from inside their code. The provided features are:

  • Handling of the regular url/intermap/attachment notation,
  • Ability to lock globally against external resource usage,
  • Javascript helper script to bypass Internet Explorer activeX activation.

The archive contains two files: a php file to be put in the cookbook repository (extlinkedres.php) and a javascript file to be made publically accessible into the /pub directory (extlinkedres.js).

Usage…

…for end users

Once installed, the recipe allows specialized markups using it to (partially) handle the link syntax in their parameters such as:

(:somemarkup (http://host/my/external/)resource(.txt) :)
(:somemarkup Intermap:something/somewhere/else.doc :)
(:somemarkup Attach:an_attached_image.jpg :)

It also provides the following configuration flag:

$EnableExternalResource
In order to prevent the use of http://... urls (defaults to 1).
$EnableObjectAutoActivation
In order to controls the use of the provided javascript which will bypass the Internet Explorer activeX activation step (defaults to 1).

…for recipe writers

Simply add a include_once("$FarmD/cookbook/extlinkedres.php"); directive into your own cookbook recipe to enable the following functions:

ResolveLinkResource($pagename, $tgt, &$url, &$txt, &$upname, &$filepath, &$size, &$mime)
Splits a link resource specification such as: (Attach:)myFile(.jpg)
and returns its related components:
  • $url - the target url specification (Attach:Group.Name/myFile.jpg).
  • $txt - the visual rendering of the link (myFile).
  • $upname - if applicable, the url name of the local file attachment (Group/myFile.jpg)
  • $filepath - if applicable, the path to the local file attachment (uploads/Group/myFile.jpg)
  • $size - if applicable, the size of the local file attachment.
  • $mime - if applicable, the mime-type (as defined by PmWiki) of the local file attachment.
A boolean value is returned, indicating weither the resulting url is to be considered as valid or not:
true
  • if the resource is an existing local file attachement,
  • if the resource is an external link and the configuration parameter $EnableExternalResource hasn't been set to 0.
false
  • if the local file attachement hasn't been found. The url is set to the usual upload link.
  • if external links has been denied.
Sample usage:
Markup('mymarkup', 'directives',
       '/\\(:mymarkup\\s+([^\\s]+)(\\s+.*)?\\s*:\\)/e',
       "Keep(MyMarkupFunction(\$pagename,'$1',PSS('$2')))");

function MyMarkupFunction($pagename, $target_resource) {
  if(!ResolveLinkResource($pagename, $target_resource,
                          $url, $lpath, $txt, $size, $type, $mime))
    return isset($lpath) ? $url : '';
  ...
In the sample code above, the MyMarkupFunction() retrieves the differents resource components and gracefully renders as an usual upload link if the provided attachement doesn't exist. The resulting markup would able to handle syntaxic sugars like those describes in the end user usage above.
ExplodeLinkResource($pagename, $tgt, &$imap, &$path)
Internally used by ResolveLinkResource(), acts as the core's MakeLink() does to split the different link parts and compute the resulting text link.
ObjectAutoActivationWrapper($obj)
This function allows to circumvent the Internet Explorer activeX activation step, with the help of some javascript code (graceful fall back to the standard behavior for Javascript disabled browser).
Sample usage:
  ...
  return ObjectAutoActivationWrapper("
<object ...>
...
</object>");
}

Contributors

Dfaure

Release Notes

2007-02-15
Fixed erroneous RecipeInfo.
2007-01-25
ObjectAutoActivationWrapper() patch to enable usage from (skin-)included pages like the SideBar.
2007-01-20
Added upname, size and type for local file attachments.
2006-12-18
Initial (public) release.

References

Comments

See discussion at LinkedResourceExtras-Talk

User notes +1: If you use, used or reviewed this recipe, you can add your name. These statistics appear in the Cookbook listings and will help newcomers browsing through the wiki.