The Creating a Subscribed Link Using Text Files and Web Feeds page guided you through the process of creating a subscribed link from text files and web feeds. This page shows you how you can create an advanced subscribed link using Subscribed Links XML tags. This and the subsequent pages on advanced features assume that you have basic knowledge of XML concepts.
A dynamic subscribed link created from XML is more complicated than a subscribed link created from TSV files or web feeds, but the XML format gives you access to advanced features and control over the look and feel of your custom results. You can incorporate regular expressions, calculators, and Google gadgets.
The best way to understand XML subscribed links is by viewing an example. The following code creates a subscribed link that shows a "Hello, World!" result that is triggered by the search query "subscribed links".
<Results>
<AuthorInfo description="My first XML-based subscribed link" author="Your Name"/>
<!--The result specification is the main guts of your custom results-->
<ResultSpec id="helloworld_xml">
<!--The result specification includes one query.-->
<Query>subscribed links</Query>
<!--The query triggers this response-->
<Response>
<Output name="title">Google Subscribed Links API</Output>
<Output name="more_url">www.google.com/coop/subscribedlinks</Output>
<Output name="text1">Hello, world!</Output>
<Output name="text2">Google Subscribed Links allow you to put your own</Output>
<Output name="text3">content on the Google search results page.</Output>
</Response>
</ResultSpec>
<!--You can create more result specifications.-->
</Results>
A result specification, which is enclosed in the ResultSpec element, is the control center of the Subscribed Links XML file. And each ResultSpec element is composed of a query and its corresponding response. You can have many result specifications in your XML file, but each result specification can have only one pair of query and result. The query, which is enclosed within the Query tags, defines what users need to type in the Google search box to trigger the custom result. The response, which is enclosed within the Response tags, defines what information should be displayed when a custom result is triggered.
The custom result of the sample XML code looks something like this:
Creating Queries and Results
Let's try our hands at simple XML files. This section will go through every element in the XML file step-by-step. You can use a plain text editor to create your file. It does not matter what you name the file, so long as the name is unique among your subscribed link files and has the file extension: .xml (for example, helloworld.xml). Make sure that the size of your files does not exceed the limit described in the Publishing Your Subscribed Links page.
As with any XML file, your subscribed link must follow XML syntax ( <element attribute="value">content</element>) and be well-formed. XML has the following rules:
All your elements must have an opening tag (<tag>) and a closing tag (</tag>).
All your tags must be properly nested. You cannot have XML code that looks like: <sandwich>Wheat <filling> peanut butter</sandwich></filling>. Instead, it should be like: <sandwich>Wheat <filling> peanut butter</filling></sandwich>.
All attribute values must be enclosed in double quotation marks (<element attribute="value">).
XML is case-sensitive, so follow the capitalization and spelling of the tags in the instructions.
XML requires you to precede your top-level tags with an XML declaration, but the Subscribed Links API doesn't require it. So don't bother prefacing your XML with a declaration.
Create the top-level <Results></Results> tags that enclose the entire XML file.
Create all subsequent elements inside the opening <Results> tag and the closing </Results> tag.
Optional. Define the AuthorInfo tag with a short description of your subscribed link file and your name.
While this element is optional, it is a good idea to include it for reference.
<Results>
<AuthorInfo description="My first XML-based subscribed link" author="Your Name"/>
</Results>
Create the ResultSpec tags, which define the query-response set for your subscribed link.
Your subscribed link file could have multiple ResultSpec elements, and each ResultSpec must have an id attribute with a value that is unique across all your subscribed link files. For the ResultSpec ID, you can use meaningful text, numbers, or a combination of both.
<ResultSpec id="helloworld_xml">
</ResultSpec>
Inside the ResultSpec tags, define the Query element.
Query specifies the general pattern of queries that would trigger your result. A query might include exact text, a search pattern with regular expressions, or variables. It is not case-sensitive, so your subscribers can use any form of capitalization in their search. You can have only one Query element within each ResultSpec element. If you want to create a large set of queries for a ResultSpec element, see the Creating Patterns of Queries page.
<Query>subscribed links</Query>
Inside the ResultSpec tags and right after the Query element, create the Response element.
Response specifies the custom results to display when your subscriber types the pre-defined query in Google search. A basic response includes a title, a URL, and up to three lines of text.
Finally, we define the Output tags inside the Response tags. Each Output element has a name attribute that specifies the content of your results. Define the following attribute values:
title - The title of the custom result. The URL for the title is defined in the next attribute. The title can have up to 50 characters.
more_url - The hyperlink of the title of the result. It does not matter if you include or exclude the protocol specification (http:// or https://) of the web address. The URL can have up to 200 characters. The URL also appears as the last line in the custom result.
text1 - Optional. The first line of the text in the body of the custom result. Each line can have up to 80 characters of text; any character beyond the 80-character limit will be truncated. HTML tags are interpreted as plain text, not formatting instructions. If you want to learn more about controlling the appearance of your custom results, see the Designing Your Look and Feel page. If you want to add hyperlinks to your result body, see the Adding Hyperlinks to Your Results section of this page.
text2 - Optional. The second line of text in the result body.
text3 - Optional. The third line of text in the the result body.
The standard result format consists of a title link and up to three lines of body text; however, since all but the title and its URL (more_url) are optional, you can also create results with no body of text.
The standard Response set would look something like this:
<Response>
<Output name="title">Google Subscribed Links API</Output>
<Output name="more_url">www.google.com/coop/subscribedlinks</Output>
<Output name="text1">Hello, world!</Output>
<Output name="text2">Google Subscribed Links allow you to put your own</Output>
<Output name="text3">content on the Google search results page.</Output>
</Response>
And that's it, you are done. Type "subscribed links" in the Google search box and you should see a custom result similar to the screen shot in the Overview section of this page.
Adding Hyperlinks to Your Results
You can add hyperlinks to the body of your result. In fact, as long as you do not exceed the 80-character limit for each line of displayed text, each line of output text can have up to five hyperlinks; so your custom result can have a total of 15 hyperlinks. You define the hyperlinks inside the Response tags.
Creating Linked Text
To created linked text in your result body, define the following attribute values for Output name:
link[n][a], where [n] is the number that indicates which text line in the result body the link should appear on and [a] corresponds to the order of the linked text within that line. You do not need to specify the [a] for the first link, only the subsequent ones. So the attribute values for the links in your first line would be: link1, link1b, link1c, link1d, link1e. The URL for the linked text are defined in the next attribute value.
Let's look at the following example:
<Response>
<Output name="title">Google Subscribed Links API</Output>
<Output name="more_url">www.google.com/coop/subscribedlinks</Output>
<Output name="text1">Hello, world!</Output>
<Output name="link1">Link to the Reference Directory, </Output>
<Output name="link1b">link to the News Directory, </Output>
<Output name="link1c">and link to the Movie Directory.</Output>
</Response>
The code has three links. They are just the text for the hyperlink, and the URL will be defined in the next attribute value. The linked text are defined in:
<Output name="link1"> - Defines the first link in the first line of the result body. The number in the attribute value corresponds to the line where the linked text appears. In this case, the linked text appears in the first line of the result body. Since the order of the linked text was not defined with a letter, it will be the first linked text to appear in the line.
<Output name="link1b"> - Defines the second link in the first line of the result body. We defined the order of the link with the letter b.
<Output name="link1c"> - Defines the third link in the first line of the result body. We defined the order of the link with the letter c.
url[n][a]defines the URL for the linked text you defined previously. The [n] and [a] portion of the url attribute values match that of the link. So the url attribute values for your first line would match the link attribute values and look like: url1, url1b, url1c, url1d, url1e.
Let's look at the following example:
<Response>
<Output name="title">Google Subscribed Links API</Output>
<Output name="more_url">www.google.com/coop/subscribedlinks</Output>
<Output name="link1">Link to the Reference Directory, </Output>
<Output name="url1">http://www.google.com/coop/subscribedlinks/directory/Reference</Output>
<Output name="link1b">link to the News Directory, </Output>
<Output name="url1b">http://www.google.com/coop/subscribedlinks/directory/News</Output>
<Output name="link1c">and link to the Movie Directory.</Output>
<Output name="url1c">http://www.google.com/coop/subscribedlinks/directory/Movies</Output>
</Response>
The code has three links. The url[n][a] attribute values define the web address for the link[n][a], which is the text for the hyperlink. The URL of the hyperlinks are defined in:
<Output name="url1"> - Defines the URL for the the linked text defined in link1, which is the first link in the first line of the result body.
<Output name="url1b"> - Defines the URL for the the linked text defined in link1b, which is the second link in the first line of the result body.
<Output name="url1c"> - Defines the URL for the the linked text defined in link1c, which is the third link in the first line of the result body.
The contents of the url[n][a]do not count toward the 80-character limit for each line of result body.
Although the sample code has plain text (<Output name="text1">Hello, world!</Output>), you can have results that consist only of links. Of course, once you define a link[n][a]attribute value, you also need to define its counterpart url[n][a] attribute value.
By default, the linked text is aligned to the left side of the custom results. If you want the hyperlinks to appear on the right side of the text instead, see the Designing the Look and Feel page.
Interspersing Plain Text with Linked Text
Each line in the result body may contain a combination of plain text and linked text. You can have a line with multiple links, another line with just a single link, and another one with just plain text, provided that the total length of each line–including the plain text and the linked text–does not exceed 80 characters.
To intersperse linked text with plain text, use the text[n][a] attribute value. As with the previously discussed attribute values for the Output name, [n] is the number that indicates which text line in the result body the link should appear on and [a] corresponds to the order of the text within that line. You do not need to specify the [a] for the first text, only the subsequent ones. So the attribute values for the text in your first line would be: text1, text1b, text1c, text1d, text1e. The snippet of plain text will by default appear after the linked text with the same order ID; that is, the contents of text1b will appear after the contents of link1b. You can change this order by changing the output format as described on the Designing the Look and Feel page.
Here's a sample code with all the attribute values for Output.
<Response>
<Output name="title">Google Subscribed Links API</Output>
<Output name="more_url">www.google.com/coop/subscribedlinks</Output>
<Output name="text1">Hello, world!</Output>
<Output name="link1">Link to the Reference Directory, </Output>
<Output name="url1">http://www.google.com/coop/subscribedlinks/directory/Reference</Output>
<Output name="text1b"> and </Output>
<Output name="link1b">link to the News Directory, </Output>
<Output name="url1b">http://www.google.com/coop/subscribedlinks/directory/News</Output>
<Output name="text1c">and </Output>
<Output name="link1c">link to the Movie Directory.</Output>
<Output name="url1c"http://www.google.com/coop/subscribedlinks/directory/Movies</Output>
</Response>
Escaping Special Characters
The Subscribed Links API has a few special characters that are reserved for particular purposes. You cannot use them unless you use escape characters. For example, the bracket characters ([ ]) are reserved for setting off object types, which are discussed in the Creating Patterns of Queries page.
The following table lists the reserved characters and their escape characters:
