How to Build an App
The idea behind Apps is to use the existing building blocks of Drupal to create a more discoverable and usable set of functionality for a Drupal distribution. So, our goal is that building an App for a distribution is a simple and straightforward process. We've laid out the following steps to help accomplish the goal of planning, creating, and submitting your app to OpenPublic or OpenPublish. For more information about Apps generally, please see Apps Documentation. And if you're interested in learning about the Open App Standard please visit our groups at http://groups.drupal.org/open-app-standard
The process of building an app for a distribution can be summarized in four steps, each with a set of activities. They are:
1. Define the problem
2. Define the audience
3. Define the solution
4. Contact the team that manages the distribution to discuss inclusion
1. Identify contributed modules to use
2. Identify components you need to build
3. Identify what can be contributed back
4. Build the app's main module.
1. Prepare the app for its distribution
2. Build the configuration page
3. Build default content
4. Test your app
1. Put it somewhere!
-- Drupal.org or some other location
-- Create a project on d.o for it and add all of your content
-- Tag on d.o for distributions/ apps, etc. (?)
2. Submit the app
Let's get started.
Steps to Building an App
I. PLAN for your app
1. Define the Problem: What is the Problem we're trying to solve?
The first thing to understand is the exact, specific problem you're trying to solve.
At Phase2, many of our ideas for Apps come from active projects, and the process of "solving a specific problem" is built into our solutions analysis here at Phase2. However, as we look toward more community-generated Apps, it will be important for all of us to engage in more community-generated solutions to the business problems emerging within the group.
One way to do this is to take a page from traditional product design, and take a look at existing sites to see how the problem is being solved now:
- How is the data being published?
- What workarounds are people using?
- What third parties are engaged in this solution?
- What's missing from the current solutions?
- Which steps could be reduced or removed to make the process easier?
Example of a Problem to Solve: create a calendar to tell people what the agency is doing and when
2. Define the Audience: Who is this app for? (who is going to INSTALL the app?)
To begin, we think about the exact problem we're trying to solve and who we're trying to solve it for. Does it solve a problem for administrators or staff? Is it for a non-profit, local, state, or federal organization? Not every app is for every distribution user--if it was, it would be a better fit for the distribution's core installation. So, the first thing to do is to understand the person who will be using it. This includes both the people who will be implementing the app technically and those who will be using it on a day-to-day basis. If it will be used to regularly add content to a site, who will be the person using it? What is their level of knowledge of Drupal, of CMS, and of your app's specific area of knowledge?
Example of a Defined Audience: this is for a public sector organizations who need to publicize their events to their constituents
3. Define the Solution: How is this app used? Use Cases: how the admin and user interacts with the app. We're going to come back to these as we run into more as we go.
Once you've identified the problem and the audience, it's time to start building a solution. To start, consider building a couple of use cases, to show exactly what you want the end user and site administrator to be able to do with this app. Continuing our example above, let's look at some use cases for an event promotion app for OpenPublic:
a) Event app End-User
* End user viewing a calendar: From the homepage, follow the upcoming events link to a calendar. See an event name on the calendar; click on it and see what, where, when, who details of the event.
b) Event app Site Admin:
* Site administrator creates new content - add event: where, when, description, who, categorized(?). Create event. Appear on calendar.
Knowing these use cases, we can then build a solution. We start by looking at what we already have and asking ourselves: Is there an existing module that could be used for this App? Have we built this solution for a site before?
Then we look at the solution's main question: "what is the simplest and most concise way to solve this problem for this audience?" Often, there is more than one way to solve a problem, so understanding what the potential solution set is, and which solution solves the question best is key.
This is the point in the process when we find that it's helpful to return to the core elevator pitch and user we identified before. In considering the solution, we don't just consider the app's main module or function. We instead use a short checklist that considers the whole app's "experience" for our user:
Does our solution address the exact problem we identified?
Does our solution solve any other problems that need to be stripped out or broken up into two or more apps?
Can our solution be executed technically?
Our goal is to identify the enhancements that will make our App useable and easy to explore. If the solution we see in front of us is as concise and specific as the audience and the problem we've identified, we're on our way to a great app.
4. Contact the team managing the distribution to discuss inclusion
If you haven't yet, now is a great time to contact the team managing the distribution you are interested in to discuss your app. It may be that we have some ideas for how it might best serve the distribution's audience, or some suggestions on best practices for focusing the functionality of your app, so that it "solves a discrete problem for a specific audience, in a complete way."
5. Double check the checklist: apps checklist
-- Does it solve a specific, discrete problem?
-- Does it solve a problem for a specific audience?
-- Does it solve the problem completely?
-- Can you describe it in a minute or less?
II. BUILD your app's main module
1. What modules are we going to use?
First, it's important to consider whether there are existing modules that you can use to build your app. Apps do not seek to replicate existing contributed module functionality, and whenever possible, you should use contributed modules to accomplish your build. As best practice, we strongly recommend contacting the maintainer(s) of a module to let them know you intend to use it for an App you're creating, if you do not maintain that module yourself.
In our calendaring example, some ideas for contributed modules to use would be: Location module, calendar display
2. What pieces do we need to build just for this app?
The next step is to identify what functionality you might need to build specifically for this app. That can include modules, content type, views, and other aspects of the solution.
In our example, perhaps we'd choose to build a content type, a view and a block view, and a page view
3. What part of our functionality can we generalize into a new contributed module, or an enhancement to a current module?
In addition to using contributed Drupal modules to build your App, we strongly recommend contributing back any and all modules that you create specifically for this app. Apps are part of the open source Drupal community, and contributing back your modules is what helps the community grow.
4. Build the app's main module.
Build a module with the "custom" pieces, and with dependencies to the community contributed modules they've created or that already exist. A few recommendations to consider as you build your app's main module:
Kit Compliance: Your main app module should be KIT-Compliant. The KIT specification for Features can be found here:
Features: Your main app module should be Features-based. Documentation and instructions for packaging modules as features can be found here: http://drupal.org/node/580026
Apps API: You'll find the Apps API at apps.api.txt. Apps uses the standard hooks architecture of Drupal for its API. For your app, you'll need to implement the hook_apps_app_info in the module.
5. Build checklist
-- Did you seek out existing modules?
-- Did you contribute back new modules to Drupal.org?
-- Is it kit compliant?
-- Does it address the defined use cases?
III. PACKAGE your app
1. Prepare the app for its distribution
Now that you have your app's components built, it's time to package up the assets for submission. Here's how:
a. Gather Assets
i. screen shots
iv. contributor information
b. Build directory for all of the parts and add everything to it
c. Create the manifest.app file
The manifest.app should be an ini file with the following items
- Name of the App: example: Project Mapper
- Description that tells what it does and who its for, for the apps listing in the OpenPublic apps server.
- Example: "Open Public's Project Mapper is a great way to present your work on a beautiful map. It provides you with a landing page that shows your projects as pins on a map and as a grid of image thumbnails giving your users a quick way to get an overview of your activities. Each project has its own page for publishing detailed information. You can create new projects by simply logging on to your Open Public Site and filling-out a web form.",
- Machine name: name of the main module
- Version: which version of the app this is. e.g. 1.0-beta1
- Location: where the main module is found. e.g. http://drupal.org/files/projects/openpublic_projects _7.x-1.0-alpha3.tar.gz
- Author: who created this app; e.g. Development Seed
- Author URL: link to the author's site; e.g http://www.developmentseed.org
- Screenshots: an array of screen shot relative to the path of the manifest.app
- A list of screen shots that will show up in app interface. e.g.http://appserver.openpublicapp.com/sites/default/files/apps/project-mapper-screenshot1.jpg
- Logo: a logo or icon for the app itself; this path should be relative to the manifest.app path
- Dependencies: please list all the modules that need to be installed for the App to work; and any modules that those modules depend on. The key is the name of the module, and the value is the name of the downloadable of which it is a part
- Libraries: specify required libraries and reference the keys in downloadables
- Downloadables: please list all downloadables and the location from which they can be downloaded. Downloadables keys are referenced from the dependencies. You should also list your app module here so it can be downloaded.
d. App Specific Hook
This can be found in modules/apps/apps.api.php
In order to provide a more integrated experience to the App console your app should implement hook_apps_app_info. This module allows you to describe certain aspects of your Apps functionality to the App Console. This hook is to return an array with the following information
2. Build the configuration page
Oftentimes with Drupal modules, when you are finished installing you need to track down (if you even know to look) where the modules many configuration forms are. Sometimes they are in admin/config sometimes they are in admin/structure, other times in a more specialized location. The point is that, currently in Drupal, once a module is enabled you need to track down some forms to allow for information gathering and configuration. Drupal 7 makes it a step better by providing a configuration link in the modules page but sometimes you want/need more.
Here is where Apps shine, giving you a configuration form presented immediately after enabling your module and in the context of where you read about, downloaded, and enabled your App. At any point in the future you can return to the App Console and find your app and configure it directly form the console. This config form can be use to gather API keys, set permissions or any other thing might need to do. This configuration destination also natively support the enabling/disabling of demo content.
3. Build default content
One of the hardest things about installing new functionality in Drupal is that often times you never know quite how to use it. The demo content functionality of Apps aims to lower the barriers to using an App by provide soem default content that can be easily enabled and disabled. Demo content can be implement in any way you see fit. Some options are:
- Manually create nodes, taxonomy, menus, etc and track their individual ids to that they can be removed later.
- Use Feeds to import/export content from included data files (see: Ideation app)
- Use Default Content to give Nodes machine names and export them with Features
- Use UUID Features to export content into Features for inclusion.
There are countless ways to crack this nut, the real goal here though is that you can turn this content on AND OFF. This allows a user to play with content to see how it works and when they are done, disable the module and have all of that installed content disappear so they can start building their own content.
It's important, once your app is built, to test it thoroughly before submitting it.
The Apps module provides Development Mode, a way to locally develop and test apps.
- Enable the development console from the Apps Configuration page located at admin/config/system/apps
- Reference the manifest from the module.info and make sure the server is development:
apps[INST:server] = development
apps[INST:manifests] = app/manifest.app
and place your manifest and images in a subfolder of the module
5. PACKAGE Checklist:
a. Can the app install?
b. Can you configure the app?
c. Can you turn on and off default content?
d. Can you uninstall it?
e. Does it show up everywhere it's supposed to on installation, and disappear as needed on uninstall?
IV. SUBMIT your app
- Create a project on Drupal.org for it and add all of your content
- Create a release for your project
- Tag on d.o for distributions/apps
Submit your app
What You Need to Provide:
To submit your app, please create a .zip or .tar file with a manifest.app file as well as any image referenced in the manifest.
How OpenPublic and OpenPublish Apps are Selected
The decision on how to select and approve Apps for a distribution is up to the distribution's owner. For OpenPublic and OpenPublish, we've built the following process for evaluating and collaborating with others on Apps:
Goals & Process for Including Contributed Apps in OpenPublic and OpenPublish:
1. Ideas & Collaboration: The goal is to collaborate with contributors from the idea stage, helping apply best practices for OpenPublic and OpenPublish to the creation of the app. This includes providing excellent documentation, training, and collaborative support through code sprints and one-on-one interaction. This first step should help to identify App solutions that are appropriate for OpenPublic's and OpenPublish's users, and that fit well within the Apps structure.
2. Support for Building: The goal is for our technical team at OpenPublic and OpenPublish to be available and responsive to App contributors as they work through the process of developing and building their App. This can include one-on-one interaction, as well as training and documentation, and will be provided as requested, as well as through some regular group opportunities, such as at Drupal camps and meet-ups.
3. Testing and Submission: The goal is to make the testing and submission process for Apps for OpenPublic and OpenPublish transparent and as simple as possible. We are continuing to build components of the Apps module to aid the testing and submission process for Apps in OpenPublic and OpenPublish. In addition to this, we'll provide useful feedback on testing results to app contributors, to help ensure successful inclusion in the distribution.
4. Technical Review & Approval: The goal is to provide helpful feedback and ensure the inclusion of technically solid Apps for the distribution. Whenever possible, this includes providing feedback on things that are not working, with specific recommendations for making them suitable for inclusion.
5. (Ongoing) Update & Approval: The goal is to provide ongoing support to App contributors as they provide updates to their Apps. Support in the form of testing and review of updated Apps will help to ensure best practices on an ongoing basis.
Evaluation Criteria for Inclusion in OpenPublic and OpenPublish:
As distribution owners, we are advocates for consumers of OpenPublic and OpenPublish, trying to create consistency and confidence in using Apps in these distributions. We are not interested in "cherry-picking' specific apps or showing preference for specific organizations, companies, or solutions. Apps for OpenPublic and OpenPublish, even if they have similar functionality or form, should co-exist in the App console, as certain solutions may be better for certain audiences.
A great app in OpenPublic and OpenPublish will have the following:
1. A clear solution to a discrete problem for the OpenPublic and OpenPublish audiences:
- It solves a specific, discrete problem
- It solves a problem for a specific audience
- There's a defined use case for a public sector user
- It solves the problem completely
- It can be described quickly and easily
2. Sound architecture and construction
- There's a configuration panel
- There's default content to show what it does
- You can turn off and turn on that default content.
- The description matches the functionality
- It installs and uninstalls cleanly
- It shows up everywhere it's supposed to on installation
- It disappears as needed on uninstall
- It is KIT compliant, if it is a Feature
- The app's functionality meets the defined use cases
- It does not simply package a contributed Drupal module, but integrates functionality in OpenPublic
3. It is reliable in its representation, stability, and functionality in the Apps console for OpenPublic:
- The assets (e.g screenshots, icons, contributor information) are complete and of high quality
- The descriptions are well written and easy to understand to a non technical user
- There is nothing inappropriate or illegal represented in the app or its description
- The app does not infringe on anyone else's copyright or trademarked material
- It exists on a stable server. We always consider drupal.org to be a stable server, but there are others such as GitHub, etc.