The following pages are the official documentation of the InsertNode module available on Drupal.
This module is a filter used to insert a node in another. Version 5.x is only being maintained. Version 6.x still evolves as time passes. It is already pretty powerful!
Since this is a filter, you can use it to insert a node in any text area that supports filters by including the InsertNode filter in it.
It works by using the simple syntax:
[node:<node name or nid or *1> <parameters>]
The following describes all the available parameters and how to use all the neat features of this module.
Version 6.x added many new features (parameters, themes, etc.) to the module. However, the tags themselves remain backward compatible except for those two parameters:
The D5 version will insert the node content and make it collapsible or collapsed.
The D6 version inserts nothing on these parameters. It only makes the result collapsible or collapsed.
So if you are using D5 and want to keep the collapsible and collapsed look the same, you must add the body keyword as in:
[node:123 body collapsible]
[node:123 body collapsed]
Decompress the module in your sites/all/modules folder.
Go to admin/build/modules (Admin » Site Building » Modules) and select the new module (under package named "Filters input".)
Go to admin/settings/filters (Admin » Site Configuration » Input formats) and select the Insert node filter1.
Make sure that the text areas using the [node:...] tag make use of one of the formats having this Insert node filter turned on. The Input format field set shows [node:123 parameters] for any format that supports the Insert node filter.
You are ready!
The Insert node tag syntax is:
[node:<name of node> <parameters>]
The <name of node> can either be
As pointed out by one of our users, the asterisk can be used to create macros.
All the <parameters> are optional. Since version 6-1.1, some parameters accept a value (i.e. cck, link, more, etc.) This is defined as:
<parameter>=<value>;3
It is expected that each parameter is used at most once. However, it is valid to specify the same parameter twice (as in "title body title" to include the title before and after the body.) For some parameters (i.e. collapsed, demote, etc.), only the last instance is taken in account.
By default, not including any parameters that add content is similar to using content (see below.) However, the default uses a separate theme and therefore it can be made different by overloading the theme named InsertNode_default.
In Drupal 5, you can only specify one parameter. And the collapsible option automatically includes the body.
In itself, the order of the parameters is not important. However, in most cases it defines the order in which you want the data to be displayed. So if you want the title, teaser and more link in that order, you must enter them in that order as in:
[node:article41 title teaser more]
Once the output was generated, it is themed one last time using the InsertNode_node theme.
The default InsertNode_node theme adds one more <span> or <div> around the output and includes three classes:
These classes can be used to create advanced CSS output specific to a node or an entry insert on another page.
A <span> is used if the Insert Node inserts only <span> or no tags. Otherwise, a <div> is used.
NOTE
The version defined between parenthesis in the list below shows the time when the given parameter appeared. Parameters that were available in 5-1.0 are still available in 6-1.2, for instance. When a parameter changed in some way, it is indicated in its definition.
The parameters that are marked as [no content] do not insert any content and thus do not affect the insertion of the "default" data. In other words, if you only used parameters that are marked [no content], you will get the "default".
By default, the node tag can be used without any of the parameters that add content (the parameters without the [no content] comment in their description title.) In that case, the content of the node is inserted as if content had been specified.
However, since version 6-1.1, the theme of the default parameter can be overloaded. This means you can change the default by writing a function to overload the default.
CSS Class: div.insert-node-content
Theme: InsertNode_default
Display the body of the node, the terms and the CCK fields. Input filters are applied.
CSS Class: div.insert-node-body
Theme: InsertNode_body
See Also: Insert Node Parameter: content (6-1.0), Insert Node Parameter: page (6-1.2), Insert Node Parameter: teaser (5-1.x), Insert Node Parameter: themed (6-1.0)
If you have books and you are using the booktree module, then you can insert a book tree in another node using the Insert node module with the booktree parameter.
The book tree will start with the specified node.
See Also: Insert Node Parameter: cck (6-1.2)
IMPORTANT NOTE
This parameter is an extension that should be part of the booktree module and not of the Insert Node. It made not be supported in future versions (3.x, D7...)
The Insert Node module verifies that the user has permission to view that book tree. If not, nothing is output which means that the tag may instead generate the "default" output.
The CCK parameter let you insert one of your CCK field and some node fields that cannot otherwise be added without being themed.
We support CCK fields and several special field names as follow.
Fields that appeared after version 6-1.2 have a version specified between parenthesis (i.e. 6-1.3).
The CCK parameter must be followed by a field name. An empty name is likely to generate an error. The name of a field that does not exist is likely to generate nothing.
For instance, if you have a field named see_also, you would write:
cck=field_see_also;
See Also: Insert Node Parameter: cckteaser (6-1.3)
This inserts the body data as is (without being themed). The body data is still parsed through all the input filters.
Note that in case of a book, only the description of the book will appear with this option. To get the navigation, use the book_navigation field.
See Also: Insert Node Parameter: body (5-1.x)
A book page includes a navigation panel that include a list of children (sub-pages) and a set of three links at the bottom (previous, parent, and next.) This field can be used to only show the children of that book page.
See Also: Insert Node Parameter: booktree (6-1.2)
A book page has a description, which is the regular body of the page, and a navigation. The navigation is composed of a list of children and a set of links: previous, parent, and next. This option extracts that portion of a book page.
See Also: Insert Node Parameter: booktree (6-1.2)
This inserts the teaser data. Like the cck=body; parameter, it is parsed through all the input filters, but not themed.
See Also: Insert Node Parameter: teaser (5-1.x)
This inserts the title without any decoration (H2 tag, for instance.) The title is passed through the check_plain() function replacing any character that would otherwise generate a problem to your HTML (i.e. < is transformed into <, etc.)
See Also: Insert Node Parameter: title (6-1.1)
This option inserts the form of a webform node. When inserting the body of a webform everything is included (i.e. description, terms, links...)
See Also: Insert Node Parameter: webform (6-1.3)
IMPORTANT NOTE
Note that the parameter value ends with a semi-colon! Do not include quotes unless you want to see them in the output. Yes. This means the text cannot include a semi-colon as is. Since CCK field names should not include semi-colon, you should have no problem.
Many of the special fields, such as the cck=body; and cck=teaser; always work. Some of the fields, however, require a module or another, such as the CCK module, to be installed. When a CCK field is used without the CCK module installed, the Insert Node module output an inline error letting you know that you need to install and enable the CCK module.
The CCK parameter let you insert one of your CCK field in full. This parameter, cckteaser, let you insert the teaser of your CCK field.
This feature uses the teaser flag of the CCK module in order to insert the teaser data. This means only the field_<name> fields make the distinction between cck=... and cckteaser=..., the other fields simply ignores the difference.
For more information on the CCK field names that are supported, check the Insert Node Parameter: cck (6-1.2) page.
IMPORTANT NOTE
Note that the parameter value ends with a semi-colon! Do not include quotes unless you want to see them in the output. Yes. This means the text cannot include a semi-colon as is. Since CCK field names should not include semi-colon, you should have no problem.
This option requires the CCK module to be installed. When it is used without the CCK module installed, the Insert Node module output an inline error letting you know that you need to install and enable the CCK module.
Put the generated content inside a collapsible frame.
The frame is collapsed at the start.
By default, the title of the node is used as the title of the frame. You can specify (since 6-1.2) the title as the value of the parameter:
collapsed=There is my other node, click to read it;
See Also: Insert Node Parameter: collapsible (5-1.x) [no content]
IMPORTANT NOTE
Note that the parameter value ends with a semi-colon! Do not include quotes unless you want to see them in the output. Yes. This means the text cannot include a semi-colon as is.
Put the generated content inside a collapsible frame.
The frame is expanded at the start.
By default, the title of the node is used as the title of the frame. You can specify (since 6-1.2) the title as the value of the parameter:
collapsible=There is my other node;
See Also: Insert Node Parameter: collapsed (6-1.0) [no content]
WARNING
The version of the module for Drupal 5.x outputs the body whenever the collapsible parameter is used.
IMPORTANT NOTE
Note that the parameter value ends with a semi-colon! Do not include quotes unless you want to see them in the output. Yes. This means the text cannot include a semi-colon as is.
Attach the comments at the bottom of the node data.
The comments will be shown just as in the regular page (i.e. flat, thread, expanded, collapsed.)
Note that this data is considered a [no content] because it does not affect the use of the "default" parameter. However, it definitively adds content to your output.
CSS Class: div.insert-node-comments
Theme: InsertNode_comments
IMPORTANT NOTES
The comments are appended to anything else that you have inserted. You cannot use the order of your parameters to put the comments in a different location. In order to do that, use multiple node tags.
Specifying comments multiple times will insert the same comments multiple times.
If the comments module is not installed and enabled, this parameter adds an inline error letting you know that the comments module is not currently available. Either enable the module or remove the comments parameter.
Display the body of the node, the terms, the CCK fields, and the links. Input filters are applied.
When no output parameter is used, this is what appears by default. However, the "default" theme can be changed.
CSS Class: div.insert-node-content
Theme: InsertNode_content
See Also: Insert Node Parameter: body (5-1.x)
This parameter inserts the date when the specified node was created.
The date format defined for the site is used to display the date (see the Drupal function named format_date().)
CSS Class: span.insert-node-date
Theme: InsertNode_created
See Also: Insert Node Parameter: modified (6-1.0)
Demote (positive) or promote (negative) the headers found in the output before inserting it into your node.
This is useful if you want to include a complete node that has an H1 title, H2 sub-titles, etc. and make these sub-titles of your current page, maybe starting at H3 (i.e. using "... demote=2; ..." in your tag.)
By default, the value of this parameter is expected to be 1. To change the value use the following syntax:
demote=<integer>;
The integer can be negative, in which case it promotes the headers (i.e. H3 can be changed to H1 using "... demote=-2; ...")
This parameter, by itself, does not generate any output.
IMPORTANT NOTES
Note that the parameter value ends with a semi-colon! Only integers, eventually negative, are accepted in this parameter. An invalid integer will be transformed into the 0 or 1. Note that the value 0 has no effect.
Only the last demote parameter is taken in account.
This parameter adds a quick link to edit the node1.
CSS Class: span.insert-node-edit
Theme: InsertNode_edit
See Also: Insert Node Parameter: link (5-1.0)
The imagefield parameter allows you to insert a CCK image from the specified node.
The parameter must be set to a very specific value for the feature to function properly. The following describes the value:
imagefield=<field name>:<image cache value>:<type>:<index>
The <field name> is the name of the CCK field. You need to include field_ as the introducer. For example, a field you named image is referenced as field_image.
The <image cache value> represents the way the image is displayed. Most often it represents a size such as small, medium, and large.
The <type> tells the system how to generate the HTML. The Insert Node module supports two types:
The <index> returns that image from the CCK array. The default is zero (0) meaning that the very first image is returned. If you are not using a multi-image CCK field (i.e. limited to 1,) then you can ignore this field entirely.
An example to display the large image of you third photo field with the link:
imagefield=field_photo:large:link:2
Notice that the third photo is #2 since the counter starts at 0.
Display the title of the node as a link to the node, unthemed.
With version 6.x-1.1, it is possible to change the link to a text that you specify as in:
link=Read more about that in yesterday's post!;
CSS Class: span.insert-node-link
Theme: InsertNode_link
See Also: Insert Node Parameter: edit (6-1.2), Insert Node Parameter: more (6-1.1)
IMPORTANT NOTE
Note that the parameter value ends with a semi-colon! Do not include quotes unless you want to see them in the output. Yes. This means the text cannot include a semi-colon as is.
This parameter inserts the date when the node was last modified.
Note that a node that was never edited does not have a modification date. When that happens, the creation date is used instead.
The date is formatted using the default format date function (see the Drupal format_date() function.)
CSS Class: span.insert-node-date
Theme: InsertNode_modified
See Also: Insert Node Parameter: created (6-1.0)
Display the words "Read more..." with a link to the node, unthemed.
Useful when just the teaser or the title are being shown.
The text "Read more..." can be changed by specifying a string after the parameter like this:
more=Lire la suite...;
CSS Class: span.insert-node-more
Theme: InsertNode_more
See Also: Insert Node Parameter: link (5-1.0)
IMPORTANT NOTE
Note that the parameter value ends with a semi-colon! Do not include quotes unless you want to see them in the output. Yes. This means the text cannot include a semi-colon as is.
This parameter can be used to avoid inserting the terms of your node in the output.
It must be used before the "default", content, or any other parameter that inserts the node terms in the output.
See Also: Insert Node Parameter: "default" [no content parameter] (5-1.x), Insert Node Parameter: body (5-1.x), Insert Node Parameter: content (6-1.0)
WARNING
This parameter is considered a security hazard. There is an option in your format definition that you have to turn on in order for the feature to work. When not selected, override is ignored. Only allow this feature in an input filter where you can trust users 100%.
One can use the override parameter to replace the expected data with their own data. Although one would think using the data directly would work as well, there are cases when this is useful.
By default the InsertNode module gets data from the $node object as defined by the system. At times, the data available in the node needs to be tweaked with a forced value. This parameter is used for that purpose.
The parameter can be set to two different type of values:
The node parameter is defined with this syntax:
override=<field name>:<value>
The CCK parameter is defined with this syntax:
override=cck:<field name>:<value>:<key>:<index>
In both cases, <field name> is a field found in the $node object (i.e. $node->$field_name). This field is required.
In both cases, <value> is the new value of the indicated field. This field is required.
The <key> indicates the CCK field value name. By default it is 'value', which is what is necessary in most cases. This field is optional.
The <index> represents the array index. The default is 0. Remember that the array is zero based. So the 3rd item has index 2.
See Also: Insert Nodes used as a macro (6.x-1.2)
Display the body of the node, the terms, the CCK fields, and the links. Input filters are applied.
In this case the Insert Node tells the node that it is its page. Some modules will react differently than when body is used.
CSS Class: div.insert-node-page
Theme: InsertNode_page
See Also: Insert Node Parameter: body (5-1.x)
The plain keyword is used to avoid having the content being inserted put inside a tag. By default, the content is inserted inside a <span> or a <div> tag (<span> is used if the output does not include <div>, <p> and other such tags.)
Although one could overload the theme_InsertNode_node() theme function, it is at times practical to be able to use both methods.
The plain keyword does not otherwise generate any output.
This keyword primary use is for adding CCK parameters inside HTML code as proposed by one of our users (see here):
<input type="hidden" name="item_name" value="[node:book_abc cck=title; plain]" />
In this HTML example, we insert the title from the specified node named book_abc and make sure that no extra tags are included.
The repeat keyword is used to repeat the filtering on the data just inserted. This is particularly useful with the asterisk name or on nodes that do not otherwise include a format that transforms the tags included in themselves.
This let you create nodes that are like macros.
Note that the macro can itself include a repeat in one of its Insert Node tags.1
IMPORTANT NOTE
Try to avoid using the repeat keyword. To have deep recursivity, it is better to have (and probably easier to manage) all the nodes support the Insert Node filter instead.
IMPORTANT SECURITY NOTE
It is very important to note that in general we do not include a filter in a format because the users who have permission to use that format should not be allowed to use that filter.
For your macros, make sure that only users with permissions to use the Insert Node filter are allowed to create those macro nodes since their content will include one or more Insert Node tag that will be executed (filtered) in another node!
Add a window target in a link. For example
[node:123 target=_blank; link]
This option only applies to links and defines the target attribute of those links, as created with:
Insert Node Parameter: title (6-1.1),
Insert Node Parameter: link (5-1.0), or
Insert Node Parameter: more (6-1.1).
Using the target option by itself resets the Insert Node module to the default behavior (i.e. no target attribute):
[node:123 target=_blank; link target more]
The title link will have target="_blank" and the more link will not.
Note that this data is considered a [no content] because it does not affect the use of the "default" parameter. However, it definitively adds content to your links.
IMPORTANT NOTES
Note that the parameter value ends with a semi-colon! Only window names and special names are accepted in this parameter. An invalid window name will generally be ignored by browsers. See the following w3c documentation for more information (HTML 4.01):
https://www.w3.org/TR/1999/REC-html401-19991224/types.html#h-6.16
Display the teaser of the node and the terms. Input filters are applied.
CSS Class: div.insert-node-teaser
Theme: InsertNode_teaser
See Also: Insert Node Parameter: body (5-1.x)
Display the themed body of the node and the terms as if you were looking at that very node.
The CCK fields and links are not shown. The filters are not applied.
This means if you use a filter such as the footnotes filter with [fn]Info tags, they will NOT be transformed.
CSS Class: no class is added, this keyword returns the theme() call content immediately.
Theme: InsertNode_themed
See Also: Insert Node Parameter: body (5-1.x)
Display the title of the node inside an <h3> tag. It is otherwise unthemed.
To avoid the <h3> tag, use cck=title;, link, or more instead.
CSS Name: h3.insert-node-title
See Also: Insert Node Parameter: cck (6-1.2)
See Also: Insert Node Parameter: target (6-1.4) [no content]
See Also: Insert Node Parameter: link (5-1.0)
See Also: Insert Node Parameter: more (6-1.1)
Insert the form of a webform node. With this parameter you include the form that you defined in a webform in any node. The complete form will be included and fully functional. Remember, however, that the destination on save defined in the webform will be effective here too (although the default is to stay on the same page, which works as expected.)
The parameter is ignored if the referenced node is not a webform or if the webform module is not enabled.
It is now possible (See #418004: Comments included --> Back after reply) to have Drupal send you back to the page that inserts the node instead of the inserted node. Say you create node A and B. You include node A inside node B. You are looking at node B now. You decide to add a comment on node A (that you see from within node B.) Click on the Add new comment link, write the comment and click Save. At that point, you probably want to come back to node B instead of node A.
This feature is only necessary if you have the links at the bottom of the node and allow comments to show up.
The feature requires the jQuery plugins module installed and enabled. It is in the package named User interface. Note that because most people do not need this feature turned on, the Insert Node module does not require the jQuery plugins to be installed (it is not a hard coded dependency.)
IMPORTANT NOTES
This feature only works on nodes. It will not work for views and other special pages.
To spare some time, the HREF is changed only when someone clicks on the comment links. Thus, looking at the HTML code will not show any difference.
The Comments cannot be using the Preview feature or the destination query string will get lost. This is a problem in all of Drupal. It would be really neat to have a fix in Drupal 6.x though.
To send someone back to your home page:
You will find the necessary links on my home page: [node:home link]
To include a hidden node as a reference in a post:
I talked about that in my post yesterday. [node:yesterday_post_name body collapsed]
To include a node from a forum or story and keep the comments:
See below: [node:57 themed comments]
I changed the name of the module back to InsertNode (although I did not want to, I did not want to jeopardize the Drupal 5 version... which would probably have been fine, but well...)
So, the newer version of the D6 module is again called InsertNode.
To upgrade you will want to keep the other version running until you get the new version as the replacement (although you can manage your site the way you'd like this procedure let you switch from the previous version to the new version without having to turn off your site for a little while.)
The following are problems that have not been resolved and will probably not be.
At times, you enter the tag as in [node:123 cck=title] and it is not converted by the filter.
There are 3 common reasons for this to append:
The 3rd one is certainly the most likely explanation once you made sure that the filter was effectively selected for that node. In many cases, it will be the missing semi-colon after the parameter value. In the example above, the cck parameter must end with a semi-colon as in: cck=title;.
Otherwise, check that all the parameters are indeed valid parameters for the node filter version you have.
Finally, I have seen it happen: make sure that you do not include spaces in the name. If the node name has spaces, use the node identifier instead. The syntax does not allow for a node name with spaces1.
In the Drupal 5.x version, it is possible to create a loop when you insert nodes in circle (i.e. A inserts B which in turn inserts A.)
In the Drupal 6.x version we have a recursivity protection. If the module detects that a node inserts itself, then it breaks the loop and generates an inline error message. Fix the circling insertion to remove the error message.
A node can contain PHP code. In that case, it is not unlikely that the code will be executed multiple times when loading a page inside another. In other words, if you do something with a global or a static variable, they will eventually not be equal to what you expected on the second and further runs. Note that this may especially happen when CRON runs, since some CRON tasks may require many nodes to be loaded and executed multiple times.
For sure, one thing that will break the code is the redefinition of a function. You will want to protect any function definition as follow:
if (!function_exists('my_func')) { function my_func(arg1, arg2, ...) { [...] // your function code } }
Any other entity that can be declared only once needs to be protected in the same way.
Reference: https://www.drupal.org/node/607704
I have had issues from people who see taxonomy terms at the top and the links at the bottom (the taxonomy terms are also often called links, although technically, they are different.)
The terms can be removed using the Insert Node Parameter: noterms (6-1.1) [no content] option.
The other links appear or not depending on the option used. By default, they appear. See the Insert Node Parameter: body (5-1.x), Insert Node Parameter: page (6-1.2), Insert Node Parameter: content (6-1.0), Insert Node Parameter: teaser (5-1.x), and Insert Node Parameter: cck (6-1.2) fields.
Although the accessibility of the node and comments are checked, it is a good idea to see this module as a security risk giving users a way to display nodes otherwise forbidden to them.
Because a lot of the data is used unfiltered, it is strongly suggest that you pay very close attention to the order of your filters. If you authorize this module to your users (i.e. where they can select an Input filter that includes this specific filter,) then look into checking the HTML code after this filter. Otherwise, a user could inject some unwanted HTML code1.
This module can be used to create macros (as pointed out by one of our user in a Drupal issue.)
The following steps show you how you can create a macro with the Insert Node module.
First, create a node that is to become the macro. We will call this node macro. It is used without the Insert Node filter so the Insert Node tags do not get changed. This is important since we reference the main node (with the asterisk) and that reference would look like a recursive reference.
One idea is to use the macro as a PayPal button which gets set with parameters from another node. This means you create a PayPal form with different <input> tags and expect the Insert Node to fill in the data.
<input name="item_name" type="hidden" value="[node:* cck=title; plain]" />
Repeat these entries as required (cost, ISBN, etc.)
Once ready, save the macro. This node, by itself, will not work for end users. Whenever easily done on your system, hide the Insert Node from your users.
Now, we create another node that is to use the macro. That new node includes the macro with the following tag:
[node:macro cck=body; repeat]
The repeat parameter ensures that what is being included is itself re-parsed by the Insert Node filter (by default it isn't since we expect the child node to already have been filtered by Insert Node, but remember, in our case, that is not the case!)
Save this node and see the result! The node CCK fields appear in your macro fields!
Insert Node Parameter: cck (6-1.2)
There is a Link Node project that can be used to generate a link to a node using the node title or another user specified title.
This is similar to using the following with Insert Node:
[node:<name> title=<my link>;]
If you want to include a view, use the insert_view module instead.
If you want to include blocks in your nodes (or other blocks, scary, hey?!), use the insert_block module instead.
If you know or have a similar project, please, feel free to post a comment below and I will add it to the list.
Thank you.
Alexis Wilke