xml-sitemap/docs/api.md

Utilities for quickly writing XML sitemaps

# API

An object representation of XML sitemaps and methods for editing them.

**Kind**: global class  

* [XmlSitemap](#XmlSitemap)
    * [new XmlSitemap([xmlAsString])](#new_XmlSitemap_new)
    * _instance_
        * [.host](#XmlSitemap+host) : <code>String</code>
        * [.xmlObj](#XmlSitemap+xmlObj) : <code>Object</code>
        * [.urls](#XmlSitemap+urls) : <code>Array.&lt;String&gt;</code>
        * [.files](#XmlSitemap+files) : <code>Object</code>
        * [.urlOptions](#XmlSitemap+urlOptions) : <code>Array.&lt;String&gt;</code>
        * [.optionHandlers](#XmlSitemap+optionHandlers) : <code>Object</code>
        * [.xml](#XmlSitemap+xml) ⇒ <code>String</code>
        * [.hasUrl(url)](#XmlSitemap+hasUrl) ⇒ <code>Bool</code>
        * [.add(url, [urlOptions])](#XmlSitemap+add) ⇒ <code>[XmlSitemap](#XmlSitemap)</code>
        * [.remove(url)](#XmlSitemap+remove) ⇒ <code>[XmlSitemap](#XmlSitemap)</code>
        * [.getUrlNode(url)](#XmlSitemap+getUrlNode) ⇒ <code>Object</code>
        * [.buildUrlNode(url, [options])](#XmlSitemap+buildUrlNode) ⇒ <code>Object</code>
        * [.setHost(url, [urlOptions])](#XmlSitemap+setHost) ⇒ <code>[XmlSitemap](#XmlSitemap)</code>
    * _static_
        * [.w3Date(date)](#XmlSitemap.w3Date) ⇒ <code>String</code>
        * [.handleLastmod([date])](#XmlSitemap.handleLastmod) ⇒ <code>String</code>
        * [.handleChangefreq(value)](#XmlSitemap.handleChangefreq) ⇒ <code>String</code>
        * [.handlePriority(value)](#XmlSitemap.handlePriority) ⇒ <code>String</code>
        * [.getLastmodFromFile(filepath)](#XmlSitemap.getLastmodFromFile) ⇒ <code>String</code>
        * [.parseUrlObject(urlObject)](#XmlSitemap.parseUrlObject) ⇒ <code>Object</code>

<a name="new_XmlSitemap_new"></a>

### new XmlSitemap([xmlAsString])
Create a new sitemap or create a sitemap object from an XML string.


| Param | Type | Description |
| --- | --- | --- |
| [xmlAsString] | <code>String</code> &#124; <code>Buffer</code> | Optional, the sitemap XML as a string or Buffer. Must be a valid sitemap. |

**Example**  
```js
See Basic Usage above
```
<a name="XmlSitemap+host"></a>

### xmlSitemap.host : <code>String</code>
The webpage host to which all future urls will be relative. See [setHost](#XmlSitemap+setHost)

**Kind**: instance property of <code>[XmlSitemap](#XmlSitemap)</code>  
**Default**: <code>&#x27;&#x27;</code>  
**Example**  
```js
var sitemap = new XmlSitemap()
  .setHost('http://domain.com/');

sitemap.host
//=> 'http://domain.com/'

sitemap.add([
'/magic',
'http://domain.com/another-page'
]);

sitemap.urls
//=> [ 'http://domain.com/', 'http://domain.com/magic',
//     'http://domain.com/another-page']
```
<a name="XmlSitemap+xmlObj"></a>

### xmlSitemap.xmlObj : <code>Object</code>
XML object tree of sitemap, as generated by [xml2js](https://github.com/Leonidas-from-XIV/node-xml2js). Automatically created and udated as the sitemap is modified.

**Kind**: instance property of <code>[XmlSitemap](#XmlSitemap)</code>  
**Example**  
```js
{
  urlset: {
    '$': { xmlns: 'http://www.sitemaps.org/schemas/sitemap/0.9' },
    url: [
      { loc: 'http://domain.com/',
         lastmod: '1985-12-25',
         priority: '0.9' },
      { loc: 'http://domain.com/magic',
         lastmod: '2012-12-21',
         changefreq: 'never' }
    ]
  }
}
```
<a name="XmlSitemap+urls"></a>

### xmlSitemap.urls : <code>Array.&lt;String&gt;</code>
Array of urls in the sitemap. Add urls by using [add](#XmlSitemap+add).

**Kind**: instance property of <code>[XmlSitemap](#XmlSitemap)</code>  
**Example**  
```js
var sitemap = new XmlSitemap()
  .add('http://domain.com/')
  .add('http://domain.com/magic');

console.log(sitemap.urls);
// [ 'http://domain.com/', 'http://domain.com/magic' ]
```
<a name="XmlSitemap+files"></a>

### xmlSitemap.files : <code>Object</code>
Object of files linked to a url, for determining lastmod. To link a file use [XmlSitemap#linkFile](XmlSitemap#linkFile) or pass the filename under the key `file` in the initial options.

**Kind**: instance property of <code>[XmlSitemap](#XmlSitemap)</code>  
<a name="XmlSitemap+urlOptions"></a>

### xmlSitemap.urlOptions : <code>Array.&lt;String&gt;</code>
Allowable option tags for urls in sitemap. Add options with or without handlers by using [XmlSitemap#addOption](XmlSitemap#addOption).

**Kind**: instance property of <code>[XmlSitemap](#XmlSitemap)</code>  
**Default**: <code>[&#x27;lastmod&#x27;, &#x27;changefreq&#x27;, &#x27;priority&#x27;]</code>  
**Example**  
```js
var sitemap = new XmlSitemap();

console.log(sitemap.urlOptions);
// [ 'lastmod', 'changefreq', 'priority' ]

sitemap.addOption('foo');
console.log(sitemap.urlOptions);
// [ 'lastmod', 'changefreq', 'priority', 'foo' ]
```
<a name="XmlSitemap+optionHandlers"></a>

### xmlSitemap.optionHandlers : <code>Object</code>
Optional handlers for custom option settings. Handler functions are listed under the option name key. Add options with [XmlSitemap#addOption](XmlSitemap#addOption).

**Kind**: instance property of <code>[XmlSitemap](#XmlSitemap)</code>  
**Default**: <code>{
  lastmod: XmlSitemap.handleLastmod,
  changefreq: XmlSitemap.handleChangefreq,
  priority: XmlSitemap.handlePriority
}</code>  
<a name="XmlSitemap+xml"></a>

### xmlSitemap.xml ⇒ <code>String</code>
Output the sitemap as XML.

**Kind**: instance property of <code>[XmlSitemap](#XmlSitemap)</code>  
**Returns**: <code>String</code> - The sitemap XML  
<a name="XmlSitemap+hasUrl"></a>

### xmlSitemap.hasUrl(url) ⇒ <code>Bool</code>
Check if sitemap contains a url.

**Kind**: instance method of <code>[XmlSitemap](#XmlSitemap)</code>  
**Returns**: <code>Bool</code> - Whether the url is in the sitemap  

| Param | Type | Description |
| --- | --- | --- |
| url | <code>String</code> | The url to look for |

**Example**  
```js
var sitemap = new XmlSitemap()
  .add('http://domain.com/');

sitemap.hasUrl('http://domain.com/'); // true
sitemap.hasUrl('http://otherdomain.com/'); // false
```
<a name="XmlSitemap+add"></a>

### xmlSitemap.add(url, [urlOptions]) ⇒ <code>[XmlSitemap](#XmlSitemap)</code>
There are a few ways to add a urls:

1. Pass a single url as a string
2. Pass a single url as a string with an options object
3. Pass a single object with either a `url` or `loc` attribute and options
4. Pass an array with any of the above as elements

Aliased with `addUrl` or `addUrls`

**Kind**: instance method of <code>[XmlSitemap](#XmlSitemap)</code>  
**Returns**: <code>[XmlSitemap](#XmlSitemap)</code> - The sitemap object  
**Throws**:

- <code>TypeError</code> Url object must contain a `url` or `loc` property
- <code>Error</code> Url is already in sitemap
- <code>TypeError</code> Url must be object, string, or array


| Param | Type | Description |
| --- | --- | --- |
| url | <code>String</code> &#124; <code>Object</code> &#124; <code>Array</code> | The url(s) to add |
| [urlOptions] | <code>Object</code> | Options for setting various information about the url. Options must be in the objects [urlOptions](#XmlSitemap+urlOptions). |

**Example**  
```js
var sitemap = new XmlSitemap();
  .add('http://domain.com/')
  .add('http://domain.com/other', {lastmod: '2012-11-21'})
  .add({
    url: 'http://domain.com/magic',
    priority: 0.7
  })
  .add({
    loc: 'http://domain.com/another-page',
    changefreq: 'never'
  });

// which makes the same sitemap as:
var sitemap = new XmlSitemap()
  .add([
  'http://domain.com/',
  {
    url: 'http://domain.com/other',
    lastmod: '2012-11-21'
  },
  {
    url: 'http://domain.com/magic'
    priority: 0.7
  },
  {
    loc: 'http://domain.com/another-page',
    changefreq: 'never'
  }
];

sitemap.urls
//=> [ 'http://domain.com/', 'http://domain.com/other', ....s

sitemap.xml
//=> <?xml version="1.0"....
```
<a name="XmlSitemap+remove"></a>

### xmlSitemap.remove(url) ⇒ <code>[XmlSitemap](#XmlSitemap)</code>
Remove url from the Sitemap. Aliased with `removeUrl`.

**Kind**: instance method of <code>[XmlSitemap](#XmlSitemap)</code>  
**Returns**: <code>[XmlSitemap](#XmlSitemap)</code> - The sitemap object  

| Param | Type | Description |
| --- | --- | --- |
| url | <code>String</code> | The url to remove |

**Example**  
```js
var sitemap = new XmlSitemap()
  .add('http://domain.com/')
  .add('http://domain.com/other');

// BEFORE
console.log(sitemap.urls); // ['http://domain.com/', 'http://domain.com/other']
sitemap.hasUrl('http://domain.com/other'); // true

sitemap.remove('http://domain.com/other');

// AFTER
console.log(sitemap.urls); // ['http://domain.com/']
console.log(sitemap.xml);
// <?xml version="1.0" encoding="UTF-8"?>
// <urlset xmlns="http://www.sitemaps.org/schemas/sitemap/0.9">
//   <url>
//     <loc>http://domain.com/</loc>
//   </url>
// </urlset>
```
<a name="XmlSitemap+getUrlNode"></a>

### xmlSitemap.getUrlNode(url) ⇒ <code>Object</code>
Get node of the XML object tree for a url.

**Kind**: instance method of <code>[XmlSitemap](#XmlSitemap)</code>  
**Returns**: <code>Object</code> - The XML element of the url  

| Param | Type | Description |
| --- | --- | --- |
| url | <code>String</code> | The url of the desired XML node |

**Example**  
```js
var sitemap = new XmlSitemap()
  .add('http://domain.com/', {lastmod: '2012-12-21', changefreq: 'never'});

sitemap.getUrlNode('http://domain.com/');
// { loc: 'http://domain.com/',
// lastmod: '2012-12-21',
// changefreq: 'never' }
```
<a name="XmlSitemap+buildUrlNode"></a>

### xmlSitemap.buildUrlNode(url, [options]) ⇒ <code>Object</code>
Create a url node XML object

**Kind**: instance method of <code>[XmlSitemap](#XmlSitemap)</code>  
**Returns**: <code>Object</code> - The url XML node  

| Param | Type | Description |
| --- | --- | --- |
| url | <code>String</code> | The url to add |
| [options] | <code>Object</code> | Options for setting various information about the url, must be one of [urlOptions](#XmlSitemap+urlOptions). Add options with [XmlSitemap#addOption](XmlSitemap#addOption). |

<a name="XmlSitemap+setHost"></a>

### xmlSitemap.setHost(url, [urlOptions]) ⇒ <code>[XmlSitemap](#XmlSitemap)</code>
Sets the host of the webpage. All relative links added after this will added relative to the host. Automatically adds the host to the tree with the provided options.

**Kind**: instance method of <code>[XmlSitemap](#XmlSitemap)</code>  
**Returns**: <code>[XmlSitemap](#XmlSitemap)</code> - The updated sitemap object  
**Throws**:

- <code>Error</code> Url object must contain a `url` or `loc` property


| Param | Type | Description |
| --- | --- | --- |
| url | <code>String</code> &#124; <code>Object</code> | The url to set as host, or urlObject |
| [urlOptions] | <code>Object</code> | Options for setting various information about the url. Options must valid options in the [urlOptions](#XmlSitemap+urlOptions). |

<a name="XmlSitemap.w3Date"></a>

### XmlSitemap.w3Date(date) ⇒ <code>String</code>
Format a Date object to W3 standard string.

**Kind**: static method of <code>[XmlSitemap](#XmlSitemap)</code>  
**Returns**: <code>String</code> - Date formatted as year-month-day  
**Throws**:

- <code>TypeError</code> Argument must be Date object


| Param | Type | Description |
| --- | --- | --- |
| date | <code>Date</code> | the Date to format |

**Example**  
```js
var date = new Date();
date.setFullYear(2012);
date.setMonth(11);
date.setDate(21);

XmlSitemap.w3Date(date); // '2012-12-21'
```
<a name="XmlSitemap.handleLastmod"></a>

### XmlSitemap.handleLastmod([date]) ⇒ <code>String</code>
Determine what to put in the lastmod field given the input. Will NOT check format of string.

**Kind**: static method of <code>[XmlSitemap](#XmlSitemap)</code>  
**Returns**: <code>String</code> - The value of lastmod  

| Param | Type | Description |
| --- | --- | --- |
| [date] | <code>String</code> &#124; <code>Date</code> | The lastmod value as a Date object, the string 'now', or a string (will not confirm format) |

<a name="XmlSitemap.handleChangefreq"></a>

### XmlSitemap.handleChangefreq(value) ⇒ <code>String</code>
Check if changfreq value is valid.

**Kind**: static method of <code>[XmlSitemap](#XmlSitemap)</code>  
**Returns**: <code>String</code> - A valid changefreq value  
**Throws**:

- <code>Error</code> The changefreq must be valid. Allowed values are "always", "hourly", "daily", "weekly", "monthly", "yearly", "never".


| Param | Type | Description |
| --- | --- | --- |
| value | <code>String</code> | The changefreq value to check |

<a name="XmlSitemap.handlePriority"></a>

### XmlSitemap.handlePriority(value) ⇒ <code>String</code>
Check for valid priority value and return it as a string. Priority must be between 0 and 1.

**Kind**: static method of <code>[XmlSitemap](#XmlSitemap)</code>  
**Returns**: <code>String</code> - The priority value as a string  
**Throws**:

- <code>Error</code> Priority must be number between 0 & 1, inclusive.


| Param | Type | Description |
| --- | --- | --- |
| value | <code>Double</code> | The Priority value |

<a name="XmlSitemap.getLastmodFromFile"></a>

### XmlSitemap.getLastmodFromFile(filepath) ⇒ <code>String</code>
Get W3-standard formatted date string from file's last modified time.

**Kind**: static method of <code>[XmlSitemap](#XmlSitemap)</code>  
**Returns**: <code>String</code> - W3-standard formatted date string  
**Throws**:

- <code>Error</code> Unable to resolve filepath


| Param | Type | Description |
| --- | --- | --- |
| filepath | <code>String</code> | The path to the file |

<a name="XmlSitemap.parseUrlObject"></a>

### XmlSitemap.parseUrlObject(urlObject) ⇒ <code>Object</code>
Separates out url from options in urlObject.

**Kind**: static method of <code>[XmlSitemap](#XmlSitemap)</code>  
**Returns**: <code>Object</code> - Object with url under `url` and options object under `options`  
**Throws**:

- <code>TypeError</code> `urlObject` must be an object
- <code>TypeError</code> `urlObject` contains no `url` or `loc` key


| Param | Type | Description |
| --- | --- | --- |
| urlObject | <code>Object</code> | The url object to parse |