$Id: install.txt 188 2008-06-12 17:11:24Z Landseer $
What is MultiHook?
------------------
MultiHook is a transform hook. This means it scaas text for certain keywords and performs actions
depending on what has been defined for them. You can easily create
* autolinks, eg. the word MultiHook can always link to the project site at code.zikula.org
* abbr + acronym tags, eg. EC gets converted to <abbr title="European Community">EC</abbr>
* censors, eg. bad words get converted to *****
* needles (see below for more information this feature and read John's great pndocs/needles_nowto.txt)
Installation
------------
Copy the MultiHook folder to your Zikula's modules folder, regenerate the
modules list in the admin panel, initialize and activate it.
For further changes to your theme see the chapter "Ajax support".
Do not forget to activate the MultiHook for the modules you want to use it with, like
pnForum or Pagesetter. The main admin panel shows for which modules the MultiHook is activated.
If present, the links stored in AutoLinks will be copied to the MultiHook
tables.
You can now add links, acronyms, abbreviations and censors in the admin panel or by selecting
text while pressing the CTRL-button on every page inside PN.
HTML Tags needed for MultiHook
------------------------------
You need to allow these tags incl. parameters for the MultiHook:
* a
* abbr
* acronym
* em
* span
Internet Explorer special trick:
--------------------------------
IE cannot (sigh...) handle the abbr tag correctly (or better said: it cannot
handle it correctly at all). We need a special css trick to make this
possible. This
abbr, acronym, span.abbr {
cursor: help;
border-bottom: 1px dashed #000;
}
is stored in the internal stylesheet mh.css file which will be loaded automatically
in Zikula 1.0.
The abbr tag created will look like this:
<abbr title="longlonglong"><span class="abbr" title="longlonglong">short</span></abbr>
So it will work on IE and not break Mozilla or other Gecko based browsers.
External Links
--------------
MultiHook can add special markup for external links. For this feature you can (and
should) specify a css class in the configuration, e.g. externallink.
The css declaration in mh.css looks like:
a.externallink {
padding-left: 14px;
font-size: 11px;
background: url('../../../modules/MultiHook/pnimages/extlink.gif') no-repeat bottom left;
}
a:hover.externallink {
padding-left: 14px;
font-size: 11px;
background: url('../../../modules/MultiHook/pnimages/extlink.gif') no-repeat bottom left;
}
This adds the image extlink.gif to the left of the created link. Please note that
the path to the image file is relative to the place of the css file used. Without
the a:hover the image would disappear in IE when the mouse is over the link
(sigh, again IE..).
Make sure that your target links are absolute, not relative. Linking to www.pn-cms.de will lead to
http://www.yourdomain.com/www.pn-cms.de although the a-tag looks correct in the page source.
This is not a bug in MultiHook, but the normal behaviour if a browser does not reckognize a fully
qualified url.
Censoring
---------
Since 4.5 MultiHook is able to replace the .76x module Censor. You can define words or
phrases that get replaced by **** (one * for each character). Handling is the same as for
link, abbreviations or acronyms.
Using Zikula 1.0 this is 100% integrated in the MultiHook and replaces the old
Censor module. Existing censored words will be converted to MultiHook during the upgrade.
Ajax support
------------
Since version 2.0 MultiHook uses Ajax for easier adding and manipulating of data.
In previous versions of MultiHook you had to make manual changes to
your theme. Using Zikula 1.0 this is not longer necessary. The core is
prepared to do everything automatically when using a Xanthia theme.
If you want to use this feature in other themes, your Zikula theme has to be prepared for
this and you have to enable javascript in your browser.
Copy modules/MultiHook/pntemplates/plugins/function.multihookhelper.php to your
modules/Xanthia/plugins folder and change your theme templates:
<... some code ...>
<link rel="stylesheet" type="text/css" href="modules/MultiHook/pnstyle/style.css" />
</head>
<body>
<... lots of code ...>
<!--[ multihookhelper ]-->
</body>
</html>
The multihookhelper plugin adds the necessary javascript and hidden divs if the users has min.
ACCESS_ADD permissions for MultiHook.
In non-Xanthiathemes (legacy, AT...) you can call
$multihookhelper = pnModAPIFunc('MultiHook', 'theme', 'helper'));
to retrieve the HTML in $multihookhelper and show where you want (which in fact is what the
plugin does too).
You can now select text portions of your page. When you press CTRL when releasing the mouse button
at the end of the selection process, a popup window will appear. Without CTRL you can copy and
paste the text as before.
If you do not want to use Ajax you can still use the normal admin panel for adding and changing
the data.
Needles
-------
Needles are a clever invention by Oivind Skau and have been implemented in PagEd for the
first time. They have been implemented since MultiHook 4.0.
You can simply add any kind of link by writing NEEDLENAME{moduleparams} if there is a
corresponding pnneedleapi-function available, eg.
PNFORUMF-2 adds a link to the forum with id 2
PNFORUMT-5 adds a link to the topic with id 5
Important: After adding new needles, you need to go to the needles configuration in Multihook
once (index.php?module=MultiHook&type=admin&func=viewneedles) in order to make them available
in the system. This rescans the pnneedleapi folder. Now the new needles are ready for use.
These needles are shipped with MultiHook:
DOWNLOAD{C-downloadcategoryid|D-downloadid|L-downloadid|S}
-> links to a download category, the download details or directly to the download
HTMLPAGE{pid}
-> links to the htmlpages page pid
PAGED{P-publicationid|T-topicid}
-> links to the PagEd article or a list of articles of the given topic
PAGESETTER{tid}
-> links to the list of all publications of publication type tid
PAGESETTER{tid}-{pid}
-> links to the Pagesetter publication with publication type tid
and publication pid
PHOTOSHARE{A-albumid|P-pictureid|T-pictureid}
-> links to an album, an image or a thumbnail with a link to the full size
image. In case of P its also possible to add addtional parameter for the
width and height to be used. So you can resize the output:
PHOTOSHAREP-3-200-150 will result in an image with width=200 and height=150
PNFORUM{F-forumid|T-topicid}
-> links to a forum or topic
WEBLINK{C-weblinkcategoryid|D-weblinkid|L-weblinkid|S}
-> links to a web links category, the web links details or directly to the link
Replace {description} with the data, | means "or".
E.g. {P-pictureid} should be used like P-123 for picture 123
The needles will be searched in upper case only:
HTMLPAGE12 will be found while
htmlpage12 won't.
Writing new needles (for developers only)
-----------------------------------------
A needle consists of two simple functions stored in two files, see the MultiHook/pnneedleapi/
folder.
modulename_info.php
-> contains MultiHook_needleapi_moulename_info(), which returns an array
containing the modulename and a string of how to use the needle.
modulename.php
-> contains MultiHook_needleapi_modulename(), which does the real work and returns
the replacement string. It gets the needle id passed as $nid. The needle id is the
part after the uppercase needlename, in PNFORUMF-1 the F-1 is the needle id.
Parsing and acting on the results is your part as developer ;-)
The modulename must not necessarily be a real module name, you can use this to for different
purposes, e.g.
showlistofitems.php/showlistofitems_info.php to show a list (SHOWLIST###)
showitem.php/showitem_info.php show one item (SHOWITEM###)
for the same module.
You are encouraged to use some caching mechanism in order to avoid consecutive SQL calls.
