tag:blogger.com,1999:blog-92173566396623948712024-02-08T00:07:17.260-06:00Cognifloyd's CognifireAnonymoushttp://www.blogger.com/profile/14944134144016532385noreply@blogger.comBlogger19125tag:blogger.com,1999:blog-9217356639662394871.post-61356039347453078052015-07-21T15:12:00.000-05:002015-07-21T15:22:19.899-05:00An Image Web-Service for Documentarians<h2>
The Pain</h2>
I’ve been writing docs for the Neos project, watching for ways to make it easier for more people to get involved. The Neos Editor Guide (a user manual I’m writing) really needs a lot of screenshots to be effective for the end-users that need it. But, creating docs with visuals is annoying at best, even for a technical writer like me. Screenshots are annoying to produce, and keeping them up-to-date is painful. I want to create something to make this part of documentation easier to produce and maintain.<br />
<br />
As you write the docs, you need to create screenshots. You could interrupt the flow of writing to go create the screenshot, and then struggle to get back into the flow of writing. Or, you could try and make notes on what screenshots are needed and deal with making them later. Hopefully, you won't miss any of the image placeholders in the docs. Whichever workflow you choose, switching contexts like that causes a lot of mental friction. Taking screenshots is annoying. Plus, it’s hard to get someone else to create the screenshots for you because they have to have both sets of tools as well.<br />
<br />
And then, someone’s got to maintain the docs. How many times have you seen manuals where the screenshots are 5 or 10 years old? Once you write a doc with lots of screenshots, no one will ever update it; If someone does update it, they won’t update the screenshots. Screenshot maintenance is tedious, so no one does it.<br />
<br />
<h2>
The Seed of an Idea</h2>
What if we automated screenshots? There are a variety of tools that we could use to do this, including <a href="http://behat.org/">Behat</a>, <a href="https://cucumber.io/">Cucumber</a>, <a href="http://phantomjs.org/">phantomjs</a>, <a href="https://www.ffmpeg.org/">ffmpeg</a>, etc. Then, you could describe the required screenshot in the doc you are writing and let <a href="http://sphinx-doc.org/">Sphinx</a> call the other tools to generate the screenshots. However, automating image creation will create a lot of images. If you keep your docs in a git repository, like I do, your git repository will quickly bloat with all those images; that kind of bloat makes git fetches slower and makes turns the git experience into an annoyance.<br />
<br />
So, what if all of those screenshots were stored in some external service like Dropbox or Google Drive, or some other CDN(-like) service? Then, Sphinx (or whatever doc generator you use) would need a way to get the URI of those images without hard-coding them in the docs.<br />
<br />
<h2>
A Solution</h2>
So, I'm building a web-service for documentation visuals like screenshots. The service will take an image description (sent by Sphinx or some other doc generator like Jekyll, WikiMedia, or Confluence), and return an image URI. In the background it can let users upload the screenshots or automatically create them with something like Behat. Let's say goodbye to user manuals with screenshots that are out-of-date.<br />
<br />
While writing the docs, the author just includes a description of the screenshot. Then, as far as the author is concerned, the description of the screenshot gets replaced with an actual screenshot. No more context switching between writing and taking screenshots. Someone else or some other program can deal with actually taking the screenshots.<br />
<br />
Imagine a website like crowdin where people upload screenshots instead of localizations. The website would list the screenshot descriptions and let users upload a screenshot for each one. Automate what we can, and leave the rest to volunteers. That gives more people a way to contribute to the docs.<br />
<div>
<br /></div>
<h3>
Thanks!</h3>
<div>
<i>The TYPO3 Association <a href="https://forge.typo3.org/boards/22/topics/505">funded</a> the initial development of these ideas. Check out TYPO3 CMS at <a href="http://typo3.org/">typo3.org</a>. To all of the TYPO3 Association members who have supported this effort: Thank You!</i></div>
Anonymoushttp://www.blogger.com/profile/14944134144016532385noreply@blogger.com0Virginia, USA37.4315734 -78.65689420000001137.4315734 -78.656894200000011 37.4315734 -78.656894200000011tag:blogger.com,1999:blog-9217356639662394871.post-55797239643290473842015-06-25T23:03:00.000-05:002015-06-25T23:03:27.846-05:00A generic screenshot webservice for documentation@mathias.schreiber gave me some <a href="https://typo3.slack.com/archives/t3a-eab/p1435219984000138">great feeback on Slack</a> about the tools I want to build as part of my T3A budget (see my <a href="http://cognifloyd.blogspot.com/2015/06/roar-docs-docs-docs.html" target="_blank">most recent blog post</a>):<br />
<blockquote class="tr_bq">
we plan to move this away from rst anyways, thus I ask myself how we benefit from the toolset</blockquote>
He also clarified that he's only talking about finding a tool that's easier to use, like Confluence, and it would only be for the manuals, not the reference documentation. And, he also tried to make it very clear that they aren't changing document formats right now, and there hasn't even been any official conversations in the ML. There are only plans, so far.<br />
<br />
I'm really glad he pointed out this possibility on the horizon. Now, I need to generalize any tools I make so that they can be used by Confluence, Sphinx, or (almost) any other documentation tool that serves the needs of the project. Knowing it is on the horizon, I can design the tools to work in that context.<br />
<br />
Here's my first stab at generalizing the screenshot tools.<br />
<br />
Instead of starting with screenshot generation, I'm going to start with a simple web service that allows some kind of input (just an image id for the MVP, and later, it will accept a full behat scenario to describe the image that should be generated) and return a final image URI. (initially the image will serve up some placeholder/transparent image that is set to expire very quickly, and later the placeholder can be replaced with the generated image) This way, frequently regenerating screenshots in user manuals will not cause the git repo to bloat significantly. This will allow us to put the images directly in some kind of CDN service (an actual CDN if needed, or something like Dropbox or maybe Google Drive).<br />
<br />
For the first MVP of this web service (which will only be accessible to a clients that are whitelisted, such as build.docs.typo3.org.), I will still manually generate any screenshots/screencasts. In the next phase, I will integrate behat (or something similar) that can describe the screenshots that should be generated. I'll add the ability to annotate screenshots later on.<br />
<br />
This way, a description of the necessary screenshots can be embedded in manuals without requiring the document author to generate the screenshot (thus breaking the flow of writing the document). Then that description gets sent to the web service where something (or someone) takes the description and generates the required screenshot and makes it available at the URI provided by the web service. Even without automating the screenshot, this will allow the author, or other contributors, to go through the queue and generate all of the needed screenshots with the annotations.<br />
This service would then need a sphinx plugin, or a wikimedia plugin, or a confluence plugin, or whatever tool is used to write manuals.<br />
<br />
So, my budget can be useful to both TYPO3 and Neos, even if one or both teams decides to move the user manuals away from restructured text format.Anonymoushttp://www.blogger.com/profile/14944134144016532385noreply@blogger.com0tag:blogger.com,1999:blog-9217356639662394871.post-65213544034160799862015-06-25T01:14:00.000-05:002015-06-25T23:03:38.085-05:00Roar: Docs! Docs! Docs!<i>Update: I've responded to some great technical feedback on how my budget can help TYPO3 <a href="http://cognifloyd.blogspot.com/2015/06/a-generic-screenshot-webservice.html">here</a>.</i><br />
<br />
This welcome conversation caught my attention on Twitter this week. I couldn’t get my comments to fit within 140 characters, so I’m responding here. Here are the tweets (without the twitter handles):<br />
<ul>
<li><b><a href="https://twitter.com/sorenbryder">@sorenbryder</a>:</b> (<a href="https://twitter.com/sorenbryder/status/613354907488374784">tweet</a>)<br />“Documentation & Documentation Tools for Neos/Flow” for 2015 is EUR 13,750. At present, 0% of this budget have been used." Come on! #neoscms</li>
<li><b><a href="https://twitter.com/AskeErtmann">@AskeErtmann</a>:<span style="font-weight: normal;"> (<a href="https://twitter.com/AskeErtmann/status/613359129793548288">tweet</a>)</span></b>This is a budget for @cognifloyd who wanted to spent time working on that now, but didn't start due to the budget situation..</li>
<li><b>@sorenbryder:<span style="font-weight: normal;"> (<a href="https://twitter.com/sorenbryder/status/613361695545798656">tweet</a>)</span></b>Okay, sounds good then. Better documentation is really needed, but this isn't news to anyone :)</li>
<li><b><a href="https://twitter.com/kdambekalns">@kdambekalns</a>:<span style="font-weight: normal;"> (<a href="https://twitter.com/kdambekalns/status/613800800125632512">tweet</a>)</span></b>@sorenbryder And even better: The #TYPO3 documentation will probably profit from his work as well!</li>
<li><b><a href="https://twitter.com/mattLefaux">@mattLefaux</a>:<span style="font-weight: normal;"> (<a href="https://twitter.com/mattLefaux/status/613801033249239041">tweet</a>)</span></b>go on</li>
<li><b>@kdambekalns:<span style="font-weight: normal;"> (<a href="https://twitter.com/kdambekalns/status/613801414251413504">tweet</a>)</span></b>Go [on] with… the work? Or explaining what it is about?</li>
<li><b>@mattLefaux:<span style="font-weight: normal;"> (<a href="https://twitter.com/mattLefaux/status/613801564738732032">tweet</a>)</span></b>if it’s a joint venture, the budget situation can easily be resolved. Need roar info</li>
<li><b>@kdambekalns:<span style="font-weight: normal;"> (<a href="https://twitter.com/kdambekalns/status/613802413665972224">tweet</a>)</span></b>So let's roar on :) The tooling (see <a href="https://forge.typo3.org/boards/22/topics/505">the budget application</a>…) could benefit all docs</li>
</ul>
I, <a href="https://twitter.com/cognifloyd">@cognifloyd</a>, am the budget owner for the “<a href="https://forge.typo3.org/boards/22/topics/505">Documentation and Documentation Tools for Neos/Flow</a>” 2015 budget. <b>This is my roar!</b> <i>(check out the discussion of my budget application on forge. I'll just assume that you've read it in the rest of what I have to say)</i><br />
<br />
As @kdambekalns said, I think the “#TYPO3 documentation will [...] profit from [my] work as well!”. Yes, my budget has “Neos” written all over it, but writing documentation alone is not enough. Dig a little deeper, and you’ll see how my work will benefit both projects. The key budget milestones are milestones 3 and 4:<br />
<ul>
<li>“Infrastructure\Tools for [...] documentation contributions”, and</li>
<li>“Automated screenshot & video capture system for embedding in [rst docs]”.</li>
</ul>
<br />
I want to create a layer of glue between Sphinx (software that docs.typo3.org uses to render ReStructured Text, or rst) and screenshot/video capture tools like phantomjs and ffmpeg. Some people embed behat scenarios in rst, so that might be how I accomplish this. Others have already figured out how to make each of the other elements work. I want to bring the power of automated screenshots into the hands of the people that end up maintaining the docs.<br />
<br />
When I applied for the budget, the Neos/Flow docs were ideal candidates for developing these tools. I was working on docs.typo3.org’s rendering infrastructure (more on this below), so I planned on writing those tools within that infrastructure. As a technical writer, I figured I’d be my own “domain expert” as I create the tools that I think will make it easier to create and maintain the docs. However, to be the “domain expert”, I can’t create the tools without actually writing some documentation. I need to write to identify exactly where writing/maintaining docs is painful. I need to write to make sure that the tools I create fit into the writing workflow as seemlessly as possible.<br />
<br />
In fact, I’d started writing the Neos Editor Guide long before I applied for this budget. With this budget, I hope to make it easier for me and others to contribute to documentation efforts. It would take me a lot longer to identify gaps in TYPO3 docs than it takes to just continue what I’m already working on. Switching docs now would be like telling someone they have to rewrite all of their unit/functional tests before they can continue developing their software. Talk about lost productivity. The Neos docs are my “tests” (or at least my first test project), but TYPO3 will still get the benefit of the tools I create (or more appropriately, the tools I glue together).<br />
<br />
I hope that TYPO3 Association members decide to continue funding my budget, even though the TYPO3 and Neos communities are separating into two overlapping communities. Both communities will benefit from better documentation tools and infrastructure. Plus, I will be able to more efficiently build these doc tools if I can continue building them as I write the docs I have already been working on.<br />
<br />
<h3>
“0% of this budget [has] been used.” (@sorenbryder)</h3>
Why haven’t I used that budget yet? Besides several personal time constraints, whenever I had time to work on something from a T3A budget this year, I prioritized building the docs infrastructure over writing/revising any of the docs. I started working on the docs infrastructure last year, and I wanted to finish that infrastructure project before I spent much time on my budget.<br />
<br />
There has been a long-running project to replace the shell scripts that build the docs on docs.typo3.org with a web application that will make managing that rendering process easier. Any tools I write as part of my budget will be designed to plugin to this new rendering process. So, I thought working with the docs team first was the most logical course of action.<br />
<br />
<h3>
What was my budget for? Why did I apply for it?</h3>
<div>
Frankly, I applied because “docs”, for a lot of people, is a <a href="https://en.wikipedia.org/wiki/Four-letter_word">four-letter word</a>. As @sorenbryder said, the need for better docs “isn’t news to anyone”.</div>
<br />
But why? Why are docs always so out-of-date? Why don’t more people help keep them updated? Sure, English isn’t PHP (Sorry devs!), it’s not Esperanto, and, for most people, it’s not their native language. Writing good docs is hard work. It’s time consuming, and it requires a different mindset then writing good code does. Writing docs doesn’t feel profitable like selling another website gig, it’s not as enjoyable as a good YouTube playlist, and, when you finally get around to writing the docs, getting all the documentation tools together can be a nightmare.<br />
<br />
There are a lot of gaps in the Neos and Flow docs. Given enough time, I could probably write new docs and revise the old docs, but that isn’t good enough for me. If I just “get it done”, the manuals I write would end up just as out-of-date as TYPO3’s Modern Template Building manual. No one has taken the time to substantially update that guide since it was written. Isn’t there a way to write a manual so that it’s easier for others to update it?<br />
<br />
I’m a geek (ie I like PHP), English is my native language, and I’m a technical writer. Heck, I enjoy writing! I’m one of few people I know of in the TYPO3 community (and now the overlapping Neos community) with qualifications like that. Does that make me a “domain expert” when it comes to improving the documentation workflow? Maybe. I’m scratching an itch, and trying to do it in a way that will help as many people as possible.<br />
<br />
So, I applied for a budget to help me find ways to make documentation easier for more people. But, how could I find the rough spots in writing/revising documentation without actually writing/revising a manual in the process?<br />
<br />
That’s why I applied for my budget. There just had to be a better way!<br />
<br />
<h3>
What do screenshots have to do with that?</h3>
One of the most annoying, focus-stealing tasks in generating user documentation was generating the screenshots and short screencasts that I wanted to embed in the docs. Because they’re such a pain, and because no one takes the time to stop what they’re doing and regenerate them, I decided to automate that process. In searching the web, I discovered a variety of resources that make automating that a conceptually simple thing to do. I just need to glue the pieces together so that they can use descriptions embedded in rst docs to generate those screenshots/screencasts. If I could come up with a way to make that part of the documentaiton process better, then surely, I can find other process improvements too.<br />
<br />
Another problem with screenshots is, everyone has their own way to take them. If numbers/labels are required, then they are going to look very inconsistent throughout a manual that gets updated by different people over the course of many years. If those screenshots are automatically generated instead, then our documentation will not only be more easy to update, but it’ll have more professional graphics as well.<br />
<br />
<h3>
What about the community split?</h3>
But, now, I’m faced with a dilemma. I didn’t know the TYPO3 and Neos communities were going to split. I think the split is good, as it is relieving a lot of tensions that have been building up in our community for many years. But, it sure makes it difficult for me to continue working on what I think will benefit both projects.<br />
<br />
I have been in the TYPO3 community for over a decade, since version 3.4 or so of TYPO3. Back then, I was using TYPO3 to build a website for my high school. Since then, I’ve used TYPO3 and Neos in a variety of hobby and school projects. As a technical writer, I built a documentation website for one company first in TYPO3 CMS and then transitioned to using Neos, or TYPO3 Phoenix as it was called at the time. Sadly, none of the sites I’ve built still exist, but I don’t need those projects to consider myself a member of both the TYPO3 community and the Neos community.<br />
<br />
Like I said at the beginning, I think my work will benefit both projects. My only problem was that I didn’t think a community split would happen this year. So, I made my budget mention Neos/Flow too many times instead of thinking/writing about how the TYPO3 project as a whole could benefit from these tools.<br />
<br />
<h3>
Conclusion/Request</h3>
If you are a TYPO3 Association member, please vote to honor the “Documentation & Documentation Tools for Neos/Flow” budget. I will make sure that screenshot automation and any other tools I create are smoothly integrated into the docs.typo3.org infrastructure. I’m already working hard on maintaining that infrastructure, and I look forwarding to making these features available to the docs that get rendered on docs.typo3.org.Anonymoushttp://www.blogger.com/profile/14944134144016532385noreply@blogger.com0tag:blogger.com,1999:blog-9217356639662394871.post-41916552833022658472013-10-29T13:17:00.000-05:002013-10-29T13:18:58.076-05:00Software Patents = Crazy Talk<a href="https://twitter.com/repgoodlatte">Rep. Goodlatte</a>, my representative in congress, has been working on <a href="http://judiciary.house.gov/news/2013/10292013.html">fixing the problems with US Patent Law</a>. I just emailed him the following:<br />
<br />
<blockquote class="tr_bq">
<blockquote class="tr_bq">
Thank you for working on reforming our blighted patent system. Merely controlling litigation is not enough. You mentioned frivolous and speculative patent lawsuits, but you did not identify the deeper problem with software patents.</blockquote>
<blockquote class="tr_bq">
Software is written. Software should be protected under copyright laws not patent laws. Copyrights protect exact wording, but do not prevent people from speaking, thinking or writing about those ideas. Just like literate people can read ideas in good books, literate software engineers can read ideas in software. Just as literate people should not copy a book word for word and take credit for writing it, software engineers should not copy a computer program word for word and take credit for writing it.</blockquote>
<blockquote class="tr_bq">
Software should not be patentable. Think about these: A bookbinding, a new way to make paper, a new computer case, and a revolutionary computer screen. These can be patented, but the ideas on the pages of a book and the ideas in each line of software code are only thoughts and ideas. Patenting an idea is like trying to control how people think, it's like trying to control the newspapers saying that there can only be one republican newspaper and one democratic newspaper. Preventing the spread of thoughts and ideas is not constitutional.</blockquote>
<blockquote class="tr_bq">
Allowing software patents is like saying we don't really believe in the right to believe, think, or speak. Allowing software patents is fundamentally wrong. </blockquote>
<blockquote class="tr_bq">
Please champion legislation to protect software the right way: with copyrights, not with patents.</blockquote>
</blockquote>
Anonymoushttp://www.blogger.com/profile/14944134144016532385noreply@blogger.com0tag:blogger.com,1999:blog-9217356639662394871.post-31914561315316107662013-08-06T10:42:00.002-05:002013-08-06T11:28:45.259-05:00Figuring out TDDI want to use TDD in my GSoC project. Tests are important, and the benefits of testing are worth it.<br />
<div>
<br /></div>
<div>
Now, my only problem with TDD is, I'm not quite sure how to do it. Oh, I've got the mechanics in place (Travis is set up and ready to eat my github repo, and I think I've got phpunit setup locally. Heck I even have Jenkins on my local machine if I could ever get it configured right.), but whenever I go to write unit tests, I feel like I'm staring at a blank page in an old fashioned typewriter.<br />
<br /></div>
<table align="center" cellpadding="0" cellspacing="0" class="tr-caption-container" style="margin-left: auto; margin-right: auto; text-align: center;"><tbody>
<tr><td style="text-align: center;"><a href="http://www.flickr.com/photos/starside/242723164/" style="margin-left: auto; margin-right: auto;" title="t o w e r by wander.lust, on Flickr"><img alt="t o w e r" src="http://farm1.staticflickr.com/93/242723164_c88411598c.jpg" /></a></td></tr>
<tr><td class="tr-caption" style="text-align: center;">I feel like I'm staring at a blank page in an old fashioned typewriter. (Image from starside on flickr)</td></tr>
</tbody></table>
<div>
For a long time, I think my problem was an incomplete design. I knew I wanted to take stuff from a boilerplate, then "process it somehow", then put it in a derivative package. But I didn't know what that "somehow" looked like.<br />
<br />
Well, I've figured out <a href="https://github.com/cognifloyd/Cognifire.BuilderFoundation/blob/974b9db6ba3ad25dd3f640b0bf022f29fd061c2e/Documentation/index.rst">the main parts of that process now</a>. I know what I want my API to look like (within PHP). So, I take my first example, and go line-by-line to make it work.<br />
<br /></div>
<div class="gistLoad" data-id="6165529" id="gist-6165529">
Loading Gist ....</div>
<br />
<div>
So, let's take part of line 2: <br />
<br />
<pre>new BlobQuery('Cognifire.SweetSitePackage');</pre>
<pre></pre>
<br />
How do I test this? Do unit tests test constructors? Is this a unit?<br />
<br />
And so I'm back at that blank page again. I'm not quite sure what unit I'm testing. The constructor doesn't return anything, it just sets up the object. Should I add getters and setters for what should ultimately be protected properties just so that I can test that they are initialized correctly? That seems rather odd.<br />
<br />
But TDD says don't write a line of code until you've written a failing test, so I feel stuck.<br />
<br />
How do you approach TDD? Unit testing? What questions do you ask yourself to get past the stupid blank page?</div>
<script src="https://raw.github.com/moski/gist-Blogger/master/public/gistLoader.js" type="text/javascript"></script>
Anonymoushttp://www.blogger.com/profile/14944134144016532385noreply@blogger.com0Salt Lake City, UT, USA40.7607793 -111.8910473999999940.568390300000004 -112.21377089999999 40.9531683 -111.5683239tag:blogger.com,1999:blog-9217356639662394871.post-30710020552686489052013-07-15T12:07:00.000-05:002013-07-15T12:09:07.696-05:00BuilderFoundation BlobQuery<b>Blob:</b> A file, or a snippet/section of a file, or syntax-tree like thing. Typically, a blob requires a special parser.<br />
<br />
<b>BlobType:</b> A blob has a type so that it can be handled by the appropriate parser.<br />
<br />
<b>SubBlobs:</b> A blob in another blob.<br />
<br />
<b>BlobType-SubType:</b> BlobTypes are not restricted to just the main blob types, but may define subtypes as well to make working within the syntax tree easier. A SubType is separated by a dash (maybe I should use a dot as the separator like NodeTypes does in TYPO3CR. What do you think?)<br />
<br />
Example BlobTypes include: FluidBlob, HtmlBlob, PhpBlob, YamlBlob, TypoScriptBlob. I believe the packageBuilder will need an additional DomainBlob that doesn't map to any particular media-type. A Blob is essentially a generalized syntax tree, and a DomainBlob would be used to create PhpBlobs, it's just a more specialized/focused view of the information.<br />
<br />
Example SubTypes (if I match the syntax tree exactly):<br />
<br />
<ul>
<li>FluidBlob</li>
<ul>
<li>FluidBlob-Array</li>
<li>FluidBlob-Boolean</li>
<li>FluidBlob-ObjectAccessor</li>
<li>FluidBlob-Numeric</li>
<li>FluidBlob-Text</li>
<li>FluidBlob-ViewHelper.</li>
</ul>
<li>PhpBlob</li>
<ul>
<li>PhpBlob-Class</li>
<li>PhpBlob-Function (PhpBlob-Method within Class)</li>
<li>PhpBlob-Interface</li>
<li>PhpBlob-Namespace</li>
<li>PhpBlob-Property</li>
</ul>
</ul>
<b>BlobQuery:</b> This provides a context for FlowQuery. You create a new BlobQuery with a given path (typically a package path), and BlobQuery scans for files (optionally filtered by type), creates a Blob object for each of them, and adds them to an initial set of objects before returning a new FlowQuery instance that's using the set of Blobs.<br />
<br />
OK, so here's a portion of the UML diagram I've been creating (in ArgoUML) to figure out what all needs to go in BuilderFoundation.<br />
<br />
<div class="separator" style="clear: both; text-align: center;">
<a href="https://blogger.googleusercontent.com/img/b/R29vZ2xl/AVvXsEiX0cLV6T1OZwT7I4kkKIEc3knEAXCvOC8mnUKzSgEyt83yNV92XsGzf8K12dsTLWH-KxFhcYdHpgleSJZElLhDrJoWqSZkHChbN2u9m0RvzLt4dBIOr7kk2tq_Eo1uVyCez_bVb8sNkJI/s1600/ClassDiagram.png" imageanchor="1" style="margin-left: 1em; margin-right: 1em;"><img border="0" height="451" src="https://blogger.googleusercontent.com/img/b/R29vZ2xl/AVvXsEiX0cLV6T1OZwT7I4kkKIEc3knEAXCvOC8mnUKzSgEyt83yNV92XsGzf8K12dsTLWH-KxFhcYdHpgleSJZElLhDrJoWqSZkHChbN2u9m0RvzLt4dBIOr7kk2tq_Eo1uVyCez_bVb8sNkJI/s640/ClassDiagram.png" width="640" /></a></div>
<br />
The OperationResolver expects simple values for priority, shortName, and Final, but I want to have one Operation class, BlobTypeSpecificOperations, that calls a variety of methods on the Blobs. To make this work, I add a BlobTypeSpecificOperationsAspect that calls a specialize initializeObject right after OperationResolver->initializeObject() gets called. This grabs the Cognifire.BuilderFoundation.BlobTypeOperations configuration and adds all of the registered blob operations to the list of operations. That means that if a blob has a special operation that only works for that BlobType, then add it as a method in the Blob itself (makes code organization feel better), and register that method as a BlobOperation in the Settings.yaml file. Whenever that operation gets called, it will go through BlobTypeSpecificOperations->evaluate() which will call the registered method on the blob for that operation.<br />
<br />
The reason this is important, is you'll select a set of blobs with BlobQuery/FlowQuery, and then do some operation, and it will do that operation on all of the Blobs.<br />
<br />
AOP is awesome!Anonymoushttp://www.blogger.com/profile/14944134144016532385noreply@blogger.com0tag:blogger.com,1999:blog-9217356639662394871.post-35279423986347627102013-07-06T06:58:00.001-05:002013-07-15T12:09:21.953-05:00GSoC NotebookI wanted to show that I'm still working on this, and a video seemed like the easiest way to show off my notes to the world. Enjoy. Let me know if you have any questions or want to know about something in my notebook.<br />
<br />
<iframe allowfullscreen="" frameborder="0" height="344" src="//www.youtube.com/embed/QfSvYR-49g4" width="459"></iframe><br />
<br />Anonymoushttp://www.blogger.com/profile/14944134144016532385noreply@blogger.com0tag:blogger.com,1999:blog-9217356639662394871.post-82873948196994379202013-06-14T15:26:00.001-05:002013-06-27T16:45:50.375-05:00Changing OpenRC colors to use SolarizedSo, after switching my terminals to use the <a href="http://ethanschoonover.com/solarized">solarized color scheme</a>, I was dismayed to discover that alot of apps don't like it when you change the ANSI colors.<br />
<br />
OpenRC commands are no exception: rc-status, rc-config, and rc-service all tried to use the bold colors which have been reassigned, so the output is downright ugly.<br />
<br />
I just went sifting through the OpenRC sources, and discovered a little gem: EINFO_COLOR is an environment variable that does more than turn color on or off. No, that little sucker allows you to redefine which ANSI colors it will use for output.<br />
<br />
Here's what I do to make it use solarized. I put the following line in /etc/bash/bashrc (because everything is solarized, not just my user):<br />
<br />
<blockquote class="tr_bq">
<pre>export EINFO_COLOR="good=2;0:bad=1;0:warn=1;1:hilite=7;1:"</pre>
</blockquote>
<br />
This sets my colors to:<br />
<ul>
<li>good is green</li>
<li>bad is red</li>
<li>warn is orange</li>
<li>hilite is base3</li>
</ul>
So, EINFO_COLOR lets you change the <a href="http://git.overlays.gentoo.org/gitweb/?p=proj/openrc.git;a=blob;f=src/libeinfo/libeinfo.c;h=6f0ca7669e86ce3411d9564b993bdedb9730e3a6;hb=HEAD#l130">colors</a> (all lower case): good, warn, bad, hilite, and bracket. You can't change the normal text color.<br />
<br />
Each of the colors is a <a href="http://git.overlays.gentoo.org/gitweb/?p=proj/openrc.git;a=blob;f=src/libeinfo/libeinfo.c;h=6f0ca7669e86ce3411d9564b993bdedb9730e3a6;hb=HEAD#l451">pair of two numbers</a><br />
<br />
<ul>
<li>The first number is the <a href="http://en.wikipedia.org/wiki/ANSI_escape_code#Colors">ANSI Color</a> (0-7)</li>
<li>followed by a semicolon (;)</li>
<li>followed by whether or not it should use the "bold" ANSI Color (0 is normal, 1 is "bold")</li>
<li>followed, by a colon (:) which serves to 'end' the number and separate the variables in the string</li>
</ul>
<div>
So that means that Solarized colors would be specified like this:</div>
<br />
<div style="text-align: center;">
<pre><code>
SOLARIZED HEX 16/8 TERMCOL EINFO_COLOR
--------- ------- ---- ------- -----------
base03 #002b36 8/4 brblack 0;1:
base02 #073642 0/4 black 0;0:
base01 #586e75 10/7 brgreen 2;1:
base00 #657b83 11/7 bryellow 3;1:
base0 #839496 12/6 brblue 4;1:
base1 #93a1a1 14/4 brcyan 6;1:
base2 #eee8d5 7/7 white 7;0:
base3 #fdf6e3 15/7 brwhite 7;1:
yellow #b58900 3/3 yellow 3;0:
orange #cb4b16 9/3 brred 1;1:
red #dc322f 1/1 red 1;0:
magenta #d33682 5/5 magenta 5;0:
violet #6c71c4 13/5 brmagenta 5;1:
blue #268bd2 4/4 blue 4;0:
cyan #2aa198 6/6 cyan 6;0:
green #859900 2/2 green 2;0: </code></pre>
</div>
Anonymoushttp://www.blogger.com/profile/14944134144016532385noreply@blogger.com0tag:blogger.com,1999:blog-9217356639662394871.post-70507651984051779842013-06-12T23:51:00.000-05:002013-06-14T13:31:32.081-05:00Tech Buzzword BonanzaI made this awhile ago while studying a bunch of different tech topics. I referred back to it today, and ended up recreating it in VUE so that I could update it. The original version was in a trial version of Lucid Chart. I've updated it with a few more terms from Domain Driven Design and TDD/BDD. Maybe someone else might find this helpful.<br />
<table align="center" cellpadding="0" cellspacing="0" class="tr-caption-container" style="margin-left: auto; margin-right: auto; text-align: center;"><tbody>
<tr><td style="text-align: center;"><a href="https://blogger.googleusercontent.com/img/b/R29vZ2xl/AVvXsEjt15BRit5AucZnnloUWoYO0tHFy-8m-_m27hkwB-PtfzH7WwsFuwEONHycZ7zvy5fYYgKaX6N-KskKuuVqjG7THsgO9C9T1OR0Gw106d-qFkwYQFcEMAu1MzGOVz3MQqB7kyIKMp3EOHU/s1600/TechBuzzwordBonanza-copy.png" imageanchor="1" style="margin-left: auto; margin-right: auto;"><img border="0" height="547" src="https://blogger.googleusercontent.com/img/b/R29vZ2xl/AVvXsEjt15BRit5AucZnnloUWoYO0tHFy-8m-_m27hkwB-PtfzH7WwsFuwEONHycZ7zvy5fYYgKaX6N-KskKuuVqjG7THsgO9C9T1OR0Gw106d-qFkwYQFcEMAu1MzGOVz3MQqB7kyIKMp3EOHU/s640/TechBuzzwordBonanza-copy.png" width="640" /></a></td></tr>
<tr><td class="tr-caption" style="text-align: center;">Tech Buzzword Bonanza</td></tr>
</tbody></table>
<br />Anonymoushttp://www.blogger.com/profile/14944134144016532385noreply@blogger.com0tag:blogger.com,1999:blog-9217356639662394871.post-48796018510062294012013-06-10T16:10:00.001-05:002013-06-21T16:20:15.233-05:00Scattered design thoughtsSo, I have notes scattered everywhere and I'm somewhat lost. I'm using this post to try and collect my notes, and get a better idea of where I am and where I'm going. Though you're welcome to browse through this, I don't expect these notes to make sense to anyone other than me.<br />
<div>
<br /></div>
<div>
<hr />
</div>
<div>
<br /></div>
<div>
BuilderFoundation provides a MetaModel for packages that other Builders will extend.</div>
<div>
<br /></div>
<div>
A Package can be built like FormDefinitions from TYPO3.Form</div>
<div>
<ul>
<li>FormDefinitions have:</li>
<ul>
<li>finishers <array></li>
<li>processingRules <array></li>
<li>elementsByIdentifier <array></li>
<li>eleementsDefaultValue <array></li>
<li>formFieldTypeManager <injected class></li>
<li>validatorPresets <array></li>
<li>finisherPresets <array></li>
<li>setOptions (stuff that works with info from a YAML)</li>
<ul>
<li>setRendererClassName</li>
<li>setRenderingOption</li>
<li>createFinisher</li>
</ul>
</ul>
<li>The FormFactory builds FormDefinitions</li>
<li>Use the name "presets" which would work as an options layer in general, or a "themes" layer in TemplateBuilder (a preset is a name + configuration; or iow it is a named set of configuration)</li>
<li>Based on YAML files</li>
<li>Using a yamlPersistenceManager</li>
</ul>
<div>
YAML files</div>
</div>
<div>
<ul>
<li>Use superTypes inheritance concept (like in Forms and TYPO3CR: NodeTypes.yaml) to allow for things like mixins</li>
<li>Always get converted to arrays</li>
<li>considered using TypoScript, but YAML seems to fit how I'll use this better. (YAML is for data serialization. TypoScript helps in processing things)</li>
<li>YAML processors should always have at least one of dump() or load()</li>
<li>Each package has a configuration file in YAML</li>
<li>boilerplates and settings repositories should be added from the yaml (Cognifire\BuilderFoundation\boilerplateRepositories & derivativeRepositories)</li>
<li>Current configuration files</li>
<ul>
<li>Settings.yaml</li>
<li>Routes.yaml</li>
<li>Objects.yaml</li>
<li>Policy.yaml</li>
<li>PackageStates.php</li>
<li>Caches.yaml</li>
<li>Views.yaml</li>
</ul>
<li>It would be nice to be able to breakup boilerplate configurations so that there's one preset per file (or somethin like that). <whatever base name>.<preset name>.yaml</li>
<li>Will need a schema:</li>
<ul>
<li><a href="https://git.typo3.org/FLOW3/Packages/TYPO3.TYPO3.git/blob/HEAD:/Resources/Private/Schema/NodeTypes.schema.yaml">TYPO3.TYPO3CR:NodeTypes.schema.yaml</a></li>
<li><a href="https://git.typo3.org/FLOW3/Packages/TYPO3.TYPO3.git/blob/HEAD:/Resources/Private/Schema/NodeTypes.schema.yaml">TYPO3.Neos:NodeTypes.schema.yaml</a></li>
</ul>
</ul>
<div>
AbstractPackage: Boilerplates and Derivatives</div>
<ul>
<li>not packageKey identified, but w/ UUID because packageKey might change several times during package build process</li>
<li>What gets stored in the package object is metadata about it's creation</li>
<ul>
<li>a declarative set of steps--if you will--to allow the builder to recreate the same derivative but with another package key</li>
<li>Only part of this can be found out by parsing directory structures.</li>
<li>Instead, you</li>
<ul>
<li>list Packages/<target repo>/*</li>
<li>read each <package>/Configuration/<yaml file></li>
</ul>
</ul>
<li>Yaml file names (not satisfied with these names)</li>
<ul>
<li><strike>Themes.yaml</strike> (Builders might want to provide their own yaml file, like the templateBuilder where the word "themes" makes a lot of sense)</li>
<li>Possible names in Boilerplates:</li>
<ul>
<li><strike>Builder.Boilerplate.yaml</strike></li>
<li><b>Boilerplate.yaml</b></li>
<ul>
<li>Declared components (all available)</li>
</ul>
<li><strike>Boilerplate.presets.yaml</strike></li>
<li><strike>Boilerplate.presets.<something>.yaml</strike></li>
</ul>
<li>Possible names in Derivatives:</li>
<ul>
<li><strike>Builder.Derivative.yaml</strike></li>
<li><b>Derivative.yaml</b></li>
<li><strike>Boilerplate.Integrated.yaml</strike></li>
<ul>
<li>Declare which components were used and from where without introducing a dependency on the boilerplate</li>
</ul>
<li><strike>Builder.Template.yaml or Builder.Package.yaml</strike></li>
<ul>
<li>contains the presets or the final configuration, how all of declared components were put together</li>
<li>Builder specific?</li>
</ul>
</ul>
<li>Boilerplate.yaml and Derivative.yaml can be a collection of YAML files to keep the component definitions in the same folder as the component. Everything in that Boilerplate would apply only to that path. With one exception: Resources/Private/[Boilerplate || Derivative].yaml applies to the whole package. They should be restricted to the Resources folder, though, so that we don't have YAML files in the Classes/ or Tests/ folders. Boilerplate.yaml and Derivative.yaml should also not be in Settings/ as that is reserved for Presets.*.yaml for builder stuff as well as other configuration that is not builder-related.</li>
<li>Basically, this means that Boilerplates will store the snippets they use to build files in the Resources folder.</li>
</ul>
<li>Boilerplate vs Derivative</li>
<ul>
<li>Package Repository (Boilerplate vs Application)</li>
<li>Derivative</li>
<ul>
<li>Root files (composer.json...)</li>
<li>Resources</li>
<li>Configuration</li>
<li>Documentation</li>
<li>Classes</li>
<li>Tests</li>
<li>Scripts</li>
<li>Migrations</li>
<li>Meta</li>
</ul>
</ul>
<li>Yaml files, rethought</li>
<ul>
<li><span style="font-size: large;"><package>/Resources/Private/<b>Boilerplate</b>.yaml</span><br />Declares which components/resources are available in boilerplate including:</li>
<ul>
<li>Which builder is required to work with a particular set of files. Or maybe they would declare filetypes like x.html is fluid and y.html is handlebars so that the appropriate Builder can be used, and the Builder would say which filetypes it works with)</li>
<li>A versioning "namespace" of sorts, so that a boilerplate can include multiple versions of layouts/templates/partials (thinking of TwitterBootstrap v2 and v3). This would assist the migration service</li>
<li>Perhaps a list of presets that are available in the Boilerplate (though that should probably be based on what is in the Settings/)</li>
</ul>
<li><span style="font-size: large;"><package>/Resources/Private/<b>Derivative</b>.yaml</span></li>
<ul>
<li>Declares which components & presets have been used</li>
<ul>
<li>from which boilerplate</li>
<li>and which boilerplate version (to assist with migrations)</li>
</ul>
<li>Perhaps a list of which manual changes have been detected</li>
<li>This file would have the Eel selectors to say "insert [component] at [location] in [file]" including components from boilerplates and components that are added manually. This should be verbose enough that a Builder could regenerate the templates from the boilerplates (for the custom components [the 'changeset in Boilerplate math], maybe the builder could pull them out and store them in another Resources/Private/ folder so that it can keep track of manual changes.)</li>
<li>Though this should be human readable, only Builders will edit it. I can imagine people tweaking an Eel statement. But most of the file is for Builder metadata persistence.</li>
</ul>
<li><span style="font-size: large;"><package>/Settings/<br /><b>Presets</b>.[BuilderSpecific].[PresetName].yaml</span><br /><i>A preset configures a set of components to work together. This is the Builders' "options" layer. It does not define how the files are combined. That belongs in the Boilerplate.yaml (for what can be combined) or Deriative.yaml (for what has been combined) files.</i><br />Should the BuilderSpecific part be singular or plural? You can have multiple presets in a Presets.Builder.yaml file, or break them out into individual Presets.Builder.Preset1.yaml and Presets.Builder.Preset2.yaml files.<br />Someone could edit a Preset manually and use the Builder to make the change in their templates. These should be human-friendly. They would have to fire up the Builder to make the builder adjust whatever files are built with that preset (like changing a color in a LESS file).<br />Examples of possible uses per builder (just examples, most are not part of GSoC project):</li>
<ul>
<li>PackageBuilder</li>
<ul>
<li>Presets.<b>Package.CMS</b>.yaml</li>
<li>Presets.<b>Package.Flow</b>.yaml</li>
<li>Presets.<b>Package.Symfony</b>.yaml (example extension of PackageBuilder)</li>
</ul>
<li>TemplateBuilder</li>
<ul>
<li>Presets.<b>Theme</b>.yaml</li>
<li>Presets.<b>Theme.FixedLayout</b>.yaml</li>
<li>Presets.<b>Theme.AwesomeGreen</b>.yaml</li>
<li>Presets.<b>Theme.MyThemeName</b>.yaml</li>
<li>Presets.<b>Fluid</b>.yaml (for stuff that doesn't quite fit the term "Theme"</li>
</ul>
<li>TypoScriptBuilder</li>
<ul>
<li>Presets.<b>TypoScript</b>.yaml</li>
</ul>
<li>EmberBuilder or JavaScriptBuilder (Works with JavaScript stuff like Ember and Handlebars)</li>
<ul>
<li>Presets.<b>Ember</b>.yaml</li>
<li>Presets.<b>Ember.Handlebars</b>.yaml</li>
<li>Presets.<b>Handlebars</b>.yaml</li>
<li>Presets.<b>JS</b>.yaml (maybe everything could be Presets.JS.*.yaml like Presets.JS.Ember.yaml and Presets.JS.Handlebars.yaml)</li>
</ul>
<li>FormBuilder (if it switches to using BuilderFoundation at its core)</li>
<ul>
<li>Presets.<b>Form</b>.yaml</li>
<li>Presets.<b>Form.Cli</b>.yaml</li>
<li>Presets.<b>Form.Bootstrap</b>.yaml</li>
</ul>
<li>TranslationBuilder (works with .xlf files)</li>
<ul>
<li>Presets.<b>Translation</b>.yaml (not sure how a TranslationBuilder would need Presets, but it's possible)</li>
</ul>
<li>SchemaBuilder (a Resource that needs to be built. Different Builders might want to create a schema for what is allowed in their Presets.[Builder].*.yaml files, and they might not want to craft the schemas by hand)</li>
<li>OntologyBuilder/TaxonomyBuilder (Not sure this one will work with packages or boilerplates, but, the Builder concept still applies)</li>
</ul>
</ul>
<li><strike>Yaml file contents Boilerplate vs Derivative (extendable yaml schema)</strike></li>
<ul>
<li><strike>Boilerplate</strike></li>
<ul>
<li><strike>relevant builder (like template builder)</strike></li>
<ul>
<li><strike>components that can be built</strike></li>
<ul>
<li><strike>include[superType]</strike></li>
<li><strike>Variations of each component</strike></li>
<li><strike>Options that apply to each component</strike></li>
</ul>
</ul>
<li><strike>presets</strike></li>
<ul>
<li><strike>components 1,2,5</strike></li>
<ul>
<li><strike>variations such and so</strike></li>
<li><strike>options</strike></li>
</ul>
</ul>
<li><strike>TemplateBuilder: (example specific builder)</strike></li>
<ul>
<li><strike>Declare what is avilable</strike></li>
<ul>
<li><strike>Components:</strike></li>
<ul>
<li><strike>Variations</strike></li>
<li><strike>Options</strike></li>
</ul>
<li><strike>Variations</strike></li>
<li><strike>Options (Theme in TemplateBuilder)</strike></li>
<ul>
<li><strike>color1:</strike></li>
<li><strike>color2:</strike></li>
<li><strike>width:</strike></li>
</ul>
</ul>
<li><strike>Presets are pre-configured defaults / collections of components and options</strike></li>
<ul>
<li><strike>Presets / <presetname></strike></li>
<ul>
<li><strike>components: 1, 2, 3</strike></li>
<li><strike>variation: A, B</strike></li>
<li><strike>options</strike></li>
</ul>
</ul>
</ul>
</ul>
<li><strike>Derivative</strike></li>
<ul>
<li><strike>Has one preset that lists which</strike></li>
<ul>
<li><strike>boilerplate components are in use</strike></li>
<li><strike>how they are configured</strike></li>
<li><strike>what options are set</strike></li>
</ul>
<li><strike>Boilerplate.Integrated.yaml</strike></li>
<ul>
<li><strike>declares components used from each boierplate</strike></li>
<ul>
<li><strike>copied from boilerplate w/ boilerplate version</strike></li>
</ul>
</ul>
</ul>
</ul>
</ul>
<div>
Spl*Iterators [Directory, FileSystem, Glob]:</div>
<div>
<ul>
<li>Relationships</li>
<ul>
<li>GlobIterator extends FileSystemIterator extends DirectoryIterator</li>
<li>RecursiveDirectoryIterator extends FileSystemIterator as well</li>
<li>GlobIterator is one level w/ glob pattern search</li>
<li>DirectoryIterator is one level</li>
<li>FileSystemIterator is just like DirectoryIterator but with flags that give more control over what current and key return.</li>
<li>RecursiveDirectoryIterator does many levels</li>
</ul>
<li>Interesting FileSystemIterator Flags</li>
<ul>
<li>::CURRENT_AS_PATHNAME</li>
<li>::KEY_AS_PATHNAME</li>
<li>::KEY_AS_FILENAME</li>
<li>::FOLLOW_SYMLINKS</li>
<li>::NEW_CURRENT_AND_KEY (KEY_AS_FILENAME & CURRENT_AS_FILEINFO)</li>
<li>::SKIP_DOTS</li>
<li>::UNIX_PATHS (I'll want this one)</li>
<li>Current could return Pathname, or Filename or Fileinfo (which is a SplFileInfo object)</li>
</ul>
<ul>
<li>Key is just a numeric array key</li>
</ul>
<li>SplFileInfo interesting methods (also available on DirectoryIterator and FileSystemIterator)</li>
<ul>
<li>getBasename (can omit a suffix from path & filename)</li>
<li>getFilename</li>
<li>getPath (w/o filename)</li>
<li>openFile (creates SplFileObject to iterate ovver a file w/ fwrite, fpassthru...)</li>
<li>getRealPath (resolve links)</li>
<li>getExtension</li>
<li>getType (file, link, dir)</li>
</ul>
<li>Streams</li>
<ul>
<li>file:// -- for file access</li>
<li>glob://*.png -- for listing dir contents that match the glob</li>
<li>data: -- to encode stuff straight in files and treat it as a file/stream (RFC 2397)</li>
<ul>
<li>data:text/plan,$data</li>
<li>data:text/plain;base64,$data</li>
<li>data:image/jpeg;base64;$image</li>
</ul>
<li>resource:// -- flow specific only for stuff in resources of a particular package</li>
<ul>
<li>The purpose of this is not to hide that something is a file, but to hide where it is stored (so that Flow can do the linking magic with all the public stuff in the Web/_Resources folder</li>
</ul>
</ul>
</ul>
<div>
<div>
Persistence</div>
</div>
<div>
<ul>
<li>Flow injects the persistenceManagerInterface</li>
<li>There's no way to say which one flow will use, instead it is specified in objects.yaml (doctrine by default)</li>
<li>Mutliple concurrent Persistence backends won't be available until Flow 2.2 (or Flow 3 depending on how backwards compatible it is</li>
<ul>
<li>define on repository basis what kind of DB to persist it in</li>
<li>This is not implemented yet due to lack of funding</li>
<li>I would rather reuse the flow persistence stuff where it makes sense, but I have to decouple everything until this is implemented. I'll copy lots of stuff to make it work. The thing is, a DB doesn't make any sense in my packages, even though I'm persisting stuff, the code assumes that persistence is always to a DB.</li>
<li>workaround is to put persistence stuff in the repository and not use @Flow\Entity and the like</li>
</ul>
<li>"Models do not know (a lot) about Persistence (internals)"</li>
<li>Repository responsible for:</li>
<ul>
<li>Saving object</li>
<li>persisting changes to object throughout lifetime (update DB as needed)</li>
<li>provide QL</li>
<ul>
<li>handle DB retrieval</li>
<li>ensures only one instance in memory</li>
</ul>
<li>provides the aggregate root</li>
</ul>
<li>Comparing Radmiraal.CouchDB (doctrine branch) with normal doctrine persistence</li>
<ul>
<li>@ODM\Document instead of @ORM\Entity or @Flow\Entity</li>
<li>replaces persistence manager w/ document manager</li>
<li>queries</li>
<ul>
<li>no query on arbitrary properties</li>
<li>drops queries in favor of lucenQueries</li>
<li>setQueryMatchValue</li>
</ul>
<li>both use persistenceManager</li>
<ul>
<li>->getObjectByIdentifier in generic</li>
<li>->getIdentifierByObject in radmiraal</li>
</ul>
<li>persistenceManager vs documentManager method names</li>
<ul>
<li>add; persist</li>
<li>update; merge</li>
<li>remove; remove</li>
<li>createQueryForType; [createLuceneQuery, createNativeQuery, createQuery]</li>
</ul>
</ul>
<li>Doctrine's PersistenceManager uses the Annotations Driver</li>
<ul>
<li>Annotations</li>
<ul>
<li>Entity</li>
<ul>
<li>map the repository / set CustomRepositoryClass</li>
<li>markReadOnly</li>
</ul>
</ul>
<li>loadMetaDataForClass</li>
<ul>
<li>evaluatePropertyAnnotations</li>
<ul>
<li>maps to column names, OneToOne, OneToMany, ManyToOne, ManyToMany</li>
</ul>
<li>evaluateOverridesAnnotations</li>
<li>evaluateLifeCycleAnnotations</li>
<ul>
<li>public methods</li>
<ul>
<li>PrePersist</li>
<li>PostPersist</li>
<li>PreUpdate</li>
<li>PostUpdate</li>
<li>PreRemove</li>
<li>PostRemove</li>
<li>PostLoad</li>
<li>PreFlush</li>
</ul>
</ul>
<li>isTransient (yes if not entity or value object)</li>
</ul>
<li>I want to use Flow/Validate</li>
<li>PersistenceManager fires</li>
<ul>
<li>Yaml Configuration</li>
<ul>
<li>All combined/cached like views.yaml</li>
</ul>
</ul>
</ul>
</ul>
</div>
<div>
<br /></div>
<div>
How other things interact w/ files</div>
<ul>
<li>Parts of flow that work with files</li>
<ul>
<li>Reflection uses cache to interact w/ Files</li>
<li>Fluid uses cache in compiler, and strings get passed to parser (it doesn't work w/ files)</li>
<li>TypoScript also parses strings, not files</li>
<li>Kickstarter</li>
<ul>
<li>uses $templatePathAndFilename = resource://TYPO3.Kickstart/Private/...</li>
<li>shoves into renderTemplate()</li>
<li>then generateFile()</li>
<ul>
<li>File::createDirectoryRecursviely</li>
</ul>
<li>uses reflection for php files</li>
<li>hard codes important paths</li>
<ul>
<li>Classes</li>
<li>Tests</li>
<li>Resources</li>
</ul>
<li>Validate PackageKey ; PackageManager->isPackageAvailable</li>
</ul>
</ul>
<li>TYPO3\Flow\Utility</li>
<ul>
<li>Environment</li>
<ul>
<li>$this->environment->getPathToTemporaryDirectory()</li>
</ul>
<li>Files</li>
<ul>
<li>::getUnixStylePath($cacheDirectory)</li>
<li>::concatenatePaths($cacheDirectory)</li>
<li>::readDirectoryRecursively($cacheDirectory)</li>
<li>::createDirectoryRecursively($cacheDirectory)</li>
<li>::emptyDirectoryRecursively($cacheDirectory)</li>
</ul>
</ul>
<li>php funcs</li>
<ul>
<li>file_exists($pathAndFillename)</li>
<li>unlink($pathAndFilename)</li>
<li>file_get_contents($pathAndFilename)</li>
<li>file_put_contents($tempCacheEntryPathAndFilename, $data)</li>
<li>rename($tempCacheEntryPathAndFilename, $newPathAndFilename)</li>
<li>filesize($cacheEntryPathAndFilename)</li>
<li>filemtime($file)</li>
<li>new \DirectoryIterator ($this->cacheDirectory)</li>
<ul>
<li>->valid()</li>
<li>->next()</li>
<li>->isDot()</li>
</ul>
<li>glob($pattern) find pathname matching the pattern</li>
<li>$fileHandle=fopen($this->logFileUrl, 'ab')</li>
<li>dirname($logFileUrl)</li>
<li>is_dir($)</li>
<li>is_link($)</li>
<li>stream_get_meta_data($fileHandle)</li>
<li>fclose($)</li>
<li>chmod( , )</li>
<li>touch()</li>
<li>fputs()</li>
</ul>
</ul>
<div>
Services<br />
<br />
<ul>
<li>RoundTrip</li>
<ul>
<li><a href="https://git.typo3.org/TYPO3v4/Extensions/extension_builder.git/blob/HEAD:/Classes/Service/RoundTrip.php#l647">Extension Builder's RoundTrip Service</a></li>
<li>Extension Builder uses <a href="https://git.typo3.org/TYPO3v4/Extensions/extension_builder.git/blob/HEAD:/Classes/Domain/Model/Class/Class.php">reflection</a> instead of string magic</li>
</ul>
<li>Migration</li>
<ul>
<li>Doctrine Migrations</li>
<ul>
<li><a href="https://github.com/doctrine/migrations/blob/master/lib/Doctrine/DBAL/Migrations/Configuration/Configuration.php">Doctrine/DBAL/Migrations/Configuration</a></li>
<li><a href="https://github.com/doctrine/migrations/blob/master/lib/Doctrine/DBAL/Migrations/Migration.php">Doctrine/DBAL/Migrations/Migration</a></li>
<li><a href="http://docs.doctrine-project.org/projects/doctrine-migrations/en/latest/reference/managing_migrations.html">Managing Migrations Doc</a></li>
</ul>
<li><a href="https://github.com/TYPO3-PackageBuilder/TYPO3.PackageBuilder">TYPO3.PackageBuilder</a></li>
</ul>
<li>REST API</li>
<ul>
<li><a href="https://twitter.com/bwaidelich/status/338967177292046336">https://twitter.com/bwaidelich/status/338967177292046336</a> (RESTful efforts in Flow)</li>
<li>Specs that help with <a href="http://en.wikipedia.org/wiki/HATEOAS">HATEOAS</a></li>
<ul>
<li><a href="http://jsonapi.org/">JSON API Spec</a></li>
<li><a href="http://json-ld.org/">JSON for Linked Data Spec</a></li>
<li><a href="http://stateless.co/hal_specification.html">HAL (Hypertext Application Language) Spec</a></li>
<li><a href="http://stackoverflow.com/questions/1164154/is-that-rest-api-really-rpc-roy-fielding-seems-to-think-so">HATEOAS question on stackoverflow</a></li>
</ul>
<li><a href="http://emberjs.com/guides/models/the-rest-adapter/">ember.js REST Adapter</a></li>
<li><a href="https://www.google.com/#output=search&q=hateoas+vs+uritemplate">https://www.google.com/#output=search&q=hateoas+vs+uritemplate</a></li>
</ul>
</ul>
<div>
<a href="http://en.wikipedia.org/wiki/Behavior_driven_development">Behavior</a>/<a href="http://en.wikipedia.org/wiki/Test_driven_development">Test</a> Driven Development</div>
</div>
</div>
<div>
<ul>
<li><a href="http://docs.behat.org/guides/1.gherkin.html">Writing Features for Behat to test in Gherkin</a></li>
</ul>
</div>
<div>
<br /></div>
</div>
Anonymoushttp://www.blogger.com/profile/14944134144016532385noreply@blogger.com0tag:blogger.com,1999:blog-9217356639662394871.post-44942341395758016942013-05-30T18:12:00.003-05:002013-05-31T11:11:28.481-05:00Boilerplates and Builders in TYPO3 Neos<i>I will edit this article to edit the In-Scope and Out-of-Scope sections as needed. I wanted to publish this sooner rather than later.</i><br />
<h2>
GSoC Deliverables</h2>
<h3>
In-Scope for this GSoC</h3>
<div>
I plan to deliver the following packages:</div>
<div>
<ul>
<li>TYPO3.BuilderAbstract</li>
<li>TYPO3.TemplateBuilder</li>
<li>TYPO3.ZurbBoilerplate</li>
<li>TYPO3.BootstrapBoilerplate</li>
</ul>
</div>
<div>
Important features / components:</div>
<div>
<ul>
<li>RoundTripService (very basic)</li>
<ul>
<li>TemplateBuilder ties into the Fluid parser</li>
</ul>
<li>MigrationService (very basic)</li>
<li>Backend Package Manipulation</li>
<ul>
<li>Copy boilerplate package contents into a Deriative package</li>
</ul>
<li>Boilerplate Configuration in YAML</li>
<ul>
<li>Options layer that allows for multiple "presets" (like in TYPO3.Form). In the context of the TemplateBuilder, those "presets" should be exposed in the UI as a "theme" layer of options.</li>
<li>File manipulation indicators (a way to say that you inserted a fluid widget at a particular point in a template. These will be stored in the YAML files as Eel/FlowQuery because XPath only works for XML, and we will work with more than XML)</li>
</ul>
<li>Fluidify SourceTemplates in TemplateBuilder (the backend for something like TemplaVoila)</li>
</ul>
<div>
<i><b>Note</b>: These are the names I prefer right now, though they've gone through several iterations. If these are not clear, please let me know. TYPO3.BuilderAbstract used to be called TYPO3.Boilerplate. TYPO3.TemplateBuilder used to be called TYPO3.FluidBuilder. SourceTemplates used to be called RawTemplates, NakedTemplates, or NakedBoilerplates.</i></div>
</div>
<h3>
Out-of-Scope for this GSOC</h3>
<div>
I will not have time to work much, if at all, on these:</div>
<div>
<ul>
<li>Anything that works with TypoScript</li>
<li>Much of the UI (may be partially working thanks to TYPO3.Ice - but that's not my focus)</li>
<ul>
<li>Including the TemplaVoila-like UI to select the various parts of a SourceTemplate file</li>
</ul>
</ul>
</div>
<h2>
Package Dependencies</h2>
<table align="center" cellpadding="0" cellspacing="0" class="tr-caption-container" style="margin-left: auto; margin-right: auto; text-align: center;"><tbody>
<tr><td style="text-align: center;"><a href="https://blogger.googleusercontent.com/img/b/R29vZ2xl/AVvXsEigTAVB-A2Jevt6b9kYZnw80E2bkCuiVSEUddf1HK_GUnV60Z83CXK4WYMeX3NrCdzjO3WO5eCxYUvwmWMslacN6-m4CP7pKxEDuModS0y1EZQUW8Vnr2LggOVU6FvSjsDO9A5-gcWbF08/s1600/BoilerplateDependencies.png" imageanchor="1" style="margin-left: auto; margin-right: auto;"><img alt="Diagram of Package Dependencies" border="0" height="260" src="https://blogger.googleusercontent.com/img/b/R29vZ2xl/AVvXsEigTAVB-A2Jevt6b9kYZnw80E2bkCuiVSEUddf1HK_GUnV60Z83CXK4WYMeX3NrCdzjO3WO5eCxYUvwmWMslacN6-m4CP7pKxEDuModS0y1EZQUW8Vnr2LggOVU6FvSjsDO9A5-gcWbF08/s640/BoilerplateDependencies.png" title="" width="640" /></a></td></tr>
<tr><td class="tr-caption" style="text-align: center;">Boilerplates depend on the Builder that understands the files in them. Builders depend on the BuilderAbstract.<br />
Builders extend the basic package manipulation of BuilderAbstract to handle particular filetypes<br />
(eg TemplateBuilder handles Fluid files, and eventually will deal with SASS/LESS/CSS, etc).<br />
BuilderAbstract also provides generic services Builder services (eg RoundTripService, MigrationService).<br />
The PackageBuilder will probably orchestrate the other Builders when building a package, as they are complementary.<br />
Derivative Packages never depend on the Boilerplates they are based on. They get modified copies of boilerplate files.</td></tr>
</tbody></table>
<div>
<div>
<br /></div>
<div>
<h2>
Producing a Derivative Package</h2>
<table align="center" cellpadding="0" cellspacing="0" class="tr-caption-container" style="margin-left: auto; margin-right: auto; text-align: center;"><tbody>
<tr><td style="text-align: center;"><a href="https://blogger.googleusercontent.com/img/b/R29vZ2xl/AVvXsEjSCCaHf-uy2EGuxfvoYZGsf9P6jQFo3u6BjzroGRN3ZeVs7pfTMcbPNDZzh27R-Ukwg87LuQmpzv-rVNfjlja2glnFNOOICWlrBHYKsREeVXaxsVuZlYIKzXKqE2qVH4plhyY_KzLBzo0/s1600/BoilerplateProcessing.png" imageanchor="1" style="margin-left: auto; margin-right: auto;"><img border="0" height="292" src="https://blogger.googleusercontent.com/img/b/R29vZ2xl/AVvXsEjSCCaHf-uy2EGuxfvoYZGsf9P6jQFo3u6BjzroGRN3ZeVs7pfTMcbPNDZzh27R-Ukwg87LuQmpzv-rVNfjlja2glnFNOOICWlrBHYKsREeVXaxsVuZlYIKzXKqE2qVH4plhyY_KzLBzo0/s640/BoilerplateProcessing.png" width="640" /></a></td></tr>
<tr><td class="tr-caption" style="text-align: center;">This shows how Derivative Packages are made with the TemplateBuilder. The user has several choices:<br />
(1) Selects a SourceTemplate (HTML/CSS) that will be converted to Fluid Templates in a Derivative Package<br />
(2) Copy Fluid Templates from a Boilerplate Package and customize in a Derivative Package<br />
(3) Start with nothing, and generate a Fluid Templates in a Derivative Package,<br />
but insert some Fluid Widgets from a Boilerplate Package</td></tr>
</tbody></table>
</div>
<br />
<i>I produced these images in <a href="http://www.yworks.com/en/products_yed_about.html">yED</a>. I can provide the original .graphml files if requested.</i></div>
Anonymoushttp://www.blogger.com/profile/14944134144016532385noreply@blogger.com0tag:blogger.com,1999:blog-9217356639662394871.post-92143526162629363032013-05-28T19:16:00.001-05:002013-05-28T19:40:06.274-05:00Basic Designs for TYPO3.BoilerplateI'm designing <a href="https://github.com/cognifloyd/TYPO3.Boilerplate">TYPO3.Boilerplate</a>.<br />
<div>
<br /></div>
<div>
<h2>
Basics of TYPO3.Boilerplate</h2>
</div>
<div>
<ul>
<li><b>Boilerplate Package[s] </b>(Alternative name: Boilerplate[s]): A package that resides in FlowRoot/Packages/Boilerplates/ which has stuff that may be integrated into another package.</li>
<li><b>Derivative Package[s]</b> (Alternative name: Derivative[s] or Boilerplate Derivative[s]): A package that integrates one or more boilerplate packages.</li>
<li><b>Naked Boilerplate[s]</b>: The raw materials that makes a boilerplate without the metadata that TYPO3.Boilerplate needs to create Derivative Packages. These are often part of other packages or libraries. A site package might store the designer provided HTML/CSS files somewhere in the Resources.</li>
</ul>
<div>
<div>
TYPO3.Boilerplate is not very useful (from a user's perspective) on it's own, but is powerful within a Builder app such as FluidBuilder or PackageBuilder.<br />
<br /></div>
</div>
<h3>
Boilerplates and Derivatives</h3>
TYPO3.Boilerplate is concerned with copying stuff from a Boilerplate package to a Derivative Package including interfaces to help Builders process or manipulate the files that get copied. Though the builders work with files, they should be able to treat them as objects via TYPO3.Boilerplate APIs.<br />
<br />
Though I could say that Boilerplates and Derivatives have a parent-child relationship, I thought that would suggest a much more dependent or a hierarchical relationship. Derivative Packages should have a copy of everything they need from the Boilerplate. These Derivatives should never depend on Boilerplates. Only Builders that use a particular Boilerplate package should depend on the Boilerplates.<br />
<br />
Are there situations where something other than a Builder (or a Kickstarter) can depend on a Boilerplate? One possible situation would be an agency (or maybe even Neos) that has a collection of widgets that they store in a Boilerplate package, and reuse those widgets, without modification, in their site packages. In that case, I suppose they could introduce a dependency in their composer.json, but then they run the risk of upgrading one little thing in their boilerplate only to break things in the dependent site packages. It would be better to copy the widgets into the site packages, and then have a Boilerplate Migration that helps to update site packages from one Boilerplate version to the next. In any case, I don't think there should a technical limitation that prevents the dependency; It'd be one of those only-do-this-if-you-know-what-you're-doing kind of things.<br />
<br />
I wonder if TYPO3.Neos.NodeTypes could be considered a Boilerplate package.<br />
<br />
<i>Please respond in the comments, or in the Neos forum, and let me know what you think of this design direction.</i><br />
<h3>
Naked Boilerplates and Boilerplate Metadata</h3>
In initial designs, I used the term Virtual Boilerplate, but I think Naked Boilerplate is a more appropriate term, because it has templates, but they are missing any boilerplate metadata. It is up to a Builder Package whether or not they support Naked Boilerplates. For some Builders, like PackageBuilder, it won't make much sense. For others, like FluidBuilder (TemplateBuilder?), it makes a lot of sense to support templates that have not been converted into Fluid templates already.<br />
<br />
These HTML/CSS/JS templates that have not been broken into Fluid templates are Naked Boilerplates. For example, Twitter Bootstrap is a <b>Naked Boilerplate</b>. To create a Fluid <b>Boilerplate Package</b>, Twitter Bootstrap gets integrated into some Fluid templates with metadata that tells TYPO3.Boilerplate<br />
<ul>
<li>which Builder to use (FluidBuilder) and</li>
<li>what stuff is available in the Boilerplate (lists of layouts, widgets, options like changing colors, etc)</li>
</ul>
<div>
The Builder uses that metadata to present a list of stuff to the user. They can then integrate that stuff into their own Derivative Package. FluidBuilder could create fluid templates in an Application package or a Site package using the widgets/options (stuff) that the user chooses from the list of available stuff.</div>
<div>
<br />
The site package that is based on Twitter Bootstrap does not have information about <i>all </i>of the widgets available in the Boilerplate package; Instead, it contains metadata about which parts of the Boilerplates were integrated into it (e.g. which widgets were included in the site or application package). Ideally, the Derivative Package could have enough information to facilitate upgrades from one Boilerplate version to the next (deltas or diffs or steps taken to create the site package from the old boilerplate. These changes would be rebased--like git--on the new version to help with template upgrades).<br />
<br /></div>
</div>
<div>
<h3>
Derivative Metadata</h3>
</div>
<div>
Derivative Packages will need metadata about:<br />
<ul>
<li>Integrated Boilerplates</li>
<ul>
<li>Which Boilerplates have been integrated</li>
<li>What stuff (layouts/widgets/components) came from a particular Boilerplate (I assume that if it didn't come from the Boilerplate, then it was added by the developer, so care should be taken not to overwrite those changes.)</li>
<li>How things were integrated (like where widgets were inserted) could use Eel/FlowQuery (my preference) or XPath (which only works on XML-like files, but could be very useful in some cases.)</li>
</ul>
<li>Versioning Information to facilitate Migrations</li>
<ul>
<li>Kickstarters and Builders might not support migrating from one version of a Boilerplate to the next, but they should store something that says which version of a Boilerplate was used in generating the derivative package.</li>
<li>Neos and other agencies might provide a Boilerplate package with a collection of widgets that can be added to templates. How/where these widgets are inserted should be carefully recorded, so that changes may be replayed/rebased on any manual template modifications or to facilitate migrating a package from one boilerplate version to the next.</li>
</ul>
<li>Builder-specific options</li>
<ul>
<li>For example, the FluidBuilder (maybe TemplateBuilder would be a better name) would have a theme layer that uses theming options. If a Boilerplate can be customized with custom colors (think SASS or LESS), then the Builder could expose those options in some kind of interface.</li>
</ul>
</ul>
<div>
<h2>
Initial Thoughts on Code</h2>
</div>
</div>
<div>
<div>
Note: I need to go through Flow's code again to decide which parts can be reused. Possibilities include:<br />
<br />
<ul>
<li>Configuration (Store all the metadata in yaml files)</li>
<li>Monitor (File Monitor / Change Detection, Possibly implement ChangeDetectionStrategyInterface to look for specific changes in target files)</li>
<li>Package (This has some cool stuff, but I can't depend on a package being "activated" before I interact with it, since Builders and Kickstarters will be creating packages. Packages might be broken until a Kickstarter/Builder is finished creating it.) </li>
<li>Reflection (Possibly only useful in builders that work with PHP...)</li>
<li>Resource (Could be very helpful, as long as it's not restricted to just the Resources Folder. This needs to be able to interact with any file in a package)</li>
<li>Utilities (File manipulation stuff)</li>
</ul>
For the services and the domain (which does not get persisted to a database, everything is stored in files), we have:<br />
<ul>
<li>Model</li>
<ul>
<li>Packages/ <i>(Builders should extend these to provide the business-logic of how to manipulate relevant parts of a Derivative based on metadata from the Boilerplate)</i></li>
<ul>
<li>AbstractPackage implements PackageInterface</li>
<li>BoilerplatePackage extends AbstractPackage</li>
<li>DerivativePackage extends AbstractPackage <i>(might be a Site or Applicaiton)</i></li>
<li><i>(Others like library could be implemented at some point if someone needs it, but they might not extend the PackageInterface... I'm not sure on that, and I think it is outside the scope of this project.)</i></li>
</ul>
<li>NakedBoilerplateInterface</li>
</ul>
<li>Factories<i> (extended in Builder packages to provide implementation details of how to work with different parts of a package)</i></li>
<ul>
<li>Copy between packages (Boilerplate to Site; Boilerplate to Application)</li>
</ul>
<li>Repository <i>(Each package type has a separate repository that extends the basic repository)</i></li>
<ul>
<li>BoilerplateRepository is the collection of BoilerplatePackages</li>
<li>SitePackagesRepository is a collection of DerivativePackages</li>
<li>ApplicationRepository is a collection of DerivativePackages</li>
</ul>
<li>Service</li>
<ul>
<li>RoundTrip service <i>(like PackageBuilder: Detecting changes in watched packages to trigger updates in registered Builders -- Uses FileMonitor)</i></li>
<li>Migration service <i>(assists in migrating a Derivative from one Boilerplate version to the next, assuming the boilerplate included migration scripts. For inspiration: Doctrine Migrations, TYPO3CR Migrations, Flow Code Migrations, git rebase and friends)</i></li>
</ul>
</ul>
</div>
<div>
</div>
</div>
<div>
<h2>
Boilerplate Math</h2>
</div>
<div>
Calculus is my inspiration for and explanation of how TYPO3.Boilerplate works. I call this, Boilerplate Math.<br />
<br />
<blockquote class="tr_bq">
<i>NOTE: I don't think people need to understand that I got the terms from Calculus to use the Boilerplate API. "Integrate" and "derive" are common enough words, that I think the meaning will be easy enough to understood for anyone who needs to use the Boilerplate API. But, for those that might want to modify Boilerplate, the history of them might come in handy.</i></blockquote>
</div>
<div>
<br />
Consider these basic calculus equations:<br />
<table align="center" cellpadding="0" cellspacing="0" class="tr-caption-container" style="margin-left: auto; margin-right: auto; text-align: center;"><tbody>
<tr><td style="text-align: center;"><a href="http://latex.codecogs.com/gif.latex?\int{f'(x)}dx=f(x)+C" imageanchor="1" style="margin-left: auto; margin-right: auto;"><img alt="\int{f'(x)}dx=f(x)+C" border="0" src="http://latex.codecogs.com/gif.latex?\int{f'(x)}dx=f(x)+C" title="" /></a></td></tr>
<tr><td class="tr-caption" style="text-align: center;"><span style="font-size: small;">Integrate <i>f'(x)</i> to get <i>f(x)</i> plus some change</span></td></tr>
</tbody></table>
<br />
<table align="center" cellpadding="0" cellspacing="0" class="tr-caption-container" style="margin-left: auto; margin-right: auto; text-align: center;"><tbody>
<tr><td style="text-align: center;"><a href="http://latex.codecogs.com/gif.latex?\frac{dy}{dx}f(x)+C=f'(x)" imageanchor="1" style="margin-left: auto; margin-right: auto;"><img alt="\frac{dy}{dx}f(x)+C=f'(x)" border="0" src="http://latex.codecogs.com/gif.latex?\frac{dy}{dx}f(x)+C=f'(x)" title="" /></a></td></tr>
<tr><td class="tr-caption" style="text-align: center;"><span style="font-size: small;">Derive </span><i style="font-size: medium;">f'(x)</i><span style="font-size: small;"> from </span><i style="font-size: medium;">f(x)</i><span style="font-size: small;"> plus some change</span></td></tr>
</tbody></table>
<br />
If I say that <i>f'(x)</i> is a Fluid Boilerplate package that gets integrated into <i>f(x)</i>, a SitePackage, then:<br />
<table align="center" cellpadding="0" cellspacing="0" class="tr-caption-container" style="margin-left: auto; margin-right: auto; text-align: center;"><tbody>
<tr><td style="text-align: center;"><a href="http://latex.codecogs.com/gif.latex?\int{B(f)}df=P(f)+C" imageanchor="1" style="margin-left: auto; margin-right: auto;"><img alt="\int{B(f)}df=P(f)+C" border="0" src="http://latex.codecogs.com/gif.latex?\int{B(f)}df=P(f)+C" title="" /></a></td></tr>
<tr><td class="tr-caption" style="text-align: center;"><span style="font-size: small;">Integrate Fluid (<i>f</i>) Boilerplate (<i>B</i>) into SitePackage (<i>P</i>) with Changeset (<i>C</i>)</span></td></tr>
</tbody></table>
<div>
<span style="text-align: center;"></span></div>
<br />
<table align="center" cellpadding="0" cellspacing="0" class="tr-caption-container" style="margin-left: auto; margin-right: auto; text-align: center;"><tbody>
<tr><td style="text-align: center;"><a href="http://latex.codecogs.com/gif.latex?\frac{dp}{df}P(f)+C=B(f)" imageanchor="1" style="margin-left: auto; margin-right: auto;"><img alt="\frac{dp}{df}P(f)+C=B(f)" border="0" src="http://latex.codecogs.com/gif.latex?\frac{dp}{df}P(f)+C=B(f)" title="" /></a></td></tr>
<tr><td class="tr-caption" style="text-align: center;"><span style="font-size: small;">Derive Fluid (<i>f</i>) Boilerplate (<i>B</i>) Package (<i>p</i>) from SitePackage (<i>P</i>) with Chagneset (<i>C</i>) </span></td></tr>
</tbody></table>
</div>
<div>
A SitePackage might use parts from more than one Fluid Boilerplate. For example, it could integrate some widgets from twitter bootstrap as well as widgets from an agency's custom boilerplate that they use for many of their websites.</div>
<div>
<br /></div>
<div>
<br /></div>
Anonymoushttp://www.blogger.com/profile/14944134144016532385noreply@blogger.com0tag:blogger.com,1999:blog-9217356639662394871.post-28371355531097915112013-05-25T14:35:00.002-05:002013-05-30T14:21:00.074-05:00Designing TYPO3.BoilerplateSo, I've been thinking about boilerplates in TYPO3 Flow + Neos (<a href="http://www.google-melange.com/gsoc/proposal/review/google/gsoc2013/cognifloyd/1" target="_blank">it's my GSOC project</a>). After filling up a couple of whiteboards, I started writing stuff in my notebook. I don't expect my notes to mean very much to anyone but me, but I love to see how other people work, so I'm posting <a href="https://docs.google.com/file/d/0B5ggNaMEnqekZko5VVo2TW5OYzQ/edit?usp=sharing" target="_blank">all of my notes</a> so that you can see how I work.<br />
<br />
edit: I removed the iframe because it was demanding more attention than it deserved. <a href="https://docs.google.com/file/d/0B5ggNaMEnqekZko5VVo2TW5OYzQ/edit?usp=sharing">Check the notes out here.</a>Anonymoushttp://www.blogger.com/profile/14944134144016532385noreply@blogger.com0tag:blogger.com,1999:blog-9217356639662394871.post-13790333006225201362013-05-10T22:48:00.001-05:002013-05-10T22:48:09.367-05:00Flow Package Types + Boilerplate ThoughtsSo, there are a bunch of different package types for TYPO3 Flow. If you look in the packages folder you'll see several major kinds:<br />
<br />
<ul>
<li>Distribution/ : The super-package that includes (via composer.json) all the other packages</li>
<ul>
<li>Packages/</li>
<ul>
<li><b>Applications</b>: Flow-based apps</li>
<li><b>Framework</b>: Flow's packages</li>
<li><b>Libraries</b>: 3rd party libs and non-Flow packages</li>
<li><b>Sites</b>: Neos site packages</li>
<li><b>Boilerplates</b>: Meta-templates (part of my <a href="http://www.google-melange.com/gsoc/proposal/review/google/gsoc2013/cognifloyd/1">GSOC Proposal</a>) that contain boilerplate files (php code, fluid templates, yaml, ...)</li>
</ul>
</ul>
</ul>
<div>
Then, there are some common naming conventions for Flow applications.</div>
<div>
<ul>
<li>Foo<b>Kickstarter</b>: for initial creation of packages of type "Foo".</li>
<li>Foo<b>Builder</b>: to not only create, but edit "Foo" packages.</li>
</ul>
<div>
So, if my GSOC project is only going to be a one-time copy kind of a package, then I need to call it FluidKickstarter. If I give it the ability to edit and not just start templates, like I plan, then it should be called FluidBuilder.</div>
<div>
<br /></div>
<div>
I'm thinking of creating a Boilerplate framework. That way, there'd be a TYPO3.FluidBoilerplate that deals with Fluid specific template manipulation, but the TYPO3.Boilerplate package would contain the more abstract parts of dealing with any Boilerplate package. So that would mean there'd be something like this:</div>
<ul>
<li>Foo<b>Boilerplate:</b></li>
<ul>
<li>extends TYPO3.Boilerplate to assist builders in building "Foo" packages.</li>
<li>Not to be confused with packages in the Boilerplates folder, which contain raw material for the Boilerplate system to use in creating various types of packages (by FluidBuilder, PackageBuilder, FormBuilder, etc)</li>
</ul>
</ul>
<div>
That solution feels awkward. Perhaps, there's a TYPO3.Boilerplate package, like before, that provides the abstract ways of working with Boilerplate packages. Then, the Builder packages would include a server-side layer that interacts with TYPO3.Boilerplate to do the building of packages (Fluid, Package (Flow), Form, Ember). Plus, each Builder package would contain a Frontend app that does the same thing as the backend, but in the browser. Then they would communicate over some RESTful API with Ember Data.</div>
</div>
<div>
<br /></div>
<div>
To date, that has been the solution for the other builder projects, so I think that would be a good convention to follow, with one change, in that I'll be using Boilerplate package, and hopefully other Builders will follow suite.</div>
<div>
<br /></div>
<div>
One of the issues with current Builders is that they store all of the template like stuff in their Private Resources folder. That's not very extensible, and though it might work for a lot of the current Builders, it won't work for FluidBuilder because I want there to be a lot of ready-made boilerplates that people can use to create whatever site they want as fast as they want. They should be able to make their own, or use Twitter Bootstrap, or H5BP, or whatever other grid system they enjoy.</div>
<div>
<br /></div>
<div>
Why? Flow is already fun for developers, but it needs to attract designers. So, Neos should be fun for designers to use, and Boilerplate packages are a good way to get there.</div>
Anonymoushttp://www.blogger.com/profile/14944134144016532385noreply@blogger.com0Fairpark, Salt Lake City, UT, USA40.7741479 -111.9228957999999940.7500994 -111.96323629999999 40.7981964 -111.88255529999999tag:blogger.com,1999:blog-9217356639662394871.post-52478568493916105872013-05-10T18:15:00.000-05:002013-05-10T23:20:34.365-05:00Ice and PackageBuilder and Boilerplates, Oh my!So, I was just browsing github, and stumbled on <a href="https://github.com/radmiraal/TYPO3.Ice">TYPO3.Ice</a> (ICE=Interface Construction Environment). Looking around, there's also a <a href="http://forge.typo3.org/projects/package-ice">project on forge</a>, and a <a href="https://git.typo3.org/FLOW3/Packages/TYPO3.Ice.git">git.typo3.org repo</a>. I wanted to make sure it wasn't a previous effort to build TYPO3.FluidBuilder (<a href="http://www.google-melange.com/gsoc/proposal/review/google/gsoc2013/cognifloyd/1">my GSOC proposal</a>), so I asked Rens on IRC what Ice was all about.<br />
<h4>
TYPO3.PackageBuilder</h4>
<div>
Apparently, it's part of the effort to create a TYPO3.PackageBuilder (see the <a href="https://github.com/TYPO3-PackageBuilder">github project</a>, the <a href="http://forge.typo3.org/projects/package-packagebuilder/wiki">forge project</a>, and the <a href="https://git.typo3.org/FLOW3/Packages/TYPO3.PackageBuilder.git">git.typo3.org repo</a>). PackageBuilder is like the next generation of the <a href="http://wiki.typo3.org/T3Doc/Extension_Builder">ExtensionBuilder</a> that we know and love from TYPO3 CMS. It'll have a domain building UI, so that you can graphically create your domain objects and link them all together. I'm very excited to see someone working on the PackageBuilder.</div>
<div>
<br /></div>
<h4>
TYPO3.Ice in TYPO3.PackageBuilder</h4>
<div>
PackageBuilder needs a UI similar to TYPO3.FormBuilder, so some of that interface was abstracted out, so that they could be reused in multiple packages. That common UI lives in TYPO3.Ice.</div>
<div>
<br /></div>
<h4>
TYPO3.FluidBuilder</h4>
<div>
The best part of that? I'll probably be able to use TYPO3.Ice when I create TYPO3.FluidBuilder for a GSOC project. Maybe it'll be possible for me to create the UI portion in FluidBuilder after all, since it's mostly built for me already.</div>
<div>
<br /></div>
<h4>
Boilerplates in TYPO3.PackageBuilder</h4>
<div>
Plus, looking through PackageBuilder's code, it looks like PackageBuilder could use the Boilerplate concept as well. Right now, there's <a href="https://github.com/TYPO3-PackageBuilder/TYPO3.PackageBuilder/tree/master/Resources/Private/CodeTemplates">Resources/Private/CodeTemplates</a>. They've got both TYPO3 CMS and Flow templates, which could be put in separate boilerplate packages, so that you don't have to update the whole PackageBuilder package every time one of the boilerplates gets updated. Plus, then other organizations could create their own Flow Package Boilerplates, and use PackageBuilder to create packages with them.</div>
<div>
<br />
Resources/Private/Generator could become Boilerplate packages in <a href="https://git.typo3.org/FLOW3/Packages/TYPO3.SiteKickstarter.git/tree/HEAD:/Resources/Private/Generator">SiteKickstarter</a> and <a href="https://git.typo3.org/FLOW3/Packages/TYPO3.Kickstart.git/tree/HEAD:/Resources/Private/Generator">Kickstart</a>. <a href="https://git.typo3.org/FLOW3/Packages/TYPO3.FormBuilder.git/tree/HEAD:/Resources/Private/NewFormTemplates">Resources/Private/NewFormTemplates</a> in FormBuilder could also be a Boilerplate, though one yaml file might not warrant it, so it could be treated like a virtual boilerplate. Potentially, other people could create Form boilerplates, though.<br />
<br /></div>
<div>
I'm very glad that I found out about Ice and PackageBuilder. It looks like my GSOC project will be very useful indeed (who wants their work to die and rot unused in the backroom?!). I hope that the Boilerplate concept, and the FluidBuilder will help more people to start using Flow and get involved with Neos.</div>
<div>
<br /></div>
Anonymoushttp://www.blogger.com/profile/14944134144016532385noreply@blogger.com0Fairpark, Salt Lake City, UT, USA40.7741479 -111.9228957999999940.7500999 -111.96323629999999 40.7981959 -111.88255529999999tag:blogger.com,1999:blog-9217356639662394871.post-69539481177401643672013-05-03T19:27:00.000-05:002013-05-03T19:29:05.732-05:00Neos (dev-master) HintsI'm using Neos from dev-master. Here are some things I've run up against with my group.<br />
<h2>
Workspaces</h2>
<div>
You can see and work in anyone's workspace, not just your own. If you want to work in the same workspace with someone, just edit the url.</div>
<div>
<br /></div>
<div>
@ in a Neos URL tells you what workspace you're looking at or using. For example, this shows that I'm in cognifloyd's workspace (hey, that's me!).</div>
<div>
<br /></div>
<div class="separator" style="clear: both; text-align: center;">
<a href="https://blogger.googleusercontent.com/img/b/R29vZ2xl/AVvXsEgcdi8gtmGaiUSgkt23zY_yl1FmOjdf-aOuOs2_HQK7UDIfiMyrcnD_s9YI9uYYVCbCiPB4TNUjZo6aF25iN5k3Z7Y9X2hJsUu-KMn1rpOCrvmDv_eRFNRACloE2YPi9YxbiBf9gViU7Vo/s1600/url1.png" imageanchor="1" style="margin-left: 1em; margin-right: 1em;"><img border="0" src="https://blogger.googleusercontent.com/img/b/R29vZ2xl/AVvXsEgcdi8gtmGaiUSgkt23zY_yl1FmOjdf-aOuOs2_HQK7UDIfiMyrcnD_s9YI9uYYVCbCiPB4TNUjZo6aF25iN5k3Z7Y9X2hJsUu-KMn1rpOCrvmDv_eRFNRACloE2YPi9YxbiBf9gViU7Vo/s1600/url1.png" /></a></div>
<div>
<br /></div>
<div>
If I wanted to see the workspace for user john316 I would replace "@user-cognifloyd" with "@user-john316". Eventually, there will be some kind of access control to say which users can interact with which workspaces, but for now, once you're logged in, everything's fair game.</div>
<div>
<br /></div>
<div>
One way to use this is to share a workspace with a group of colleagues. Before I found this, we would each publish our changes (move them live) every time we wanted to share our work. This way, we can all work in the same workspace, and publish it live when everyone has finished their part.</div>
<div>
<br /></div>
<h2>
Wireframe Mode</h2>
<div>
Resizing images in wireframe mode is currently broken.</div>
<div>
<br /></div>
<div>
Sections don't show up reliably until you've got content in them.</div>
<div>
<br /></div>
<div>
When you aren't in wireframe mode, you can just drag-n-drop elements to re-organize them. However, this feature isn't in wireframe mode. Instead, click "Inspect" in the lower left hand corner. You can rearrange the elements in there.</div>
<div>
<br /></div>
<div class="separator" style="clear: both; text-align: center;">
<a href="https://blogger.googleusercontent.com/img/b/R29vZ2xl/AVvXsEizcmdLwmXwqvCvnUp_05Q3ahsIElQ9Vbh2ITMHqzuy_0rl2dYGLtBkRiIf8o0CAPifulzyvYqulwk_-QVpUSAcVAoD6R5n9bTCE813anQhm78oT3kEsv5VzqAPSAA3G0A0FmnSKQCK8xo/s1600/inspect.png" imageanchor="1" style="margin-left: 1em; margin-right: 1em;"><img border="0" src="https://blogger.googleusercontent.com/img/b/R29vZ2xl/AVvXsEizcmdLwmXwqvCvnUp_05Q3ahsIElQ9Vbh2ITMHqzuy_0rl2dYGLtBkRiIf8o0CAPifulzyvYqulwk_-QVpUSAcVAoD6R5n9bTCE813anQhm78oT3kEsv5VzqAPSAA3G0A0FmnSKQCK8xo/s1600/inspect.png" /></a></div>
<div>
<br /></div>
<div>
<br /></div>
<div>
When you add a page, be sure to edit the nodepath in the right hand properties bar or you'll get some ugly urls. Neos doesn't seem to be automatically creating the nodepath based on the page name yet.</div>
Anonymoushttp://www.blogger.com/profile/14944134144016532385noreply@blogger.com0tag:blogger.com,1999:blog-9217356639662394871.post-23471611300763464802012-07-11T05:44:00.000-05:002012-07-11T14:50:28.592-05:00Fluid Templating--from v4 to Phoenix<span style="background-color: white;">This post explores my experience transitioning from v4 templates to Phoenix+Fluid Templates.</span><br />
<h2>
<a href="http://www.blogger.com/blogger.g?blogID=9217356639662394871" name="template-v4"></a>
<span style="background-color: white;">Templating in TYPO3v4</span></h2>
<div>
There are a lot of ways to build a site in v4, including "Modern Template Building" (autoparse templates), TemplaVoila, and now we can use <span style="background-color: white;">FLUIDTEMPLATE</span><span style="background-color: white;">s. The site I am converting originally used the templavoila_framework, but a couple of weeks ago, I made it use a FLUIDTEMPLATE instead.</span></div>
<div>
<span style="background-color: white;"><br /></span></div>
<div>
<div>
<span style="background-color: white;">Each of these methods--the templavoila_framework and FLUIDTEMPLATE--gave me some basic templates to get the site I'm working on up and running fast. One of the keys in choosing the templavoila_framework and then fluid was aesthetics and useability. </span><span style="background-color: white;">The site had to look great without using a designer to get it off the ground. Useability is more important than appearance, but aesthetics play a role in useability (If it's ugly, most people don't want to use it). Plus, the site has to look 'polished' for those moments when the sales team is using the docs site as a sales tool to help potential clients understand that their developers will be able to interact with our API.</span></div>
</div>
<div>
<span style="background-color: white;"><br /></span></div>
<h3>
<a href="http://www.blogger.com/blogger.g?blogID=9217356639662394871" name="templavoila"></a>
From templavoila_framework to FLUIDTEMPLATE</h3>
<div>
One of the issues I faced with the templavoila_framework (and templavoila in general) was the effort involved in migrating a template to Phoenix. It would take significantly more effort to convert from the TypoScript and TemplaVoila based approach to fluid, than it would take to go from a FLUIDTEMPLATE in v4 to a fluid template in Phoenix.</div>
<div>
<br /></div>
<div>
At T3CON12CA, Bastian Waidelich shared how he sets up his FLUIDTEMPLATEs in TYPO3v4. His <a href="https://github.com/bwaidelich/Extensions.my_website_com" target="_blank">example site package is available on Github</a>. Bastian's template uses Twitter Bootstrap, which turned out to be a perfect match for the documentation site I'm working on. It's elegant and can handle multi-column content just fine. Bootstrap also gives me great styling for forms, which I'll be using later on as I develop the site. So, I converted the v4 site from the templavoila_framework to use a Site Package based on Bastian's example site package using Twitter Bootstrap.</div>
<div>
<br /></div>
<div>
The result? Fast beauty. It only took me a week to finish the Bootstrap based template and get it integrated into TYPO3v4. One of those days was spent generating an appropriate logo for the site. Overall, for my first time using FLUIDTEMPLATEs, I was very pleased with how little time it took to get up and running.</div>
<div>
<br /></div>
<h2>
<a href="http://www.blogger.com/blogger.g?blogID=9217356639662394871" name="template-phoenix"></a>
Templating in TYPO3 Phoenix</h2>
<div>
I'm currently in the process of converting that FLUIDTEMPLATE into something that Phoenix can use. I just copied most of the Resources folder from my v4 extension to my FLOW3+Phoenix Site Package.</div>
<div>
<br /></div>
<div>
Then, I had to modify the template to work with the ViewHelpers that are available in Phoenix.</div>
<div>
<br /></div>
<div>
Then, I had to modify the template headers, because Phoenix controls the output more than my v4 setup did (I had disabled all head output in v4). As part of modifying the headers, I discovered that the FLOW3 version of Fluid is a lot smarter about linking to the right files for stylesheets. Instead of using an f:uri.* ViewHelper, I could just include the relative location of the stylesheet, and Phoenix automatically cleaned it up to use the base url to the correct resource (props to the devs. :D This feature is awesome).</div>
<div>
<br /></div>
<div>
I also dropped using the f:uri ViewHelper to include the JavaScript files at the end of body.</div>
<div>
<br /></div>
<div>
After some more refactoring, most of the template is working well--Phoenix is inserting content elements right where I told it to.</div>
<div>
<br /></div>
<h3>
<a href="http://www.blogger.com/blogger.g?blogID=9217356639662394871" name="menuing"></a>
Menuing</h3>
<div>
I used the fed:page.menu ViewHelper in v4, so I had to replace that with my own fluid templates for menuing in Phoenix. Though <span style="background-color: white;">TYPO3.TYPO3 provides some nice fluid templates with a great ViewHelper for menuing, they didn't allow me to include the bootstrap classes in the various elements. So, I copied the menu templates into my Site Package, and modified them to include the bootstrap markup+classes, as well as re-using some menu partials that I'd already written for use in v4.</span></div>
<div>
<br /></div>
<div>
I would like to see something that's a little more flexible for generating menus. For example, I really like how fed:page.menu allows me to include the menu inline between the fed:page.menu tags. The ViewHelper just adds the {items} variable in the fluid template to assist in generating the menu.</div>
<div>
<br /></div>
<div>
<h3>
<a href="http://www.blogger.com/blogger.g?blogID=9217356639662394871" name="terminology"></a>
Terminology: Layout, Template, Partial</h3>
<div>
On another note, I've seen the word "template" used in a variety of contexts. However, I don't see anywhere <a href="http://flow3.typo3.org/documentation/guide/partiii/templating.html" target="_blank">in the docs</a> that explain the difference between layouts, templates, and partials. I would appreciate some feedback to make sure I'm using these terms and resource paths correctly.</div>
<div>
<br /></div>
<div>
From what I understand, there's a kind of hiearchy of these template components. The Layout includes Templates. Templates can include other templates or partials. Partials might include other partials.</div>
<div>
<br /></div>
<div>
A layout (stored in Resources/Private/Layouts) Is the overall outline of a fluid template. It seems that TYPO3.TYPO3 already provides its own layout, so Site Packages don't really need to have a Layouts folder, right? But then, what if you have more than one layout for your site, but you want to have separate templates.</div>
<div>
<br /></div>
<div>
A template (stored in Resources/Private/Templates) controls the the presentation of a section (or more) of a particular layout. TYO3.TYPO3 defines one main section that encloses everything in the body tags--it's appropriately called the "body" section. Phoenix also defines a section for additional headerData and stylesheets. Beyond that, you have to somehow control where everything goes in the body section. If you want to include JavaScript at the end of the body tag, then include that in the template. I'm not sure how to handle the case where the site has more than one template for your site.</div>
<div>
<br /></div>
<div>
Partials (stored in Resources/Private/Partials or Resources/Private/Templates/Partials) are short sections of code that can be used and reused anywhere in your template. For example, I use a set of recursive partials for an unlimited depth menu.</div>
</div>
<div>
<br /></div>
<h3>
<a href="http://www.blogger.com/blogger.g?blogID=9217356639662394871" name="multiple-templates"></a>
Using Multiple Templates</h3>
<div>
When you want to use multiple templates in v4, the <a href="https://github.com/bwaidelich/Extensions.my_website_com/blob/master/Configuration/TypoScript/page.setup.ts#L22" target="_blank">Backend Layout field is used to feed the {layout}</a> variable in the template. However, there's no UI in Phoenix [yet] for selecting templates.</div>
<div>
<br /></div>
<div>
<div>
I guess as a stop-gap, I can create a TypoScript object that inserts a similar layout variable... Or perhaps there's a way to inject a variable in the fluid template based on where in the page tree it's being rendered? Does Sites.xml provide a way to have custom variables that are made available in Fluid?</div>
</div>
<div>
<br /></div>
<div>
I'll start grepping+reading more of the phoenix code tomorrow to see if I can find such a thing, but if someone else has already worked this out, that'd be awesome. Please let me know in the comments.</div>
<div>
<br />
<h4>
Related Posts:</h4>
<br />
<ul>
<li><a href="http://cognifloyd.blogspot.com/2012/07/converting-from-typo3v4-to-phoenix.html" target="_blank">Converting from TYPO3v4 to Phoenix</a> (provides context for this project)</li>
</ul>
<br />
<br />
<i><b>Disclaimer</b>: Opinions here are my own, not my employers (InfoTrax Systems).</i></div>Anonymoushttp://www.blogger.com/profile/14944134144016532385noreply@blogger.com0tag:blogger.com,1999:blog-9217356639662394871.post-17811921303076821352012-07-11T03:42:00.001-05:002012-07-11T14:47:33.953-05:00Converting from TYPO3v4 to Phoenix<br />
<div class="MsoNormal">
I'm working on converting a site I've built in TYPO3v4 to
TYPO3 Phoenix (or Foo, or whatever the final name becomes). I'm going to
document the progress and the pitfalls I run into on this blog.<o:p></o:p><br />
<br />
<i>Edit: Added link to related post (see end of this post).</i></div>
<h2>
Is it wise to use Phoenix in such a pre-alpha state?<o:p></o:p></h2>
<div class="MsoNormal">
For many, it is not a good idea to use such pre-alpha
software, especially not for a site that is supposed to be a production site
once conversion from v4 is complete.<o:p></o:p></div>
<div class="MsoNormal">
<br /></div>
<div class="MsoNormal">
That being said, you must understand something about me.
Using Phoenix, or just reading the code that runs Phoenix, feels like a five
year old opening presents on his birthday. Every review in gerrit and every
commit in git is like a new present--they're all beautiful features that just
make the geek inside me want to jump for joy.<o:p></o:p></div>
<div class="MsoNormal">
<br /></div>
<div class="MsoNormal">
Really, go read the code in FLOW3 and Phoenix. I've learned
a lot about good software design by perusing the excellent examples of DDD,
TDD, AOP, and any other programming buzzword you want to throw in the mix.
Right now, FLOW3 and Phoenix are like a submarine where you can't see very much
on the surface of the water (the UI), but when you go into the depths of the
water, into the core of that submarine, there's just power--raw nuclear energy
just begging to fly yours and my next project just as fluid and sleek as a
submarine gliding through the water.<o:p></o:p></div>
<div class="MsoNormal">
<br /></div>
<div class="MsoNormal">
Phoenix also has a wonderful UI with a ton of potential.
When you look at Phoenix's UI, you're looking at an Airforce Squadron that is
ready to put on a show. When Phoenix launches, all you'll see is the bombs
bursting in an awesome show of carefully crafted fireworks that will amaze even
the most stubborn of executives. Aloha is simply a breeze. It's the lift that
carries these airplanes and makes Phoenix soar above the rest of the CMS
landscape. I look forward to <b>not</b>
training editors and anyone else that wants to work with content. Aloha makes
the editing process so simple, that I believe Phoenix could easily be the next
wiki platform. Aloha is easier to learn than wiki language, and with the
amazing security that courses through the veins of FLOW3 and Phoenix, I'll be
able to open up the website to allow people to edit their own content without
relying on a dedicated technical writer like me.<o:p></o:p></div>
<h3>
But what about all the rough edges?<o:p></o:p></h3>
<div class="MsoNormal">
Are there rough edges? Yes. Am I going to use Phoenix
anyway? Yes. Will there be issues? Absolutely.<o:p></o:p></div>
<div class="MsoNormal">
<br /></div>
<div class="MsoNormal">
This is a challenge for me. Using Phoenix is something I've
been toying with for years. The smooth features, for me, outweigh any of the
rough edges I'll face.<o:p></o:p></div>
<div class="MsoNormal">
<br /></div>
<div class="MsoNormal">
I need forms, and TYPO3.Form is an awesome, simple way to
build them.<o:p></o:p></div>
<div class="MsoNormal">
<br /></div>
<div class="MsoNormal">
I want to edit certain tables and bits of documentation as
quickly as possible. Aloha is the key to that. I've already used some Aloha
integration in v4, which has saved me hours of time that I would have spent
manually editing the CSV tables in v4. Aloha is just an easier interface for
all parties involved.<o:p></o:p></div>
<div class="MsoNormal">
<br /></div>
<div class="MsoNormal">
When I find a rough edge, I'll write about it. I'll post
what I've discovered and what I'm doing to hopefully help others. I'll be the
test case to help start discussions that need to happen to make Phoenix ready
for a wider launch.<o:p></o:p></div>
<h2>
Just what does this transition from v4 to Phoenix entail?<o:p></o:p></h2>
<div class="MsoNormal">
For the site I'm building, I will deal with a variety of
parts. Some parts don't even exist in my v4 site yet. Other parts do. In any
case, much of the conceptual site design was completed in v4. These parts include
(in no particular order):<o:p></o:p></div>
<div class="MsoNormal">
<br /></div>
<div class="MsoNormal">
</div>
<ul>
<li><span style="background-color: white;">Templating</span></li>
<li><span style="background-color: white;">Security (I need to have both pages, and individual elements
that are only visible to certain usergroups).</span></li>
<li><span style="background-color: white;">Automatic deployment with JIRA and TYPO3.Surf</span></li>
<li><span style="background-color: white;">Custom plugin(s) to generate some of the content on the site</span></li>
<li><span style="background-color: white;">Generate forms (with TYPO3.Form) on most of the pages with
generated content</span></li>
<li><span style="background-color: white;">Custom ViewHelper and plugin to generate a special menu to
'cascade' or merge pages and content across branches of a page tree based on
who is logged in</span></li>
<li><span style="background-color: white;">Transition any content that could not be automatically
generated from v4 to Phoenix.</span></li>
<li><span style="background-color: white;">Custom FLOW3 Package to export the content in a useable
format to be consumed by external processes.</span></li>
</ul>
<br />
<div class="MsoNormal">
When I blog about these things, I'll focus on the parts that
will spur discussions about Phoenix--like things that need to be developed
further in FLOW3 or Phoenix--or that are more generally interesting. In much of
this, I won't be able to share too much of the code I write, because it involves
interacting with some of our proprietary APIs, but for much of what I'm working
on, I should be able to share what I learn in the process.</div>
<div class="MsoNormal">
<br /></div>
<div class="MsoNormal">
<h4>
Related Posts:</h4>
<br />
<ul>
<li><a href="http://cognifloyd.blogspot.com/2012/07/fluid-templating-from-v4-to-phoenix.html" target="_blank">Fluid Templating--from v4 to Phoenix</a></li>
</ul>
</div>
<div class="MsoNormal">
<br /></div>
<div class="MsoNormal">
<b><i>Disclaimer</i></b><i>: These
opinions are my own, and do not necessarily reflect the opinions of my
employer, InfoTrax Systems. InfoTrax is an international corporation that
provides software solutions and consulting services to the MLM and direct
marketing industry. My job is to document the developer oriented parts of our
software such as the API we provide to our customers.<o:p></o:p></i></div>Anonymoushttp://www.blogger.com/profile/14944134144016532385noreply@blogger.com0Salt Lake City, UT, USA40.777683 -111.91341340.6814905 -112.0713415 40.873875500000004 -111.75548450000001tag:blogger.com,1999:blog-9217356639662394871.post-14564730670670755432012-03-23T04:40:00.000-05:002012-03-23T23:21:59.892-05:00Expanding the TYPO3 Form Builder Concept<br />
I think the new Form/FormBuilder packages are an amazing addition to FLOW3. Here are some ideas to expand on that solid foundation.<br />
<br />
<br />
<h2>
<b>Point Number One: UI Theme-ing</b></h2>
<i>Phoenix needs a cool UI? No. Let's try again:<br />Phoenix needs a cool Theme-er (api and theme builder)</i><br />
<br />
Arguably, WordPress and Drupal are as popular as they are because of customize-able eye candy. From what I've read (I don't remember where), WP had an ugly default theme for a long time. They built a solid core and the design community took off making custom themes, because, of course people didn't want to stick with the default ugly theme. Drupal is also popular with themers. The way Drupal is designed, people had to theme much of the backend whenever they created a new template/theme for the frontend (though the distinction between front and back ends is much fuzzier in Drupal than in TYPO3). Themes gave people, and the organizations they served, a sense of pride and ownership. "I did that!"<br />
<br />
Perhaps you've used Trillian, the instant messenger? Several years ago, I was getting into theme-ing that beast because I wanted it to look different. An entire community of themers has grown up around Trillian, and a variety of other products. People love to style things their own way.<br />
<br />
I say, <i>make it theme-able and they will come</i>. I like that the user interface doesn't feel totally polished right now. I think that leads us down the same path that WP took. I think we should use everything Jens did to create a themeable foundation. We organize the system with links across the top, typically stylized as tabs. We have a page tree and various other UI concepts that can live in phoenix no matter what they look like. I would like to see something to help people generate themes for Phoenix; something that will make theme-ing fun and very approacheable; something that says "Phoenix helps you be yourself".<br />
<br />
It's interesting to note that the themeing capabilities of
TYPO3v4 never really took off. I'm guessing the system was too complex, and all of the extensions (TV comes to mind) took forever to support changes in just the default theme, let alone support any other themes. So, I think there needs to be some kind of <i>theme-ing api</i>. I'd imagine that extensions/plugins would register any new elements or icons through this api, and access the current theme's ui elements through the same. If a theme doesn't have something, then it falls back to the default or something like that.<br />
<br />
So I guess that's two components: a graphical Theme Builder and a sweet Theme API that all phoenix extensions/plugins use.<br />
<br />
<h2>
<b>Point Number Two: Phoenix Visual Framework and App UI Builder</b></h2>
<i>Phoenix will have a lot of pretty standard UI elements.</i><br />
<i><br /></i><br />
Perhaps we can call these elements a visual framework and make them easy to use.<br />
<br />
<ul>
<li>The page tree will be available in a lot of places.</li>
<li>The various Form elements will be ubiquitous (dropdowns, textareas, radio buttons, etc).</li>
<li>Handling system feedback like errors or "processing..." or whatever will be all over the place.</li>
<li>The various menus across the top or the context sensitive menus (like aloha's floating toolbar, or a right click menu)</li>
</ul>
When someone builds a new module/extension, in many cases they will need to create an interface to interact with it. The Form API and Form Builder look perfect for this, except that not everything is a form. Navigational things like the page tree or the menu of tabs across the top are not really form elements and I doubt we'd want to make the entire backend dependent on the Form API. I'm open to other thoughts on this, maybe we do want to build everything in the backend with the Form Builder, I don't know. I do, however, think that we need <i>something</i>; Something very much like the form builder that can create the fluid templates for use in Phoenix; Something that will help extension creators to use the theme api from the get-go; Something that will help to create a standard way to create user interface in Phoenix.<br />
<br />
<br />
In this UI Builder, devs should be able to quickly say, include the page tree, and a menu across the top, and a content-editable element in the main section to use Aloha during data input, and a Form, probably designed in the Form builder, to show up in this section over here. The UI Builder builds on the theme-ing api to encourage developers to use the standard Phoenix elements before creating their own. Of course, devs can always drop down and add stuff in fluid and handlebars, but if they 80/20 rule is true, then 80% of the time, the standard elements will do, so they shouldn't have to rebuild them all the time.<br />
<br />
I'd imagine that such an App UI Builder would be used to quickly put together functional mock-ups of the desired functionality before completing the data model and whatever controllers are needed.<br />
So, Phoenix needs a visual framework of standard elements, a UI Builder that makes it easy to use those elements.<br />
<br />
<h2>
<b>Point Number Three: Fluid Template Builder</b></h2>
<i>I think the Builder concept could also be applied to creating templates.</i><br />
<br />
Drupal and WP afficionados love creating themes and sharing them. There have been several different efforts to create the same share-ability with
TYPO3 v4's various templating systems, but none have attracted the attention needed to create a truely competitive library of templates that people can try and use as the basis for their own template. The social buzz generated by the "I made that" thought is really important to capture with this new version of
TYPO3 - our friend the Phoenix. I think that we could one-up the competition by extending the Form Builder concept, and the Application UI Builder concept mentioned above, and create a Fluid Template Builder to get people up and running as fast as possible.<br />
<br />
There are standard template elements like menus, videos, columns, etc. Each of these elements can be created in Fluid/TypoScript (a la the Form API/Builder) and then people can create basic Fluid templates with drag and drop. They say "I want a three column layout" and then they drag a menu into the left column and say that the middle column is editable content. It would only support a limited number of things, but it would let people get into the flow with fluid, even faster.<br />
<br />
On the other hand, this could also be something like the TV wizard where a designer or design team has created an html template that you must now 'fluidify'. They select the elements that need to be replaced, and either drag the standard fluid elements into replace them or they edit the fluid template in a kind of text box at the bottom of the page (think ide). It would also be nice to select, say, a menu that the designer created with ul and li tags. then a kind of modal wizard that runs through and helps to generate the fluid loops required to create the menu.<br />
<br />
<h2>
<b>Point Number Four: Third Party Visual Frameworks</b></h2>
The catalysts for all of these thoughts are: The sweet new TYPO3.FormBuilder and the LDS Church's IxF (Interaction Framework).<br />
<br />
I take a special interest in this organization because I'm a member of the Church of Jesus Christ of Latter-day Saints (members are also known as Mormons). The Church has a huge technology department of at least a couple thousand people. There are so many disparate development efforts (lots of web apps created mostly for internal use by other employees) that <a href="http://www.aaronbarker.net/" target="_blank">Aaron </a><a href="https://twitter.com/#!/zelph" target="_blank">Barker </a>(a UX designer who works for the Church) built an awesome Interaction Framework (IxF). I hope that final approvals will happen sometime soon so that the IxF can be used in things other than Church projects. For now, sadly, it's not publicly available, so I can't show it off to too many people.<br />
<br />
In the meantime, as Phoenix matures, I would love to see some of the Church's PHP projects use
FLOW3 on the backend, with IxF as the standard frontend. I think one way to encourage that would be to create the App UI Builder, as described above, that uses the IxF elements. That way devs can generate the already standardized UI even faster in a visual interface like (based on) the Form Builder. This way,
FLOW3 becomes an easy choice - build the forms with this nice visual tool, and naturally they'll end up using the amazing
FLOW3 framework.<br />
<br />
In the Form Builder, you have something like:<br />
Form > Page* [> Section]* > Element*<br />
<br />
That's somewhat analogous to the organization of IxF:<br />
Template > Layout* [> Section]* > Element*<br />
<br />
There are 4 basic templates (the IxF calls these Layouts as well, but they're more like super-layouts because they consist of the whole page, the stuff that goes around the internal layout).<br />
6 standard layouts (inner layouts that go inside an outer layout/template) accessible from the <a href="http://ixf.ldstech.cognifire.com/layout/index.html" style="color: #1155cc;" target="_blank">Layouts</a> section of the IxF docs.<br />
Several section elements that allow for organizing other elements (like tabs or accordians).<br />
And other standard widgets/elements are in the "<a href="http://ixf.ldstech.cognifire.com/demo/list.html#detail=intro" style="color: #1155cc;" target="_blank">Demos & Examples</a>" section of the IxF docs.<br />
Templates (accessible from the Interaction Framework menu in the upper left):<br />
<ul>
<li>The main IxF template demonstrated by the IxF docs (<a href="http://ixf.ldstech.cognifire.com/documentation/themeroller.html#color=%23161616" style="color: #1155cc;" target="_blank">with the outer border that you can change colors</a>).</li>
<li>IxF Sign In Page</li>
<li>IxF Alternate Layout - Fixed Small App (for simpler, or mobile apps)</li>
<li>IxF LDS.org (this one is important as most public facing apps have to use this template.)</li>
</ul>
Currently the extent of publicly available info about IxF resides on Twitter: <a href="http://twitter.com/ldsixf" rel="nofollow" target="_blank">@ldsixf</a><br />
<br />
<h2>
<b>Tying it all together</b></h2>
In the main IxF template, some of the elements in the top bar that are very similar to some of the Phoenix concepts. - messaging in the upper right, and app sections in tabs across the top.<br />
<br />
I would love to be able to have a theme that reused the IxF elements in Phoenix itself (Point Number 1 above). When it comes time to try and convince people to switch over to Phoenix, that would be a very sweet spot to say "and see, it even uses the IxF". The App Builder (Point Number Four, based on Point Number Two) would help with
FLOW3 adoption now, before Phoenix is ready. Point 3 is, well, just because I think that would be way cool for Phoenix to have that to try and expand
TYPO3's potential market.<br />
<br />
I'd imagine that other organizations would like to have their own theme used in Phoenix and other
FLOW3 based apps as well. I hope that this stuff can be generalized/abstracted enough to make it useful to more than just the Church. Maybe the themer would allow me to change the classes that are applied to different kinds of elements so that I can use standard stylesheets from whatever project I choose (not just twitter bootstrap, but the IxF or whatever else).<br />
<br />
The only hangup (admittedly a significant one) with using the IxF, is that we have to wait for IxF to be open sourced - which should happen afaik, I just don't know when. I really hope sooner than later.Anonymoushttp://www.blogger.com/profile/14944134144016532385noreply@blogger.com1