• Events

• LocalGroups

• Activities

• Teams

• KnowHow

• RecentChanges

Basic info

This Wiki page is about adding, modifying and archiving content on the SpreadTheWord pages (here written as STW).

The former STW page was a single .xhtml file for every language. In 2015 we decided to change the procedure because the files were too long to be maintained easily and simultaneously in many languages. The new system works with .xml files which are combined by XSLT scripts to a complete page similar to the FSFE's merchandise shop page. This makes translations and mass-edits quite simple.

Structure and important keywords

If you are a user you have to know following files: /contribute/spreadtheword.**.xhtml (for example spreadtheword.en.xhtml), /contribute/promotion-materials-archive.**.xhtml and the content of the directory /contribute/promoitems/.

Inventory files

In /contribute/promoitems/ you can find the files active-items.en.xml and archived-items.en.xml, which we call inventory files. In these files you can define which items are available on the STW and the promotion-materials-archive (here written as SWT-archive) page. An item can look like this:

   1 <item type="cat" id="cat-sticker" year="2015" order="1">
   2   <image imgsmall="/contribute/promopics/megaphone.png"/>
   3 </item>

• type defines what is being called category in this article. A category is for example a campaign or an activity. This is important because we don't want to list all promotion material in a looong list but we want to have a structure with different headlines. Normally you can just use one of the existing categories for a new promo item, except the case that this is a item for a whole new campaign or similar.

• id defines a unique identifying string for the item. Normally you should use category-type, for example "dfd-sticker". The id should be short and verbose at once, because you can use #id to link to the item directly.

• year defines the year of first production of an item. This is important for the archive as well as for our internal documentation.

• order is important if you want to order all items of a category in a specific way. Else it's believed to be ordered by the placement in the file.

• imgsmall should point to a thumbnail of the item. The maximum width of a thumbnail is believed to be 300px so don't make it larger to save bandwidth and disk space. Please place all thumbnails in /contribute/promopics/ for good overview.

Item files

The item files are located in /contribute/promoitems/ and should have the filename info-<id>.xml, so for example info-cat-sticker.xml. It does not matter if the item is used on the STW or STW-archive page. Please have a look at the file /contribute/promoitems/info-TEMPLATE.en.xml to see how an item file is structured.

You can leave certain fields (a field is for example <author>XYZ</author>) blank if you don't have the information or if you don't need it. On the page only fields with content (in this case XYZ) are displayed. Please beware that also blank lines may be interpreted as content.

As id in <info id=""> please use the same id that you have given to the item in the inventory files.

Please only add the plain content of the field, so for example "Name Surname" in between <author></author> and not "Author: Name Surname". The field description "Author: " and its respective translations are added automatically on the final page. You can find the translations in the files /tools/texts-**.xml starting with stw-, but please be careful with changes because they affect all items on STW and SWT-archive. Ask web@lists.fsfe.org for assistance if you're not completely sure.

STW and STW-archive files

In the .xhtml files (spreadtheword.**.xhtml and promotion-materials-archive.**.xhtml) the defined categories are called. For SWT we chose to categorize by type="", for STW-archive by year="". Normally you won't have to edit these files if you just want to add an item, because most of the items should already fit a category (type). However, here's how you do it:

Call category on STW

To call a category on the normal STW page, just add a new headline and the XSL-call:

   1 <h3 id="cat" class="left break">Headline of the category</h3>
   2 <!-- <p>Maybe some explanatory text about the campaign or acivity?</p> -->
   3 <dynamic-content type="cat"/>

Line1 is simply a headline. As its id just choose whatever you want. This is helpful to directly link to a category (URL#id) e.g. in a table of content. Line2 could be some text about the campaign or similar. It's commented out in this example. Line3 is the call of the category "cat". By this, all items in active-items.en.xml which have type="cat" as their attribute will be listed, ordered by order="xy". Of course, you have to do that in all available languages.

Call category on STW-archive

On the archive the items are not ordered by category but by year. Therefore we don't have to call the category but all single years. To call a year, put following in promotion-materials-archive.**.xhtml.

   1 <h3 class="left break">2015</h3>
   2 <dynamic-content year="2015"/>

In this case, all items in archived-items.en.xml which have year="2015" as their attribute are listed, again ordered by order="xy". Do this for all available language versions.

How to add a new promo item

In this chapter I assume you're familiar with the basic structure of the new STW pages. Therefore this is just a step-by-step guideline.

1. In /contribute/promoitems/, copy the file info-TEMPLATE.en.xml and fill out all fields you find there. Look at already existing items on the STW to get an idea how the fields' content should look like. You can use HTML code like <a href=""></a> between the fields for links. If you don't have information for a field, just leave it blank (no space, no linebreak!) and it won't appear.

   Give the item an unique id="" at the top of the file. Normally, just take the category (for example dfd) and the type (for example sticker or poster). In our example above it could be cat-sticker.

   The filename has to start with info- and should afterward be the same that the given id. End the filename with .<language>.xml, so for example info-cat-sticker.en.xml. Just copy this file and give it another language marker to translate it.

2. Now add the item to active-items.en.xml. The entry could look like this:

      1 <item type="cat" id="cat-sticker" year="2015" order="1">
      2   <image imgsmall="/contribute/promopics/megaphone.png"/>
      3 </item>
   

   As you see, you have to define type="" (mostly this will be the same as some other items), id="" (which is the same as the id you defined in the info--file), year="" (which is the year of first production) and order="" (which is the order of appearance in its category). Additionally you have to define imgsmall="" which directs to the thumbnail of the item. All thumbnails should be located in /contribute/promopics/.

3. If the category defined by type="" was already existent, you only have to wait for the next build to let it appear in all languages. Just ask for translations for the info- files. If its a new category, call the category on all STW .xhtml files:

      1 <h3 id="cat" class="left break">Headline of the category</h3>
      2 <!-- <p>Maybe some explanatory text about the campaign or acivity?</p> -->
      3 <dynamic-content type="cat"/>
   

How to archive a promo item

We archive item if they're not produced anymore or unavailable for a longer time. Don't archive them if they're just 2 weeks in printing process.

I assume the item already exists both as an info- file and in active-items.en.xml.

1. Move the item's lines from active-items.en.xml to archived-items.en.xml. Both type="" and year="" should normally stay the same. But because on STW-archive we order by year and not by category, you can change the order="" attribute. You won't have to edit the info--file unless something changed. The <printed></printed> field isn't shown on STW-archive since there's no printed stuff to order anymore.

2. If the year is already called on /contribute/promotion-materials-archive.**.xhtml you don't have to do anything more. If it's not the case (for example there're no 2015-items archived yet), call it in all available languages by

      1 <h3 class="left break">2015</h3>
      2 <dynamic-content year="2015"/>
   

   The table of content is created automatically, ordered by a) category and b) the order number.

Details for webmaster to edit the code

To change the order of appearance of the different XML fields on the final page, edit spreadtheword.xsl and/or promotion-materials-archive.xsl. In the STW XSLT, there's the defined call of the category, in STW-archive XSLT the call of the year and the template for the table of content.

If you have knowledge in XSLT it shouldn't be hard to understand it. Important may be the usage of the function fsfe-gettext which takes translations from /tools/texts-**.xml (this file may be splitted in several others in the future). All necessary translation strings begin with stw- so it should be easy to find or to add.