Insert Node Usage

Syntax

The Insert node tag syntax is:

   [node:<name of node> <parameters>]

Name of node

The <name of node> can either be

  • The name of the node, i.e. it's URL without the protocol and domain1, or
  • The node identifier (the number you see in your URL when you edit the node), or
  • An asterisk (*) in which case the current node applies2 (6-1.2).

As pointed out by one of our users, the asterisk can be used to create macros.

Parameters

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]

Final Output

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:

  1. insert-node
  2. insert-node<count>
  3. insert-nid<node-nid>

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".

  • 1. For instance, to insert this very node, I would use the name doc_insert_node_usage.
  • 2. The asterisk is useful to repeat something from the node in a block. This could be the title of the node or a CCK field. I would suggest you avoid using the body of the current node in a block!
  • 3. It is important to note that the value ends with a semi-colon and it cannot itself include a semi-colon.

Insert Node Parameter: "default" [no content parameter] (5-1.x)

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

Insert Node Parameter: body (5-1.x)

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)

Insert Node Parameter: booktree (6-1.2)

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.

Insert Node Parameter: cck (6-1.2)

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).

cck=field_<name>; [requires CCK]

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)

cck=body;

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)

 

cck=book_children; (6-1.3) [requires book]

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)

 

cck=book_navigation; (6-1.3) [requires book]

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)

 

cck=teaser;

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)

 

cck=title; (6-1.3)

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 &lt;, etc.)

See Also: Insert Node Parameter: title (6-1.1)

 

cck=webform; (6-1.3) [requires webform 2.x+]

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.

Insert Node Parameter: cckteaser (6-1.3)

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.

Insert Node Parameter: collapsed (6-1.0) [no content]

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.

Insert Node Parameter: collapsible (5-1.x) [no content]

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.

Insert Node Parameter: comments (6-1.1) [no content]

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.

Insert Node Parameter: content (6-1.0)

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)

Insert Node Parameter: created (6-1.0)

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)

Insert Node Parameter: demote (6-1.2) [no content]

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.

Insert Node Parameter: edit (6-1.2)

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)

  • 1. It may appear even to users who do not have edit permission (which is a bug,) although it still won't allow them to edit anything.

Insert Node Parameter: imagefield or imagecache (6-1.3)

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:

  • default — show the image as is
  • link — show the image with the link specified in the CCK field

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.

Insert Node Parameter: link (5-1.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.

Insert Node Parameter: modified (6-1.0)

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)

Insert Node Parameter: more (6-1.1)

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.

Insert Node Parameter: noterms (6-1.1) [no content]

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)

Insert Node Parameter: override (6-1.3) [special]

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:

  • Node parameter
  • CCK parameter

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)

Insert Node Parameter: page (6-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)

Insert Node Parameter: plain (6-1.2) [no content]

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.

Insert Node Parameter: repeat (6-1.2) [no content]

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!

  • 1. As far as I can tell, this will not create recursive calls, however, if you have a problem with a macro using repeat, try to remove the keyword to see if that solves the problem. If so, let me know by opening an issue or posting a comment below and I can look into a way to prevent the recursion. Thank you.

Insert Node Parameter: target (6-1.4) [no content]

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):

http://www.w3.org/TR/1999/REC-html401-19991224/types.html#h-6.16

Insert Node Parameter: teaser (5-1.x)

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)

Insert Node Parameter: themed (6-1.0)

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)

Insert Node Parameter: title (6-1.1)

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 Node Parameter: webform (6-1.3)

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.