middleman-apps 0.1.0 → 0.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 07e504c02695ba4f0387c2d974c49030b12a0655
-  data.tar.gz: 46a2badf1b57e7572d6f71232999ce7783c8f50b
+  metadata.gz: 6a213786e26254de55227a6665424f7e292a309d
+  data.tar.gz: ee7f03b33678750f48025f9d1175066aaa89a9b1
 SHA512:
-  metadata.gz: 110ab87281cb3a4109e9c3ef5b73d4db382a8622a7b34534b4b01ef31aaeab30af06e783bde2cccb727c9d043f32004eaf7d3e5227dfeafd00db1c293eff973e
-  data.tar.gz: 5f8a7f7edc8b1785e3ff7da9ace36d4e731c7ec01319256adea95d71cdf4f200e49ee6c7cb0b6a5b8ef84d1798d8d6f01a95cc2e826dacb7483d978efe225a8d
+  metadata.gz: 39fc434b08df657f9e5784dd146e03808808ed51a068dbfa45433776a0b2c44aea81ceee060a1535f0847eddbe86df50dc1c299a95edcb27b7af7b46b9d3c231
+  data.tar.gz: 9581a50b7a073eff04dbf89fd8797ddb3d2324d2279a2bd6e65d6ec0f31482382e5abedbd80ac162afc8e2540dcbffdac059e423e6e28f11be67f984218f815b

data/.gitignore

@@ -6,3 +6,6 @@
 
 /tmp
 /doc
+/.yardoc
+*.gem
+config.ru

data/.rubocop.yml

@@ -1,7 +1,8 @@
 AllCops:
   Exclude:
     - 'lib/middleman/apps/rack_contrib.rb'
-    - 'tmp/aruba'
+    - 'tmp/aruba/**/*'
+    - 'features/**/*'
 
 Metrics/ClassLength:
   Exclude:

data/Gemfile

@@ -6,6 +6,7 @@ source 'https://rubygems.org'
 gemspec
 
 group :development do
+  gem 'pry'
   gem 'rake'
   gem 'rdoc'
   gem 'yard'
@@ -14,6 +15,9 @@ end
 group :test do
   gem 'aruba'
   gem 'capybara'
+  gem 'capybara-mechanize'
   gem 'cucumber'
+  gem 'poltergeist'
+  gem 'redcarpet', '~> 3.3', '>= 3.3.3'
   gem 'rspec'
 end

data/README.md

@@ -1,4 +1,4 @@
-## Middleman Apps
+## Middleman Apps [![Build](https://api.travis-ci.org/nikhgupta/middleman-apps.svg?branch=master)](https://travis-ci.org/nikhgupta/middleman-apps)
 
 `middleman-apps` is an extension for the [Middleman] static site
 generator that allows you to run truly dynamic pages within your static
@@ -12,21 +12,26 @@ You can create dynamic pages using this extension. Maybe you want to:
 - Display a dynamic Gallery of your most recent timeline from Flickr?
 - ... suggest one? ...
 
-The best way to get started with this extension is to have a look at the
-various `features` in the test suite. There is a test for each feature
-that exists for extension, such as:
-
-- Mount Rack apps by, simply, placing them in `MM_ROOT/apps` directory.
-- Allow running child apps in-tandem with the static (built) MM app, and
-  wrap them both in a single `Rack::App`, which can be run with e.g.
-  `rackup`.
-- Use a specific `404` error page that is common across your static
-  website, and child apps mounted using this extension.
-- Discovery of mountable child apps and automatic mounting.
-- Optionally, specify a URL where a child app should be mounted.
-- Optionally, specify a Class name or namespace for the child app.
-- Optionally, inherit from `Middleman::Apps::BaseApp` for helper methods
-  and added goodies for your apps.
+## Installation
+
+If you're just getting started, install the `middleman` gem and generate
+a new project:
+
+```
+gem install middleman
+middleman init MY_PROJECT
+```
+
+If you already have a Middleman project: Add `gem "middleman-apps"`
+to your `Gemfile` and run `bundle install`.
+
+## Getting Started
+
+To get started with this extension, you only need to place a rack app
+inside `MM_ROOT/apps` directory. Now, run `middleman build` or 
+`middleman server`, and your rack app will be mounted for you.
+
+The app should be visible in `/__middleman/sitemap`, as well.
 
 ### Example
 
