Removed calltime pass-by reference
[project/nodecomment.git] / README.txt
1 ABOUT THE NODE COMMENTS
2 =======================
3
4 With this module comments can be full nodes. For every content type you can 
5 choose to use different content type as comment, or to continue using Drupal 
6 core comments.
7 Thanks to this module, comments can have fields, revisions, taxonomy, 
8 uploaded files, access control and anything else that comes from the goodness 
9 of nodeapi.
10
11 Current maintainer: Andrey Tretyakov http://drupal.org/user/169459
12
13 REQUIREMENTS
14 ============
15
16 Views module.
17
18 USAGE AND TECHNICAL DETAILS
19 ===========================
20
21 Node Comments module has settings page at admin/settings/nodecomment. There you 
22 can get overview of your content types and their Node Comment settings.
23 The module also uses Comment module settings, configured per content type.
24
25 Comment types can have own comments. For example, a site can have 
26 products, commented by reviews, commented by comments.
27
28 Comment types can be enabled to work as "content", meaning they will have own
29 pages, full node titles (independently from the comment settings) and generally
30 behave as content. The only requirement currently is they must be added in 
31 comment context, i.e. via "Add new <type>" link for their target node.
32
33 Node Comments displays comments using "nodecomments" view. You can configure 
34 the view to tweak some options, but "Nodecomments" (second) display is always 
35 used, and you can switch display style (e.g. set it to "table") only when node 
36 comments are configured as flat in content type configuration. In threaded mode 
37 Node Comments module forces usage of own display style.
38
39 When deleting a node with node comments, or a node comment, child node comments
40 will be automatically deleted even if the user performing the delete doesn't 
41 have delete permission for them. This may be surprise for you if you previously
42 used 2.x branch. This is needed not to leave orphan nodes in the database and is 
43 generally in line with the core Comment module logics.
44 This behavior can be changed programmatically (see Node Comments API).
45
46 To theme the node comments, use general node templates. There are some tricks, 
47 in terms of theming, though.
48 First, because we generally repeat comment module stuff, we use "comment-123" 
49 anchors (where 123 is node id). You must add these anchors to your nodecomment 
50 templates for consistent scrolling.
51 When previewing a nodecomment on the same page with the thread, the module
52 will try to scroll to preview zone using "#preview" anchor. This
53 anchor is missing from the original theme_node_preview() function so you need 
54 to add it using theme override.
55
56 KNOWN ISSUES
57 ============
58
59 This module may consume more resources and run slower than the core Comment 
60 module. To increase performance there is special Views caching plugin which 
61 caches the view output (a list of node comments). It can cause problems with 
62 modules expecting to modify node output in the list dynamically.
63 There are 2 solutions to this problem:
64 - the caching can be disabled via Views UI
65 - using hook_views_post_render() one can insert dynamic values in the cached 
66   output. This is similar to what Node Comments module itself does. 
67
68 To render node comments, the module overrides node view menu callback. This can
69 conflict with other modules doing the same. This is a limitation of Drupal: only
70 one function can process menu item. To deal with this problem, you can use 
71 Panels module and output combined data from both Node Comments and conflicting 
72 module. For more information, see http://drupal.org/node/477518.
73
74 Unlike 2.x branch, 3.x doesn't have comment conversion tool anymore. It had too
75 many bugs and could lose data. Current maintainer is not comfortable supporting 
76 it. It can be revived as a separate module anytime, if someone is willing to do 
77 that.
78 This means that changing comment type when comments of that type already exist 
79 can turn them into orphans, and break the database consistency. You are STRONGLY
80 recommended to configure comment types only once.
81
82 For efficiency and reliability the module uses MySQL-only upsert (merge) 
83 queries. If you want to make the module work with Postgres, submit a patch.
84
85 COMPATIBILITY WITH COMMENT MODULE
86 =================================
87
88 Previous branches of Node Comments had various issues with Comment module:
89 - 1.x branch was not compatible at all
90 - 2.x branch had many hacks, resulting in lots of bugs and compatibility issues 
91   with other contributed modules
92
93 3.x branch has exactly one hack: when loading a node with node comments enabled,
94 it moves "commentability" setting to own variable, so other modules 
95 think the node can't be commented using Drupal core comments. When saving 
96 the node, Node Comments restores that setting. Thus we fully re-use Comment 
97 module default "commentability" setting and per-node "commentability" setting.