viewing source for "README"
last commit
commit cadf0a02a370feae0ecc84b80b76dd765595addd
Date: Sun Feb 3 10:13:41 2008 -0800
source code
001: # Expand Comments for Wordpress #
002:
003: The Expand Comments Plugin provides Wordpress with the
004: ability to expand the comments of a post below to any point
005: on a page using AJAX. What this means, is that a user can
006: click the "Expand Comments" link, and have the comments be
007: added to the page, no refresh required. The "flow" of the
008: site is not changed (the user can stay on the main blog
009: page) as well as provides a streamlined feel to the blog.
010:
011: As of newer versions, it also has the optional ability for
012: users to post comments via ajax. This means no page
013: redirects/reloads after they press the submit button.
014:
015: Expand Comments has been tested on WP versions 2.0+ and 2.1
016:
017: ### Technical Features ###
018:
019: * Comments are not downloaded until link is clicked
020: * Comments can then be hidden by clicking the same link
021: * Inline comment submissions (AJAX enabled) so visitors
022: can post comments without leaving the front page (no
023: refreshes required!)
024: * User definable loading message (supports images/html)
025: * Post author's comments use unique CSS to allow for
026: different styling
027: * Comments are only downloaded once, subsequent
028: expands/contracts just show/hide the comments using css
029: styles
030: * Uses simple javascript and css
031: * User definable CSS to match your style
032: * Easy to setup and use
033: * Graceful degredation for browsers without javascript.
034: Expand Comments link simply acts as the post's
035: permalink.
036:
037: ## Demo ##
038:
039: You can see an online demo at my test Wordpress page [here][1]
040:
041: ## Installation ##
042:
043: Installation is easy, just download the zip file from below,
044: and unzip it to your `wp-content/plugins` folder. Inside the
045: zip is a directory with the plugin files. Feel free to edit
046: these if you want, but this is not required for normal
047: operation.
048:
049: Check that the plugin is seen by WP by going under the
050: plugin options. Go ahead and activate it now. Now, you have
051: to edit the index.php (and archive.php) file of your theme
052: by adding two (2) lines. The only requirement to these edits
053: is that you place the lines inside "The Loop" where each
054: post gets entered. If you aren't sure what this means, if
055: you see `<?php the_ID(); ?>` then you're good (Expand
056: Comments uses the ID to determine which post to expand).
057:
058: The first line to add is the "Expand Comments" link. To do
059: this, open up index.php and find where you want the link,
060: then insert the line `<?php expand_comment_link(); ?>`
061: where you feel its appropriate. I put mine at the end of the
062: postmetadata section.
063:
064: Now, we need to specify where each post's comments are
065: going to go once that link is pressed. To do this, we have
066: another php function that adds a div to where the function
067: is called. When you find a spot (below the post is probably
068: best) add the line `<?php expand_comment_div(); ?>`
069: Remember, this adds a div to the page, so don't put it
070: inline with anything.
071:
072: And that's it, you comments are now AJAX'd! If you'd like,
073: you can keep reading about how the plugin works, but this
074: isn't necessary.
075:
076: ## Hacking the Plugin ##
077:
078: First, lets get a very basic overview of how the plugin
079: works. Expand Comments hooks into the wp_head action
080: (wp_head is called whenever the header is needed for a
081: page). This adds some vital javascript functions to the head
082: of each page. One of these functions is set to run on the
083: page load. This function looks for the specially tagged
084: links and modifies them so they will cause the plugin to do
085: its thing. By adding the above two php lines to your theme,
086: you are adding a link and a div to the page code that is
087: specially tagged for the javascript to find it.
088:
089: When the link is pressed, it first checks the status of that
090: post's comment div. If the div contains comments, it just
091: hides/shows them. Otherwise, it makes an AJAX request to
092: the exp-com.php file, which returns the comment data.
093:
094: The AJAX call can be a tricky thing to understand. The call
095: actually returns before the data is downloaded, the function
096: basically just says "Go get this data, and let me know when
097: its done". The "hey its done" message is sent by executing a
098: function that you tell it to. So the communication goes as
099: follows:
100:
101: **Plugin**: "Go get this data, and run 'myFunction' when you have it".
102:
103: **AJAX**: "Okay, I'm working on it".
104:
105: **Plugin**: Continues on working on other stuff.
106:
107: **AJAX**: "Hey, the data just got back to me!"; `myFunction(data)`
108:
109: So from the above example, Expand Comments does the
110: following: Plugin tells AJAX to get the comment data for a
111: certain ID number. AJAX asks the server for the data. When
112: it gets the data, AJAX calls the function that parses that
113: data and puts it into the div.
114:
115: ### Included Files ###
116:
117: Now the specifics, first we need to know what each file is
118: responsible for in the plugin.
119:
120: #### expand-comments.php ####
121:
122: This is the actual plugin file. It contains code that hooks
123: Expand Comments into Wordpress via actions, as well as the
124: expcom class that contains all of the functions for Expand
125: Comments. This is where the getter/setter functions are for
126: all of the options, as well as the expand_comment_*
127: functions. This most likely won't need to be edited
128:
129: #### expand-comments.js ####
130:
131: This is where all the AJAX magic like above happends. Inside
132: thise file contains javascript to make AJAX requests using
133: GET or POST.
134:
135: #### expand-comments-events.js ####
136:
137: Holds the meat of the javascript. This is where the onLoad
138: javascript function that modifies the RSS links to the
139: Expand/Collapse links. This also has functions for expanding
140: the div, submitting comments, and inserting/removing
141: comments from the div.
142:
143: #### expand-comments-ui.php ####
144:
145: Holds the option page for Expand Comments
146:
147: #### exp-com.php ####
148:
149: This talks to the database, and returns comment data in the
150: form of XML. Browsing to this file with the query ?id=X
151: where X is a post number will show you all of the data you
152: can access. Take a look at the file to see how you can
153: modify what it returns.
154:
155: #### inline-comment-form.php ####
156:
157: This file holds the submit comment form for when comments
158: are expanded. This was taken from the default WP theme
159: (with slight modifications). This also has a call to the
160: AJAX comment submit code. Feel free to edit this file for a
161: customized form.
162:
163: #### style.css ####
164:
165: This file is a dummy css file. It contains the default
166: elements, but no styling information. Edit this to fine
167: tune the style of the expanded comments. **Note**: If you
168: have changed the CSS class/id names in the options page, you
169: will have to change theme here to match.
170:
171: ### CSS ###
172:
173: You can set the CSS classes/ids in the options page, and use
174: the style.css file to match your theme. If you're lucky,
175: renaming the classes/ids to match your theme might be all
176: it takes to get it to look right.
177:
178: And that's all you need to know! Let me know if you want
179: more details on anything, and I'll be happy to expand upon
180: the above.
181:
182: [1]:http://dwords.voidsplat.org/