Newscoop 3 Cookbook

Working with images

It's an understatement to say that images are crucial to news organizations. Because of their central role, Newscoop has a powerful and user-friendly media archive for storing, retrieving and reusing images in the administration interface. Newscoop's template language can access images in a number of different ways, and the output can be sent to web pages, to jQuery slideshows or other channels (see the chapter Image galleries with jQuery for more on that).

In this chapter, we'll look at how Newscoop templates work with images, image attributes and metadata. According to the Newscoop template reference, "The image object is usually initialized inside a list of article images or a list of images. It is not initialized at the beginning of the template and cannot be initialized by other Newscoop functions." In other words, images must be used through lists or through articles.

You can make use of images through the article object, like when the current article has one or more images attached. One more place where you can use an image object is with author objects. We'll go into these options in detail below. What you can't do at this point is use an image object as a single isolated element, because it has to be set first by any of the means mentioned above.

Displaying an article image

Let's start with a simple example. You have an article with only one image, and you want to display the image when the article is requested.

You can point to an image in two ways, either:

<img src="{{ $gimme->article->image1->imageurl }}" alt="{{ $gimme->article->image->caption }}" />

or:

<img src="{{ uri options="image 1" }}" alt="{{ $gimme->article->image->caption }}" /> 

The following code snippet does more, it:

  • Gets the URL for an image attached to an article
  • Puts the image caption (the description) into the ALT tag
  • Puts the photo description into the title tag
  • Displays the photographer's name
  • Displays the image caption (the description)
<img src="{{ $gimme->article->image->imageurl }}"
     alt="{{ $gimme->article->image->caption }}"
   title="{{ $gimme->article->image->description }}"  /><br />
       by {{ $gimme->article->image->photographer }}<br />
          {{ $gimme->article->image->description }}

An example of what similar code looks like in the browser is below (taken from the "The Journal" template pack):

You can even validate whether the article has an image or not. The value passed in parentheses correspond to the image number you assign to the image when attaching it to the article.

{{ if $gimme->article->has_image(1) }}
    <img src="{{ $gimme->article->image->imageurl }}" />
{{ /if }}

It's also possible to access the image directly by the index number. If an image with that given index does not exist, then an empty image object is returned, and nothing will be displayed. It is good practice to first validate whether the requested image exists or not, but you already know how to do that!

<img src="{{ $gimme->article->image5->imageurl }}" />

There are more image properties you can display; we've already used some like imageurl, photographer and description, but there'll be more in the following examples. You can read the entire list in the chapter Template Objects -> Image of the Newscoop Template Reference.

Listing all images attached to an article

This is basically the same as we did before, but within a list of article images. Let's see some code:

{{ list_article_images }}
    <li>
        <img src="{{ $gimme->article->image->imageurl }}" /><br />
        Caption: {{ $gimme->article->image->caption }}<br />
        By: {{ $gimme->article->image->photographer }}
    </li>
{{ /list_article_images }}

There's no need to use image indexes, because the list provides iteration over all images attached to the article.

Listing images from the media archive

Now the fun begins :-)

You already know how to work with image objects and how to list images attached to articles; this is very useful and will allow you to use image content all over your site.

But in specific cases you'll probably want to display images not necessarily related to articles. Remember that Newscoop provides a Media Archive (read more about it in the Newscoop 3 for Journalists and Editors manual), and every image you attached to an article is stored there.

The Newscoop template language provides a function to build lists of images according to different criteria. Let's say you want to build a list of images from a specific photographer. This code snippet can:

  • Get a list of images where the photographer name is John Doe
  • Order the images by the last update
  • Get the images themselves based on their URLs
  • Get the image captions (descriptions)
{{ list_images photographer=" John\ Doe" order="byLastUpdate" }}
    <img src="{{ $gimme->image->imageurl }}" /><br />
    <p>{{ $gimme->image->description }}</p>
{{ /list_images }}

Now here's list of images where the string "Prague" is present:

{{ list_images caption_like="Prague" order="byPhotographer" }}
    <img src="{{ $gimme->image->imageurl }}" /><br />
    <p>{{ $gimme->image->caption }}</p>
{{ /list_images }}

There are many other criteria you can use. A detailed list can be found in the Newscoop Template Reference in the List Images chapter.

Thumbnails

Newscoop automatically generates a 64-pixel-wide thumbnail for every image when the image file is uploaded into the Media Archive. Displaying a thumbnail is as easy as this:

<img src="{{ $gimme->image->thumbnailurl }} />

Author picture

The author object has the property picture, which is an image object, so that you can use it exactly as an article image. There's more on this in the chapter Managing multiple authors and articles in this Cookbook.

Scaling in percent and absolute size

Images in Newscoop are only stored in two different sizes: the original size and the automatically generated thumbnail. Usually it is necessary to display those images in a different size than those two available, so Newscoop provides a simple way to do this on the fly:

<img src="{{ $gimme->image->imageurl }}&ImageRatio=70" /> 

Here we just specified a ratio equal to 70, which means the image will be resized to 70 percent of its original size. You also have the option to provide an specific width or height value.

<img src="{{ $gimme->image->imageurl }}&ImageWidth=350&ImageHeight=310" />

Any image provided by $gimme can be scaled as shown above, including the thumbnail and author pictures. The logic of how Newscoop processes the values when both width and height are provided (and even the ratio) at the same time is explained, with more examples, in the wiki page: http://wiki.sourcefabric.org/x/c4EH