Cocktail changelog

Cocktail changelog




  • The hash from files uploaded using cocktail.controllers.FileUpload was previously generated as a binary value. Now it is encoded as hex string. This makes it easier to use in many contexts. In particular, it solves some issues in the implementation of the synchronization mechanism in Woost/Diablo.

  • Changed the default value for the cocktail.html.Pager.button_style property to characters. Most sites ended up subclassing or modifying the view to achieve a similar effect, so it makes it sense to change the default behavior.


The main change in this release is the introduction of a caching framework, cocktail.caching.

  • Implemented a caching framework (cocktail.caching):

    • Documented, stable API
    • Support for multiple backends
    • Support for entry tagging, providing fine grained invalidation of cached entries
    • Replaces the custom cache in cocktail.html (the previous implementation was limited to in memory caching)
    • The existing cocktail.cache.Cache class is renamed to cocktail.cache.resourceloader.ResourceLoader, to avoid confusions
  • Support for subclassing When declaraing an event it is now possible to specify the subclass that it should instantiate to collect the parameters and context of the event invocation.

  • Improvements to the cocktail.memoryutils module:

    • cocktail.memoryutils.format_bytes() now supports units in base 2 and 10.
    • Added the cocktail.memoryutils.parse_bytes() function


The main features of this release include:

  • Support for translation inheritance
  • Support for grouping and processing scripts and stylesheets
  • Improvements and new additions to interactive controls (selectable and searchable containers)
  • Added the locale translation key, which provides the human readable name for a language or one of its variants. This key replaces the use of ISO language codes as translation keys.

  • The compiler of CML templates now ignores all text nodes consisting only of whitespace. Those nodes could introduce unwanted margins; the change gives template writers the freedom to indent and structure their code correctly without it influencing the layout in any way. Some elements that relied on whitespace to introduce a visual separation between them may appear welded together now. To fix it, use the margin CSS property, or add a white space character to the template using ${" "}.

  • Changed the HTML structure of the cocktail.html.CollectionView class.

  • Replaced cocktail's custom system for defining keyboard shortcuts with the standard accesskey HTML attribute.

  • Changed the name of the CSS class added by cocktail.html.Form to indicate the language of a field, from language to field_language.

  • Support translation inheritance across languages/locales, both for translation keys and translatable members.

    The following new elements have been added:

    • cocktail.translations.iter_language_chain()
    • cocktail.translations.descend_language_tree()
    • cocktail.translations.fallback_languages_context()
    • cocktail.translations.clear_fallback_languages()
    • cocktail.translations.set_fallback_languages()
    • cocktail.translations.add_fallback_language()
    • cocktail.schema.SchemaObject.get_source_locale()
    • cocktail.schema.SchemaObject.iter_derived_translations()
  • Changes to the behavior of the client side cocktail.selectable() function:

    • Changed the system used to manage the focusing of selected elements, to solve several bugs and navigation issues
    • Added a "non exclusive" mode. In this mode, selecting an element doesn't replace the active selection (so it behavies as if the control key was always selected). This is useful on check lists and similar controls.
    • Implemented the ctrl + a and ctrl + shift + a keyboard shortcuts (to select all elements or empty the selection, respectively)
    • Added a focusContent() method, to pass focus to the first visible and enabled interactive element
    • Added a selectEntries() method, to select multiple entries based on a selector
    • The clearSelection() method can now clear a subset of the active selection, based on a selector
    • Toggle a focused CSS class on selectable elements, to make it possible to change their appearence when any of their items is selected
  • Added the client side cocktail.searchable() function, to implement elements that can filter their entries based on a text query.

  • Changes to cocktail.html.CheckList:

    • Use cocktail.selectable() to implement the selection behavior for the control (benefitting from keyboard shortcuts and an improved API)
    • Add an entry CSS class for the elements containing the check box / label pairs
  • Added the cocktail.html.SearchableCheckList view.

  • Added the cocktail.html.Table.use_separate_selection_column property. It defaults to True, to preserve backwards compatibility. If disabled, the check boxes for tables with selectable rows are added as children of the first column, instead of generating a dedicated column of their own. This makes it easier to hide those checks so they can receive focus and be included in form submissions.

  • Schema adapters can now limit the languages to import / export

  • Added the cocktail.html.Form.redundant_translation_labels property. It defaults to True to preserve backwards compatibility. When disabled field labels are only rendered once per field.

  • Add CSS classes to the entries and links generated by cocktail.html.LinkSelector.

  • Validate and normalize cocktail.schema.PhoneNumber members.

  • Added the cocktail.stringutils.plain_text_to_html() function.

  • Support for per site grouping and processing of scripts and stylesheets. The following elements have been added:

    • cocktail.html.HTMLDocument.resource_sets
    • cocktail.html.ResourceRepositories
    • cocktail.html.ResourceSet
    • cocktail.html.ResourceAggregator
    • cocktail.html.ResourceBundle
    • cocktail.html.ScriptBundle
    • cocktail.html.StyleBundle
    • cocktail.html.EmbeddedResources
    • cocktail.html.ExcludedResources
  • Include a distribution of TinyMCE by default. Previously it had to be manually downloaded and included by each site.

  • Changes to cocktail.html.DropdownPanel:

    • Style changes
    • Restored the automatic focusing of the first available child when the panel is unfolded
  • Changed the way the scripted CSS class is added to theelement so it takes effect earlier. This can help prevent ugly visual rearrangement effects on javascript heavy pages.


  • Removed the cocktail.stringutils.clean_html() function and the cocktail.stringutils.HTMLCleaner class. No site used them so far, and the update to BeautifulSoup4 had broken them.

  • The containingDropdownExpanded and containingDropdownCollapsed events triggered by the cocktail.html.DropdownPanel class were terribly inefficient. Furthermore, event bubbling could cause handlers of these events to be triggered multiple times on a single expand / collapse operation.

    To fix this, these events have been replaced by the exposed and concealed events, which are only triggered on elements with an exposable CSS class.

  • Support for indexing cocktail.schema.Collection members. The following expressions have been added or modified to take advantage of this:

    • cocktail.schema.expressions.ContainsExpression
    • cocktail.schema.expressions.ContainsAnyExpression
    • cocktail.schema.expressions.ContainsAllExpression
    • cocktail.schema.expressions.LacksExpression
  • Added the cocktail.html.SplitSelector control.

  • Improved the client side cocktail.selectable() function to make it possible to add/remove items to the selectable container dynamically.

  • Added the cocktail.html.Clone class. This view fully replicates the rendering of another element, which can be useful in some cases (for example, to have a pager above and below a listing without defining it twice).

  • Added the locale_component and locale_component.X translation keys, to simplify the translation of locale names.


  • Removed the cocktail.schema.expressions.SearchExpression.partial_match property.

  • Removed cocktail.schema.expressions.GlobalSearchExpression, which had been obsolete for quite a while (use cocktail.schema.expressions.Search instead).

  • Changed the behavior of the cocktail.schema.SchemaObject.get_searchable_text() method. Until now it returned an iterator; from now on, it should return a string. Also, the protected cocktail.schema.SchemaObject._get_searchable_text() method exists no longer; instead, use the new cocktail.schema.TextExtractor class.

  • The client side cocktail.showDialog() function now attaches the dialog element to the page's root element, instead of attaching it directly to the element. This makes it easier to share styles between the page's main area and its dialogs.

  • Support multiple levels of grouping in cocktail.html.Selector, using the new SelectorGroup class. The cocktail.html.Selector.grouping option is still available, but it should return a tuple (representing each of the different grouping criteria, from more generic to more specific). Values that are not tuples will be treated as a single criteria (so "x" is the same as ("x",)).

    In practical terms, the only breach of backwards compatibility will be on grouping functions that already returned a tuple. Those should be modified to wrap their return values using a single position tuple.

  • The cocktail.html.List.items propery is now deprecated; use cocktail.html.List.value instead.

  • Added support for stemming on full text indexing / searches. See the new module cocktail.translations.words for details.

  • Added the cocktail.schema.HTML member type.

  • Added the overlay_base directive for CML templates.

  • Added the cocktail.schema.SearchHighlighter class, to higlight matching text in full text searches.

  • Added the client side cocktail.rootElement property.

  • The cocktail.html.TreeView class now adds an active CSS class to the active entry.

  • Added support to cocktail.html.ResourceAggregator for downloading remote resources. This behavior is disabled by default, and has to be enabled using the new cocktail.html.ResourceAggregator.download_remote_resources property.

  • Added the cocktail.html.MonthCalendar.get_cell() method.

  • Make the searchable.js file install a polyfill for the String.prototype.trim() method (required for Internet Explorer < 9).

  • Add a radio_entry CSS class to the entries generated by cocktail.html.RadioSelector controls.

  • Added the -generic_group translation suffix for schemas, to translate the anonymous group generated by members without an explicit group.

  • Added the cocktail.html.DrillDownSelector, to generate sequences of dropdown selectors based on a tree of options.

  • Implemented translation for instances of the datetime.time class.

  • Added the cocktail.html.MappingTable class.

  • Added the default_action parameter for the cocktail.controllers.handlerprofiler.handler_profiler CherryPy tool.

  • Changed the behavior of cocktail.instantiate() to make it possible to instantiate table rows and cells.


  • Extensive refactoring of the schema validation APIs:

    • The validation process now creates a separate instance of cocktail.schema.ValidationContext for each validated member. Previously, a single context was shared among all the members of the validated schema, using an internal stack to maintain a shared / overridable context across specific member validations. The new approach is cleaner and more flexible.
    • Added the cocktail.schema.Member.validation_parameters property, to customize the context passed to the validation process of the member.
    • Added the cocktail.schema.Member.validating event. This allows members to dynamically alter the validation process.
    • The cocktail.schema.ValidationContext.validable property no longer exists. Use cocktail.schema.ValidationContext.get_value() or cocktail.schema.ValidationContext.get_object(), depending on the desired result.
    • The cocktail.schema.ValidationError.path property no longer exists. Use the cocktail.schema.ValidationError.context property to access the cocktail.schema.ValidationContext.path instead (that is, use error.context.path instead of error.path)
  • The generation of the incremental ID for persistent objects is now delayed until object insertion. If an object requires knowing its ID before that, it can invoke the new cocktail.persistence.PersistentObject.require_id() method.

  • Added the cocktail.schema.Adapter.member_created event. This provides further options for schema adaptation. In order to ensure that the event is invoked, adaptation rules should invoke the cocktail.schema.AdaptationContext.member_created() method.

  • Merged the cocktail.schema.Member.adaptation_source and cocktail.schema.Member.copy_source properties into the new cocktail.schema.Member.source_member property.

  • cocktail.controllers.Form.validation_context has been renamed to cocktail.controllers.Form.validation_parameters, for consistency.

  • Added the cocktail.schema.Expansion adaptation rule, and its reverse, cocktail.schema.Contraction. These rules make it possible to recurse into nested references in a schema adaptation, including the members of related objects into the resulting schema.

  • Changed cocktail.schema.Schema.init_instance() to accept cocktail.schema.undefined values. This will prevent the default value for the member from being computed from the onset (it will still be computed the first time its attribute is accessed).

    Note that this method is used by the cocktail.schema.SchemaObject constructor to implement object initialization, so this behavior extends to the constructor for schema based objects.

  • Added a parent_context parameter to the adaptation methods of cocktail.schema.Adapter and cocktail.schema.RuleSet. This change is required by the new cocktail.schema.Expansion and cocktail.schema.Contraction rules.

  • Improvements to the object copy system of cocktail.schema.SchemaObject.

    • The new cocktail.schema.Member.copy_mode makes it possible to specify copy behavior on a per member basis, indicating if the member must be shallow copied, deep copied or ignored
    • The cocktail.schema.SchemaObject.create_copy(), cocktail.schema.SchemaObject.init_copy(), cocktail.schema.SchemaObject.get_member_copy_mode() and cocktail.schema.SchemaObject.copy_value() can override the copy behavior of an object's members using a member_copy_modes parameter (a mapping of members to copy behaviors)
    • Avoid (some) infinite cycles during deep copy procedures
    • Added a suffix system to prevent collision on unique cocktail.schema.String members
  • Added the cocktail.schema.Member.get_possible_values() method.

  • Support for prefix or pattern based full text searches.

  • Implemented an autocomplete control.

    This change adds the cocktail.html.Autocomplete and cocktail.controllers.autocompletecontroller.AutocompleteController classes.

  • Added the client side methods getNumberOfEntries() and setNumberOfEntries() of cocktail.html.CollectionEditor.

  • Preserve the value of cocktail.schema.SchemaObject.groups_order when declaring subclasses.


  • Made it easier to limit the max size for file uploads.

    • Added the cocktail.controllers.FileUpload.max_size property
    • Added the cocktail.controllers.FileSizeTooBigError exception


  • New UI generation system.

    • Moved parts of the cocktail.html.datadisplay.DataDisplay to a new cocktail.html.uigeneration.UIGenerator class
    • New signature for UI generation functions: ui_generator, obj, member, value, **context
    • cocktail.html.Element.data_display is replaced by cocktail.html.Element.ui_generator
    • Make it possible to set up linked contexts for UI generation (f. eg. backoffice_control as a specialization of edit_control)
    • Added and cocktail.html.Element.value as standard properties for all elements
    • Added the cocktail.html.Element.data_binding_delegate and cocktail.html.Element.init_data_binding_delegate() to simplify UI composition; these replace the cocktail.html.databoundcontrol module and its contents:
      • cocktail.html.databoundcontrol.DataBoundControl
      • cocktail.html.databoundcontrol.data_bound()
      • cocktail.html.databoundcontrol.bind_member()
      • cocktail.html.databoundcontrol.delegate_control()
    • Added the cocktail.html.Element.is_valid_display() method, to allow views to preclude themselves from serving as the display for certain members or contexts
  • The cocktail.modeling.InstrumentedCollection.changed() method now receives added and removed parameters, each containing a collection with the added / removed items during the change.

  • Replaced the grouping API in cocktail.html.Selector with a more general one in cocktail.html.grouping.

  • Support for read only fields in forms.

    • Added the cocktail.schema.Member.editable property (previously defined by Woost)
    • Added the constants cocktail.schema.EDITABLE, cocktail.schema.NOT_EDITABLE and cocktail.schema.READ_ONLY
    • Added the convenience method cocktail.schema.Adapter.export_read_only()
    • Added the cocktail.html.Form.read_only_ui_generator property
    • cocktail.controllers.FormSchemaReader will now skip any member that isn't flagged as EDITABLE
  • The cocktail.schema.SchemaObject.changed event now receives added and removed parameters (propagated from cocktail.modeling.InstrumentedCollection.changed()).

  • Added the cocktail.html.Table.grouped property.

  • Added the class, to provide more control and customization oportunities when exporting schema based data to MS Excel.

  • Added a visual control in cocktail.html.CollectionView to set the page size of listings. Until now this was only available as a query string parameter.

  • Added member types to represent geocoordinates. The following classes have been added:

    • cocktail.schema.GeoCoordinates
    • cocktail.schema.GeoCoordinate
    • cocktail.schema.Latitude
    • cocktail.schema.Longitude
  • Added the cocktail.html.SuggestionList control. This makes it easier to suggest a series of values to users while preserving the option to introduce an arbitrary value.

  • Added the cocktail.collage module, to create montages of pictures that completely cover the indicated area.

  • Added the client side cocktail.getVariable() function.

  • Added the client side cocktail.waitForImages() function.

  • Changes to cocktail.html.SplitSelector.

    • It now generates change events
    • Added the client side getValue(), setValue() and getPossibleValues() methods
  • Added the cocktail.iteration.batch() function.

  • Added the cocktail.styled.ProgressBar class.

  • Improvements to cocktail.html.templates.SourceCodeWriter.

    • Make it possible to nest SourceCodeWriter objects, using the new cocktail.html.templates.SourceCodeWriter.append() and cocktail.html.templates.SourceCodeWriter.nest() methods
    • Added the cocktail.html.templates.SourceCodeWriter.indented_block() context manager
    • Added the cocktail.html.templates.SourceCodeWriter.linejump() method
  • Added the CML py-init processing instruction. This makes it possible to add code to the constructor of the class generated by the template compiler.

  • Added a language_subset parameter to the cocktail.schema.diff() function.

  • Improvements to the HTTP requests profiler.

    • Allow profiling of requests that generate unhandled exceptions (typical use case: HTTP redirections)
    • Added the filter parameter, to make it possible to limit the activation of the profiler to requests that fulfill certain conditions
  • Added a links_target parameter to the cocktail.stringutils.plain_text_to_html() function.

  • UI improvements to the search box in cocktail.html.CollectionView.

  • Changes to the client side cocktail.showDialog() function.

    • Added the closeMode parameter, to create dialogs that become hidden when closed, instead of removed outright
    • Emit a dialogClosing event
    • The dialogClosed event now receives a background parameter, giving access to the background layer (typical use case: manipulate the background when closing the dialog, to apply animations, CSS classes, etc). Also available on the new dialogClosing event.
  • The client side function now waits for images to be loaded before centering the content.

  • Use indices when resolving expressions containing a cocktail.schema.expressions.TranslationExpression. This drastically improves the validation of unique constraints on translated members.


  • The client side cocktail.waitForImages() function didn't account for the browser cache. Cached images never resolved the returned promise object.

  • Fixed the cocktail.translations.add_fallback_language() function.


  • Made it easier to limit the max size for file uploads.

    • Added the cocktail.controllers.FileUpload.max_size property
    • Added the cocktail.controllers.FileSizeTooBigError exception


