Differences between revisions 1 and 2
Revision 1 as of 2009-04-02 11:46:59
Size: 14106
Comment:
Revision 2 as of 2009-09-20 23:35:18
Size: 14106
Editor: localhost
Comment: converted to 1.6 markup
No differences found!

Title/Summary

Themes Saving

Currently the only way to create a new Roller theme is to work outside of Roller, editing text files, creating a theme.xml file and then placing resources into Roller's themes directory. This is very inconvenient and error-prone. To fix this develop the ability to save a blog's current theme as a Theme Archive File (TAF). A TAF should contain all theme templates, resources and the theme.xml file. Also provide the ability for Roller to load whatever TAFs that it finds in the themes directory.

Student

Tatyana Tokareva

Student e-mail

tat.tokareva@gmail.com

Student Major

Computer Science

Student Degree

undergraduate. I’m currently at the 5th year of education at the Computer Science Department of Voronezh State University, Russia

Student Graduation

June 2009

Organization

Apache Software Foundation

Assigned Mentor

David Johnson

Abstract

Themes functionality allows blog admins to customize view, components displaying and functionality of the blog pages and thus make their user experience more full, easy and enjoyable. One of the crucial moments in themes functionality is creation of new themes and exchanging themes with others. Right now the way of doing it is quite inconvenient – one has to work outside of Roller, editing text files, creating a theme.xml file and then placing resources into Roller's themes directories. There is a need to provide an easy mechanism for theme sharing between roller blog admins. So, the aim of the project is to create a functionality of saving current blog theme as one file (TAF, Theme Archive File) which will contain all theme templates, resources and theme.xml file. Opposite, when the user wants to install a theme from TAF he should just browse this file via user interface and it will be parsed automatically and properly installed into roller.

Detailed Description

The system should provide the following capabilities:

  • Ability to share custom themes by creating a TAF file, which will be constructed from the resources stored in the database and placed to the themes directory in Roller.
  • TAF (Theme Archive File) will consist of all templates, stylesheets, *.css and *.vm files and resources for certain theme and the theme.xml file.
  • Once placed in the themes directory, TAF will be automatically recognized and unpacked, so the new shared theme will be available.
  • The user who is selecting a theme will see the newly added theme in the list of basic themes and use it like other basic themes or use it as a basis for creating his own custom theme.
  • Optional functionality: themes loading from a third-party location.

Supposed development technologies

  • Programming language: Java
  • Framework: Java2EE, Spring, Struts
  • Technologies: JSP, JAXB

Tentative project architecture

One of the main points which need to be clarified is the TAF archive file structure. In order to make this approach more universal I suppose to create TAF in such a manner, so its unpacked content will represent a brand new scheme catalog, which while placed in the themes directory of Roller will represent a new publicly available theme. So, this file should represent the structure of directories, where resource and template files are normally stored. Sample structure is the following:

  • Sampletheme1
  • Images
  • Image.jpg
  • about.vm
  • day.vm
  • override.css
  • preview.jpg
  • theme.xml
  • weblog.vm
  • [additional custom theme files]

There will be functionality created to unpack this file and place to the themes directory automatically, but having this clear structure, a user will have the opportunity to look at these files and edit them manually if there’s need to do it.

Central part of the architecture is construction and parsing of TAF file. When blog admin creates a custom theme, modifying a basic one, and hits save button, all theme data is being saved to the database table “webpage”, where all files with attributes are represented. So, a module for constructing a TAF file from DB-stored data should be created. As the current blog theme state is stored in the roller database, the process of TAF constructing will include collecting data from the “webpage” table and constructing files with names corresponding the name “webpage.column”. At first, theme.xml file for the new theme should be created. It should contain stylesheets and template descriptions, resources path, as well as its own properties – id, name, author and preview-image.

Preview-image will be uploaded by theme creator, id and name properties will be defined by him too, and author property will be filled according to creator’s name.

Theme resources also must be copied into a new TAF. In order to achieve that, stylesheets need to be analyzed in order to expose all needed jpg, gif files, that should be added to a new theme.

As theme.xml file tags and file attributes which are stored in the “webpage” database table columns differ a bit, but store the same information, one of the complicated steps will be determining, what should be put into each of theme.xml tags. So, theme.xml consists of the following tags:

  • <id/> <name/> <author/> <preview-image path="" />

<stylesheet>

  • <name/> <description/> <link/> <templateLanguage/> <contentsFile/>

</stylesheet> <template action="weblog">

  • <name/> <description/> <link></link> <navbar/> <hidden/> <templateLanguage/> <contentType/> <contentsFile/>

</template>

<resource path="" />

As for the webpage table structure, it consists of the following columns:

  • Id
  • Name
  • Description
  • Link
  • Websiteid
  • Template
  • Updatetime
  • Hidden
  • Navbar
  • Templatelang
  • Decorator
  • Outputtype
  • Action

Name, description, link, template language properties of stylesheet will correspond fields in the table. Contents file will be filled according to name column.

Action, Name, description, link, navbar, hidden, templateLanguage properties of a template will be filled according to corresponding table fields. contentsFile property will be filled basing on the name and templateLanguage columns, contentsType property – based on “output type column”, if it is not null (text/html otherwise).

The resulting set of files will be packed into a single TAF archive as well as placed into the themes directory of the weblogger to become a standalone shared theme.

