=============================================================================== Khanh's Content Adder (KCA) 2.0.1 Copyright (c) 2005, 2006 - Add content anywhere - =============================================================================== Tags: admin, development, content, interface, dom, design, javascript Contributor: John Ha =============================================================================== 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. =============================================================================== Compatibility =============================================================================== - Wordpress 1.5.2 - Wordpress 2.0 =============================================================================== Files =============================================================================== kca.php Main file kca.css CSS file for KCA includes/admin-js.php Admin javascript functions includes/core-js.php Useful javascript functions includes/svn.php Retrieves KCA svn page includes/mozEmuLarholm2.js Emulates insertAdjacentHTML in Mozilla includes/tw-sack.js Simple ajax code kit includes/fat.js Fade anything technique addons/default.ini Default addon code snippets addons/dom-tooltips.js Tooltips addon script addons/dom-tooltips.css CSS file for dom-tooltips addons/TextArea.js Textarea resizer addon script addons/TextArea.css CSS file for TextArea resizer docs/readme.txt Readme / help file for KCA docs/history.txt History file 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". =============================================================================== Installation =============================================================================== 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. =============================================================================== 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. => 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. => 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. Variables --------- Now you can define variables in between %% and %% that will call a corresponding php function: %%bloginfo('url')%% => will print out the results of a call to bloginfo('url') To print the results of a funtion, "=" must be added to the %% like so: %%=get_bloginfo('url')%% => this will print out the results of the call to get_bloginfo('url') The function must exist in the first place in order for the call to succeed. If the function does not exist, a message stating the fact will be printed: [some_function(): n/a] Obviously, just like the "Eval" field, care must be taken when calling certain functions. 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: = [data] = [data] + [data] + [data] ... = [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 [∞]. 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 =============================================================================== F.A.Q. =============================================================================== Q: Why do I get an error when I click the help link? A: Make sure you have copied all files over, including the readme and history files, because these files are used in the help section. Q: Why aren't the tooltips working? A: Title attributes for anchor tags need to be set in order for the tooltips to show up Eg. link Q: Where can I get more addons for KCA? A: Addons can be any client side script you find on the net, or written yourself. Nothing special needs to be done to them before adding them to your pages via KCA. A few examples can be found here: http://ink.bur.st/?s=addons Q: Will all my settings be brought over when I upgrade to a newer version? A: Yes, this was why KCA was written in the first place: to simplify adding widgets / buttons / links to your pages, without editing any template or core files, while saving all data to the database, so when upgrading WP there is less of headache. Q: Where did all my panels go? A: They are still there. It's just that you are probably in single-edit mode, where only one panel is visible at a time, or you have closed the panel. Just click on the number corresponding to the panel you want displayed to edit that record set. Q: What the hell is wrong with the Nav-Bar links? It's not working! The links are not being highlighted properly and they aren't responding properly! A: Make sure you only have one instance of KCA open at a time. If you have more than one instance of KCA open, the cookie system that Nav-Bar uses becomes "confused". =============================================================================== About the Nav-Bar =============================================================================== You maybe wondering: is a navigation interface like this needed for just a simple admin plugin? You are right - it's not needed, but I saw it as a interesting exercise in interface design. I tried to fit the Nav-Bar design in with the current admin interface, while at the same time introducing more efficient ways of jumping about the page. The problem was how to navigate the page without relying on using the system scroll bars. Since the number of record sets could get quite large, there had to be a way to quickly find record sets and jump to them. To simply have just one page containing all the potential data was not going to be feasible. (Forms vs. Applications: http://www.useit.com/alertbox/forms.html) Originally the Nav-Bar was duplicated for each record set and this worked fine, but the resultant html was bloated due to this duplication. After mulling over the problem, I decided that the only elegant solution was with a floating Nav-Bar. Should it use only CSS? Not possible, since it needed to be dynamically updated with various bits of information, so DHTML was the choice. And since the admin interface uses client side scripting and cookies to achieve much of it's work, I saw no problem with users not having any of these enabled on their system. Still, I made sure if javscript isn't enabled, that a warning was shown. Cookies must be enabled for the plugin interface to work, but obviously if cookies weren't enabled, you wouldn't have access to the admin interface anyway. In the end I tried to make the Nav-Bar as simple as possible, while still being aesthetically pleasing. The design fits in with the WP 1.5.x interface as well as later versions. I've tested it in IE 6, Firefox and Opera in Windows XP, but have not had the opportunity to test it in other browsers or systems. Any problems please let me know. =============================================================================== Technical Stuff: Event Registration =============================================================================== The included samples use a technique for registering handlers so that the scripts are defined independently, yet access the same events, while not adversely affecting each other's operation. addEvent(obj, evType, fn [, cap]); removeEvent(obj, evType, fn [, cap]); wait4obj(fn, objID [, t]); schedule(fn [, objID] [, t]); Where: obj = the object to attach the handler objID = the object ID to attach the handler evType = which event to register with eg. 'load' for 'onload' event fn = the handler we have defined for the event cap = event capture (true/false) t = time out (ms) for handler [] = optional argument The reason why we chain event handlers is so when the event eventually fires all the handlers can be executed, regardless of when they were registered. If we were to only put: window.onload = tooltip.init; ..what happens to the next script we have defined that needs the onload event? We can't redefine window.onload, because then tooltip.init won't load. This is why addEvent is so handy. We just use addEvent to register the handler with the specified event and forget about it. When the event fires it will go through the list of handlers that was registered with it and execute them one after another. Using this method the order in which the handlers are executed depends on when they were registered. It also depends on the browser, because Mozilla and IE deal with events differently. In IE the first handler registered will be executed first, while in Mozilla the last handler registered will run first. This all has to do with event capturing and bubbling. It's beyond the scope of this readme file to go into detail about how this all works. A good place to start though, is here: http://www.quirksmode.org/js/events_advanced.html#top The "schedule" function is useful if you need to operate on a certain element, but you don't know when it would be ready. It uses a timer to check for the element tag on the page at regular intervals. A callback function is called when the element tag is detected, otherwise it will exit once the timeout period is reached. Hopefully that's enough to get your curiosity going. =============================================================================== Notes =============================================================================== This plugin has been developed for Wordpress version 1.5.2 and up. I'm can't guarantee that it works on older versions. You can give it a try if you wish, but I'm not going to be held responsible if anything horrible happens. If you are prudent and do backups before experimenting with new plugins, you should not have anything to worry about. Having said that, I'm quite certain that the only horrible thing that might happen after installation of this plugin is the fact that the author can be quite lazy and updates are far and few in between. Hopefully, the code is relatively bug-free and there won't be a need to update too regularly! If, you do find bugs however, or have some questions, or just want to say hi, you can contact me at: ink@bur.st Finally, if you find this plugin useful, it would be nice if you acknowledge it in some way. How? I leave that up to you. :o) Enjoy! John Ha (aka khanh) ******************************************************************************* Copyright (c) 2005, 2006 John Ha ******************************************************************************* This work is licensed under the Creative Commons Attribution License. To view a copy of this license, visit http://creativecommons.org/licenses/by-nc-nd/2.5/ ******************************************************************************* If this code has helped you in anyway, any acknowledgement would be appreciated *******************************************************************************