Need to document the build instructions

[philwareham]

The readme file needs to contain instructions on how to build the project.

[philwareham]

I'm not sure I've got the build quite right on this, so I'm open to advice.

I want to pull this repo into other projects via Bower (such as my Hive admin theme, for use in development mocks), so I don't know if the final compiled built CSS should be included in the repo or (as it currently is setup) the build ignored.

[gocom]

Build fragments don't belong to a source repository. If build step needs to be done, it's done on the consumer's end, or during packaging.

But really, you should be distributing this as a Sass component. If modularity and consumption is an issue, you can always to migrate to something that is even more modular, such as LESS. All distributed LESS mixings can be merely included in the project using import statement in your LESS project files. E.g.

@import ../../bower_components/some-less-project/file;

LESS can also build and consume CSS:

@import (less) ../../some/private/css/file/outside/document/root.css;

[gocom]

Ideally this repository should be consumable by simply adding import statement to consumer's main scss or less file. Workflow should be limited to few very simple steps.

Install:

$ bower install textpattern-jquery-ui-theme

Import in your project:

@import bower_components/textpattern-jquery-ui-theme/jquery-ui;

...and done.

You will want to remove any global settings from this component, such as $legacy-support-for-ie6 from core/_settings.scss, or similarly to LESS, these should be overridable. At least LESS has variable scoping, so in LESS overriding is possible before the mixing is called. Don't know if same is possible in Sass.

Things such as image location should configurable; they should be set by a variable and configurable from LESS/Sass without modifying the source. For instance this:

@import bower_components/textpattern-jquery-ui-theme/jquery-ui;
#textpattern > #jqueryui > .init('/path/to/images/');

Would work in LESS.

The code also should be namespaced if possible to prevent collisions and allow users to consume the component even if other components use the same mixing and variable names. LESS supports namespaces, don't know about Sass. If it doesn't, you could probably wrap the styles in an prefixed initializer mixing and prefix the mixins itself.

[philwareham]

Hmmm, let me think this through properly.

Initially I was just intending this repo to be an easier way of generating the jQuery UI theme we use in the Textpattern CMS, but I can see the benefit or harnessing it for other uses (such as the Textpattern.org site). I've purposely used the same text sizing and colourways for our brand site designs that I use for the Hive admin theme so I could share bits of code and also keep some consistency.

[gocom]

In LESS variables are scoped so those settings wouldn't matter. You could just define them inside a namespace. E.g.

#textpattern #jqueryui
{
    @legacy-support-for-ie8 = 0;
    @import '../some-other-compass-like-less-module/main'; // or user can import that in their own LESS files

    .init(@path-to-images)
    {
         .opacity(0.8); // generates transparency without polyfill.
    }
}

[disabled] {
    .opacity(0.8); // generates transparency with polyfill.
}

[gocom]

Initially I was just intending this repo to be an easier way of generating the jQuery UI theme we use in the

You are manually building this source and then copy pasting this repository to other repository. I don't think that is very easy. More of so frustrating. I'm pretty amazed how much copy pasting you are willing to do and how little human errors you do.

This should be built on Textpattern end and consumed by Textpattern. Which is where LESS shines as its modular (has no system wide dependencies) and you can include different versions of the library you are working on (include local copy of something instead of the one installed by package manager) and its dependencies.

I've purposely used the same text sizing and colourways for our brand site designs that I use for the Hive admin theme so I could share bits of code and also keep some consistency.

This doesn't matter if you don't set the variables in this component, especially the ones that affect Compass as whole. Leave defining variables (color and font) to the project that consumes this theme, and this theme can be used anywhere, on any site, using any text size, color palette or font.

In LESS variables are overridable (as they are scoped -- work similarly to programming languages). Don't know about Sass. You can define and re-define variables, but not sure if it has namespaces or scoping.

[philwareham]

Sass 3.3 (currently at release candidate stage) has namespaces, apparently... http://thechangelog.com/namespace-support-is-being-added-to-sass/

I need to read up on it though.

[gocom]

I don't believe that is what you want. I appears that there is no actual mixing namespaces similarly to programming languages, and LESS. That mentioned example itself has the mixing it uses to extract its "namespace" in the global scope.

What you will want is a method to prevent mixing collisions. The mixins defined in this repository should not leak to the project consuming this repository, like they now are. Additionally, the user that consumes this repository should still be able to call those namespaced mixins, just like in LESS, so that he can create additional elements using the styles provided. E.g.

button {
   #textpattern > #jqueryui > .button();
}

Should compile to:

button {
    font-size: 100%;
    [...]
}

button:hover {
    [...]
}

button:active {
    [...]
}

But I'm not sure if you can reuse classes like you can in LESS. But anyways, those all styles should be created using mixings and then assigned to proper classes/elements, which would allow reusing the styles (e.g. button styles wouldn't have to be duplicated - we could reuse stuff in Textpattern admin-side theme too, since some of styles are duplicates). Its just that in LESS you can both define a mixing and generate CSS at once. Like so:

.button() {} /* function mixing, doesn't output anything if not called. */
.button {} /* renders styles and registers the class as mixin so it can be used again later on. */