The main changes in this release include an update to jQuery, support for SASS stylesheets and calculated fields.

  • Updated jQuery from 1.8.3 to 1.11.3.

  • Removed support for SwitchCSS. Almost no site used it, and SASS is a better option all around.

  • Added the cocktail.schema.Member.expression property to implement support for calculated fields.

  • Added the cocktail.schema.CodeBlock.execute() method.

  • Added the cocktail.controllers.filepublication module.

    • Support for serving file-like objects without needing to store a temporary file.
    • Support for SASS, including source map generation
  • Added the cocktail.html.Traceback class.


  • Improvements to cocktail.styled.ProgressBar.

    • Can now be used as a context manager (with the with statement)
    • Added the cocktail.styled.ProgressBar.visible property
    • Added the cocktail.styled.ProgressBar.label property
    • Added the cocktail.styled.ProgressBar.message() method
  • Modified cocktail.schema.Schema.translate_group() to make it recursive.

  • Make cocktail.html.Selector generate a validation context when it determines its possible values. This is mostly useful to have dynamic expressions on a cocktail.schema.Member.enumeration constraint.

  • The client side cocktail.waitForImages() function didn't account for the browser cache. Cached images never resolved the returned promise object.

  • Fixed the cocktail.translations.add_fallback_language() function.

  • Fixes for dynamic member constraints based on cocktail.schema.expressions.Expression objects.

  • Improved the behavior of nested HTML forms.


  • Replaced the Froogaloop API in the cocktail.html.VimeoPlayer view with a custom API.

    • The Froogaloop API provided by Vimeo crashes when creating players dynamically
    • The vimeoAPI() and vimeoCommand() methods have been removed
    • The new API generates events that match the HTML5 Media Events specificacion (playing, pause and ended)
  • Added the cocktail.html.utils.is_inline_element() function.

  • Support collections.Counter objects on

  • Added the cocktail.html.RatingBox view.

  • cocktail.controllers.filepublication.SASSPreprocessor failed if a stylesheet contained non-ascii characters.

  • Make cocktail.html.MappingTable respect the order of collections.Counter objects.

  • Changed the cell formatting behavior of; it didn't honor cocktail.schema.Member.translate_value() in some cases.

  • Descriptive members should invoke cocktail.schema.Member.translate_member() when producing the translation for an object.



  • cocktail.styled.ProgressBar.__exit__() shouldn't finalize the bar if an exception has been raised.



  • Added the scrollintoview jQuery plug-in.

  • Made it easier to limit the max size for file uploads.

    • Added the cocktail.controllers.FileUpload.max_size property
    • Added the cocktail.controllers.FileSizeTooBigError exception


  • cocktail.controllers.parameters.FormSchemaReader should invoke member specific normalization after parsing parameter values.

  • Fixed issues with full text searches and language neutral content:

    • Changed the implementation of cocktail.schema.expressions.SearchExpression
    • Modified cocktail.controllers.userfilters.GlobalSearchFilter to always include language neutral text
    • Make cocktail.schema.TextExtractor.iter_node_languages() always include None
  • Fixed the incompatibility of per-language full text search and cocktail.schema.Member.translate_value().

    Although cocktail.schema.Member.get_searchable_text() would call cocktail.schema.Member.translate_value(), it failed to recognize the text that it produced could be either language dependant or independant. This made segmenting searchable text by language unreliable when translate_value() was involved.

    To fix this situation, the following changes have been made:

    • Modified the internals of cocktail.schema.TextExtractor
    • Modified the text extraction logic for several member types
    • Added the cocktail.schema.Member.language_dependant property
    • Added the cocktail.schema.Member._infer_is_language_dependant() method
    • Removed the cocktail.schema.Member.language_agnostic_text_extraction property
  • Moved the cocktail.schema.String.translatable_enumeration property to cocktail.schema.Member. This makes it easier to define enumerations based on non-string data types (f. eg. integers).

  • Added the <?resource ?> processing instruction for CML templates.



