PublishingPageCollection.Add Method (String, PageLayout)

Article
10/23/2013

Creates a new PublishingPage in the PublishingPageCollection of the PublishingWeb object.

Namespace: Microsoft.SharePoint.Publishing
Assembly: Microsoft.SharePoint.Publishing (in Microsoft.SharePoint.Publishing.dll)

Syntax

'Declaration
Public Function Add ( _
    name As String, _
    layout As PageLayout _
) As PublishingPage

'Usage
Dim instance As PublishingPageCollection
Dim name As String
Dim layout As PageLayout
Dim returnValue As PublishingPage

returnValue = instance.Add(name, layout)

public PublishingPage Add(
    string name,
    PageLayout layout
)

Parameters

name
Type: System.String
URL name of the new PublishingPage.

layout
Type: Microsoft.SharePoint.Publishing.PageLayout
PageLayout instance that is used to render the new PublishingPage.

Return Value

Type: Microsoft.SharePoint.Publishing.PublishingPage
The newly created PublishingPage.

Exceptions

Exception	Condition
[System.ArgumentException]	Invalid value. The value cannot be an empty string.
[System.ArgumentException]	Invalid extension for PublishingPage URL name. PublishingPage URL names must have the file extension .aspx.
[System.IO.PathTooLongException]	Specified file or folder name is too long. The URL path for all files and folders must be 260 characters or fewer (and no more than 128 characters for any single file or folder name in the URL). Type a shorter file or folder name.
[Microsoft.SharePoint.SPException]	File with the name x already exists. It was last modified by y on z.
[Microsoft.SharePoint.SPException]	File or folder name x contains characters that are not permitted. Use a different name.
[System.ArgumentNullException]	One of the input parameters is a null reference (Nothing in Visual Basic).
[System.UnauthorizedAccessException]	Current user does not have sufficient permissions to perform this action.
[System.IO.FileLoadException]	Another file with the same name already exists.
[System.IO.DirectoryNotFoundException]	There is a problem with the name parameter.

Remarks

The name value cannot be empty and cannot exceed 128 characters. If it exceeds the maximum number of characters, it will be trimmed. The name must also be unique within the parent PublishingWeb.

The name cannot contain any of the following invalid characters: "#%*:<>?\/{|} & or ASCII character 0x7f.

The layout value must be a PageLayout from the current site collection. Generally, the PageLayout should be a member of the PageLayoutCollection that is returned by the Publishing.GetAvailablePageLayouts() method, but Microsoft Office SharePoint Server 2007 does not enforce this.

The new PublishingPage has the following property values.

Property	Value
PublishingPage.PublishingWeb	PublishingWeb that contains the PublishingPageCollection.
PublishingPage.ContentType	AssociatedContentType value for the layout.
PublishingPage.CreatedBy	User of PublishingPage at the date and time this method was called.
CreatedDate	Date and time this method was called.
PublishingPage.Description	None.
PublishingPage.EndDate	Never (null).
PublishingPage.LastModifiedBy	Current user.
PublishingPage.LastModifiedDate	Date and time when this method was called.
PublishingPage.Layout	layout parameter value.
PublishingPage.ListItem	Underlying SPListItem of the PublishingPage.
PublishingPage.LocalContactEmail	None.
PublishingPage.LocalContactImage	None.
PublishingPage.LocalContactName	None.
PublishingPage.Name	name parameter value.
PublishingPage.Contact	Current user.
PublishingPage.StartDate	Immediate (null).
PublishingPage.Title	None.
PublishingPage.Url	Server-relative URL for the new PublishingPage.

The user must have Add and Edit permissions in the PublishingWeb, specifically for items in the PublishingWeb.PagesList, to use this method.

Examples

This sample creates a new PublishingPage object in a PublishingWeb.

Before compiling and running this sample, verify that an SPWeb that is a PublishingWeb exists and is passed in as a Web parameter.

The PageLayout used for creating the page must be passed in.

using SPWeb = Microsoft.SharePoint.SPWeb;
using PublishingWeb = Microsoft.SharePoint.Publishing.PublishingWeb;
using PageLayout = Microsoft.SharePoint.Publishing.PageLayout;
using PublishingPageCollection = Microsoft.SharePoint.Publishing.PublishingPageCollection;
using PublishingPage = Microsoft.SharePoint.Publishing.PublishingPage;

namespace Microsoft.SDK.SharePointServer.Samples
{
    public static class PublishingPageCollectionCodeSamples
    {
        public static void CreateNewPage( SPWeb web, PageLayout pageLayout )
        {
            // TODO: Replace these variable values with your own
            // values.
            //
            // The URL name of the new page
            string newPageName = "Contoso.aspx";
            //
            // The comment to set when the page is checked in.
            string checkInComment = "Your check in comments";

            // Validate the input parameters.
            if (null == web)
            {
                throw new System.ArgumentNullException("web");
            }
            if (null == pageLayout)
            {
                throw new System.ArgumentNullException("pageLayout");
            }

            // Get the PublishingWeb wrapper for the SPWeb
            // that was passed in.
            PublishingWeb publishingWeb = null;
            if (PublishingWeb.IsPublishingWeb(web))
            {
                publishingWeb = PublishingWeb.GetPublishingWeb(web);
            }
            else
            {
                throw new System.ArgumentException("The SPWeb must be a PublishingWeb", "web");
            }
           
            // Create the new page in the PublishingWeb.
            PublishingPageCollection pages = publishingWeb.GetPublishingPages();
            PublishingPage newPage = pages.Add(newPageName, pageLayout);

            // Check the new page in so that other contributors
            // can work on it.
            newPage.CheckIn(checkInComment);          
        }
    }
}