Forum OpenACS Development: css style classes for the documentation project

Hi folks,

as the documentation in the openacs wiki grows (which is great) also the variety of layout concentions increases. For example, there are many pages where code or screen content is included, nearly always in a different style. The perceived quality of the documentation is related to the presentation style.

It would be great to develop for identified needs appropriate CSS classes and to develop a documentation guideline.

The 'stylist' plugin of xinha is well suited to apply the suggested CSS classes for the documentation, since it provides a panel with suggested styles. I have added to the xowiki.css some classes for coding, but this is not more than a first start.

See the panel on the right in the following screen-shot, where a file with code content is edited. The rendering of the code (box, bacground, monospace) are renderend merely due to the fact, that i have marked the program text and clicked in the panel on "Code Block" to apply it. Within the code block, italics are used for denoting comments, they are rendered green according to the CSS style rule.
http://media.wu-wien.ac.at/download/xowiki-doc/policy-edit.png

Here is the same page when viewed, where more properties of selva are inherited:
http://media.wu-wien.ac.at/download/xowiki-doc/policy-view.png

Here is another small example for editing some code, with the string class applied to render strings nicely.
http://media.wu-wien.ac.at/download/xowiki-doc/class-edit.png

Note, that since xinha is based on html+css, changing the css file will change both, the rendering in the editor as well as the rendering of the html file when it is viewed. This kind of "semantic" tagging makes it easy possible to use e.g. alternate skins...

In order to activate this functionality in your xowiki installation, add the following to your folder object:


set rich_text_spec {richtext(richtext),nospell,optional {
   label Content} {html {style {width: 100%}}} {
    options {editor xinha plugins {Stylist OacsFs} height 350px javascript {
    xinha_config.stylistLoadStylesheet('/xowiki/resources/xowiki.css',
     {'div.code' : 'Code Block'});
}}}}
 
set widget_specs [list *,text $rich_text_spec]


Note, that one has to be careful not to conflict with the wiki-markup (double braces, double brackets). Maybe we will need in the future a flag per page saying, what kind of substitutions are wanted...

-gustaf

i have acivated this a few days ago on openacs.org. This has the consequence that
- The styles from xowiki.css are rendered within xinha, and
- taht the available styles selectable from the displayed panel.

Certainly, the styles in xowiki.css should be extended...

Goto openacs.org/xowiki and edit an arbitrary page. You will see on the right-hand-side of the xinha editor a panel named "styles". This is rendered by the stylist...

Hope this helps
-gustaf neumann

What kind of content do you want to edit?
Do you get xinha at all?
What browser are you using?

Are you edit xowiki pages? if yes, there is no need to mess around with template::head::add_script at all.

if you are editing with plain ad_form, then it is not required either:
See example in https://openacs.org/api-doc/proc-view?proc=template%3a%3awidget%3a%3arichtext

Why have you started with template::head::add_script?

The easiest approach is to add the code-snippet into the folder object. Checkout section 7.3 and 7.4 at http://media.wu-wien.ac.at/download/xowiki-doc/#folder-object

The term "directory object" referes to the same thing as the term "folder object". See http://alice.wu-wien.ac.at:8000/xowiki-doc/#folder-object

I have replaced all occurances of "directory object" by "folder object" in the documentation above. The concept of the "folder object" comes from the very first versions of xowiki. Currently, the primary use-case is actually the javascrupt configuration. It is planned that future versions of xowiki will not require the folder object anymore.

What is the stylist toolbar? The rich_text_spec contains attribute/value pairs; one can include arbitrary javascript code there (see below for an example). There is no need to source javascript code. Put every javascript for the configuration of xinha there.

The definitions contained in the folder object are used for every page contained in this folder (i.e. for this xowiki instance). The definitions used for the folder object for the wiki on openacs.org are:

set rich_text_spec {richtext(richtext),nospell,optional {
   label Content} {htmlarea_p 1} {html {style {width: 100%}}} {
    options {editor xinha plugins {Stylist OacsFs} height 350px javascript {
    xinha_config.stylistLoadStylesheet('/xowiki/resources/xowiki.css',
     {'div.code' : 'Code Block'});
    xinha_config.stylistLoadStylesheet('/doc/openacs.css');
}}}}
set widget_specs [list *,text $rich_text_spec]

These definitions are passed via acs-templating to the HTML generated for the page. So, if you have added the information to the folder object, and you edit some ::xowiki::Page (a new one or an existing one), you will see the included javascript when you look at the source-code of the currently displayed HTML page.

What is the definition you are using? What do you see in the HTML page? Maybe, the answer to your "problem" is trivial: stylist shows in the panel only the applicable styles. Depending on the provided styles, the panel might be empty.

Will the Stylist panel display even if there are no 'applicable styles'?

yes

I am still struggling with the 'folder object' concept. I have created an ::xowiki::Object and inserted the rich_text_spec definition referenced above into the 'Content' box.

xowiki creates the folder object automatically for you. Look into your admin pages, you will find an ::xowiki::Object with the name "::SOMENUMBER" in your instance. SOMENUMBER stands here for the folder_id in the content repository. If you create an arbitrary ::xowiki::Object as you indicated in your last posting, it won't do anything.

Now, does that mean by simply saving this ::xowiki::Object I have 'enabled' the Stylist panel for this and other pages/objecs?

yes, if you update the folder object, the definition will be valid for editing all pages of this xowiki instance using xhinha. Note that ::xowiki::Object and ::xowiki::PlainPage don't use xinha, so there will be no stylist.

How do other pages/objects reference this content?

Every page of xowiki is saved in the content repository under a folder (which is as automatically created for every xowiki instance). Wery ::xowiki::Page knows its folder (normally the parent_id) and checks for its configuration the folder object.

Hope, this helps
-gustaf neumann