The main changes in these release include a new abstraction layer for HTML resource URIs, changes to the SASS compilation process and support for visual grids.

  • Support custom URL schemes for resource repositories.

    • Views can now use cocktail://, woost://, my-package://... URLs, which will be resolved using the cocktail.html.resources.ResourceRepositories class
    • Added the cocktail.html.resources.ResourceRepositories.normalize_uri() method. Make it available as the normalize_resource_uri() global function in CML templates.
    • Added the cocktail.html.resources.ResourceRepositories.is_repository_uri() method
    • @import statements in SASS files can now include resource repository URLs
    • Added the client side cocktail.normalizeResourceURI() function
    • Changed the default location of the resources for cocktail from /cocktail to /resources/cocktail
  • Modified the SASS compilation procedure to prevent importing dependencies twice.


  • Changes to the in browser code editor control (cocktail.html.CodeEditor).

    • Updated CodeMirror to version 5.14.2
    • Fixed the resource URIs for the control, which had been broken by the komovica branch
    • Renamed cocktail.html.CodeEditor.base_settings to default_settings, to state the intended usage of the property more clearly
    • Removed the standard per-syntax settings; per syntax customization is still available, but the new mode system in CodeMirror makes having defaults unnecessary
    • Added support for CodeMirror submodes
  • Improvements to the cocktail.html.SlideShow view.

    • Make it easier to customize the prev/next buttons of the slideshow view. The following elements have been added:
      • cocktaill.html.SlideShow.next_slide_button_image
      • cocktaill.html.SlideShow.next_slide_button_text
      • cocktaill.html.SlideShow.previous_slide_button_image
      • cocktaill.html.SlideShow.previous_slide_button_text
      • cocktaill.html.SlideShow.create_next_slide_button_content()
      • cocktaill.html.SlideShow.create_previous_slide_button_content()
    • Added a wrapper element for the next / previous buttons. This makes it easier to achieve growingly common layouts (wide slides, with the text / buttons centered according to the site grid).
    • Set the right/bottom CSS properties of fading slides. This helps with slides that don't define an explicit width.
  • Added support for grid based designs using SASS.

    • Added the cocktail://styles/grid module, providing the following mix-ins and functions
      • define-grid
      • show-grid
      • grid-max-size
      • grid-min-size
      • grid-size-media-query
      • grid-size-matches
      • grid
      • grid-centered
      • grid-fit
      • grid-row
      • grid-cell
      • grid-items
      • grid-item
      • grid-size
      • grid-columns
      • grid-spacing
      • grid-width
    • Added the cocktail.html.GridRulers view, to overlay rulers on top of grid based designs, as a development aid
  • Added theme support for SASS stylesheets.

  • Factored out SASS compilation to a dedicated cocktail.html.resources.SASSCompilation class.

  • Added the cocktail://styles/utils SASS module, providing general utility mix-ins:

    • join-media-query
    • clear-list-styles
    • horizontal-list
    • clear-children-float
    • scripting-enabled
    • transparent-button
    • dropdown-menu
  • Added the cocktail.controllers.filepublication.SASSPreprocessor.ignore_cached_files property, to force recompilation of SASS files during development.

  • Added the convenience method.

  • Added the cocktail.schema.TranslatedValues class.

    This new class (plus the required modifications in cocktail.schema.MemberDescriptor) provides convenient syntax for setting the value for multiple translations of an object in a single go.

  • Added the cocktail.html.SmallScreenPopUp view.

  • Added the cocktail.stringutils.normalize_indentation() function.

  • The cocktail.dateutils.CalendarPage constructor now also accepts a single date/datetime parameter.

  • Added french translations for date/time expressions.

  • Make element usable on the constructor and _build() method of CML templates.

  • Fixed the translation of None for cocktail.schema.Boolean members.

  • Fixed a bug that caused the cocktail.schema.SchemaObject constructor to sometimes ignore translated values.

  • The cocktail.html.Document._ready() override should call the base implementation

  • Added the cocktail.persistence.Query.is_subset() method.



