NP_CurrentMedia : NUCLEUS CurrentMedia plugin ReadMe file. last updated: 1/4/2005 2:02 AM ******************************************************************* ******************************************************************* *** *** *** Please read this ENTIRE file before contacting for support. *** *** *** ******************************************************************* ******************************************************************* ... CONTENTS ... 1. Introduction 2. Requirements and Installation Instructions 3. Upgrade Instructions 4. Plugin Options 5. Usage 6. Questions 7. Known Issues / To Do 8. Bug Reports / Contact 9. Thanks 10. Changelog ... INTRODUCTION ... -------------------- The CurrentMedia plugin allows you to use the Amazon.com search engine to attach a "Currently Reading/Watching/Listening" block to your Nucleus posts. It automates the process by providing a popup window to perform the search. Then with a couple clicks of your mouse button you will have the block attached to your Nucleus post, along with a thumbnail image (if available) and a direct link to the item on Amazon.com. If you are an Amazon associate (a free program to join), you can have your associateID included in the media links, meaning potential commission fees if viewers click the links and buy the item themselves. ... REQUIREMENTS AND INSTALLATION INSTRUCTIONS ... -------------------------------------------------- This plugin requires Nucleus version 2.0+, and a Javascript enabled web browser. Unzip the file 'CurrentMedia.zip' and upload the contents into your plugin directory. By default this directory is 'nucleus/plugins', but may vary depending if you used different folder names when you installed Nucleus. Login to your site's Nucleus administration area, and go to the plugin page under "Nucleus Management". Scroll down to the "Install New Plugin" heading, and select "CurrentMedia" from the drop-down selection box. Then click "Install". The plugin should be installed now and will show up in the list of installed plugins (same page). ... UPGRADE INSTRUCTIONS ... ---------------------------- Upgrading from v0.4: 1. On the plugin page of the Nucleus Admin Panel, click 'edit options' for the CurrentMedia plugin and make sure the option to "Delete this plugin's table and data when uninstalling?" is set to 'no'. 2. On the plugin page of the Nucleus Admin Panel, uninstall the CurrentMedia plugin. 3. Upload the new version CurrentMedia files on top of the existing CurrentMedia files. This includes all files in the currentmedia/ subdirectory. 4. On the plugin page of the Nucleus Admin Panel, install the CurrentMedia plugin. Upgrading from v0.3 or earlier: 1. In file NP_CurrentMedia.php, make sure the sql_query line in function "unInstall()" is commented out. Comments are indicated by two forward slashes. The line should look like: // sql_query('DROP TABLE ' . sql_table('plugin_currentmedia') ); 2. On the plugin page of the Nucleus Admin Panel, uninstall the CurrentMedia plugin. 3. Upload the new version CurrentMedia files on top of the existing CurrentMedia files. This includes all files in the currentmedia/ subdirectory. 4. On the plugin page of the Nucleus Admin Panel, install the CurrentMedia plugin. STEP 1 is important because if that line is not commented out for some reason, all previous media data will be deleted upon uninstalling the plugin. Default installations of CurrentMedia have this line commented out, so unless you have uncommented that line, everything should be OK. It's a good idea to double check, though, before uninstalling the plugin. ... PLUGIN OPTIONS ... ---------------------- From the plugin page, click "edit options" on the Current Media plugin. First, there is an option to choose which Amazon site to search. Amazon.com and Amazon.de are currently supported. Then, if your website is in a different language, there are options for translations of the words that will display in the Current Media block on your weblog. The defaults are English, so no changes are necessary if your weblog is in English. If you have an Amazon Associate ID, you may enter it in Associate ID field. This will be used in the creation of all links, meaning potential commission fees if people click the links and buy the item. The default associate ID is for the Nucleus project, meaning the Nucleus project will receive any commission fees generated unless you change the Associate ID. ... USAGE ... ------------- To display the CurrentMedia block on your Nucleus posts, insert the tag <%CurrentMedia%> in the appropriate template(s). This plugin works per-item, so the tag must be in a template, not a skin. _It will not work in a skin._ The CurrentMedia block is constructed using a table, and the style can be controlled using CSS. There are 3 classes associated with the block. Add definitions for these CSS classes to your stylesheet: 'cm_table' = in the TABLE tag 'cm_image' = in the TD tag enclosing the thumbnail image 'cm_text' = in the TD tag enclosing the media text When adding a new item, you will see a section for the Current Media plugin under the "Extra Plugin Options" heading. Click the appropriate link for 'Reading', 'Watching', or 'Listening' to popup the search window. The search window is pretty straight-forward: type in the keyword you want to search for and click 'Search'. The first 10 results will load in the window. At the bottom will be links to the rest of the results if there were more than 10. Click "select this" next to the media item that you want, and it will automatically be inserted on the Add Item page. When editing an item, if no media item has been added already, the procedure is the same as above. If a media item has been added previously, you will see the media information, along with links "change" and "delete". Click "delete" to delete the media item (note: the deletion actually occurs when you click "Edit" on the Edit Item page). Click "change" to change the media item, which works as explained above. ... QUESTIONS ... ----------------- Q: I clicked 'delete', why wasn't the media data deleted from the weblog item? A: The actual deletion isn't committed until you finalize your edit of the weblog item by clicking "edit". Q: I clicked 'change' and selected another media item, why doesn't it change on the weblog item? A: The actual update of the media item isn't committed until you finalize your edit of the weblog item by clicking "edit". ... KNOWN ISSUES / TO DO ... ---------------------------- . Add more language support for the plugin popup window. They are currently hard-coded in English. . Add more Amazon sites as search options. . Add option to not search at all but just enter the media information, since not everything is on Amazon.com (*gasp*). Specifically in mind for independent media. . Some people are having weird problems with the plugin not working entirely. I'm not sure if this is a matter of PHP version, lack of XML support in their PHP install, or some other reason. Need to perform some checks on plugin install to warn users if the plugin is not going to work for them. . I am not a javascript professional, so it's possible this plugin may not work too elegantly in some browsers. Suggestions for improvement and compatibility are welcome, as well as any bug reports of course. [See 'Bug Reports / Contact' section] ... BUG REPORTS / CONTACT ... ----------------------------- Please post on the Nucleus forums *FIRST*. That is my preferred method of communication. I will do my best to check at least once a week on there, typically more often than that. If for some reason you don't hear back from me on the forum within a week, feel free to visit my website and use my contact form there. Nucleus forums: http://forum.nucleuscms.org My site: http://www.gregorlove.com ... THANKS ... -------------- Thanks to jaal for the help/inspiration to add different language Amazon sites. Thanks to roel for his update to NP_CustomField. I took his idea for the plugin option whether to delete the table data upon uninstall. And last but not least, thanks for the users of this plugin for their feedback and their patience with me fixing things. :) ... CHANGELOG ... ----------------- Version 0.5 + Added plugin capability to list "Currently Playing" video games + Added DOCTYPE to popup search window + Corrected minor bug that would show PHP errors for books with no authors listed + Cleaned up/streamlined miscellaneous parts of the code. (I'm a neat freak sometimes :D ) Version 0.4 + Fixed "apostrophe" bug by escaping certain characters before inserting in the database. + Moved popup stylesheet to its own css file. + Added Amazon.de as a search option. + Added language options (for the plugin words that display on the weblog) + Added plugin option to delete the tables and data on uninstall, defaulted to 'no'. (thanks roel!) + Changed to use HTTP_POST_VARS and HTTP_GET_VARS for compatibility with PHP versions < 4.1.0 + Added correctly functioning supportsFeature switch statement. + Added "Upgrade Instructions", "Plugin Options", and "Thanks" sections to this README file. Version 0.3 + Corrected missing IDs from form fields that was causing javascript errors in Mozilla Firefox (and maybe Opera). + Updated file structure and coding for easier readability . Version 0.2 + Fixed a bug with embedded FORM tags. The bug caused the "Extended Entry" field to not be stored in the database. + Added CSS to the popup window to make it look like the default Nucleus admin area. + Stable release. Version 0.1 + Stable pre-release.