This article explains animation profiles creation in Smart Countdown 2.5.x If you are using Smart Countdown 3 or Smart Countdown FX for WordPress you can still use this document as a reference for animation profiles document structure.
This section is related to Smart Countdown 2.5 only:
Smart Countdown is easily extensible with additional animation profiles. Each profile is stored in a separate XML file and should be installed into /modules/mod_smartcountdown/fx folder. The profiles that come with the module installation package are already there and you can use them as a guide for creating new ones.
More profiles (free and paid) are also available. You are absolutely not obliged to purchase add-ons to extend module's features. This document explains how to create profiles on your own, from scratch or editting the installed ones. That said, still if you like to save time and/or do not have nescessary CSS skills follow this link.
"Custom Profile" text area contents will have effect if "--- Custom ---" is selected from profiles list so that you can apply one profile that is not stored in XML file but saved directly to module's settings. Normally this will be a temporary profile, if you need it for future use it is recommended that you create a profile package and install it, otherwise it can be overriten when you select another setting from profiles list.
XML document structure for all versions:
Animation profiles are XML documents. The document structure is:
<config name="profile_name" description="profile_description"
<!-- optional, if profile needs to load images -->
<style name="height" unit="[|px|em]" value="some_value" scalable="[0|1]" />
<style name="width" unit="[|px|em]" value="some_value" scalable="[0|1]" />
<!-- more styles -->
<group duration="duration_in_ms" transition="transition_type" unit="[%|px]">
<!-- one or more elements -->
<!-- more groups if needed -->
<group duration="duration_in_ms" transition="transition_type">
<!-- one or more elements -->
<!-- more groups if needed -->
<!-- more digits with specific scope(s) if needed -->
Profile name and description are displayed in module configuration screen in backend when a profile is selected from the lost and do not affect the program's functions, so these attributes are not required but recommended as they may contain information about the styles used for animation thus helping the site administrator to configure the module properly.
Images folder attribute is obligatory if current animation has to load images. It should contain a path to the folder with images starting from Joomla root. Preinstalled profiles save their images in module's "images" subfolder, sol the path looks as "/modules/mod_smartcountdown/images/profile_name/". One or more profiles may use the same images folder.
A digit section with scope="*" is obligatory. It holds the default animation settings for all counter digits. If your design requires different animations for some digit(s) you can add one or more digit elements with scopes defined as comma-separated list of digit places from 0 to 6. These scope values stand for digits from seconds-low to days-low and will override default settings defined in "*" digit. All higher days digits must share the same settings as the lowest day digit, so digit scopes greater than 6 are ignored.
Styles section is obligatory for all digit elements. At least two styles are required: height and width and must have absolute values in pixels or em (if font-size style is also defined for this digit). You can add more styles including margins, background, etc. These styles will be applied to the digits in scope only. Note that module configuration also has "digits style(s)" field but those are applied to the container div (digits are children of this container in DOM), so that styles defined in profile take priority over module configuration settings (CSS naturas behavior). You should consider which additional styles to set in your profile, with more detailed styles you get a ready to use configuration with minimum settings required but you lose the control of these styles in "digits style(s)" module setting.
Modes section is obligatory and must contain two mode elements (name="down" and name="up"). One of the modules features is that count-up and count-down counter modes may have different animations (it is widely used in all sliding and folding animations - the movement direction changes with counter mode). So "down" and "up" sections are practically independent and may even have different number of groups and elements inside!
At least one group section is required for each mode. When animation starts all elements inside the first group start their transitions at the same time and run parallel. If you define more groups the elements from each group that follows start transitions after the preceding group's animation is finished (thus creating chain effect). Each group may have individual attributes: duration - transition duration in ms, transition - transition FX style (see Mootools FX.Transitions) and unit type used for styles calculation during animation. By default unit = "%" but "px" is also valid (still not recommended because this make the digit not scalable). Only duration attribute is obligatory.
Each group must contain at least one element section. Elements make the visual presentation of a digit. Element section has the following structure:
<!-- optional if element content_type!=txt -->
filename_base="image file name"
filename_ext="image file extension">
Tag attribute is quite self-explanatory. Smart Countdown 2.x supports div and img element tags.
Content_type is the type of content the element refers to. It is possible to use elements of different types in one digit.
- txt - text (usually a digit character) inside a div. Animation for this type of elements may include moving the div into/out from digit wrapper div, creating sliding effects. Txt type also suits good for opacity (morph) effects.
- img - an image that forms (a part of) the digit. Images are scaled automatically when their dimensions change, so you get much more possibilities for animations - flipping, folding, growing and shrinking effects (in addition to slides). You may want to have 2 sets of images for the same part of the digit - one with transparent background and another opaque - it is important for some animation designs.
- uni-img - a special type of image that is unique for all digit values. Normally it will be a decoration or background element that should be animated.
- static-bg - like uni-img, but without animation, normally a background or watermark image. This type of elements do not participate in animation, in fact they are rendered only once when the counteritself is rendered.
Value_type is the role that the element plays in animation logic. The animation is always a transition from one digit value to another and happens each time counter value changes.
Each element (except uni-img, that has only 1) must have 10 variants, one for each value from 0 to 9. At least two variants are needed for transition - one that is displayed before the transition starts and another - at the end of transition. On the next counter tick (and next animation cycle) the new current element must be positioned and look exactly as the resulting element from the previous step, so it becomes "displayed before the transition" for the next cycle, etc.
- "prev" value_type means that an element acts like current (before transition).
- "next" value_type means that an element will come into view as a result of transition (after transition ends)
- "pre-prev" and "post-next" are required for those profiles only where more that one value has to be (partially) visible when animation starts. They act as "prev" and "next" relatively to native "prev" and "next" elements.
Just review built-in animation profiles as samples. Note that the order of elements in a group is important in some cases (they are displayed in the order they are declared).
Styles section defines element's styles at the moment just before the animation starts. Any appropriate CSS rule(s) may be used in form of
each style as a separate XML element. You have to explicitly set unit value (%,px) when you declare styles.
Tweens are the heart of animation - they define what CSS styles of an element change and 'from' and 'to' values.
each style as a separate XML element. You should not explicitly set unit value (%,px) when you declare tween styles. The unit is set as an attribute of the group.
Filename_base is a string that images filenames start with. Current digit value (0 to 9) will be appended to this string followed by filename_ext resulting in a valid image filename. You module images/images_foldername/ subdirectory must contain 10 files named as filename_baseX.EXT where X is from 0 to 9 and EXT is filename_ext.
Style properties that are listed in styles section but not listed in tweens section are applied during the whole animation. For the elements that do not require animation you may leave tweens section empty or even omit it.
As soon as you are happy with your recently created profile do not forget to save it (copy/paset) someware on you desktop or create a profile packadge.
A profile package is a ZIP archive that can be installed via standard "Extension Manager" in Joomla backend just like any other extension. This archive must contain only the files that are specific for the animation profile(s) that you want to add to an existing Smart Countdown Pro installation.
The structure of the profile installation file should be:
name_of_profile.xml - manifest file - must contain same extension (name - MOD_SMARTCOUNTDOWN, method="upgrade", description, author, date etc. is up to you but keep in mind that these settings will override the existing ones and change how module's information is presented in Extension Manager) data as mod_smartcdpro.xml. This ensures that the profile package you install will only upgrade the existing module not creating a new one. For the rest of the XML file you have to include <files>...</files> section only. YOUR PROFILE MANIFEST FILENAME MUST BE UNIQUE! If you set "mod_smartcountdown.xml" as your custom profile name you will have to reinstall the module to be able to configurate it!
It should look like:
index.html - empty html file as in any joomla subfolder
/fx subfolder must contain one or more XML documents - one per the profile installed. The name of each file will appear in profiles selection list in module settings with '_' symbols replaced by spaces.
/images/profile_name subfolder is only needed if your profile uses images. If it is the case your profile xml file must state profile_name subfolder in images_folder="/modules/mod_smartcountdown/images/profile_name_subfolder/" for each digit scope.
The contents of this folder in your packadge depends on the type of image(s) used. If you need static background or "uni-img" one image is used for all digit values so you place it in this folder and reference its filename and extension in element's filename_base and filename_ext attributes. If some elements use "img" type (as of all image-based profiles) you have to place 10 versions of an image per each unique "filename_base" attribute used. These files should be named as filename_baseX.filename_ext where X is a number from 0 to 9. For example myimage0.png, myimage1.png ... myimage9.png. The right image to display will be selected on the fly when the counter value changes.
Make sure that you include an empty index.html file in each directory of your profile package.
You may review preinsalled profiles or purchase more profiles will advanced features and use them as a starting point in developing your own anumations.