This project is read-only.

Page directives, master pages and layout customization.

Topics: Developer Forum
Nov 25, 2008 at 8:45 AM
I'm trying to understand what the page directives points to and if some of them are dynamic or used in an unusual way. It seems that the default page is rather empty. And the master directive is pointed to a Top+SubMenu.Master. I assume master pages can be swapped through site configuration?
Looking at NS_TemplatesSite project there is a MyPage.aspx custom page. I want to apply my layout.
Do I create all pages custom, or do I change the aspx, ascx and master files that aren't included in the project?
I'm guessing blindly that default.aspx is what all calls are routed through and some dynamic page/control loading selects the proper gui templates?
If I'm guessing right, should I alter the default.aspx or should I create another one? How about the master page, should that one be ripped out or gently changed?
Seing all the droppable zone stuff I feel like I'll probably break functionality along the way. (I have a rather distinct layout specified, that I'm either implementing with tables or YUI stylesheets.)
When I started looking at the guides on the web page I felt confident that it would be easy to get started with N2, but I'm getting more and more confused the more I compare the docs with the source I'm looking at.
Btw, is MVC required for N2 to work?
Nov 25, 2008 at 7:01 PM
Hi, let me start with an overview of the solution, hope this will help put things in perspective:
  • N2 library: functionality to store and load data to the database, map url:s to content and other useful components
  • Edit: Uses N2 library to visually manage the content of a site
  • Templates: A set of funtionality like news and content pages with styles and layout
  • Add-ons: More functionality on top of N2 templates
  • Examples: Ways to interact with different levels of the stack, e.g.
    • Templates site: An example project that builds upon Templates. This is an example of building functionality on top of the templates without modifying them (good for upgradability)
    • Minimal (VB/C#): Show how to build a site without templates (only n2 library and edit)
    • MVC: Show how to use n2 library and edit with the ASP.NET MVC framework for the external parts
Now, I'm understanding you want to use "N2 Templates" with modifications. You can hack away in the source but you prefer to retain some hope for upgradability.

Here are some options:
  • Add a custom theme in App_Themes
  • Add content item (.cs) + content template (.aspx) for the functionality you need (you can also inherit and replace existing functions)
  • Add custom parts (.cs + .ascx).
  • Replace the master page through configuration. The most fail-safe approach is copying the existing master page and reorganize the zones as needed. Yon can safely remove the zones. If they arn't there they just won't show up when "organizing" a page.
  • Skip templates and go for a custom solution
Can you link to the documents that are confusing? Everyone has different perspectives and it's hard to find the balance between complete, useful and too much.
Nov 26, 2008 at 10:32 AM
>Can you link to the documents that are confusing? Everyone has different perspectives and it's hard to find the balance between complete, useful and too much.

Yes, sure. :)

Here's my experience with the "Documentation/Getting started" guide i read:
------------------------------------------------------------------------
1.
http://n2cms.com/Documentation/Startup_guide/Installation.aspx
Heading: Step 1: Download from CodePlex
I looked at the download section in codeplex for the current release (1.3.4)
The corresponding templates project afaik is "Templates + Sample Project (compiled core+edit+templates+sample source, 1.4.3.1)", aka N2_TemplatesSite.zip.
Example_TemplatesImplementation, which you link to in the next sentence seems rather different looking at the file tree.

IMO, N2_TemplatesSite is better for the demo having the zero config database, sqllite.


2.
http://n2cms.com/Documentation/Startup_guide/Installation.aspx
Heading: Step 5: Log in and play around
Why not log in and play around a bit. The username and password should be admin/changeme.

First real confusion. It should be mentioned that ~/edit/login.aspx is the only place where this user/password works. Trying the login box on the webpage just leads to an "invalid login" attempt.


3.
http://n2cms.com/Documentation/Startup_guide/Installation.aspx
Heading: Step 6: Look at some code
The template uses a master page and a theme which is set at runtime. To change edit the start page.

What is the start page? I guess it's the first child to the root node in the admin gui, but I can't find any master page reference there.

4.
http://n2cms.com/Documentation/Startup_guide/Installation.aspx
Heading: Okay, lets start programming
* Open up the solution

It's already up. We have looked at the web config, and examined the class and template. Nitpicking maybe, but still confusing. Maybe you are referring to some other solution?

5.
http://n2cms.com/Documentation/Startup_guide/Step_2_A_glance_at_our_domain_model.aspx
Heading: The content bearing class (content item)

