/// <summary>
/// Retrieve the headings associated with this superheading.
/// </summary>
/// <param name="superheading">The superheading parent</param>
/// <returns>A list of headings</returns>
public List<Heading> Headings(Superheading superheading)
{
return _client.Request("superheading/headings").
AddParameter("opco", superheading.Opco).
AddParameter("slug", superheading.Slug).
MakeRequest<List<Heading>>();
}
/// <summary>
/// Remove the heading from the superheading. Removing a heading from
/// a superheading that doesn't have that heading has no effect and
/// generates no exceptions.
/// </summary>
/// <param name="superheading">The superheading parent</param>
/// <param name="heading">The child heading</param>
/// <exception cref="Terra.ServerException">Either the superheading or the heading doesn't exist</exception>
public void RemoveHeading(Superheading superheading, Heading heading)
{
_client.Request("superheading/heading", Method.DELETE).
AddParameter("opco", superheading.Opco).
AddParameter("superheading", superheading.Slug).
AddParameter("heading", heading.Pid).
MakeRequest();
}
/// <summary>
/// This is a convenience method to create or add an existing synonym
/// (or translation) to a superheading. If the synonym does not already
/// exist, it is created with a default slug (and default language, if
/// not otherwise indicated). The synonym, existing or new, is
/// associated with the superheading.
/// </summary>
/// <param name="superheading">The superheading to associate with this synonym</param>
/// <param name="synonym">The new or existing name of a synonym</param>
/// <param name="language">The language of the synonym; defaults to the opco's language</param>
/// <returns>The new or existing synonym</returns>
/// <exception cref="Terra.ServerException">The superheading does not exist</exception>
public Synonym AddSynonym(Superheading superheading, string synonym, string language = null)
{
var slug = _client.Slugify(synonym);
try
{
var existing = _client.Synonyms.Get(superheading.Opco, slug);
_client.Request("superheading/synonym", Method.PUT).
AddParameter("opco", superheading.Opco).
AddParameter("superheading", superheading.Slug).
AddParameter("slug", slug).
MakeRequest();
return existing;
}
catch (ServerException e)
{
if (e.Status == System.Net.HttpStatusCode.NotFound)
{
return CreateSynonym(superheading, synonym, slug, language);
}
else
{
throw e;
}
}
}
/// <summary>
/// Remove the synonym with from the superheading. Note that this doesn't
/// delete the synonym, simply removes its association from this
/// superheading.
/// </summary>
/// <param name="superheading">The superheading with which to disassociate the synonym</param>
/// <param name="synonym">The synonym for the superheading</param>
/// <exception cref="Terra.ServerException">Either the superheading or the synonym doesn't exist</exception>
public void RemoveSynonym(Superheading superheading, Synonym synonym)
{
_client.Request("superheading/synonym", Method.DELETE).
AddParameter("opco", superheading.Opco).
AddParameter("superheading", superheading.Slug).
AddParameter("slug", synonym.Slug).
MakeRequest();
}
/// <summary>
/// Create a new synonym and associate it with this superheading.
/// <para>
/// Synonyms may also be used as a simple translation tool. When you
/// create a synonym, by default it is assigned to the same langauge as
/// the operating company. However, by assigning a different language
/// to the synonym, you now have a translation for the superheading.
/// </para>
/// </summary>
/// <param name="superheading">The superheading to associate with the synonym</param>
/// <param name="name">The human-readable name of the synonym</param>
/// <param name="slug">An SEO-compliant slug for the synonym; generated if not provided</param>
/// <param name="language">The language of the name; defaults to the opco's language</param>
/// <returns>The newly created Synonym</returns>
/// <exception cref="Terra.ServerException">The superheading does not exist, or the synonym already exists</exception>
public Synonym CreateSynonym(Superheading superheading, string name, string slug = null, string language = null)
{
return _client.Request("superheading/synonym", Method.POST).
AddParameter("opco", superheading.Opco).
AddParameter("name", name).
AddParameter("slug", slug).
AddParameter("lang", language).
AddParameter("superheading", superheading.Slug).
MakeRequest<Synonym>();
}
/// <summary>
/// Get the list of synonyms associated with this superheading.
/// </summary>
/// <param name="superheading">The superheading</param>
/// <returns>A list of synonyms</returns>
/// <exception cref="Terra.ServerException">The superheading does not exist</exception>
public List<Synonym> Synonyms(Superheading superheading)
{
return _client.Request("superheading/synonyms").
AddParameter("opco", superheading.Opco).
AddParameter("slug", superheading.Slug).
MakeRequest<List<Synonym>>();
}
/// <summary>
/// Completely delete a superheading from Terra. If you delete a
/// superheading, the headings will still be available from the
/// operating company itself.
/// </summary>
/// <param name="superheading">The superheading to delete</param>
/// <exception cref="Terra.ServerException">The superheading does not exist</exception>
public void Delete(Superheading superheading)
{
_client.Request("superheading", Method.DELETE).
AddParameter("opco", superheading.Opco).
AddParameter("slug", superheading.Slug).
AddParameter("v", superheading.Version).
MakeRequest();
}
/// <summary>
/// Update the name, external identifier, or language for this superheading.
/// Neither the operating company nor the slug may be modified.
/// </summary>
/// <param name="superheading">An superheading with the updated information</param>
/// <returns>A new Superheading object, with the updates in place</returns>
/// <exception cref="Terra.ServerException">
/// <list type="bullet">
/// <item>
/// <description>If any of the parameters submitted are invalid, returns a status of Not Acceptable.</description>
/// </item>
/// <item>
/// <description>If the existing superheading could not be found on the server, returns a status of Not Found</description>
/// </item>
/// <item>
/// <description>If the local superheading is older than the version on the server, a Precondition Failed status is returned</description>
/// </item>
/// </list>
/// </exception>
public Superheading Update(Superheading superheading)
{
return _client.Request("superheading", Method.PUT).
AddParameter("opco", superheading.Opco).
AddParameter("name", superheading.Name).
AddParameter("slug", superheading.Slug).
AddParameter("external", superheading.External).
AddParameter("lang", superheading.Language).
AddParameter("v", superheading.Version).
MakeRequest<Superheading>();
}
/// <summary>
/// Create a new heading for the given operating company. The heading
/// name need not be unique, but its PID must be.
/// <para>
/// If the PID is not provided (either null or an empty string), it will
/// be created by transforming the name of the heading into an SEO-ready
/// value. For example, the name "Mexican Restaurants" would be transformed
/// into "mexican-restaurants".
/// </para>
/// <para>
/// If language is not supplied it will default to the language of the
/// operating company.
/// </para>
/// </summary>
/// <param name="opco">The three or four letter code for the operating company</param>
/// <param name="name">The name of the heading</param>
/// <param name="pid">A unique identifier for the heading, or null to have one generated</param>
/// <param name="language">The language of the heading, or null to use the opco's language</param>
/// <param name="parent">A superheading, to add this new heading directly to a superheading</param>
/// <returns>The newly created Heading object</returns>
/// <exception cref="Terra.ServerException">
/// <list type="bullet">
/// <item>
/// <description>If any of the parameters submitted are invalid, returns a status of Not Acceptable.</description>
/// </item>
/// <item>
/// <description>If the PID already exists, returns a status of Conflict.</description>
/// </item>
/// <item>
/// <description>If the operating company or superheading does not exist, returns a status of Not Found.</description>
/// </item>
/// </list>
/// </exception>
public Heading Create(string opco, string name, string pid = null, string language = null, Superheading parent = null)
{
var request = _client.Request("heading", Method.POST).
AddParameter("opco", opco).
AddParameter("name", name).
AddParameter("pid", pid).
AddParameter("lang", language);
if (parent != null)
{
request.AddParameter("superheading", parent.Slug);
}
return request.MakeRequest<Heading>();
}
