N2 - Tutorial, Guides, Docs.. Required

Topics: Developer Forum
Apr 14, 2009 at 3:45 PM
Hi guys,

I've been trying to get into N2 for a little while now, I have to say the lack of tutorials, guides, and docs - For beginners is pretty bad.

There IS a lot of content both up here on the discussion group and on the N2 site (not to mention example downlods); however it doesn't seem to be aimed at developer newbie's to N2. I have a bunch of questions that I have and still aren't answered, I feel some are pretty basic and would help new developers that stumble upon N2 to actually think "Hey this is really cool, and I can understand how it works without having a PHD".

esteewhy and libardo are brilliant at replying to posts (thanks to you guys in particular), but I think you both might know a little bit too much about N2 as your answers often leave me confused or with more questions! :(

Here are some things I've written down since I started using N2:
  • Where are files, classes, items, parts etc. discussed in the basic intro guides?
  • Almost all guides, answers to posts are overcomplicated and difficult to follow.
  • Why does N2 not open in Visual Studio Express 2008 without lots of errors about projects etc? (I have to use Visual Studio 2008 - Pro on my work PC).
  • Why is SQL Server 2008 not compatible with N2?
  • Is there not a diagram that shows the class hierarchy etc so we can see what objects are available to us, and what/where they get properties methods etc from?
  • How to add different types of attributes to an already existing object builtin to N2?
  • How do the attributes etc relate to real world things such as drop down menus, text boxes? How do you know what they are (without the diagram mentioned before or lots of experience).
  • How do you override existing objects with your own flavour (ie creating a news object - replacing parent definitions).
  • How does existing functionality work - filtering in the News object for a start.
  • Should we be creating generic attributes for an object, then attaching them to the relevant object, or adding them to the object directly.
  • What is the best and proper way to disable functionality when overriding existing items (turn off a field).
  • How do you create Addons, file/folder structure, how and why they are used.. examples are too complicated or don't make sense.
  • How do you get data in and out the database? if you create an addon should you try and use N2s DB tables? or create your own?
  • How do you remove old versions of pages? what about when a site has been created, UAT'd and is ready to go live.. since the DB contains all the page structure, content etc etc. we need it. But not the testing things that may be in previous versions.
This might look like a rant, but I am having such a hard time with N2 and really want to get it going so I can start using it for our sites! I just feel some developers who aren't as genius as you guys might come to N2 and end up looking elsewhere because docs etc are sinking failboats. I am quite willing to help with re-writing docs to make them easier to understand or correct any gramatical errors I can see (sometimes thing's don't read correctly in documentation). But in order to help more, I need to be able to understand - then I can write straight away while it's fresh in my mind. Did the docs get created at the very end of N2's inception?

I hope someone in the forum can help!
Cheers
Pete

Apr 14, 2009 at 7:58 PM
I agree with your overall sentiment. It would be great if someone could weed through the discussion boards and come up with a good FAQ, walk-troughs on how features in the various demos work, and perhaps a few guides on implementing some advanced features/techniques. Documentation may be N2's achilles heel when it comes to adoption.
Apr 14, 2009 at 8:14 PM

It sounds like you are in the same boat I am - very interested in N2, but somewhat lost with how to do things.  I completely understand your frustration, because I feel it too.  When I am feeling particularly frustatated (and stupid), I think to myself that N2 is a gift.  I have it only from the good graces of libardo and other contributors like esteewhy.  Nobody is asking for money here.  We should all really be thankful for what we have an the opportunies it brings.

We should also be consoled becasue we can have the code and everything else we need to figure it out our problems.  We just need enough time and patience to get through it. I have found it extremely helpful to start with the C# example site and attempt to recode most the templates in a simpler (less generalized) way for the sake of understanding.  I am amazed at how much I have learned about N2 through this process, as well as C# asp.net programming in general.   I thought I was good - these guys are great!

There are clearly more newbies here than experts, so we obviously need to create more experts.  The only way to do that is to help each other more.  Now that I am beginning to understand N2 I will share what I have learned when I can.

To your questions:

  1. I haven't found the files exactly as they are on the main site, but similar files can be found throughout.  For me the folder structure is a bit unnatural so I keep the N2.Everything solution open and do searches.  Everyting is in the code.
  2. Agreed.  My take is that since N2 is meant for programmers, the idea is that the code is the real documentation.  The problem is that the code can be confusing becasuse of all of the abstraction and the lack of experience we newbies have with it.  I think what would help a great deal would be for an expert here to do a screen-cast of some common scenarios (getting set up, creating templates, add-ons, etc.)  I would pay money to supply the screen capture software (Camtasia) for libardo or esteewhy if they are willing.
  3. I do not get errors - what solution are you having problems with?
  4. hmm - no idea. What happens when you use the 2005 style?
  5. The object browser (Ctrl+Alt+J) in visual studio will provide a lot of answers
  6. I assume you mean  the templates (N2.Templates...) - I have been doing this by creating my own versions.
  7. Attributes provide additional "meaning" to classes, properties, etc.  When you see an attribute like [DefaultTemplate("Text")]  Search the code for DefaultTemplate.cs to see what it does.
  8. I don't know how to override existing items yet, or if we can.
  9. I would suggest to play with the examples.  It even took me a while to know to put \edit in the URL to get the the edit pages.  Regarding filtering the news items, there is some good stuff on the main site that will give you some clues  http://www.n2cms.com/Documentation/Manipulating%20content/Finding%20content.aspx
  10. I don't know
  11. I don't know
  12. I don't know - haven't tackled Addons yet
  13. I think the best answer here is to NOT think about the database, but rather object properties knowing that if you decorate your item properties i.e. [EditableTextBox...   and code the item properties correctly they will get persisted for you without worry.   GetDetail and SetDetail will take care of it all for us.
  14. I don't know this one either?

I hope some of this was useful.

 

Apr 15, 2009 at 9:11 AM
It sounds like you are in the same boat I am - very interested in N2, but somewhat lost with how to do things.  I completely understand your frustration, because I feel it too.  When I am feeling particularly frustatated (and stupid), I think to myself that N2 is a gift.  I have it only from the good graces of libardo and other contributors like esteewhy.  Nobody is asking for money here.  We should all really be thankful for what we have an the opportunies it brings

 - I totally understand your thoughts here; I apologise if the post came across as expecting these things. What I am trying to get at is that there needs to be more in order to get more people to adopt N2. The learning curve is very very steep.


We should also be consoled becasue we can have the code and everything else we need to figure it out our problems.  We just need enough time and patience to get through it. I have found it extremely helpful to start with the C# example site and attempt to recode most the templates in a simpler (less generalized) way for the sake of understanding.  I am amazed at how much I have learned about N2 through this process, as well as C# asp.net programming in general.   I thought I was good - these guys are great!

 - I've been trying something similar too, although probably with worse results :) I have created a new version of an existing item (a news item); and managed to crudely 'turn-off' an existing attribute. I've started to create an addon.. but apart from getting the icon onto the toolbar at the top in edit mode nothing to shout about there. I'm pretty new to using C# and ASP.net having come from a ColdFusion background (shudder).

There are clearly more newbies here than experts, so we obviously need to create more experts.  The only way to do that is to help each other more.  Now that I am beginning to understand N2 I will share what I have learned when I can.

 - Agreed, I also suggested in another post that some people may want to idle in a irc channel to make problem solving, chatting about ideas easier.. we can then create relevant posts or docs after a solution comes up in conversation?

To your questions:

  1. I haven't found the files exactly as they are on the main site, but similar files can be found throughout.  For me the folder structure is a bit unnatural so I keep the N2.Everything solution open and do searches.  Everyting is in the code.
  2. Agreed.  My take is that since N2 is meant for programmers, the idea is that the code is the real documentation.  The problem is that the code can be confusing becasuse of all of the abstraction and the lack of experience we newbies have with it.  I think what would help a great deal would be for an expert here to do a screen-cast of some common scenarios (getting set up, creating templates, add-ons, etc.)  I would pay money to supply the screen capture software (Camtasia) for libardo or esteewhy if they are willing. I would also be up for this!
  3. I do not get errors - what solution are you having problems with? I'll have to fire this up at home to get the errors again most of the N2 stuff I've done is for work (at work) :(
  4. hmm - no idea. What happens when you use the 2005 style? Not sure what you mean, is there some kind of compatibility mode in 2008?
  5. The object browser (Ctrl+Alt+J) in visual studio will provide a lot of answers I'll check this out! thanks
  6. I assume you mean  the templates (N2.Templates...) - I have been doing this by creating my own versions.
  7. Attributes provide additional "meaning" to classes, properties, etc.  When you see an attribute like [DefaultTemplate("Text")]  Search the code for DefaultTemplate.cs to see what it does.
  8. I don't know how to override existing items yet, or if we can. - I've managed to do this using [ReplacesParentDefinition] in the definition of my item then extended the item I wanted to replace (code below 1*)
  9. I would suggest to play with the examples.  It even took me a while to know to put \edit in the URL to get the the edit pages.  Regarding filtering the news items, there is some good stuff on the main site that will give you some clues  http://www.n2cms.com/Documentation/Manipulating%20content/Finding%20content.aspx - good call, I hadn't given enough thought to that when reading I suspect!
  10. I don't know
  11. I don't know So far I have added a getter/setter for the property and returned 0, this seems to have disabled it from rendering when creating new items (see below for code 2*)
  12. I don't know - haven't tackled Addons yet
  13. I think the best answer here is to NOT think about the database, but rather object properties knowing that if you decorate your item properties i.e. [EditableTextBox...   and code the item properties correctly they will get persisted for you without worry.   GetDetail and SetDetail will take care of it all for us.
  14. I don't know this one either?
I hope some of this was useful. Thanks for the post, thanks to jamestharpe also! I'm sure together we can crack this n2 nugget! :)


1*
[Definition("News Item", "MyNewsItem", "New 'News' Item", "Create a new 'News' item - this can represent an article.", 1)]
[Template( "~/Templates/UI/Views/NewsItem.aspx" )]
[ReplacesParentDefinition]
public class MyNews : N2.Templates.Items.News
{
// my code here
}


2*
// override the TitleLevel so it is not used.
public override int TitleLevel
{
get { return 0; }
set { }
}
I used the code in 2* inside my News Panel which I created to override the NewsList item in N2.
Apr 15, 2009 at 3:25 PM
I like the IRC channel idea - I'll get that set up.

 RE: #4 SQL2008 - I assume that the 2005 settings in web.config would work for 2008, but I haven't tried.  If not that, then I think a SQL2008 database could be put into compatability mode (right click on it, properties, options, compatability level...)  I don't have one in front of me, but I think its around that area.

Thanks for sharing the code snips. I didn't understand that we could override the existing definitions like that!







Apr 15, 2009 at 3:35 PM
I joined the #n2cms channel on efnet, dalnet and freenode (although my BNC has since died so I couldn't stay there).. I'll be back there as soon as I get it back up. See you there? :)

No problem with the code snippets, hope it helps.. I'm sure I'll get banned from this discussion group eventually for asking constantly.

Thanks
Pete
Coordinator
Apr 16, 2009 at 7:52 PM
Hi,

I'd like to plug a very interesting project Chris (mrshrinkray) has started over at the googlecode wiki. Judging from the site map this will be rather more approachable. I'd be happy to help filling out a FAQ given relevant questions.

Now to your question. I'll try to fill in the blanks.
  • Should we be creating generic attributes for an object, then attaching them to the relevant object, or adding them to the object directly.
    I don't understand what you mean. There are three major types of attributes that N2 looks for on the content items. If you fins these interfaces using reflector and follow attributes implementing them you can probably discover a great deal. Here's an old post about these attributes (beware it is rather old)
    • IEditable: controls which editing controls are added to the form and how to bind data from the content item
    • IDisplayable: controls how the property is displayed by the <n2:Display controls
    • IDefinitionRefiner: updates various aspects of the item definition that contains information about available editors, allowed children and more
  • What is the best and proper way to disable functionality when overriding existing items (turn off a field).
    Actually I havn't forseen this usage. There are some ways I can think of. E.g. overriding the property in a base class or modifying the item definition (N2.Context.Definitions.GetDefinition). You are actually doing some pretty advanced stuff. It could be easier and more understandable to modify the template project directly instead of finding nify way of bending it to your needs.
  • How do you create Addons, file/folder structure, how and why they are used.. examples are too complicated or don't make sense.
    Can you be more concrete? What is it that doesn't make sense? Would you like to see a simpler example of an addon?
  • How do you remove old versions of pages? what about when a site has been created, UAT'd and is ready to go live.. since the DB contains all the page structure, content etc etc. we need it. But not the testing things that may be in previous versions.
    You could write a database query that deletes versions (VersionOf != null). Another way is exporting the pages and importing them on the live environment. That clears old versions.
Thanks for posting good questions. This will help others in your situations. I must say that writing good documentation is rather hard. Probably harder than writing good code. I tend to forget steps along the road and forget what's needed to come across.
Apr 17, 2009 at 9:33 AM
Hey, the project looks cool! Thanks for the link.

With regards to the general attributes vs object ones, I guess I was just a little muddled up from the docs, on the N2cms.com website there is information about Custom Editors and also Composition. I think my head was spinning a little from going through it all.

As for overriding/disabling a property of an item you are trying to extend; I used the following method (in this case for a news panel)

       // override the TitleLevel so it is not used.
        public override int TitleLevel
        {
            get { return 0; }
            set { }
        }

(P.s. I would be interested to know how you guys get the highlighting on code pastes).

I've found out from esteewhy recently that Addons aren't quite how I imagined them as a newbie (I've posted this in reply to another question today - sorry).

Where should I create my functionality?

You should create each snippet/mini application in the ~/Addons folder.

~/Addons/MySnippet
-> Items
-> Plugins
-> UI
    -> Parts
    -> Views

Functionality that is linked can be packaged within the same parent folder:

~/Addons/GenericAddon/SubAddon1/
~/Addons/GenericAddon/SubAddon2/

~/Addons is used by convention, technically any folder name can be used, but if we all stick to Addons then namespaces make sense I guess. I think it's only the sub folders that matter (Items, UI etc).

I guess I just wanted an addon example that did basic things that real developers might want out of the box; I think the addon example I started looking at had obscure comments at the top about scheduled actions:

    /// To spice things up there is a scheduled action that finds all MyParts and
    /// updates their properties on a regular basis. Far-fetched? Yes.

I think a few of the posts kind of tie together, as a novice looking at creating an addon, I wanted to understand how the folders should be set, what conventions to follow. Then, how to add an icon to the toolbar and then how to actually do something inside the addon.. Listing of items for my Enquiry Manager was a start - How do I find objects in the database that I wouldn't want to appear anywhere on pages of the site (i.e. when a user fills out a 'contact us' form and submits. I want to create an Enquiry object and save it to the N2 database. Then get a list of these for the Enquiry Managers' listing display.On the more general level, I guess everyone would look for functionality they may have seen elsewhere.. Listing, Editing, Creating, Deleting objects.

Thanks for the information regarding versioning, I wasn't aware you could even export the pages - that sounds like the best idea. I don't want to fiddle with the N2 tables :)

Here are two other things I discovered about N2 yesterday (I will keep writing them down and hopefully they can be of use somewhere).

What represents the different between what can be a page or a part for an item?

bool IsPage { get; } inside the item.
Also, [AllowedZones] is used only for parts.

How do you create a link to a page within the N2 system?

N2.Web.Url.Parse(Link.To(URL HERE).Url)
You can also append parameters using:
.AppendQuery("term", qry)

e.g.

var qry = "test";
Response.Redirect(Url.Parse(Link.To(CurrentItem.LinkedPage).Url).AppendQuery("term", qry));

Where LinkedPage is a property of this item, but similar to that seen in a news container where you must link and object to a page.

P.P.S. What happens when you delete a page which other objects are linked to? I haven't tried it yet, but should/does N2 warn or prevent this? Or list the other elements which need to be removed to prevent errors in browsing the pages they exist on?



Coordinator
Apr 18, 2009 at 9:14 PM
Thanks for the feedback. I'll review the example and try to incorporate your suggestions.

Re: PPS. the links are cleared with no warnings. You can however see inbound links if you click all the way to a secondary page.
Apr 20, 2009 at 8:26 AM
Edited Apr 22, 2009 at 8:43 AM
Which links? :)

*EDIT* I just clicked on about the PPS thing, I'm sorry - stress seems to be making me unable to read properly.
:)
Coordinator
Apr 21, 2009 at 5:05 PM
Which links: "a page which other objects are linked to". When the linked page is removed the links are also removed.
Apr 22, 2009 at 8:33 AM
Oh got ya!

Strangely enough I added a [EditableLink] which I forced to be an event object; to an Event object. (such that events could be linked to eachother).

Say I had Event 1 and Event 2. If Event 1's related link is Event 2. Then I delete Event 2 from the calendar, upon editing Event 1 again the site url to the event is replaced with a file path:

/my-calendar/event2 becomes /Addons/Events/UI/Views/EventDisplay.aspx?page=52. I thought it would have been completely removed from Event 1.

Thanks for all the help!
Pete
Apr 23, 2009 at 2:19 PM
Is there a way to get N2 to remove the linked items from another item when the linked ones are deleted?


Coordinator
Apr 23, 2009 at 4:40 PM
You could subscribe to the N2.Context.Current.Persister events and do this.
Apr 24, 2009 at 10:59 AM
Hi Cristian,

I think I have found a bug with the help of esteewhy; it seems that when you delete an item which is referenced by another item - As long as the deleted item stays in the trash you do not get null returned when getting detail on the referenced item.. instead end up with the id#id. This leads to the problem I described above where the CMS edit field becomes: /my-calendar/event2 becomes /Addons/Events/UI/Views/EventDisplay.aspx?page=52

And outputting the related calendar event on the front end shows: 52#52 or similar depending on the ID of the item deleted to the trash.

Coordinator
Apr 24, 2009 at 10:27 PM
Right, items in the trash gets that url since they are not below a start page. Do you have any idea about how to handle restores from the trash if we were to remove the link? How can the link be restored in that case?
Apr 27, 2009 at 8:31 AM
Between two problems of: 1) having to recreate a link upon linked item restoration, and 2) having to invalidate a link to "recycled" item, i'd choose to tackle the latter first, as it's behavior seems to be more counter-intiutive for now. As to implementation, i guess invalid link clearing could be done inside ContentItem.GetDetail..
Coordinator
Apr 27, 2009 at 5:03 PM
This discussion has been copied to a work item. Click here to go to the work item and continue the discussion.