Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with
or
.
Download ZIP

Loading…

Partials documentation improvements #994

Closed
wants to merge 4 commits into from

2 participants

@MattiSG

Hi there,

I and some friends had some trouble figuring out how the partials parameter passing happened. Now that I have it (hope so!) figured out, I tried to make the documentation clearer :)

Feel free to take as many or few commits as you wish, I tried to separate them into several levels of doc refactoring.

Greetings,
Matti

MattiSG added some commits
@MattiSG MattiSG [doc] Made partials parameters naming system clearer.
Corrected res.partial() link's href.
d71fb06
@MattiSG MattiSG [doc] Improved partials doc with a note regarding naming conventions …
…and Express' specificities with it.

Rephrased the performance note regarding partials.
0c20102
@MattiSG MattiSG [doc] Renamed partials examples' varnames to avoid ambiguity regardin…
…g the name of the created local.

(It wasn't clear whether the name of the local var was inferred from the name of the partial or from the name of the passed variable.)
f5f85eb
@MattiSG MattiSG [doc] (missing a part)
Renamed partials examples' varnames to avoid ambiguity regarding the name of the created local.
(It wasn't clear whether the name of the local var was inferred from the name of the partial or from the name of the passed variable.)
b5e6460
@jonathanong

sorry for the delay. the express docs have moved from the gh-pages branch to https://github.com/visionmedia/expressjs.com

@jonathanong jonathanong closed this
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Commits on Feb 6, 2012
  1. @MattiSG

    [doc] Made partials parameters naming system clearer.

    MattiSG authored
    Corrected res.partial() link's href.
  2. @MattiSG

    [doc] Improved partials doc with a note regarding naming conventions …

    MattiSG authored
    …and Express' specificities with it.
    
    Rephrased the performance note regarding partials.
  3. @MattiSG

    [doc] Renamed partials examples' varnames to avoid ambiguity regardin…

    MattiSG authored
    …g the name of the created local.
    
    (It wasn't clear whether the name of the local var was inferred from the name of the partial or from the name of the passed variable.)
  4. @MattiSG

    [doc] (missing a part)

    MattiSG authored
    Renamed partials examples' varnames to avoid ambiguity regarding the name of the created local.
    (It wasn't clear whether the name of the local var was inferred from the name of the partial or from the name of the passed variable.)
This page is out of date. Refresh to see the latest.
Showing with 26 additions and 9 deletions.
  1. +26 −9 docs/guide.md
View
35 docs/guide.md
@@ -515,28 +515,45 @@ These paths may also be absolute:
### View Partials
-The Express view system has built-in support for partials and collections, which are "mini" views representing a document fragment. For example rather than iterating
-in a view to display comments, we could use partial collection:
+The Express view system has built-in support for partials and collections, which are "mini" views representing a document fragment. For example, rather than iterating in a view to display comments, we could use the following partial call:
- partial('comment', { collection: comments });
+ partial('comment', { collection: commentsArray });
If no other options or local variables are desired, we can omit the object and simply pass our array, which is equivalent to above:
- partial('comment', comments);
+ partial('comment', commentsArray);
-When using the partial collection support a few "magic" locals are provided
-for free:
+#### Variables passing
+
+Inside the partial, variables contained in the iterated objects (in the given example, comments represented as objects in the `commentsArray` array) are contained in an object that has the name of the partial. So, in the example above, if a comment had the following structure:
+
+ {
+ author: "Username",
+ content: "Some text"
+ }
+
+…you could access each value through `comment.author` and `comment.content`.
+
+If you would prefer to explicitly name the passed variables, see the full documentation for [res.partial()](#res.partial()) and its `as` option.
+
+In addition to these passed variables, the following "magic" locals are provided for free:
* _firstInCollection_ true if this is the first object
* _indexInCollection_ index of the object in the collection
* _lastInCollection_ true if this is the last object
* _collectionLength_ length of the collection
-Local variables passed (or generated) take precedence, however locals passed to the parent view are available in the child view as well. So for example if we were to render a blog post with _partial('blog/post', post)_ it would generate the _post_ local, but the view calling this function had the local _user_, it would be available to the _blog/post_ view as well.
+Local variables passed (or generated) take precedence, however locals passed to the parent view are available in the child view as well. So for example if we were to render a blog post with _partial('blog/post', allPosts)_ it would generate the _post_ local, but the view calling this function had the local _user_, it would be available to the _blog/post_ view as well.
+
+#### Naming
+
+It is a common convention in many web frameworks to differentiate views from partials by prefixing the latter with an underscore. Using the comments example above, one could for example have a `post` view and a `_comment` partial.
+
+If you are to use this convention, know that the default container variable for the current parameter in the collection has its leading underscore removed. With the `_comment` partial, unless specified otherwise with the [`as`](#res.partial()) option, the key/value pairs of the current partial parameter will be namespaced in a `comment` object, **not** `_comment`.
-For documentation on altering the object name view [res.partial()](http://expressjs.com/guide.html#res-partial-view-options-).
+#### Performance note
-__NOTE:__ be careful about when you use partial collections, as rendering an array with a length of 100 means we have to render 100 views. For simple collections you may inline the iteration instead of using partial collection support to decrease overhead.
+Be careful about when you use partial collections, as each element in the collection array has to be rendered on its own. For simple collections, you should inline the iteration instead of using partial collection support to decrease overhead.
### View Lookup
Something went wrong with that request. Please try again.