===============================================================================
                          Khanh's Content Adder (KCA)
                            Copyright (c) 2005-2007
                           - Add content anywhere -
===============================================================================
Tags: admin, development, content, interface, dom, design, javascript
Contributor: John Ha
===============================================================================

    Copyright (c)  2005-2007  John Ha.
    Permission is granted to copy, distribute and/or modify this document
    under the terms of the GNU Free Documentation License, Version 1.2
    or any later version published by the Free Software Foundation;
    with no Invariant Sections, no Front-Cover Texts, and no Back-Cover Texts.
    A copy of the license is included in the section entitled "GNU
    Free Documentation License".

===============================================================================
                         GNU GENERAL PUBLIC LICENSE
===============================================================================

    Copyright (C) 2005-2007  John Ha.

    This program is free software; you can redistribute it and/or modify
    it under the terms of the GNU General Public License as published by
    the Free Software Foundation; either version 2 of the License, or
    (at your option) any later version.

    This program is distributed in the hope that it will be useful,
    but WITHOUT ANY WARRANTY; without even the implied warranty of
    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
    GNU General Public License for more details.

    You should have received a copy of the GNU General Public License along
    with this program; if not, write to the Free Software Foundation, Inc.,
    51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA.

===============================================================================
                              Licensing Policy
===============================================================================

Free to use for those who are 100% GPL
--------------------------------------
If your application is licensed under GPL, you are free and welcome to ship
this program with your application. By "application", I mean any type of
software application, system, tool or utility.

Commercial use for everyone else
--------------------------------
If your application is not licensed under GPL, such as you build a web site for
your client and the web site is non Open Source, you must first purchase this
program.

It's only $15 USD per domain name.

Developer License
-----------------
The Developer License allows you to use the software freely within your own
projects, or to rebrand as your own product.

It's only $99 USD.

Payment
-------
Payment can be made via PayPal.

===============================================================================
                                  Purpose
===============================================================================
Have you wanted to add an extra button to the Admin Panel or Quicktag toolbar?
Usually, you would have to edit the core Wordpress files, or be limited to what
and where you can add stuff.

With KCA you can add content anywhere on any page on your site. The plugin
makes use of client side scripting and the DOM to insert content.

The framework of the plugin allows you to also add your own scripts to any
page. All this is configurable through a plugin management page, so you don't
have to go through the plugin code to change variables. You also don't have to
manually edit any files to see the results. All you need to do is configure
settings in the plugin management page.

In it's simplest form, it can be used to add buttons to the quicktags panel.
Another more complex example that is included as an addon, demonstrates how
tooltips are added to any of your pages, without editing a line of code in
your files or templates.

You also have the option of activating/deactivating addons, as well as choosing
what userlevel the plugin will allow the addon to operate.

Because you can include client side scripts (javascript/vbscript) and CSS to
your pages, what you can do is only limited by the DOM. Even without knowing
much about the DOM, you can add links, buttons or CSS to any page easily.

===============================================================================
                                 Features
===============================================================================
- Allow addition of Javascript snippets to any page in your blog
- Add buttons to Quicktags panel
- Include Javascript library files to your pages
- Selectively include Javascript files/code snippets in certain pages
- No need to manually add Javascript by editing template files
- Uses DOM to add content
- Can also be used to add CSS to your pages
- Either add Javascript/CSS to all, or some pages
- All settings and options are controlled via nifty admin panel
- All data is importable/exportable
- Data cut/copy/paste is supported
- Most functions use AJAX to make for quick updates/changes
- Plugin includes useful Javascript/PHP functions which can be used elsewhere
- You can write your own Javascript code or simply it import from elsewhere
- Includes plugin variables to make plugin operation easier

Note: The usual default addon settings are now stored in addons/default.ini.
      You can load and parse default.ini into Scratch-Pad via the "default.ini"
      button, then import what you want or if you are installing for the first
      time, you can go into the global panel and hit restore, which will import
      the lot. Then you can (de)activate an addon by (un)ticking the "activate"
      tickbox, followed by "update".

===============================================================================
                                Compatibility
===============================================================================

Should work in all versions from Wordpress 1.2.x up to 2.x.x.

===============================================================================
                             Installation / Upgrade
===============================================================================

New Install
-----------
1.  Unzip and upload the "kca" directory into the plugins directory, keeping
    the directory structure intact.
2.  Make sure correct permissions are applied (files=0644, directories=0711).
3.  Activate the plugin.
4.  Find the plugin management page under Manage->KCA
5.  Click "Restore" under "Global" to populate with default settings.
6.  By default all sample records are activated.
7.  Uncheck "Activate", then "Update" to deactivate ones you don't require.
8.  Play with the default record sets.
9.  To restore original record sets, hit the "Restore" button in "Global".
10. Read the rest of this readme file.

Upgrading
---------
1.  De-activate kca.
2.  Remove old "kca" directory (to make sure no left over redundant files are
    carried over to the new version upgrade, since some files have changed).
3.  Unzip and upload the "kca" directory into the plugins directory, keeping
    the directory structure intact.
4.  Make sure correct permissions are applied (files=0644, directories=0711).
    (Note: These permissions might not work on certain servers, so try 0755)
5.  Activate the plugin.
6.  Find the plugin management page under Manage->KCA
7.  Go to "Global" and click "Upgrade" if option is available. The database
    will be converted to the latest format, ready for use.
8.  Read the rest of this readme file.

Note:   Be sure to upgrade the data BEFORE you do anything else, otherwise you
        will lose the data already in the database. If you do not see an the
        "Upgrade" option in "Global" then the database should already be in
        the correct format.

        If all you have in the database is the default record sets that came
        with the plugin, then there's no need to upgrade the database. Just use
        "Restore" in the "Global" panel instead, which would bring everything
        up to date, including any extra addons that might have been added since
        the last release.

        To be certain you won't lose any data:
            1. extract what data you do have
            2. copy & paste to text file
            3. save it
        If something does go wrong, at least you will have some form of backup.


===============================================================================
                              Usage / Explanation
===============================================================================

Messages
--------
At the top of the page just below the Nav-Bar you should see a message panel.
Any messages generated by KCA will be displayed here. You have the option of
rolling up the panel so only the title shows, or close it completely.

If closed completely, you can still recall it by clicking on the messages
link (Xi symbol), which will toggle it back into view.

It is recommended that you leave the message box open until you are sure you
won't be missing any crucial messages.

KCA uses cookies to store certain data that allows for many of the settings to
remain persistant across sessions.


Help
----
The help panel shows this file in a readonly textarea, so you can have quick
access to any information that might help you. This panel, like all panels,
also has rollup and minimise options.


Record Set Panels
-----------------

Field                   Description
-------------------------------------------------------------------------------
Description:            Description for current record set.
(optional)              Eg. [Test] button in Quicktags panel

Eval:                   A valid boolean comparison (php format) that can
(optional)              uniquely identify the page that the current option
                        set can operate on.
                        Eg. is_single() && get_current_theme() == 'default'
                        =>  will only add content to a single post page AND
                            only if the current theme is default theme.

Needle:                 A URL string fragment that can uniquely identify
(optional)              the page that the current record set can operate on.
                        (comma separated)
                        Eg. post.php, page-new.php
                        =>  will only add content to pages with "post.php" or
                            "page-new.php" in the URL string.

Level:                  Minimum user level that this record operates under.
                        (Default = '' ie. Not logged on.)

Active:                 Activate record set or keep it dormant.
                        (Default = false)

Content:                HTML content to insert.
(optional)              Eg. <input class="ed_button" type="button" value="Test"
                        title="A little test" onClick="return my_test();" />
                        =>  makes a Quicktags style button.

Reference:              Tag ID to refer to on the page to operate on.
{optional)              This is the reference point to add content.
                        ** Must be specified if Content is used. **
                        Eg. ed_toolbar
                        =>  specifies the Quicktags toolbar ID

Location:               Where to insert the content relative to the 
                        reference ID.
                        (Default = '')
                        ** Must be specified if Content is used. **
    - beforeBegin       Content is inserted immediately before the element.
    - afterBegin        Content is inserted after the start of the element
                        but before all other content in the element.
    - beforeEnd         Content is inserted immediately before the end of the
                        element but after all other content in the element.
    - afterEnd          Content is inserted immediately after the end of the
                        element.

Head/Body:              Client side scripts that can add functionality to the
(optional)              content you add, or CSS declarations.
                        Eg. <script type="text/javascript">
                            //<![CDATA[
                            function my_test() {
                                alert('Does this work?');
                                return false;
                            }
                            //]]>
                            </script>
                        =>  adds a javascript function to the page


Buttons                 Description
-------------------------------------------------------------------------------
Clear                   Clear current record set form.
Reset                   Reset current record set form.
Extract                 Extract formatted data from form to the Scratch-Pad
Dump                    Dump formatted data from Scratch-Pad to form
Delete                  Delete current record set from KCA database.
Update                  Update current record set data to KCA database.
Save                    Saves new record set to KCA database. This button is
                        only shown in the "Add Record Set" panel.


Eval %%
-------
Now you can define PHP code in between %% and %% that will be eval'ed:
%%bloginfo('wpurl')%%
=> will print out the results of a call to bloginfo('wpurl')

To print the results of a funtion, "=" must be added to the %% like so:
%%=get_bloginfo('wpurl')%%
=> this will print out the results of the call to get_bloginfo('wpurl')

Make sure the code in between %% and %% is valid PHP, otherwise you will get
errors. Be careful what code you use in between %% and %%. You have been
warned.

some predefined %% variables are:
- %%site_url%%: echos root url, similar to bloginfo('wpurl')
- %%kca_url%%: echos the url to the kca directory

