Sign In with your Yahoo! ID or Join Now

Module Reference: User Input Modules

User Input modules add flexibility to your Pipes. They let you feed input information into your completed Pipe when you run it. The Location Input module, for example, lets you supply different cities to a Pipe that looks up available apartments. With the Date Input module, you can search for news that's no more than a few days old.

All Input Modules let you specify five values:

  • Name - this is the parameter name that Pipes associates with the input value.
  • Prompt - this is used only when you run a Pipe using the Run Pipe option. When you use Run Pipe, you'll see a text entry field for every Input module in your Pipe. The Prompt is the text that identifies the entry.
  • Position - this is also only applicable when using Run Pipe. It specifies the order that each Input field is displayed.
  • Default - when running a Pipe, if no value is specified, this default value is used.
  • Debug - similar to the Default value, this value is used when processing a Pipe within the Pipes Editor. The Debug value is not used when you run your Pipe outside the Pipes Editor.

If you're writing a program that runs your Pipe using its URL, you'll want to replace values in the Pipe URL. Here's an example Pipe URL, somewhat abbreviated for clarity:

http://pipes.yahoo.com/pipes/pipe.run?_id=Kt...y0Q&_render=rss&_run=1&locationinput1=richmond%2C+va

The highlighted portion of the URL shows where the a Location Input module is used. locationinput1 corresponds to the Name given to the module. The value (right of the equal sign) is the Default location value. It's currently set to "richmond%2C+va". That's actually "richmond, va", but the comma and space have been encoded as %2C and +. You simply change this value in the URL to specify a different location.

Module Output: datetime

Date Input Module

With this module, a datetime value can be passed by the user into the Pipe. You can type in the date value, or use the pop-up calendar widget to select a default date.

Valid Date Values

So what formats does Date Input understand? Obvious date formats are recognized:

  • Jan. 12, 2001
  • 10/21/1958
  • 15 JUN 06

But it'll understand some unusual formats as well:

  • now
  • yesterday
  • +3 days
  • -10 days
  • +5 hours
  • 1181230100

From these examples you can see how flexible Date Input can be. If today is June 2nd, using "yesterday" gives you June 1st. "+3 days" will give you June 5th. "+5 hours" shows that when we say date we really mean date and time.

It's useful at this point to see what the Yahoo! Pipes datetime data type gives you. Drop a Date Input module onto the Editor canvas, then click on it to make sure it's selected (it'll turn yellow). Enter a Debug value of now, then hit "refresh" in the Debugger. You'll see data like this:

		hour 22
		timezone UTC
		second 33
		month 6
		minute 33
		utime 1181255613
		day 7
		day_of_week 4
		year 2007
		

The datetime type breaks time down into these nine fields. You can specify time down to the seconds. Most of these fields require no explanation, but you may be wondering about utime. This value goes back to the prehistory of the Unix operating system (and possibly earlier than that). It's the number of seconds that have passed since the beginning of the epoch, which is defined as January 1st, 1970. That may sound a bit whimsical, but with a single integer time value you can easily perform date arithmetic.

Example: Run this Pipe | View Source

This example gets the freshest news from the Yahoo! World News feed. The Date Input module lets the user set the freshness. By default only news published in the last 15 minutes is shown.

Module Output: location

Location Input Module

With this module, you can specify a geographic location as input to your Pipe. Valid locations include addresses, latitude/longitude pairs, U.S. city and state, world city and country, and postal code.

Here are some examples of valid locations:

  • Albany, New York
  • Main Steet, Richmond, VA
  • 23116
  • 37.542770 -77.443894
  • London, UK

The location datatype provides some or all of these fields:

		country United States
		street 123 Main Street
		lat 37.643683
		postal 23116
		state VA
		city Mechanicsville
		lon -77.341372
		quality 87
		

How many of these fields are available to you depends on the accuracy of the location you provide. The quality field is an indication of the accuracy of the location provided. A specific street address will often have a quality in the 80s or higher. Providing just a city name, like "London", returns a quality of about 40, and providing just a country name, like "Portugal", yields a quality of only 10.

To see what data Location Input is providing, place the module on the Editor Canvas, then enter a value in the module's Debug field. Click on the module's title bar to make sure it's the selected module (the title bar turns orange), then click the Refresh link in the Debugger.

Example: Run this Pipe | View Source

This example uses the Yahoo! Local module to find restaurants within 1 mile of a location. The user provides the location using the Location Input module. This example also shows a cool feature of the Run Pipes option. The output feed contains geographical information, so you can display the restaurant locations on an interactive map.

Module Output: number

Number Input Module

This module lets the user specify a number (either integer or floating point) as input to a Pipe. This module connects to other modules that use numeric input, such as Truncate, Filter, Yahoo! Local, Google Base, and Simple Math.

Example: Run this Pipe | View Source

The Number Input module is great for limiting the number of items returned in your Pipes feed. This example wires the Number Input module into a Truncate module to restrict the Pipes output. The feed shows the top 10 digged stories from digg.com.

Module Output: text

Text Input Module

Use this module any time you need to wire text input into your Pipe. Many of the other modules can accept text, including all the String modules, almost all of the Source modules (except Fetch Feed), Filter, For Each: Annotate, Regex, and Rename.

Example: Run this Pipe | View Source

This example wires a Text Input module into the Yahoo! Search module to create a general-purpose search service for Wikipedia.

Module Output: url

URL Input Module

This module lets the user specify a URL used by the Pipe. URL Input can be wired into any of the Sources modules as well as the Filter, For Each: Annotate, Regex, Rename, and URL Builder modules.

Example: Run this Pipe | View Source

In this example, we wire the URL Input module into a Yahoo! Search module to let the user restrict the search to a particular site. A Text Input module is also wire in, so the user can also select the search terms.

Module Output: text

Private Text Input Module

Use this module any time you need to add sensitive input data into your Pipe, such as aplication IDs, usernames or passwords.

By marking the debug or default values as private (check the checkbox), you prevent anyone other than the owner of the Pipe from seeing that value. In addition, private debug or default values will not be copied if the Pipe is cloned (except by the owner).

Regardless of the "private" setting, the "default" value in the user input will always be used when running the Pipe outside of the editor (such as the Pipe's run page, or through the RSS, JSON, KML requests).

Example: Run this Pipe | View Source

This example wires a Private Input module into the Flickr module to search for "stars". However, only the Pipe author can see the "search" term because its marked private - but the Run page shows the correct output nevertheless

Copyright © 2014 Yahoo! Inc. All rights reserved.