Merge branch 'master' into v1.0

docs/key_concepts/debugging.md

@@ -33,9 +33,9 @@ To use internal assests, such as a local copy of jQuery, add this to `local.conf
 
 
 
-## Logging within Controllers and Jobs
+## Logging within Controllers
 
-Omeka S provides a `logger()` plugin. This provides access to the Omeka S logging system. You can write messages to the log with, e.g., `$this->logger()->info("Status: good");`
+Omeka S provides a `logger()` plugin withing Controllers. This provides access to the Omeka S logging system. You can write messages to the log with, e.g., `$this->logger()->info("Status: good");`
 
 The `Omeka\Mvc\Controller\Plugin\Logger` object uses methods from `Zend\Log\LoggerInterface`, which makes it easy to give messages at different log levels:
 
@@ -48,6 +48,18 @@ The `Omeka\Mvc\Controller\Plugin\Logger` object uses methods from `Zend\Log\Logg
 * info()
 * debug()
 
+## Logging within Jobs
+
+Jobs that run in the background do not have access to the `logger()` plugin. Instead, you can get the logger from the ServiceManager anywhere inside the Job class:
+
+```php
+$logger = $this->getServiceLocator()->get('Omeka\Logger');
+```
+
+Then use as above, e.g. `$logger()->info('Importing page 1')`
+
+Log messages are not written to `application.log` from inside a Job. Instead, they are written to the Job's record. You can view the information by look at the Job record in the admin screen.
+
 ## Logging within Views
 
 ## Logging elsewhere

docs/key_concepts/themes.md → docs/key_concepts/working_with_Sass_and_CSS.md

@@ -1,6 +1,4 @@
-# Themes
-
-## Working with SASS and CSS
+# Working with Sass and CSS
 
 
 Omeka S's CSS is generated using Gulp and other Node packages. The necessary packages are installed with npm. From the top-level Omeka S directory:
@@ -15,7 +13,7 @@ For convenience, you may also want to install Gulp's CLI globally:
 npm install -g gulp-cli
 ```
 
-### Editing the Styles
+## Editing the Styles
 
 **Do not edit the files in the `css` directory manually!** They are automatically generated and your changes will be overwritten. 
 

docs/register_an_addon.md

@@ -1,6 +1,6 @@
 # Registering a new module or theme with omeka.org
 
-After you [register your GitHub repository](http://preview.omeka.org/addons/register/) as an Omeka addon we'll publish new versions of your addon if you follow these steps.
+After you [register your GitHub repository](http://omeka.org/register/) as an Omeka addon we'll publish new versions of your addon if you follow these steps.
 
 First, in your addon's GitHub repository, go to the releases page and click
 "Draft a new release". Enter a tag name (it does not have to be your addon

docs/themes/introduction.md

@@ -0,0 +1,20 @@
+# Introduction
+
+Omeka S supports themes, a way to customize the presentation of Omeka S sites. Omeka S comes with a default theme, and officially supports the [Center Row](http://github.com/omeka-s-themes/centerrow), [Cozy](http://github.com/omeka-s-themes/cozy), and [The Daily](http://github.com/omeka-s-themes/thedaily) themes. The following is a guide for modifying existing themes as well as starting a theme from scratch.
+
+## Theme Basics
+
+Themes for Omeka S live within the `themes` directory within the root directory of an Omeka S installation. They typically include the following directories and files:
+
+* `config/theme.ini`: This is a **required** file for a theme to be recognized by Omeka S. It includes the theme name, author, support information, theme version, Omeka S version requirements, and theme configuration options for users.
+* `asset`: Theme creators use this directory to house assets such as CSS, Javascript, images, and more. It mimics the directory structure of `application/asset` within an Omeka S installation.
+* `view`: Files within this directory are the meat of a theme. These customized theme files override Omeka S default view template files located in `application/views/`.
+
+## Sass
+
+Themes officially supported by the Omeka team ([the Omeka S default theme](http://github.com/omeka-s-themes/default), [Center Row](http://github.com/omeka-s-themes/centerrow), [Cozy](http://github.com/omeka-s-themes/cozy), and [The Daily](http://github.com/omeka-s-themes/thedaily)), use SASS to generate their CSS. For users who want to start using SASS, here are recommended tutorials for installation. 
+
+* [Sass Basics](http://sass-lang.com/guide)
+* [Working with SASS and CSS](/key_concepts/working_with_Sass_and_CSS)
+
+Those who simply want to edit the CSS without getting into preprocessors can ignore the 'asset/sass' folder completely and focus on .css files. **Note:** if you edit a .css file but later decide to use Sass, you should back up and make note of your changes before compiling for the first time. Changes made in .scss files overwrite any changes made to .css files.

docs/themes/modifying_themes.md

@@ -0,0 +1,44 @@
+# Modifying Themes
+
+## Overriding default templates
+
+Omeka S has a set of default template files that all themes use, and override when the desired page structure is different from the default.
+
+The default template files are in the folder `/application/views` in your Omeka S installation within the following subfolders: `/application/views/common`, `/application/views/error`, `/application/views/layout`, and `/application/views/omeka/site`. Most views that theme builders need will be in `/application/views/layout` and `/application/views/omeka/site`. Subfolders correspond to the pages that are seen along url patterns. For example, the page displayed at `{YourOmeka SSite}/item/show` is produced by the file in `/application/views/omeka/site/item/show.phtml`.
+
+Themes might or might not override these files. The default theme, for example, has a `layout` directory that overrides one of the default templates: `layout.phtml`.
+
+```
+- default/
+    - views/
+        - layout/
+            - layout.phtml
+```
+
+If you want to modify a file in a theme, the first place to look is in the theme's own directories. But notice that that will only work if the theme has overridden the default template. In many cases, then, you will need to copy the default template files into the theme, taking care to maintain the directory structure.
+
+So, for example, imagine wanting to modify the show page for items and the browse page for collections in the default theme.
+
+For the show page for items, we need to copy `/application/views/omeka/site/item/show.phtml` 
+to `/default/views/omeka/site/item/show.phtml`
+
+For the browse page for collections, we need to first create the directory: `/default/views/omeka/site/collection`
+
+Then we can copy `/application/views/omeka/site/collection/browse.phtml` 
+to `/default/collections/browse.phtml`
+
+The result in the default theme will look like::
+
+```
+- default/
+      - views/
+        - layout/
+            - layout.phtml
+        - omeka/
+            - site/
+                - item/
+                    - show.phtml
+                - collection/
+                    - browse.phtml
+---
+```

docs/themes/style_guide.md

@@ -0,0 +1,20 @@
+## Omeka S Theme Style Guide
+
+This style guide is for use in writing themes for Omeka S. It borrows heavily from the _[Github style guide](http://primercss.io/)_. This style guide is a work in progress, so excuse our dust.
+
+### General styles
+
+* Use 4 spaces for indentation. Do not use tabs.
+* Use spaces after `:` when writing property declarations.
+* Put spaces before `{` in rule declarations.
+* Use hex color codes `#000` unless using rgba.
+
+Use the `/*` style of comments for headings you want to appear in the `.css` file. For Sass-only sections, such as the variables set in `_base.scss`, use the `//` commenting syntax. The `!` at the beginning of the header helps bookmark sections for theme writers using the Coda web editor.
+
+### _base.scss
+
+The `_base.scss` file should include any variables used across multiple `.scss` files. Otherwise, the variables appear at the top of the file in which they are used.
+
+### _normalize.scss
+
+We like to use Nicolas Gallagher's [`normalize.css`](http://necolas.github.io/normalize.css/) as our reset stylesheet. Include it as a `.scss` file and import it into `_base.scss`.