Using the project we are asked to (templates project), we can F12 our way to ContentItem reading [from metadata] declarations.
However it's rather difficult taking "a quick look at that Text property". We can only see it's signature.
Also, "Text" isn't defined in ContentItem but rather AbstractContentPage.
Nitpicking? It's either way confusing for a total newcomer to this project, and made at least me feel dumb.
Personally i would drop the word "interesting" in that bullet because to me I interpret this as there is coming a deeper analysis of the attribute. I feel it would be better to write out the attribute name and explain it's parameters.
(But i change my mind in the next point. I as reader (probably some more guys) will try to understand what he reads now, not continuing hoping to understand later. This bullet makes me stop here, trying to understand the EditableFreeTextArea by reading code before realizing the explanation is the next topic. You said it first in the bullet "Take a quick look.. ..before you move on")


6.
http://n2cms.com/Documentation/Startup_guide/Step_2_A_glance_at_our_domain_model.aspx
Heading: A property encapsulating our content

Here comes the explanation of the attribute. This makes me want to drop the third bullet in "The content bearing class (content item)" completely or refrasing it and moving it down here.

7.
http://n2cms.com/Documentation/Startup_guide/Step_2_A_glance_at_our_domain_model.aspx
Heading: A property encapsulating our content
"The parameters are just the name displayed in edit and the order of this property."
could maybe be changed to:
"The parameters are just the name displayed in edit and the sort order of this property."
There are many kinds of orders. :)

8.
http://n2cms.com/Documentation/Startup_guide/Step_2_A_glance_at_our_domain_model.aspx
Heading: A property encapsulating our content

"Secondly, look at that GetDetail call in the getter"

In AbstractContentPage? Allright. But now it's clear that I have the wrong project open. I can't look at the GetDetail call because I haven't got the source.

You could just paste the code there if we should stay in the Templates Project:
        [EditableFreeTextArea("Text", 100, ContainerName = Tabs.Content)]
        public virtual string Text
        {
            get { return (string) (GetDetail("Text") ?? string.Empty); }
            set { SetDetail("Text", value, string.Empty); }
        }

9.
http://n2cms.com/Documentation/Startup_guide/Step_3_Edit_mode.aspx

Please ask the reader to go to a specific page in the sample site first.
"Now we are accessing the site's edit interface (/edit) and are editing the start page." is concise, but remember we don't know our way around either the project nor the cms gui yet. We're complete noobs reading this.

10.
http://n2cms.com/Documentation/Startup_guide/Step_3_Edit_mode.aspx
"The attribute tells N2 what type of page is called when we are editing."
chould that maybe be
"This attribute tells N2 what the type of page is called in the editor."
?

11.
http://n2cms.com/Documentation/Startup_guide/Step_4_How_is_content_used_on_a_page.aspx
Heading: Our only template: default.aspx

This is where you lost me completely in the documentation:
* Since we were using default.sapx as template we didn't need to change anything.

Que?
public override string TemplateUrl
{
        get { return "~/UI/MyPage.aspx"; }
}


12.
http://n2cms.com/Documentation/Startup_guide/Step_4_How_is_content_used_on_a_page.aspx
Heading: Our only template: default.aspx
* Examine the GalleryItem. Did you notice we're inheriting N2.Web.UI.Page? Since we are inheriting this base class we have some nice options when it comes to getting our content. Read on...

GalleryItem? Where? Not Template Project? Source? Ok.. looking....

But...
public class GalleryItem : AbstractPage
AbstractPage : ContentItem
ContentItem : IComparable, IComparable<ContentItem>, ICloneable, Web.IUrlParserDependency, IContainable, INode

No N2.Web.UI.Page in sight.
Am I looking at wrong GalleryItem? Using search in visual studio the only GalleryItem is src\wwwroot\Templates\Items\GalleryItem.cs
(Find all "GalleryItem", Subfolders, Keep modified files open, Find Results 1, "Entire Solution", "*.*")

13.
http://n2cms.com/Documentation/Startup_guide/Step_4_How_is_content_used_on_a_page.aspx
Heading: Generic page base class

Are you talking about N2.Templates.Web.UI.TemplatePage here?
Please specify.


14.
http://n2cms.com/Documentation/Startup_guide/Step_4_How_is_content_used_on_a_page.aspx
Heading: Intellisense...

Our custom TextPage class?
Again searching the source code...

namespace N2.Templates.UI.Views
    public partial class Text : Web.UI.TemplatePage<TextPage>
   
or
namespace N2.Templates.Items
    public class TextPage : AbstractContentPage, IStructuralPage, ISyndicatable
?

Neither has any Text property. What are you referring to?
What does "That Text property is defined in our custom TextPage class." really mean?

15.
http://n2cms.com/Documentation/Startup_guide/Step_4_How_is_content_used_on_a_page.aspx
Heading: Accessing properties in the page aspx

Please show a short code snippet so we can see what you mean.

16.
http://n2cms.com/Documentation/Startup_guide/Step_5_More_about_inheriting_content_items.aspx
Heading: Inheritance

