Main Contents¶
Installation Guide¶
Installing UCS itself¶
Before using ucs to install components, you first need to install ucs itself!
To install ucs, we need to add a PPA
sudo add-apt-repository ppa:ubuntu-touch-community-dev/ppa
sudo apt-get update
sudo apt-get install ucs
Finding Components¶
Use the search command to search for available components by name or description.:
$ ucs search state
Matching curated components:
EmptyState
Matching community components:
(no matches)
$ ucs search podcast
Matching curated components:
(no matches)
Matching community components:
sil/GenericPodcastApp A component which manages a podcast RSS feed, with playback and display of episodes
You can list all components in the store, both curated and community components, with ucs search.
Installing Components¶
You can install components individually using the install command,
ucs install EmptyState
ucs install PageWithBottomEdge
ucs install sil/GenericPodcastApp
Note
Remember to run the ucs command from inside your application’s component folder!
You can then use the components by importing it in your qml files by,
import ubuntu_component_store.Curated.EmptyState 1.0
import ubuntu_component_store.Curated.PageWithBottomEdge 1.0
import ubuntu_component_store.sil.GenericPodcastApp 1.0
Note
Community components are named as developer/ComponentName. Curated components are installed with just a ComponentName (like ucs install EmptyState), but when importing them in QML you must call them ubuntu_component_store.Curated.EmptyState as above.
Updating Components¶
You can also update the UCS components using the ucs script. It will automatically fetch the latest upstream code.
ucs update EmptyState
Note
Remember to run the ucs command from inside your application’s component folder!
You can see the full ucs script help using the help argument,
ucs help
Contributing to UCS¶
There are two sorts of components in the Ubuntu Component Store: Curated components and Community components. As a developer, you can publish your component to either. Components in the Curated store have higher requirements to ensure that they are high-quality; anyone can publish to the Community store without approval.
Contributing a component¶
Contributing a component to the Curated store¶
Ubuntu Component Store is intended to be a community project where app developers are encouraged to contribute any component that they think would be useful to other developers. To contribute a component to UCS, we recommend first joining the team by applying here. This would then make it possible for you to maintain your component by pushing bug fixes and improvements as and when you choose.
By moderating the members of the team and components in UCS, we can promise a well tested component with a stable API. We recognize that this can impede the rate at which new components can be added to UCS, but we feel that this is an acceptable drawback to ensure good quality components to our userbase.
Let’s go through the steps required to upload a new component to the store.
Getting Started¶
You can technically contribute new components to the store without being a member of the team by requesting someone from the team to maintain your component. However we highly recommend that you join the team since that would allow you to push bug fixes and improvements to your component quickly. You can apply to become a member by applying here. The approval should be done within a day or two.
UCS is hosted on launchpad and requires bazaar (bzr) to grab or push the code. As such you would need to have an account on launchpad and be familiar with bzr. You can grab the code by,
bzr branch lp:component-store
UCS by itself is an ordinary QML project. You should be able to open it using qtcreator like any other project. Run the UCS Gallery app by either pressing the green button in qtcreator or via the command line as shown below,
qmlscene main.qml
This should open the UCS Gallery app as shown below. It provides a visual overview of all the components in the store.
Note
At the time of writing this documentation, you would need a 14.10 desktop to run the component store gallery. You can run the gallery app on the phone or emulator using a 14.04 desktop, however the gallery app doesn’t converge well on the phone yet. This should be fixed soon.
Adding a new component to the store¶
Adding a new component to the store involves 3 main steps which are,
- Adding a new component to the ComponentStore folder
- Updating the gallery app to showcase your new component
- Updating the documentation
The components are stored in their own folders in the ComponentStore folder. Let’s assume for illustration purposes, we are trying to add a new component MyNewComponent to UCS. Let’s grab UCS first and then add the new component.
bzr branch lp:component-store MyNewComponentBranch
Let create a new folder for our component in the ComponentStore folder,
cd MyNewComponentBranch/ComponentStore
mkdir MyNewComponent && bzr add MyNewComponent
cd MyNewComponent
Inside your MyNewComponent folder, add your generic component files. Everything that is required to use your component must be included in this folder. Let’s now add these files to the source control bzr and commit them.
bzr add *
bzr commit -m "Added my new component"
Now that we have our component ready and added, let’s update the gallery app to show that. Create a new file in the GallerySRC folder called MyNewComponentWidget.qml. This file is rather easy to fill out. Just copy the code from the other widget template files. It basically involves filling in information like the author, license, contact and a description of your component which is rather simple. Once completed, add MyNewComponentWidget.qml to the version control.
cd GallerySRC
bzr add MyNewComponentWidget.qml
bzr commit -m "Showcase new component in the gallery"
Next, open WidgetsModel.qml and add your component to the list. That’s it! Run the gallery app and see if your component shows up as expected.
This is one of the most important steps and benefits of adding your component to UCS. By providing a well written and clear documentation you make it easier for other app developers to use your component in their app. All the documentation is hosted in the docs folder. Create a new documentation file in the _components folder and fill in the necessary documentation. Use the existing documentation files to help you with setting it up.
Once done, add your component to the list in index.rst. Now let’s test if the documentation looks good. To build the documentation, you need sphinx and pip packages to be installed. Let’s install that for the first time.
sudo apt-get install pip
sudo pip install sphinx sphinx-autobuild
Building your documentation is now really simple. Once the build process is complete, open _build/index.html in your browser to see your documentation.
make html
Once again, let’s add this to the version control.
cd docs/_components
bzr add MyNewComponent.rst
bzr commit -m "Added documentation for the new component"
That was it! Your component is ready. Let’s push this online to UCS.
bzr push lp:~launchpad-id/component-store/MyNewComponentBranch
From there on, it is just a matter of reviewing the code (for new components, we try to ensure everything is in order) and then merging to trunk.
Contributing a component to the Community store¶
To publish an Ubuntu SDK component to the Community store, you will need a Launchpad account, and you will need to be familiar with using bzr to push code to Launchpad.
Community components can be pure QML, or they can be compiled binary components.
Publishing a pure QML component¶
Create a branch on Launchpad (in any project of your choice) which is named how you plan to name the component, with a top-level qml folder, and put your QML file and any required assets for your component in that qml folder. Add an ubuntu_component_store.json file. Then, submit the component to the community store with ucs submit lp:~username/project/branch.
So, your branch should look like:
/qml/
MyComponent.qml
required_image.png
included_script.js
/ubuntu_component_store.json
If your component does not have any external assets, it is fine to have a branch with qml/MyComponent.qml and nothing else in it. Your branch may also contain any other files you choose outside the qml top-level folder; these files are not installed with your component, but may provide useful guidance, READMEs, or other code for people who want to make changes to the component and contribute them back to you.
The name of the component itself is defined by ubuntu_component_store.json; the QML filename is what names the QML Item that it provides. So, if you are Launchpad user sil, and you push your component to lp:~sil/SomeProject/mything, it defines its own name in ubuntu_component_store.json as UsefulComponent, and it contains qml/RedRectangle.qml, an app developer will use it like this:
import QtQuick 2.0
import ubuntu_component_store.sil.UsefulComponent 1.0
....
MainView {
RedRectangle {
....
}
}
Most components should have component name and QML file name be the same thing to avoid confusion.
Do not publish two unrelated QML components in one UCS component; publish them separately, so they can be used separately.
Note
if you do not want to create a whole Launchpad project just for this component, you can push to a Launchpad “junk” branch: lp:~username/+junk/somename
Once your branch is created, publish it to the Community store with
$ ucs submit lp:~username/project/somename
(submitting to community repository)
Checking Launchpad branch lp:~username/project/somename
Checks passed OK
Calculated package summary data
Updating master record
Component username/ComponentName updated successfully
It should then be visible to ucs search.
Note
Once added to the community store, there is no way (yet) to remove your component.
Publishing a compiled component¶
Publishing a compiled component is a little more complicated, for CPU architecture reasons. Your component must be an Extension Plugin, “a plugin library to make it available to the QML engine as a new QML import module”. Creating such a plugin is currently beyond the scope of this document. (We are hoping to provide an Ubuntu SDK IDE template for creating such components with the proper filesystem layout; before then, the “App with QML Extension Library” option creates an appropriate type of component.)
You must compile your component for three different architectures: ARM, x86, and amd64 (for Ubuntu phones, the desktop emulator, and Ubuntu desktops). Once you have compiled it as such, you will have three different libMyComponent.so files.
Assemble a Launchpad branch with a top-level qmllib folder, and in it put a folder for each architecture, named for the GNU architecture triplet, and then the .so file within. So:
/qmllib
/x86_64-linux-gnu
/libMyComponent.so
/i386-linux-gnu
/libMyComponent.so
/arm-linux-gnueabihf
/libMyComponent.so
/ubuntu_component_store.json
Add an ubuntu_component_store.json file to the root of the branch.
Your branch may contain any other files of your choice outside the /qmllib folder; in particular, it should contain the source code for the plugin so others can build it themselves if they choose!
The name of the component itself is defined by ubuntu_component_store.json; your component is expected to use qmlRegisterType to provide QML Item types. So, if you are Launchpad user sil, and you push your component to lp:~sil/SomeProject/Whatever, it defines its name in ubuntu_component_store.json as SomeComponent, and it registers a Triangle type, an app developer will use it like this:
import QtQuick 2.0
import ubuntu_component_store.sil.SomeComponent 1.0
....
MainView {
Triangle {
....
}
}
Do not publish two unrelated components in one UCS component; publish them separately, so they can be used separately.
Note
if you do not want to create a whole Launchpad project just for this component, you can push to a Launchpad “junk” branch: lp:~username/+junk/somename
Once your branch is created, publish it to the Community store with
$ ucs submit lp:~username/project/somename
(submitting to community repository)
Checking Launchpad branch lp:~username/project/somename
Checks passed OK
Calculated package summary data
Updating master record
Component username/ComponentName updated successfully
It should then be visible to ucs search.
A component can contain both qml and qmllib folders and so contain both QML parts and binary parts; both will be installed when a developer uses ucs install to install your component.
ubuntu_component_store.json¶
A community component must contain a file ubuntu_component_store.json describing metadata about the component. It must be valid JSON, with keys name, version, and description:
{
"name": "GenericPodcastApp",
"version": "1.0",
"description": "A component which manages a podcast RSS feed, with playback and display of episodes"
}
Other keys may be added in future. Note that the public name of the component will be launchpadusername/name, where name is the name taken from ubuntu_component_store.json. The branch name in Launchpad is ignored.
Release Notes¶
13th April 2015
- Reorganized UCS by adding a Curated and Community Store.
- Added Bottom Edge Tabs component
23rd March 2015
- Added haptic feedback to radial action buttons
- Added drop shadow to radial bottom edge hint
13th March 2015
- Improved ListItemWithActions components by adding the following new properties,
- showDivider - mimics SDK ListItem property
- showUnderscore - Shows an underscore under the active right side action
- enableHaptics - enables haptic effects on actions triggered
11th March 2015
- Added expandAngle property to radial bottom edge component to allow developers to specify the spread angle.
3rd March 2015
- Added WelcomeWizard component
- Fixed a typo in listitemwithactions documentation
23rd February 2015
- ListItemWithActions: Reset active action after executing it.
- ListItemWithActions has been fixed to use actions’s iconSource property to allow using icons that are not in the theme
4th January 2015
- Add ubuntu_component_store.json metadata files for curated components
15th November 2014
- Added radial bottom edge component
12th November 2014
- Fixed typos in the installation guide
- Added ListItemWithActions component
9th November 2014
- Fixed build warnings in CircleImage and PageWithBottomEdge documentation
- Added release notes to the documentation
- Released ucs 0.1.2
- Improved intall and update command to use less network bandwidth
- Fixed typos in the help command
8th November 2014
- Added Fastscroll Component
- Packaged ucs 0.1.1 and released to trusty, utopic and vivid using a PPA
- Improved index.rst and fixed typos
6th November 2014
- Added PageWithBottomEdge component
- Added iconColor property to EmptyState component
- Added images to EmptyState and CircleImage to make it more descriptive for users
4th November 2014
- First release of Ubuntu Component Store
- Added UCS Gallery
- Added EmptyState and CircleImage components
