Wiki Weblog Customization

Release 0.1

Wiki / WebLog Customization

Purpose The purpose of this document is to descibe how to customize DocuShare Wiki and Weblog using Cascading Style Sheet (CSS).

Overview DocuShare web customization has been historically using Visual Definition Format (VDF) to change the look and feel for DocuShare. VDF customization generally apply to the entire site, with the capability to define specific conditions to apply single or a class of object when necessary. Developer also requries access to the DocuShare server to apply the customizations.

In DocuShare CPX, a new way to use CSS on Wiki and Weblog is introduced. This feature offers customization on individual Wiki and Weblog object, while eliminating the need to provide developer access to the server. The approach also separated the business logic on the VDF, while styling resides within VDF. DocuShare global css are located at, • DSHome\tomcat\webapps\\docushare_cpx.css • DSHome\tomcat\webapps\\docushare.css Developer can customize these css, which applied to the entire DocuShare site, and beware that changes in these css might be override by later release of DocuShare during upgrade. Let’s take a look how a browser works from requresting the Weblog to display of the Web Log, 1. User browser request to display Weblog-11 2. VDF digest the request

June 22, 2006

1

Wiki Weblog Customization

Release 0.1

3. VDF base on the, a. style of the Wiki, “clean”, “default”, or “custom”, and b. whether the Wiki / Weblog object has individual css 4. VDF generate the HTML response to the user and display the content of the Wiki

Themes There are 3 DocuShare themes available on each individual Wiki / Weblog,

Table 1: Theme Definition Theme Default

Definition

When to use?

• Use docushare.css and docushare_cpx.css as the style sheet for the given Wiki / Weblog object.

Display in standard DocuShare Theme with minimal CSS customization.

• CSS style in the CSS property on a Wiki / Blog object will override the style of the default theme. Clean

• Use docushare_cpx.css and without DocuShare top naigation bar, for the given Wiki / Weblog object.

Display Wiki / Weblog without general DocuShare Theme with minimal CSS customization.

• CSS style in the CSS property on a Wiki / Blog object will override the style of the default theme. Custom

• Do not use docushare_cpx.css, and display the HTML content without a stylesheet. • CSS style in the CSS property on a Wiki / Blog object will override the style of the default theme.

June 22, 2006

2

Developer wishes to start from scracth and define Wiki / Weblog display theme.

Wiki Weblog Customization

Release 0.1

Upon Wiki / Weblog creation, user will have the option to set the theme proeprty. User can also navigate to the Edit Properties of the object at a later time to modify the theme. Let’s create a Wiki and see how the Theme works, 1. Navigate to a DocuShare Collection / Workspace, and add a new Wiki, 2. Choose the Theme property to default.

3. Add an entry to the Wiki HomePage and then view the Wiki 4. Navigate to Services of the Wiki > Edit Properties, change the Theme value to Custom

DocuShare base on the theme setting, and the custom CSS field on the Wiki Object, and determine which css to be used. In the case of custom css value is empty, and the theme is set to custom, therefore no CSS is used and Wiki displayed in plain HTML format.

June 22, 2006

3

Wiki Weblog Customization

Release 0.1

Customization To customize Wiki page, follow a 2 steps process, 1. Identify the CSS Selector 2. Apply and Refresh CSS on the css property field

Identify CSS Selector Developer can use web browser view HTML source to find review the Wiki / Weblog HTML, then determine the selector that need to override. Existing utilties available on the Web, including Firefox DOM Inspector, IE Developer Toolbar or Firefox Colorzilla extension can assist developer to accurately determine the selector. Developer can first copy the entirie docushare_cpx.css from the tomcat docushare root, then use it as a template for all modifications. To identify the selector, 1. Launch Firefox DOM Inspector and highlight the section that intend to modify

June 22, 2006

4

Wiki Weblog Customization

Release 0.1

2. Then we identify the classname is wiki-text in this case. Note: Similiar mechanism can be use for IE Developer Toolbar. Apply and Refresh After identify the CSS selection, developer can then apply the customization on the individual Wiki Properties. 1. Navigate to edit properties of the Wiki Page 2. Input the corresponding CSS that wish to apply on the Wiki

3. Click Apply 4. Then refresh and open the Wiki Page.

June 22, 2006

5

Wiki Weblog Customization

Release 0.1

Storing and Reuse Styles Developer can customize their own CSS store it anywhere, including store in DocuShare, then use it with the Wiki / Weblog objects. The options are,

Table 2: Ways to Store CSS Store Location

Description

Strength

Weakness

DocuShare Root Directory

Store images and css at where DocuShare web server located, such as, DSHome\tomcat\webap ps\docushare

Easy to store

Developer need server access When upgrade is needed might need to re-apply the customization

DocuShare

Upload CSS and images into DocuShare Collection

Easy to maintain

When program in CSS, need to get the Document handle piror define the CSS

June 22, 2006

6

Wiki Weblog Customization

Release 0.1

Table 2: Ways to Store CSS Store Location External Location

Description

Strength

3rd party web server host somewhere accessible by the users

Independent of DocuShare

Weakness External links might not be always available to the users More difficult to troubleshoot problem