* The examples contains two classes deriving from N2.ContentItem.
  * MyItemBase: an abstract class defining an editable title and name
  * TextPage: a class containing an editable property, Text. Since this class isn't abstract it is available in edit mode when we create new pages.

Find all "MyItemBase", Subfolders, Keep modified files open, Find Results 1, "Entire Solution", "*.*"
  Matching lines: 0    Matching files: 0    Total files searched: 1748

TextPage doesn't contain any Text property as noted in #14.


17.
http://n2cms.com/Documentation/Startup_guide/Step_5_More_about_inheriting_content_items.aspx
Heading: Inheritance

No classes in the TemplatesSite sample code inherits directly from ContentItem. Please rephrase such that it can be read that it inherits from ContentItem indirectly, as the base clase 3 levels away.


18.
http://n2cms.com/Documentation/Startup_guide/Step_5_More_about_inheriting_content_items.aspx
"Our custom base class...

...is a N2.ContentItem

Define editable properties

This class has some attributes, the Item attribute and the HasEditable attribute (the attribute name has recently changed to WithEditable).
The Item attribute defines information about the item
The WithEditable attribute defines editable properties/details in the class or any base class. In this case we are defining an editable Title and Name.
Actually there is no requirement of a property with the name defined on the WithEditable attribute. If no property with the same name exists the value is stored in the detail collection. More about details later."

What is the Custom base class? MyPage? Or the missing MyItemBase? TextPage?
There is no WithEditable attribute.
There are attributes called WithEditableTitle, WithEditableName and WithEditablePublishedRange used in the project. Theese are used on the Templates/Items classes. They are not avaliable in the TemplatesProject but rather the source project.

For a newcomer, it's impossible to understand when the docs and the source are completely different.

19.
http://n2cms.com/Documentation/Startup_guide/Step_5_More_about_inheriting_content_items.aspx
Heading: Dissecting the WithEditable attribute; display name
  It has a display name which is the label the editors see when they are editing
Heading: Content item property name
  It has a property name which is the property (or detail) name on the content object that will receive the value that is beeing edited.
Heading: Editor control
  It has a type of control used for the editing (in this case it's a textbox)
  It has a property on the editor control which will contain the value when we save (textbox.Text)

Sorry, I don't understand what I am reading. Please write out the property names or the classes or the template (.aspx) names.
---------------------------------------------

I hope this sheds a light on what I'm meaning with getting confused by reading the docs.
Still, this looks like a great platform. I'm just eager to understand it properly.
:)
Nov 26, 2008 at 10:34 AM
On my computer the italic letters came out very uneasy for the eyes. Sorry. Maybe copy/paste to word makes it readable...
Nov 27, 2008 at 1:58 PM
Edited Nov 27, 2008 at 2:03 PM

Here are some options:
      • Add a custom theme in App_Themes
      • Add content item (.cs) + content template (.aspx) for the functionality you need (you can also inherit and replace existing functions)
      • Add custom parts (.cs + .ascx).
      • Replace the master page through configuration. The most fail-safe approach is copying the existing master page and reorganize the zones as needed. Yon can safely remove the zones. If they arn't there they just won't show up when "organizing" a page.
      • Skip templates and go for a custom solution


Here's what I'm trying to accomplish. I want to have a 3 column layout with header and footer. However, I would like to, if possible, to use Yui-grids for this.
Using the gridbuilder at yui for generating the structure, here's some sample code:


<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN"
"http://www.w3.org/TR/html4/strict.dtd">
<html>
<head>
<title>YUI Base Page</title>
<link rel="stylesheet"
href="http://yui.yahooapis.com/2.5.1/build/reset-fonts-grids/reset-fonts-grids.css"
type="text/css">
</head>
<body>
<div id="doc4" class="yui-t2">
<div id="hd">
<h1>
YUI: CSS Grid Builder</h1>
</div>
<div id="bd">
<div id="yui-main">
<div class="yui-b">
<div class="yui-ge">
<div class="yui-u first">
<!-- YOUR DATA GOES HERE -->
</div>
<div class="yui-u">
<!-- YOUR DATA GOES HERE -->
</div>
</div>
</div>
</div>
<div class="yui-b">
<!-- YOUR NAVIGATION GOES HERE -->
</div>
</div>
<div id="ft">
Footer is here.</div>
</div>
</body>
</html>


I'll go for the approach with another master page and try to make it as similar as possible to the current master.
Thanks for the clarifications!
Dec 2, 2008 at 8:46 AM
Edited Dec 2, 2008 at 8:48 AM
It seems the current master in fact has all the layout features i ask for. Rewriting the master seems rather unnecessary for me, and probably most usages. The structure along with the possibility of removing parts either by CSS or using the ContentPlaceHolders seems to be flexible enough for most designs. I think it's an excellent master page for CMS managed pages!