omeka / omeka-s-developer Goto Github PK
View Code? Open in Web Editor NEWDocumentation for Omeka S developers
License: Other
Documentation for Omeka S developers
License: Other
When I was writing CSSEditor and reading the Events documentation, I couldn't discern what class identifier(s) to use with view.layout
.
This will likely call for @kimisgold consultation to lay out principles and structures
Part of #8
the advice about getView
is tricky as that's really specific to where you are
many/most places don't have a getView method to call
some places we pass $view in to the appropriate method or whatever to let you call stuff
i hesitate about the description of the use case for factories being "additional data"
it's other services that usually causes you to need a factory
i assume you need "common" in that view helper using partial example, when you're actually calling the partial
the user role bit of the example might be more confusing than helpful, i dunno
i think the major bit you don't cover is that you can take arguments in __invoke
that's the preferred and easiest way of getting in data, just make the theme writer pass it to you
I set up my routes and navigation in module.config.php
and couldn't figure out why they weren't working until I was advised to include getConfig()
in Module.php
. I don't think we currently have documentation on its usage.
When I was thinking about using external libraries with my module, I couldn't find any documentation on best practices for including them.
Largely parallel content exists in the Modules and Key Concepts sections.
The Modules content is better-quality, but obviously is pitched from a module viewpoint. Still, this should be the bulk of what's kept, I think.
What is the license for this repo?
Zend's spelling and the spelling used in the config files is "invokable" so we need to be using that spelling.
Large parts of the two modules pages are identical... likely different vintage copies of the wiki or something similar
Underneath Modules is probably the preferable place for this to go.
We have some of this in the API page but we should have a page that has every possible parameter.
The reorganization branch is an attempt to reorganize the docs in a more logical and intuitive fashion. This breaks internal links, but mkdocs can help us find and correct them. This also breaks the flow of some of the content, which we'll need to correct by proofing each page to fit into the new structure. We'll eventually have to change the order of the navigation, but that will have to wait until we finish organization.
But before I continue I need some eyes on the new organization. Does it make sense from a developer's perspective? A module developer? A theme developer?
- Omeka S Developer Documentation
- Contributing to Omeka S
- Debugging Omeka S
- For Omeka Classic Developers
- Registering an Addon
- Api
- Introduction to the API
- API Reference
- REST API
- Configuration
- Configuring Omeka S
- Configuration Reference
- Services and Factories
- Controllers
- Introduction to Controllers
- Controller Plugins
- Routes and Navigation
- ViewModel
- Events
- Client Event Reference
- Client Events
- Server Event Reference
- Server Events
- Miscellaneous
- Access Control Lists (ACL)
- Doctrine ORM
- Forms
- Internationalization
- Modules
- Introduction to Modules
- Data Model
- Data Types
- Media Ingesters and Renderers
- Page Blocks
- Themes
- Introduction to Themes
- Sass and CSS
- Style Guide
- Theme Modifications
- Theme Settings
- Views
- Introduction to Views
- Representations
- View Helpers
There are some new pages that need content:
@zerocrates This is a slight departure from where we left off yesterday. I've added back in the "Modules" section because "Themes" is a separate section and the contents of the (now deleted) "Extending" section are specific to modules. I moved the "Introduction to..." pages to their respective "Modules" and "Themes" sections. Also, I'm particularly interested in getting your help editing the page content to fit into the new "flow" that the organization imposes. I don't have the time to do this alone.
From the convo on omeka/omeka-s#1074 (comment)
This should go into the i18n documentation here.
Theming development needs more information
Tutorial.
This should be tutorial-type content:
hi there,
we are using omeka s in our library and a requirement for uploaded files (or URLs) appeared.
in order to show the right file version for the user, after he chooses the front end language, we need to catalog the file/URL language
curent field types dont allow this metadata to be inserted, so, would ther be any plugin to fulffill this requisit?
if not, what part of omeka source code need to be changed to allow this aditional descriptio for uploaded files
thanks!
The helpers folder, and what to put in config/theme.ini
I'm a fair amount through enough of the writing that it's worth asking at this point if/where I'm going astray in any aspects of the dev documentation. If you don't want to read markdown, the README has minimal info on how to build HTML to read it (how to incorporate a build into the real site is still up for grabs).
There are still lots of blank pages, but ones that have content under Key Concepts are:
These reflect a bunch of move-overs from the existing wiki, some of which contains updates for the current state of affairs.
Much more for me to work on, but no reason not to ask if people want to look now.
Any thoughts, @jimsafley @zerocrates @kalbers @kimisgold ?
Thanks
Generated documentation seems to be having diminishing returns since last investigated.
ApiGen is looking for a new maintainer. It's been painful and unsuccessful to revert back to the version that generated what we currently have. The latest fixes bugs, but eats up memory like crazy. It got 2% through the process, and had used up more than 25 GB of memory/swap. That puts us at needing more than a TB of memory to generate docs using it, unless my arithmetic is way off (always a possibility).
The fallback would be to look again at PHPDocumentor, which we didn't like much based on the output. It's had more activity lately, but we'd have to see if it runs through okay.
The content of the forum post about updating modules to 2.0.0 is a perfect example of what should go there.
Github now allows you to use actions that could create a release and attach a zipped version of the module for you. Putting an example action in the documentation (docs/register_an_addon.md
) might be very helpful. Here is the one I use for the Any Cloud module. You create a tag with the version of the module you want to create a release for (v2.2.3 for example) and the action takes over from there:
.github/workflows/release.yml
name: Release
on:
push:
tags:
- '*'
jobs:
release:
runs-on: ubuntu-latest
permissions:
contents: write
steps:
- name: "Checkout repository"
uses: "actions/checkout@master"
- name: "Set up PHP"
uses: "shivammathur/setup-php@v2"
with:
php-version: "latest"
- name: "Composer install"
uses: "ramsey/composer-install@v2"
with:
composer-options: "--ignore-platform-reqs --optimize-autoloader"
- name: "Create archive release"
uses: "thedoctor0/zip-release@master"
with:
filename: "{AddonZipName}.zip"
exclusions: "*.git* .tx/ language/*.po* .editorconfig phpcs.xml.dist"
- name: Upload Release
uses: ncipollo/release-action@v1
with:
artifacts: '{AddonZipName}.zip'
bodyFile: "RELEASE.md"
token: ${{ secrets.GITHUB_TOKEN }}
It downloads composer, installs the versions of the dependencies indicated in your composer.lock
file in the repository, zips everything up except what you put in the exclusions
section, and adds the text of RELEASE.md
as the text of the release.
In any case, this might be helpful to other developers and make things a little easier than manually uploaded a .zip
file to every release. Creating a git
tag for a release and letting GitHub do all the other work is really helpful.
Within Installation, it sounds there's more to fill in/clarify about both local.config and module.config, especially overriding in local.config
The documentation for the API lists out resources available, but it looks like the resources Resource isn't publicly accessible.
There might be a difference here and there between the internal and external API behavior?
Currently, we guide toward the SQL statements for updating/migrating. But I don't immediately see where/how to invoke the event. That should be more prominent.
Also notable, the current docs are ant
-based, which seems to be going the way of the dodo
This omeka/omeka-s#852 should be added for module writers
As with API Request Options, [API Search Parameters] should have a defaults column.
Should cover:
The gulp stuff in the migrations section is actually for core, not modules
The docs/modules/introduction.md
page states that assets should be placed in an assets/
directory but Omeka S seems to only be looking for asset/
.
currently, it reads like the logger it automatically there. it isn't. it needs to be retrieved from the service locator
First draft, so much will change, but figuring out a sense of priorities, and whether the basic sections here need immediate adjustment should happen quickly. Any thoughts from @zerocrates @jimsafley @kalbers @kimisgold appreciated
If you are out of date, the suggested path to how to do updates ignores that multiple modules, and indeed core, could give SQL update instruction when running the update sql tool.
We'll need to give guidance about parsing that out for what a developer needs to pay attention to.
Per this convo omeka/omeka-s#1171 (comment)
Sounds like we should have a list of our own helpers, with limited guidance about Zend's helpers. We can't document all of Zend's stuff, but a handful of examples from Zend will help clarify the difference (and why we're not documenting all of theirs)
The paths in this documentation are all over the place - we have /default/collections/browse.phtml
and /default/views/omeka/site/collection
In the introduction, we have a singular 'view' for the theme:
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/
.
might be worth cleaning up.
Tutorial.
A declarative, efficient, and flexible JavaScript library for building user interfaces.
๐ Vue.js is a progressive, incrementally-adoptable JavaScript framework for building UI on the web.
TypeScript is a superset of JavaScript that compiles to clean JavaScript output.
An Open Source Machine Learning Framework for Everyone
The Web framework for perfectionists with deadlines.
A PHP framework for web artisans
Bring data to life with SVG, Canvas and HTML. ๐๐๐
JavaScript (JS) is a lightweight interpreted programming language with first-class functions.
Some thing interesting about web. New door for the world.
A server is a program made to process requests and deliver data to clients.
Machine learning is a way of modeling and interpreting data that allows a piece of software to respond intelligently.
Some thing interesting about visualization, use data art
Some thing interesting about game, make everyone happy.
We are working to build community through open source technology. NB: members must have two-factor auth.
Open source projects and samples from Microsoft.
Google โค๏ธ Open Source for everyone.
Alibaba Open Source for everyone
Data-Driven Documents codes.
China tencent open source team.