	-------------------------------------
	BASIC GUIDE TO MODULAR NEEDLES
	-------------------------------------
    
    -------------------------------------
    WHAT IS A NEEDLE
    -------------------------------------
    A needle is simply a quick way to insert a link from
    one piece of your content to another piece of your content.
    Instead of typing out say, a long URL to reference some
    post in your pnForum, you could simply type a short
    string such as PNFORUMT-2 and the link would be automatically
    created for you.  Or maybe you want to link to a specific
    download, weblink, news article...any module that has a 
    needle (or needles) included, can use the functionality.
    Of course, they will need the MultiHook module installed in 
    order to take advantage of this great new feature in Zikula.

    -------------------------------------
    GETTING STARTED
    -------------------------------------
    The first thing to do is install MultiHook as per its instructions.
    Next, if you're working on a custom module, and I presume that
    you are, you will need to access your module admin and set the 
    module to use MultiHook: access Admin->Modules->ModName->Hooks
    and set the module to use MultiHook.
    
    -------------------------------------
    HOW AND WHERE
    -------------------------------------
    A needle has 2 functions, each in its own file.  In a module,
    these files will be located in ../ModName/pnneedleapi/.. so
    now you should create that directory within the module that
    you're working on.  And then, in that freshly-created directory, 
    you will need to create 2 files that follow this simple schema:
    
        FILE 1: somename.php
        FILE 2: somename_info.php
    
    The 'somename' will be relevant to whatever needle you're creating.
    See the file-pairs within the ../MultiHooks/pnneedleapi/.. directory
    for the format of each file.  Note that the function names must be 
    reflective of the filename.  That is, if you named your files after
    the 'somename' examples above, then your corresponding function names
    would be:
    
        - YourModName_needleapi_somename_info($args)
        - YourModName_needleapi_somename($args)
        
    Your goal with the 2 functions is to set them up as shown below, which
    only represents a basic example.  Again, look at the example files 
    referenced above to flesh out your functions; it's pretty easy really.

        FUNCTION: ModName_needleapi_somename_info($args)
        RETURNED: ARR   - $info		- module name, needle name, syntax rules for needle.
        
        FUNCTION: ModName_needleapi_somename($args)
        ARGUMENT: INT   - $nid      - needle id.
        RETURNED: STR	- $result 	- replacement value for the needle.
    
    These 2 files/functions comprise the entire needle.  In case you haven't
    had your coffee yet:
    
        - YourModName_needleapi_somename()      - will go into somename.php
        - YourModName_needleapi_somename_info() - will go into somename_info.php
    
    Now, having the structure and function names sorted, take a look at the
    several needle file-pairs located in the ../MultiHooks/pnneedleapi/..
    directory.  There are some good examples to get you started; I did my
    first needle based on the htmlpage needle and you might also find it
    a good place to start.  Converting it over to your module should be
    easy, especially if the module is simple in nature.
    
    Once you have your needle's functionality worked out, you'll need to 
    access your site admin: Admin->MultiHook->Needles to re-register the
    needles available to your site.
    
    The names you give to your hooks is not overly important other than
    that you should name them in an effort not to clash with existing needle
    names.  You can create more than a single needle (file-pair) for a
    module simply by adding more file/function-pairs to your (whatever)
    module's needles directory.  The system will register them all, provided
    that it finds the expected function names.
    
    Caching is encouraged.  See the example file-pairs for examples.
    
    	Good luck and cheers,
    
    - John (alarconcepts)
