206 lines
10 KiB
Plaintext
Executable File
206 lines
10 KiB
Plaintext
Executable File
This is a general todo list for the remaining items for the Theme application
|
|
-----------------------------------------------------------------------------
|
|
|
|
|
|
1. Make sure everything in the README is taking care of
|
|
2. Use manifest files
|
|
a. when validating files in ThemeValidationPanel
|
|
b. when creating the zip file for all styles
|
|
c. when copying the default styles in to a new theme
|
|
d. anywhere else I may have forgotten
|
|
3. clean up all of the TODO comments in the code
|
|
4. check in the "correct" stylesheet-paths file
|
|
5. figure out how to make the xsl stylesheets be able to properly import
|
|
sheets that are not available...for instance, right now, the
|
|
stylesheet-paths contains ccm-ldn-theme and ROOT but that means we get an
|
|
error when we try to use ccm-ldn-atoz which is not present in the paths file
|
|
|
|
Documentation:
|
|
--------------
|
|
Summary:
|
|
The Themes application provides an easy way for designers to be able to
|
|
upload and apply xsl stylesheets to a running web server without having
|
|
to recompile anything. The application works by allowing users to place
|
|
files in a designated directory that is recognized by the server. The
|
|
user is then able to preview what these files will look like on a live running
|
|
server before allowing other users to see the changes. This provides
|
|
designers with the ability to test out different styles without changing
|
|
the look and feel of the entire site. Once a designer is happy with
|
|
the changes, they can publish the themes and make them live which will
|
|
then change attributes anywhere the new stylesheets are used.
|
|
|
|
The Themes application is integrated with the Subsite application and
|
|
allows administrators to select a different theme for each subsite when
|
|
desired.
|
|
|
|
|
|
Configuration:
|
|
The Themes application has 5 configuration parameters.
|
|
|
|
The first one, com.arsdigita.london.theme.ThemeConfig.file_extensions,
|
|
allows the user to provide a list of file extensions that are consided
|
|
"styling" files. Specifically, when the user requests to download all
|
|
styling files in the system, the provided zip will only contain files with
|
|
extensions in the list. By default, the value of this is
|
|
|
|
jpeg jpg gif xsl css js png
|
|
|
|
|
|
The other 4 parameters deal with background threads that sync files when
|
|
in a multi-JVM configuration. They are
|
|
com.arsdigita.london.theme.ThemeConfig.theme_dev_file_watch_startup_delay
|
|
com.arsdigita.london.theme.ThemeConfig.theme_dev_file_watch_poll_delay
|
|
com.arsdigita.london.theme.ThemeConfig.theme_pub_file_watch_startup_delay
|
|
com.arsdigita.london.theme.ThemeConfig.theme_pub_file_watch_poll_delay
|
|
|
|
The *theme_dev_file_* parameters manage the background thread that is
|
|
responsible for syncing development files used by designers while
|
|
the *theme_pub_file_* parameters manage the backgroud thread that is
|
|
responsible for syncing published theme files so that all of the servers
|
|
are able to use the same look and feel.
|
|
|
|
The *_startup_delay parameters indicate how long the thread should wait
|
|
after the server starts until it runs for the first time. If you are
|
|
running on a single JVM or do not want the threads to run at all, you
|
|
can set these parameters to 0. The *_poll_delay parameters indicate how
|
|
long the thread should sleep before running again.
|
|
|
|
All parameters are expressed in seconds.
|
|
|
|
|
|
--Installation:
|
|
Installation for this application is similar to other applications
|
|
built on top of the WAF. When built, it typically deploys itself to
|
|
the /webapps/ccm-ldn-theme/ directory. It is important that the code
|
|
is deployed in a directory rather than a JAR file. If it is not deployed
|
|
as a directory then it will know know which directory to scan for
|
|
updates by designers.
|
|
|
|
When the application is first installed, the loader runs and mounts
|
|
itself at the <server-prefix>/theme/ and is only accessible to site
|
|
wide administrators.
|
|
|
|
One of the main pieces of the application is to allow designers to
|
|
be able to directly upload files to the application through a
|
|
mechanism that they choose. So, systems administrators should open
|
|
up the below directory for write by their favorite program (e.g. FTP
|
|
or SCP).
|
|
<root to servlet context>/webapps/[context]/themes/devel-themedir/
|
|
|
|
In addition, since the threads that synchronize the directories between
|
|
multiple servers use their own timestamps to determine the age of files
|
|
it is important to try to keep the various machines running with similar
|
|
times on their system clocks.
|
|
|
|
|
|
Using the "Themes" Application:
|
|
The themes application has one main page that can be accessed by any
|
|
site wide administrator at <server-prefix>/theme/.
|
|
|
|
When first viewing the page, the two options available are to
|
|
create a new theme or to "Download default base styles".
|
|
The link to download the base styles provides the user with zip file that
|
|
contains all files used by the system that have an extension that appears
|
|
in the list set during the configuration process.
|
|
|
|
Creating a Theme:
|
|
The link "Create New Theme" provides a form allow the user to
|
|
specify a Title, Description, and URL. The Title is used when
|
|
listing the themes in the user interface and is an easy way to
|
|
identify them. The Description currently is not used.
|
|
The URL is the name of the folder that is created in the
|
|
file system and must obviously be unique. Also, the URL is restricted
|
|
to [0-9,a-z,A-Z,-,_]
|
|
|
|
When a new "theme" is created, the application creates the directory
|
|
corresponding to the url under the directory
|
|
<root to servlet context>/webapps/[context]/themes/devel-themedir/<new theme url>.
|
|
It copies the contents of the default themes directory
|
|
(<root to servlet context>/webapps/[context]/themes/devel-themedir/default/)
|
|
to this newly created directory directory.
|
|
|
|
Once the theme is created, designers and upload and download the theme files,
|
|
changing them to meet their goals. When they are ready to test the new
|
|
stylesheets, they can select the theme from the panel on the left to
|
|
manage the existing theme.
|
|
|
|
|
|
Managing an Existing Theme:
|
|
After a theme is created, administrators are able to view properties
|
|
about them theme by selecting it from the list on the left.
|
|
The "details" page for the theme lists the basic properties, including
|
|
the date the themes were last published and the user that last
|
|
published the theme. If the theme has never been published, those
|
|
values will indicate that state. The page also lists all of the files
|
|
that are in the theme as well as links to operate on the theme.
|
|
|
|
+ The "Edit Theme" link allows the user to edit the basic property.
|
|
Changing the URL will cause the system to move the directory on the
|
|
file system.
|
|
|
|
+ The "Download Development Theme Files" is a tar of the development directory
|
|
(<root to servlet context>/webapps/[context]/themes/devel-themedir/<theme url here>)
|
|
rooted at the theme url.
|
|
|
|
+ If the item has been published, the "Download Published Theme Files"
|
|
will give you a zip of the published files
|
|
(<root to servlet context>/webapps/[context]/themes/published-themedir/<theme url here>)
|
|
rooted at the theme url.
|
|
|
|
+ The "Validate Theme" allows the system to check all of the xsl stylesheets
|
|
that have been uploaded to ensure that they compile and are able to import
|
|
all referenced files. If the validation fails, the user is shown the
|
|
error message so that they can easily fix the problem.
|
|
|
|
+ Clicking on the "validate and preview theme" link allows designers
|
|
to see what the new look feels like without applying the theme to the
|
|
entire site. Rather, it validates the theme, and assuming everything
|
|
checks out, will take you to <server-prefix>/theme/<theme url
|
|
here>/ccm/register/. If you follow the links, you can see what the
|
|
system will look like using your theme. This pulls the files from the
|
|
/themes-dev/<theme url here> directory. If there is a particular page
|
|
that a user wants to see in preview mode, the user can just add
|
|
"/theme/<theme url here>/ as a prefix to the actual url. So, to see
|
|
"/ccm/content-center/" with the new look, they can use "/theme/<theme
|
|
url here>/ccm/content-center". If the files do not pass validation
|
|
then the user is shown the validation results and must fix any errors
|
|
before the preview link will work. If the user does try to preview
|
|
a page that runs in to an XSL error that was not caught by the validation,
|
|
the page still displays the user friendly error message so that the
|
|
designer can easily fix the error.
|
|
|
|
+ The "publish theme" link copies the
|
|
<root to servlet context>/webapps/[context]/themes/devel-themedir/<theme_url>
|
|
directory to
|
|
<root to servlet context>/webapps/[context]/themes/published-themedir/<theme_url>,
|
|
inserts all of the files in the database, and places the themes in the
|
|
"Subsite" list (mentioned below). Placing the files in the database allows
|
|
for simple system backup because no critical files are stored on the
|
|
file system. The database also allows for multiple JVMs to share the
|
|
same file even though it was only uploaded to a single server. As with
|
|
"preview", the theme cannot be published until all of the files pass the
|
|
validation step. If the files do not pass validation then the errors are
|
|
displayed and must be fixed before the theme can be published.
|
|
|
|
|
|
If a designer is somehow able to publish a file that does not compile
|
|
and thus makes it impossible to view any page because of xsl errors,
|
|
there is a jsp page that will allow you to revert back to the default
|
|
theme. Any site administrator can access the page by going to
|
|
<server-prefix>/theme/undoTheme.jsp.
|
|
|
|
Using Themes with Subsites:
|
|
One of the main reasons for allowing themes is to be able to allow
|
|
different subsites to have completely different feels. When an
|
|
administrator creates a subsite they have an option to select an "XSLT
|
|
Directory" from a select box or by typing it in to a text box. The
|
|
select box contains "Site Wide Default", "Other (type in box below)"
|
|
as well as a list of all published themes. If anything other than the
|
|
"Other" is selected, the "XSLT Directory (other)" box must be left
|
|
empty. If "Other" is selected then it must have a value. To select a
|
|
"theme", simply select the theme title from the drop down and use the
|
|
rest of the subsite application like before. If you select a theme,
|
|
the application looks in the "themes-prod" directory for the
|
|
stylesheets before falling back on the default.
|
|
|