Creating a Simple Dynamic Listing (Widget) - Documentation topics on: creating a simple dynamic listing,.

Creating a Simple Dynamic Listing (Widget)

Using the Staff Content Type created in the first tutorial, lets create a simple dynamic pull of Staff content using Velocity inside a dotCMS Widget.  Widgets are a type of content that uses front-end programming code (HTML/CSS, Velocity, Javascript), to pull content dynamically from the content repository.

To create your first Staff Listing Widget, make sure you have completed the Building your First Content Type tutorial, and then make sure you have added several Staff contentlets, using the dotCMS Content Tab.  

Simple Widget Tutorial (No Screenshots)

*To follow this tutorial with screenshots, see the Simple Widget Tutorial (with Screenshots) below this list.

  1. After adding the Staff content, click the "Last Name" column in the body area of the Staff Content detail on the Content tab and make sure that the Last Names are listing in A-Z order by clicking on "Last Name" at the top of the column.  Next click the down arrow next to the "Search" button and select "Show Query."
  2. Copy the suggested "Velocity Content Pull" which includes an example of a foreach loop in Velocity and the dotCMS dotcontent viewtool.
  3. Paste the foreach loop into your favorite text editor and save the file as SimpleStaffListing.vtl - make sure to include the .vtl extension (On PC make sure to set filetype to "All Files")
  4. Add the following velocity variables from the Staff Content Type and the macro to allow content editors the ability to edit each piece of content in your listing (permissions permitting).
  5. #foreach($Staff in $dotcontent.pull("+contentType:Staff +(conhost:48190c8c-42c4-46af-8d1a-0cd5db894797 conhost:SYSTEM_HOST)",10,"Staff.lastName"))
    
      #editContentlet($Staff.inode)
      <h3>$!{Staff.lastName}, $!{Staff.firstName}</h3>
      <strong>$!{Staff.title}</strong><br
      <em>$!{Staff.email}</em><br/>
      $!{Staff.phone}<br/>
      <hr/>
      
    #end
    
  6. Now create a new HTML Page (use any demo starter Quest template), and click the "+Add Content" button, then select "Add Widget"
  7. Choose the Simple Widget (to drop all the code in one field), and then click the "+Create New Simple Widget" Button.
  8. Paste your code into the widget code field from your text editor. In the next tutorial we will parse an external file, but lets keep it simple for now.  Now click "Save / Publish" button to see your widget code execute on the page.
  9. The Simple Widget code will pull whatever Staff Content you have created in the system.  The widget will continue to pull Staff content from the content repository as it is added to the system (via the Content tab).  The macro exposes "Edit Content" buttons next to each of the Staff contentlets to allow content editors to make corrections to the content being pulled in the listing.

Congratulations! you have now created your first Simple Widget in dotCMS. This same tutorial is repeated below with screenshots of each step to help you if you get stuck.


*Simple Widget Tutorial (with Screenshots)

1) After adding the Staff Content, click the "Last Name" column in the body area of the Staff Content detail on the content tab and make sure that the Last Names are listing in A-Z order by clicking on "Last Name" at the top of the column.  Next click the down arrow next to the "Search" button and select "Show Query."


2) Copy the suggested "Velocity Content Pull" which includes an example of a foreach loop in Velocity and dotCMS dotcontent viewtool.


3) Paste the foreach loop into your favorite text editor and save the file as SimpleStaffListing.vtl - make sure to include the .vtl extension (On PC make sure to set filetype to "All Files")


4) Add the following velocity variables from the Staff Content Type and the macro to allow content editors the ability to edit each piece of content in your listing (permissions permitting).

#foreach($Staff in $dotcontent.pull("+contentType:Staff +(conhost:48190c8c-42c4-46af-8d1a-0cd5db894797 conhost:SYSTEM_HOST)",10,"Staff.lastName"))

  #editContentlet($Staff.inode)
  <h3>$!{Staff.lastName}, $!{Staff.firstName}</h3>
  <strong>$!{Staff.title}</strong><br
  <em>$!{Staff.email}</em><br/>
  $!{Staff.phone}<br/>
  <hr/>
  
#end

See the image below for a brief explanation of the changes made to the Velocity Content Pull suggested by the "Show Query" button on the Content tab. For more detailed information, see the Velocity and Pull Content documentation.


5) Now create a new HTML Page (use any demo starter Quest template), and click the "+Add Content" button, then select "Add Widget"


6) Choose the Simple Widget (to drop all the code in one field), and then click the "+Create New Simple Widget" Button.


7) Paste your code into the widget code field from your text editor. In the next tutorial we will parse an external file, but lets keep it simple for now.  Now click "Save / Publish" button to see your widget code execute on the page.


8) The Simple Widget code will pull whatever Staff Content you have created in the system.  The widget will continue to pull Staff content from the content repository as it is added to the system (via the Content tab).  The macro exposes "Edit Content" buttons next to each of the Staff contentlets to allow content editors to make corrections to the content being pulled in the listing.


Congratulations! You created your first Simple Widget.  Review the next tutorial to learn how to parse .vtl files, create dynamic code repositories, and edit .vtl files via webdav.