Difference between revisions of "Theme Management API"

From WebOS Internals
Jump to navigation Jump to search
(New page: == Theme Management API == This is an initial attempt at hashing out a secure, reliable Theme Management API. One of the main goals is to modify as little as we can of stock Palm files. ...)
 
(3)
 
(10 intermediate revisions by 3 users not shown)
Line 1: Line 1:
 
== Theme Management API ==
 
== Theme Management API ==
  
−
This is an initial attempt at hashing out a secure, reliable Theme Management API.  One of the main goals is to modify as little as we can of stock Palm files.  The first step is launcher icon replacement, which currently consists of overwriting/replacing icon.png files.
+
This is an initial attempt at hashing out a secure, reliable Theme Management API.  One of the main goals is to modify as little as we can of stock Palm files.   
 +
 +
# Create a new theme folder in /media/internal/.themes/thisTheme/
 +
# Create a new theme_config.json file in that folder which contains the following: 
 +
<pre>
 +
{
 +
  themename: Display name for theme
 +
  themedesc: quoted text of html for description of theme
 +
  app:
 +
  {
 +
    { com.palm.package1: { icon: relative/path/to/icon, cssFileName: relative/path/to/css },
 +
    { com.palm.package2: { icon: relative/path/to/icon }
 +
  },
  
−
=== Launcher Icons ===
+
  global:
 +
  {
 +
    cssFileName: relative/path/to/global/css
 +
  },
  
−
Instead of replacing icon.png files, the new theme API will use C service to call applicationManager/updateLaunchPointIcon {} service method.  This will change a launcher icon on the fly.
+
  wallpaper:
 +
  {
 +
    relative/path/to/background/file
 +
  }
 +
}
 +
</pre>
 +
#: paths are relative to the folder thisTheme.  
  
−
=== Overwrite CSS classes ===
+
# In your theme override stylesheets references to your images that override the default images should refer to /var/activetheme/... not to /media/internals/.theme/mytheme 
  
−
The next part of themeing will be overwriting CSS classes (of any app's stylesheet as well as Palm stock global stylesheets).  This will require a small patch to the framework to load a theme's CSS on top of any css being loaded.
+
# When your theme is chosen as the active theme, the system will symlink YOUR theme directory to /var/activetheme.
  
−
=== Theme Designer API ===
+
A one-time patch will be made against the framework files in /user/palm/framework which will add loading /var/activetheme/<orig_path>/XXX.css after each reference to <orig_path>/XXX.css and which will modify launcher so that when an application is loaded,  after appname.css is loaded, /var/activetheme/<app_dir>appname.css will be loaded -- matching CSS classes from those files will then automatically override the previous ones from the defaults.
  
−
In order to accomplish the icon and css replacements/overwrites, designers will put full paths to icon.png files for any app they want to replace the launch icon for inside of their theme directory.  They will also put full paths to any CSS file including a class they would like to overwrite in their theme directory. 
+
==Writing the theming css files==
  
−
Each theme will supply a THEME_DIR consisting of these elements, for example a tiny theme that replaced messaging launcher icon and changed the symbol popup selected character color from blue to red would consist of a theme directory we will name tmapi_example will be supplied with the following:
+
Theming css files must be "sparse" that is, they ONLY contain the classes being overridden not the entire global css file.  So, if for example you are overriding the "button_one" class in the phone application css,  your theme.css in /thisTheme would be /usr/palm/applications/phone/stylesheets/theme.css  and would contain ONE class
 +
<pre>
 +
{button_one:
 +
  background-image: /var/activetheme/yadayadayada/1.png
 +
}
 +
</pre>
 +
'''NOTE NOTE NOTE -- I know that's wrong -- I'm trying to get an Idea out here ok? '''
  
−
tmapi_example/usr/palm/applications/com.palm.app.messaging/icon.png
+
==Theme Management app==
−
tmapi_example/usr/palm/frameworks/mojo/submissions/200.72/stylesheets/global.css
+
* The theme management app iterates the folders in /media/internals/.themes and comes up with a list of themes folders in there.  
 +
* It then opens each of the themeinfo.json files and displays a list of the available themes.  
 +
* Upon tapping on a theme name a descriptive page (stolen from preware) comes up and displays the thumbnails and description and otherdata with an INSTALL button
 +
* Upon pressing install, the theme app's service symlinks /media/internal/.themes/chosenTheme to /var/activetheme
  
−
The global.css would contain only:
 
  
−
span.selected-char {
+
The Theme Management App also displays a command button which says something like: Get more themes.  which accesses the compatible themes feeds. Any theme-manager compatible feeds are displayed using code which we steal from Preware. 
−
  color: red;
 
−
}
 
  
 +
The theme manager app can call the preware file service to get the theme feeds information. 
  
−
"Installing" the theme would simply be moving the tmapi_example directory to /media/internal/.themes/
+
It does NOT download the feeds by default, only on request by pressing "get more themes."
  
−
.ipk files containing themes installing them /media/internal/.themes will be possible for easy preware installation of themes.
+
When a theme downloads, it extracts into /media/internal/.themes if the theme manager app attempts to open themedata.json and there isn't one, or it is corrupt, it informs the user that "this is not a theme manager compatible theme, sorry."  and calls the service to delete the folder created by the IPK.

Latest revision as of 20:00, 31 January 2010

Theme Management API

This is an initial attempt at hashing out a secure, reliable Theme Management API. One of the main goals is to modify as little as we can of stock Palm files.

  1. Create a new theme folder in /media/internal/.themes/thisTheme/
  2. Create a new theme_config.json file in that folder which contains the following:
{ 
  themename: Display name for theme
  themedesc: quoted text of html for description of theme 
  app:
  {
    { com.palm.package1: { icon: relative/path/to/icon, cssFileName: relative/path/to/css },
    { com.palm.package2: { icon: relative/path/to/icon }
  },

  global:
  {
    cssFileName: relative/path/to/global/css 
  },

  wallpaper:
  {
    relative/path/to/background/file
  }
}
  1. paths are relative to the folder thisTheme.
  1. In your theme override stylesheets references to your images that override the default images should refer to /var/activetheme/... not to /media/internals/.theme/mytheme
  1. When your theme is chosen as the active theme, the system will symlink YOUR theme directory to /var/activetheme.

A one-time patch will be made against the framework files in /user/palm/framework which will add loading /var/activetheme/<orig_path>/XXX.css after each reference to <orig_path>/XXX.css and which will modify launcher so that when an application is loaded, after appname.css is loaded, /var/activetheme/<app_dir>appname.css will be loaded -- matching CSS classes from those files will then automatically override the previous ones from the defaults.

Writing the theming css files

Theming css files must be "sparse" that is, they ONLY contain the classes being overridden not the entire global css file. So, if for example you are overriding the "button_one" class in the phone application css, your theme.css in /thisTheme would be /usr/palm/applications/phone/stylesheets/theme.css and would contain ONE class 

{button_one: 
   background-image: /var/activetheme/yadayadayada/1.png
}

NOTE NOTE NOTE -- I know that's wrong -- I'm trying to get an Idea out here ok?

Theme Management app

  • The theme management app iterates the folders in /media/internals/.themes and comes up with a list of themes folders in there.
  • It then opens each of the themeinfo.json files and displays a list of the available themes.
  • Upon tapping on a theme name a descriptive page (stolen from preware) comes up and displays the thumbnails and description and otherdata with an INSTALL button
  • Upon pressing install, the theme app's service symlinks /media/internal/.themes/chosenTheme to /var/activetheme


The Theme Management App also displays a command button which says something like: Get more themes. which accesses the compatible themes feeds. Any theme-manager compatible feeds are displayed using code which we steal from Preware.

The theme manager app can call the preware file service to get the theme feeds information.

It does NOT download the feeds by default, only on request by pressing "get more themes."

When a theme downloads, it extracts into /media/internal/.themes if the theme manager app attempts to open themedata.json and there isn't one, or it is corrupt, it informs the user that "this is not a theme manager compatible theme, sorry." and calls the service to delete the folder created by the IPK.

Retrieved from "http://wiki.webos-internals.org/index.php?title=Theme_Management_API&oldid=8802"