Notes 8.5 DominoBlog.ntf - The Missing Using Document

Tripp Black  June 22 2010 01:15:32 PM

In the last few days, we implemented the Domino Blog that comes with Notes/Domino 7, 8, and 8.5. This is the first time, because we already had blogs with and without comments for years. We just called them discussion rooms and journals in our applications. For any new blog for clients, we used the Blogsphere template on OpenNTF. However, this past week, I finally made time to create my (this blog) and Nicki started wearing a new hat and and needed another separate blog/journal. We decided to try the out-of-the-box Blog template that came with Lotus Domino.

For the first 5 minutes it was great, we pasted in a blog posting. We set up some links. Added categories.

Then went to the web to look for them. We found no categories, no links, and only tags with the standard yellow bar header at the top. We looked in the Using document (nothing there), we did a quick Wiki search which returned nothing - we didn't yet know we needed to search for specific phrases. So I proceeded to reverse engineer ...

Here we'd like to document our mistakes due to poor documentation:
I. Customizing the "Look" and header.
I found that global.css was appended to the default.css in the stylesheets folder a secondary css, Seeing that the global.css was a document, and we have the 8.5 Designer, we decided to hack/update the default.css with our customizations to make both blogs look like us.

Result:
What we should have done for what the original authors intended was to simply override in global.css. I'm not much on this as a purist, but it would have made some other things later easier had we known this was the paradigm.

II. Updating the Sidebars.
Luckily we figured out the Block templates make up a page and correctly assumed to properly adjust the layout you should use the existing block templates templates. Specifically, there are two for the left and right templates. (They are under the configuration/advanced options for the blog.)

We clicked the option in the configuration document to do categories over tags. That did not display categories instead - this is what we wanted for Nicki's blog. In fact it did nothing useful.

Mistake:
We ended up creating a manual list of her categories and using the URL to restrict to a category.

Result:
However, as new blog categories change often, this quickly became too painful for those used to Lotus Notes automation. That's when I was doing a search on tags and categories and stumbled on the Domino Wiki post on DX Tags. That lead me to Steve's blogs and the light bulb came on just I was about to just say we go back to Blogsphere or just update our own applications journal component to do comments, and bring it up-to-date to the current re-inventing of the wheel.

III. The List of what we should have done...

1. Make all overrides in "look" formatting in global.css.
a. Option 1: Do it as a document. Even though you lose the ability to edit in-line. It's a nice clean way to do an override and you don't have to remember which lines of the existing default.css are the mods.
b. If you like the color coding and formatting in Designer, ignore the document and create a stylesheet with the same name and hack the template to point there instead.
(If  I was starting over, I'd do this route.)

2. Before you starting customizing the layout of the side tables, you need to learn the paradigm.
Start with these two posts:

Steve's blog:
Steve appears to be one of the original authors. Here he defends that his template is not difficult to use, but doesn't quite get that is very difficult because you just "get" his paradigm from looking at a cluttered configuration document and basic user help on creating a post in the Notes help file.
Get past the text and the links at the bottom are VERY helpful.
a. To get started, check the link to the Wiki article on themes and tags.
The top part of the page is useful if you don't already understood the paradigm.  Since you don't:

• First read only the Default CSS paragraph. The CSS in there is used by the Page templates (which are two global for light customization) and the Blog Templates.
• Next, in your new blog application, go into the Advanced area and locate the HTML Block templates. Edit one and reformat the big blob adding so you can see the structure easily for all the DIVs in the blocks. Go back and forth between the default.css and particularly the left and right blocks to see how the CSS formats the Blocks.
• Next, go back and re-read the Wiki article and don't worry about the parts that go over your head right now,
• Did you notice those DX Tags in the left and right Block Templates. This is what sold me on the usefulness of the template (a.k.a. saved me from dumping it). Take a look at this list of the DX tags as a view and as a document in the Wiki article hidden under Attachments. Yes, a bunch are poorly documented that aren't completely obvious and they aren't document if they are used with various fields on the configuration document (some are, we've found). So the best thing to do is add them in to one of the Blocks, open the browser, and see what displays.

b. The best way to describe this is by example.

Example 1:
Here is what we did to Nicki's blog to get the Categories working including a link to each as a RSS feed using the RSS feed image:

We created a new DIV in the "LeftSideBar" block template (Advanced --> HTML Templates --> Block Templates). After we reformatted the code with carriage returns and indents to easily see what's there, we tried one of DX Tags and added this code:

<div class="list">
 <h3>Categories</h3>
 <ul><$DXCategories$></ul>
</div>

However, just that puts a weird separate RSS text link as a second link after each category. That's cool, but not what the user expects. However, to fix it ended up being a piece of cake.
Open the Configuration document (Advanced --> Configuration --> Open the document). Now choose the tabs: Formatting --> Categories --> Basics.
In the RSS Link Text/HTML field, we entered:

<img src="/NICKI/nickiblog.nsf/feed.gif" alt="RSS">

It appears we could have even abstracted the hard-coding of Nicki's filepath using the DXURL tag. But we didn't even try.

Example 2:
Here is how we got the links to work:

We created a new DIV in the "RightSideBar" block template (Advanced --> HTML Templates --> Block Templates). After we reformatted the code to see, we added the following new DIV:

<div class="list">
<h3>Links</h3>
<ul id="list">
 <li class="page_item"><$DXLinks$></li>
</ul>
</div>

After that, the links, we had already created, just displayed.

Example 3:
After we saved this blog post, we noticed our HTML rendered in the browser instead of displaying as code. We tried < code > and < blockquote > (spaces removed), but they didn't work. Another quick Google search back onto Steve's blog found the little tag:

< htmlblock >
code goes here
< /htmlblock >
(spaces removed).  

We also could have used the insert action button.


c. After we got our layout, we just went through the CSS file and tweaking it for text colors, size, spacing, and other attributes of the various sections.

To figure out what to edit, you can scan through the source and basically play a headache game of concentration. Don't do that to yourself. It will take hours.
To quickly do this, use Firefox with the Web Developer and Firebug plugins in Firefox.  It makes it so simple:
Open your page in Firefox.
Right click on the text/object to update. Then choose "Inspect This Element". This will cause a pop-up window to come up from the bottom of the Firefox window.
The right side has the CSS. Any CSS overwritten has a strikethrough line.
So basically you just look for what's left on top, note the line number and either hack default.css or better yet add the same tag in global.css as an override tag with your new values.

IV. Summary:
We made it! As you can see, the DominoBlog.ntf template's real coolness/power are the block templates and the DXTags . If we had this page of documentation to start with, we would have saved hours of reverse engineering and trial-and-error.

Since the DXTag library's PDF document is lacking in examples, you still have trial and error figuring out how to use an individual tag, but our hope is that by passing along this "loose documentation", it will allow those that follow us to not give up and be able to more readily use one the templates that comes with the product.

Also there are other great templates. We have some on our free apps page. We also have custom ones which we can customize and sell as a consulting solution. In addition, there also great templates out there on OpenNTF including Blogsphere which I mentioned earlier, which we've deployed for several clients.

 

• Comments [0]