This release introduces important changes in the cocktail.translations package, support for bidirectional text, changes to collection instrumentation and new APIs for dealing with URLs.

  • New translations API.

    • Removed the cocktail.translations.strings module
    • Renamed cocktail.translations.TranslationsRepository to cocktail.translations.Translations
    • Removed the cocktail.translations.Translation class
    • Added the cocktail.translations.Translations.instances_of() decorator
    • __translate__ methods are no longer used; use .instance translation keys instead (e.g. myapp.models.mymodel.MyModel.instance).
    • Support defining a translation key using single value applying to all languages (e.g. translations.define("foo", "bar") instead of translations.define("foo", es = "bar", en = "bar", de = "bar"))
    • Added the cocktail.schema.Member.custom_translation_key property.
    • Added the following helper functions:
      • cocktail.translations.translate_locale()
      • cocktail.translations.translate_locale_component()
      • cocktail.translations.month_name()
      • cocktail.translations.month_abbr()
      • cocktail.translations.weekday_name()
      • cocktail.translations.weekday_abbr()
      • cocktail.translations.translate_date_range()
    • CML templates now offer a view_translations() function that automatically injects the view's fully qualified name as a prefix
    • cocktail.translations.helpers.plural2() is now more convenient to use:
      • It accepts objects with a __len__ method, as well as integers (so you can use plural2(items, "a", "b") instead of plural2(len(items), "a", "b"))
      • It attempts to insert the count into the plural form using the % operator (so you can use plural2(count, "one item", "%d items") instead of plural2(count, "one item", "%d items" % count))
    • Introduced the .default_member_translation translation suffix for schema members
    • Added the cocktail.translations.get_root_language() and cocktail.translations.language_has_fallback() functions
  • Several conventions for translation keys have changed.

    • Schema classes now use their fully qualified name as their translation key. Example: use "myapp.models.mymodule.MyModel" instead of just "MyModel".
    • Schema members are now translated using the schema's fully qualified name + ".members." + member name. Example: use "myapp.models.mymodule.MyModel.members.my_member" instead of "MyModel.my_member".
    • Schema groups are now translated using the schema's fully qualified name + ".groups." + group name. Example: use "myapp.models.mymodule.MyModel.groups.my_group" instead of "MyModel.my_group".
    • The -instance suffix becomes .instance
    • The -plural suffix becomes .plural
    • The -explanation suffix becomes .explanation
    • None values for schema members are now translated using the member's translation key followed by a ".none" suffix. Example: use "myapp.models.mymodule.MyModel.members.my_member.none" instead of "MyModel.my_member=None".
    • The values for schema members with enumerations are now translated using the member's translation key followed by a ".values." + value prefix. Example: use "myapp.models.mymodule.MyModel.members.my_member.values.value" instead of "MyModel.my_member=value".
    • "month N" and "month N abbr" become "" and "cocktail.months.N.abbr", respectively. That said, applications are encouraged to use the new cocktail.translations.month_name() and cocktail.translations.month_abbr() functions instead.
    • "weekday N" and "weekday N abbr" become "" and "cocktail.weekdays.N.abbr", respectively. That said, applications are encouraged to use the new cocktail.translations.weekday_name() and cocktail.translations.weekday_abbr() functions instead.
    • "date range" becomes "cocktail.date_range". That said, applications are encouraged to use the new cocktail.translations.translate_date_range() function instead.
    • "Decimal parser" becomes "cocktail.decimal_parser"
    • "today" becomes ""
    • "locale X" becomes "cocktail.locales.X". That said, applications are encouraged to use the new cocktail.translations.translate_locale() function instead.
    • The "-custom_value" suffix becomes ".custom_value"
  • The file names for CML templates must now be in lowercase.

  • Introduced support for strings files.

    Applications used to define a single module to hold all their translations. This could become unwieldy quickly; as a new alternative, it is now possible to distribute translations throughout multiple files (typically one per module), using a dedicated format.

    • Added the cocktail.translations.Translations.load_bundle() method
    • Added the cocktail.translations.Translations.request_bundle() method
    • cocktail.schema.SchemaObject and cocktail.html.Element classes now attempt to autoload a translation file
  • Changes to collection instrumentation.

    • Collection members now trigger the cocktail.schema.SchemaObject.changing event
    • Removed the cocktail.modeling.InstrumentedCollection.item_added() and cocktail.modeling.InstrumentedCollection.item_removed() methods
    • Added the cocktail.modeling.InstrumentedCollection.changing() method
    • Added a context parameter to cocktail.modeling.InstrumentedCollection.changed(), to receive the change context (see the cocktail.schema.SchemaObject.changing and cocktail.schema.SchemaObject.changed events for details)
    • Removed cocktail.schema.SchemaObject.MemberDescriptor.instrument_collection(), replaced with cocktail.schema.SchemaObject.MemberDescriptor.get_instrumented_collection_type()
    • Moved the set_content() methods from cocktail.schema.RelationCollection subclasses to the cocktail.modeling.InstrumentedCollection subclasses
    • Added the cocktail.modeling.InstrumentedList.clear() method
    • Fixed a bug that caused the cocktail.schema.SchemaObject.changed event of collection members to be triggered twice
  • Use the new vimeo Javascript API.

  • Introduced new APIS for URL parsing and manipulation.

    • Introduced the cocktail.urls package, which provides the following new classes:
      • cocktail.urls.URL
      • cocktail.urls.URLBuilder
      • cocktail.urls.Path
      • cocktail.urls.QueryString
    • Added the cocktail.controllers.request module, with the following functions:
      • cocktail.controllers.request.get_request_url()
      • cocktail.controllers.request.get_request_url_builder()
      • cocktail.controllers.request.get_request_root_url()
      • cocktail.controllers.request.get_request_root_url_builder()
    • Added the cocktail.controllers.redirection module, with the following functions:
      • cocktail.controllers.redirection.redirect()
      • cocktail.controllers.redirection.reload_request_url()
      • cocktail.controllers.redirection.post_redirection()
    • Deprecated the following classes and functions:
      • cocktail.controllers.Location
      • cocktail.controllers.uriutils.make_uri()
      • cocktail.controllers.uriutils.percent_encode()
      • cocktail.controllers.uriutils.percent_encode_uri()
  • Added support for bidirectional text in HTML elements.

    • Added the cocktail.translations.directionality module
    • HTML elements bound to a translatable member now add a dir attribute based on their language
    • HTML documents also declare a dir attribute
    • Added several mixins to the utils SASS module:
      • ltr
      • rtl
      • position-start
      • position-end
      • margin-start
      • margin-end
      • padding-start
      • padding-end
      • float-start
      • float-end
      • clear-start
      • clear-end
      • text-align-start
      • text-align-end
  • Removed seldom used code for multiple choice filters.

    • Removed cocktail.html.MultipleChoiceSelector
    • Removed cocktail.html.ModalSelector
  • Add CSS classes to cocktail.html.TreeView entries to denote branches and leaves.

  • Animate dialogs and make it possible to replace an existing dialog with another.

  • Changes to cocktail.html.SlideShow:

    • Preserve the position CSS property of the slide show if set to absolute or fixed beforehand
    • Make the addSlide() method return the slide element
    • Added an option to select a slide without applying transition effects
    • Give each slideshow its own client models, instead of sharing them across all slideshows in the page (this makes it possible to modify them on a per instance basis)
  • Added an option to cocktail.declare() to initialize the namespace with the given members

  • Replace cocktail.html.Element.when_binding() and cocktail.html.Element.when_ready() with events.

    Use cocktail's event system instead of custom callback lists to signal the stages of an HTML element's life cycle. Events provide more flexibility, and having a single system makes things more consistent and robust.


    • The metaclass for elements now inherits from (so elements can use the decorator)
    • cocktail.html.Element.when_ready() and cocktail.html.Element.when_binding() have been removed; use the new cocktail.html.Element.ready_stage and cocktail.html.Element.binding_stage events instead.
    • is now automatically imported in CML templates
  • Defend against CSRF attacks using a synchronizer token pattern.

    • Added the cocktail.controllers.csrfprotection module. The following elements are added to the cocktail.controllers package:
      • cocktail.controllers.CSRFProtection
      • cocktail.controllers.CSRFTokenError
      • cocktail.controllers.get_csrf_protection()
      • cocktail.controllers.set_csrf_protection()
    • Protection is enabled by default
    • The module injects a token into forms and Ajax requests, using a cookie and javascript.
    • Requests made using XMLHttpRequest directly need to call cocktail.csrfprotection.setupRequest(). Requests made with any of the jQuery helper methods inject the token automatically.
    • The valums asynchronous file uploader had to be monkey patched to inject the token into its Ajax request. Note that its iframe based uploads won't work anymore (that basically affects old versions of IE).
  • Added an option to autocommit migrations after they are completed.

  • Added the cocktail.html.Element.dispose() method, to break up element trees and free their resources right after a view is rendered.

  • Provide access to error objects from the translation keys used by cocktail.schema.Member.translate_error().

  • Added the cocktail.controllers.memorymonitorcontroller.MemoryMonitorController class.

  • Make the members parameter of optional.

  • Improvements to the cocktail.persistence.query.Query class.

    • Added the cocktail.persistence.query.Query.is_subset() method
    • Added the cocktail.persistence.query.Query.description property
    • Support negative indices when accessing a single item
  • Added the infinitescroll.js script

  • Make it possible to disable sorting on reference members.

    Setting cocktail.schema.Reference.default_order to None now disables sorting. The previous behavior is achieved by setting the property to "__auto__". This is the new default value, so the default behavior shouldn't change.

  • Added functions to translate currencies and format money amounts in different currencies.

    • Backwards incompatible: cocktail.schema.Money.currency now uses ISO 4217 codes instead of their unicode signs (so EUR instead of €)
    • Added the cocktail.translations.translate_currency() function
    • Added the cocktail.translations.get_currency_sign() function
    • Added the cocktail.translations.format_money() function (replaces the format_money() function in the module)
    • Added the cocktail.schema.Currency member type
  • Make it possible to define cocktail.caching.MemoryCacheStorage.memory_limit using a constructor parameter

  • Added a cocktail.schema.HTML.tinymce_params property to easily customize cocktail.html.TinyMCE instances

  • Changed cocktail.controllers.Controller to accept extra positional arguments and issue a 404 error.

    Before, invoking a controller with extra positional arguments would raise a 500 error, since unless overriden to do so, its __call__ method didn't accept positional arguments. With this change, __call__ accepts any number of positional arguments, but will raise a 404 error if it receives any. Subclasses can still override __call__ to accept positional arguments, so most code
    shouldn't be affected by the change.

  • Added the reveal.js frontend script

  • Added the cocktail.schema.SchemaObject.consolidate_translations() method



  • Added the cocktail.schema.Schema.schema_aliases property.

    The property makes it possible to assign multiple alternative names to schemas. The main use case for this is to inherit translations between cocktail.controllers.FormProcessor

  • Changed the names assigned to the schemas generated by cocktail.controller.formprocessor.Form.

    • Use fully qualified names
    • Assign aliases based on each base controller
  • Added the cocktail.translations.DATE_STYLE_COMPACT_TEXT option for date formatting.

  • Added the cocktail.html.TreeView.highlighted_selection property.

    The property makes it possible to avoid adding the markup that highlights the active entry and the selected branches on those trees that don't require it. This can lead to performance improvements in some scenarios. It can also be useful to share a
    cached tree between different contexts if the selected entry can be highlighted client side.

  • Media queries generated by the grid SASS module are no longer limitted to screens, they now affect all medias by default.

  • Automatically normalize the indentation of cocktail.schema.CodeBlock members.

  • Improvements and fixes for cocktail.schema.CalendarPage.

    • Changed the default component separator for cocktail.schema.CalendarPage members to "-"
    • The serialization of cocktail.schema.CalendarPage members ignored the cocktail.schema.Member.request_value_separator property
    • Added the cocktail.html.MonthBox view, set it as the default control for cocktail.schema.CalendarPage.
  • Added the decimals parameter for the cocktail.translations.format_money() function.

  • Support custom Python functions in SASS files, overridden the url() function to resolve custom protocols for resource repositories.

  • Use RFC 6266 to encode Content-Disposition headers

  • Added a validations parameter to the cocktail.schema.Member constructor

  • Added a submit_button CSS class for the submit button of cocktail.html.Form

  • Added the cocktail.schema.SchemaObject.get_translated_value() method.

    The following expression:

    can now be rewritten as:


    Language and keyword arguments are propagated as well.

  • Size expressions in SASS grids can now use the in and not-in operators.

  • Added an optional focus parameter to the appendEntry() and setNumberOfEntries() client side methods of cocktail.html.CollectionEditor.

  • Added the cocktail.html.MonthCalendar.min_rows property

  • Fixed the parsing / serialization of None/missing items in cocktail.schema.Tuple members

  • Support parsing empty values in cocktail.schema.Date / cocktail.schema.DateTime parameters

  • Support choosing the desired number of grid columns using a map.

    • Added the grid-select-value() SASS function
    • The grid-columns() SASS function and all the mixins that depend on it (grid, grid-cell, grid-fit, grid-item) now support a map on their $columns parameter, making it possible to specify a different number of columns for different size expressions (the value for the first matching expression will be used)