DocuShare recommend customer to stores their CSS either in DocuShare, or in the DocuShare tomcat directory. For example, developer develop a custom ctheme.css and cImage.jpg, 1. Upload cImage.jpg to DocuShare 2. Keep a record of the Document Handle after the upload, for example, Document-11 3. In the .css, refer the image URL, for example, 4. body {background-image: url(http://localhost:8080/docushare/dsweb/Get/Document-11/ bgdesert.jpg')

Troubleshoot and FAQ Q: When and how should I decide to use, default, clean, or custom theme? A: Use default theme when only 1 or 2 CSS field need to customize, use clean theme when you wish to display DocuShare theme, and use custom theme to generate your own style. Please refer to table 1 for more information.

Q: How to remove the breadcrumb box A: DocuShare breadcrumb box is using the class “webLogBreadcrumbs”, therefore set the CSS field to, .webLogBreadcrumbs{display:none} will remove the breadcrumb display from the Wiki / Weblog page.

Q: How to troubleshooting

CSS Issues?

A: Besides IE Developer Tool and Firefox DOM Inspector, Dreamweaver or TopStyle can further assitt

troubleshoot CSS issues. Please be cautious that IE and Firefox might behave differently and more testing would shown wether the style is valid for all browser.

Q: How can I choose to display different style for different browser, or for differet user agent? To display different style using CSS, for example, developer might define one for IE and another one for other browsers,

June 22, 2006

7

Wiki Weblog Customization

Release 0.1

width: 100px; _width:120px; /*I.E only -hidden from all other browsers */ Please refer to CSS Hacks and Filters for more information/

Q: How can I generate my own Selector name, such as DIV, SPAN, or classname on the Wiki Object? Unfortunately this is not recommended to change the selector name. Developer can modify VDFs that when necessary to generate such content in the Wiki.

Q: Can I customize to add my own custom theme in the Add or Edit Propeties Wiki / Weblog page? Unfortunately this is not supported in the currently release of DocuShare. This customization is intended to change in the future release.

Example Example 1 - Change Weblog to display a different background and change font style 1. Create a Weblog, then navigate to view the weblog page. 2. Using browser, view HTML source. Select all, copy. 3. Go to your favorite HTML editor. Open a new blank file. Paste. 4. Create a new directory to hold your files in for this exercise, say theme1. 5. Save this file as theme1_weblog.html. 6. Create a blank CSS document. (theme1.css) 7. Replace the reference to the docushare.css or docushare_cpx.css with theme1.css 8. Use a robust css editor to edit theme1.css. if it's in the same directory, your reference should be like this: 9. If you want to see the action icons, copy the images to your local working folder: For example, src="/docushare/images/large/action_properties.gif" navigate to DocuShare location and copy the images to the local/docushare folder. 10. This is optional: Move all the css in the header between the tags to your theme1.css file. You might just want to completely delete it and start from scratch. If you delete all the styles, just browse through the page in code or in a DreamWeaver WYSIWYG window, find out the ID or class of an element, and then go to your css file and reference it and write your rules for how you want it to look. Do this for all elements or make some page level styles etc.

June 22, 2006

8

Wiki Weblog Customization

Release 0.1

11. Start modifying your CSS! If any of your CSS requires images, you can put them into the same directory as your theme1.css file and your theme1.html file. 12. You will also need to style your weblog entry page as well. This will require you to go to a weblog entry page, view source, select all, and copy and paste it into another file and save that files as theme1_weblogEntry.html. Follow steps 7-11 to prepare and edit theme1_weblogEntry.html. You want to have this page also use the same theme1.css file. 13. optional - if you want to retain the styles that are already there and just modify them, When you get to step 10, paste all the styles into the bottom of the theme1.css file (don't overwrite your existing styles!). You will be pasting in some redundant styles -- delete all redundant styles and make a comment that says this is the section where the weblog Entry styles are. 14. Upload to DocuShare. First step is to upload all the images you used to docushare. Record their url references. 15. In the properties page of your weblog, select "custom" for your theme, and then copy and paste all your css from your theme1.css file into the styles textbox. 16. Image reference replacement. Everywhere where you referenced an image in your rules, you must update them with their new absolute docushare document reference in the newly pasted CSS text in the styles textbox. background:#edeeee url(breadcrumb_line.gif) 50% 100% repeat-x; becomes (for example): background:#edeeee url(http://serverxyz/dsweb/docushare/Get/Document-12/breadcrumb_line.gif) 50% 100% repeat-x;

Reference CSS: http://www.w3schools.com/css/ Firefox DOM Explorer: http://www.mozilla.org/projects/inspector/ Firefox Colorzilla: http://www.iosart.com/firefox/colorzilla/ Mozilla Developer Toolbar: https://addons.mozilla.org/firefox/60/ IE Developer Toolbar: http://www.microsoft.com/downloads/details.aspx?FamilyID=e59c3964-672d-4511bb3e-2d5e1db91038&displaylang=en CSS Hacks and Filter: http://centricle.com/ref/css/filters VDF Reference Guide: Available at DocuShar Help section when login as admin user.

June 22, 2006

9