PageRenderTime 50ms CodeModel.GetById 26ms RepoModel.GetById 1ms app.codeStats 0ms

/README.md

https://gitlab.com/learn-co-curriculum/partials-lecture
Markdown | 258 lines | 184 code | 74 blank | 0 comment | 0 complexity | 071c1cc29e72d937299c434ec24bf56f MD5 | raw file
    

  1. ## Intro
    2. 

  2. 

  3. * What is a partial? Code re-use for HTML. Think-keeping our code DRY. 
    4. 

  4. * General example: Our app displays a user profile page, and an edit user profile page, a new user profile page and an index page of all of the users. Each of these four HTML templates repeat the same, or very similar, code for displaying a user's details--their name, age, and location. But, our project manager has just let us know that our client has decided a user's details should also include their favorite cat. While we commend our client for their excellent taste, we are annoyed that we have to make the *same change* to all four files that display a user's details. Using partials avoids this headache. With a partial, we can extract a portion of our html code, store it in some other file, and simply call, or *render*, the code in that file in any other template. Think of it as making your html code into a method that you can call again and again.
    5. 

    6. 

  6. ## The Domain Model
    7. 

  7. 

  8. Today, we'll be working with a music management app that has a song, artist and genre model. An artist has many songs and a song belongs to an artist. A song has many genres and a genre has many songs. We'll be taking a closer look at a few views in particular: the application.html.erb layout, the song show page, the genre show page and the new and edit pages for the song model.
    9. 

  9. 

  10. ## Rendering a Simple Partial
    11. 

  11. 

  12. Let's take a look at the simple navigation menu that we've provided our music management app. Right now our menu (which has no styling, don't judge), is placed directly in our `views/layouts/application.html` view:
    13. 

    14. 

  14. ```html
    15. 

  15. <!DOCTYPE html>
    16. 

  16. <html>
    17. 

  17. <head>
    18. 

  18.   <title>PlaylisterApp</title>
    19. 

  19.   <%= stylesheet_link_tag    "application", media: "all", "data-turbolinks-track" => true %>
    20. 

  20.   <%= javascript_include_tag "application", "data-turbolinks-track" => true %>
    21. 

  21.   <%= csrf_meta_tags %>
    22. 

  22. </head>
    23. 

  23. <body>
    24. 

  24. <p>Menu</p>
    25. 

  25. <ul>
    26. 

  26.   <li>
    27. 

  27.     <%= link_to 'Songs', songs_path %>
    28. 

  28.   </li>
    29. 

  29.   <li>
    30. 

  30.     <%= link_to 'Genres', genres_path %>
    31. 

  31.   </li>
    32. 

  32.   <li>
    33. 

  33.    <%= link_to 'Artists', artists_path %>
    34. 

  34.   </li>
    35. 

  35. </ul>
    36. 

    37. 

  37. <%= yield %>
    38. 

    39. 

  39. </body>
    40. 

  40. </html>
    41. 

  41. ``` 
    42. 

  42. 

  43. Right now, our view is a little disorganized. Its crowded and difficult to read. Imagine an even more complex navigation menu, along with some other content that you might find on this view, like a footer and a sidebar that contains some widgets. Our view would get increasingly difficult to read, understand and edit. Wouldn't it be great if we could organize discrete units of html code, like our menu, by extracting them into their very own files? That's exactly what a partial will do for us. Let's do it. 
    44. 

    45. 

  45. * Step 1: Make the partial file: `app/views/layouts/_menu.html.erb`. *Always name partial files with an underscore*. 
    46. 

  46. * Step 2: Remove the menu code from the application view and place it in the partial:
    47. 

  47. 

  48. ```html
    49. 

  49. # app/views/layouts/_menu.html.erb
    50. 

    51. 

  51. <p>Menu</p>
    52. 

  52. <ul>
    53. 

  53.   <li>
    54. 

  54.     <%= link_to 'Songs', songs_path %>
    55. 

  55.   </li>
    56. 

  56.   <li>
    57. 

  57.     <%= link_to 'Genres', genres_path %>
    58. 

  58.   </li>
    59. 

  59.   <li>
    60. 

  60.    <%= link_to 'Artists', artists_path %>
    61. 

  61.   </li>
    62. 

  62. </ul>
    63. 

  63. ```
    64. 

  64. 

  65. * Step 3: Call, or *render*, the partial on the application view. 
    66. 

  66. 

  67. ```html
    68. 

  68. # app/views/layouts/application.html.erb
    69. 

    70. 

  70. <!DOCTYPE html>
    71. 

  71. <html>
    72. 

  72. <head>
    73. 

  73.   <title>PlaylisterApp</title>
    74. 

  74.   <%= stylesheet_link_tag    "application", media: "all", "data-turbolinks-track" => true %>
    75. 

  75.   <%= javascript_include_tag "application", "data-turbolinks-track" => true %>
    76. 

  76.   <%= csrf_meta_tags %>
    77. 

  77. </head>
    78. 

  78. <body>
    79. 

    80. 

  80. <%= render 'menu' %>
    81. 

    82. 

  82. <%= yield %>
    83. 

    84. 

  84. </body>
    85. 

  85. </html>
    86. 

  86. ```
    87. 

  87. 

  88. * Notice that we call the render method with an argument of the name of the partial we want to render, *minus the underscore*. 
    89. 

  89. 

  90. Now that we have a basic understanding of how to render a partial to keep our view code organized and DRY, let's take a look at using more complicated partials. 
    91. 

    92. 

  92. ## Rending Partials with Locals
    93. 

  93. 

  94. Notice that the genre show page displays the genre's name, the songs associated with that genre, and some of the details of each of those songs:
    95. 

    96. 

  96. ```html
    97. 

  97. <p id="notice"><%= notice %></p>
    98. 

    99. 

  99. <p>
    100. 

  100.   <strong>Genre Name:</strong>
    101. 

  101.   <%= @genre.name %>
    102. 

  102. </p>
    103. 

    104. 

  104. <br>
    105. 

  105. <h3>Songs:</h3>
    106. 

  106. <ul>
    107. 

  107.   <% @genre.songs.each do |song| %>
    108. 

  108.     <p>
    109. 

  109.     <strong>Name:</strong>
    110. 

  110.       <%= song.name %>
    111. 

  111.     </p>
    112. 

    113. 

  113.     <p>
    114. 

  114.       <strong>Artist Name:</strong>
    115. 

  115.       <%= link_to song.artist.name, song.artist if song.artist %>
    116. 

  116.     </p>
    117. 

  117.   <%end %>
    118. 

  118. </ul>
    119. 

    120. 

  120. <%= link_to 'Edit', edit_genre_path(@genre) %> |
    121. 

  121. <%= link_to 'Back', genres_path %>
    122. 

    123. 

  123. ```
    124. 

  124. 

  125. Notice that the song show page also displays the song name and the name of that song's artist:
    126. 

    127. 

  127. ```html
    128. 

  128. <p id="notice"><%= notice %></p>
    129. 

    130. 

  130. <p>
    131. 

  131.   <strong>Name:</strong>
    132. 

  132.   <%= @song.name %>
    133. 

  133. </p>
    134. 

    135. 

  135. <p>
    136. 

  136.   <strong>Artist Name:</strong>
    137. 

  137.   <%= link_to @song.artist.name, @song.artist if @song.artist %>
    138. 

  138. </p>
    139. 

    140. 

  140. <p>
    141. 

  141.   <strong>Genres:</strong>
    142. 

  142.   <%= @song.genres.collect{|g| g.name}.to_sentence %>
    143. 

  143. </p>
    144. 

    145. 

  145. <%= link_to 'Edit', edit_song_path(@song) %> |
    146. 

  146. <%= link_to 'Back', songs_path %>
    147. 

  147. ```
    148. 

  148. 

  149. This code isn't very dry. We repeat the same code in two locations, and any changes we make to what attributes a song has and how we display them will need to be made in both locations. 
    150. 

    151. 

  151. Let's extract this code for displaying a song's name and artist into a partial. 
    152. 

  152. 

  153. * Step 1: Create a partial in `views/songs/_song_details.html.erb`.
    154. 

  154. * Step 2: Place the HTML that displays a song name and it's artist's name in that file:
    155. 

  155. 

  156. ```html
    157. 

  157. <p>
    158. 

  158.   <strong>Name:</strong>
    159. 

  159.   <%= @song.name %>
    160. 

  160. </p>
    161. 

    162. 

  162. <p>
    163. 

  163.   <strong>Artist Name:</strong>
    164. 

  164.   <%= link_to @song.artist.name, song.artist if @song.artist %>
    165. 

  165. </p>
    166. 

  166. ```
    167. 

  167. 

  168. Now, let's render our partial in place of those lines of code on our song show page:
    169. 

    170. 

  170. ```html
    171. 

  171. <%= render 'song_details'%>
    172. 

  172. ```
    173. 

  173. 

  174. It works! Notice that our partial relies on an instance variable, `@song`, which it implicitly has access to since we set it in the controller action that brought us to this view page. 
    175. 

  175. 

  176. **Using Convention**
    177. 

  177. 

  178. let's try rendering our partial like this
    179. 

    180. 

  180. ```html
    181. 

  181. <%#= render @song %>
    182. 

  182. ```
    183. 

  183. 

  184. We get error message missing template songs/song. Rails convention is trying to find a partial that matches the name of the object we are passing in to render. Would this work if we create a song/_song.html.erb that looked just like `_song_details`? Let's try it!
    185. 

    186. 

  186. Yes it works, explain a bit about that rails convention but then go back to using song_detail. 
    187. 

  187. 

  188. 

  189. 

  190. Now Let's try rendering our `_song_detail` partial from our genre show page:
    191. 

    192. 

  192. ```html
    193. 

  193. <ul>
    194. 

  194.   <% @genre.songs.each do |song| %>
    195. 

  195.     <%= render "songs/song_details" %>
    196. 

  196.   <%end %>
    197. 

  197. </ul>
    198. 

  198. ```
    199. 

  199. 

  200. Notice that this time, we have to specify which subdirectory of views our partial is found in `/songs`. If a partial is in the same directory as the file on which it is rendered, we can leave this part off. 
    201. 

  201. 

  202. Let's visit a genre's show page and see our partial in action. Oh no! We have an error, `undefined method 'name' for nil class`. This error is getting thrown by this line of our partial: `<%= @song.name %>`. Which controller action brought us to the genre show page? `genres#show`, not only did that controller action *not* set a variable, `@song`, for us, but we are actually calling this partial inside our `#each` iteration as we iterate over the collection of the given genre's song. All of this is to say that we do *not* in fact have access to any variable called `@song` on our partial when it is rendered from the genre show page. For this reason, we never want to use instance variables in a partial.
    203. 

    204. 

  204. So, how can we solve this? 
    205. 

  205. 

  206. * First, we'll replace the instance variable `@song` with a local variable, `song`, on that partial. 
    207. 

  207. * Then, we'll pass in the value of the local variable when we call `render` on both the song and genre show page, using the following syntax:
    208. 

    209. 

  209. ```html
    210. 

  210. # song view
    211. 

    212. 

  212. <%= render partial: 'song_details', locals: {song: @song} %>
    213. 

  213. ```
    214. 

  214. 

  215. 

  216. 

  217. ```html
    218. 

  218. <%= render partial: 'song_details', locals: {song: song} %>
    219. 

  219. ```
    220. 

  220. 

  221. In this way, we can dynamically pass in the appropriate song object whenever and wherever we render the partial. Think of it as calling the `render` method with keyword arguments. Each time, we are setting the local variable, `song`, inside of the partial, equal to whatever object gets set to `locals: {song: some_song_object}`. 
    222. 

  222. 

  223. `render` has a polymorphic interface. the way we use it changes. if we pass it a hash, it expects the full thing above. if first arg is a string, it reacts appropriate and expects second arg to be hash of locals:
    224. 

  224. 

  225. ```erb
    226. 

  226. <%=render 'songs/song_details', song: song%>
    227. 

  227. ```
    228. 

  228. ## Rendering A Collection via a Partial
    229. 

  229. 

  230. Let's take a moment and refactor our rendering of the `song_details` partial on the genre show page. Here, we are using the partial inside of our iteration over a genre's collection of songs. This is such a common practice, that Rails provides us with an even easier way to do it:
    231. 

  231. 

  232. ```html
    233. 

  233. <%= render partial: "songs/song_details", collection: @genre.songs, as: :song %>
    234. 

  234. ```
    235. 

  235. 

  236. 

  237. In fact, there is an even more concise way to render a partial with a collection of objects:
    238. 

  238. 

  239. ```html
    240. 

  240. <%= render @genre.songs %>
    241. 

  241. ```
    242. 

  242. 

  243. However, if we try this approach, we'll see the following error:  (missing template songs/song). Rails is trying to locate a partial using a singular version of the collection we are passing the render method (songs/song). Since we named our partial song_details, this level of abstraction won't work for us. We'll have to use the more explicit version. Let's take a closer look at that now:
    244. 

  244. 

  245. ```html
    246. 

  246. <%= render partial: "songs/song_details", collection: @genre.songs, as: :song %>
    247. 

  247. ```
    248. 

  248. 

  249. Here, we assign `collection` equal to the collection of songs we want to render and we tell our partial to set the `song` local variable equal to each member of the `@genre.songs` collection. The render method will the work for us of iterating over the given collection and setting each member of that collection equal to the local variable, `song`. 
    250. 

  250. 

  251. ## Rendering Partials with Local Variables, Form Example
    252. 

  252. 

  253. Another common usage of partials is in rendering forms. Let's take a look at the page to edit a song and the view for creating a new song. Notice that the forms are exactly the same! Further, notice that the number of form fields can be a lot to take in. The more form fields we have, the harder it gets to read, understand and edit the form, from the developers point of view. Let's refactor these forms into using partials to render the form fields:
    254. 

  254. 

  255. * Step 1: Make a partial, `songs/_form_fields.html.erb`. 
    256. 

  256. * Step 2: Paste our form fields in the partial
    257. 

  257. * Step 3: Pass the local variable, `f`, into the partial when we render it on the pages.
    258. 

  258. <p data-visibility='hidden'>View <a href='https://learn.co/lessons/partials-lecture' title='Intro'>Intro</a> on Learn.co and start learning to code for free.</p>
    259. 

  259.