I suppose to alter some existing classes in order to implement theme saving and loading functionality. Here is the approximate list of updates:

  • Add marshal method to the ThemeMetaDataParser that will collect all the needed data from db using WeblogCustomTheme file class methods, take user-defined parameters (see above: author, theme id, etc.) and finally will produce a proper theme.xml.

  • Add exportTheme method to the ThemeManager, that will construct a SharedTheme object of resources, stored in the database. It will make all the needed output in order to construct files and will put resulting TAF into the themes directory. Theme loading is already provided by ThemeManagerImpl.

Another part of project will consist of UI modifications. On the Design-theme tab a button should be added for sharing theme. User also will be able to enter a theme name, id and upload a picture for theme preview. Maybe we can allow choosing files to be saved from a list of current custom theme templates. Pressing on “share” button launches processor, which creates an archive file and shares it in the themes directory (also, think of offering to save TAF on user’s local machine). The saved theme will be also automatically published in the themes directory, becoming available for other roller admins.

This will require some changes in UI classes (such as adding “share” method to the ThemeEdit uiaction) and updating of presentation elements such as JSP pages (alter ThemeEdit jsp in order to add elements needed for theme sharing etc.) As for optional functionality stated in the project description, Roller weblogger should know how to interact with other roller applications to provide them access to its themes and themes TAF files.

On the new blog creation page, there should be the ability to choose theme from combo box, which presents all themes installed into the roller, as usual and also some UI elements to allow download theme from the other roller weblogger application. It will allow user to specify a web url of the other roller installation and receive a list of its shared themes, choose on of them and install it in his own blog. This issue will include creation of a web service built-in to Roller which could process several types of requests. First one is request for list of all themes available, and another one is for providing a TAF file with a certain theme. Then the user could just point to the URL where the roller is deployed, then the list of themes will be shown and after that he can choose the certain theme and TAF file with a theme will be sent as a response.

Potentially we could use either Roller MetaWeblog API or Atom Publishing Protocol. But they are designed for quite different purpose. MetaWeblog API allows getting and setting the text and attributes of weblog posts and APP is designed specifically to manage weblog entries as well as attached media files, and does not fit our requirements. We can choose Roller Admin Atom Publishing Protocol that allows managing Roller users, weblog memberships and weblogs as well. I suppose to have two types of request:

  • GET /roller/roller-services/aapp/themes - to list all available themes.
  • GET /roller/roller-services/aapp/themes/themeName - to receive a particular theme. This will return all associated theme resources (encoded TAF file, actually).

In order to support this functionality a ThemeHandler class as well as ThemeEntry should be implemented. Atom protocol supports sending different types of content, including Base64-encoded binaries (and so does Roller Atom implementation), so this services suits our needs. More detailed architecture description of web service will be created after implementation of the main functionality.

Additional Information

'Project Plan'

  1. Examine the application code and structure and themes loading process. Create the detailed project architecture which will describe how the new themes functionality will fit into the existing structure.
  2. Make a research on the possibility of creating a built-in web service for exchanging TAF files with external resources.
  3. Release main functionality of themes saving and creating as well as built-in web service.
  4. Present achieved results, get feedback and look for some other improvements to be done.
  5. Test the system.
  6. Write documentation.

'Timeline'

  • Week 1-2
    • Initial planning of the project and research. Exploring roller codebase, make sure current roller version compiles under my system. Deliverable: Document of detailed description of the project.
  • Week 3-5
    • Implementing themes sharing functionality as well as testing. Deliverable: Source code for mid-term evaluation.
  • Week 6-7
    • Implementing themes sharing service functionality and testing modules.
  • Week 8-10
    • Refactor code based on community and mentor feedback - in this point, corrections would be done that make lack to the previous code. Add additional testing, excecute testing. Deliverable: Documentation on the project and source code for final evaluation.

Biography

I’m studying at the 5th grade of the Computer Science Department of the Voronezh State University, Russia. I will graduate in June 2009 and receive a Specialist diploma. My specialization is Programming and Informational Technologies. My GPA is 5.0. At the high school I specialized on Physics and Maths. During my education at the university I’ve studied different programming languages, like Delphi, C++, C#, PHP, Java, Ruby and used different frameworks. My score at the JavaSE Fundamentals test at the brainbench.com website is 4.5. For last 3 years I’ve been learning and using Java in most of my projects. I used JSP/JSF and Struts 2 for web applications as well as Spring framework. I have experience connected with Apache Axis library for work with web services and I’m sure that it will be helpful during the work on this project. I also have a team development experience and working experience gained during practical training at the university. It was software designing and developing for department’s administration daily needs. You can find detailed description of my previous projects and other experience in my resume [1].

Last year I’ve participated in the Google Summer of Code with Apache Software Foundation and worked on OpenID support for Roller blog server. It was a great experience for me, I got to know the application structure as well as gained knowledge in how the open source community is functioning. It has been some time since I’ve finished GSoC 2008 program, I’ve become more experienced and would like to implement my knowledge in Roller blog server project and contribute to it further.

This year I’m willing to take a bit more difficult task than the last year, by creating functionality of themes saving and sharing between blogs. While using Roller blog, I’ve noticed that themes functionality is not ideal and has areas to work on. Now there is a chance for me to improve this functionality and expand it even more with creation of a web service for 3rd party exchange.

I consider myself a strong candidate for this project with all necessary skills as well as community work experience. I’m confident in my ability of handling work on this project and complete it successfully!

[1] - http://docs.google.com/Doc?id=d8mj8np_0f2dtr2c9

SoC2009/TatyanaTokareva-Roller-ThemeSaveProposal (last edited 2009-09-20 23:35:18 by localhost)