Scratch-Pad Panel
-----------------
The Scratch-Pad is a good place to extract and save snippets of data, or
import record sets saved from elsewhere.

Buttons                         Description
-------------------------------------------------------------------------------
Select / Copy / Paste           Used for selecting, copying and pasting data
                                from the system clipboard. Note: Only select
                                will be shown in Mozilla browsers, due to
                                browser security reasons.
Clear                           Will clear the Scratch-Pad.
Extract                         Data from all record sets is formatted and
                                dumped to the textarea, where it can be edited
                                or dumped back onto another form.
default.ini                     Read and parse default.ini into the Scratch-Pad
Import                          Save formatted data from Scratch-Pad. A fair
                                bit of data processing has been added to weed
                                out garbage from incorrectly entered data, but
                                it's always best to go through and check that
                                the correct format is adhered to.


Data Format
-----------
So, what is the correct format for importing data? Basically:

<field> = [data]
<field> = [data]
        + [data]
        + [data]
...
<field> = [data]


The field must exist and be the right order. All fields must be defined in
order for the importation to go ahead. The number of spaces and tabs are not
important. Any line that does not correspond to an existing field will just
be ignored.

For a sample of a correctly defined data set, just go to a record set panel and
hit "Extract", then go to Scratch-Pad and have a look at the formatted data.

If there is correctly formatted data in the Scratch-Pad, hit "Import" and all
data will be imported into the KCA database. The new record sets will be
appended to whatever was there beforehand.

Data can also be dumped to the "Add Record Set" panel, where "Save" will import
the data to the KCA database. If there was more than one record set in the
Scratch-Pad, only the first record set would be processed.

Usually you will not have to worry about the data format, since KCA will take
care of extracting correct format already. Any editing of scripts should be
done in the record set panel. The Scratch-Pad should mainly be used for
extracting or importing data.


Global Panel
------------
Buttons     Description
-------------------------------------------------------------------------------
Purge       This will delete all KCA data from the database. This would be
            useful if you want a clean slate, or if you want to unistall KCA.
Restore     Restores default plugin record sets.
Update      Updates all record sets with current data simultaneously.
Upgrade     If database needs updating, then this button will be enabled, while
            all other database manipulation buttons will be disabled.


Nav-Bar
-------
Now all navigation is done via a Nav-Bar. The Nav-Bar is of the floating
variety, so will always be shown at the top of the page for quick access to
the navigation links.

There are two display modes: single-edit [1] and multi-edit [&infin;]. In
single-edit mode only one record set or form is shown at a time, which makes
it easier to view and edit. Just use the nav buttons to display the record
you want.

In multi-edit mode, all record sets are displayed at once, so you can scroll
from one set to the next, or again, you could jump from one set to another
via the nav buttons. The Nav-Bar will remain onscreen always.

Another feature of the Nav-Bar is it remembers the record set you were viewing
and which panels were minimised, as well as what edit mode was in use, so the
next time you return to the KCA management page, it restores the state the page
was in the last time you were there.

Nav-Bar Explanation
-------------------

The following is a representation of the Nav-Bar. All UTF-8 symbols have been
replaced with a corresponding letter. n = any number greater than 1.

-------------------------------------------------------------------------------
1..n + # T                         [n:n] [1|..|n] [n:-] << < > >> U D N E M ? A
-------------------------------------------------------------------------------

Link                Description
-------------------------------------------------------------------------------
1..n                Links to each record set panel
+                   Add record set
#                   Scratch-Pad
T                   For making global changes (Theta symbol)
[n:n]               [Page top:Nav-Bar top] in pixels
[1|..|n]            Displays minimised record sets
[n:-]               [Number of operations:Progress] during XMLHttp operations

<< < > >>           First record, previous record, next record, last record
U, D                Jumps to page top, jump to page bottom (Up / Down arrows)
N                   Toggles between two Nav-Bar modes (Cross / Double-Cross)
E                   Displays edit mode:
                        - proportional symbol = single-edit
                        - infinity symbol = multi-edit
M                   Shows / hide messages. (Xi symbol)
                    Note: This link will be highlighted when the message panel
                          is closed, but there is an important message in the
                          panel:
                            - Red: high priority message
                                - Eg. Plugin update notice
                            - Yellow: medium priority message
                                - Eg. Global operations
                            - white: low priority message
                                - Eg. Record set update
                          It is recommended you should check the message
                          panel for any important message if the link is red.
?                   Shows / hide help. (Question mark)
A                   Toggles between small and large fonts for Nav-Bar


Panel links
-----------
Link                Description
-------------------------------------------------------------------------------
-/+                 Toggle panel contents show/hide
X                   Close panel

===============================================================================
                                   Services
===============================================================================

If you need extra support for installation, customisation, development of new
features, or you have project in mind, you are welcome to contact me.  

===============================================================================
                              End of Readme File
===============================================================================