@@ -55,21 +60,51 @@ Run/Build your Middleman site now, and visit:
 `/base64-api/encode/somestring`. Voila! It just works!
 
 A `config.ru` is, also, generated for you, so that you can keep
-using these dynamic pages/endpoints using `rackup`. Try running 
-`rackup`, and visiting the above endpoint on that server instance.
+using these child apps/endpoints in production mode, e.g. via `puma`, 
+`rackup`, etc.. Try running `rackup`, and visiting the above endpoint on 
+that server.
 
-## Installation
+## Features
 
-If you're just getting started, install the `middleman` gem and generate
-a new project:
+Consider a real world example, where you have a Middleman website 
+running at `/`. Now, everything is static at this point. Lets, provide 
+a page on this website, which redirects the user to a random blog entry 
+from the last year. Lets assume this isn't possible without Javascript, 
+or maybe you need to do some server-side processing before you redirect.
 
-```
-gem install middleman
-middleman init MY_PROJECT
-```
+Well, we can write down a succint Sinatra application that queries 
+Middleman's sitemap in the realtime, and redirect to a random article 
+from there. Let's call this a `child app`.
 
-If you already have a Middleman project: Add `gem "middleman-apps"`
-to your `Gemfile` and run `bundle install`.
+Using this extension, you can place this `child app` inside your 
+Middleman directory, and have it mounted at a specific path, and add 
+other niceties, and so on.
+
+- Creates an `umbrella` rack-app that mounts Middleman to `/` and all 
+  other child apps inside itseslf. You can run this umbrella application 
+  in development mode using `middleman server`.
+  
+- A `config.ru` is generated for you, so that you can run this 
+  `umbrella` application in production using `rackup`, `puma`, etc. What 
+  you see in development is what you get in production (nearly).
+
+- Use a specific `404` error page that is used across `middleman` 
+  application and `child apps` in production mode.
+
+- Automatic reloading of code for child apps in development mode.
+
+- Specify `url` where a given `child-app` should be mounted.
+
+- Use Middleman layouts in the HTML rendered by child apps. Requires 
+  child apps to be inherited from `Middleman::Apps::Base`, which in turn 
+  inherits from `Sinatra::Base`.
+
+  Inheriting from this class, also, provides you with several other 
+  goodies, such as specifying title and description for your child apps, 
+  so that they can be listed on some page with some overview of what 
+  they do. It is recommended to inherit from this class, when possible.
+
+- Works well with `DirectoryIndexes`, and `AssetHash` extensions.
 
 ## Configuration
 
@@ -78,18 +113,11 @@ activate :apps,
   map: {},               # Mappings for custom URL and Class for child apps
   verbose: false,        # Display warnings if any when building main app
   not_found: "404.html", # Render this page for 404 errors, if it exists
-  namespace: nil         # By default, use a namespace for finding Class
-                         # of a child app
+  namespace: nil,        # Use a namespace for Class of a child app
+  mount_path: '/',       # Prefix all child apps URLs with this path
+  app_dir: 'apps'        # Child apps are placed in this directory.
 ```
 
-A `config.ru` will be generated for you (if one does not exist already),
-when you preview/build your MM site. Your child apps will be mounted in
-both development (preview) mode (e.g. via `middleman server`) as well in
-production (build) mode of MM (e.g. running the built app using `puma`
-or `rackup`).
-
-## Options
-
 ### `not_found: '404.html'`
 
 This option defines a custom HTML page to use for 404 errors. By
@@ -100,11 +128,14 @@ A warning is generated in `verbose` mode, if this file does not exist!
 Set this option to `false`, if you prefer not to use a 404 page and
 would rather stick with default 404 response from Rack.
 
+At the moment, this page can not be shown in `development` mode, but 
+will be used for missing URIs across the `umbrella` application in 
+`production`.
+
 ### `verbose: false`
 
 If true, display warnings such as non-existent 404 error page, and any
-child apps that were ignored when starting server in
-development/production mode.
+child apps that were ignored when starting server or building it.
 
 ### `namespace: nil`
 
@@ -114,7 +145,7 @@ below for better clarification.
 ### `map: {}`
 
 This option can be used to specify a custom URL endpoint for a specific
-child app, or different class name for your child app if different than
+child app, or class name for your child app if different than
 what is guessed (`str.classify.constantize`).
 
 ```ruby
