This project is read-only.

What is the API?

Topics: Developer Forum
Dec 3, 2008 at 3:15 PM
I think I'm trying to understand the boundaries of what can be done in a binary distribution and what can't.
(Preferably I don't want to touch the source distribution.)

Reading the docs on the N2 site one can conclude that the following _is_ possible with a binary distribution:
* Creating New Pagetypes
* Creating New Controltypes
* Skinning the site (themes)
    - Adjusting css
    - Adjusting images and themeable control settings if the used control can be located in source.
* Adjusting the tinyMCR editors settings.
* Replacing Master Pages

What I don't understand if I can or can't without sabotaging the src:
* Altering the rendering of existing built in templates beyond themes.
    - By configuration (The menu can be i know)
    - By replacing the aspx or ascx somehow? (like pointing to it)
* Altering the default settings of new items of existing types in the editor.
    - Configuration settings?

What I would like to know but is unrelated to code:
* Changing type of an item on a site in use?

I so like the features, but at the same time I'm pulling my hair trying to understand...
What is the API?
What is not the API?
Is there API docs?

I'm not used at all to work with something that has this much features already done. While it's frustrating not completely understanding how the built in parts works, it's unreasonable not using them when the already done stuff seems so excellent.

Now in my case, I've realized that the master is powerful enough for all my needs, so I ended up rewriting the html/css instead of creating a master with less and only the features we need. (Also because I can't fully understand what the implications would be with a different master.)
I didn't see any need at all for creating another pagetype, the default "Text Page" (plain content page) meets the requirements currently, it's all text pages.
We need news and navigation, already done.
Now when I want to remove the page header (h1) have I painted myself into a corner? Should one always do a template even if the current stuff works?
What renders the "Text Page"? How do I locate it? Can I step through the debugger finding it? Where would a reasonable starting breakpoint be?
If I want another rendering of the news. Is the only way building a new type and recreating/copy-pasting all the news items?
Thanks for whatever kind of help I can get.
Dec 3, 2008 at 10:35 PM
Hi, you pose interesting questions, and choose interesting words (sabotaging the src =)

Please change what you need to solve your problems. If you can use the extension points, or propose new ones you and the next guy might benefit from a more upgradable system. In the end the templates project is just a proposal to be used as needed.

One way to extend without sabotaging you can use the ReplacesParentDefinition attribute:

    [Definition("News", "News", "A news page.", "", 155)]
    public class MyNews : News
         get { return "~/path/to/my/news.aspx"; }

This would hide the default news and display MyNews instead. There is also ReplaceDefinitions attribute to specify several items to replace.

Show title is an interesting question. One way to do it would be modifying new items:

            N2.Context.Definitions.ItemCreated += delegate(object sender, ItemEventArgs e)
                    if(e is N2.Templates.Items.AbstractPage)
                        (e as N2.Templates.Items.AbstractPage).ShowTitle = false;

Another way would be configuring a custom master page and not adding a title.

To locate the text page I would look up it's content class in the templates source.

One way to start debugging to step through could be RequestLifecycleHandler. It's the first object beeing called.

Grokking a codebase is tough and I don't really know a shortcut. I tend to focus on the details and try to succeed with small steps.

About API and what it is. I'd say it's primarily the interfaces and abstract base classes in N2.dll. From there it's a floating line. Encapsulation and internals are very rare in N2. It can make for a daunting API but I've seen some great examples using this approach and I very much prefer it myself. The templates project is something grown out of personal need and friendly requests.

Hope you make something out of this.
Feb 3, 2009 at 10:14 AM
I realized castle/ioc was the key to the API. I had no experience in IoC/DI earlier but since this question I read up on IoC and have tried out and used both autofac and unity in some of my projects. I thank you for the enlightenment! It was very refreshing.

I'm back to finishing the website now and I'm currently thinking about creating a new menu class implementation, but first I want to check with you so that it isn't already there and I've missed it.
I want the menu to start on a specific node, and to be visible regardless if the current node is in that branch or not.
BuildControlHierarchy seems to be what I need to replace right? Or maybe just GetStartingPoint or StartPage?
Feb 3, 2009 at 9:43 PM
The navigation is tougher than it seems. There are a few different approches to this in N2 (e.g. ASP.NET sitemap provider and N2.Find.Tree). You could look at the menu control in the templates project for some inspiration.