Introduction

This guide covers the steps required to set up your Awestruct generated project site on the JBoss Community infrastructure including configuration and deployment.

How to configure your Awestruct site?

There are a small number of configuration steps which need to be done in order to prepare your site to be deployed on the JBoss Community infrastructure. Because all project sites are required to have the common JBoss Community header menu and footer they need to be injected into your project site while Awestruct generates content. In order to make it happen, you must do following steps:

  1. Inside _ext/pipeline.rb please add this line to import of Remote Partial helper:

    In requires section:
                 require 'awestruct/extensions/remotePartial'

    In initialization section:
                 helper Awestruct::Extensions::RemotePartial 
    Note: The Remote Partial helper is available from version 0.2.15 of Awestruct.
  2. In your main layout HAML file, link to the CSS file:

                 %link{ :rel=>'stylesheet', :type=>'text/css', :href=>'http://static.jboss.org/theme/css/awestruct/jbossdefault_wrapper.css', :media=>'screen, projection' }
  3. You'll also need to import the javascript file to make top navigation active. If your page already uses jquery, it's worth linking this file after jquery imports.

                 %script{:type=>'text/javascript', :src=>'http://static.jboss.org/theme/js/tabzilla.js' }
  4. Just after your layout's body tag add the top navigation import:

                 = remotePartial('http://static.jboss.org/theme/includes/org_header_topNav.html')
  5. Before the closing of you layout's body tag, import the page footer:

                 = remotePartial('http://static.jboss.org/theme/includes/org_footer2.html')
  6. Optionally, you may be interested in linking also our additional CSS file which will provide you with a set of basic content styles. This CSS file may be useful if you are just starting your new site.

                %link{ :rel=>'stylesheet', :type=>'text/css', :href=>'http://static.jboss.org/theme/css/awestruct/jbossdefault_content.css', :media=>'screen, projection' } 

A very simple example of base layout that contains all mentioned changes can be downloaded here.

How to publish your site on JBoss Community infrastructure?

If you're doing this for the first time, you'll first need to ask Engineering Systems team to create you filemgmt.jboss.org account unless you already have one for storing documentation or downloads. Additonally, you'll need to ask for the configuration of your project domain to be served from your www_htdocs directory or an Apache rewrite rule if you wish to deploy under www.jboss.org/<project_name> URL.

Once completing these initial first time user steps, all you have to do is connect to filemgmt.jboss.org.

Connection example using sftp:

    sftp <project_name>@filemgmt.jboss.org

Once connected, navigate to your www_htdocs directory and upload your site. The site will be immediately visible after the upload.

How to get into the list of JBoss projects page

There is a so called project matrix page, where you can find a list with important links of the JBoss community projects. If you want your project to be in that list, you have two possibilities:

  1. Send a request to help@jboss.org. A page will be added into our content management system (Magnolia) and you will receive a link to it and the user credentials for your project, so you can modify its content.

    The documentation in Magnolia uses paragraphs to publish the content. Most of the projects have several paragraphs on each page with some content, however while you have all your documents in your infrastructure, this would duplicate your data and therefore it is not necessary. The only important paragraph is the project navigation. The project matrix searches for these paragraphs in Magnolia and reads the project data from them. 

    Assuming you requested the creation of the paragraph and we sent you a link to your administration page and your user credentials: Go to the link and find the project navigation paragraph  (it is the one, that looks like a menu and has "Overview, Community, User Groups, Events....). It will have a green button with text "Edit" that will open a dialog, where all important links can be entered (or changed by you in the future if necessary). *)
     
  2. In case you do not want to use the Magnolia CMS and you would rather manage your important links directly on your page we have a solution for you too. You must publish a property file on your site (it must be available without any authorization) and send a request to help@jboss.org with its URL. JBoss team will add the URL to Magnolia and your property file will be parsed once a day for the data. The content of this property dialog is here.

    Even if this approach seems easier, it has some drawbacks. The changes you do are applied once a day (instead of immediately as in the previous case). Also the plain text (the property file is the sort of the plain text) is more error prone than the dialog. And of course the property file must be available across the internet so you must maintain it in your infrastructure. .

(* Note: At this moment there is a small issue with styles. The button is nearly hidden under "Overview", but it is there.