@@ -143,6 +174,100 @@ With the above configuration in place, here is what happens:
   `MM_ROOT/apps/other_mini_project.rb`, it will be mounted at:
   `/other-mini-project` endpoint.
 
+### `mount_path: /a/b/c/d`:
+
+Prefix URL for child apps with the given string, such that a child app 
+that was to be mounted on `/child-app`, will now be mounted at: 
+`/a/b/c/d/child-app`.
+
+### `app_dir: apps`:
+
+Customize the name of the directory used to host all child apps.
+
+## Middleman Layouts
+
+Child apps can use Middleman layouts, if required. This is useful to 
+keep a seamless appearance across the `umbrella` application.
+
+To use Middleman layouts, inherit your child app from 
+`Middleman::Apps::Base` and call `middleman_layout` with appropriate 
+layout name, like this:
+
+    require 'middleman/apps/base'
+
+    class TestApp < Middleman::Apps::Base
+      get '/' do
+        middleman_layout :page, locals: { var: value }
+      end
+    end
+
+The above call to `middleman layout` will try to render 
+`source/layouts/page.erb` layout from Middleman and pass it specified 
+options or locals.
+
+## Listing child apps on a Middleman Page
+
+    # in: source/apps.html.erb
+
+    <section class="child-apps list">
+      <h3 class="title">Available apps:</h3>
+      <ul>
+        <% apps_list.each_with_index do |app, i| %>
+          <article>
+          <h2 class="title"><%= link_to app.title, app.url %></h2>
+          <p><%= app.html_description %></p>
+          </article>
+        <% end %>
+      </ul>
+    </section>
+
+- `title`, `url`, and `routes` for the application are added on their 
+  own.
+- To overwrite `title`, or provide `description`, or any other arbitrary 
+  metadata for your child app, you can make a call to `set_metadata(key, 
+  val)` in your child app (must inherit from `Middleman::Apps::Base`). 
+  
+- Markdown should be provided to `description`, which will be used to 
+  populate `html_description`.
+
+- Call `metadata` in your child app to have a peek at all the variables 
+  that can be accessed this way.
+
+For example:
+
+    require 'middleman/apps/base'
+
+    class SomeApp < ::Middleman::Apps::Base
+      get '/' do
+        'hello'
+      end
+
+      post '/' do
+        'done'
+      end
+
+      add_routes_to_metadata :get # only `get` routes in metadata
+      set_metadata :title, 'Awesome Application'
+      set_metadata :description, <<-MARKDOWN
+        # Description for this Child application
+
+        This will be added as a metadata property for this child app.
+      MARKDOWN
+    end
+
+## Notes/Gotchas
+
+- To setup `routes` metadata, call `add_routes_to_metadata` at the end 
+  of your child app (after, actually, defining your routes).
+
+- 404 error page is not shown in `development` mode, i.e. when running 
+  `middleman server`. A default `File Not Found` message is shown in 
+  this case, by Middleman.
+
+- When `relative_assets` is activated, 404 errors on 
+  `/deeper/pages/in/your/website` will have wrong assets, and layout for 
+  404 pages may be inconsistent with the rest of the site in this case.
+
 ## Community
 
 The official community forum is available at: http://forum.middlemanapp.com
@@ -183,3 +308,4 @@ Copyright (c) 2018 Nikhil Gupta. MIT Licensed, see [LICENSE] for details.
 
 [middleman]: http://middlemanapp.com
 [LICENSE]: https://github.com/nikhgupta/middleman-apps/blob/master/LICENSE.txt
+[Simple]: https://github.com/nikhgupta/middleman-apps/tree/master/fixtures/simple

data/features/e_asset_hash.feature

@@ -0,0 +1,17 @@
+Feature: Compatibility with other Extensions: AssetHash
+
+  @production @javascript
+  Scenario: Custom error page with AssetHash
+    Given successfully built app is running at "asset_hash"
+     When I go to "/unknown-app"
+     Then the status code should be "404"
+      And I should see text "404 - Not Found!"
+      And I should not see text "Error"
+
+  @production @javascript
+  Scenario: Custom error page with AssetHash
+    Given successfully built app is running at "asset_hash"
+     When I go to "/unknown-app/some/deep/nested/url"
+     Then the status code should be "404"
+      And I should see text "404 - Not Found!"
+      And I should not see text "Error"

data/features/{directory_indexes.feature → e_directory_indexes.feature}

@@ -1,18 +1,14 @@
-Feature: Compatibility with other Extensions
+Feature: Compatibility with other Extensions: DirectoryIndex
 
   # Use custom error page for `middleman-apps`:
   # with Directory Indexes on - using `find_resource_by_path`
   Scenario: Custom error page with Directory Indexes
-    Given a fixture app "simple-app"
-      And a file named "source/custom.html.erb" with:
+    Given a fixture app "dir_index"
+      And a file named "source/error.html.erb" with:
           """
           <h2><%= 404 %> Custom Not Found!</h2>
           """
-      And app is running with config:
-          """
-          activate :directory_indexes
-          activate :apps, not_found: "custom.html"
-          """
+      And app is running
     When I go to "/unknown-app"
     Then the status code should be "404"
     And  I should see "<h2>404 Custom Not Found!</h2>"
@@ -20,16 +16,17 @@ Feature: Compatibility with other Extensions
   # Use custom error page for `middleman-apps`:
   # with Directory Indexes on - using `find_resource_by_destination_path`
   Scenario: Custom error page with Directory Indexes
-    Given a fixture app "simple-app"
-      And a file named "source/custom.html.erb" with:
+    Given a fixture app "dir_index"
+      And a file named "source/error.html.erb" with:
           """
           <h2><%= 404 %> Custom Not Found!</h2>
           """
-      And app is running with config:
+      And I overwrite the file named "config.rb" with:
           """
           activate :directory_indexes
-          activate :apps, not_found: "custom/index.html"
+          activate :apps, not_found: "error/index.html"
           """
+      And app is running
     When I go to "/unknown-app"
     Then the status code should be "404"
     And  I should see "<h2>404 Custom Not Found!</h2>"
@@ -37,16 +34,17 @@ Feature: Compatibility with other Extensions
   # Use custom error page for `middleman-apps`:
   # with Directory Indexes on - using `find_resource_by_page_id`
   Scenario: Custom error page with Directory Indexes
-    Given a fixture app "simple-app"
-      And a file named "source/custom.html.erb" with:
+    Given a fixture app "dir_index"
+      And a file named "source/error.html.erb" with:
           """
           <h2><%= 404 %> Custom Not Found!</h2>
           """
-      And app is running with config:
+      And I overwrite the file named "config.rb" with:
           """
           activate :directory_indexes
-          activate :apps, not_found: "custom"
+          activate :apps, not_found: "error"
           """
+      And app is running
     When I go to "/unknown-app"
     Then the status code should be "404"
     And  I should see "<h2>404 Custom Not Found!</h2>"

data/features/e_relative_assets.feature

@@ -0,0 +1,17 @@
+Feature: Compatibility with other Extensions: RelativeAssets
+
+  @production @javascript
+  Scenario: Custom error page with RelativeAssets
+    Given successfully built app is running at "relative_assets"
+     When I go to "/unknown-app"
+     Then the status code should be "404"
+      And I should see text "404 - Not Found!"
+      And I should not see text "Error"
+
+  @production @javascript @wip
+  Scenario: Custom error page with RelativeAssets
+    Given successfully built app is running at "relative_assets"
+     When I go to "/unknown-app/some/deep/nested/url"
+     Then the status code should be "404"
+      And I should see text "404 - Not Found!"
+      And I should not see text "Error"

data/features/f_code_reloading.feature

@@ -0,0 +1,134 @@
+Feature: Code reloading for child apps
+
+  @mechanize @development
+  Scenario: Allows reloading in development server
+    Given a fixture app "real_world"
+      And server is running in background
+     When I go to "/child-app" on local server
+     Then I should see "hello my world"
+     When I overwrite the file named "apps/child_app.rb" with:
+          """
+          require 'middleman/apps/base'
+          class RealWorld::ChildApp < ::Middleman::Apps::Base
+            get '/' do
+              "reloaded #{named} world"
+            end
+            def named; 'other'; end
+          end
+          """
+      And I go to "/child-app" on local server
+     Then I should see "reloaded other world"
+
+  @mechanize @development
+  Scenario: Allows reloading for apps without any namespace
+    Given a fixture app "real_world"
+      And server is running in background
+     When I go to "/no-name" on local server
+     Then I should see "pass"
+     When I overwrite the file named "apps/no_namespace.rb" with:
+          """
+          require 'middleman/apps/base'
+          class NoNamespaceApp < ::Middleman::Apps::Base
+            get '/' do
+              "reloaded"
+            end
+          end
+          """
+      And I go to "/no-name" on local server
+      Then I should see "reloaded"
+
+  @mechanize @development
+  Scenario: Throws 404 when child app is suddenly ignored
+    Given a fixture app "real_world"
+      And server is running in background
+     When I overwrite the file named "apps/child_app.rb" with:
+          """
+          require 'middleman/apps/base'
+          class ChildApp < ::Middleman::Apps::Base
+            get '/' do
+              "reloaded #{named} world"
+            end
+            def named; 'other'; end
+          end
+          """
+      And I go to "/child-app" on local server
+      Then the status code should be "404"
+
+  @mechanize @production
+  Scenario: Do not allow reloading of apps in production
+    Given a fixture app "real_world"
+      And server is running in background
+     When I go to "/child-app" on local server
+     Then I should see "hello my world"
+     When I overwrite the file named "apps/child_app.rb" with:
+          """
+          require 'middleman/apps/base'
+          class RealWorld::ChildApp < ::Middleman::Apps::Base
+            get '/' do
+              'hello world\n' * n
+            end
+            def n; 2; end
+          end
+          """
+      And I go to "/child-app" on local server
+     Then I should see "hello my world"
+
+  @mechanize @development
+  Scenario: New child apps are loaded automatically
+    Given a fixture app "real_world"
+      And server is running in background
+     When I go to "/unknown-app" on local server
+     Then the status code should be "404"
+      And I should see "File Not Found"
+     When I write to "apps/unknown_app.rb" with:
+          """
+          require 'middleman/apps/base'
+          class RealWorld::UnknownApp < ::Middleman::Apps::Base
+            get '/' do
+              "I am now!"
+            end
+          end
+          """
+      And I go to "/unknown-app" on local server
+     Then I should see "I am now!"
+
+  @mechanize @production
+  Scenario: New child apps are NOT loaded automatically
+    Given a fixture app "real_world"
+      And server is running in background
+     When I go to "/unknown-app" on local server
+     Then the status code should be "404"
+      And I should see "Not Found"
+     When I write to "apps/unknown_app.rb" with:
+          """
+          require 'middleman/apps/base'
+          class RealWorld::UnknownApp < ::Middleman::Apps::Base
+            get '/' do
+              "I am now!"
+            end
+          end
+          """
+      And I go to "/unknown-app" on local server
+     Then the status code should be "404"
+      And I should see "Not Found"
+
+  @mechanize @development
+  Scenario: Removing child apps removes them from server
+    Given a fixture app "real_world"
+      And server is running in background
+     When I go to "/child-app" on local server
+     Then I should see "hello my world"
+     When I remove the file named "apps/child_app.rb"
+      And I go to "/child-app" on local server
+     Then the status code should be "404"
+      And I should see "File Not Found"
+
+  @mechanize @production
+  Scenario: Removing child apps does NOT remove them from server
+    Given a fixture app "real_world"
+      And server is running in background
+     When I go to "/child-app" on local server
+     Then I should see "hello my world"
+     When I remove the file named "apps/child_app.rb"
+      And I go to "/child-app" on local server
+     Then I should see "hello my world"